IMediaSample2 Interface

The IMediaSample2 interface derives from the IMediaSample interface. It enables you to set and to retrieve sample properties such as start and stop time that are defined in AM_SAMPLE2_PROPERTIES, and sample flags defined in the AM_SAMPLE_PROPERTY_FLAGS structure.

Implement this interface when you implement an allocator that creates media samples. The CMediaSample class in the Microsoft® DirectShow® class library implements this interface.

Use this interface when you want to retrieve properties from a media sample that are available through this interface and through the IMediaSample interface or if you want to retrieve multiple sample properties in one call.

Not all media samples will support IMediaSample2, so use the IUnknown::QueryInterface method to get a pointer to the sample's IMediaSample2 interface and check for failure.

If an allocator generates samples, then either all of the media samples must support IMediaSample2 or none of them will.

Methods in Vtable Order

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

IMediaSample methods Description
GetPointer Retrieves a read/write pointer to this buffer's memory.
GetSize Returns the size, in bytes, of the buffer data area.
GetTime Retrieves the stream times at which this sample should begin and finish.
SetTime Sets the stream times at which this sample should begin and finish.
IsSyncPoint Determines if the beginning of a sample is a synchronization point.
SetSyncPoint Sets the synchronization point.
IsPreroll Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed.
SetPreroll Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed.
GetActualDataLength Retrieves the data length of the sample.
SetActualDataLength Sets the data length of the sample.
GetMediaType Retrieves the media type of the sample.
SetMediaType Sets the media type of the sample.
IsDiscontinuity Indicates a discontinuity property. If S_OK is returned, sample is not contiguous with previous sample.
SetDiscontinuity Sets the discontinuity property. Set to TRUE if sample is new after a seek or dropped sample.
GetMediaTime Retrieves the media time stamps for the sample.
SetMediaTime Sets the media time stamps for the sample.

IMediaSample2 methods Description
GetProperties Retrieves the properties of a media sample.
SetProperties Sets the properties of a media sample.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IMediaSample methods	Description
GetPointer	Retrieves a read/write pointer to this buffer's memory.
GetSize	Returns the size, in bytes, of the buffer data area.
GetTime	Retrieves the stream times at which this sample should begin and finish.
SetTime	Sets the stream times at which this sample should begin and finish.
IsSyncPoint	Determines if the beginning of a sample is a synchronization point.
SetSyncPoint	Sets the synchronization point.
IsPreroll	Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed.
SetPreroll	Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed.
GetActualDataLength	Retrieves the data length of the sample.
SetActualDataLength	Sets the data length of the sample.
GetMediaType	Retrieves the media type of the sample.
SetMediaType	Sets the media type of the sample.
IsDiscontinuity	Indicates a discontinuity property. If S_OK is returned, sample is not contiguous with previous sample.
SetDiscontinuity	Sets the discontinuity property. Set to TRUE if sample is new after a seek or dropped sample.
GetMediaTime	Retrieves the media time stamps for the sample.
SetMediaTime	Sets the media time stamps for the sample.
IMediaSample2 methods	Description
GetProperties	Retrieves the properties of a media sample.
SetProperties	Sets the properties of a media sample.

IMediaSample2::GetProperties

IMediaSample2 Interface

Retrieves the properties of a media sample.

Syntax

HRESULT GetProperties(
    DWORD cbProperties,
    BYTE *pbProperties
    );

Parameters

cbProperties
[in] Length of property data to retrieve, in bytes.
pbProperties
[out] Pointer to a generic data buffer. The cbProperties parameter specifies the length of the data. This value can be NULL if cbProperties is NULL. Data conforms to the format of the AM_SAMPLE2_PROPERTIES structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default implementation returns S_OK.

Remarks

You can use this method to return only some of the sample properties by setting cbProperties to be less than the size of the AM_SAMPLE2_PROPERTIES structure.
For performance reasons, the pMediaType member returned in AM_SAMPLE2_PROPERTIES is merely a pointer to the data stored in the media sample. Therefore, the pointer will not necessarily be valid after the sample has been passed to another filter or after the Receive call to which it was passed has been completed. Also, you don't need to free the pointer as you do with the pointer returned from the IMediaSample::GetMediaType method.

IMediaSample2::SetProperties

IMediaSample2 Interface

Sets the properties of a media sample.

Syntax

HRESULT SetProperties(
    DWORD cbProperties,
    const BYTE *pbProperties
    );

Parameters

cbProperties
[in] Length of property data to set, in bytes.
pbProperties
[in] Pointer to properties to set. The cbProperties parameter specifies the length of the data. This value can be NULL if cbProperties is NULL. Data conforms to the format of the AM_SAMPLE2_PROPERTIES structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.