IMFSourceReader::ReadSample method (mfreadwrite.h)

Reads the next sample from the media source.


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


[in] dwStreamIndex

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

Value Meaning
The zero-based index of a stream.
The first video stream.
The first audio stream.
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
The method succeeded.
Invalid request.
The dwStreamIndex parameter is invalid.
A flush operation is pending. See IMFSourceReader::Flush.
Invalid argument. See 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.


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

See also


Source Reader