Functions | |
| void | cif_loop_free (cif_loop_tp *loop) |
| Releases any resources associated with the given loop handle without modifying the managed CIF with which it is associated. | |
| int | cif_loop_destroy (cif_loop_tp *loop) |
| Releases any resources associated with the given loop handle, and furthermore removes the entire associated loop from its managed CIF, including all items and values belonging to it. | |
| int | cif_loop_get_category (cif_loop_tp *loop, UChar **category) |
| Retrieves the specified loop's category. | |
| int | cif_loop_set_category (cif_loop_tp *loop, const UChar *category) |
| Sets the specified loop's category. | |
| int | cif_loop_get_names (cif_loop_tp *loop, UChar ***item_names) |
| Retrieves the item names belonging to the specified loop. | |
| int | cif_loop_add_item (cif_loop_tp *loop, const UChar *item_name, cif_value_tp *val) |
| Adds the CIF data item identified by the specified name to the specified managed loop, with the given initial value in every existing loop packet. | |
| int | cif_loop_add_packet (cif_loop_tp *loop, cif_packet_tp *packet) |
| Adds a packet to the specified loop. | |
| int | cif_loop_get_packets (cif_loop_tp *loop, cif_pktitr_tp **iterator) |
| Creates an iterator over the packets in the specified loop. | |
| int cif_loop_add_item | ( | cif_loop_tp * | loop, | |
| const UChar * | item_name, | |||
| cif_value_tp * | val | |||
| ) |
Adds the CIF data item identified by the specified name to the specified managed loop, with the given initial value in every existing loop packet.
The caller retains ownership of all arguments.
Note that there is an asymmetry here, in that items are added to specific loops, but removed from overall containers (data blocks and save frames). This reflects the CIF architectural asymmetry that item names must be unique within their entire container, yet within it they each belong exclusively to a specific loop.
| [in] | loop | a handle on the loop to which the item should be added |
| [in] | item_name | the name of the item to add as a NUL-terminated Unicode string; must be non-NULL and a valid CIF item name |
| [in] | val | a pointer to the value object that serves as the the initial value for the item, or NULL to use a CIF unknown value |
CIF_OK on success or a characteristic error code on failure, normally one of: CIF_INVALID_ITEMNAME if the item name is not valid CIF_DUP_ITEMNAME if the specified item name is already present in the loop's container CIF_ERROR in most other cases | int cif_loop_add_packet | ( | cif_loop_tp * | loop, | |
| cif_packet_tp * | packet | |||
| ) |
Adds a packet to the specified loop.
The packet object is not required to provide data for all items in the loop (items without specified values get the explicit unknown value), but it must specify at least one value, and it must not provide data for any items not in the loop. The caller retains ownership of the packet abd its contents.
| [in] | loop | a handle on the loop to which to add a packet; mist be non-NULL and valid |
| [in] | packet | a pointer to the packet object specifying the values for the new packet; must be non-NULL, specifying at least one item value, and not specifying any that do not belong to the designated loop |
CIF_OK on success, or a characteristic error code on failure, normally one of: CIF_INVALID_PACKET if the packet contains no items CIF_WRONG_LOOP if the packet specifies any items that do not belong to the target loop CIF_ERROR in most other cases | int cif_loop_destroy | ( | cif_loop_tp * | loop | ) |
Releases any resources associated with the given loop handle, and furthermore removes the entire associated loop from its managed CIF, including all items and values belonging to it.
Provided that they are initially valid, the loop handle and any outstanding iterators over its contents are invalidated by successful execution of this function.
On failure, the loop handle is not freed, so that the caller can interrogate it for error reporting purposes. The caller remains responsible to release it, possibly via cif_loop_free().
| [in,out] | loop | a handle on the loop to destroy |
CIF_OK on success or an error code (typically CIF_ERROR ) on failure. | void cif_loop_free | ( | cif_loop_tp * | loop | ) |
Releases any resources associated with the given loop handle without modifying the managed CIF with which it is associated.
| [in] | loop | the loop handle to free; must be non-NULL and valid |
| int cif_loop_get_category | ( | cif_loop_tp * | loop, | |
| UChar ** | category | |||
| ) |
Retrieves the specified loop's category.
Responsibility for cleaning up the category string belongs to the caller. Note that loops are not required to have categories assigned, therefore the category returned may be a NULL pointer.
| [in] | loop | a handle on the loop whose item names are requested |
| [in,out] | category | a pointer to the location where a pointer to a NUL-terminated Unicode string containing the requested category (or NULL) should be recorded; must not be NULL |
CIF_OK on success, or an error code (typically CIF_ERROR ) on failure | int cif_loop_get_names | ( | cif_loop_tp * | loop, | |
| UChar *** | item_names | |||
| ) |
Retrieves the item names belonging to the specified loop.
The resulting name list takes the form of a NULL-terminated array of NUL-terminated Unicode strings. The caller assumes responsibility for freeing the individual names and the array containing them.
| [in] | loop | a handle on the loop whose item names are requested |
| [in,out] | item_names | the location where a pointer to the resulting NULL-terminated item name array should be written; must not be NULL |
CIF_OK on success or an error code (typically CIF_ERROR ) on failure. | int cif_loop_get_packets | ( | cif_loop_tp * | loop, | |
| cif_pktitr_tp ** | iterator | |||
| ) |
Creates an iterator over the packets in the specified loop.
After successful return and before the iterator is closed or aborted, behavior is undefined if the underlying loop is accessed (even just for reading) other than via the iterator. Furthermore, other modifications to the same managed CIF made while an iterator is active may be sensitive to the iterator, in that it is undefined whether they will be retained if the iterator is aborted or closed unsuccessfully. As a result of these constraints, users are advised to maintain as few active iterators as feasible for any given CIF, to minimize non-iterator operations performed while any iterator is active on the same target CIF, and to close or abort iterators as soon as possible after they cease to be required.
| [in] | loop | a handle on the loop whose packets are requested; must be non-NULL and valid |
| [in,out] | iterator | the location where a pointer to the iterator object should be written; must not be NULL |
CIF_OK on success or an error code on failure, normally one of: CIF_INVALID_HANDLE if the loop handle represents a loop that does not (any longer) exist; CIF_EMPTY_LOOP if the target loop contains no packets; or CIF_ERROR in most other cases | int cif_loop_set_category | ( | cif_loop_tp * | loop, | |
| const UChar * | category | |||
| ) |
Sets the specified loop's category.
The zero-character string (as distinguished from NULL) is RESERVED as a loop category. No loop's category may be set to a zero-character string (unless that's what it already is), nor may a loop's category be changed if it is the zero-character string.
| [in,out] | loop | a handle on the loop whose category is to be set |
| [in] | category | the category string to set as a NUL-terminated Unicode string; does not need to be unique and may be NULL, but must not be a zero-length string. Ownership of this string is not transferred by passing it to this function. |
CIF_OK on success, or an error code on failure, typically either CIF_RESERVED_LOOP or CIF_ERROR Copyright 2014, 2015 John C. Bollinger