IAMStreamControl::StartAt

  • Article
 
Microsoft DirectShow 9.0

IAMStreamControl::StartAt

The StartAt method informs the pin when to start delivering data.

Syntax

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

Parameters

ptStart

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

dwCookie

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

Return Values

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

Header: Declared in Strmif.h; include Dshow.h.

Library: Use Strmiids.lib.

See Also