IMFSourceReader::ReadSample method

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

dwStreamIndex [in]

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

ValueMeaning
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.

 

dwControlFlags [in]

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

pdwActualStreamIndex [out]

Receives the zero-based index of the stream.

pdwStreamFlags [out]

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

pllTimestamp [out]

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

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 codeDescription
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

Minimum supported client

Windows 7, Windows Vista and Platform Update Supplement for Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 [desktop apps | Windows Store apps]

Header

Mfreadwrite.h

See also

Source Reader
IMFSourceReader

 

 

Community Additions

ADD
Show:
© 2014 Microsoft