IMultiMediaStream Interface


		Index Topic Contents
	Previous Topic: Multimedia Streaming Reference Next Topic: IMediaStream Interface

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.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.
Top of Page

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.

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.

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.