ICaptureGraphBuilder2::ControlStream

  • Article
 
Microsoft DirectShow 9.0

ICaptureGraphBuilder2::ControlStream

The ControlStream method sets the start and stop times for one or more streams of captured data.

Syntax

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

Parameters

pCategory

[in] Pointer to a member of the AMPROPERTY_PIN_CATEGORY structure of the Pin Property Set property set, specifying the pin category. The value of this parameter cannot be NULL.

pType

[in] Pointer to a major type GUID that specifies the media type, or NULL. If this parameter is NULL, set the pFilter parameter to NULL as well. Otherwise, you might control the wrong pin and get unpredictable results.

pFilter

[in] Pointer to an IBaseFilter interface that specifies which filter to control. To control all the capture filters in the graph, set this parameter to NULL.

pstart

[in] Pointer to a variable that contains the start time. If the value is MAXLONGLONG (0x7FFFFFFFFFFFFFFF), the method cancels the previous start request. If the value is NULL, the pin starts immediately when the graph runs.

pstop

[in] Pointer to a variable that contains the stop time. If the value is MAXLONGLONG, the method cancels any previous stop request. If the value is NULL, the pin stops immediately.

wStartCookie

[in] Value that is sent as the second parameter of the EC_STREAM_CONTROL_STARTED event notification. See Remarks for more information.

wStopCookie

[in] Value that is sent as the second parameter of the EC_STREAM_CONTROL_STOPPED event notification. See Remarks for more information.

Return Values

Returns an HRESULT value. Possible values include the following.

Return code Description
S_FALSE At least one downstream renderer will not send a stop notification.
S_OK Success.
E_FAIL Could not find a matching pin, or the pin did not support stream control.
E_POINTER NULL pointer argument.

Remarks

This method locates output pins on capture filters, using search criteria that you supply in the method call. Then it calls the IAMStreamControl methods on those pins. This method enables an application to control streams without the application needing to enumerate the filters and pins in the graph.

Use this method for frame-accurate capture, or for individual control of capture and preview. For example, you can stop capturing to disk but leave video preview running.

The first three parameters specify which pins to control. A capture graph can have more than one capture filter. For example, it might have filters for video, audio, and closed captioning data. Also, a capture filter can have more than one output pin. Some capture filters have separate pins for preview and capture, or separate pins for video-only data and audio-video interleaved data. To control video preview, for example, specify PIN_CATEGORY_PREVIEW for pCategory and MEDIATYPE_Video for pType.

  • Note   If the pin category is PIN_CATEGORY_PREVIEW, you cannot set specific start and stop times, because the samples delivered by a preview pin have no time stamps (see Time Stamps). Instead, use the values NULL and MAXLONGLONG to start and stop the pin at the desired times.
  • Also, this method is not supported for preview if the device uses a video port pin, because in that case the device is delivering the preview samples directly over hardware.

To control a pin, this method calls the IAMStreamControl::StartAt and IAMStreamControl::StopAt methods. Each pin sends an EC_STREAM_CONTROL_STARTED event notification when it starts. The second parameter of the event notification is the value given in wStartCookie. When the pin stops, it sends an EC_STREAM_CONTROL_STOPPED event notification. The second parameter of that event notification is the value given in wStopCookie.

When this method locates a matching pin, it searches downstream for another filter that supports IAMStreamControl (typically a multiplexer). If it finds one, it also sets the start and stop times on that filter. This generates two pairs of stop notifications: one for the capture filter, and one for the downstream filter. Only the stop notification from the downstream filter uses the wStopCookie parameter. Waiting for this event guarantees that the downstream filter receives the last sample.

If no downstream filter supports IAMStreamControl, the method returns S_FALSE. In that case, you might receive the stop notification before the last sample is rendered.

MAXLONGLONG is the largest possible REFERENCE_TIME value. In the DirectShow 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