|This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.|
This interface supports event notification from the filter graph and filters within it to the application. It is decoupled by using a queuing scheme rather than callbacks, because events can be notified from worker threads that cannot safely call back into application code.
An event code and two DWORDvalues represent event notification information. Your application can use this for typical completion of asynchronous operations, errors that occur during asynchronous operation, or user-initiated events, such as when a user clicks a hot spot.
Filters within the filter graph and the filter graph itself raise event notifications. Possible events include playback completion or asynchronous playback errors. In addition, the filter graph provides a method to generate events at specific reference clock times. The filter graph exposes an IMediaEventSinkinterface that the filters within the graph can call to pass event notifications to the application.
Event notifications are placed in a queue. An application calls the IMediaEvent::GetEventmethod to retrieve the next notification from the queue. This method blocks until there is an event to return. The GetEventtime-out parameter ( msTimeout) allows the application to specify the time, in milliseconds, to wait for an event, including values of zero and INFINITE. After calling GetEvent, applications should always call FreeEventParamsto release any resource associated with the event.
In addition, applications can retrieve the event handle. IMediaEvent::GetEventHandlereturns a handle to a manual-reset event created by the Microsoft® Win32® CreateEventfunction. This event is in a signaled state as long as there are event notifications to collect. The IMediaEvent::GetEventmethod clears the event when there are no more event notifications to collect. This enables an application to use an application programming interface (API), such as MsgWaitForMultipleObjects, to wait for events and other occurrences at the same time. This event handle will be closed when the filter graph is released; therefore, applications should ensure that they are not using it after this point.
The filter graph manager handles some events raised by filters that are not passed to the application. One example of this is the EC_REPAINTevent notification. By default the filter graph manager handles this event by pausing the filter graph and repainting the video renderer's static images. An application can override default handling for a specific event by calling the IMediaEvent::CancelDefaultHandlingmethod with the event value as a parameter. The IMediaEvent::RestoreDefaultHandlingmethod reinstates default handling for the specified event value. These methods have no effect on events that have no default handling.
If an error occurs during the transition to a running state on any filter, the IMediaControl::Runmethod returns an error value. In this case, some filters within the graph might be running successfully. The filter graph leaves it up to the application to determine whether to stop the graph in case of an error. After the IMediaControl::Runmethod has returned, event notifications report any additional errors. The EC_ERRORABORTand EC_USERABORTevent notifications indicate that playback has probably stopped in the graph (certainly in the filter that reported it). Other errors and events indicate that it is still running. Note, however, that in all cases the graph remains in running mode until the application explicitly changes it to stopped or paused mode.
If the streams in the filter graph detect the end of the stream, the streams report this by using the EC_COMPLETEevent notification. The filter graph manager asks filters if they can report EC_COMPLETE by means of seekable renderers.
A seekable renderer is one that supports the IMediaPositioninterface from the filter and that has only input pins, or whose input pins report through IPin::QueryInternalConnectionsthat they are rendered. The filter graph uses IPin::QueryInternalConnectionsand IMediaPositionto detect seekable renderers. A seekable renderer should report EC_COMPLETEwhen all seekable streams on that filter have reached the stream's end.
- The typical case: Whether there is data arriving or not, if it
succeeds all calls to
will eventually get
If the end of the media is reached and when all data and
EndOfStreamhas been processed it will signal
- The filter can never produce any data. In that case it just
EC_COMPLETEimmediately when a Run method is called. For
example, a filter would pass
EC_COMPLETEif none if its input pins is connected.
- The complicated case, sometimes used by the wave renderer: It
cannot render data right now even though it is getting it but it
might be able to later. In that case, it fails the first
EC_COMPLETEfor a time
tStartin the future (based on the
NewSegmentparameters). If it finds it can start sending data it
EC_NEED_RESTART. A better approach could be to use stream
control for this to avoid stopping and starting the graph.
- It detects an unrecoverable error. Then, like any filter, it
signals end of stream which for a renderer means signaling
The filter graph manager will not pass EC_COMPLETEto the application until an EC_COMPLETEevent notification has been received from each stream. For example, if a live camera stream is playing as the background for a video playing from a file, the application will be notified about EC_COMPLETEwhen the video and audio streams from the file have come to the stream's end, even though the live source is still playing. In this case, too, the filter graph remains in running mode until the application explicitly calls the IMediaControl::Pauseor IMediaControl::Stopmethod.
Your application can disable the aggregation of EC_COMPLETEmessages by calling IMediaEvent::CancelDefaultHandlingwith EC_COMPLETEas the parameter. In this case, all EC_COMPLETEevents raised by the filters will be passed directly to the application.
For a list of system-defined event notifications, see Event Notification Codes.
|All events must be handled if a handle to an IMediaEventinterface is obtained otherwise events will pile up and cause the heap to be used up.|
When to Implement
The filter graph manager implements this interface.
When to Use
Applications use this interface to retrieve event notifications or event handles from the filter graph manager. For example, an application can retrieve the EC_COMPLETEnotification to find out when a media stream has been rendered completely.
Methods in Vtable Order
The following tables show the methods that appear in the Vtable beneath the standard COM methods inherited from IUnknown.
Determines whether there is type information available for this dispinterface.
Retrieves the type information for this dispinterface if GetTypeInfoCountreturned successfully.
Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
Retrieves a handle to a manual-reset event that will be signaled.
Retrieves the next notification event.
Blocks execution of the application thread until the graph's operation finishes.
Cancels any default handling of the specified event by the filter graph.
Restores default handling for this event.
Frees resources associated with the parameters to an event.
|Windows Embedded CE||Windows CE 2.12 and later|
|Windows Mobile||Windows Mobile Version 5.0 and later|
|Note||Microsoft DirectShow applications and DirectShow filters have
different include file and Library requirements
For more information, see Setting Up the Build Environment