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.
When to Implement
Implement this interface when you want to provide multimedia stream-based support for DirectShow media types in your applications.
When to Use
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. |
Adds the specified media stream to the current filter graph.
HRESULT AddMediaStream(
IUnknown* pStreamObject,
const MSPID *pPurposeID,
DWORD dwFlags,
IMediaStream** ppNewStream
)
| AMMSF_ADDDEFAULTRENDERER | Add a default renderer. |
| AMMSF_CREATEPEER | Create a peer stream based on the same object as a pStreamObject. |
Returns an HRESULT value, which can include the following values:
| Value | Meaning |
| MS_E_PURPOSEID | Stream being added has a different PurposeId from the one specified or a stream with the specified PurposeId already exists. |
| E_POINTER | NULL pointer argument. |
| S_OK | Success. |
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. pStreamObject varies depending on the stream type. In general pStreamObject can point to an IMediaStream object, in which case a stream with the sample PurposeId and format is created. For IDirectDraw streams it can also be a pointer to an IDirectDraw object.
If neither flag is 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 tothe 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. |
Retrieves the specified filter from the current filter graph.
HRESULT GetFilter(
IMediaStreamFilter** ppFilter
)
Returns S_OK if successful or E_POINTER if one or more of the required parameters are null.
Retrieves the associated filter graph's IGraphBuilder interface.
HRESULT GetFilterGraph(
IGraphBuilder **ppGraphBuilder
);
Returns S_OK if successful or E_POINTER if one or more of the required parameters are null.
Sets the stream type. If the pFilterGraph parameter is non-NULL the filter graph passed in is used for the stream.
HRESULT Initialize(
STREAM_TYPE StreamType,
DWORD dwFlags,
IGraphBuilder * pFilterGraph
)
Returns S_OK if successful or E_POINTER if one or more of the required parameters are null.
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.
Opens and automatically creates a filter graph for the specified media file. If DirectShow doesn't support the file format, this method does nothing.
HRESULT OpenFile(
LPCWSTR pszFileName,
DWORD dwFlags
)
| Value | Meaning |
| 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. |
Returns one of the following values.
| Value | Meaning |
| E_INVALIDARG | The dwFlags parameter is invalid. |
| E_POINTER | This method tried to access an invalid pointer. |
| S_OK | Success. |
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.
Opens a file or device moniker; you can read media data from this moniker if DirectShow supports the moniker.
HRESULT OpenMoniker(
IBindCtx *pCtx,
IMoniker* pMoniker,
DWORD dwFlags
)
| Value | Meaning |
| 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. |
Returns S_OK if successful or E_INVALIDARG if the dwFlags parameter is invalid.
Renders the current filter graph.
HRESULT Render(
DWORD dwFlags
)
| Name | Description |
Returns S_OK if successful or E_INVALIDARG if the dwFlags parameter is invalid.
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.