IAMStreamControl Interface
A version of this page is also available for
4/8/2010
The IAMStreamControl interface 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 CBaseStreamControl base class implements IAMStreamControl. CBaseStreamControl enables the user to specify start and stop times in the CBaseStreamControl::StartAt and CBaseStreamControl::StopAt member functions and provides stream information in the CBaseStreamControl::GetInfo member function. CBaseStreamControl uses the StreamControlState enumerated 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 StreamControlState for more details on stream states.
If you want to implement this interface on your own your class should typically inherit from CBaseStreamControl to obtain an implementation of the CBaseStreamControl::StartAt, CBaseStreamControl::StopAt, and CBaseStreamControl::GetInfo methods. The CBaseStreamControl class also maintains state information and makes decisions about what to do with the sample. Developers implementing their own filters with pins that support IAMStreamControl through the CBaseStreamControl base class must follow certain guidelines outlined in the CBaseStreamControl documentation.
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 QueryInterface for 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 IAMStreamControl on 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::StartAt at 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 CBaseStreamControl for 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 |
|---|---|
Informs the pin when to start sending streaming data. |
|
Informs the pin when to suspend processing and supplying data. |
|
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 |