Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

The IAMStreamControlinterface is exposed on input and output pins on any filter in a filter graph. This interface exposes methods that allow applications to control individual stream components in a filter graph. You can turn various streams on or off without affecting the rest of the graph. For example, you can turn off an audio stream while a video stream continues, for muting. This interface also assists in frame accuracy when exact start or stop times are important.

Currently, the CBaseStreamControlbase class implements IAMStreamControl. CBaseStreamControlenables the user to specify start and stop times in the CBaseStreamControl::StartAtand CBaseStreamControl::StopAtmember functions and provides stream information in the CBaseStreamControl::GetInfomember function. CBaseStreamControluses the StreamControlStateenumerated data type to describe the various states a stream is in. A flowing stream is indicated by the STREAM_FLOWING setting; otherwise it is in a discarding state indicated by the STREAM_DISCARDING setting. See StreamControlStatefor more details on stream states.

If you want to implement this interface on your own your class should typically inherit from CBaseStreamControlto obtain an implementation of the CBaseStreamControl::StartAt, CBaseStreamControl::StopAt, and CBaseStreamControl::GetInfomethods. The CBaseStreamControlclass also maintains state information and makes decisions about what to do with the sample. Developers implementing their own filters with pins that support IAMStreamControlthrough the CBaseStreamControlbase class must follow certain guidelines outlined in the CBaseStreamControldocumentation.

Note:
There must be a clock in the filter graph or the stream control methods might not function as expected.

This interface is not available on the preview pin of capture cards with hardware overlay. Calling QueryInterfacefor this interface will return the error E_NOINTERFACE (0x80004002).

When to Implement

Implement on input or output pins of filters when you want precise control of the data stream. This interface enables you to turn off portions of the filter graph's streams at specific times without affecting the rest of the graph. Although this interface can be used throughout the graph, the input pins of multiplexer filters are the primary users.

If you are writing a filter that will implement IAMStreamControlon one of its pins, you should set the STREAM_DISCARDING state so that the pin discards media samples in a timely fashion, rather than as soon as they are received. This means that if your pin is discarding samples as soon as it determines they are outside the time that the pin is supposed to be on, it will discard samples as fast as possible and the whole file could potentially be pushed into your filter and discarded in mere moments. This causes problems if the pin tries to call IAMStreamControl::StartAtat a later point in time because the entire file will have already been discarded. To avoid pins from dumping media samples as fast possible, your code should check the media sample's timestamp and wait until the reference clock verifies that the end of the sample's time has actually occurred before discarding. This is known as discarding in a timely fashion (see CBaseStreamControlfor an implementation that does this).

When to Use

Use this interface to turn on or off certain portions of the filter graph's streams while other portions continue to process data. For example, your application can tell a video filter's input pin precisely when to start or stop playback, independent of what is happening in the rest of the graph. This assists in frame accuracy when exact start or stop times are important.

Methods in Vtable Order

The following table shows the methods that appear in the Vtable beneath the standard COM methods inherited from IUnknown.

Method Description

StartAt

Informs the pin when to start sending streaming data.

StopAt

Informs the pin when to suspend processing and supplying data.

GetInfo

Retrieves information about the current streaming settings.

Requirements

Windows Embedded CE Windows CE 2.12 and later
Windows Mobile Windows Mobile Version 5.0 and later
Note Microsoft DirectShow applications and DirectShow filters have different include file and Library requirements
For more information, see Setting Up the Build Environment