Event Notification Codes


		Index Topic Contents
	Previous Topic: Event Notification Codes Next Topic: DVD Event Notification Codes

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.
See DVD Event Notification Codes for event notification codes that are specific to DVD. The following list shows the available event notification codes in alphabetical order.

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_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_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_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.
EC_ACTIVATE
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.
EC_BUFFERING_DATA

The buffering status is changing.
EC_BUFFERING_DATA
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.
EC_CLOCK_CHANGED

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

lParam1
Zero.
lParam2
Zero.

Remarks

One likely cause of this event notification is a call to the IMediaFilter::SetSyncSource method.
EC_COMPLETE

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

lParam1
HRESULT value of some operation. This can be S_OK.
lParam2
Zero.

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).
EC_DISPLAY_CHANGED

The current display mode has been changed. Renderers send this event notification when they detect a display change.
EC_DISPLAY_CHANGED
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.
EC_END_OF_SEGMENT

Notifies that a segment end has been reached.
EC_END_OF_SEGMENT
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.
EC_ERROR_STILLPLAYING

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

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

EC_ERRORABORT

An error forced the termination of a requested operation.
EC_ERRORABORT
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.
EC_FULLSCREEN_LOST

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

lParam1
Zero.
lParam2
Pointer to the IBaseFilter interface that is sending the notification (the modex 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.
EC_NEED_RESTART

The current graph must be stopped and restarted.
EC_NEED_RESTART
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.
EC_NOTIFY_WINDOW

Pass the window handle around during pin connection.
EC_NOTIFY_WINDOW
Parameters

lParam1
Handle to the window.
lParam2
Zero.

EC_OLE_EVENT

A filter is passing a text string to the application.
EC_OLE_EVENT
Parameters

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

EC_OPENING_FILE

The open file status is changing.
EC_OPENING_FILE
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.
EC_PALETTE_CHANGED

The video palette has changed.
EC_PALETTE_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.
EC_QUALITY_CHANGE

The playback quality has changed.
EC_QUALITY_CHANGE
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.
EC_REPAINT

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.
EC_REPAINT
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.
EC_SEGMENT_STARTED

Notifies that a new segment has been started.
EC_SEGMENT_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.
EC_SHUTTING_DOWN

The shutdown of the filter graph is starting.
EC_SHUTTING_DOWN
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.
EC_STARVATION

A filter has detected starvation.
EC_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.
EC_STREAM_CONTROL_STARTED

A previous call to the IAMStreamControl::StartAt method has taken effect.
EC_STREAM_CONTROL_STARTED
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.
EC_STREAM_CONTROL_STOPPED

A previous call to the IAMStreamControl::StopAt method has taken effect.
EC_STREAM_CONTROL_STOPPED
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.
EC_STREAM_ERROR_STILLPLAYING

The stream is still playing, but should not be playing.
EC_STREAM_ERROR_STILLPLAYING
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.
EC_STREAM_ERROR_STOPPED

The stream has stopped, but should not have stopped.
EC_STREAM_ERROR_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.
EC_TIME

The requested reference time occurred.
EC_TIME
Parameters

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

EC_USERABORT

A user has forced the termination of a requested operation.
EC_USERABORT
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.
EC_VIDEO_SIZE_CHANGED

The size of the native video has changed.
EC_VIDEO_SIZE_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.
EC_WINDOW_DESTROYED

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.
EC_WINDOW_DESTROYED
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).
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.
Top of Page

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_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_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_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.