lookupEvent Member Function

An Event may be created at the top-level under the Listener object, as a subordinate of a Container object, or subordinate to another Event object (a sub-Event). In the first two cases, the programmer must specify the event class of the Event, while in the latter case, the class must be the same as the parent Event object's class.

This function will create an Event object only when that object does not already exist. If the object already exists, the existing object is returned.

When using the Listener object or a Container object to create an Event, the event class must be specified using the EventClass enumeration object, which includes the constants RPC and USER. When creating an Event subordinate to another Event (sub-Event), the event class is not specified because sub-Events must have the same class as their parent Event object.

CAUTION The application should not call delete on any objects returned by this function.

Syntax (Top-level)
Top-level Event objects exist directly under the Listener object (their Container object is null) and may be created using one of the following constructors:

Event *lookupEvent(EventClass eventClass, const char *eventName, [optional] bool includeParent);
Event *lookupEvent(EventClass eventClass, const wchar_t *eventName, [optional] bool includeParent);
Syntax (Subordinate to a Container)
Subordinate Event objects of a Container object must be created using one of the following constructors:
 
Event *lookupEvent(EventClass eventClass, const char *eventName, [optional] bool includeParent);
Event *lookupEvent(EventClass eventClass, const wchar_t *eventName, [optional] bool includeParent);
Syntax (sub-Event)
sub-Events (subordinate Event objects of another Event object) must be created using one of the following constructors:
 
Event *lookupEvent(const char *eventName, [optional] bool includeParent);
Event *lookupEvent(const wchar_t *eventName, [optional] bool includeParent);
Parameters
eventClass - [in] Required EventClass enumeration, that specifies the class of the event. The value of this parameter must be set to RPC or USER. This parameter is not specified when creating a sub-Event because the event class of the sub-Event must be the same as that employed by the parent Event object.
eventName - [in] Required pointer to a string, which provides the name of the Event object. The string should consist of UTF-8 or Unicode characters, which may contain any printable characters excluding the newline character.
includeParent - [in] Optional Boolean value (default is false), which indicates whether the recordEvent member function of the parent Event object should also be called, when the counter for the subordinate Event object is incremented.
Example
Listener *listener = new Listener("sampleApp", "4.0", NULL, false);
Event *creations = listener->lookupEvent(USER, "document creations");
   - or -
Event *creations = new Event(USER, "document creations");
Accumulator *numCreations = creations->numCreations("number of document creations");
...
delete creations;
creations = NULL;
   - or -
Listener *listener = new Listener("sampleApp", "4.0", NULL, false);
Container *store = listener->lookupContainer("storeName");
Event *creations = store->lookupEvent("document creations", false);
Event *subCreations = creations->lookupEvent("document sub-creations");
Meter *creationSize = creations->lookupMeter("creation size");
Accumulator *numCreations = creations->numCreations("number of document creations");
...
See Also
Container Class
Event Class
Listener Class
EventClass Enumeration