Functions | |
| int | cif_packet_create (cif_packet_tp **packet, UChar *names[]) |
| Creates a new packet for the given item names. | |
| int | cif_packet_get_names (cif_packet_tp *packet, const UChar ***names) |
| Retrieves the names of all the items in the current packet. | |
| int | cif_packet_set_item (cif_packet_tp *packet, const UChar *name, cif_value_tp *value) |
| Sets the value of the specified CIF item in the specified packet, including if the packet did not previously provide any value for the specified data name. | |
| int | cif_packet_get_item (cif_packet_tp *packet, const UChar *name, cif_value_tp **value) |
| Determines whether a packet contains a value for a specified data name, and optionally provides that value. | |
| int | cif_packet_remove_item (cif_packet_tp *packet, const UChar *name, cif_value_tp **value) |
| Removes the value, if any, associated with the specified name in the specified packet, optionally returning it to the caller. | |
| void | cif_packet_free (cif_packet_tp *packet) |
| Releases the specified packet and all resources associated with it, including those associated with any values within. | |
| int cif_packet_create | ( | cif_packet_tp ** | packet, | |
| UChar * | names[] | |||
| ) |
Creates a new packet for the given item names.
The resulting packet does not retain any references to the item name strings provided by the caller. It will contain for each data name a value object representing the explicit "unknown" value. The caller is responsible for freeing the packet via cif_packet_free() when it is no longer needed.
| [in,out] | packet | the location were the address of the new packet should be recorded. Must not be NULL. The value initially at *packet is ignored. |
| [in] | names | a pointer to a NULL-terminated array of Unicode string pointers, each element containing one data name to be represented in the new packet; may contain zero names. The responsibility for these resources is not transferred. May be NULL, which is equivalent to containing zero names. |
CIF_OK on success, or else an error code characterizing the nature of the failure, normally one of: CIF_INVALID_ITEMNAME if one of the provided strings is not a valid CIF data name CIF_ERROR in most other cases | void cif_packet_free | ( | cif_packet_tp * | packet | ) |
Releases the specified packet and all resources associated with it, including those associated with any values within.
This function is a safe no-op when the argument is NULL.
| [in] | packet | a pointer to the packet to free |
| int cif_packet_get_item | ( | cif_packet_tp * | packet, | |
| const UChar * | name, | |||
| cif_value_tp ** | value | |||
| ) |
Determines whether a packet contains a value for a specified data name, and optionally provides that value.
The value, if any, is returned via parameter value, provided that that parameter is not NULL. In contrast to cif_packet_set_item(), the value is not copied out; rather a pointer to the packet's own internal object is provided. Therefore, callers must not free the value object themselves, but they may freely modify it, and such modifications will subsequently be visible via the packet.
| [in] | packet | a pointer to the packet object from which to retrieve a value |
| [in] | name | the data name requested from the packet |
| [in,out] | value | if not NULL, gives the location where a pointer to the requested value should be written. |
CIF_OK if the packet contains an item having the specified data name, or CIF_NOSUCH_ITEM otherwise. | int cif_packet_get_names | ( | cif_packet_tp * | packet, | |
| const UChar *** | names | |||
| ) |
Retrieves the names of all the items in the current packet.
It is the caller's responsibility to release the resulting array, but its elements MUST NOT be modified or freed. Names are initially in the order in which they appear in the array passed to cif_packate_create(). If a new item is added via cif_packet_set_item() then its name is appended to the packet's name list.
| [in] | packet | a pointer to the packet whose data names are requested |
| [in,out] | names | the location where a pointer to the array of names should be written. The array will be NULL-terminated. |
CIF_OK on success, or an error code (typically CIF_ERROR ) on failure | int cif_packet_remove_item | ( | cif_packet_tp * | packet, | |
| const UChar * | name, | |||
| cif_value_tp ** | value | |||
| ) |
Removes the value, if any, associated with the specified name in the specified packet, optionally returning it to the caller.
The value object is returned via the value parameter if that is not NULL, in which case the caller assumes responsibility for the value. Otherwise the removed value and all resources belonging to it are released.
| [in,out] | packet | a pointer to the packet from which to remove an item. |
| [in] | name | the name of the item to remove, as a NUL-terminated Unicode string. |
| [in,out] | value | if not NULL, the location where a pointer to the removed item should be written |
CIF_OK if the packet initially contained an item having the given name, or CIF_NOSUCH_ITEM otherwise; the case where the given name is not a valid CIF item name is not distinguished as a separate case. | int cif_packet_set_item | ( | cif_packet_tp * | packet, | |
| const UChar * | name, | |||
| cif_value_tp * | value | |||
| ) |
Sets the value of the specified CIF item in the specified packet, including if the packet did not previously provide any value for the specified data name.
The provided value object is copied into the packet; the packet does not assume responsibility for either the specified value object or the specified name. If the value handle is NULL then an explicit unknown-value object is recorded. The copied (or created) value can subsequently be obtained via cif_packet_get_item().
When the specified name matches an item already present in the packet, the existing value is first cleaned as if by cif_value_clean(), then the new value is copied onto it. That will be visible to code that holds a reference to the value (obtained via cif_packet_get_item()). Exception: if value is the same object as the current internal one for the given name then this function succeeds without changing anything.
| [in,out] | packet | a pointer to the packet to modify |
| [in] | name | the name of the item within the packet to modify, as a NUL-terminated Unicode string; must be non-null and valid for a CIF data name |
| [in] | value | the value object to copy into the packet, or NULL for an unknown-value value object to be added |
CIF_OK on success, or else an error code characterizing the nature of the failure, normally one of: CIF_INVALID_ITEMNAME if name is not a valid CIF data name CIF_ERROR in most other cases Copyright 2014, 2015 John C. Bollinger