IMediaEvent Object

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

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.

CancelDefaultHandling Method (IMediaEvent Object)

IMediaEvent Object

Cancels default handling of the specified event by the filter graph and ensures that the event is passed to the application.

Syntax

objMediaEvent.CancelDefaultHandling lEvCode

Parts

objMediaEvent
Object expression that evaluates to an IMediaEvent object.
lEvCode
Long value specifying the event code which cancels default handling. The following values are valid.

Return Value

This method raises an error if the event does not have any default handling.

Remarks

Currently the filter graph manager only applies default handling to EC_COMPLETE and EC_REPAINT.

GetEvent Method (IMediaEvent Object)

IMediaEvent Object

Retrieves the next notification event.

Syntax

objMediaEvent.GetEvent lEventCode, lParam1, lParam2, msTimeout

Parts

objMediaEvent
Object expression that evaluates to an IMediaEvent object.
IEventCode
Returns the next event notification. The following values are valid.
lParam1
Long value specifying the first parameter of the event.
lParam2
Long value specifying the second parameter of the event.
msTimeout
Time, in milliseconds, to wait before assuming that there are no events. To return immediately, specify a time-out value of 0.

Remarks

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.

GetEventHandle Method (IMediaEvent Object)

IMediaEvent Object

Returns a handle to a manual-reset event that will be signaled as Long as there are event notifications to deliver.

Syntax

objMediaEvent.GetEventHandle hEvent

Parts

objMediaEvent
Object expression that evaluates to an IMediaEvent object.
hEvent
Long value that will contain the event handle.

Remarks

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.

RestoreDefaultHandling Method (IMediaEvent Object)

IMediaEvent Object

Reinstates the normal default handling by a filter graph for the specified event if there is one.

Syntax

objMediaEvent.RestoreDefaultHandling lEvCode

Parts

objMediaEvent
Object expression that evaluates to an IMediaEvent object.
lEvCode
Event to restore. The following list contains system-defined event notifications.

Remarks

Events that have default handling in place, such as EC_REPAINT, are not typically passed to the application.

WaitForCompletion Method (IMediaEvent Object)

IMediaEvent Object

Waits until the filter graph's operation has completed.

Syntax

objMediaEvent.WaitForCompletion msTimeout, EvCode

Parts

objMediaEvent
Object expression that evaluates to an IMediaEvent object.
msTimeout
Long value that specifies the duration of the time-out, in milliseconds. To block indefinitely, pass –1. To return immediately, pass zero.
EvCode
Long value that will contain the value of the event completion code, such as EC_COMPLETE. A value of zero indicates that the operation has not completed.

Remarks

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.

Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.