CBaseInputPin Class

CBaseInputPin is an abstract base class derived from CBasePin that adds support for IMemInputPin in addition to the IPin interface support provided by CBasePin. Its IMemInputPin::GetAllocator method returns a CMemAllocator object. Derive your input pin from this class.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Protected Data Members

Name	Description
m_bFlushing	In the state of flushing; if TRUE, all IMemInputPin::Receive methods are returned with S_FALSE.
m_bReadOnly	If TRUE, indicates that the allocator being used contains samples that are read-only.
m_pAllocator	Pointer to the default memory allocator.

Member Functions

Name	Description
CBaseInputPin	Constructs a CBaseInputPin object.
IsReadOnly	Checks the m_bReadOnly data member and returns its value.
IsFlushing	Checks the m_bFlushing data member and returns its value.
PassNotify	Passes a quality-control notification to the appropriate sink.

Overridable Member Functions

Name	Description
CheckStreaming	Verifies conditions for continuing with a streaming operation.
Inactive	Switches the pin to an inactive state.

Implemented IPin Methods

Name	Description
BeginFlush	Informs the pin to begin a flush operation.
Disconnect	Releases the stored allocator.
EndFlush	Informs the pin to end a flush operation.

Implemented IMemInputPin Methods

Name	Description
GetAllocator	Returns the allocator interface that this input pin would like the output pin to use.
GetAllocatorRequirements	Indicates an optional method to use if the filter has specific alignment or prefix requirements but could use an upstream allocator.
NotifyAllocator	Tells the input pin which allocator the output pin is actually going to use.
Receive	Returns the next block of data from the stream. (Override this method to process a sample being passed in.)
ReceiveCanBlock	Determines if sending an IMemInputPin::Receive method might block.
ReceiveMultiple	Returns the next block of data from the stream. (Override this method to process samples being passed in.)

Implemented INonDelegatingUnknown Methods

Name	Description
NonDelegatingQueryInterface	Retrieves an interface from the subobject, not the aggregated object.

Implemented IQualityControl Methods

Name	Description
Notify	Notifies the recipient that a quality-control change is requested. (Override on the output pin only. This implementation returns NOERROR.)

---

CBaseInputPin::BeginFlush

CBaseInputPin Class

Informs the pin to begin a flush operation.

HRESULT BeginFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::BeginFlush method. When this method is called, the pin is entering flush state. You must override this method in your derived class, but you should call this base class first in your implementation, because it sets m_bFlushing so that no more IMemInputPin::Receive calls will succeed.

The overriding member function should then carry out the following steps.

1. Discard any queued data.
2. Free any pin blocked by the Receive method.
3. Pass the IPin::BeginFlush method to any downstream pins.

IPin::BeginFlush is not logically part of the media stream and can be optimized in the sense that if a pin has passed no data downstream before this method is called, there is no need to pass this notification on.

An example of an overriding implementation of this member function can be found in the CTransformInputPin::BeginFlush member function, which uses the CBaseOutputPin::DeliverBeginFlush member function to perform the last step.

---

CBaseInputPin::CBaseInputPin

CBaseInputPin Class

Constructs a CBaseInputPin object.

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

Parameters

pObjectName

Name of the class object.

pFilter

Pointer to the filter that owns this pin.

pLock

Pointer to the CCritSec critical section object used to lock the pin.

phr

Pointer to the general COM return value. This value is changed only if this function fails.

pPinName

Name of the pin.

Return Values

No return value.

---

CBaseInputPin::CheckStreaming

CBaseInputPin Class

Verifies conditions for continuing with a streaming operation.

virtual HRESULT CheckStreaming( );

Return Values

Returns one of the following HRESULT values, depending on the state.

Value	Meaning
S_FALSE	Currently in flushing state.
S_OK	Receive or EndOfStream operations can safely proceed.
VFW_E_RUNTIME_ERROR	Run-time error occurred while processing a previous sample.
VFW_E_WRONG_STATE	Filter is in the State_Stopped state.

Remarks

Conditions checked in this member function include whether the filter is connected, if it is in an active state, if it is not currently flushing data, and if it has not just issued a run-time error. If all these conditions pass, it returns S_OK.

You can override this member function to add restrictions defined by your derived class. The overriding member function should call this base class implementation to check for conditions here as well.

This function member should be called from any override of the CBaseInputPin::Receive or CBasePin::EndOfStream member function (or they should do some equivalent check).

---

CBaseInputPin::Disconnect

CBaseInputPin Class

Releases the stored allocator.

HRESULT Disconnect( );

Return Values

Returns an HRESULT value.

Remarks

This member function overrides the CBasePin::Disconnect member function. It calls CBasePin::Disconnect first, and then releases the allocator held by m_pAllocator.

---

CBaseInputPin::EndFlush

CBaseInputPin Class

Informs the pin to end a flush operation and notifies the pin that it can start accepting data again.

HRESULT EndFlush(void);

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::EndFlush method. When this method is called, the pin is beginning to end a flush operation. Your derived class must override this member function, but should call this member function at the end of your implementation to clear m_bFlushing so that IMemInputPin::Receive calls will succeed.

Before calling this base class implementation, your overriding member function should perform the following steps.

1. Ensure that your filter will not push any additional data. (To do this, synchronize with a thread, stop it pushing, and discard any queued data.)
2. Pass the EndFlush method downstream by calling the method on the downstream filter's input pin.

IPin::EndFlush is not logically part of the media stream. It can be optimized in the sense that if a pin has passed no data downstream before this method is called, there is no need to pass this notification on.

An example of an overriding implementation of this member function can be found in the CTransformInputPin::EndFlush member function, which uses the CBaseOutputPin::DeliverEndFlush member function to perform the last step.

---

CBaseInputPin::GetAllocator

CBaseInputPin Class

Retrieves the allocator interface that this input pin identifies as the interface for the output pin to use.

HRESULT GetAllocator(
  IMemAllocator ** ppAllocator
  );

Parameters

ppAllocator

Pointer to an obtained IMemAllocator object.

Return Values

Default implementation returns either E_OUTOFMEMORY, if an allocator cannot be created, or NOERROR upon success.

Remarks

This member function implements the IMemInputPin::GetAllocator method, which is called by the connected output pin to retrieve an allocator to use for transporting media samples. By default, this member function creates a CMemAllocator object and obtains the IMemAllocator interface, to which it adds a reference count for the pin when assigning it to the m_pAllocator data member, and adds another reference count before passing it back to the output pin.

Override this member function if your filter has another allocator, such as one from a downstream pin, or a specialized allocator to offer the connected output pin.

---

CBaseInputPin::GetAllocatorRequirements

CBaseInputPin Class

Optional member function to use if the filter has specific alignment or prefix requirements but could use an upstream allocator.

HRESULT GetAllocatorRequirements(
  ALLOCATOR_PROPERTIES * pProps
  );

Parameters

pProps

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

Return Values

Returns an HRESULT value. Returns E_NOTIMPL by default.

Remarks

Override this member function if you have specific alignment or prefix requirements but could use an upstream allocator.

---

CBaseInputPin::Inactive

CBaseInputPin Class

Releases the allocator's memory.

HRESULT Inactive(void);

Return Values

Returns an HRESULT value.

Remarks

This member function is called through IMediaFilter, which is responsible for locking the object first.

---

CBaseInputPin::IsFlushing

CBaseInputPin Class

Checks the m_bFlushing data member and returns its value.

BOOL IsFlushing(void);

Return Values

Returns TRUE if the input pin is flushing data; otherwise, returns FALSE.

---

CBaseInputPin::IsReadOnly

CBaseInputPin Class

Checks the m_bReadOnly data member and returns its value.

BOOL IsReadOnly(void);

Return Values

Returns TRUE if the allocator has read-only samples; otherwise, returns FALSE.

---

CBaseInputPin::NonDelegatingQueryInterface

CBaseInputPin Class

Retrieves an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void ** ppv
  );

Parameters

riid

Reference identifier.

ppv

Pointer to the interface.

Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IMemInputPin and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

---

CBaseInputPin::Notify

CBaseInputPin Class

Notifies the recipient that a quality change is requested.

HRESULT Notify(
  IBaseFilter * pSelf,
  Quality q
  );

Parameters

pSelf

Pointer to the filter that is sending the quality notification.

q

Quality notification structure.

Return Values

Returns NOERROR by default.

Remarks

The IQualityControl::Notify method is usually implemented on the output pin, because quality-control messages are passed upstream, and not on the input pin.

---

CBaseInputPin::NotifyAllocator

CBaseInputPin Class

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

HRESULT NotifyAllocator(
  IMemAllocator * pAllocator,
  BOOL bReadOnly
  );

Parameters

pAllocator

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

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

Return Values

Default implementation returns NOERROR.

Remarks

This member function implements the IMemInputPin::NotifyAllocator method, which is called by the connected output pin to inform the input pin of the chosen allocator for the memory transport. Override this member function if your filter cares about this information. By default, this sets the m_pAllocator data member to the allocator interface passed in after adding a reference count to that interface.

---

CBaseInputPin::PassNotify

CBaseInputPin Class

Passes a quality-control notification to the appropriate sink.

HRESULT PassNotify(
  Quality q
  );

Parameters

q

Quality-control notification object.

Return Values

Returns VFW_E_NOT_FOUND if no quality sink is set and the upstream filter does not support the IQualityControl interface. Otherwise, returns the HRESULT value resulting from notifying the sink or the upstream filter.

Remarks

Output pins receive quality-control notifications and, if possible, filters act on them to degrade appropriately. Often, filters cannot respond to the notifications; in this case the notification should be passed to the quality-control sink or, by default, upstream to the next filter. The PassNotify member function is called from the CTransformOutputPin::Notify member function when a notification requires passing. The Quality structure passed is the one that the output pin received.

---

CBaseInputPin::Receive

CBaseInputPin Class

Retrieves the next block of data from the stream.

HRESULT Receive(
  IMediaSample * pSample
  );

Parameters

pSample

Pointer to a media sample.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMemInputPin::Receive method. It first checks that it can process the sample by calling CBaseInputPin::CheckStreaming; if that member function does not return S_OK, Receive returns immediately with the value returned by CBaseInputPin::CheckStreaming.

This base class member function checks to see if the format has changed with this media sample; if so, it checks that the filter will accept it, generating a run-time error if not. If a run-time error is raised, the m_bRunTimeError data member is set so that no more samples will be accepted.

The overriding member function does something with the passed-in sample, such as calling a member function to transform it or pass it downstream.

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

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

---

CBaseInputPin::ReceiveCanBlock

CBaseInputPin Class

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

HRESULT ReceiveCanBlock(void);

Return Values

Returns an HRESULT value, which can include one of the following values.

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

Remarks

This member function implements the IMemInputPin::ReceiveCanBlock method. The base class implementation calls the IMemInputPin::ReceiveCanBlock method on the input pin connected to each of the filter's output pins.

This member function is useful because 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 be blocked, and might choose to start another thread to wait on the blocking Receive method. See the COutputQueue base class for queuing samples to input pins that potentially block.

---

CBaseInputPin::ReceiveMultiple

CBaseInputPin Class

Retrieves the next block of data from the stream. This method behaves much like the IMemInputPin::Receive method, but it works with multiple samples. Override this function if you can usefully process samples in batches.

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

Parameters

pSamples

Pointer to an array of samples.

nSamples

Number of samples to process.

nSamplesProcessed

Number of samples processed.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IMemInputPin::ReceiveMultiple method. It is implemented to call the CBaseInputPin::Receive member function in a loop for nSamples number of iterations.

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

Top of Page