IPinConnection::NotifyEndOfStream method (strmif.h)

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

The NotifyEndOfStream method requests notification from the pin when the next end-of-stream condition occurs.

Syntax

HRESULT NotifyEndOfStream(
  [in] HANDLE hNotifyEvent
);

Parameters

[in] hNotifyEvent

Handle to an event object that the pin will signal.

Return value

Returns an HRESULT value. Possible values include the following.

Return code	Description
S_FALSE	Event handle was NULL, but there was no existing event handle to reset.
S_OK	Event handle was set. (If event handle was NULL, event notification was canceled.)

Remarks

This method enables the caller to push data through a portion of the filter graph ending with this pin.

For example, suppose the caller is pushing data from an output pin called "A" on one filter, to an input pin called "B" on another filter, possibly with intermediate filters connecting them. The following sequence of events would take place.

The caller blocks the data flow at pin A.
It calls NotifyEndOfStream on pin B.
It calls IPin::EndOfStream on the input pin connected to pin A.
As the remaining data travels downstream through any intermediate filters, those filters propagate the end-of-stream notification.
When pin B receives the end-of-stream notification, it signals the event given in the hNotifyEvent parameter. At that point, the caller can safely reconfigure the graph between pin A and pin B.

Because the purpose of this method is to enable the caller to rebuild the graph dynamically and then restart the connection, the end-of-stream notification does not represent the actual end of the stream. Therefore, pin B does not propagate the end-of-stream condition or signal EC_COMPLETE. This is an exception to the usual rules for data flow in the filter graph.

It is the caller's responsibility to cancel notification by calling this method again with a NULL event handle.

The filter graph calls this method inside the IGraphConfig::Reconnect method. If an application or filter does any specialized dynamic reconfiguration to the graph (using the IGraphConfig::Reconfigure method), it might call this method first in order to push data through the portion of the graph that is being reconfigured.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	strmif.h (include Dshow.h)
Library	Strmiids.lib