CMediaSample Class

This class represents a buffer object that supports the IMediaSample interface. It represents a buffer in memory, together with some associated properties stored as protected data members.

The constructor is passed as a pointer to the buffer with its length in bytes; other properties are normally set and accessed through implemented IMediaSample interface methods. These properties describe various attributes of the media sample, such as the sample's media type, start and end time, and options. The options can include whether the media sample is a sync point, a preroll sample, or discontinuous with other samples.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Protected Data Members

Name	Description
m_cbBuffer	Size of the buffer.
m_dwFlags	Sample property flags as follows:
	Sample_Discontinuity: Set if start of a new segment.
	Sample_MediaTimeValid: Set if the media time is valid.
	Sample_Preroll: Set if sample is a preroll sample.
	Sample_StopValid: Set if the stop time is valid.
	Sample_SyncPoint: Set if sample is a synchronization point.
	Sample_TimeValid: Set if the time is valid.
	Sample_TypeChanged: Set if the type has changed.
m_End	Sample end time.
m_lActual	Actual length of data in this sample.
m_MediaEnd	Media end (offset from m_MediaStart).
m_MediaStart	Media start position.
m_pAllocator	Pointer to the IMemAllocator object associated with this object.
m_pBuffer	Pointer to the complete buffer.
m_pMediaType	Pointer to a structure containing the media type of the sample.
m_pNext	Pointer to the next CMediaSample object in the free list.
m_Start	Sample start time.

Member Functions

Name	Description
CMediaSample	Constructs a CMediaSample object.
SetPointer	Sets the buffer pointer and length.

Implemented IUnknown Methods

Name	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

Implemented IMediaSample Methods

Name	Description
GetActualDataLength	Retrieves the data length of the sample.
GetMediaTime	Retrieves the media time extents of the sample.
GetMediaType	Retrieves the media type of the CMediaSample object.
GetPointer	Retrieves a read/write pointer to the memory of this buffer.
GetSize	Returns the size, in bytes, of the buffer data area.
GetTime	Sets the media time extents for this sample.
IsDiscontinuity	Determines if there is discontinuity in the data stream.
IsPreroll	Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed.
IsSyncPoint	Determines if the beginning of a sample is a synchronization point.
SetActualDataLength	Sets the data length of the sample.
SetDiscontinuity	Sets the discontinuity property.
SetMediaTime	Sets the media time of the CMediaSample object.
SetMediaType	Sets the media type of the CMediaSample object.
SetPreroll	Sets preroll property. If TRUE, this sample is for preroll only and should not be displayed.
SetSyncPoint	Sets sync-point property.
SetTime	Sets the stream time at which this sample should start and finish.

Implemented INonDelegatingUnknown Methods

Name	Description
NonDelegatingQueryInterface	Passes out pointers to any interfaces added to the derived filter class.

---

CMediaSample::AddRef

CMediaSample Class

Increments the reference count for the calling interface on an object.

ULONG AddRef(void);

Return Values

Returns an integer from 1 to n, the value of the new reference count.

Remarks

This member function implements the IUnknown::AddRef method.

---

CMediaSample::CMediaSample

CMediaSample Class

Constructs a CMediaSample object.

CMediaSample(
  TCHAR *pName,
  CBaseAllocator *pAllocator,
  HRESULT *phr,
  LPBYTE pBuffer = NULL,
  LONG length = 0
  );

Parameters

pName

Name of the media sample.

pAllocator

Pointer to the CBaseAllocator object used for memory allocation.

phr

Pointer to the general COM return value. Note that this value is changed only if this function fails.

pBuffer

Pointer to a memory buffer (to be allocated by the pAllocator parameter).

length

Length of the allocated memory buffer.

Return Values

No return value.

Remarks

The constructor creates an object with the buffer and buffer length set to that of the CBaseAllocator object to which it points.

---

CMediaSample::GetActualDataLength

CMediaSample Class

Retrieves the data length of the sample.

HRESULT GetActualDataLength(void);

Return Values

Returns the value of m_lActual by default.

Remarks

This member function implements the IMediaSample::GetActualDataLength method.

---

CMediaSample::GetMediaTime

CMediaSample Class

Retrieves the starting and ending media time.

HRESULT GetMediaTime(
  LONGLONG * pStart,
  LONGLONG * pEnd
  );

Parameters

pStart

Retrieved beginning media time.

pEnd

Retrieved ending media time.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::GetMediaTime method. It sets pStart to the current value of m_MediaStart and pEnd to the sum of m_MediaStart and m_MediaEnd. If the sample has not been set, this member function returns VFW_E_MEDIA_TIME_NOT_SET.

---

CMediaSample::GetMediaType

CMediaSample Class

Retrieves the media type of the CMediaSample object.

HRESULT GetMediaType(
  AM_MEDIA_TYPE ** ppMediaType
  );

Parameters

ppMediaType

Pointer to a pointer to the retrieved media type.

Return Values

Returns an HRESULT value. When a sample is received and there is no format change, this method returns S_FALSE.

Remarks

This member function implements the IMediaSample::GetMediaType method. The member function makes a copy of the AM_MEDIA_TYPE structure and creates a task memory block to maintain the reference. When you are done with the media type, free the memory block with the FreeMediaType utility function, and then free the entire media type with the Microsoft® Win32® CoTaskMemFree function.

---

CMediaSample::GetPointer

CMediaSample Class

Retrieves a read/write pointer to the buffer's memory.

HRESULT GetPointer(
  BYTE ** ppBuffer
  );

Parameters

ppBuffer

Retrieved pointer to the buffer.

Return Values

Returns VFW_E_BUFFER_NOTSET if CMediaSample::SetPointer was not called before calling this function, or NOERROR otherwise.

Remarks

This member function implements the IMediaSample::GetPointer method. GetPointer returns the value of m_pBuffer, set using CMediaSample::SetPointer.

---

CMediaSample::GetSize

CMediaSample Class

Retrieves the size, in bytes, of the buffer data area.

HRESULT GetSize(void);

Return Values

Returns the value of m_cbBuffer by default.

Remarks

This member function implements the IMediaSample::GetSize method.

---

CMediaSample::GetTime

CMediaSample Class

Retrieves the stream time at which this sample should begin and finish.

HRESULT GetTime(
  REFERENCE_TIME * pTimeStart,
  REFERENCE_TIME * pTimeEnd
  );

Parameters

pTimeStart

Retrieved beginning stream time.

pTimeEnd

Retrieved ending stream time.

Return Values

Returns VFW_E_SAMPLE_TIME_NOT_SET if this sample doesn't have valid timestamps, or NOERROR otherwise.

Remarks

This member function implements the IMediaSample::GetTime method. It sets pTimeStart to the current value of m_Start and pTimeEnd to the current value of m_End.

---

CMediaSample::IsDiscontinuity

CMediaSample Class

Determines if there is discontinuity in the data stream.

HRESULT IsDiscontinuity(void);

Return Values

Returns S_OK if the sample is a discontinuous sample and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

This member function implements the IMediaSample::IsDiscontinuity method. It returns the value of the m_dwFlags Sample_Discontinuity property flag. Discontinuity occurs when a source filter seeks to a different place in the stream or when a filter drops samples for quality control.

---

CMediaSample::IsPreroll

CMediaSample Class

Preroll property. If TRUE, this sample is for preroll only and should not be displayed.

HRESULT IsPreroll(void);

Return Values

Returns S_OK if the sample is a preroll sample and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

This member function implements the IMediaSample::IsPreroll method. It returns the value of the m_dwFlags Sample_Preroll property flag. Preroll samples are not meant to be rendered.

---

CMediaSample::IsSyncPoint

CMediaSample Class

Determines if the beginning of a sample is a synchronization point.

HRESULT IsSyncPoint(void);

Return Values

Returns S_OK if the sample is a synchronization point and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

This member function implements the IMediaSample::IsSyncPoint method. It returns the value of the m_dwFlags Sample_SyncPoint property flag. If the bTemporalCompression member of the AM_MEDIA_TYPE structure is FALSE, all samples are synchronization points. A filter can begin a stream at any synchronization point.

---

CMediaSample::NonDelegatingQueryInterface

CMediaSample Class

Retrieves an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void ** ppv
  );

Parameters

riid

Reference identifier.

ppv

Pointer to the interface.

Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IMediaSample and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

---

CMediaSample::QueryInterface

CMediaSample Class

Retrieves a pointer to a specified interface on a component to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.

HRESULT QueryInterface(
  REFIID iid,
  void ** ppvObject
  );

Parameters

iid

Specifies the IID of the interface being requested.

ppvObject

Receives a pointer to an interface pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.

Return Values

Returns S_OK if the interface is supported, S_FALSE if not.

Remarks

This member function implements the IUnknown::QueryInterface method.

---

CMediaSample::Release

CMediaSample Class

Decrements the reference count for the calling interface on an object. If the reference count on the object falls to zero, the object is freed from memory.

ULONG Release(void);

Return Values

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.

Remarks

This member function implements the IUnknown::Release method.

---

CMediaSample::SetActualDataLength

CMediaSample Class

Sets the data length of the sample.

HRESULT SetActualDataLength(
  long lLen
  );

Parameters

lLen

Length of the data in the media sample, in bytes.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetActualDataLength method. It sets the value of m_lActual to the value of lLen.

---

CMediaSample::SetDiscontinuity

CMediaSample Class

Sets the discontinuity property.

HRESULT SetDiscontinuity(
  BOOL bDiscont
  );

Parameters

bDiscont

Set to TRUE to specify the media sample as discontinuous with the previous sample.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetDiscontinuity method. It sets the value of the m_dwFlags Sample_Discontinuity flag to the value of bDiscont. Discontinuous samples occur when a source filter seeks to a different place in the media stream or when a filter drops samples for quality control.

---

CMediaSample::SetMediaTime

CMediaSample Class

Sets the starting and ending media times.

HRESULT SetMediaTime(
  LONGLONG * pStart,
  LONGLONG * pEnd
  );

Parameters

pStart

Beginning media time.

pEnd

Ending media time.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetMediaTime method. It sets the m_MediaStart data member to the value of pStart and the m_MediaEnd data member to the value of pEnd minus pStart.

---

CMediaSample::SetMediaType

CMediaSample Class

Sets the media type for the CMediaSample object.

HRESULT SetMediaType(
  AM_MEDIA_TYPE * pMediaType
  );

Parameters

pMediaType

Pointer to a pointer to a media type structure to be set.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetMediaType method. It deletes the previous media type if one exists, makes a copy of the media type passed in, sets m_pMediaType to the copy of the media type, and sets the value of the m_dwFlags Sample_TypeChanged flag to TRUE.

---

CMediaSample::SetPointer

CMediaSample Class

Sets the buffer pointer and length.

SetPointer(
  BYTE * ptr,
  LONG cBytes
  );

Parameters

ptr

Pointer to a buffer.

cBytes

Length of the buffer, in bytes.

Return Values

No return value.

Remarks

Allocators that require variable-sized pointers or pointers into data that has already been read use this member function. This is available only through a CMediaSample class, not an IMediaSample interface, so only the filter that owns the allocator knows how to access this member function (not any filter or pin that is passed the object's IMediaSample interface pointer).

---

CMediaSample::SetPreroll

CMediaSample Class

Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed.

HRESULT SetPreroll(
  BOOL bIsPreroll
  );

Parameters

bIsPreroll

Set to TRUE to specify the media sample as a preroll sample, or FALSE otherwise.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetPreroll method. It sets the value of the m_dwFlags Sample_Preroll flag to the value of bIsPreroll. Preroll samples are samples that are processed but not displayed, and are located in the media stream before the displayable samples.

---

CMediaSample::SetSyncPoint

CMediaSample Class

Property of a synchronization point.

HRESULT SetSyncPoint(
  BOOL bIsSyncPoint
  );

Parameters

bIsSyncPoint

Value specifying whether the synchronization point was set.

Return Values

Returns S_OK.

Remarks

This member function implements the IMediaSample::SetSyncPoint method. It sets the value of the m_dwFlags Sample_SyncPoint flag to the value of bIsSyncPoint. A filter can begin a stream at any synchronization point.

---

CMediaSample::SetTime

CMediaSample Class

Sets the media time extents for this sample.

HRESULT SetTime(
  REFERENCE_TIME * pTimeStart,
  REFERENCE_TIME * pTimeEnd
  );

Parameters

pTimeStart

Stream time at which the sample begins.

pTimeEnd

Stream time at which the sample ends.

Return Values

Returns NOERROR or an HRESULT value.

Remarks

This member function implements the IMediaSample::SetTime method. It sets the m_Start data member to the value of pTimeStart and the m_End data member to the value of pTimeEnd.

If pTimeStart and pTimeEnd are null, DirectShow turns off the m_dwFlags data member's Sample_TimeValid and Sample_StopValid bits.

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

Top of Page