IMFMediaStream::RequestSample method (mfidl.h)

Article
10/13/2021

Requests a sample from the media source.

Syntax

HRESULT RequestSample(
  [in] IUnknown *pToken
);

Parameters

[in] pToken

Pointer to the IUnknown interface to an object that is used as a token for the request. The caller must implement this object. This parameter can be NULL. See Remarks.

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_END_OF_STREAM	The end of the stream was reached.
MF_E_MEDIA_SOURCE_WRONGSTATE	The media source is stopped.
MF_E_SHUTDOWN	The source's Shutdown method has been called.

Remarks

If pToken is not NULL, the media stream calls AddRef on pToken and places the token in a first-in, first-out queue.

When the next sample is available, the media stream stream does the following:

Pulls the first token from the queue.
Sets the MFSampleExtension_Token attribute on the media sample. The attribute data is a pointer to the token object.
Sends an MEMediaSample event. The event data is a pointer to the media sample's IMFSample interface.
Calls Release on the token.

If the media stream cannot fulfill the caller's request for a sample, it simply releases the token object and skips steps 2 and 3.

The caller should monitor the reference count on the request token. If the media stream sends an MEMediaSample event, get the MFSampleExtension_Token attribute from the sample and match the attribute value against the token. If the token's reference count falls to zero and you did not receive an MEMediaSample event, it means that the request was dropped.

Because the Media Foundation pipeline is multithreaded, the source's RequestSample method might get called after the source has stopped. If the media source is stopped, the method should return MF_E_MEDIA_SOURCE_WRONGSTATE. The pipeline does not treat this return code as an error condition. If the source returns any other error code, the pipeline treats it as fatal error and halts the session.

Note Earlier versions of the documentation listed the wrong error code for this case.

If the media source is paused, the method succeeds, but the stream does not deliver the sample until the source is started again.

If a media source encounters an error asynchronously while processing data, it should signal the error in one of the following ways (but not both):

Return an error code from the next RequestSample call.
Send an MEError event.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	mfidl.h
Library	Mfuuid.lib