The AP_NormalisedEventIterator structure
Some of the functions above refer to a normalized event ‘iterator'. This object is for stepping through the contents of a normalized event, in forwards or reverse order.
The AP_NormalisedEventIterator structure contains a function table defined by AP_NormalisedEventIterator_Functions, which includes all of the functions exported by a normalized event iterator:
valid - Check whether the iterator points to a valid element of the normalized event. Typically used as part of the loop condition when iterating over the contents of an event.
key - Return the key (name) associated with the current event element pointed to by the iterator. The returned value is owned by the underlying normalized event and should not be modified or freed by the caller.
value - Return the value associated with the current event element pointed to by the iterator. The returned value is owned by the underlying normalized event and should not be modified or freed by the caller.
next - Move the iterator to the next element of the underlying normalized event instance. The iterator must be in a valid state (such that the
valid function would return
AP_TRUE) before this function is called. Note that the order in which elements is returned is not necessarily the same as the order in which they were added. The order may change as elements are added to or removed from the underlying event.
back - Move the iterator to the previous element of the underlying normalized event instance. The iterator must be in a valid state (such that the
valid function would return
AP_TRUE) before this function is called. Note that the order in which elements is returned is not necessarily the same as the order in which they were added. The order may change as elements are added to or removed from the underlying event.
Note that all of these functions take an initial AP_NormalisedEventIterator* argument; this is analogous to the implicit ‘this' pointer passed to a C++ object when a member function is invoked on it.
AP_NormalisedEventIterator_dtor destroys a normalized event iterator object, and should be called when the iterator is no longer required to free up resources. There is no public constructor function; iterators are created and returned only by AP_NormalisedEvent functions.
See the NormalisedEvent.h header file for more information about the structures and functions introduced in this section.
