Functions | |
| int | cif_pktitr_close (cif_pktitr_tp *iterator) |
| Finalizes any changes applied via the specified iterator and releases any resources associated with it. The iterator ceases to be active. | |
| int | cif_pktitr_abort (cif_pktitr_tp *iterator) |
| If possible, reverts any changes applied via the provided iterator to its CIF, and, in all cases, releases any resources associated with the iterator itself. | |
| int | cif_pktitr_next_packet (cif_pktitr_tp *iterator, cif_packet_tp **packet) |
| Advances a packet iterator to the next packet, if any, and optionally returns the contents of that packet. | |
| int | cif_pktitr_update_packet (cif_pktitr_tp *iterator, cif_packet_tp *packet) |
| Updates the last packet iterated by the specified iterator with the values from the provided packet. | |
| int | cif_pktitr_remove_packet (cif_pktitr_tp *iterator) |
| Removes the last packet iterated by the specified iterator from its managed loop. | |
A packet iterator, obtained via cif_loop_get_packets(), represents the current state of a particular iteration of the packets of a particular loop (of a particular container). Based on that state, the user controls the progression of the iteration and optionally accesses the data and / or modifies the underlying loop.
The life cycle of an iterator contains several states:
cif_pktitr_close() or cif_pktitr_abort(), or it is moved to the ITERATED state (or, under special circumstances, directly to the FINISHED state; see below) via cif_pktitr_next_packet(); no other operations are valid for a packet iterator in this state. cif_pktitr_next_packet() (when that function returns CIF_OK), and leaves it via cif_pktitr_remove_packet() [to the REMOVED state] or via cif_pktitr_next_packet() [to the FINISHED state] when that function returns CIF_FINISHED. All packet iterator functions are valid for an iterator in this state; some leave it in this state. cif_pktitr_remove_packet(). From a forward-looking perspective, this state is nearly equivalent to the NEW state; the primary difference is that it is not extraordinary for an iterator to proceed directly from this state to the FINISHED state. cif_pktitr_next_packet() returns CIF_FINISHED to signal that no more packets are available. The only valid operations on such an iterator are to destroy it via cif_pktitr_close() or cif_pktitr_abort(), and one of those operations should be performed in a timely manner.The CIF data model does not accommodate loops without any packets, but the CIF API definition requires such loops to be accommodated in memory, at least transiently. It is for such packetless loops alone that a packet iterator can proceed directly from NEW to FINISHED.
Inasmuch as CIF loops are only incidentally ordered, the sequence in which loop packets are presented by an iterator is not defined by these specifications.
While iteration of a given loop is underway, it is implementation-defined what effect, if any, modifications to that loop other than by the iterator itself (including by a different iterator) have on the iteration results.
An open packet iterator potentially places both hard and soft constraints on use of the CIF with which it is associated. In particular, open iterators may interfere with other accesses to the same underlying data -- even for reading -- and it is undefined how closing or aborting an iterator affects other open iterators. When multiple iterators must be held open at the same time, it is safest (but not guaranteed safe) to close / abort them in reverse order of their creation. Additionally, and secondarily to the preceding, packet iterators should be closed or aborted as soon as they cease to be needed. More specific guidance may be associated with particular API implementations.
| int cif_pktitr_abort | ( | cif_pktitr_tp * | iterator | ) |
If possible, reverts any changes applied via the provided iterator to its CIF, and, in all cases, releases any resources associated with the iterator itself.
Whether changes can be reverted or rolled back depends on the library implementation.
| [in,out] | iterator | a pointer to the packet iterator object to abort; must be a non-NULL pointer to an active iterator |
CIF_OK on success, CIF_NOT_SUPPORTED if aborting is not supported, or an error code (typically CIF_ERROR ) in all other cases | int cif_pktitr_close | ( | cif_pktitr_tp * | iterator | ) |
Finalizes any changes applied via the specified iterator and releases any resources associated with it. The iterator ceases to be active.
Failure of this function means that changes applied by the iterator could not be made permanent; its resources are released regardless, and it ceases being active.
| [in,out] | iterator | a pointer to the iterator to close; must be a non-NULL pointer to an active iterator object |
CIF_OK on success or an error code (typically CIF_ERROR ) on failure | int cif_pktitr_next_packet | ( | cif_pktitr_tp * | iterator, | |
| cif_packet_tp ** | packet | |||
| ) |
Advances a packet iterator to the next packet, if any, and optionally returns the contents of that packet.
If packet is not NULL then the packet data are recorded where it points, either replacing the contents of a packet provided that way by the caller (when *packet is not NULL) or providing a new packet to the caller. "Replacing the contents" includes removing items that do not belong to the iterated loop. A new packet provided to the caller in this way (when packet is not NULL and *packet is NULL on call) becomes the responsibility of the caller; when no longer needed, its resources should be released via cif_packet_free().
If no more packets are available from the iterator's loop then CIF_FINISHED is returned.
| [in,out] | iterator | a pointer to the packet iterator from which the next packet is requested |
| [in,out] | packet | if non-NULL, the location where the contents of the next packet should be provided, either as the address of a new packet, or by replacing the contents of an existing one whose address is already recorded there. |
CIF_OK if the iterator successfully advanced, CIF_FINISHED if there were no more packets available. Returns an error code on failure (typically CIF_ERROR ), in which case the contents of any pre-existing packet provided to the function are undefined (but valid) | int cif_pktitr_remove_packet | ( | cif_pktitr_tp * | iterator | ) |
Removes the last packet iterated by the specified iterator from its managed loop.
It is an error to pass an iterator to this function for which cif_pktitr_next_packet() has not been called since it was obtained or since it was most recently passed to cif_pktitr_remove_packet().
| [in,out] | iterator | a pointer to the packet iterator object whose most recently provided packet is to be removed |
CIF_OK on success, or else an error code characterizing the nature of the failure, normally one of: CIF_MISUSE if the iterator has no current packet (because it has not yet provided one, or because the one most recently provided has been removed via this function CIF_ERROR in most other cases | int cif_pktitr_update_packet | ( | cif_pktitr_tp * | iterator, | |
| cif_packet_tp * | packet | |||
| ) |
Updates the last packet iterated by the specified iterator with the values from the provided packet.
It is an error to pass an iterator to this function for which cif_pktitr_next_packet() has not been called since it was obtained or since it was most recently passed to cif_pktitr_remove_packet(), or to pass one for which cif_pktitr_next_packet() has returned CIF_FINISHED. Items in the iterator's target loop for which the packet does not provide a value are left unchanged. It is an error for the provided packet to provide a value for an item not included in the iterator's loop.
| [in] | iterator | a pointer to the packet iterator defining the loop and packet to update; must be a non-NULL pointer to an active packet iterator |
| [in] | packet | a pointer to a packet object defining the updates to apply; must not be NULL |
CIF_OK on success, or else an error code characterizing the nature of the failure, normally one of: CIF_MISUSE if the iterator has no current packet (because it has not yet provided one, or because the one most recently provided has been removed CIF_WRONG_LOOP if the packet provides an item that does not belong to the iterator's loop CIF_ERROR in most other cases Copyright 2014, 2015 John C. Bollinger