IMultiMediaStream Interface

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 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 that implements the multimedia streaming interfaces, see Multimedia Streaming Sample Code.

Implement this interface when you want to create containers for a specific type of media stream.

Use this interface when your application must 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 multimedia stream.
GetMediaStream Retrieves 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.

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 multimedia stream.
GetMediaStream	Retrieves 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.

IMultiMediaStream::EnumMediaStreams

IMultiMediaStream Interface

Retrieves a media stream from a multimedia stream by zero-based index.

Syntax

HRESULT EnumMediaStreams(

  long Index,

  IMediaStream **ppMediaStream

  );

Parameters

Index
[in] Index of the stream array to check.
ppMediaStream
[out] Address of a pointer to an IMediaStream interface object. On return, it contains a pointer to the stream at the specified index.

Return Value

Returns one of the following values.

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.

Remarks

You should call this method until it returns S_FALSE, which indicates that the stream enumeration is complete.

IMultiMediaStream::GetDuration

IMultiMediaStream Interface

Returns the media stream's duration.

Syntax

HRESULT GetDuration(
  STREAM_TIME *pDuration
  );

Parameters

pDuration
[out] Pointer to a STREAM_TIME value that will contain the media duration.

Return Value

Returns one of the following values.

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 return, this method sets pDuration to zero.
S_OK Stream contains recorded media. On return, pDuration contains duration of media.

IMultiMediaStream::GetEndOfStreamEventHandle

IMultiMediaStream Interface

Retrieves the handle for the event triggered when the stream completes playback.

Syntax

HRESULT GetEndOfStreamEventHandle(

  HANDLE *phEOS

  );

Parameters

phEOS
[out] Pointer to an event HANDLE returned by the current object when it completes playback. If no HANDLE is associated with the object, this value will be NULL.

Return Value

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

Remarks

The Microsoft® Win32® WaitForSingleObject and WaitForMultipleObjects functions use the retrieved handle to watch for completion of playback.

IMultiMediaStream::GetInformation

IMultiMediaStream Interface

Retrieves the capabilities of a media stream that matches the specified media type.

Syntax

HRESULT GetInformation(
  DWORD *pdwFlags,
  STREAM_TYPE *pStreamType

  );

Parameters

pdwFlags
[out] Pointer to a value that will contain a combination of one or more of the following flags. Can be NULL.

MMSSF_ASYNCHRONOUS The stream supports asynchronous sample updates. All implementations of IMultiMediaStream will support the asynchronous updates; this flag confirms it.
MMSSF_HASCLOCK The stream has a clock.
MMSSF_SUPPORTSEEK The stream supports seeking.

pStreamType
[out] Pointer to a STREAM_TYPE enumeration type that will contain the media type information for the derived media streams. Can be NULL.

Return Value

Returns an HRESULT value.

Remarks

A stream's capabilities include whether it has a clock, if it supports seeking, and whether it supports asynchronous updating.

IMultiMediaStream::GetMediaStream

IMultiMediaStream Interface

Retrieves a media stream that has the specified purpose ID.

Syntax

HRESULT GetMediaStream(
  REFMSPID idPurpose,
  IMediaStream **ppMediaStream

  );

Parameters

idPurpose
Value that specifies the desired stream.
ppMediaStream
Address of a pointer to an IMediaStream interface that will point to the desired media stream.

Return Value

Returns one of the following values.

E_POINTER The ppMediaStream pointer is invalid.
MS_E_NOSTREAM No stream has the specified purpose ID.
S_OK Success.

Remarks

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.

IMultiMediaStream::GetState

IMultiMediaStream Interface

Retrieves the multimedia stream's current state.

Syntax

HRESULT GetState(

  STREAM_STATE *pCurrentState

  );

Parameters

pCurrentState
[out] Pointer to the STREAM_STATE enumerated type that will contain the current multimedia stream's state.

Return Value

Returns S_OK if successful or E_POINTER if pCurrentState is invalid.

IMultiMediaStream::GetTime

IMultiMediaStream Interface

Retrieves the current time from the multimedia stream's clock, if it has a clock.

Syntax

HRESULT GetTime(

  STREAM_TIME *pCurrentTime

  );

Parameters

pCurrentTime
[out] Pointer to a STREAM_TIME value that will contain the current time, if the media stream has a clock.

Return Value

Returns one of the following values.

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.

Remarks

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.

IMultiMediaStream::Seek

IMultiMediaStream Interface

Sets the seek location of all contained media streams to the specified time.

Syntax

HRESULT Seek(
  STREAM_TIME SeekTime
  );

Parameters

SeekTime
[in] STREAM_TIME value that specifies the seek time.

Return Value

Returns one of the following values.

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.

Remarks

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 derived from the multimedia stream object.

IMultiMediaStream::SetState

IMultiMediaStream Interface

Sets the media stream to either a running or stopped state.

Syntax

HRESULT SetState(
  STREAM_STATE NewState
  );

Parameters

NewState
[in] A STREAM_STATE enumeration value that specifies the new media stream state.

Return Value

Returns S_OK.

Remarks

When you set the stream to STREAMSTATE_STOP, this method deletes all data still pending.

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.

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 return, this method sets pDuration to zero.
S_OK	Stream contains recorded media. On return, pDuration contains duration of media.

MMSSF_ASYNCHRONOUS	The stream supports asynchronous sample updates. All implementations of IMultiMediaStream will support the asynchronous updates; this flag confirms it.
MMSSF_HASCLOCK	The stream has a clock.
MMSSF_SUPPORTSEEK	The stream supports seeking.

E_POINTER	The ppMediaStream pointer is invalid.
MS_E_NOSTREAM	No stream has the specified purpose ID.
S_OK	Success.

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.

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.