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

Syntax

HRESULT StartAt(
  [in] const REFERENCE_TIME *ptStart,
  [in] DWORD                dwCookie
);

Parameters

[in] ptStart

Pointer to a REFERENCE_TIME value that specifies when the pin should start delivering data. If the value is MAXLONGLONG (0x7FFFFFFFFFFFFFFF), the method cancels the previous start request. If psStart is NULL, the pin starts immediately when the graph runs.

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

[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

By default, the pin delivers data as soon as the filter graph runs. The StartAt method causes the pin to wait until a specified time after the graph runs, before the pin begins delivering data.

If the dwCookie parameter is non-zero, the pin will send an EC_STREAM_CONTROL_STARTED event when it starts to deliver data. The first event parameter is a pointer to the pin's IPin interface, and the second is the value of dwCookie.

This method implements the following special cases:

If ptStart is NULL, the pin starts as soon as the graph runs. No event is sent, and the value of dwCookie is ignored.
If ptStart contains the value MAXLONGLONG, and there is a pending stop request, the pin starts when the graph runs. If there is no pending stop request, the pin remains stopped. In either case, no start event is sent, and the value of dwCookie is ignored.

This method also handles the following boundary conditions:

If the start 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