CBasePin Class

CBasePin is an abstract base class from which all pins are derived. CBasePin supports the IPin interface. You can derive from this if your pin does not supply or use the IMemInputPin interface; otherwise, derive from the CBaseInputPin class or the CBaseOutputPin class.

The connection process is crucial to the success of creating filter graphs. The filter graph finds two filters (and subsequently two pins) to connect. It calls the IPin::Connect method on the output pin (it can also call Connect on the input pin at the same time). The output pin then calls the virtual pin member function CBasePin::CheckConnect. Derived classes should override this member function to use QueryInterface to return any interfaces required. The base class implementation of CheckConnect queries the IMemInputPin interface to establish the default transport protocol.

After calling CheckConnect, the output pin calls CBasePin::AgreeMediaType; this is a worker member function not intended for overriding in derived classes. This gets the input pin's enumerator and calls CBasePin::TryMediaTypes with it. TryMediaTypes is another base pin worker member function that is not intended for derivation. It cycles through each media type provided by an enumerator to determine if a connection can be made with that type.

If that process fails, AgreeMediaType retrieves the output pin's media type enumerator and calls CBasePin::GetMediaType, which cycles through the media types to agree on a connection type. If there is agreement, a media type with the input and output pins becomes the type used in the connection.

If no media type can be agreed on, the connection between the pins cannot be made. The base pin calls CBasePin::SetMediaType to broadcast the format. The m_mt base pin variable is set during this process.

The IPin interface provides a method called QueryAccept. This method allows a connected filter to query whether the pin will accept a specified media type. The method is asynchronous so that a filter can call it at any time—even when another filter is calling it. For this reason, its implementation in any override of the base class should not lock the filter. The base class implementation of IPin::QueryAccept calls the overridden CBasePin::CheckMediaType member function on the derived pin 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_bRunTimeError	Run-time error generated.
m_Connected	Pin to which this pin is connected.
m_dir	Direction of this pin.
m_dRate	Rate from the CBasePin::NewSegment call.
m_mt	Media type that this pin is using. This is established during the connection process.
m_pFilter	Filter that created the pin.
m_pLock	Object used for locking.
m_pQSink	Target for quality messages.
m_pName	Name of the pin.
m_tStart	Start time from the CBasePin::NewSegment call.
m_tStop	Stop time from the CBasePin::NewSegment call.
m_TypeVersion	Current media type version (see CBasePin::GetMediaTypeVersion).

Member Functions

Name	Description
AttemptConnection	Attempts to make a connection to another pin using a specified media type.
CBasePin	Constructs a CBasePin object.
CurrentRate	Returns the segment rate set by the CBasePin::NewSegment member function.
CurrentStartTime	Returns the segment start time set by the CBasePin::NewSegment member function.
CurrentStopTime	Returns the segment stop time set by the CBasePin::NewSegment member function.
DisplayPinInfo	Displays pin information on the debugging monitor.
DisplayTypeInfo	Displays media type information on the debugging monitor.
GetConnected	Returns the pin that is connected to this pin.
IncrementTypeVersion	Adds 1 to the current media type version.
IsConnected	Determines whether the pin is connected.
IsStopped	Determines whether the filter owning this pin is in the State_Stopped state.
Name	Returns the m_pName name of the pin.

Overridable Member Functions

Name	Description
Active	Switches the pin to the active (running) mode.
AgreeMediaType	Agrees on the media type to be used by the pin.
BreakConnect	Adds custom code when the connection quits. This is also called when a stage in the connection process fails, so this member function should also clean up partial connection states.
CheckConnect	Adds custom code when the connection is being made. This is called at the start of the connection process.
CheckMediaType	Checks if the pin can support a specific media type.
CompleteConnect	Completes the connection.
GetMediaType	Returns the media type used by the pin.
GetMediaTypeVersion	Returns the version of the pins that were created dynamically.
Inactive	Switches the pin to the inactive (stopped) mode.
SetMediaType	Sets the m_mt data member to the established media type.
TryMediaTypes	Tries to find an acceptable media type for a connection from the list returned by a media type enumerator.

Implemented IPin Methods

Name	Description
Connect	Initiates a connection to another pin.
ConnectedTo	Returns a pointer to the connecting pin.
ConnectionMediaType	Returns the media type of this pin's connection.
Disconnect	Breaks a connection.
EndOfStream	Informs the input pin that no additional data is expected until a new run command is issued. (returns S_FALSE by default).
EnumMediaTypes	Returns an enumerator for this pin's preferred media types.
NewSegment	Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate.
QueryAccept	Determines whether this pin accepts the media type.
QueryDirection	Retrieves the pin direction of the pin.
QueryId	Retrieves an identifier for the pin.
QueryInternalConnections	Returns an array of the pins to which this pin connects internally.
QueryPinInfo	Retrieves information about the pin itself (the name, owning filter, or direction).
ReceiveConnection	Called by a connecting pin to make a connection to this pin. Usually this does not need to be overridden, because the default implementation calls CBasePin::CheckConnect, CBasePin::CheckMediaType, and CBasePin::BreakConnect.
Run	Notifies the pin that the filter has changed state from paused to running.

Implemented IQualityControl Methods

Name	Description
Notify	Notifies the recipient that a quality change is requested.
SetSink	Sets the IQualityControl object that will receive quality messages.

Implemented INonDelegatingUnknown Methods

Name	Description
NonDelegatingAddRef	Increments the owning filter's reference count.
NonDelegatingQueryInterface	Retrieves CBasePin interfaces. Override this member function to pass out pointers to any interfaces added by the derived pin class.
NonDelegatingRelease	Decrements the owning filter's reference count.

---

CBasePin::Active

CBasePin Class

Called by the CBaseFilter implementation when the state changes from stopped to either paused or running.

virtual HRESULT Active(void);

Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

Any class that requires notification of a change of state should override this member function. This is called when the filter owning the pin exits the State_Stopped state.

Note that the filter graph manager's internal state variable is not updated until after this member function returns, so testing the filter graph manager's state (directly or indirectly) from within this member function should be avoided.

---

CBasePin::AgreeMediaType

CBasePin Class

Searches for a media type for the pin connection.

virtual HRESULT AgreeMediaType(
  IPin *pReceivePin,
  const CMediaType *pmt
  );

Parameters

pReceivePin

Pointer to the receiving pin.

pmt

Pointer to a media type object to be returned.

Return Values

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

Value	Meaning
NOERROR	A media type was found.
VFW_E_NO_ACCEPTABLE_TYPES	No agreement on a media type was reached.

Remarks

This member function is called during the connection process. It calls CBasePin::TryMediaTypes on both the owning pin and the pin connected to the owning pin; it enumerates the preferred data types on the pin. If one is found, TryMediaTypes tries the media type with the pin in a call to the CBasePin::ReceiveConnection member function. If this pin proposes a media type, its support is still verified by calling CBasePin::CheckMediaType. The enumerator can list all the media types, even if some of them are not currently available.

This member function is protected.

---

CBasePin::AttemptConnection

CBasePin Class

Attempts to make a connection to another pin using a specified media type.

virtual HRESULT AttemptConnection(
  IPin * pReceivePin,
  const CMediaType *pmt
  );

Parameters

pReceivePin

Pointer to the receiving pin.

pmt

Pointer to a media type object containing the preferred media type for the connection.

Return Values

Returns an HRESULT value.

Remarks

This member function is used to attempt to connect with a given media type. Its main purpose is to call the IPin::ReceiveConnection method of the pin passed in the pReceivePin parameter. This member function is protected.

---

CBasePin::BreakConnect

CBasePin Class

Called when a connection is broken to allow for customization (intended for overriding).

virtual HRESULT BreakConnect( );

Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

This member function is called when a connection to the pin cannot be made or when CBasePin::Disconnect is called. In this case, it is necessary to undo anything performed during the connection process. You can override this member function to release any references to interfaces that were made during the connection.

---

CBasePin::CBasePin

CBasePin Class

Constructs a CBasePin object.

CBasePin(
  TCHAR *pObjectName,
  CBaseFilter *pFilter,
  CCritSec *pLock,
  HRESULT *phr,
  LPCWSTR pName,
  PIN_DIRECTION dir
  );

Parameters

pObjectName

Description of the object.

pFilter

Owning filter that knows about pins.

pLock

Object that implements the lock.

phr

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

pName

Pin name.

dir

Either PINDIR_INPUT or PINDIR_OUTPUT.

Return Values

No return value.

Remarks

This is a standard class constructor.

---

CBasePin::CheckConnect

CBasePin Class

Allows for customization when the connection is first made (intended for overriding, if required).

virtual HRESULT CheckConnect(
  IPin * pPin
  );

Parameters

pPin

Pointer to the connecting pin.

Return Values

Returns one of the following arguments by default; if overridden, should return standard HRESULT values, including the following values.

Value	Meaning
E_INVALIDARG	Pin directions do not match between pins.
NOERROR	Connection verified successfully.

Remarks

This member function is called during a call to the IPin::Connect method to provide a virtual method that can do any specific check required for a connection, such as calling CBasePin::NonDelegatingQueryInterface. This base class method determines if the pin directions match.

---

CBasePin::CheckMediaType

CBasePin Class

Determines if the pin can support a specific media type.

virtual HRESULT CheckMediaType(
  const CMediaType * pmt
  )
PURE;

Parameters

pmt

Pointer to a media type object containing the proposed media type.

Return Values

The overriding member function should return S_OK if the proposed media type is accepted; otherwise, it should return an HRESULT failure value, such as S_FALSE.

Remarks

This member function is typically called before calling the CBasePin::SetMediaType member function. It is also called from several other member functions, including CBasePin::ReceiveConnection and CBasePin::QueryAccept.

---

CBasePin::CompleteConnect

CBasePin Class

Completes a connection to another filter (intended for overriding).

virtual HRESULT CompleteConnect(
  IPin *pReceivePin
  );

Parameters

pReceivePin

Pointer to the connected (receiving) pin.

Return Values

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

Override this member function to check for required connection interfaces on the pReceivePin parameter or its filter. Failing this member function fails the connection and disconnects the other pin. The CBaseOutputPin class overrides this member function to establish a local memory transport.

---

CBasePin::Connect

CBasePin Class

Initiates a connection from this pin to the other pin.

HRESULT Connect(
  IPin * pReceivePin,
  const AM_MEDIA_TYPE *pmt
  );

Parameters

pReceivePin

Input pin to connect to.

pmt

Optional media type parameter.

Return Values

Returns one of the following arguments by default; if overridden, should return standard HRESULT values.

Value	Meaning
VFW_E_ALREADY_CONNECTED	This output pin is already connected to another pin.
VFW_E_NOT_STOPPED	The filter graph is not in a stopped state and connection can't be performed.
Other error value	Returned from CBasePin::AgreeMediaType or CBasePin::CheckConnect or overridden versions of these member functions.

Remarks

This member function implements the IPin::Connect method. IPin::Connect is implemented on the output pin and calls the IPin::ReceiveConnection method for the connected input pin (implemented in the base classes as CBasePin::ReceiveConnection). This member function calls the virtual CBasePin::CheckConnect member function, which can be overridden to verify that the connection is possible. CBasePin::CheckConnect then calls CBasePin::AgreeMediaType to negotiate a common media type with the connected pin.

CBasePin::AgreeMediaType calls CBasePin::TryMediaTypes twice; once for this pin's media type enumerator and once for the receiving pin's media type enumerator. For each media type found, CBasePin::AttemptConnection is called, which in turn calls the receiving pin's IPin::ReceiveConnection method, and finally CBasePin::CompleteConnect if successful.

---

CBasePin::ConnectedTo

CBasePin Class

Retrieves a pointer to the connected pin, if there is one.

HRESULT ConnectedTo(
  IPin ** ppPin
  );

Parameters

ppPin

IPin interface of the other pin (if any) to which this pin is connected.

Return Values

The base class returns S_OK if connected; otherwise, returns VFW_E_NOT_CONNECTED.

Remarks

This member function implements the IPin::ConnectedTo method. It adds a reference to the connected IPin interface by calling the IUnknown::AddRef method, because each copy of an interface pointer has its reference incremented. The calling application is responsible for calling IUnknown::Release on this interface when done with it.

---

CBasePin::ConnectionMediaType

CBasePin Class

Retrieves the media type associated with the current connection of the pin.

HRESULT ConnectionMediaType(
  AM_MEDIA_TYPE *pmt
  );

Parameters

pmt

Pointer to an AM_MEDIA_TYPE structure. If the pin isn't connected, this structure is initialized to zero. Otherwise, the media type is returned in this parameter.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::ConnectionMediaType method. It returns a copy of the AM_MEDIA_TYPE structure that was negotiated for the pin connection when the pin was connected.

This method fails if the pin is unconnected. The task allocator allocates the media type's format block. Use the task allocator to free the format block, for example by calling the Microsoft Win32 CoTaskMemFree function.

---

CBasePin::CurrentRate

CBasePin Class

Retrieves the segment rate set by the CBasePin::NewSegment member function.

double CurrentRate( );

Return Values

Returns the value of m_dRate.

---

CBasePin::CurrentStartTime

CBasePin Class

Retrieves the segment start time set by the CBasePin::NewSegment member function.

REFERENCE_TIME CurrentStartTime( );

Return Values

Returns the value of m_tStart.

---

CBasePin::CurrentStopTime

CBasePin Class

Retrieves the segment stop time set by the CBasePin::NewSegment member function.

REFERENCE_TIME CurrentStopTime( );

Return Values

Returns the value of m_tStop.

---

CBasePin::Disconnect

CBasePin Class

Breaks a connection.

HRESULT Disconnect(void);

Return Values

Returns NOERROR if there is no connection.

Remarks

This member function implements the IPin::Disconnect method. It calls the CBasePin::BreakConnect member function and releases the IPin interface of the connected pin (held by m_Connected). There are no parameters because there is only one possible connection on this pin.

---

CBasePin::DisplayPinInfo

CBasePin Class

Displays pin information during debugging.

void DisplayPinInfo(
  IPin *pReceivePin
  );

Parameters

pReceivePin

Pointer to the receiving pin.

Return Values

Returns an HRESULT value.

---

CBasePin::DisplayTypeInfo

CBasePin Class

Displays media type information during debugging.

void DisplayTypeInfo(
  IPin *pPin,
  const CMediaType *pmt
  );

Parameters

pPin

Pointer to the pin's IPin interface.

pmt

Pointer to the media type object.

Return Values

No return value.

Remarks

This member function displays the major and minor media types of the specified media type object.

---

CBasePin::EndOfStream

IPin Interface

Informs the input pin that no additional data is expected until a new run command is issued.

HRESULT EndOfStream(void);

Return Values

Returns S_FALSE.

Remarks

This member function implements the IPin::EndOfStream method. This is intended for input pins only.

---

CBasePin::EnumMediaTypes

CBasePin Class

Provides an enumerator for this pin's preferred media types.

HRESULT EnumMediaTypes(
  IEnumMediaTypes ** ppEnum
  );

Parameters

ppEnum

Pointer to an enumerator for the media types.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::EnumMediaTypes method. It returns an enumerator object implemented by the CEnumMediaTypes class and obtains the IEnumMediaTypes interface, which adds a reference count to this enumerator. If an application receives an enumerator, the application must release this when done with it by calling IUnknown::Release on the enumerator.

---

CBasePin::GetConnected

CBasePin Class

Retrieves the pin that is connected to this pin.

IPin * GetConnected( );

Return Values

Returns a pointer to an IPin interface.

Remarks

The caller should call the CBasePin::IsConnected member function before calling CBasePin::GetConnected.

---

CBasePin::GetMediaType

CBasePin Class

Retrieves the current type version, which is used by enumerators.

virtual HRESULT GetMediaType(
  int iPosition,
  const CMediaType *pMediaType
  );

Parameters

iPosition

Position in the media type list.

pMediaType

Returned pointer to the media type at this position.

Return Values

Returns E_UNEXPECTED by default implementation; the overriding member function should return one of the following values, or an HRESULT error value if the value could not be set.

Value	Meaning
S_FALSE	Media type exists but is not currently usable.
S_OK	Media type was set.
VFW_S_NO_MORE_ITEMS	End of the list of media types has been reached.

Remarks

This is a virtual member function that returns a media type corresponding to the position in the list specified by the iPosition parameter. This base class simply returns an error because no media types are supported by default. Derived classes should override this member function.

---

CBasePin::GetMediaTypeVersion

CBasePin Class

Retrieves the current type version, which is used by enumerators.

virtual LONG GetMediaTypeVersion( );

Return Values

Returns the value of m_TypeVersion by default. To return new media types, override this member function.

Remarks

This is a virtual member function that returns the current media type version. The base class initializes the media type enumerators to 1. A derived class can change the list of available media types. Each time it does, it should increment the version in the overriding member function. The media type enumerators call this member function when they are called to determine if they are out of date.

---

CBasePin::Inactive

CBasePin Class

Switches the pin to an inactive state.

virtual HRESULT Inactive(void);

Return Values

Returns NOERROR for a base class implementation. The overriding member function returns a standard HRESULT value and should not fail if the pin is already set as inactive.

Remarks

This member function is called by the IMediaFilter implementation when the state changes to inactive. This member function should be overridden to decommit allocators and free any hardware resources that were obtained in the CBasePin::Active call. The default implementation of the base class member function does nothing.

Note that the filter graph manager's internal state variable is not updated until after this member function returns, so testing the filter graph manager's state (directly or indirectly) from within this member function should be avoided.

---

CBasePin::IncrementTypeVersion

CBasePin Class

Adds 1 to the current media type version.

void IncrementTypeVersion(void);

Return Values

No return value.

Remarks

The media type version is used to ensure that the filter has not changed the media type. If it changes the media type, the filter should call this member function.

---

CBasePin::IsConnected

CBasePin Class

Determines if the pin is connected to another pin.

BOOL IsConnected(void);

Return Values

Returns TRUE if the pin is connected; otherwise, returns FALSE.

Remarks

This member function checks the value of the m_Connected protected data member.

---

CBasePin::IsStopped

CBasePin Class

Determines if the filter is stopped.

BOOL IsStopped( );

Return Values

Returns TRUE if the filter is stopped; otherwise, returns FALSE.

Remarks

Note that this member function must not be used in the constructor of the pin, because the filter that is passed is often not initialized properly at that time (due to the convention of using a this pointer during the construction of data members).

---

CBasePin::Name

CBasePin Class

Retrieves the name of the pin.

LPWSTR Name( );

Return Values

Returns the value of the m_pName data member.

---

CBasePin::NewSegment

CBasePin Class

Specifies that samples following this call are grouped as a segment with a given start time, stop time, and rate.

HRESULT NewSegment(
  REFERENCE_TIME tStart,
  REFERENCE_TIME tStop,
  double dRate
  );

Parameters

tStart

Start time of the segment.

tStop

Stop time of the segment.

dRate

Rate of the segment.

Return Values

Returns an HRESULT value (S_OK by default).

Remarks

This member function implements the IPin::NewSegment method. The default implementation sets the m_tStart, m_tStop, and m_dRate data members to the values passed in as parameters. Overriding member functions should pass this notification downstream.

---

CBasePin::NonDelegatingAddRef

CBasePin Class

Increments the reference count for an interface.

ULONG NonDelegatingAddRef( );

Return Values

Returns the reference count of the object.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingAddRef method. It increments the reference count of the owning filter.

---

CBasePin::NonDelegatingQueryInterface

CBasePin 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 IPin, IQualityControl, and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

---

CBasePin::NonDelegatingRelease

CBasePin Class

Decrements the reference count for an interface.

ULONG NonDelegatingRelease( );

Return Values

Returns the reference count.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingRelease method. It releases a reference to the owning filter.

---

CBasePin::Notify

CBasePin 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

The default base class implementation returns E_FAIL.

Remarks

This member function must be overridden to accept notifications. It is typically overridden to implement this method on the output pin because quality-control messages are passed upstream. The CTransformOutputPin::Notify member function is one example of how this member function is overridden to pass quality-control messages to the next filter upstream.

---

CBasePin::QueryAccept

CBasePin Class

Determines whether the pin accepts the format type.

HRESULT QueryAccept(
  const AM_MEDIA_TYPE* pmt
  );

Parameters

pmt

Pointer to a proposed media type.

Return Values

Returns S_TRUE if the format is accepted; otherwise, returns S_FALSE.

Remarks

This member function implements the IPin::QueryAccept method. It simply calls the pure virtual CBasePin::CheckMediaType member function, which the derived class must implement, and maps any returned codes from CheckMediaType other than S_OK to S_FALSE.

---

CBasePin::QueryDirection

CBasePin Class

Retrieves the direction of the pin.

HRESULT QueryDirection(
  PIN_DIRECTION* pPinDir
  );

Parameters

pPinDir

Pointer to a PIN_DIRECTION structure to be filled in with the direction.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::QueryDirection method. pPinDir will contain PINDIR_INPUT or PINDIR_OUTPUT. The same information is available through the CBasePin::QueryPinInfo member function, but this member function is more efficient.

---

CBasePin::QueryId

CBasePin Class

Retrieves an identifier for the pin.

HRESULT QueryId(
  LPWSTR * Id
  );

Parameters

Id

Pin identifier.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::QueryId method. By default, this member function uses the pin name in the CBasePin::m_pName data member, so implementing this member function in your derived filter class is not normally required.

---

CBasePin::QueryInternalConnections

CBasePin Class

Provides an array of pointers to IPin objects. These are the pins to which this pin internally connects.

HRESULT QueryInternalConnections(
  IPin ** apPin,
  ULONG * nPin
  );

Parameters

apPin

Array of IPin pointers.

nPin

Upon input, indicates the number of channels; upon output, indicates the number of pins.

Return Values

Returns one of the following HRESULT values.

Value	Meaning
E_FAIL	Undetermined failure.
E_NOTIMPL	The filter graph manager interprets E_NOTIMPL as meaning all input pins connect to all output pins.
S_FALSE	Insufficient number of channels; returns no pins in apPin.

Remarks

This member function implements the IPin::QueryInternalConnections method but only to return E_NOTIMPL. Override this if you want to provide mapping between specific input and output pins.

The default implementation to return E_NOTIMPL implies that the caller can assume that all input pins feed all output pins. Overriding this member function allows a filter to specify when it is a renderer for some of its input pins and not for others.

---

CBasePin::QueryPinInfo

CBasePin Class

Retrieves information about the pin.

HRESULT QueryPinInfo(
  PIN_INFO * pInfo
  );

Parameters

pInfo

Pointer to a PIN_INFO structure.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::QueryPinInfo method. By default, the member function fills in the PIN_INFO structure with the IBaseFilter interface of its owning filter, the pin name from m_pName, and the pin direction from m_dir.

The IBaseFilter interface passed out by this member function is reference counted, and so must be released when the caller has finished with it.

---

CBasePin::ReceiveConnection

CBasePin Class

Makes a connection to the calling output pin.

HRESULT ReceiveConnection(
  IPin * pConnector,
  AM_MEDIA_TYPE *pmt
  );

Parameters

pConnector

Connecting pin.

pmt

Media type of the samples to be streamed.

Return Values

Returns an HRESULT value.

Remarks

This member function implements the IPin::ReceiveConnection method. It calls CheckConnect and, if successful, then calls CheckMediaType to verify if the media type is acceptable. If either of these calls fails, it calls BreakConnect and exits. To finish the connection process, it calls CompleteConnect, which is implemented in CBasePin to return NOERROR, but can be overridden in the derived class.

---

CBasePin::Run

CBasePin Class

Notifies the pin that the filter has changed state from paused to running.

HRESULT Run(
  REFERENCE_TIME tStart
  );

Parameters

tStart

Start time as passed to the filter's Run method.

Return Values

Returns an HRESULT value (NOERROR_OK by default).

Remarks

This member function can be overridden in the derived class to perform activities such as committing memory or obtaining resources. For an overriding implementation of this member function, see the CRenderedInputPin::Run member function.

Note that the filter graph manager's internal state variable is not updated until after this member function returns, so testing the filter graph manager's state (directly or indirectly) from within this member function should be avoided.

---

CBasePin::SetMediaType

CBasePin Class

Sets the m_mt data member to the established media type.

virtual HRESULT SetMediaType(
  const CMediaType * pmt
  );

Parameters

pmt

Pointer to a media type object that was previously agreed on.

Return Values

Returns NOERROR by default implementation. The overriding member functions return an HRESULT value.

Remarks

This member function is called to establish the format for a pin connection. The CBasePin::CheckMediaType member function will have been called to check the connection format and, if it did not return an error value, this virtual member function will be called. The default implementation sets the m_mt protected data member to the value passed to this member function. Override to inform the derived class when the media type is set.

---

CBasePin::SetSink

CBasePin Class

Sets the object containing the IQualityControl interface that will receive quality-control messages.

HRESULT SetSink(
  IQualityControl *piqc
  );

Parameters

piqc

Pointer to the IQualityControl interface to which the notifications should be sent.

Return Values

Base class returns NOERROR by default. The overriding member function should return an HRESULT value.

Remarks

This member function implements the IQualityControl::SetSink method. The default implementation sets the m_pQSink data member to the piqc parameter passed in.

The IQualityControl::SetSink method tells a filter where to send quality-control messages it receives. When no sink has been explicitly set or if the last call to CBasePin::SetSink set the sink to NULL, the message should go upstream. The derived output pin class typically overrides CBasePin::Notify to enable this.

---

CBasePin::TryMediaTypes

CBasePin Class

Determines a media type for a pin connection.

virtual HRESULT TryMediaTypes(
  IPin *pReceivePin,
  const CMediaType *pmt,
  IEnumMediaTypes *pEnum
  );

Parameters

pReceivePin

Pointer to the IPin interface of the receiving pin.

pmt

Pointer to a returned media type.

pEnum

Pointer to an IEnumMediaTypes enumerator interface.

Return Values

Returns an HRESULT value, which can include the following.

Value	Meaning
FAILED	Resetting of the enumerator failed.
NOERROR	Media type found.
VFW_E_NO_ACCEPTABLE_TYPES	No acceptable media types were found.

Remarks

Given an enumerator, this member function cycles through all the media types proposed by the enumerator. Each type is suggested to the derived pin class and, if acceptable, is tried with the connected pin in a call to the IPin::ReceiveConnection method. This means that if the owning pin proposes a media type, it is still checked to determine whether it is supported. This is deliberate so that, in simple cases, the enumerator can hold all the media types, even if some of them are not currently available.

This member function is protected.

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

Top of Page