Microsoft DirectX 8.0

IMediaEvent Interface

This interface contains methods for retrieving event notifications and for overriding the filter graph's default handling of events. The IMediaEventEx interface inherits this interface and extends it.

The filter graph manager implements this interface. Applications can use it to respond to events that occur in the filter graph, such as the end of a stream or a rendering error. Filters post events to the filter graph using the IMediaEventSink interface.

For more information about event notification, see Event Notification in DirectShow. For a list of system-defined event notifications, see Event Notification Codes.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IDispatch methodsDescription
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 methodsDescription
GetEventHandleRetrieves a handle to a manual-reset event that remains signaled while the queue contains event notifications.
GetEventRetrieves the next event notification from the event queue.
WaitForCompletionWaits for the filter graph to render all available data.
CancelDefaultHandlingCancels the filter graph manager's default handling of a specified event.
RestoreDefaultHandlingRestores the filter graph manager's default handling of a specified event.
FreeEventParamsFrees resources associated with the parameters of an event.

IMediaEvent::CancelDefaultHandling

IMediaEvent Interface

Cancels the filter graph manager's default handling of a specified event. The event notification is passed to the application.

Syntax

HRESULT CancelDefaultHandling(
    long lEvCode
);

Parameters

lEvCode
Event code for which to cancel default handling.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.
S_OKSuccess.
E_INVALIDARGNo default handling for this event.

Remarks

To restore the default handling for an event, call the RestoreDefaultHandling method with the event code.

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] Event code.
lParam1
[in] First event parameter.
lParam2
[in] Second event parameter.

Return Value

Returns S_OK.

Remarks

After you call the IMediaEvent::GetEvent method to retrieve an event notification, you must call FreeEventParams. This method frees any resources that were allocated for the event parameters. Pass in the same variables used for the GetEvent call, as shown in the following example:

hr = pEvent->GetEvent(&evCode, &param1, &param2, 0);
// Handle the event (not shown). 
hr = pEvent->FreeEventParams(evCode, param1, param2);

IMediaEvent::GetEvent

IMediaEvent Interface

Retrieves the next event notification from the event queue.

Syntax

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

Parameters

IEventCode
[out] Pointer to a variable that receives the event code.
lParam1
[out] Pointer to a variable that receives the first event parameter.
lParam2
[out] Pointer to a variable that receives the second event parameter.
msTimeout
[in] Time-out interval, in milliseconds. Use INFINITE to block until there is an event.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
E_ABORTTimeout expired.

Remarks

Applications should avoid using a time-out interval of INFINITE, because threads cannot process any messages while waiting in GetEvent. If you call GetEvent from the same thread that processes Windows messages, specify only small wait times, 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, call the FreeEventParams method to release any resources allocated for the event parameters.

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 remains signaled while the queue contains event notifications.

Syntax

HRESULT GetEventHandle(
    OAEVENT *hEvent
);

Parameters

hEvent
[out] Pointer to a variable that receives the event handle.

Return Value

Returns S_OK.

Remarks

The filter graph manager keeps a manual-reset event that reflects the state of the event queue. If the queue contains event notifications, the manual-reset event is signaled. If the queue is empty, the IMediaEvent::GetEvent method resets the event.

An application can use this event to determine the state of the queue. First call GetEventHandle to obtain a handle to the event. Wait for the event to be signaled, using a Microsoft® Windows® function such as WaitForSingleObject. When the event is signaled, call the GetEvent method to retrieve the next event notification from the queue. The filter graph manager keeps the event signaled until the queue is empty; then it resets the event.

Note  For Automation compatibility, this method takes a pointer to an OAEVENT variable. In C++, declare a variable of type HANDLE and cast it to type OAEVENT, as follows:
HANDLE hEvent;
GetEventHandle( (OAEVENT*) &hEvent );

Another way for applications to monitor the event queue is by calling the IMediaEventEx::SetNotifyWindow method.

IMediaEvent::RestoreDefaultHandling

IMediaEvent Interface

Restores the filter graph manager's default handling of a specified event.

Syntax

HRESULT RestoreDefaultHandling(
    long lEvCode
);

Parameters

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

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_INVALIDARGNo default handling for this event.

Remarks

By default, the filter graph manager handles some events (such as EC_REPAINT) without passing them to the application. If you call the CancelDefaultHandling method to override the default handling for an event, you can restore the default behavior by calling RestoreDefaultHandling with the same event code.

IMediaEvent::WaitForCompletion

IMediaEvent Interface

Waits for the filter graph to render all available data. The filter graph must be running or the method fails.

Syntax

HRESULT WaitForCompletion(
    long msTimeout,
    long *pEvCode
);

Parameters

msTimeout
[in] Time-out interval, in milliseconds. Pass zero to return immediately. Pass the value INFINITE to block indefinitely.
pEvCode
[out] Pointer to a variable that receives an event code. See Remarks for more information.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_ABORTTime-out expired.
VFW_E_WRONG_STATEThe filter graph is not running.

Remarks

This method blocks until the time-out expires, or one of the following events occurs:

During the wait, the method discards all other event notifications.

If the return value is S_OK, the pEvCode parameter receives the event code that ended the wait. When the method returns, the filter graph is still running. The application can pause or stop the graph, as appropriate.