The AP_NormalisedEventIterator structure

Some of the functions above refer to a normalised event ‘iterator’. This object is for stepping through the contents of a normalised 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 normalised event iterator:

valid - Check whether the iterator points to a valid element of the normalised 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 normalised 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 normalised event and should not be modified or freed by the caller.

next - Move the iterator to the next element of the underlying normalised 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 normalised 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 normalised 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.

Please see the NormalisedEvent.h header file for more information about the structures and functions introduced in this section.