Microsoft DirectX 8.0

Event Notification Codes

Microsoft® DirectShow® supports system-defined events. Filters pass events to the filter graph manager using the IMediaEventSink::Notify method. The filter graph manager handles some events, and passes others to the application. The application can retrieve events by calling the IMediaEvent::GetEvent method. For more information, see Event Notification in DirectShow.

This article describes the DirectShow events that are not specific to DVD. For events that are specific to DVD, see DVD Event Notification Codes.

For each event, this article lists the event code and the meaning of the two event parameters. It also describes the filter graph manager's default handling for the event, if any. To override the default handling, call IMediaEvent::CancelDefaultHandling in your application.

The event notification codes are defined in the header files Evcode.h and Audevcod.h.

Event notification codeDescription
EC_ACTIVATEA video window is being activated or deactivated.
EC_BUFFERING_DATAThe graph is buffering data, or has stopped buffering data.
EC_CLOCK_CHANGEDThe reference clock has changed.
EC_COMPLETEAll data from a particular stream has been rendered.
EC_DEVICE_LOSTA Plug and Play device was removed or has become available again.
EC_DISPLAY_CHANGEDThe display mode has changed.
EC_END_OF_SEGMENTThe end of a segment has been reached.
EC_ERROR_STILLPLAYINGAn asynchronous command to run the graph has failed.
EC_ERRORABORTAn operation was aborted because of an error.
EC_FULLSCREEN_LOSTThe video renderer is switching out of full-screen mode.
EC_GRAPH_CHANGEDThe filter graph has changed.
EC_NEED_RESTARTA filter is requesting that the graph be restarted.
EC_NOTIFY_WINDOWNotifies a filter of the video renderer's window.
EC_OLE_EVENTA filter is passing a text string to the application.
EC_OPENING_FILEThe graph is opening a file, or has finished opening a file.
EC_PALETTE_CHANGEDThe video palette has changed.
EC_PAUSEDA pause request has completed.
EC_QUALITY_CHANGEThe graph is dropping samples, for quality control.
EC_REPAINTA video renderer requires a repaint.
EC_SEGMENT_STARTEDA new segment has started.
EC_SHUTTING_DOWNThe filter graph is shutting down, prior to being destroyed.
EC_SNDDEV_IN_ERRORAn audio device error has occurred on an input pin.
EC_SNDDEV_OUT_ERRORAn audio device error has occurred on an output pin.
EC_STARVATIONA filter is not receiving enough data.
EC_STEP_COMPLETEA filter performing frame stepping has stepped the specified number of frames.
EC_STREAM_CONTROL_STARTEDA stream-control start command has taken effect.
EC_STREAM_CONTROL_STOPPEDA stream-control start command has taken effect.
EC_STREAM_ERROR_STILLPLAYINGAn error has occurred in a stream. The stream is still playing.
EC_STREAM_ERROR_STOPPEDA stream has stopped because of an error.
EC_USERABORTThe user has terminated playback.
EC_VIDEO_SIZE_CHANGEDThe native video size has changed.
EC_WINDOW_DESTROYEDThe video renderer was destroyed or removed from the graph.

EC_ACTIVATE

A video window is being activated or deactivated.

Parameters

lParam1
TRUE if the window is activated, or FALSE if the window is deactivated.
lParam2
Pointer to the renderer's IBaseFilter interface.

Default Handling

The filter graph manager sets the focus, through the IResourceManager interface. It does not send the event notification to the application.

Remarks

A video renderer sends this event whenever its window is activated or deactivated (that is, when it receives a WM_ACTIVATEAPP message). Window activation or deactivation can occur because the window has gained or lost focus, or because the renderer has switched between full-screen mode and windowed mode.

This event enables the filter graph manager to allocate resources that depend on window focus, such as audio devices.

EC_BUFFERING_DATA

Event Notification Codes

The graph is buffering data, or has stopped buffering data.

Parameters

lParam1
TRUE if the graph is starting to buffer, or FALSE if the graph has stopped buffering.
lParam2
Zero.

Default Handling

None.

Remarks

A filter can send this event if it needs to buffer data from an external source. (For example, it might be loading data from a network.) The application can use this event to adjust its user interface.

EC_CLOCK_CHANGED

Event Notification Codes

The reference clock has changed.

Parameters

lParam1
Zero.
lParam2
Zero.

Default Handling

None.

Remarks

The filter graph manager sends this event when its IMediaFilter::SetSyncSource method is called.

EC_COMPLETE

Event Notification Codes

All data from a particular stream has been rendered.

Parameters

lParam1
HRESULT value; can be S_OK.
lParam2
Zero, or a pointer to the renderer's IBaseFilter interface.

Default Handling

By default, the filter graph manager does not forward this event to the application. However, after all the streams in the graph report EC_COMPLETE, the filter graph manager posts a separate EC_COMPLETE event to the application.

If default handling is disabled for this event, the application receives all of the EC_COMPLETE events from the renderers.

Remarks

A renderer filter sends this event when it receives an end-of-stream notice. (End-of-stream is signaled through the IPin::EndOfStream method.) The filter sends exactly one EC_COMPLETE event for each stream. The filter must process any pending samples before it sends the event. Stopping a renderer resets any end-of-stream state that was cached.

Filters set the lParam2 parameter to an IBaseFilter pointer. If default handling is enabled, the filter graph manager sets this parameter to zero.

EC_DEVICE_LOST

Event Notification Codes

A Plug and Play device was removed or has become available again.

Parameters

lParam1
Pointer to the IUnknown interface of the filter that represents the device.
lParam2
Zero if the device was removed, or 1 if the device is available again.

Default Handling

None.

Remarks

When the device becomes available again, the previous state of the device filter is no longer valid. The application must rebuild the graph in order to use the device.

EC_DISPLAY_CHANGED

Event Notification Codes

The display mode has changed.

Parameters

lParam1
Pointer to the IPin interface of the video renderer's input pin, or zero.
lParam2
Zero.

Default Handling

The filter graph manager temporarily stops the graph, and then disconnects and reconnects the video renderer. It does not pass the event to the application.

Remarks

Video renderers can send this event in response to a WM_DISPLAYCHANGE message. The WM_DISPLAYCHANGE message indicates that the user has changed the display resolution.

During pin connection, most video renderers pick a format based on the current display mode. If the display mode changes, the video renderer might need to choose another format. By sending this message, the renderer signals to the filter graph manager that it needs to be reconnected. During the reconnection, the renderer can select a new format. If the reconnection fails, the filter graph manager sends an EC_ERRORABORT event to the application.

EC_END_OF_SEGMENT

Event Notification Codes

The end of a segment has been reached.

Parameters

lParam1
Pointer to a REFERENCE_TIME value that specifies the accumulated stream time since the start of the segment.
lParam2
DWORD value indicating the segment number (zero-based).

Default Handling

The filter graph manager checks the number of EC_END_OF_SEGMENT events against the number of EC_SEGMENT_STARTED events. If they match, it forwards the EC_END_OF_SEGMENT event to the application.

Remarks

This event code supports seamless looping. When a call to the IMediaSeeking::SetPositions method includes the AM_SEEKING_Segment flag, the source filter sends this event code instead of calling IPin::EndOfStream.

EC_ERROR_STILLPLAYING

Event Notification Codes

An asynchronous command to run the graph has failed.

Parameters

lParam1
HRESULT value of the operation that failed.
lParam2
Zero.

Default Handling

None.

Remarks

If the filter graph manager issues an asynchronous run command that fails, it sends this event to the application. The graph remains in a running state. The state of the underlying filters is indeterminate. Some filters might be running, others might not.

EC_ERRORABORT

Event Notification Codes

An operation was aborted because of an error.

Parameters

lParam1
HRESULT value of the operation that failed.
lParam2
Zero.

Default Handling

None.

EC_FULLSCREEN_LOST

Event Notification Codes

The video renderer is switching out of full-screen mode.

Parameters

lParam1
Zero.
lParam2
Pointer to the video renderer's IBaseFilter interface, or NULL.

Default Handling

None.

Remarks

When the Full Screen Renderer loses activation, it sends this event. When another video renderer switches out of full-screen mode, the filter graph manager sends this event, in response to an EC_ACTIVATE event from the renderer.

EC_GRAPH_CHANGED

Event Notification Codes

The filter graph has changed.

Parameters

lParam1
Zero.
lParam2
Zero.

Default Handling

None.

Remarks

This event code is intended for debugging. It is not sent for all graph changes.

EC_NEED_RESTART

Event Notification Codes

A filter is requesting that the graph be restarted.

Parameters

lParam1
Zero.
lParam2
Zero.

Default Handling

The filter graph manager pauses and restarts the graph. It does not pass the event to the application.

Remarks

If a filter rejects a sample in the middle of a stream, the upstream pin will stop delivering samples. The filter can restart the stream by sending this event. For example, the audio renderer might lose access to the sound device, because a video window has lost focus. At that point, the audio renderer starts rejecting samples. When it regains access to the sound device, it sends this event to restart the audio stream.

EC_NOTIFY_WINDOW

Event Notification Codes

Notifies a filter of the video renderer's window.

Parameters

lParam1
Handle to the window.
lParam2
Zero.

Default Handling

This event is used internally by DirectShow. The filter graph manager does not pass this event to the application. Applications cannot override the default handling for this event.

Remarks

When a video renderer is connected, it checks whether the upstream output pin supports the IMediaEventSink interface. If so, the renderer sends this event to the upstream filter.

EC_OLE_EVENT

Event Notification Codes

A filter is passing a text string to the application.

Parameters

lParam1
String of type BSTR.
lParam2
String of type BSTR.

Default Handling

None.

Remarks

By convention, the first parameter contains type information (for example, Text) and the second parameter contains the text string.

EC_OPENING_FILE

Event Notification Codes

The graph is opening a file, or has finished opening a file.

Parameters

lParam1
TRUE if the graph is starting to open a file, or FALSE if the graph is no longer opening the file.
lParam2
Zero.

Default Handling

None.

Remarks

A filter can send this event if it spends significant time opening a file. (For example, the file might be located on a network.) The application can use this event to adjust its user interface.

Currently, none of the filters included with DirectShow send this event.

EC_PALETTE_CHANGED

Event Notification Codes

The video palette has changed.

Parameters

lParam1
Zero.
lParam2
Zero.

Default Handling

None.

Remarks

Video renderers send this event if they detect a palette change in the stream.

EC_PAUSED

Event Notification Codes

A pause request has completed.

Parameters

lParam1
HRESULT value that indicates the result of the transition. If the value is S_OK, the filter graph is now in a paused state.
lParam2
Zero.

Default Handling

None.

Remarks

The filter graph manager sends this event when it completes an asynchronous pause command.

EC_QUALITY_CHANGE

Event Notification Codes

The graph is dropping samples, for quality control.

Parameters

lParam1
Zero.
lParam2
Zero.

Default Handling

None.

Remarks

A filter sends this event if it drops samples in response to a quality control message. It sends the event only when it adjusts the quality level, not for each sample that it drops. For more information, see Quality Control Management.

EC_REPAINT

Event Notification Codes

A video renderer requires a repaint.

Parameters

lParam1
Pointer to the IPin interface of the video renderer's input pin, or NULL.
lParam2
Zero.

Default Handling

The lParam1 parameter might specify the video renderer's input pin. If so, the filter graph manager finds the output pin connected to that pin and queries it for the IMediaEventSink interface. If the output pin supports IMediaEventSink, the filter graph manager calls IMediaEventSink::Notify with the EC_REPAINT event code. This gives the upstream filter the opportunity to re-send the last sample.

If lParam1 is NULL, or if the pin does not support IMediaEventSink, or if the Notify method fails, the filter graph manager handles the EC_REPAINT event by itself. Its behavior depends on the state of the graph:

By default, the filter graph manager does not pass this event to the application.

Remarks

Video renderers send this message when they receive a WM_PAINT message and have no data to display.

EC_SEGMENT_STARTED

Event Notification Codes

A new segment has started.

Parameters

lParam1
Pointer to a REFERENCE_TIME value that specifies the accumulated stream time since the start of the segment.
lParam2
DWORD value indicating the segment number (zero-based).

Default Handling

This event is not sent to the application.

Remarks

If a filter will send an EC_END_OF_SEGMENT at the end of a segment, it sends this event at the start of the segment. The filter graph manager uses this event notification to compute how many EC_END_OF_SEGMENT notifications it should expect at the end of the segment.

By default, filters do not send EC_END_OF_SEGMENT events at the end of segments, and therefore should not send this event. For more information, see AM_SEEKING_Segment and IMediaSeeking::SetPositions.

EC_SHUTTING_DOWN

Event Notification Codes

The filter graph is shutting down, prior to being destroyed.

Parameters

lParam1
Zero.
lParam2
Zero.

Default Handling

This event is not sent to the application. The filter graph manager sends it to plug-in distributors, to notify them that the graph is shutting down. Applications cannot override the default handling of this event.

EC_SNDDEV_IN_ERROR

Event Notification Codes

An audio device error has occurred on an input pin.

Parameters

lParam1
DWORD value from the SNDDEV_ERR enumerated type, indicating how the device was being accessed when the failure occurred.
lParam2
DWORD value indicating the error returned from the sound device call.

Default Handling

None.

EC_SNDDEV_OUT_ERROR

Event Notification Codes

An audio device error has occurred on an output pin.

Parameters

lParam1
DWORD value from the SNDDEV_ERR enumerated type, indicating how the device was being accessed when the failure occurred.
lParam2
DWORD value indicating the error returned from the sound device call.

Default Handling

None.

EC_STARVATION

Event Notification Codes

A filter is not receiving enough data.

Parameters

lParam1
Zero.
lParam2
Zero.

Default Handling

The event is not sent to the application. If the filter graph is running, the filter graph manager pauses the graph and waits for the pause to complete. Then it runs the graph again. The filter sending the event should not complete its transition to paused until it has enough data to resume. If the filter graph is not running, the filter graph manager ignores this event.

Remarks

A parser or source filter can send this event if too little data is arriving.

EC_STEP_COMPLETE

Event Notification Codes

A filter performing frame stepping has stepped the specified number of frames.

Parameters

lParam1
Zero.
lParam2
Zero.

Default Handling

The filter graph manager pauses the graph and passes the event to the application.

See Also

IVideoFrameStep::Step

EC_STREAM_CONTROL_STARTED

Event Notification Codes

A stream-control start command has taken effect.

Parameters

pSender
Pointer to the IPin interface of the pin that started the stream.
dwCookie
User-defined DWORD value.

Default Handling

None.

Remarks

Filters send this event in response to the IAMStreamControl::StartAt method. This method specifies a reference time for a pin to begin streaming. When streaming does begin, the filter sends this event.

The pSender parameter specifies the pin that executes the start command. Depending on the implementation, it might not be the pin that received the StartAt call.

The dwCookie parameter is specified by the application in the StartAt method. This parameter enables the application to track multiple calls to the method.

EC_STREAM_CONTROL_STOPPED

Event Notification Codes

A stream-control start command has taken effect.

Parameters

pSender
Pointer to the IPin interface of the pin that stopped the stream.
dwCookie
User-defined DWORD value.

Default Handling

None.

Remarks

Filters send this event in response to the IAMStreamControl::StopAt method. This method specifies a reference time for a pin to stop streaming. When streaming does halt, the filter sends this event.

The pSender parameter specifies the pin that executes the stop command. Depending on the implementation, it might not be the pin that received the StopAt call.

The dwCookie parameter is specified by the application in the StopAt method. This parameter enables the application to track multiple calls to the method.

EC_STREAM_ERROR_STILLPLAYING

Event Notification Codes

An error has occurred in a stream. The stream is still playing.

Parameters

lParam1
HRESULT of the operation that failed.
lParam2
DWORD value, generally zero.

Default Handling

None. The application must decide whether to stop the graph.

EC_STREAM_ERROR_STOPPED

Event Notification Codes

A stream has stopped because of an error.

Parameters

lParam1
HRESULT of the operation that failed.
lParam2
DWORD value, generally zero.

Default Handling

None.

EC_USERABORT

Event Notification Codes

The user has terminated playback.

Parameters

lParam1
Zero.
lParam2
Zero.

Default Handling

None. The application must decide whether to stop the graph.

Remarks

This event code signals that the user has terminated normal graph playback. For example, video renderers send this event if the user closes the video window.

After sending this event, the filter should reject all samples and not send any EC_REPAINT events, until the filter stops and is reset.

EC_VIDEO_SIZE_CHANGED

Event Notification Codes

The native video size has changed.

Parameters

lParam1
Low-order WORD specifies the new width, in pixels; high-order WORD specifies the new height, in pixels.
lParam2
Zero.

Default Handling

None.

Remarks

Video renderers send this event if they detect a change in the native video size.

EC_WINDOW_DESTROYED

Event Notification Codes

The video renderer was destroyed or removed from the graph.

Parameters

lParam1
Pointer to the video renderer's IBaseFilter interface.
lParam2
Zero.

Default Handling

The filter graph manager releases this window as the focus, through the IResourceManager interface. It does not send the event notification to the application.

Remarks

The video renderer sends this event when it leaves the filter graph, in its IBaseFilter::JoinFilterGraph method. (Sending the event when the filter is destroyed might be too late, because at that point the filter graph manager might also be destroyed.)

This event enables other filters to acquire resources that depend on window focus, such as audio devices.