This object supports event notification from the filter graph and the filters within it to the application.
An event code and two parameters represent event notification information. This can be used 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.
Event notifications are placed in a queue. An application calls the IMediaEvent object's GetEvent method to retrieve the next notification from the queue. This method blocks until there is an event to return. The GetEvent method's time-out parameter allows the application to specify the time, in milliseconds, to wait for an event, including values of zero (do not wait) and infinite (wait forever).
In addition, applications can retrieve the event handle. GetEventHandle returns a handle to a manual-reset event created by the Microsoft® Win32® CreateEvent function. This event is in a signaled state as long as there are event notifications to collect. The event is cleared by the GetEvent method when there are no more event notifications to collect. This allows 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 handles some events raised by filters that are not passed to the application. One example of this is the EC_REPAINT event notification. The default handling for this event is to repaint the video renderer's static images by pausing the filter graph. An application can override default handling for a specific event by calling the CancelDefaultHandling method with the event value as a parameter. The RestoreDefaultHandling method 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, an error value is returned by the Run method. 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 Run method has returned, event notifications report any additional errors. The EC_ERRORABORT and EC_USERABORT event 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_COMPLETE event notification. The filter graph asks filters if they can report EC_COMPLETE via seekable renderers.
A seekable renderer is a renderer that supports the IMediaPosition object from the filter and has only input pins, or is a renderer whose input pins report that they are rendered at that point. The filter graph detects seekable renderers. A seekable renderer reports EC_COMPLETE once when all seekable streams on that filter have reached the end of the stream.
The filter graph manager will then not pass EC_COMPLETE to the application until an EC_COMPLETE event notification has been received from each stream. For example, if a live camera stream is playing as the background to a video playing out of a file, the application will be notified about EC_COMPLETE when the video and audio streams from the file have come to the end of the stream, 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 Pause or Stop method.
The aggregation of EC_COMPLETE messages can be disabled by calling CancelDefaultHandling with EC_COMPLETE as the parameter. In this case, all EC_COMPLETE events raised by the filters will be passed directly to the application.
For a list of system-defined event notifications, see the GetEvent method.
Methods
| Name | Description |
| CancelDefaultHandling | Cancels any default handling of the specified event by the filter graph. |
| GetEvent | Retrieves the next notification event. |
| GetEventHandle | Retrieves a handle to a manual-reset event that will be signaled. |
| RestoreDefaultHandling | Restores default handling for this event. |
| WaitForCompletion | Waits until the filter graph's operation has completed. |
Cancels default handling of the specified event by the filter graph and ensures that the event is passed to the application.
objMediaEvent.CancelDefaultHandling lEvCode
| EC_COMPLETE |
| EC_ERRORABORT |
| EC_PALETTE_CHANGED |
| EC_REPAINT |
| EC_USERABORT |
This method raises an error if the event does not have any default handling.
Currently the filter graph manager only applies default handling to EC_COMPLETE and EC_REPAINT.
Retrieves the next notification event.
objMediaEvent.GetEvent lEventCode, lParam1, lParam2, msTimeout
| EC_COMPLETE |
| EC_ERRORABORT |
| EC_PALETTE_CHANGED |
| EC_REPAINT |
| EC_USERABORT |
This method removes the next event notification from the head of the queue and returns it. It waits up to msTimeout milliseconds if there are no events.
Returns a handle to a manual-reset event that will be signaled as Long as there are event notifications to deliver.
objMediaEvent.GetEventHandle hEvent
The event can be passed to the Win32 WaitForMultipleObjects or MsgWaitForMultipleObjects function to wait for event notifications at the same time as other messages and events on a single thread.
Reinstates the normal default handling by a filter graph for the specified event if there is one.
objMediaEvent.RestoreDefaultHandling lEvCode
| EC_COMPLETE |
| EC_ERRORABORT |
| EC_PALETTE_CHANGED |
| EC_REPAINT |
| EC_USERABORT |
Events that have default handling in place, such as EC_REPAINT, are not typically passed to the application.
Waits until the filter graph's operation has completed.
objMediaEvent.WaitForCompletion msTimeout, EvCode
This method performs the equivalent of blocking by calling GetEvent repeatedly until the method receives the EC_COMPLETE, EC_ERRORABORT, or EC_USERABORT event notification, or until it reaches the time-out period, whichever comes first.
If the time-out value is reached, the method returns a completion code value of 0 and raises run-time error 287, "Application-defined or object-defined error." When setting the msTimeOut parameter to anything other than –1 (infinite), you are likely to get this run-time error. You can handle this error with an On Error Resume Next statement and then check the value of EvCode, which will be 0 if a time-out has occurred or 1 (EC_COMPLETE) or greater if completion has occurred. The following example illustrates using this method with a time-out of 0.
Dim pME As IMediaEvent
Dim EventCode As Long
Set pME = pMC
On Error Resume Next
pME.WaitForCompletion 0, EventCode 'Return from WaitForCompletion immediately
Set pME = Nothing
If EventCode = 0 Then Exit Sub
To use an infinite time-out, check for a returned event code of 1 as in the following example.
Dim pME As IMediaEvent
Dim EventCode As Long
Set pME = pMC
pME.WaitForCompletion -1, EventCode 'Wait until EC_COMPLETE
If EventCode = 1 Then Exit Sub
When the method returns, the filter graph is still in a running state. This method assumes that the application is not making separate calls to the IMediaEvent object. This method fails if the graph is not in or transitioning into a running state.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.