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

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