The IMultiMediaStream interface provides methods that control a multimedia stream and provide access to its underlying media streams. A multimedia stream is the highest-level streaming object and can contain one or more media streams. While each media stream is media-type specific (audio, video, and so on), multimedia streams are generic across all types because they must provide access to a number of streams that can have very different media types. IMultiMediaStream interface methods enable you to enumerate and retrieve pointers to the specific streams; IMediaStream interface methods provide specific control over the media stream behavior.
For sample code which implements the Multimedia streaming interfaces see Multimedia Streaming Sample Code.
When to Implement
Implement this interface when you want create containers for a specific type of media stream.
When to Use
Use this interface when application need to enumerate and control a multimedia stream's underlying, type-specific streams.
Methods in Vtable Order
IUnknown methods | Description |
QueryInterface | Retrieves pointers to supported interfaces. |
AddRef | Increments the reference count. |
Release | Decrements the reference count. |
IMultiMediaStream methods | Description |
GetInformation | Retrieves the capabilities and stream type of a mulitmedia stream. |
GetMediaStream | Returns a media stream that has the specified purpose ID. |
EnumMediaStreams | Retrieves a media stream from a multimedia stream by zero-based index. |
GetState | Retrieves the multimedia stream's current state. |
SetState | Sets the media stream to either a running or stopped state. |
GetTime | Retrieves the current time from the multimedia stream's clock, if it has a clock. |
GetDuration | Retrieves the media stream's duration. |
Seek | Sets the seek location of all derived media streams to the specified time. |
GetEndOfStreamEventHandle | Retrieves the handle for the event triggered when the stream completes playback. |
Retrieves a media stream from a multimedia stream by zero-based index.
HRESULT EnumMediaStreams(
long Index,
IMediaStream** ppMediaStream )
Returns one of the following values.
Value | Meaning |
E_POINTER | The ppMediaStream pointer is invalid. |
S_FALSE | Index is out of range; no streams are left to enumerate. When the method returns this value, it also sets ppMediaStream to NULL. |
S_OK | Success. |
You should call this method until it returns S_FALSE, which indicates that the stream enumeration is complete.
Returns the media stream's duration.
HRESULT GetDuration(
STREAM_TIME *pDuration
)
Returns one of the following values.
Value | Meaning |
E_POINTER | The value of pDuration is invalid. |
MS_E_WRITESTREAM | The media stream is writable and therefore has no duration. |
S_FALSE | Stream contains live data or this method couldn't determine the duration. On exit, this method sets pDuration to zero. |
S_OK | Stream contains recorded media. On return, pDuration contains duration of media. |
Retrieves the handle for the event triggered when the stream completes playback.
HRESULT GetEndOfStreamEventHandle(
HANDLE* phEOS
)
Returns S_OK if successful or E_POINTER if one or more of the required parameters are null.
The Microsoft® Win32® WaitForSingleObject and WaitForMultipleObjects functions use the retrieved handle to watch for completion of playback.
Retrieves the capabilities of a media stream that matches the specified media type.
HRESULT GetInformation(
DWORD *pdwFlags,
STREAM_TYPE *pStreamType
);
MMSSF_ASYNCHRONOUS | The stream supports asynchronous sample updates. All implementations of IMultiMediaStream will support the asyncronous updates, this flag confirms it. |
MMSSF_HASCLOCK | The stream has a clock. |
MMSSF_SUPPORTSEEK | The stream supports seeking. |
Returns S_OK if successful.
A stream's capabilities include whether it has a clock, if it supports seeking, and whether it supports asynchronous updating.
Retrieves a media stream that has the specified purpose ID.
HRESULT GetMediaStream(
REFMSPID idPurpose,
IMediaStream **pMediaStream
);
Returns one of the following values.
Value | Meaning |
E_POINTER | The ppMediaStream pointer is invalid. |
MS_E_NOSTREAM | No stream has the specified purpose ID. |
S_OK | Success. |
If a stream exists that matches the purpose ID in idPurpose, the ppMediaStream parameter points to the stream and increments its reference count.
MSPID_PrimaryVideo and MSPID_PrimaryAudio, which represent the primary video and audio streams, are the most commonly used purpose IDs.
Retrieves the multimedia stream's current state.
HRESULT GetState(
STREAM_STATE* pCurrentState
)
Returns S_OK if successful or E_POINTER if pCurrentState is invalid.
Retrieves the current time from the multimedia stream's clock, if it has a clock.
HRESULT GetTime(
STREAM_TIME* pCurrentTime
)
Returns one of the following values.
Value | Meaning |
E_POINTER | The pCurrentTime pointer is invalid. |
S_FALSE | Stream doesn't have a clock; *pCurrentTime is zero. |
S_OK | Stream has a clock and the method succeeded; pCurrentTime contains the current time. |
If the stream doesn't have a clock, this method sets *pCurrentTime to zero and returns S_FALSE. If a stream has a clock, the stream sample times are relative to the stream's clock.
STREAM_TIME is defined as a LONGLONG value.
Sets the seek location of all contained media streams to the specified time.
HRESULT Seek(
STREAM_TIME SeekTime
)
Returns one of the following values.
Value | Meaning |
E_POINTER | One of the pointers is invalid. |
MS_E_NOSEEKING | One or more media streams don't support seeking. |
MS_E_WRITESTREAM | The streams are writable and therefore don't support seeking. |
S_OK | Success. |
This method won't work on streams that don't support seeking. Before calling this method, retrieve the stream's capabilities by calling IMultiMediaStream::GetInformation; if the retrieved value includes the MMSSF_SUPPORTSEEK flag, you can call this method.
When seeking a stream that has a clock, the current time can change to an unpredictable value, including a time before the desired seek time. This causes the method to fail.
This method seeks to the specified time in all the media streams contained under the multimedia stream object.
Sets the media stream to either a running or stopped state.
HRESULT SetState(
STREAM_STATE NewState
)
Returns S_OK.
When you set the stream to STREAMSTATE_STOP, this method deletes all data still pending.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.