ICaptureGraphBuilder::ControlStream method (strmif.h)

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

Note  The ICaptureGraphBuilder interface is deprecated. Use ICaptureGraphBuilder2 instead.
 
Sends stream control messages to the pin of the specified category on one or more capture filters in a graph.

Syntax

HRESULT ControlStream(
  [in] const GUID     *pCategory,
  [in] IBaseFilter    *pFilter,
  [in] REFERENCE_TIME *pstart,
  [in] REFERENCE_TIME *pstop,
  [in] WORD           wStartCookie,
  [in] WORD           wStopCookie
);

Parameters

[in] pCategory

Pointer to a GUID specifying the output pin category. See Pin Property Set for a list of all pin categories. This value cannot be NULL.

[in] pFilter

Pointer to an IBaseFilter interface on the filter to control. Specifying NULL controls all capture filters in the graph. You will get one notification for each capture filter.

[in] pstart

Pointer to the start time for capture. NULL means start now. MAX_TIME means cancel previous request, or take no action if there is no previous request.

[in] pstop

Pointer to the stop time for capture. NULL means stop now. MAX_TIME means cancel previous request, or take no action if there is no previous request.

[in] wStartCookie

Specifies a particular value to be sent when the start occurs.

[in] wStopCookie

Specifies a particular value to be sent when the stop occurs.

Return value

Returns S_FALSE if the stop notification is sent before the last sample sent by the capture filter is rendered, otherwise returns S_OK.

If this method returns S_FALSE, the application might want to wait before stopping the filter graph to allow all samples to pass through the graph and be rendered. Otherwise, samples might be lost.

If there are no pins matching the description you provide, or if stream control cannot be supported on all of the indicated pins, this function will return a failure code.

Remarks

Use this method for frame-accurate capture, or for individual control of capture and preview. For example, you could turn off writing of the captured image to disk if you only want to preview the captured image.

This method uses the IAMStreamControl interface on the pins.

This method sends one notification for each filter found with a pin of the specified category.

Requirements

Requirement Value
Target Platform Windows
Header strmif.h (include Dshow.h)

See also

Error and Success Codes

ICaptureGraphBuilder Interface