CBaseInputPin.Receive method

Article
07/27/2023

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The Receive method receives the next media sample in the stream. This method implements the IMemInputPin::Receive method.

Syntax

HRESULT Receive(
   IMediaSample *pSample
);

Parameters

pSample: Pointer to the sample's IMediaSample interface.

Return value

Returns an HRESULT value. Possible values include those listed in the following table.

Return code	Description
S_OK	Success.
S_FALSE	Pin is currently flushing; sample was rejected.
E_POINTER	NULL pointer argument.
VFW_E_INVALIDMEDIATYPE	Invalid media type.
VFW_E_RUNTIME_ERROR	A run-time error occurred.
VFW_E_WRONG_STATE	The pin is stopped.

Remarks

The upstream output pin calls this method to deliver a sample to the input pin. The input pin must do one of the following:

Process the sample before returning.
Return, and process the sample in a worker thread.
Reject the sample.

If the pin uses a worker thread to process the sample, add a reference count to the sample inside this method. After the method returns, the upstream pin releases the sample. When the sample's reference count reaches zero, the sample returns to the allocator for re-use.

This method is synchronous and can block. If the method might block, the pin's CBaseInputPin::ReceiveCanBlock method should return S_OK.

In the base class, this method performs the following steps:

Calls the CBaseInputPin::CheckStreaming method to verify that the pin can process samples now. If it cannot for example, if the pin is stopped the method fails.
Retrieves the sample properties and checks whether the format has changed (see below).
If the format has changed, the method calls the CBasePin::CheckMediaType method to determine whether the new format is acceptable.
If the new format is not acceptable, the method calls the CBasePin::EndOfStream method, posts an EC_ERRORABORT event, and returns an error code.
Assuming there were no errors, the method returns S_OK.

Test for a format change as follows:

If the sample supports the IMediaSample2 interface, check the dwSampleFlags member of the AM_SAMPLE2_PROPERTIES structure. If the AM_SAMPLE_TYPECHANGED flag is present, the format has changed.
Otherwise, if the sample does not support IMediaSample2, call the IMediaSample::GetMediaType method. If the method returns a non-NULL value, the format has changed.

In the base class, this method does not process the sample. The derived class must override this method to perform the processing. (What this entails depends entirely on the filter.) The derived class should call the base-class method, to check for the errors described previously.

Requirements

Requirement	Value
Header	Amfilter.h (include Streams.h)
Library	Strmbase.lib (retail builds); Strmbasd.lib (debug builds)