Microsoft DirectX 8.0

IMediaEventEx Interface

This interface inherits the IMediaEvent interface, which contains methods for retrieving event notifications and for overriding the filter graph's default handling of events. IMediaEventEx adds methods that enable an application window to receive messages when events occur. Unlike IMediaEvent, this interface is not available through Automation, and therefore cannot be called directly from Microsoft® Visual Basic®.

The filter graph manager implements this 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.
IMediaEventEx methodsDescription
SetNotifyWindowRegisters a window to process event notifications.
SetNotifyFlagsEnables or disables event notifications.
GetNotifyFlagsDetermines whether event notifications are enabled.

IMediaEventEx::GetNotifyFlags

IMediaEventEx Interface

Determines whether event notifications are enabled.

Syntax

HRESULT GetNotifyFlags(
    long *lplNoNotifyFlags
); 

Parameters

lplNoNotifyFlags
[out] Pointer to a variable that receives one of the following values:
  • Zero: Event notifications are enabled.
  • AM_MEDIAEVENT_NONOTIFY: Event notifications are disabled.

Return Value

Returns S_OK if successful, or E_POINTER if the lplNoNotifyFlags parameter is NULL.

Remarks

By default, the filter graph manager posts event notifications for the application. To disable event notification, call the SetNotifyFlags method with the value AM_MEDIAEVENT_NONOTIFY.

If event notifications are disabled, the handle returned by the GetEventHandle method is signaled at the end of each stream—that is, whenever the filter graph manager receives an EC_COMPLETE event.

IMediaEventEx::SetNotifyFlags

IMediaEventEx Interface

Enables or disables event notifications.

Syntax

HRESULT SetNotifyFlags(
    long lNoNotifyFlags
); 

Parameters

lNoNotifyFlags
[in] Value indicating whether to enable or disable event notifications. Must be one of the following values:
  • Zero: Enable event notifications.
  • AM_MEDIAEVENT_NONOTIFY: Disable event notifications.

Return Value

Returns S_OK if successful, or E_INVALIDARG if the lNoNotifyFlags parameter is invalid.

Remarks

By default, the filter graph manager posts event notifications for the application. If the lNoNotifyFlags parameter is AM_MEDIAEVENT_NONOTIFY, the filter graph manager clears any pending event notifications from the queue, and does not post any new ones.

If event notifications are disabled, the handle returned by the GetEventHandle method is signaled at the end of each stream—that is, whenever the filter graph manager receives an EC_COMPLETE event.

IMediaEventEx::SetNotifyWindow

IMediaEventEx Interface

Registers a window to process event notifications.

Syntax

HRESULT SetNotifyWindow(
    OAHWND hwnd,
    long lMsg,
    long lInstanceData
);

Parameters

hwnd
[in] Handle to the window, or NULL to stop receiving event messages.
lMsg
[in] Window message to be passed as the notification.
lInstanceData
[in] Value to be passed as the lParam parameter for the lMsg message.

Return Value

Returns S_OK if successful or E_INVALIDARG if the hwnd parameter is not a valid handle to a window.

Remarks

This method designates a window that will process event notifications. Whenever the filter graph manager puts an event in the event queue, it will also post a message to the designated window. The hwnd parameter specifies the window, and the lMsg parameter specifies the message. The application should define a private window message for this purpose. The message's lParam parameter is set to the value of lInstanceData, and the wParam parameter is set to zero.

When the window receives the message, it should call the GetEvent method to retrieve the event. Events are asynchronous, so the queue might contain several events (or none). Call GetEvent repeatedly, until it returns an error code.