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. |
Returns the allocator interface that this input pin proposes as the interface for the output pin to use.
HRESULT GetAllocator(
IMemAllocator ** ppAllocator
);
Returns an HRESULT value.
Optional method to suggest specific alignment or prefix requirements to an upstream filter.
HRESULT GetAllocatorRequirements(
ALLOCATOR_PROPERTIES * pProps
);
Returns an HRESULT value. Returns E_NOTIMPL if not implemented.
Source filters that insist on their own allocator may use this method downstream to accommodate downstream filters' memory requirements for performance benefits.
Notifies the input pin as to which allocator the output pin is actually going to use.
HRESULT NotifyAllocator(
IMemAllocator * pAllocator,
BOOL bReadOnly
);
Returns an HRESULT value.
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.
Receives the next block of data from the stream.
HRESULT Receive(
IMediaSample * pSample
);
Returns an HRESULT value.
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.
Determines if the implementation of the IMemInputPin::Receive method might block on the connected output pin.
HRESULT ReceiveCanBlock(void);
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. |
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.
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
);
Returns an HRESULT value.
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.