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

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.