IMFSourceReader::ReadSample method (mfreadwrite.h)

Article
10/13/2021

Reads the next sample from the media source.

Syntax

HRESULT ReadSample(
  [in]  DWORD     dwStreamIndex,
  [in]  DWORD     dwControlFlags,
  [out] DWORD     *pdwActualStreamIndex,
  [out] DWORD     *pdwStreamFlags,
  [out] LONGLONG  *pllTimestamp,
  [out] IMFSample **ppSample
);

Parameters

[in] dwStreamIndex

The stream to pull data from. The value can be any of the following.

Value	Meaning
0–0xFFFFFFFB	The zero-based index of a stream.
MF_SOURCE_READER_FIRST_VIDEO_STREAM 0xFFFFFFFC	The first video stream.
MF_SOURCE_READER_FIRST_AUDIO_STREAM 0xFFFFFFFD	The first audio stream.
MF_SOURCE_READER_ANY_STREAM 0xFFFFFFFE	Get the next available sample, regardless of which stream.

[in] dwControlFlags

A bitwise OR of zero or more flags from the MF_SOURCE_READER_CONTROL_FLAG enumeration.

[out] pdwActualStreamIndex

Receives the zero-based index of the stream.

[out] pdwStreamFlags

Receives a bitwise OR of zero or more flags from the MF_SOURCE_READER_FLAG enumeration.

[out] pllTimestamp

Receives the time stamp of the sample, or the time of the stream event indicated in pdwStreamFlags. The time is given in 100-nanosecond units.

[out] ppSample

Receives a pointer to the IMFSample interface or the value NULL (see Remarks). If this parameter receives a non-NULL pointer, the caller must release the interface.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code	Description
S_OK	The method succeeded.
MF_E_INVALIDREQUEST	Invalid request.
MF_E_INVALIDSTREAMNUMBER	The dwStreamIndex parameter is invalid.
MF_E_NOTACCEPTING	A flush operation is pending. See IMFSourceReader::Flush.
E_INVALIDARG	Invalid argument. See Remarks.

Remarks

If the requested stream is not selected, the return code is MF_E_INVALIDREQUEST. See IMFSourceReader::SetStreamSelection.

This method can complete synchronously or asynchronously. If you provide a callback pointer when you create the source reader, the method is asynchronous. Otherwise, the method is synchronous. For more information about setting the callback pointer, see MF_SOURCE_READER_ASYNC_CALLBACK.

Asynchronous Mode

In asynchronous mode:

All of the [out] parameters must be NULL. Otherwise, the method returns E_INVALIDARG.
The method returns immediately.
When the operation completes, the application's IMFSourceReaderCallback::OnReadSample method is called.
If an error occurs, the method can fail either synchronously or asynchronously. Check the return value of ReadSample, and also check the hrStatus parameter of IMFSourceReaderCallback::OnReadSample.

Synchronous Mode

In synchronous mode:

The pdwStreamFlags and ppSample parameters cannot be NULL. Otherwise, the method returns E_POINTER.
The pdwActualStreamIndex and pllTimestamp parameters can be NULL.
The method blocks until the next sample is available.

In synchronous mode, if the dwStreamIndex parameter is MF_SOURCE_READER_ANY_STREAM, you should pass a non-NULL value for pdwActualStreamIndex, so that you know which stream delivered the sample.

This method can return flags in the pdwStreamFlags parameter without returning a media sample in ppSample. Therefore, the ppSample parameter can receive a NULL pointer even when the method succeeds. For example, when the source reader reaches the end of the stream, it returns the MF_SOURCE_READERF_ENDOFSTREAM flag in pdwStreamFlags and sets ppSample to NULL.

If there is a gap in the stream, pdwStreamFlags receives the MF_SOURCE_READERF_STREAMTICK flag, ppSample is NULL, and pllTimestamp indicates the time when the gap occurred.

This interface is available on Windows Vista if Platform Update Supplement for Windows Vista is installed.

Requirements

Requirement	Value
Minimum supported client	Windows 7, Windows Vista and Platform Update Supplement for Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 R2 [desktop apps \| UWP apps]
Target Platform	Windows
Header	mfreadwrite.h