IMemInputPin Interface

The IMemInputPin interface provides methods on an input pin to facilitate passing data and flush notifications from a connected output pin of an upstream filter.

When to Implement

Implement this interface on the input pin of every filter. The CBaseInputPin class implements this interface.

When to Use

A connected output pin uses this interface to retrieve an IMemAllocator interface, to pass media samples to the input pin, and to flush pending buffers downstream.

Methods in Vtable Order

IUnknown methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IMemInputPin methods	Description
GetAllocator	Returns the allocator interface that this input pin proposes as the interface for the output pin to use.
NotifyAllocator	Notifies the input pin as to which allocator the output pin is actually going to use.
GetAllocatorRequirements	Optional method to use if the filter has specific alignment or prefix requirements but could use an upstream allocator.
Receive	Receives the next block of data from the stream.
ReceiveMultiple	Receives the next block of data from the stream. This method behaves similarly to the IMemInputPin::Receive method, but it works with multiple samples.
ReceiveCanBlock	Determines if sending the IMemInputPin::Receive method might block.

---

IMemInputPin::GetAllocator

IMemInputPin Interface

Returns the allocator interface that this input pin proposes as the interface for the output pin to use.

HRESULT GetAllocator(
  IMemAllocator ** ppAllocator
  );

Parameters

ppAllocator

[out] Pointer to an obtained IMemAllocator object.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

---

IMemInputPin::GetAllocatorRequirements

IMemInputPin Interface

Optional method to suggest specific alignment or prefix requirements to an upstream filter.

HRESULT GetAllocatorRequirements(
  ALLOCATOR_PROPERTIES * pProps
  );

Parameters

pProps

[in] ALLOCATOR_PROPERTIES structure containing the required size, count, and alignment of the allocator.

Return Values

Returns an HRESULT value. Returns E_NOTIMPL if not implemented.

Remarks

Source filters that insist on their own allocator may use this method downstream to accommodate downstream filters' memory requirements for performance benefits.

---

IMemInputPin::NotifyAllocator

IMemInputPin Interface

Notifies the input pin as to which allocator the output pin is actually going to use.

HRESULT NotifyAllocator(
  IMemAllocator * pAllocator,
  BOOL bReadOnly
  );

Parameters

pAllocator

[in] Pointer to the IMemAllocator object to use. This might or might not be the same IMemAllocator object that the input pin provided in the IMemInputPin::GetAllocator method (the output pin could provide its own allocator).

bReadOnly

[out] Flag to indicate if the samples from this allocator are read-only.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

This method is called by the connecting output pin to notify the pin on which this interface is implemented of the allocator it chooses to use for transporting media samples. If the bReadOnly parameter is TRUE, all samples in the allocator are read-only and a copy must be made before modifying any of them.

---

IMemInputPin::Receive

IMemInputPin Interface

Receives the next block of data from the stream.

HRESULT Receive(
  IMediaSample * pSample
  );

Parameters

pSample

[in] Pointer to a media sample.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

This is a blocking synchronous call. Typically, no blocking occurs, but if a filter cannot process the sample immediately it may use the calling application's thread to wait until it can.

Use the IUnknown::AddRef method if you need to hold the returned data block beyond the completion of the IMemInputPin::Receive method. If you use AddRef, be sure to use IUnknown::Release when done with it.

---

IMemInputPin::ReceiveCanBlock

IMemInputPin Interface

Determines if the implementation of the IMemInputPin::Receive method might block on the connected output pin.

HRESULT ReceiveCanBlock(void);

Return Values

Can return any HRESULT value. The following specific success values can be returned.

Value	Meaning
S_FALSE	Input pin will not block on a Receive method.
S_OK	Input pin might block on a Receive method.

Remarks

An output pin from a filter might require notification if its thread might be blocked when it calls the Receive method on the connected input pin. For example, a source filter might prefer to keep reading and buffering data rather than to be blocked, and may choose to start another thread to wait on the blocking Receive method.

If your implementation of Receive calls a downstream filter's Receive method on the same thread, the application will block if that filter blocks, and this method must indicate that.

---

IMemInputPin::ReceiveMultiple

IMemInputPin Interface

Returns the next block of data from the stream. This method behaves much like the IMemInputPin::Receive method, but it works with multiple samples.

HRESULT ReceiveMultiple(
  IMediaSample ** pSamples,
  long nSamples,
  long * nSamplesProcessed
  );

Parameters

pSamples

[in] Pointer to an array of samples.

nSamples

[in] Number of samples to process.

nSamplesProcessed

[out] Number of samples processed.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

This method allows a connected output pin to deliver multiple samples at one time. Use it if, like COutputQueue, the output pin batches samples for delivery together. Implement this if your filter can handle batched samples more efficiently than individual samples. The base class implementation of this method simply calls IMemInputPin::Receive repeatedly. Override this implementation if you can do something more efficiently in your derived class.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page