## 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 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 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.

###

IMultiMediaStream::EnumMediaStreams

IMultiMediaStream Interface

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

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 Values

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.

##### 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.

HRESULT GetDuration(
STREAM_TIME *pDuration
)

##### Parameters

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

##### Return Values

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 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.

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 Values

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.

HRESULT GetInformation(
DWORD *pdwFlags,
STREAM_TYPE *pStreamType
);

##### Parameters

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

  Value | Meaning
  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 Values

Returns S_OK if successful.

##### 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.

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 Values

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.

##### 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.

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 Values

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.

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 Values

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.

##### 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.

HRESULT Seek(
STREAM_TIME SeekTime
)

##### Parameters

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

##### Return Values

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.

##### 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.

HRESULT SetState(
STREAM_STATE NewState
)

##### Parameters

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

##### Return Values

Returns S_OK.

##### Remarks

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

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.