The AP_NormalisedEvent structure
The AP_NormalisedEvent structure has a pointer to a table of client-visible functions exported by the object called AP_NormalisedEvent_Functions. This function table provides access to the operations that may be performed on the event object:
size - Return the number of elements (name-value pairs) currently stored by the event.
empty - Check whether the event is empty or not.
add - Add a new name-value pair to the event. The given name and value will be copied into the event. If an element with the same name already exists, it will not be overwritten. This returns an iterator into the events at the point where the new element was added.
addQuick - Add a new name-value pair to the event. The given name and value will be copied into the event. If an element with the same name already exists, it will not be overwritten.
remove - Remove the named element from the normalized event.
removeAll - Remove all elements from the normalized event. The
empty function will return
AP_TRUE after this function has been called.
replace - Change the value of a named element in the normalized event. If an element with the given name already exists, its value will be replaced with a copy of the given value. Otherwise, a new element is created just as though
addQuick had been called.
exists - Check whether a given element exists in the normalized event.
find - Search for a named element in the normalized event. Returns an iterator into the event at the point where the element was located.
findValue - Search for a named element in the normalized event and return its value.
findValueAndRemove - Search for a named element in the normalized event and return its value. If found, the element will also be removed from the event.
findValueAndRemove2 - Search for a named element in the normalized event and return its value. If found, the element will also be removed from the event. Unlike
findValueAndRemove it tells you whether it was able to remove the value, or whether it did not exist.
first - Return an iterator pointing to the first element of the normalized event. Successive calls to the
next function of the returned iterator will allow you to visit all the elements of the event.
last - Return an iterator pointing to the last element of the normalized event. Successive calls to the
back function of the returned iterator will allow you to visit all the elements of the event.
toString - Return a printable string representation of the normalized event. The returned string is owned by the caller and should be freed when it is no longer required.
char8free – Free a string returned by the
toString function; should be called when the string is no longer required.
All of these functions take an initial AP_NormalisedEvent* argument; this is analogous to the implicit ‘this’ pointer passed to a C++ object when a member function is invoked on it.
In addition, the AP_NormalisedEvent_ctor constructor function is provided to create a new event instance. AP_NormalisedEvent_dtor destroys a normalized event object, and should be when the event is no longer required to free up resources.
The reader is invited to examine the header file for the full definitions of all these functions.