End-of-Stream Notifications

Article
07/27/2023

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

When a source filter is done sending data, it calls the IPin::EndOfStream method on the downstream input pin. The downstream filter propagates the call to the next filter, and so on. When the EndOfStream call reaches the renderer, the renderer sends an EC_COMPLETE event to the Filter Graph Manager. If the renderer has multiple input pins, it delivers the EC_COMPLETE event after every input pin has received the end-of-stream notification.

A filter must serialize EndOfStream calls with other streaming calls, such as IMemInputPin::Receive. (In other words, the downstream filter must always receive the calls in the correct order.)

In some cases, a downstream filter might detect the end of the stream before the source filter does. (For example, the downstream filter might be parsing the stream.) In that case, the downstream filter can send the end-of-stream notification, in which case it should return S_FALSE from IMemInputPin::Receive until the graph stops or flushes. The S_FALSE return value informs the source filter to stop sending data.

Default Handling of EC_COMPLETE

By default, the Filter Graph Manager does not forward every EC_COMPLETE event to the application. Instead, it waits until all streams have signaled EC_COMPLETE and then sends a single EC_COMPLETE event. Thus, the application receives the event after every stream has completed.

To determine the number of streams, the Filter Graph Manager counts the number of filters that support seeking (through IMediaSeeking or IMediaPosition) and have a rendered input pin, which is defined as an input pin with no corresponding outputs. The Filter Graph Manager determines whether a pin is rendered in one of two ways:

The pin's IPin::QueryInternalConnections method returns zero in the nPin parameter.
The filter exposes the IAMFilterMiscFlags interface and returns the AM_FILTER_MISC_FLAGS_IS_RENDERER flag.