Microsoft DirectX 8.0 |
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 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 remains signaled while the queue contains event notifications. GetEvent Retrieves the next event notification from the event queue. WaitForCompletion Waits for the filter graph to render all available data. CancelDefaultHandling Cancels the filter graph manager's default handling of a specified event. RestoreDefaultHandling Restores the filter graph manager's default handling of a specified event. FreeEventParams Frees resources associated with the parameters of an event.
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_OK Success. E_INVALIDARG No default handling for this event.
Remarks
To restore the default handling for an event, call the RestoreDefaultHandling method with the event code.
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, ¶m1, ¶m2, 0); // Handle the event (not shown). hr = pEvent->FreeEventParams(evCode, param1, param2);
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_OK Success. E_ABORT Timeout 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.
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.
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_OK Success. E_INVALIDARG No 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.
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_OK Success. E_ABORT Time-out expired. VFW_E_WRONG_STATE The 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.