[DirectShow] 018 - Retrieving Events

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.

Filter Graph Manager 暴露三个接口支持事件通知：

·         IMediaEventSink 包含 filter 发送事件的方法。

·         IMediaEvent 包含应用程序提取事件的方法。

·         IMediaEventEx 从 IMediaEvent 接口继承并扩展了 IMediaEvent 接口。

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 .

Filter 通过在 Filter Graph Manager 上调用 IMediaEventSink::Notify 发送通知事件。通知事件由一个通知码和两个 DWORD 参数组成，通知码定义事件的类型，参数给定一些附加信息。通知码决定了参数可能包含指针，返回码引用时间或者其他的信息。

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.

应用程序通过在 Filter Graph Manager 上调用 IMediaEvent::GetEvent 方法从队列中提起事件。这个方法阻塞直到有事件返回或者超时。如果提取到一个队列的消息， GetEvent 返回一个事件码和两个事件参数。在调用 GetEvent 之后，应用程序还要调用 IMediaEvent::FreeEventParams 释放事件参数有关的资源。例如，参数可能是一个由 filter graph 分配的 BSTR 。

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, &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.

要让 Filter Graph Manager 忽略某个事件，可以调用 IMediaEvent::CancelDefaultHanding 方法，参数是事件码。如果 filter graph 对于指定的事件码没有默认处理执行，那么调用这个函数没有效果。