IMediaSample Interface

The IMediaSample interface provides shared memory buffer functionality, holds some properties about the data, and holds a pointer to the data itself. It is used by connected pins to transport media samples from one pin to another.

The IMediaSample2 interface extends the functionality of this interface to allow you to set and to retrieve media sample properties.

When to Implement

Implement this interface if you are providing an allocator (buffer) to be used for transporting media samples between filters. This interface is implemented by the CMediaSample class in the DirectShow™ class library.

When to Use

Filters use methods on this interface to set properties and pass data to another filter. Downstream filters use methods on this interface to read the media sample's data and properties. Filters can modify the data in a media sample in place or can make a copy of the sample, modify the copy, and pass it on.

Methods in Vtable Order

IUnknown methods	Description
QueryInterface	Returns 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.

---

IMediaSample::GetActualDataLength

IMediaSample Interface

Retrieves the data length of the sample.

HRESULT GetActualDataLength(void);

Return Values

Returns an HRESULT value that is the length.

Remarks

Note that although this is typed as returning an HRESULT value, it actually returns the length in bytes, not an error value.

---

IMediaSample::GetMediaTime

IMediaSample Interface

Retrieves the media time stamps for this sample.

HRESULT GetMediaTime(
  LONGLONG * pTimeStart,
  LONGLONG * pTimeEnd
  );

Parameters

pTimeStart

[out] Retrieved beginning media time.

pTimeEnd

[out] Retrieved ending media time.

Return Values

Returns NOERROR if the sample contains valid time stamps. Returns VFW_E_MEDIA_TIME_NOT_SET if the time has not been set in the sample.

---

IMediaSample::GetMediaType

IMediaSample Interface

Retrieves the media type of the IMediaSample object.

HRESULT GetMediaType(
  AM_MEDIA_TYPE ** ppMediaType
  );

Parameters

ppMediaType

[in] 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 method allows for limited in-band format changes. Free the format block with FreeMediaType, and then free the entire media type with the Microsoft® Win32® CoTaskMemFree function.

---

IMediaSample::GetPointer

IMediaSample Interface

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

HRESULT GetPointer(
  BYTE ** ppBuffer
  );

Parameters

ppBuffer

[out] Retrieved pointer to the buffer.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

---

IMediaSample::GetSize

IMediaSample Interface

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

HRESULT GetSize(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

Note that although this is typed as returning an HRESULT value, it actually returns the length in bytes, not an error value.

---

IMediaSample::GetTime

IMediaSample Interface

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

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

Parameters

pTimeStart

[out] Retrieved beginning stream time.

pTimeEnd

[out] Retrieved ending stream time.

Return Values

Returns NOERROR if the sample contains valid time stamps. Returns VFW_E_MEDIA_TIME_NOT_SET if the time has not been set in the sample.

---

IMediaSample::IsDiscontinuity

IMediaSample Interface

Determines if there is discontinuity in the data stream.

HRESULT IsDiscontinuity(void);

Return Values

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

Remarks

Discontinuity occurs when a source filter seeks to a different place in the stream or when a filter drops samples for quality control.

Note that while calling SetDiscontinuity with a value of TRUE (1) sets the discontinuity property, calling IsDiscontinuity on a discontinuous sample returns S_OK (0).

---

IMediaSample::IsPreroll

IMediaSample Interface

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, or S_FALSE if not; otherwise, returns an HRESULT error value. Note that while calling SetPreroll with a value of TRUE (1) sets the preroll property, calling IsPreroll on a preroll sample returns S_OK (0).

---

IMediaSample::IsSyncPoint

IMediaSample Interface

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

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.

Note that while calling SetSyncPoint with a value of TRUE (1) sets the synchronization point, calling IsSyncPoint on a synchronization point sample returns S_OK (0).

---

IMediaSample::SetActualDataLength

IMediaSample Interface

Sets the sample's data length.

HRESULT SetActualDataLength(
  long lLen
  );

Parameters

lLen

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

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

---

IMediaSample::SetDiscontinuity

IMediaSample Interface

Sets the discontinuity property.

HRESULT SetDiscontinuity(
  BOOL bIsDiscontinuity
  );

Parameters

bIsDiscontinuity

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

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

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.

Note that while calling SetDiscontinuity with a value of TRUE (1) sets the discontinuity property, calling IsDiscontinuity on a discontinuous sample returns S_OK (0).

---

IMediaSample::SetMediaTime

IMediaSample Interface

Sets the media time stamps for this sample.

HRESULT SetMediaTime(
  LONGLONG * pTimeStart,
  LONGLONG * pTimeEnd
  );

Parameters

pTimeStart

[in] Beginning media time.

pTimeEnd

[in] Ending media time.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

To reset the time, use this method with both pTimeStart and pTimeEnd set to NULL. This will cause IMediaSample::GetMediaTime to return an error.

---

IMediaSample::SetMediaType

IMediaSample Interface

Sets the media type for the IMediaSample 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 that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

This method allows for limited in-band format changes.

---

IMediaSample::SetPreroll

IMediaSample Interface

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; otherwise, set to FALSE.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

Preroll samples are samples that are processed but not displayed, and are located in the media stream before the displayable samples.

Note that while calling SetPreroll with a value of TRUE (1) sets the preroll property, calling IsPreroll on a preroll sample returns S_OK (0).

---

IMediaSample::SetSyncPoint

IMediaSample Interface

Property of a synchronization point.

HRESULT SetSyncPoint(
  BOOL bIsSyncPoint
  );

Parameters

bIsSyncPoint

[in] Set to TRUE to specify the sample as a synchronization point; otherwise, set to FALSE.

Return Values

Returns S_OK.

Remarks

A filter can begin a stream at any synchronization point. Note that while calling SetSyncPoint with a value of TRUE (1) sets the synchronization point, calling IsSyncPoint on a synchronization point sample returns S_OK (0).

---

IMediaSample::SetTime

IMediaSample Interface

Sets the stream time when this sample should begin and finish.

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

Parameters

pTimeStart

[in] Stream time at which the sample begins.

pTimeEnd

[in] Stream time at which the sample ends.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

To reset the time, use this method with both pTimeStart and pTimeEnd set to NULL. This will cause IMediaSample::GetTime to return VFW_S_NO_STOP_TIME.

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

Top of Page