IMFSourceReader::ReadSample Method

Reads the next sample from the media source.

Syntax

public:
HRESULT ReadSample(
         DWORD dwStreamIndex,
         DWORD dwControlFlags,
         DWORD *pdwActualStreamIndex,
         DWORD *pdwStreamFlags,
         LONGLONG *pllTimestamp,
         IMFSample **ppSample
)

Parameters

dwStreamIndex
Type: DWORD

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

dwControlFlags
Type: DWORD

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

pdwActualStreamIndex
Type: DWORD *

[out, optional] Receives the zero-based index of the stream.

pdwStreamFlags
Type: DWORD *

[out, optional] Receives a bitwise OR of zero or more flags from the MF_SOURCE_READER_FLAG enumeration.

pllTimestamp
Type: LONGLONG *

[out, optional] 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.

ppSample
Type: IMFSample **

[out, optional] 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

Type: HRESULT

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

Return codes

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.

Refer to Media Foundation return codes.

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

Header: Declared in mfreadwrite.h.