[This is preliminary documentation and subject to change.]
The stream compiler objects provide several ways to locate an event in the enhancement stream. You can locate the event most recently added to the stream or locate an event by its start time or handle.
To locate the most recently added event, call the EnhEvents.LastAdd method. This returns the event that was last added to the enhancement stream. The following example illustrates this where evs is an EnhEvents collection and e is an EnhEvent object variable.
Set e = evs.LastAdd
To locate an event by its start time, call the EnhEvents.FindTime method and specify the time of the event. The start time of an event is stored in the EnhEvent.Start property. The following example finds an event by its start time and stores the event in the object variable e.
'Find the event that starts at 00:05:42:00
Set e = evs.FindTime (342.0)
There are some considerations when finding an event by its start time. The start time of an event can change slightly as new events are added to the stream. This is because the stream compiler objects may have to rebudget the available bandwidth to fit the new events in. In addition, multiple events may have the same start time. If your application needs to be able to recall a specific event multiple times it is more robust to recall the event by its handle instead of its start time.
An event handle uniquely identifies the event within the stream. Unlike the start time, the handle of an event does not change. The event handle is stored in the EnhEvent.Handle property. To locate an event using its handle, call the EnhEvents.FindHandle method.
If you need to locate an event by some other criteria, such as locating an event by the value of its EnhEvent.Name property, you will have to implement a search through the stream explicitly. This is illustrated in the following example which searches the stream for an event by Name.
Dim FoundHandle As Long
'Search through the EnhEvents collection for the event
For Each e in evs
If (e.Name = FindStr) Then
'Insert code to utilize the found event.
'...
'Store a handle to the event for later recall. (optional)
FoundHandle = e.Handle
End If
Next e
Extending the preceding example, you could use the following to recall the event found previously and store it in the object variable e.
Set e = evs.FindHandle(FoundHandle)