tibrvMsg_RemoveField()
Function
Declaration
tibrv_statustibrvMsg_RemoveField
(
tibrvMsg message,
const char* fieldName);
tibrv_statustibrvMsg_RemoveFieldEx
(
tibrvMsg message,
const char* fieldName,
tibrv_u16 fieldId);
Purpose
Remove a field from a message.
Remarks
Pointer data (such as strings, arrays, submessages, opaque byte sequences or XML data) previously extracted from the field remains valid even after removing the field from the message.
Parameter |
Description |
|
Remove the specified field from this message. |
|
Remove the field with this name. |
|
Remove the field with this identifier. Zero is a special value that signifies no field identifier. |
Field Search Algorithm
This function uses this algorithm to find and remove a field within a message, as specified by a field identifier and a field name.
Procedure
1. | The extended function begins here. The regular function begins at step 3. |
If the program supplied a non-zero field identifier, then search for the field with that identifier. If the search succeeds, remove the field.
On failure, continue to step 2. (If the identifier is zero, skip to step 3.)
2. | If the identifier search (in step 1) fails, and the program supplied a non-NULL field name, then search for a field with that name. |
If the program supplied NULL
as the field name, return the status code TIBRV_NOT_FOUND.
If the name search fails, return the status code TIBRV_NOT_FOUND.
If the name search succeeds, but the actual identifier in the field is non-NULL
(so it does not match the identifier supplied) then return the status code TIBRV_ID_CONFLICT.
If the search succeeds, remove the field.
3. | The regular function begins here. The extended function also begins here when the program supplied zero as the identifier (supplying zero is equivalent to not supplying a field identifier, so the behavior is equivalent to the regular function). |
Search for a field with the specified name—even if that name is NULL
.
If the search succeeds, remove the field.
If the search fails, return the status code TIBRV_NOT_FOUND.
If a message contains several fields with the same name, searching by name removes the first instance of the field with that name.