Share via

CBaseInputPin::Receive

  • Article
 
Microsoft DirectShow 9.0

CBaseInputPin::Receive

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.

Value 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:

  1. 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.
  2. Retrieves the sample properties and checks whether the format has changed (see below).
  3. If the format has changed, the method calls the CBasePin::CheckMediaType method to determine whether the new format is acceptable.
  4. If the new format is not acceptable, the method calls the CBasePin::EndOfStream method, posts an EC_ERRORABORT event, and returns an error code.
  5. 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

**  Header:** Declared in Amfilter.h; include Streams.h.

**  Library:** Use Strmbase.lib (retail builds) or Strmbasd.lib (debug builds).

See Also