TibrvMsg::removeField()
Method
Declaration
TibrvStatusremoveField(
const char* fieldName,
tibrv_u16 fieldId=0);
Purpose
Remove a field from a message.
Remarks
Pointer data (such as strings, arrays, submessages, XML data, or opaque byte sequences) previously extracted from the field remains valid even after removing the field from the message.
|
Parameter |
Description |
|
|
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 method uses this algorithm to find and remove a field within a message, as specified by a field identifier and a field name.
Procedure
| 1. | If the identifier is zero, skip to 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.
| 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. | When the program supplied zero as the identifier, 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.