IAMMediaStream Interface

The IAMMediaStream interface handles the internal connections between Microsoft® DirectShow® filters and filter graphs in applications that use multimedia streaming. This enables applications to automatically negotiate the transfer and conversion of data from the source to the application without having to write code to handle the connection, transfer of data, data conversion, and actual data rendering or file storage. This provides a uniform and predictable method of data access and control.

This interface isn't intended for implementation or use by application developers.

Methods in Vtable Order

IUnknown methods Description

QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IAMMediaStream methods Description

Initialize Creates and initializes a new media stream with the specified stream type and purpose ID.
SetState Sets the filter state.
JoinAMMultiMediaStream The IAMMultiMediaStream::AddMediaStream method calls this method, which adds the specified media stream to the current multimedia stream.
JoinFilter Connects a media stream to a media stream filter in the underlying filter graph.
JoinFilterGraph Connects a media stream filter to a filter graph.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMMediaStream methods	Description
Initialize	Creates and initializes a new media stream with the specified stream type and purpose ID.
SetState	Sets the filter state.
JoinAMMultiMediaStream	The IAMMultiMediaStream::AddMediaStream method calls this method, which adds the specified media stream to the current multimedia stream.
JoinFilter	Connects a media stream to a media stream filter in the underlying filter graph.
JoinFilterGraph	Connects a media stream filter to a filter graph.

IAMMediaStream::Initialize

IAMMediaStream Interface

Creates and initializes a new media stream with the specified stream type and purpose ID.

Syntax

HRESULT Initialize(
    IUnknown *pSourceObject,
    DWORD dwFlags,
    REFMSPID PurposeID,
    STREAM_TYPE StreamType
    );

Parameters

pSourceObject
[in] Pointer to an IUnknown source object.

dwFlags
[in] Value that modifies the media stream's behavior; it is a combination of one or more of the following values.

AMMSF_ADDDEFAULTRENDERER Add a default renderer.
AMMSF_CREATEPEER Create a peer stream based on the same object as a pStreamObject.

AMMSF_STOPIFNOSAMPLES Terminates the stream if no samples were created or if the last sample is deleted.

AMMSF_NOSTALL Run the stream even if Update is not called.

PurposeID
[in] Purpose ID for the new media stream.
StreamType
[in] STREAM_TYPE enumeration value that specifies the new media stream's media type.

Return Value

Returns S_OK if successful or E_POINTER if one or more of the required parameters are invalid.

Remarks

If dwFlags specifies AMMSF_ADDDEFAULTRENDERER, then the default renderer for the given purpose ID is created, if possible. Currently, the only default renderer supported is for audio using Microsoft® DirectSound®. In this case, the pStreamObject parameter must be NULL and any calls to the IMultiMediaStream::GetMediaStream or IMultiMediaStream::EnumMediaStreams method will not recognize the stream.
If dwFlags specifies AMMSF_CREATEPEER, then a media stream is created using pStreamObject and added to the current multimedia stream. The pStreamObject parameter varies depending on the stream type. In general, pStreamObject can point to an IMediaStream object, in which case a stream with the sample purpose ID and format is created. For IDirectDraw streams, it can also be a pointer to an IDirectDraw object.
If dwFlags specifies AMMSF_STOPIFNOSAMPLES, then the stream is terminated.
If no flags are set, then pStreamObject can be one of the following.

An IAMMediaStream object This stream is then added to the streams in the multimedia stream.
NULL In this case a default IMediaStream object is added to the stream with a default underlying object, if required.
A pointer to an underlying object This is used to construct default streams. For video streams, this can be an IDirectDraw pointer.

IAMMediaStream::JoinAMMultiMediaStream

IAMMediaStream Interface

The IAMMultiMediaStream::AddMediaStream method calls this method, which adds the specified media stream to the current multimedia stream.

Syntax

HRESULT JoinAMMultiMediaStream(
    IAMMultiMediaStream *pAMMultiMediaStream
    );

Parameters

pAMMultiMediaStream
[in] Pointer to the IAMMultiMediaStream object to add the current media stream to.

Return Value

Returns S_OK if successful or MS_E_SAMPLEALLOC if the media stream already has allocated stream samples.

Remarks

Don't increment the reference count of the supplied multimedia stream because it is already accounted for when created.
Applications should not call this method.

IAMMediaStream::JoinFilter

IAMMediaStream Interface

Connects a media stream to a media stream filter in the underlying filter graph.

Syntax

HRESULT JoinFilter( );

Return Value

Returns S_OK if successful.

Remarks

Don't increment the reference count for the specified media stream filter.
Applications should not call this method.

IAMMediaStream::JoinFilterGraph

IAMMediaStream Interface

Connects a media stream filter to a filter graph.

Syntax

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph
    );

Parameters

pGraph
[in] Pointer to the current media stream filter to add to the specified filter graph.

Return Value

Returns S_OK if successful or E_POINTER if pGraph is NULL.

Remarks

Don't increment the reference count of the specified filter graph.
Applications should not call this method.

IAMMediaStream::SetState

IAMMediaStream Interface

Sets the filter state.

Syntax

HRESULT SetState(
    FILTER_STATE State
    );

Parameters

State
[in] Sets the filter's state, as specified by the FILTER_STATE enumerated type.

Return Value

Returns S_OK if successful or E_INVALIDARG if the State parameter is invalid.

Remarks

Applications should not call this method.

AMMSF_ADDDEFAULTRENDERER	Add a default renderer.
AMMSF_CREATEPEER	Create a peer stream based on the same object as a pStreamObject.
AMMSF_STOPIFNOSAMPLES	Terminates the stream if no samples were created or if the last sample is deleted.
AMMSF_NOSTALL	Run the stream even if Update is not called.

An IAMMediaStream object	This stream is then added to the streams in the multimedia stream.
NULL	In this case a default IMediaStream object is added to the stream with a default underlying object, if required.
A pointer to an underlying object	This is used to construct default streams. For video streams, this can be an IDirectDraw pointer.