lookupEvent Member Function

An Event can 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 creates an Event object only when that object does not exist. If the object exists, the existing object is returned.

When you are using the Listener object or a Container object to create an Event, the event class must be specified by using the EventClass enumeration object, which includes the constants RPC and USER. When you are 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.

Attention: The application does not call delete on any objects that are returned by this function.

Syntax (Top-level)

Top-level Event objects exist directly under the Listener object (their Container object is null) and can be created by 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 by 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 by 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 you are creating a sub-Event because the event class of the sub-Event must be the same as the one employed by the parent Event object.
eventName: [in] Required pointer to a string, which provides the name of the Event object. The string consists of UTF-8 or Unicode characters, which can 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");
...