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_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_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. |
An audio or video renderer is losing or gaining activation. The audio or video renderer sends this event notification.
EC_ACTIVATE
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.
The buffering status is changing.
EC_BUFFERING_DATA
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.
The filter graph has changed from one reference clock to another.
EC_CLOCK_CHANGED
One likely cause of this event notification is a call to the IMediaFilter::SetSyncSource method.
All data has been rendered. Renderers send this event notification.
EC_COMPLETE
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).
The current display mode has been changed. Renderers send this event notification when they detect a display change.
EC_DISPLAY_CHANGED
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.
A playback error has occurred, but the graph is still playing.
EC_ERROR_STILLPLAYING
An error forced the termination of a requested operation.
EC_ERRORABORT
A filter or the filter graph manager generates this event notification and sends it to the application.
The video renderer is switching out of full-screen mode.
EC_FULLSCREEN_LOST
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.
The current graph must be stopped and restarted.
EC_NEED_RESTART
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.
Pass the window handle around during pin connection.
EC_NOTIFY_WINDOW
A filter is passing a text string to the application.
EC_OLE_EVENT
The open file status is changing.
EC_OPENING_FILE
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.
The video palette has changed.
EC_PALETTE_CHANGED
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.
The playback quality has changed.
EC_QUALITY_CHANGE
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.
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
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.
The shutdown of the filter graph is starting.
EC_SHUTTING_DOWN
This event notification is not sent to the application. This notification notifies plug-in distributors that the filter graph is shutting down.
A filter has detected starvation.
EC_STARVATION
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.
A previous call to the IAMStreamControl::StartAt method has taken effect.
EC_STREAM_CONTROL_STARTED
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.
A previous call to the IAMStreamControl::StopAt method has taken effect.
EC_STREAM_CONTROL_STOPPED
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.
The stream is still playing, but should not be playing.
EC_STREAM_ERROR_STILLPLAYING
A filter send this event notification to the filter graph manager and the application.
The stream has stopped, but should not have stopped.
EC_STREAM_ERROR_STOPPED
This event notification is sent from a filter to the filter graph manager and the application.
The requested reference time occurred.
EC_TIME
A user has forced the termination of a requested operation.
EC_USERABORT
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.
The size of the native video has changed.
EC_VIDEO_SIZE_CHANGED
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.
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
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.