IAMMultiMediaStream Interface

The IAMMultiMediaStream interface exposes Microsoft® DirectShow® functionality to multimedia stream developers. You can use its methods to automatically generate filter graphs, open files or monikers for playback or capture of incoming data, and render a given filter graph.

Implement this interface when you want to provide multimedia stream-based support for DirectShow media types in your applications.

Use this interface when you want to control DirectShow-supported media playback in your multimedia streaming applications.

Methods in Vtable Order

IUnknown methods Description

QueryInterface Retrieves pointers to supported interfaces.

AddRef Increments the reference count.

Release Decrements the reference count.

IAMMultiMediaStream methods Description

Initialize Sets the stream type. If the pFilterGraph parameter is non-NULL the filter graph passed in is used for the stream.

GetFilterGraph Retrieves the associated filter graph's IGraphBuilder interface.

GetFilter Retrieves the specified filter from the current filter graph.

AddMediaStream Adds the specified media stream to the current filter graph.

OpenFile Opens and automatically creates a filter graph for the specified media file. If DirectShow doesn't support the file format, this method does nothing.

OpenMoniker Opens a file or device moniker; you can read media data from this moniker if DirectShow supports the media type.

Render Renders the current filter graph.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMMultiMediaStream methods	Description
Initialize	Sets the stream type. If the pFilterGraph parameter is non-NULL the filter graph passed in is used for the stream.
GetFilterGraph	Retrieves the associated filter graph's IGraphBuilder interface.
GetFilter	Retrieves the specified filter from the current filter graph.
AddMediaStream	Adds the specified media stream to the current filter graph.
OpenFile	Opens and automatically creates a filter graph for the specified media file. If DirectShow doesn't support the file format, this method does nothing.
OpenMoniker	Opens a file or device moniker; you can read media data from this moniker if DirectShow supports the media type.
Render	Renders the current filter graph.

IAMMultiMediaStream::AddMediaStream

IAMMultiMediaStream Interface

Adds the specified media stream to the current filter graph.

Syntax

HRESULT AddMediaStream(
    IUnknown *pStreamObject,
    const MSPID *pPurposeID,
    DWORD dwFlags,
    IMediaStream **ppNewStream
    );

Parameters

pStreamObject
[in] Pointer to an IUnknown interface that points to either the media stream or underlying stream object you want to add to the current filter graph.
pPurposeID
[in] Pointer to the purpose ID for the newly added media stream.
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.

ppNewStream
[out] Address of a pointer to an IMediaStream interface that will point to the newly added media stream. This parameter is optional.

Return Value

Returns an HRESULT value, which can include the following values.

MS_E_PURPOSEID Stream being added has a different purpose ID from the one specified or a stream with the specified purpose ID already exists.
E_POINTER Null pointer argument.
S_OK Success.

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 DirectSound. In this case the pStreamObject parameter must be NULL and any calls to the IMultiMediaStream::GetMediaStream or IMultiMediaStream::EnumMediaStreams methods 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.

IAMMultiMediaStream::GetFilter

IAMMultiMediaStream Interface

Retrieves the specified filter from the current filter graph.

Syntax

HRESULT GetFilter(
    IMediaStreamFilter **ppFilter
    );

Parameters

ppFilter
[out] Address of a pointer to an IMediaStreamFilter interface that will point to the current filter.

Return Value

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

IAMMultiMediaStream::GetFilterGraph

IAMMultiMediaStream Interface

Retrieves the associated filter graph's IGraphBuilder interface.

Syntax

HRESULT GetFilterGraph(
    IGraphBuilder **ppGraphBuilder
    );

Parameters

ppGraphBuilder
[out] Address of a pointer to an IGraphBuilder interface that will point to the current filter graph.

Return Value

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

IAMMultiMediaStream::Initialize

IAMMultiMediaStream Interface

Sets the stream type. If the pFilterGraph parameter is non-NULL, the filter graph passed in is used for the stream.

Syntax

HRESULT Initialize(
    STREAM_TYPE StreamType,
    DWORD dwFlags,
    IGraphBuilder *pFilterGraph
    );

Parameters

StreamType
[in] STREAM_TYPE enumeration value that specifies the new filter graph's stream type.
dwFlags
[in] Either contains the AMMSF_NOGRAPHTHREAD flag, which creates a filter graph object on the current thread, or zero.
pFilterGraph
[in] [optional] Pointer to an IGraphBuilder interface that will point to the new filter graph. This parameter is optional; only pass in a valid pointer if you must access the filter graph at a later time.

Return Value

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

Remarks

Using the AMMSF_NOGRAPHTHREAD flag is safe provided the current thread does not exit before the stream object is released by the application and the current thread processes window messages.

IAMMultiMediaStream::OpenFile

IAMMultiMediaStream Interface

Opens and automatically creates a filter graph for the specified media file. If DirectShow doesn't support the file format, this method does nothing.

Syntax

HRESULT OpenFile(
    LPCWSTR pszFileName,
    DWORD dwFlags
    );

Parameters

pszFileName
[in] Pointer to the name of the file you want to open.
dwFlags
[in] Value that modifies how the filter graph will render the specified file. This value is a combination of one or more of the following flags.

AMMSF_RENDERTOEXISTING Only render to existing streams
AMMSF_RENDERALLSTREAMS Render all streams, including those that do not have an existing media stream.
AMMSF_NORENDER Open the file, but do not render any streams. This flag should always be accompanied with the AMMSF_RUN flag.
AMMSF_NOCLOCK Run the stream with no clock.
AMMSF_RUN Set the stream into the run state.

Return Value

Returns one of the following values.

E_INVALIDARG The dwFlags parameter is invalid.
E_POINTER This method tried to access an invalid pointer.
S_OK Success.

Remarks

The AMMSF_RENDERALLSTREAMS flag will create default rendering filters for video and audio if they do not exist. However, these default filters cannot be accessed by the IStreamSample::GetMediaStream method.

IAMMultiMediaStream::OpenMoniker

IAMMultiMediaStream Interface

Opens a file or device moniker; you can read media data from this moniker if DirectShow supports the moniker.

Syntax

HRESULT OpenMoniker(
    IBindCtx *pCtx,
    IMoniker *pMoniker,
    DWORD dwFlags
    );

Parameters

pCtx
[in] Pointer to the bind context associated with the moniker.
pMoniker
[in] Pointer to an IMoniker interface that specifies the moniker you want to open.
dwFlags
[in] Value that modifies how the filter graph will render the specified file. This value is a combination of one or more of the following flags:

AMMSF_RENDERTOEXISTING Only render to existing streams.
AMMSF_RENDERALLSTREAMS Render all streams, including those that do not have an existing media stream.
AMMSF_NORENDER Open the file, but do not render any streams. This flag should always be accompanied with the AMMSF_RUN flag.
AMMSF_NOCLOCK Run the stream with no clock.
AMMSF_RUN Set the stream into the run state.

Return Value

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

IAMMultiMediaStream::Render

IAMMultiMediaStream Interface

Renders the current filter graph.

Syntax

HRESULT Render(
    DWORD dwFlags
    );

Parameters

dwFlags
[in] Value that specifies how the filter graph renders the current multimedia stream. This value currently must be AMMSF_NOCLOCK.

Return Value

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

Remarks

This method renders each of the source streams for a stream of type STREAMTYPE_WRITE. This can be called several times, for instance, each time a source stream is added, the stream is not set into running mode. Use the IMultiMediaStream::SetState method to set the stream into running mode after calling this method.
The AMMSF_RENDERALLSTREAMS flag will create default rendering streams for video and audio if they do not exist.

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.

MS_E_PURPOSEID	Stream being added has a different purpose ID from the one specified or a stream with the specified purpose ID already exists.
E_POINTER	Null pointer argument.
S_OK	Success.

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.

AMMSF_RENDERTOEXISTING	Only render to existing streams
AMMSF_RENDERALLSTREAMS	Render all streams, including those that do not have an existing media stream.
AMMSF_NORENDER	Open the file, but do not render any streams. This flag should always be accompanied with the AMMSF_RUN flag.
AMMSF_NOCLOCK	Run the stream with no clock.
AMMSF_RUN	Set the stream into the run state.

E_INVALIDARG	The dwFlags parameter is invalid.
E_POINTER	This method tried to access an invalid pointer.
S_OK	Success.

AMMSF_RENDERTOEXISTING	Only render to existing streams.
AMMSF_RENDERALLSTREAMS	Render all streams, including those that do not have an existing media stream.
AMMSF_NORENDER	Open the file, but do not render any streams. This flag should always be accompanied with the AMMSF_RUN flag.
AMMSF_NOCLOCK	Run the stream with no clock.
AMMSF_RUN	Set the stream into the run state.