ICaptureGraphBuilder2::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.]
The ControlStream method sets the start and stop times for one or more streams of captured data.
Syntax
HRESULT ControlStream(
[in] const GUID *pCategory,
[in] const GUID *pType,
[in] IBaseFilter *pFilter,
[in] REFERENCE_TIME *pstart,
[in] REFERENCE_TIME *pstop,
[in] WORD wStartCookie,
[in] WORD wStopCookie
);
Parameters
[in] pCategory
A pointer to a GUID that specifies one of the pin categories listed in Pin Property Set. The value of this parameter cannot be NULL.
[in] pType
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.
[in] pFilter
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.
[in] pstart
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.
[in] pstop
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.
[in] wStartCookie
Value that is sent as the second parameter of the EC_STREAM_CONTROL_STARTED event notification. See Remarks for more information.
[in] wStopCookie
Value that is sent as the second parameter of the EC_STREAM_CONTROL_STOPPED event notification. See Remarks for more information.
Return value
Returns an HRESULT value. Possible values include the following.
| Return code | Description |
|---|---|
|
At least one downstream renderer will not send a stop notification. |
|
Success. |
|
Could not find a matching pin, or the pin did not support stream control. |
|
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.
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.
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
| 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 |