IMediaStream Interface

The IMediaStream interface provides access to the characteristics of a media stream, such as the stream's media type and purpose ID. It also has methods that create data samples.

For sample code that implements the multimedia streaming interfaces, see Multimedia Streaming Sample Code.

Implement this interface when you want to add media type-specific functionality to your media stream. This interface is implemented on multimedia stream objects. IMediaStream provides generic sample-creation methods, but you usually want to write a more powerful version of these methods that will take advantage of your media type's specific characteristics.

Use this interface when your application needs to access a stream's media type information and create data samples.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IMediaStream methods Description

GetMultiMediaStream Retrieves a pointer to the multimedia stream that contains the specified media stream.
GetInformation Retrieves the stream's purpose ID and media type.
SetSameFormat Sets the media stream to the same format as a previous stream.
AllocateSample Allocates a new stream sample object for the current media stream.
CreateSharedSample Creates a new stream sample that shares the same backing object as the existing sample.
SendEndOfStream Forces the current stream to end. If the current stream isn't writable, this method does nothing.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IMediaStream methods	Description
GetMultiMediaStream	Retrieves a pointer to the multimedia stream that contains the specified media stream.
GetInformation	Retrieves the stream's purpose ID and media type.
SetSameFormat	Sets the media stream to the same format as a previous stream.
AllocateSample	Allocates a new stream sample object for the current media stream.
CreateSharedSample	Creates a new stream sample that shares the same backing object as the existing sample.
SendEndOfStream	Forces the current stream to end. If the current stream isn't writable, this method does nothing.

IMediaStream::AllocateSample

IMediaStream Interface

Allocates a new stream sample object for the current media stream.

Syntax

HRESULT AllocateSample(
  DWORD dwFlags,
  IStreamSample **ppSample
  );

Parameters

dwFlags
[in] Flags. Must be zero.
ppSample
[out] Address of a pointer to the newly created stream sample's IStreamSample interface.

Return Value

Returns one of the following values.

E_OUTOFMEMORY There isn't enough memory available to create a stream sample.
E_POINTER A parameter is invalid.
S_OK Success.

Remarks

This method allocates the sample and its associated backing object or buffer. The backing object is either the DirectDraw surface for video or the IAudioData object for audio.

IMediaStream::CreateSharedSample

IMediaStream Interface

Creates a new stream sample that shares the same backing object as the existing sample.

Syntax

HRESULT CreateSharedSample(

  IStreamSample *pExistingSample,

  DWORD dwFlags ,

  IStreamSample **ppNewSample

  );

Parameters

pExistingSample
[in] Pointer to the existing sample.
dwFlags
[in] Reserved for flag data. Must be zero.
ppNewSample
[out] Address of a pointer to an IStreamSample interface that will point to the newly created shared sample.

Return Value

Returns one of the following values.

E_OUTOFMEMORY There isn't enough memory available to create the sample.
E_POINTER One of the parameters is invalid.
MS_E_INCOMPATIBLE The existing sample isn't compatible with the specified media stream.
S_OK Success; ppNewSample points to the newly created sample.

Remarks

This method calls IUnknown::QueryInterface on the existing sample to retrieve the media type-specific information, which it uses to create the shared sample.

IMediaStream::GetInformation

IMediaStream Interface

Retrieves the stream's purpose ID and media type.

Syntax

HRESULT GetInformation(

  MSPID *pPurposeId,

  STREAM_TYPE *pType

  );

Parameters

pPurposeId
[out] Pointer to an MSPID value that will contain the stream's purpose ID. If this parameter is NULL on entry, the method won't retrieve the purpose ID.
pType
[out] Pointer to a STREAM_TYPE enumerated data type value that will contain the stream's media type. If this parameter is NULL on entry, the method won't retrieve the media type.

Return Value

Returns S_OK if successful or E_POINTER if one of the parameters is invalid.

Remarks

The value retrieved in the pPurposeId parameter will usually be either MSPID_PrimaryVideo, which identifies the primary video stream, or MSPID_PrimaryAudio, which identifies the primary audio stream; however, you can define other values if necessary.

IMediaStream::GetMultiMediaStream

IMediaStream Interface

Retrieves a pointer to the multimedia stream that contains the specified media stream.

Syntax

HRESULT GetMultiMediaStream(

  IMultiMediaStream **ppMultiMediaStream

  );

Parameters

ppMultiMediaStream
[out] Address of a pointer to an IMultiMediaStream interface object that will point to the multimedia stream from which the current media stream was created.

Return Value

Returns S_OK if successful or E_POINTER if ppMultiMediaStream is invalid.

Remarks

This method increments the reference count of the retrieved object pointer.

IMediaStream::SendEndOfStream

IMediaStream Interface

Forces the current stream to end. If the current stream isn't writable, this method does nothing.

Syntax

HRESULT SendEndOfStream(

  DWORD dwFlags

  );

Parameters

dwFlags
[in] Reserved for flag data. Must be zero.

Return Value

Returns S_OK if successful or MS_E_INCOMPATIBLE if the existing sample isn't compatible with the current media stream.

Remarks

Applications do not call this internal method.

IMediaStream::SetSameFormat

IMediaStream Interface

Sets the media stream to the same format as a previous stream.

Syntax

HRESULT SetSameFormat(

  IMediaStream *pStreamThatHasDesiredFormat,

  DWORD dwFlags

  );

Parameters

pStreamThatHasDesiredFormat
[in] Pointer to a media stream object that has the same format.
dwFlags
[in] Reserved for flag data. Must be zero.

Return Value

Returns S_OK if successful or E_POINTER if one of the parameters is invalid.

E_OUTOFMEMORY	There isn't enough memory available to create a stream sample.
E_POINTER	A parameter is invalid.
S_OK	Success.