Event Notification for Filters
A version of this page is also available for
4/8/2010
At various times while a DirectShow application is running, the status of a filter might change. For example, it might go from paused to running, encounter an error in the stream, or request that the video window be repainted. To alert the filter graph manager of a change, the filter sends an event notification, which consists of an event code that indicates the type of event, and two parameters that supply additional information. The meaning of the parameters depends on the event code.
The filter graph manager handles some events without notifying the application, such as a request to repaint the video window. It places other events into a queue, from which the application retrieves and processes them in order. DirectShow event notification is similar in this respect to Microsoft Message Queuing. In fact, you can have the filter graph manager send a Windows message to a designated window when a new event occurs. That way, the application can handle the events from within the window's message loop.
An application might need to handle a number of event codes, depending on the purpose of the application. This topic focuses on two: EC_COMPLETE and EC_USERABORT.
- Renderer filters signal EC_COMPLETE when they reach the end of a data stream. A filter graph might contain more than one stream; for example, a video stream and an audio stream. Each stream is associated with its own renderer and therefore generates a separate EC_COMPLETE event. Rather than forward all the EC_COMPLETE events to the application, the filter graph manager waits until it receives one EC_COMPLETE notification for every stream in the graph. At that point, it sends a single EC_COMPLETE event to the application. When the application receives the EC_COMPLETE event, all the streams have finished.
- The EC_USERABORT event indicates that the user has interrupted playback. Video renderers send this event if the user closes the video window.