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.

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

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.

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

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.

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 retrieved 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] Reserved for flag data. Must be zero.

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 a media stream object that has the same format.

dwFlags

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

Return Values

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

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

Top of Page