Microsoft DirectX 9.0

IMediaEvent::GetEventHandle

The GetEventHandle method 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 IMediaEvent::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.

Do not close the event handle returned by this method, because the event handle is used internally by the filter graph. Also, do not use the handle after you release the Filter Graph Manager, because the handle becomes invalid after the Filter Graph Manager is destroyed. (To avoid this error, it is a good idea to duplicate the handle by calling DuplicateHandle, and use the duplicate instead of the original handle. Close the duplicate handle when you are finished.)

For Automation compatibility, this method takes a pointer to an OAEVENT type. In C++, declare a variable of type HANDLE and cast it an OAEVENT pointer, as follows:

HANDLE hEvent;
GetEventHandle( (OAEVENT*) &hEvent );

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

See Also