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

When to Implement

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.

When to Use

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

HRESULT AllocateSample(
  DWORD dwFlags,
  IStreamSample **ppSample
  )

Parameters
dwFlags
[in] Flags. Must be 0.
ppSample
[out] Pointer to the newly created stream sample's IStreamSample interface.
Return Values

Returns one of the following values.
Value Meaning
E_OUTOFMEMORY There isn't enough memory available to create a stream sample.
E_POINTER A parameter is invalid.
S_OK Success; ppSample points to the new sample's IStreamSample interface.

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.

HRESULT CreateSharedSample(
  IStreamSample* pExistingSample,
  DWORD dwFlags ,
  IStreamSample** ppNewSample
  )

Parameters
pExistingSample
[in] Pointer to the existing sample.
dwFlags
[in] Flags. Must be 0.
ppNewSample
[out] Address of a pointer to an IStreamSample interface that will point to the newly created shared sample.
Return Values

Returns one of the following values.
Value Meaning
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.

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 Values

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

Remarks

You can set either parameter to null on entry, to indicate that the information isn't needed.

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 other values may be defined by developers if necessary.

IMediaStream::GetMultiMediaStream

IMediaStream Interface

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

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 Values

Returns S_OK if successful or E_POINTER if ppMultiMediaStream is invalid.

Remarks

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

IMediaStream::SendEndOfStream

IMediaStream Interface

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

HRESULT SendEndOfStream(
  DWORD dwFlags
  )

Parameters
dwFlags
[in] Flags. Must be 0.
Return Values

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 the same format as a previous stream.

HRESULT SetSameFormat(
  IMediaStream *pStreamThatHasDesiredFormat,
  DWORD dwFlags
  );

Parameters
pStreamThatHasDesiredFormat
[in] Pointer to an IMediaStream which has the same format.
dwFlags
[in] Flags. Must be 0.
Return Values

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

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