Event Notification Codes

Microsoft® DirectShow® supports system-defined events, which filters in the filter graph pass to the filter graph manager . Filters pass these events to the filter graph manager by using the IMediaEventSink::Notify method, and the application retrieves them with the IMediaEvent::GetEvent method.

When you retrieve an event by calling GetEvent, the event can contain interface pointers or pointers to allocated memory. Code that uses GetEvent should, therefore, call IMediaEvent::FreeEventParams to free any resources associated with the event's parameters after it handles the event.

The system-defined event notification codes are listed in the Evcode.h header file. The following list shows the available event notification codes in alphabetical order. For event notification codes that are specific to DVD, see DVD Event Notification Codes.

The parameters listed with an event notification code are the ones passed with the code in the CBaseFilter::NotifyEvent function. For example, consider the following statements.

NotifyEvent(EC_OLE_EVENT, (DWORD) bstr, NULL);
NotifyEvent(EC_COMPLETE, S_OK, 0);
NotifyEvent(EC_ERRORABORT, E_FAIL, 0);

Event notification code	Description
EC_ACTIVATE	An audio or video renderer is losing or gaining activation.
EC_BUFFERING_DATA	The buffering status is changing.
EC_CLOCK_CHANGED	The filter graph has changed from one reference clock to another.
EC_COMPLETE	All data has been rendered.
EC_DISPLAY_CHANGED	The current display mode has been changed.
EC_END_OF_SEGMENT	Notifies that a segment end has been reached.
EC_ERROR_STILLPLAYING	At least one call to Run failed in an active filter graph. The current state of any underlying filter graph or graphs is indeterminate; they might be running, but some are almost certainly not.
EC_ERRORABORT	An error forced the termination of a requested operation.
EC_FULLSCREEN_LOST	The video renderer is switching out of full-screen mode.
EC_GRAPH_CHANGED	The filter graph structure has changed.
EC_NEED_RESTART	The current graph must be stopped and restarted.
EC_NOTIFY_WINDOW	Pass the window handle around during pin connection.
EC_OLE_EVENT	A filter is passing a text string to the application.
EC_OPENING_FILE	The open file status is changing.
EC_PALETTE_CHANGED	The video palette has changed.
EC_PAUSED	Notifies the application that the pause request has completed.
EC_QUALITY_CHANGE	The playback quality has changed.
EC_REPAINT	A repaint is required.
EC_SEGMENT_STARTED	Notifies that a new segment has been started.
EC_SHUTTING_DOWN	The filter graph is starting to shut down. DirectShow passes this notification to any plug-in distributors that support the IMediaEventSink interface.
EC_SNDDEV_IN_ERROR	An audio device error has occurred on an input pin.
EC_SNDDEV_OUT_ERROR	An audio device error has occurred on an output pin.
EC_STARVATION	One of the filters (usually a parser or file source filter) isn't receiving enough data. By default, the filter graph manager will pause all running filters, and then return to normal operation when enough data is available.
EC_STREAM_CONTROL_STARTED	The starting reference time from an earlier call to IAMStreamControl::StartAt passed.
EC_STREAM_CONTROL_STOPPED	The stopping reference time from an earlier call to IAMStreamControl::StopAt passed.
EC_STREAM_ERROR_STILLPLAYING	The stream is still playing, but should not be playing.
EC_STREAM_ERROR_STOPPED	The stream has stopped, but should not have stopped.
EC_TIME	The requested reference time occurred.
EC_USERABORT	A user has forced the termination of a requested operation.
EC_VIDEO_SIZE_CHANGED	The size of the native video has changed.
EC_WINDOW_DESTROYED	The video renderer's filter is being removed or destroyed.

EC_ACTIVATE

An audio or video renderer is losing or gaining activation. The audio or video renderer sends this event notification.

Parameters

lParam1
Set to 1 if activation gained, or 0 if lost.
lParam2
Pointer to the IBaseFilter interface that is sending the event notification.

Remarks

This event notification is not sent to the application. This notification is used for sound-follows-focus and full-screen switching. To interact in full-screen protocols, a video renderer should send an EC_ACTIVATE notification whenever its window is either activated or deactivated. In other words, an EC_ACTIVATE notification should be sent for each WM_ACTIVATEAPP message received by a renderer.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_BUFFERING_DATA

Event Notification Codes

The buffering status is changing.

Parameters

lParam1
Set to 1 if starting to buffer data, or 0 if not buffering any more.
lParam2
Zero.

Remarks

This event notification is sent to the application. This notification is used to allow the user interface to indicate that some data (media) is being buffered (loaded) prior to being processed by DirectShow. This notification is also sent when the buffering has stopped.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_CLOCK_CHANGED

Event Notification Codes

The filter graph has changed from one reference clock to another.

Parameters

lParam1
Zero.
lParam2
Zero.

Remarks

One likely cause of this event notification is a call to the IMediaFilter::SetSyncSource method.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_COMPLETE

Event Notification Codes

All data has been rendered. Renderers send this event notification.

Parameters

lParam1
HRESULT value of some operation. This can be S_OK.
lParam2
Zero or the renderer's IBaseFilter pointer.

Remarks

The default is not to send this event notification to the application, you can override the default by calling the IMediaEvent::CancelDefaultHandling method. No more data should be accepted after the EndOfStream method is called on the renderer's input pin. Exactly one EC_COMPLETE notification must be sent for each logical stream. Stopping a renderer resets any end-of-stream state that is cached.
Although individual EC_COMPLETE events aren't sent by default, the last individual EC_COMPLETE is sent to the application when all streams have sent one to the filter graph. If the default handling is turned off, the application gets them all (one per stream). If default handling is enabled, the lParam2 argument is null. If it is disabled, lParam2 contains the IBaseFilter pointer of the sending filter or null if the filter does not provide it. As with all events, call IMediaEvent::FreeEventParams to release any resources held by the event.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_DISPLAY_CHANGED

Event Notification Codes

The current display mode has been changed. Renderers send this event notification when they detect a display change.

Parameters

lParam1
Pointer to the IPin interface that should be reconnected by the graph.
lParam2
Zero.

Remarks

This event notification is not sent to the application. Most video renderers pick a format during connection so that the format can be drawn efficiently through GDI. If the user changes the current display mode without restarting the machine, a renderer might find itself with a bad image format connection. In these situations, a renderer might send an EC_DISPLAY_CHANGED event code to the filter graph manager. The first parameter should be the pin that needs reconnecting. The filter graph manager will arrange for the filter graph to be stopped and the pin reconnected. During the subsequent reconnection, the renderer can accept a more appropriate format.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_END_OF_SEGMENT

Event Notification Codes

Notifies that a segment end has been reached.

Parameters

lParam1
Pointer to a REFERENCE_TIME value indicating accumulated stream clock time since the start of the segment. You can compute this time directly as the sum of the previous and current segment durations and the rate applied to each segment. The source adds this time to the time within each segment to get a total elapsed time.
lParam2
DWORD value indicating the segment number. Zero based.

Remarks

Notifies that a segment end has been reached when the AM_SEEKING_Segment flag was set for IMediaSeeking::SetPositions. Passes in an IMediaSeeking interface to allow the next segment to be defined by the application.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_ERROR_STILLPLAYING

Event Notification Codes

A playback error has occurred, but the graph is still playing.

Parameters

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

Remarks

For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_ERRORABORT

Event Notification Codes

An error forced the termination of a requested operation.

Parameters

lParam1
HRESULT value of some operation that failed. For instance, this might be VFW_E_CANNOT_CONNECT if a reconnect failed.
lParam2
Zero.

Remarks

A filter or the filter graph manager generates this event notification and sends it to the application.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_FULLSCREEN_LOST

Event Notification Codes

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

Parameters

lParam1
Zero.
lParam2
Pointer to the IBaseFilter interface that is sending the notification (the Mode X renderer in this case).

Remarks

The full-screen renderer sends this event notification to an application. When the EC_ACTIVATE notification is sent to the filter graph manager upon switching out of full-screen mode, the filter graph manager sends an EC_FULLSCREEN_LOST notification to the controlling application. The application might use this notification to restore the state of a full-screen button, for example. The EC_ACTIVATE notifications are used internally by DirectShow to manage full-screen switching on cues from the video renderers.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_GRAPH_CHANGED

Event Notification Codes

The structure of the filter graph has changed.

Parameters

lParam1
Zero.
lParam2
Zero.

Remarks

This event code is useful for debugging and demo applications. This is not guaranteed to be sent for all graph changes. For instance, it is not sent when the application calls RenderFile.
The GraphEdt tool will redraw its filter diagram each time it gets this event.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_NEED_RESTART

Event Notification Codes

The current graph must be stopped and restarted.

Parameters

lParam1
Zero.
lParam2
Zero.

Remarks

Renderers send this notification when they regain a resource. For example, if a renderer loses contact with a device and rejects the next data sample, the stream must reconnect to the device and restart at the current position to start rendering data again. If the media stream is currently running, DirectShow calls IAMovie::Pause to pause the stream, IAMovie::put_CurrentPosition to set the current position, and IAMovie::Run to restart the stream.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_NOTIFY_WINDOW

Event Notification Codes

Pass the window handle around during pin connection.

Parameters

lParam1
Handle to the window.
lParam2
Zero.

Remarks

For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_OLE_EVENT

Event Notification Codes

A filter is passing a text string to the application.

Parameters

lParam1
BSTR for the event notification. The application must free the BSTR by calling the IMediaEvent::FreeEventParams method.
lParam2
Zero.

Remarks

For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_OPENING_FILE

Event Notification Codes

The open file status is changing.

Parameters

lParam1
Set to 1 if starting to open file, or 0 if not opening any more.
lParam2
Zero.

Remarks

This event notification is sent to the application. This notification is used to allow the user interface to indicate that a media file is being opened prior to being processed by DirectShow. (Because the file might be on the Internet or some slow device, some opens might take longer.) This notification is also sent when the file has been opened.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_PALETTE_CHANGED

Event Notification Codes

The video palette has changed.

Parameters

lParam1
Zero.
lParam2
Zero.

Remarks

This event notification is sent to the application and the filter graph manager. Whenever a video renderer detects a palette change in the stream, it should send the EC_PALETTE_CHANGED notification to the filter graph manager. The DirectShow video renderers detect whether a palette has really changed in dynamic format or not. The video renderers do this not only to filter out the number of EC_PALETTE_CHANGED notifications sent, but also to reduce the amount of palette creation, installation, and deletion required.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_PAUSED

Event Notification Codes

Notifies the application that the pause request has completed.

Parameters

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

Remarks

For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_QUALITY_CHANGE

Event Notification Codes

The playback quality has changed.

Parameters

lParam1
Zero.
lParam2
Zero.

Remarks

This event notification is sent to the application from a filter. This notification occurs only once if degradation has occurred and a filter has responded to a quality event notification.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_REPAINT

Event Notification Codes

A repaint is required. Paused or stopped video renderers send this message when they receive a WM_PAINT message and there is no data to display.

Parameters

lParam1
Pointer to the IPin interface that needs the data to be sent again.
lParam2
Zero.

Remarks

The default is not to send this event notification to the application, although the default can be overridden by calling IMediaEvent::CancelDefaultHandling. A renderer should send its input pin as the first parameter to the event. By doing this, the attached output pin will be queried for IMediaEventSink, and if supported, the EC_REPAINT notification will be sent there first. This allows output pins to handle repaints before the filter graph must be touched.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_SEGMENT_STARTED

Event Notification Codes

Notifies that a new segment has been started.

Parameters

lParam1
Pointer to a REFERENCE_TIME value indicating accumulated stream clock time since the start of the segment. You can compute this time directly as the sum of the previous and current segment durations and the rate applied to each segment.
lParam2
DWORD value indicating the segment number. Zero based.

Remarks

This notification is sent synchronously by any entity that will issue EC_END_OF_SEGMENT when a new segment is started. See the AM_SEEKING_Segment flag from IMediaSeeking::SetPositions. This notification is used to compute how many EC_END_OF_SEGMENT notifications to expect at the end of a segment and as a consistency check.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_SHUTTING_DOWN

Event Notification Codes

The shutdown of the filter graph is starting.

Parameters

lParam1
Zero.
lParam2
Zero.

Remarks

This event notification is not sent to the application. This notification notifies plug-in distributors that the filter graph is shutting down.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

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, notifying the application of how the device was being accessed when the failure occurred.
lParam2
DWORD value indicating the error returned from the sound device call.

Remarks

All audio device error events are passed to the application. Errors are never processed by the filter graph.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

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, notifying the application of how the device was being accessed when the failure occurred.
lParam2
DWORD value indicating the error returned from the sound device call.

Remarks

All audio device error events are passed to the application. Errors are never processed by the filter graph.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_STARVATION

Event Notification Codes

A filter has detected starvation.

Parameters

lParam1
Zero.
lParam2
Zero.

Remarks

A filter sends this event notification. This notification is not sent to the application. The default handling of this notification (only when running) is for the graph to be paused until all filters enter the paused state, and then to wait for the pause to complete. The filter which signaled EC_STARVATION should not complete the pause until it has enough data to resume. Normally, this would be sent by a parser or source filter when too little data is arriving.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_STREAM_CONTROL_STARTED

Event Notification Codes

A previous call to the IAMStreamControl::StartAt method has taken effect.

Parameters

pSender
Address of an IPin interface that will contain the pin that called IAMStreamControl::StartAt.
dwCookie
DWORD value that you can use to mark the start.

Remarks

You can mark calls to this event with dwCookie, allowing applications to easily associate request and completion notifications.
After the completion of this event, pSender will point to the pin that called IAMStreamControl::StartAt. This is not necessarily the pin that received the IAMStreamControl::StartAt call.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_STREAM_CONTROL_STOPPED

Event Notification Codes

A previous call to the IAMStreamControl::StopAt method has taken effect.

Parameters

pSender
Address of an IPin interface that will contain the pin that called IAMStreamControl::StopAt.
dwCookie
DWORD value that you can use to mark the stop.

Remarks

You can mark calls to this event with dwCookie, allowing applications to easily associate request and completion notifications.
After the completion of this event, pSender will point to the pin that called IAMStreamControl::StopAt. This is not necessarily the pin that received the IAMStreamControl::StopAt call.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_STREAM_ERROR_STILLPLAYING

Event Notification Codes

The stream is still playing, but should not be playing.

Parameters

lParam1
Major code (HRESULT of some operation that failed).
lParam2
Minor code (generally zero).

Remarks

A filter send this event notification to the filter graph manager and the application.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_STREAM_ERROR_STOPPED

Event Notification Codes

The stream has stopped, but should not have stopped.

Parameters

lParam1
Major code (HRESULT of some operation that failed).
lParam2
Minor code (generally zero.).

Remarks

This event notification is sent from a filter to the filter graph manager and the application.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_TIME

Event Notification Codes

The requested reference time occurred.

Parameters

lParam1
Reference time, low-order DWORD.
lParam2
Reference time, high-order DWORD.

Remarks

For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_USERABORT

Event Notification Codes

A user has forced the termination of a requested operation.

Parameters

lParam1
Zero.
lParam2
Zero.

Remarks

This event notification is sent by video renderers to the filter graph manager and the application. This notification signals a closure that the user requested. For example, this notification would be sent if the user closed the video window. After this notification has been sent, no more samples should be accepted until the renderer has gone through a stop transition. No EC_REPAINT notifications should be sent after an EC_USERABORT notification is sent unless the renderer is stopped and reset.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_VIDEO_SIZE_CHANGED

Event Notification Codes

The size of the native video has changed.

Parameters

lParam1
Low-order WORD value is the width in pixels; high-order WORD is the height in pixels.
lParam2
Zero.

Remarks

This event notification is sent whenever a video renderer detects a change in native video size. An application might use this notification to negotiate space in a compound document. The actual video dimensions are available through the IBasicVideo control interface. The DirectShow renderers detect whether the video has changed size or not prior to sending these events.
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.

EC_WINDOW_DESTROYED

Event Notification Codes

The video renderer's filter is being removed or destroyed. Video renderers send this event notification so that resources that depend on window focus can be passed to other filters.

Parameters

lParam1
Pointer to the IBaseFilter interface whose window is being destroyed.
lParam2
Zero.

Remarks

This event notification is not sent to the application. A renderer should send this notification when its window is destroyed. The first parameter must be the renderer's IBaseFilter interface. In fact, sending this when the filter is being destroyed might be too late, because the filter graph manager might have already been destroyed. Therefore, it is best to handle this when the renderer's IBaseFilter::JoinFilterGraph method is called with a null filter graph (indicating that the renderer is about to be removed from the filter graph). Sending these event codes allows the plug-in distributor in the filter graph manager to pass on resources that depend on window focus to other filters (such as audio devices).
For information on how to send this event code from your filter, see CBaseFilter::NotifyEvent.