IMediaEvent Interface

The IMediaEvent interface supports event notification from the filter graph, and from filters within the filter graph, to the application. Event notification 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.

Event notifications consist of an event code and two DWORD parameters. The parameters may contain pointers, HRESULTs, or other information about the event. Your application can use this information to handle typical completion of asynchronous operations, deal with errors that occur during asynchronous operation, or respond to user-initiated events such as the user clicking a hot spot.

The filter graph exposes an IMediaEventSink interface, which the filters within the graph call to pass event notifications to the application. Both the 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. The application calls the IMediaEvent::GetEvent method to retrieve the next notification from the queue. This method blocks until there is an event to return. The GetEvent time-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 FreeEventParams to release any resource associated with the event.

In addition, applications can retrieve the event handle. IMediaEvent::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 queued. The GetEvent method clears the event when there are no more event notifications to collect. This way of handling events enables an application to use an application programming interface (API) such as MsgWaitForMultipleObjects to wait for events and other occurrences at the same time. The event handle will be closed when the filter graph is released; therefore, applications should ensure that they are not using it after this point.

Default Event Handling

With some events raised by filters, the filter graph manager handles the event rather than passing it to the application. For example, by default the filter graph manager handles EC_REPAINT event notifications 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::CancelDefaultHandling method with the event code as a parameter. The IMediaEvent::RestoreDefaultHandling method reinstates default handling for the specified event code. These methods have no effect on events that have no default handling.

Running the Filter Graph

The IMediaControl::Run method switches the entire filter graph to a running state. If an error occurs during the transition to a running state on any filter, the method returns an error value. In this case, some filters within the graph might be running successfully, and the filter graph leaves it up to the application to determine whether to stop the graph. After the Run method has returned, event notifications report any additional errors. An EC_ERRORABORT or EC_USERABORT event notification indicates that playback has stopped in the filter that reported it, and probably in the entire graph. Other errors and events indicate that it is still running. Note that in all cases the graph remains in running mode until the application explicitly changes it to stopped or paused mode.

End of Stream Detection

If the renderers in the filter graph detect the end of the stream, the streams report this by using the EC_COMPLETE event notification. The filter graph manager asks filters if they can report EC_COMPLETE through seekable renderers.

A seekable renderer is one that supports the IMediaPosition interface from the filter and has only input pins, or one whose input pins report through the IPin::QueryInternalConnections method that they are rendered. The filter graph uses QueryInternalConnections and IMediaPosition to detect seekable renderers. A seekable renderer should report EC_COMPLETE when all seekable streams on that filter have reached the stream's end.

There are four situations in which a rendering filter can produce EC_COMPLETE (or a regular filter produce EndOfStream):

The typical case: Whether data is arriving or not, if the renderer succeeds all calls to the Receive function it will eventually get EndOfStream.If the end of the media is reached, and when all data and EndOfStream have been processed, the renderer will signal EC_COMPLETE.
The filter can never produce any data. In this case it just passes EC_COMPLETE immediately when a Run method is called. For example, a filter would pass EC_COMPLETE if none of its input pins were connected.
The filter is getting data that it cannot render right now, but which it might be able to render later. (This situation might occur with the wave renderer, for example.) In this case, the filter fails the first call to Receive and schedules an EC_COMPLETE for a time tStop minus tStart in the future (based on the parameters passed to the IPin::NewSegment method). If it later finds that it can start sending data, it signals an EC_NEED_RESTART event. A better approach in this situation might be to use stream control, to avoid stopping and starting the graph.
It detects an unrecoverable error. Like any filter, it signals end of stream which for a renderer means signaling EC_COMPLETE.

The filter graph manager will not pass EC_COMPLETE to the application until the filter graph manager receives an event notification 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_COMPLETE when 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::Pause or IMediaControl::Stop method.

Your application can disable the aggregation of EC_COMPLETE messages by calling IMediaEvent::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 Event Notification Codes.

Note If an application obtains a handle to an IMediaEvent interface, it must handle all events, or they will pile up and cause the heap to be used up.

The filter graph manager implements this interface.

You can use the CMediaEvent class, which handles the IDispatch implementation for Automation, to help implement this interface.

Applications use this interface to retrieve event notifications or event handles from the filter graph manager. For example, an application can retrieve the EC_COMPLETE notification to find out when a media stream has been rendered completely.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IDispatch methods Description
GetTypeInfoCount Determines whether there is type information available for this dispinterface.
GetTypeInfo Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.

IMediaEvent methods Description
GetEventHandle Retrieves a handle to a manual-reset event that will be signaled.
GetEvent Retrieves the next notification event.
WaitForCompletion Blocks execution of the application thread until the graph's operation finishes.
CancelDefaultHandling Cancels any default handling of the specified event by the filter graph.
RestoreDefaultHandling Restores default handling for this event.
FreeEventParams Frees resources associated with the parameters of an event.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IDispatch methods	Description
GetTypeInfoCount	Determines whether there is type information available for this dispinterface.
GetTypeInfo	Retrieves the type information for this dispinterface if GetTypeInfoCount returned successfully.
GetIDsOfNames	Converts text names of properties and methods (including arguments) to their corresponding DISPIDs.
Invoke	Calls a method or accesses a property in this dispinterface if given a DISPID and any other necessary parameters.
IMediaEvent methods	Description
GetEventHandle	Retrieves a handle to a manual-reset event that will be signaled.
GetEvent	Retrieves the next notification event.
WaitForCompletion	Blocks execution of the application thread until the graph's operation finishes.
CancelDefaultHandling	Cancels any default handling of the specified event by the filter graph.
RestoreDefaultHandling	Restores default handling for this event.
FreeEventParams	Frees resources associated with the parameters of an event.

IMediaEvent::CancelDefaultHandling

IMediaEvent Interface

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

Syntax

HRESULT CancelDefaultHandling(
    long lEvCode
);

Parameters

lEvCode
Event code for which to cancel default handling.

Return Value

Returns S_OK if successful, or S_FALSE if the event does not have any default handling.

Remarks

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

IMediaEvent::FreeEventParams

IMediaEvent Interface

Frees resources associated with the parameters of an event.

Syntax

HRESULT FreeEventParams(
    long lEventCode,
    long lParam1,
    long lParam2
);

Parameters

lEventCode
[in] Next event notification.
lParam1
[in] First parameter of the event.
lParam2
[in] Second parameter of the event.

Return Value

Returns an HRESULT value.

Remarks

Event parameters can be of type LONG or BSTR. If a BSTR is passed as an event, it will have been allocated by the task allocator and should be freed using this method. No reference-counted interfaces are passed to an application using IMediaEvent::GetEvent, because these cannot be overridden by IMediaEvent::CancelDefaultHandling. Therefore, do not use this method to release interfaces.

IMediaEvent::GetEvent

IMediaEvent Interface

Retrieves the next notification event.

Syntax

HRESULT GetEvent(
    long *lEventCode,
    long *lParam1,
    long *lParam2,
    long msTimeout
);

Parameters

IEventCode
[out] Pointer to the next event notification.
lParam1
[out] Pointer to the first parameter of the event.
lParam2
[out] Pointer to the second parameter of the event.
msTimeout
[in] Time, in milliseconds, to wait before assuming that there are no events.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. If the time-out is zero and no event is waiting, or if the time-out elapses before an event appears, this method returns E_ABORT.

Remarks

The application can pass a time-out value of INFINITE to indicate that the method should block until there is an event; however, applications should avoid using INFINITE. Threads cannot process any messages while waiting in GetEvent. If you call GetEvent from the thread that processes Windows messages, specify only small wait times on the call in order to remain responsive to user input. This is most important when streaming data from a source such as the Internet, because state transitions can take significantly more time to complete.
After calling GetEvent, applications should always call FreeEventParams to release any resource associated with the event.
For a list of notification codes and event parameter values, see Event Notification Codes.

IMediaEvent::GetEventHandle

IMediaEvent Interface

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

Syntax

HRESULT GetEventHandle(
    OAEVENT *hEvent
);

Parameters

hEvent
[out] Pointer to the handle for the event.

Return Value

Returns an HRESULT value.

Remarks

You can monitor events (including the retrieved event) and messages on a single thread; to do this, declare a HANDLE variable, cast it to an OAEVENT pointer, then pass it to GetEventHandle. You must cast the pointer to an OAEVENT pointer because HANDLE is not a valid Automation type. The following code fragment demonstrates how to cast and use the HANDLE.
HANDLE hEvent;
GetEventHandle( (OAEVENT*) &hEvent );
You can pass the retrieved event handle to the Microsoft Win32 WaitForMultipleObjects or MsgWaitForMultipleObjects functions to wait for event notifications at the same time as other messages and events on a single thread. The implementation of GetEvent sets and resets the handle within the application, so applications should not reset the handle themselves.

IMediaEvent::RestoreDefaultHandling

IMediaEvent Interface

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

Syntax

HRESULT RestoreDefaultHandling(
    long lEvCode
);

Parameters

lEvCode
[in] Event code for which to restore default handling.

Return Value

Returns S_OK if successful, or S_FALSE if there is no default handling for this event.

Remarks

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

IMediaEvent::WaitForCompletion

IMediaEvent Interface

Blocks execution of the application thread until the graph's operation finishes.

Syntax

HRESULT WaitForCompletion(
    long msTimeout,
    long *pEvCode
);

Parameters

msTimeout
[in] Duration of the time-out, in milliseconds. Pass zero to return immediately. To block indefinitely, pass INFINITE.
pEvCode
[out] Pointer to the event that terminated the wait. This value can be one of the following:

EC_COMPLETE Operation completed.
EC_ERRORABORT Error. Playback can't continue.
EC_USERABORT User terminated the operation.
Zero Operation has not completed.

Return Value

Returns one of the following HRESULT values.

E_ABORT Function timed out before the operation completed. This is equivalent to a zero pEvCode value.
S_OK Operation completed.

Remarks

This method is the equivalent of blocking until the event notification EC_COMPLETE, EC_ERRORABORT, or EC_USERABORT is received, or the time-out occurs.
When this method returns, the filter graph is still running. This method assumes that separate calls to the IMediaEvent interface are not being made. The method fails if the graph is not in, or transitioning into, a running state.
The time-out parameter (msTimeout) specifies the length of time to wait for completion. To test whether the operation completed, specify a zero msTimeout value and check the event code value (pEvCode) for zero, indicating that the operation has not completed.

EC_COMPLETE	Operation completed.
EC_ERRORABORT	Error. Playback can't continue.
EC_USERABORT	User terminated the operation.
Zero	Operation has not completed.

E_ABORT	Function timed out before the operation completed. This is equivalent to a zero pEvCode value.
S_OK	Operation completed.