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.
Implement this interface on the input pin of every filter. The CBaseInputPin class implements this interface.
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 Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMemInputPin methods Description GetAllocator Retrieves 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
Retrieves the allocator interface that this input pin proposes as the interface for the output pin to use.
Syntax
HRESULT GetAllocator(
IMemAllocator **ppAllocator
);
Parameters
- ppAllocator
- [out] Address of a pointer to the retrieved IMemAllocator object.
Return Value
Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
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
Optional method to suggest specific alignment or prefix requirements to an upstream filter.
Syntax
HRESULT GetAllocatorRequirements(
ALLOCATOR_PROPERTIES *pProps
);
Parameters
- pProps
- [in] Pointer to the ALLOCATOR_PROPERTIES structure containing the required size, count, and alignment of the allocator.
Return Value
Returns an HRESULT value. Returns E_NOTIMPL if not implemented.
Remarks
Source filters that insist on their own allocator can use this method downstream to accommodate downstream filters' memory requirements for performance benefits.
IMemInputPin::NotifyAllocator
Notifies the input pin as to which allocator the output pin is actually going to use.
Syntax
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 Value
Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
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
Receives the next block of data from the stream.
Syntax
HRESULT Receive(
IMediaSample *pSample
);
Parameters
- pSample
- [in] Pointer to a media sample.
Return Value
Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
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
Determines if the implementation of the IMemInputPin::Receive method might block on the connected output pin.
Syntax
HRESULT ReceiveCanBlock(void);
Return Value
Can return any HRESULT value. The following specific success values can be returned.
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
Retrieves the next block of data from the stream. This method behaves much like the IMemInputPin::Receive method, but it works with multiple samples.
Syntax
HRESULT ReceiveMultiple(
IMediaSample **pSamples,
long nSamples,
long *nSamplesProcessed
);
Parameters
- pSamples
- [in] Address of a pointer to an array of samples.
- nSamples
- [in] Number of samples to process.
- nSamplesProcessed
- [out] Pointer to the number of samples processed.
Return Value
Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
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 enables 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.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.