Microsoft DirectX 8.0

CBaseInputPin Class

CBaseInputPin class hierarchy

Abstract base class that implements an input pin.

Declaration: Amfilter.h

This class adds support for the IMemInputPin interface, in addition to the IPin interface support provided by CBasePin.

To use this class, derive a new class and override at least the following methods:

Protected Member Variables
m_pAllocatorPointer to the memory allocator.
m_bReadOnlyFlag that indicates whether the allocator produces read-only media samples.
m_bFlushingFlag that indicates whether the pin is currently flushing.
m_SamplePropsProperties of the most recent sample.
Public Methods
CBaseInputPinConstructor method.
~CBaseInputPinDestructor method.
BreakConnectReleases the pin from a connection.
IsReadOnlyQueries whether the allocator uses read-only media samples.
IsFlushingQueries whether the filter is currently flushing.
CheckStreamingDetermines whether the pin can accept samples. Virtual.
PassNotifyPasses a quality-control message to the appropriate object.
InactiveNotifies the pin that the filter is no longer active. Virtual.
SamplePropsRetrieves the properties of the most recent sample.
IPin Methods
BeginFlushBegins a flush operation.
EndFlushEnds a flush operation.
IMemInputPin Methods
GetAllocatorRetrieves the memory allocator proposed by this pin.
NotifyAllocatorSpecifies an allocator for the connection.
GetAllocatorRequirementsRetrieves the allocator properties requested by the input pin.
ReceiveReceives the next media sample in the stream.
ReceiveMultipleReceives multiple samples in the stream.
ReceiveCanBlockDetermines whether calls to the Receive method might block.
IQualityControl Methods
NotifyReceives a quality-control message.

CBaseInputPin.m_pAllocator

CBaseInputPin Class

Pointer to the memory allocator.

Syntax

IMemAllocator *m_pAllocator;

CBaseInputPin.m_bReadOnly

CBaseInputPin Class

Flag that indicates whether the allocator produces read-only media samples. If TRUE, the allocator produces read-only samples.

Syntax

BYTE m_bReadOnly;

CBaseInputPin.m_bFlushing

CBaseInputPin Class

Flag that indicates whether the pin is currently flushing. If TRUE, the pin is flushing.

Syntax

BYTE m_bFlushing;

CBaseInputPin.m_SampleProps

CBaseInputPin Class

Properties of the most recent sample.

Syntax

AM_SAMPLE2_PROPERTIES m_SampleProps;

CBaseInputPin::BeginFlush

CBaseInputPin Class

Begins a flush operation. Implements the IPin::BeginFlush method.

Syntax

HRESULT BeginFlush(void);

Return Value

Returns S_OK.

Remarks

This method sets the m_bFlushing flag to TRUE, which causes the Receive method to reject any more samples.

The derived class must override this method and perform the following steps:

  1. Call the IPin::BeginFlush method on downstream input pins. If the pin has not yet delivered any media samples downstream, you can skip this step. If your output pins derive from the CBaseOutputPin class, you can call the CBaseOutputPin::DeliverBeginFlush method.
  2. Call the base class method.
  3. Begin discarding queued data.
  4. Return from any blocked calls to the Receive method.

CBaseInputPin::BreakConnect

CBaseInputPin Class

Releases the pin from a connection.

Syntax

HRESULT BreakConnect(void);

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

This method overrides the CBasePin::BreakConnect method. It decommits the allocator and releases the IMemAllocator interface.

If you override this method, call the base-class method from your overriding method. Otherwise, you might cause memory leaks.

CBaseInputPin::CBaseInputPin

CBaseInputPin Class

Constructor method.

Syntax

CBaseInputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pPinName
);

Parameters

pObjectName
String containing the debug name of the object. For more information, see CBaseObject.
pFilter
Pointer to the filter that created this pin.
pLock
Pointer to a CCritSec lock, used to serialize state changes. This can be the same critical section as the filter lock, CBaseFilter.m_pLock.
phr
Pointer to a variable that receives an HRESULT value indicating the success or failure of the method.
pPinName
Unicode™ string containing the pin name (also used as the pin identifier).

Remarks

All of the parameters are passed directly to the CBasePin constructor.

CBaseInputPin::~CBaseInputPin

CBaseInputPin Class

Destructor method.

Syntax

~CBaseInputPin(void);

CBaseInputPin::CheckStreaming

CBaseInputPin Class

Determines whether the pin can accept samples.

Syntax

virtual HRESULT CheckStreaming(void);

Return Value

Returns one of the HRESULT values listed in the following table.

S_OKSuccess.
S_FALSEPin is currently flushing.
VFW_E_RUNTIME_ERRORA run-time error occurred.
VFW_E_WRONG_STATEThe pin is stopped.

Remarks

The derived class can override this method to perform further checks. In the overriding method, also call the base class implementation.

The CBasePin::Receive method calls this method. You should override the CBasePin::EndOfStream method to call this method as well.

CBaseInputPin::EndFlush

CBaseInputPin Class

Ends a flush operation. Implements the IPin::EndFlush method.

Syntax

HRESULT EndFlush(void);

Return Value

Returns S_OK.

Remarks

This method sets the m_bFlushing flag to TRUE, which enables the Receive method to accept samples.

The derived class must override this method and perform the following steps:

  1. Free any buffered data and wait for all queued samples to be discarded.
  2. Clear any pending EC_COMPLETE notifications.
  3. Call the base class method.
  4. Call IPin::EndFlush on downstream input pins. If the pin has not yet delivered any media samples downstream, you can skip this step. If your output pins derive from the CBaseOutputPin class, you can call the CBaseOutputPin::DeliverEndFlush method.

CBaseInputPin::GetAllocator

CBaseInputPin Class

Retrieves the memory allocator proposed by this pin. Implements the IMemInputPin::GetAllocator method.

Syntax

HRESULT GetAllocator(
    IMemAllocator **ppAllocator
);

Parameters

ppAllocator
Address of a variable that receives a pointer to the allocator's IMemAllocator interface.

Return Value

Returns S_OK if successful, or an error code from the CoCreateInstance function.

Remarks

This method creates a CMemAllocator object. Override this method if your filter uses an allocator from a downstream pin, or a custom allocator.

If the method succeeds, the IMemAllocator interface has an outstanding reference count. Be sure to release it when you are done.

CBaseInputPin::GetAllocatorRequirements

CBaseInputPin Class

Retrieves the allocator properties requested by the input pin.

Syntax

HRESULT GetAllocatorRequirements(
    ALLOCATOR_PROPERTIES *pProps
);

Parameters

pProps
Pointer to an ALLOCATOR_PROPERTIES structure, which is filled in with the requirements.

Return Value

Returns E_NOTIMPL.

Remarks

When an output pin initializes a memory allocator, it can call this method to determine whether the input pin has any buffer requirements. For more information, see CBaseOutputPin::DecideAllocator.

Implementing this method is optional. If the filter has specific alignment or prefix requirements, override this method.

CBaseInputPin::Inactive

CBaseInputPin Class

Notifies the pin that the filter is no longer active.

Syntax

HRESULT Inactive(void);

Return Value

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

S_OKSuccess.
VFW_E_NO_ALLOCATORNo memory allocator is available.

Remarks

This method overrides the CBasePin::Inactive method. It calls the IMemAllocator::Decommit method to decommit the memory allocator.

If you override this method, call the base-class method from your overriding method.

CBaseInputPin::IsFlushing

CBaseInputPin Class

Queries whether the filter is currently flushing.

Syntax

BOOL IsFlushing(void);

Return Value

Returns the m_bFlushing member variable.

CBaseInputPin::IsReadOnly

CBaseInputPin Class

Queries whether the allocator uses read-only media samples.

Syntax

BOOL IsReadOnly(void);

Return Value

Returns the m_bReadOnly member variable.

CBaseInputPin::Notify

CBaseInputPin Class

Notifies the pin that a quality change is requested. Implements the IQualityControl::Notify method.

Syntax

HRESULT Notify(
    IBaseFilter *pSelf,
    Quality q
);

Parameters

pSelf
Pointer to the filter that is sending the quality-control message.
q
Quality structure that contains the quality-control message.

Return Value

Returns S_OK.

Remarks

Filters usually pass quality-control messages to an upstream output pin, not to an input pin. Therefore, this method returns S_OK without doing anything.

For more information, see Quality-Control Management.

CBaseInputPin::NotifyAllocator

CBaseInputPin Class

Specifies an allocator for the connection. Implements the IMemInputPin::NotifyAllocator method.

Syntax

HRESULT NotifyAllocator(
    IMemAllocator *pAllocator,
    BOOL bReadOnly
);

Parameters

pAllocator
Pointer to the allocator's IMemAllocator interface.
bReadOnly
Flag that specifies whether samples from this allocator are read-only. If TRUE, samples are read-only.

Return Value

Returns S_OK.

Remarks

During the pin connection, the output pin chooses an allocator and calls this method to notify the input pin. The output pin can use the allocator that the input pin proposed in the IMemInputPin::GetAllocator method, or it can provide its own allocator.

CBaseInputPin::PassNotify

CBaseInputPin Class

Passes a quality-control message to the appropriate object.

Syntax

HRESULT PassNotify(
    Quality q
);

Parameters

q
Quality structure that contains the quality-control message.

Return Value

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

S_OKSuccess.
VFW_E_NOT_FOUNDCould not find an object to accept the message.

Remarks

Call this method if the filter does not handle quality-control messages. This method passes the message to one of the following objects, in order of preference:

For more information, see Quality-Control Management.

CBaseInputPin::Receive

CBaseInputPin Class

Receives the next media sample in the stream. 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.

S_OKSuccess.
S_FALSEPin is currently flushing; sample was rejected.
E_POINTERNULL pointer argument.
VFW_E_INVALIDMEDIATYPEInvalid media type.
VFW_E_RUNTIME_ERRORA run-time error occurred.
VFW_E_WRONG_STATEThe 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:

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 ReceiveCanBlock method should return S_OK.

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

  1. Calls the 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:

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.

CBaseInputPin::ReceiveCanBlock

CBaseInputPin Class

Determines whether calls to the IMemInputPin::Receive method might block. Implements the IMemInputPin::ReceiveCanBlock method.

Syntax

HRESULT ReceiveCanBlock(void);

Return Value

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

S_FALSEThe pin will not block on a call to Receive.
S_OKThe pin might block on a call to Receive.

Remarks

Return S_FALSE if calls to the Receive method are guaranteed not to block. Otherwise, return S_OK or an error code. If the Receive method calls Receive on a downstream pin, the downstream pin might block; ReceiveCanBlock must take that factor into account.

An upstream filter can use this method to determine its threading strategy. If the Receive method might block, the upstream filter might decide to use a worker thread that buffers data. See the COutputQueue class for an implementation of this strategy.

In the base class, this method returns S_OK when any of the following are true:

CBaseInputPin::ReceiveMultiple

CBaseInputPin Class

Receives multiple samples in the stream. Implements the IMemInputPin::ReceiveMultiple method.

Syntax

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

Parameters

pSamples
Address of an array of IMediaSample pointers, of size nSamples.
nSamples
Number of samples to process.
nSamplesProcessed
Pointer to a variable that receives the number of samples that were processed.

Return Value

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

S_OKSuccess.
S_FALSEPin is currently flushing; sample was rejected.
E_POINTERNULL pointer argument.
VFW_E_INVALIDMEDIATYPEInvalid media type.
VFW_E_RUNTIME_ERRORA run-time error occurred.
VFW_E_WRONG_STATEThe pin is stopped.

Remarks

This method behaves like the Receive method, but receives an array of samples. In the base class, the method loops through the array and calls Receive with each sample. Override this function if your filter can process batches of samples more efficiently than processing them one at a time.

CBaseInputPin::SampleProps

CBaseInputPin Class

Retrieves the properties of the most recent sample, as an AM_SAMPLE2_PROPERTIES structure.

Syntax

AM_SAMPLE2_PROPERTIES *SampleProps(void);

Return Value

Returns the address of the m_SampleProps member variable.