Retrieving Events
A version of this page is also available for
4/8/2010
The Filter Graph Manager exposes three interfaces that support event notification.
- IMediaEventSink contains the method for filters to post events.
- IMediaEvent contains methods for applications to retrieve events.
- IMediaEventEx inherits from and extends the IMediaEvent interface.
Filters post event notifications by calling the IMediaEventSink::Notify method on the Filter Graph Manager. An event notification consists of an event code, which defines the type of event, and two DWORD parameters that give additional information. Depending on the event code, the parameters might contain pointers, return codes, reference times, or other information. For a complete list of event codes and parameters, see Event Notification Codes.
To retrieve an event from the queue, the application calls the IMediaEvent::GetEvent method on the Filter Graph Manager. This method blocks until there is an event to return or until a specified time elapses. Assuming there is a queued event, the method returns with the event code and the two event parameters. After calling GetEvent, an application should always call the IMediaEvent::FreeEventParams method to release any resources associated with the event parameters. For example, a parameter might be a BSTR value that was allocated by the filter graph.
The following code example provides an outline of how to retrieve events from the queue.
long evCode, param1, param2;
HRESULT hr;
while (hr = pEvent->GetEvent(&evCode, ¶m1, ¶m2, 0), SUCCEEDED(hr))
{
switch(evCode)
{
// Call application-defined functions for each
// type of event that you want to handle.
}
hr = pEvent->FreeEventParams(evCode, param1, param2);
}
To override the Filter Graph Manager's default handling for an event, call the IMediaEvent::CancelDefaultHandling method with the event code as a parameter. You can reinstate the default handling by calling the IMediaEvent::RestoreDefaultHandling method. If the filter graph performs no default handling for the specified event code, calling these methods has no effect.
Note
If an application obtains an IMediaEvent interface pointer from the Filter Graph Manager, it must retrieve all events from the queue or they will accumulate and cause the heap to be used up. On the other hand, as long as the application has not obtained an IMediaEvent pointer, the filter graph does not queue any events. Therefore, you have the option of ignoring all events.