IAMStreamControl::StopAt 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 StopAt method informs the pin when to stop delivering data.

Syntax

HRESULT StopAt(
  [in] const REFERENCE_TIME *ptStop,
  [in] BOOL                 bSendExtra,
  [in] DWORD                dwCookie
);

Parameters

[in] ptStop

Pointer to a REFERENCE_TIME value that specifies when the pin should stop delivering data. If the value is MAXLONGLONG (0x7FFFFFFFFFFFFFFF), the method cancels any previous stop request. If psStop is NULL, the pin stops immediately.

For preview pins, only the values NULL and MAXLONGLONG are valid, because preview pins do not time stamp the samples they deliver.

[in] bSendExtra

Specifies a Boolean value that indicates whether to send an extra sample after the scheduled stop time. If TRUE, the pin sends one extra sample.

[in] dwCookie

Specifies a value to send along with the start notification. See Remarks.

Return value

If the method succeeds, the return value is S_OK. Otherwise, returns an HRESULT value indicating the cause of the failure.

Remarks

If the dwCookie parameter is non-zero, the pin will send an EC_STREAM_CONTROL_STOPPED event when it stops delivering data. The first event parameter is a pointer to the pin's IPin interface, and the second is the value of dwCookie. If ptStop is NULL or MAXLONGLONG, no event is sent, and the value of dwCookie is ignored.

In video capture, you would typically call this method on the capture filter's output pin and the multiplexer's input pin. The application should wait for the stop event from the multiplexer. This ensures that the capture filter sends the right number of frames, while guaranteeing that all frames reach the multiplexer. Also, set the bSendExtra parameter to TRUE for the capture pin, but FALSE for the multiplexer pin. This causes the capture filter to send one additional frame. The multiplexer relies on the time stamps from the capture pin, so if the extra frame is not sent, the multiplexer will wait indefinitely for the stop time. When the multiplexer receives the extra frame, it will discard it.

This method handles the following boundary conditions:

If the stop time falls between the start and stop times of a sample, the pin delivers that sample.
If the start time equals the stop time, the pin delivers one sample.

MAXLONGLONG is the largest possible REFERENCE_TIME value. In the base class library, it is also defined as the constant MAX_TIME.

Requirements

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