Retrieving Events

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

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 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;
LONG_PTR param1, param2;
HRESULT hr;
while (hr = pEvent->GetEvent(&evCode, &param1, &param2, 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.

Related topics

Event Notification in DirectShow