Microsoft DirectX 8.0

CBasePin Class

CBasePin class hierarchy

Abstract class that implements a generic pin.

Declaration: Amfilter.h

Connection Process

The filter graph manager initiates all pin connections. If an application needs to connect two pins, it should call the filter graph manager's IFilterGraph::ConnectDirect method.

When two pins connect, there is a connecting pin and a receiving pin. The filter graph manager calls the connecting pin's IPin::Connect method. It specifies the receiving pin and possibly a media type for the connection. The connecting pin completes the connection by calling the receiving pin's IPin::ReceiveConnection method. The receiving pin can accept or reject the connection.

If the filter graph manager specifies a media type, the pins try to connect with that type. Otherwise, the pins negotiate an acceptable type. If they cannot agree on a type, the connection fails. The filter graph manager might also specify a partial media type. A partial media type has a value of GUID_NULL for the major type, the subtype, or the format. In that case, the pins try to match the specified portions of the type, and GUID_NULL acts as a wildcard.

In the Microsoft® DirectShow® implementation, the connecting pin is always an output pin, and the receiving pin is always an input pin.

How CBasePin Implements IPin::Connect

The CBasePin::Connect method starts by verifying that the pin can accept a connection. For example, it checks that the pin is not already connected. Then it delegates the rest of the connection process to AgreeMediaType, a protected class method. Everything that follows is performed by AgreeMediaType.

If the media type is fully specified, the pin calls the AttemptConnection method. Otherwise, the pin tries media types in the following order:

  1. The receiving pin's preferred types.
  2. The connecting pin's preferred types.

Note  You can reverse the order by setting the m_bTryMyTypesFirst flag to TRUE.

In each case, the pin calls IPin::EnumMediaTypes, which retrieves an enumerator object. It passes the enumerator object to the TryMediaTypes method. This method loops through all the media types provided by the enumerator, and calls AttemptConnection with each type.

Within the AttemptConnection method, the connecting pin calls the following methods:

Note the following:

If any of these steps fails, the pin calls the BreakConnect method to undo whatever steps were taken by CheckConnect.

On the receiving side, ReceiveConnection calls the receiving pin's CheckConnect, CheckMediaType, and CompleteConnect methods. If any of these fail, the connection attempt also fails.

Filter State Changes

The pin is notified whenever the state of the owning filter changes. For each state transition, the filter calls a corresponding method on the pin, as shown in the following table.

Filter StateCBasePin Method
StopInactive
PauseActive
RunRun

The derived class should override these methods to respond to the state change. Depending on the filter, the pin might start a worker thread that delivers samples, commit or decommit its memory allocator, and so forth.

Deriving from CBasePin

To implement a pin using CBasePin, you must derive a new class from the base class and override several of its methods. You must override the following methods:

You will probably need to override these additional methods:

Finally, you must must implement the IPin::BeginFlush and IPin::EndFlush methods.

Some of these methods are implemented in base classes that derive from CBasePin, such as CBaseInputPin and CBaseOutputPin.

Protected Member Variables
m_pNamePin name.
m_ConnectedPointer to the pin that is connected to this pin.
m_dir Direction of the pin.
m_pLock Pointer to a critical section object.
m_bRunTimeErrorFlag that indicates whether a run-time error has occurred.
m_bCanReconnectWhenActiveFlag that indicates whether the pin supports dynamic reconnection.
m_bTryMyTypesFirstFlag that indicates whether the pin tries its own preferred media types before those of the receiving pin.
m_pFilter Pointer to the filter that created the pin.
m_pQSink Pointer to the object that handles quality messages.
m_TypeVersion Current version of the set of preferred media types.
m_mtMedia type for the current pin connection.
m_tStart Segment start time.
m_tStop Segment stop time.
m_dRateSegment rate.
Protected Methods
DisplayPinInfoTraces a pin connection during debugging.
DisplayTypeInfoDisplays media type information during debugging.
AttemptConnectionConnects to another pin using a specified media type.
TryMediaTypesGiven a list of media types, tries to complete a connection using one of those types.
AgreeMediaTypeSearches for a media type to make a pin connection.
DisconnectInternalBreaks the current pin connection.
Public Methods
CBasePinConstructor method.
~CBasePinDestructor method. Virtual.
IsConnectedDetermines whether the pin is connected to another pin.
GetConnectedRetrieves the pin that is connected to this pin.
IsStoppedDetermines whether the filter containing this pin is stopped.
GetMediaTypeVersionRetrieves a version number for the set of preferred media types. Virtual.
IncrementTypeVersionIncrements the version number on the set of preferred media types.
ActiveNotifies the pin that the filter is now active. Virtual.
InactiveNotifies the pin that the filter is no longer active. Virtual.
RunNotifies the pin that the filter is now running. Virtual.
SetMediaTypeSets the media type for the connection. Virtual.
CheckConnectDetermines whether a pin connection is suitable. Virtual.
BreakConnectReleases the pin from a connection. Virtual.
CompleteConnectCompletes a connection to another pin. Virtual.
GetMediaTypeRetrieves a preferred media type, by index value. Virtual.
CurrentStopTimeRetrieves the segment stop time.
CurrentStartTimeRetrieves the segment start time.
CurrentRateRetrieves the segment rate.
NameRetrieves the pin identifier.
SetReconnectWhenActiveSpecifies whether the pin supports dynamic reconnections.
CanReconnectWhenActiveQueries whether the pin supports dynamic reconnections.
Pure Virtual Methods
CheckMediaTypeDetermines if the pin accepts a specific media type.
IBasePin methods
ConnectConnects the pin to another pin.
ReceiveConnectionAccepts a connection from another pin.
DisconnectBreaks the current pin connection.
ConnectedToRetrieves the pin connected to this pin.
ConnectionMediaTypeRetrieves the media type for the current pin connection, if any.
QueryPinInfoRetrieves information about the pin.
QueryDirectionRetrieves the direction of the pin (input or output).
QueryIdRetrieves the pin identifier.
QueryAcceptDetermines whether the pin accepts a specified media type.
EnumMediaTypesEnumerates the pin's preferred media types.
QueryInternalConnectionsRetrieves the pins that are connected internally to this pin (within the filter).
EndOfStreamNotifies the pin that no additional data is expected.
NewSegmentNotifies the pin that media samples received after this call are grouped as a segment.
IQualityControl methods
NotifyNotifies the pin that a quality change is requested.
SetSinkSets an external quality manager.

CBasePin.m_pName

CBasePin Class

Pin name.

Syntax

WCHAR *m_pName;

Remarks

The QueryPinInfo method returns this string as the pin name, and the QueryId method returns it as the pin identifier. In general, however, the pin name and the pin identifier are not required to be the same. The pin identifier is used for graph persistence. For more information, see IBaseFilter::FindPin.

CBasePin.m_Connected

CBasePin Class

Pointer to the pin that is connected to this pin.

Syntax

IPin *m_Connected;

CBasePin.m_dir

CBasePin Class

Direction of the pin.

Syntax

PIN_DIRECTION m_dir;

CBasePin.m_pLock

CBasePin Class

Pointer to a critical section object.

Syntax

CCritSec *m_pLock;

CBasePin.m_bRunTimeError

CBasePin Class

Flag that indicates whether a run-time error has occurred.

Syntax

bool m_bRunTimeError;

Remarks

This flag defaults to FALSE. Set the flag to TRUE if a run-time error occurs during streaming. The Inactive method resets the flag to FALSE.

CBasePin.m_bCanReconnectWhenActive

CBasePin Class

Flag that indicates whether the pin supports dynamic reconnection.

Syntax

bool m_bCanReconnectWhenActive;

Remarks

This flag defaults to FALSE.

CBasePin.m_bTryMyTypesFirst

CBasePin Class

Flag that indicates whether the pin tries its own preferred media types before those of the receiving pin.

Syntax

bool m_bTryMyTypesFirst;

Remarks

This flag defaults to FALSE. If the flag is TRUE, the AgreeMediaType method reverses the order in which it tries media types.

CBasePin.m_pFilter

CBasePin Class

Pointer to the filter that created the pin.

Syntax

CBaseFilter *m_pFilter;

CBasePin.m_pQSink

CBasePin Class

Pointer to the object that handles quality messages.

Syntax

IQualityControl *m_pQSink;

CBasePin.m_TypeVersion

CBasePin Class

Current version of the set of preferred media types.

Syntax

LONG m_TypeVersion;

CBasePin.m_mt

CBasePin Class

Media type for the current pin connection.

Syntax

CMediaType m_mt;

CBasePin.m_tStart

CBasePin Class

Segment start time.

Syntax

CRefTime m_tStart;

CBasePin.m_tStop

CBasePin Class

Segment stop time.

Syntax

CRefTime m_tStop;

CBasePin.m_dRate

CBasePin Class

Segment rate.

Syntax

double m_dRate;

CBasePin::Active

CBasePin Class

Notifies the pin that the filter is now active.

Syntax

virtual HRESULT Active(void);

Return Value

Returns S_OK.

Remarks

When the filter goes from stopped to paused, the CBaseFilter class calls this method on all of the filter's connected pins.

This method does nothing in the base class. Derived classes can override this method; for example, a pin might commit allocators or obtain hardware resources.

The filter graph manager's internal state is not updated until after this member function returns, so do not test the state from this method.

CBasePin::AgreeMediaType

CBasePin Class

Searches for a media type to make a pin connection.

Syntax

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

Parameters

pReceivePin
Pointer to the receiving pin's IPin interface.
pmt
Pointer to a CMediaType object that specifies a media type, or NULL.

Return Value

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

S_OKSuccess.
VFW_E_NO_ACCEPTABLE_TYPESNo acceptable media type was found.

Remarks

If the pmt parameter is non-NULL and fully specifies a media type, this method attempts a connection using that media type. If the attempt fails, the method returns an error.

If the pmt parameter is NULL or specifies a partial media type, this method tries media types in the following order:

  1. The receiving pin's preferred media types.
  2. This pin's preferred media types.

Preferred media types are enumerated with the EnumMediaTypes method, and the resulting enumerator is passed to the TryMediaTypes method.

CBasePin::AttemptConnection

CBasePin Class

Connects to another pin using a specified media type.

Syntax

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

Parameters

pReceivePin
Pointer to the receiving pin's IPin interface.
pmt
Pointer to a CMediaType object that specifies the media type.

Return Value

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

S_OKSuccess.
VFW_E_TYPE_NOT_ACCEPTEDThe media type is not acceptable.

Remarks

This method attempts to connect the two pins with a specific media type. If the type is not acceptable, the method fails without trying other media types.

If the media type is acceptable, this method calls the receiving pin's IPin::ReceiveConnection method. Then it calls the CompleteConnect method to complete the connection.

CBasePin::BreakConnect

CBasePin Class

Releases the pin from a connection.

Syntax

virtual HRESULT BreakConnect(void);

Return Value

Returns S_OK.

Remarks

This method is called during pin disconnection by the Disconnect method. It is also called during a connection attempt if the CheckConnect method fails.

This method must free any resources that were obtained by the CheckConnect method. For example, if CheckConnect allocates memory, BreakConnect should free the memory. If CheckConnect queries the connecting pin for an interface, BreakConnect should free the interface.

CBasePin::CanReconnectWhenActive

CBasePin Class

Queries whether the pin supports dynamic reconnections.

Syntax

bool CanReconnectWhenActive(void);

Return Value

Returns a Boolean value that specifies whether the pin can dynamically reconnect. If TRUE, the pin can dynamically reconnect.

Remarks

By default, you must stop a filter before reconnecting any of its pins. If a pin supports dynamic reconnection, however, it can reconnect while the filter is active. For more information, see Dynamic Graph Building.

CBasePin::CBasePin

CBasePin Class

Constructor method.

Syntax

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

Parameters

pObjectName
String containing the debug name for 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. 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. Initialize the value to S_OK before creating the object. The value is changed only if an error occurs.
pName
Unicode™ string containing the name of the pin. For more information, see QueryPinInfo.
dir
Member of the PIN_DIRECTION enumeration specifying the direction of the pin.

Remarks

The critical section specified by pLock serializes the pin's state, including its connection status, choice of allocator, media type, and the status of flush operations. Do not use this critical section to serialize streaming operations. For more information, see Data Flow in the Filter Graph.

A filter might create pins in its constructor method, so at this point the pFilter pointer might not refer to a valid object. Store the pointer, but do not dereference it while inside the pin's constructor.

CBasePin::~CBasePin

CBasePin Class

Destructor method.

Syntax

CBasePin(void);

CBasePin::CheckConnect

CBasePin Class

Determines whether a pin connection is suitable.

Syntax

virtual HRESULT CheckConnect(
    IPin *pPin
);

Parameters

pPin
Pointer to the other pin's IPin interface.

Return Value

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

S_OKSuccess.
VFW_E_INVALID_DIRECTIONPin directions are not compatible.

Remarks

This method is called on both pins at the start of the connection process. The connecting pin calls it from within the CBasePin::Connect method, and the receiving pin calls it from within the CBasePin::ReceiveConnection method.

Use this method to determine whether the pin specified by the pPin parameter is suitable for a connection. The base class returns an error if both pins have the same direction (both input, or both output). Derived classes can override this method to verify other features in the pin. For example, the CBaseOutputPin class queries the input pin for its IMemInputPin interface.

If this method fails, the connection fails and the pin calls the BreakConnect method. Use BreakConnect to free any resources obtained in CheckConnect. For example, if CheckConnect calls the QueryInterface method, BreakConnect must release the interface.

CBasePin::CheckMediaType

CBasePin Class

Determines if the pin accepts a specific media type.

Syntax

virtual HRESULT CheckMediaType(
    const CMediaType *pmt
) PURE;

Parameters

pmt
Pointer to a CMediaType object that contains the proposed media type.

Return Value

Returns S_OK if the proposed media type is acceptable. Otherwise, returns S_FALSE or an error code.

Remarks

The derived class must override this pure virtual method.

CBasePin::CompleteConnect

CBasePin Class

Completes a connection to another pin.

Syntax

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

Parameters

pReceivePin
Pointer to the other pin's IPin interface.

Return Value

Returns S_OK.

Remarks

This method is called on both pins at the end of the connection process. The connecting pin calls it from within the CBasePin::Connect method, and the receiving pin calls it from within the CBasePin::ReceiveConnection method.

In the base class, this method simply returns S_OK. If a derived class has any requirements for completing a connection, it should override this method. For example, the CBaseOutputPin class uses this method to decide the memory allocator.

If this method fails, the overall connection attempt also fails, and the pin disconnects from the receiving pin.

CBasePin::Connect

CBasePin Class

Connects the pin to another pin. Implements the IPin::Connect method.

Syntax

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

Parameters

pReceivePin
Pointer to the receiving pin's IPin interface.
pmt
Pointer to an AM_MEDIA_TYPE structure that specifies the media type for the connection.

Return Value

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

S_OKSuccess.
VFW_E_ALREADY_CONNECTEDThe pin is already connected.
VFW_E_NO_ACCEPTABLE_TYPESCould not find an acceptable media type.
VFW_E_NOT_STOPPEDThe filter is active and the pin does not support dynamic reconnection.
VFW_E_TYPE_NOT_ACCEPTEDThe specified media type is not acceptable.

Remarks

The pmt parameter can be NULL. It can also specify a partial media type, with a value of GUID_NULL for the major type, subtype, or format.

In the base class, this method tests whether the pin is already connected and whether the filter is stopped. It delegates the rest of the connection process to the AgreeMediaType method.

CBasePin::ConnectedTo

CBasePin Class

Retrieves a pointer to the connected pin, if any. Implements the IPin::ConnectedTo method.

Syntax

HRESULT ConnectedTo(
    IPin **ppPin
);

Parameters

ppPin
Address of a variable that receives a pointer to the IPin interface of the other pin.

Return Value

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

S_OKSuccess.
E_POINTERNULL pointer argument.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

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

CBasePin::ConnectionMediaType

CBasePin Class

Retrieves the media type for the current pin connection, if any. Implements the IPin::ConnectionMediaType method.

Syntax

HRESULT ConnectionMediaType(
    AM_MEDIA_TYPE *pmt
);

Parameters

pmt
Pointer to an AM_MEDIA_TYPE structure that receives the media type.

Return Value

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

S_OKSuccess.
E_POINTER Null pointer argument.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

If the pin is connected, this method copies the media type into the AM_MEDIA_TYPE structure specified by pmt. The caller must free the media type's format block. You can use the Microsoft® Win32® CoTaskMemFree function, or the FreeMediaType helper function.

If the pin is not connected, this method zeroes the memory block specified by pmt and returns an error code.

CBasePin::CurrentRate

CBasePin Class

Retrieves the segment rate, set by the CBasePin::NewSegment method.

Syntax

double CurrentRate(void);

Return Value

Returns the value of m_dRate.

CBasePin::CurrentStartTime

CBasePin Class

Retrieves the segment start time, set by the CBasePin::NewSegment method.

Syntax

REFERENCE_TIME CurrentStartTime(void);

Return Value

Returns the value of m_tStart.

CBasePin::CurrentStopTime

CBasePin Class

Retrieves the segment stop time, set by the CBasePin::NewSegment method.

Syntax

REFERENCE_TIME CurrentStopTime(void);

Return Value

Returns the value of m_tStop.

CBasePin::Disconnect

CBasePin Class

Breaks the current pin connection. Implements the IPin::Disconnect method.

Syntax

HRESULT Disconnect(void);

Return Value

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

S_FALSEThe pin was not connected.
S_OKSuccess.
VFW_E_NOT_STOPPEDThe filter is active and the pin does not support dynamic reconnection.

Remarks

The base class delegates most of the work to the DisconnectInternal method.

CBasePin::DisconnectInternal

CBasePin Class

Breaks the current pin connection.

Syntax

HRESULT DisconnectInternal(void);

Return Value

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

S_FALSEThe pin was not connected.
S_OKSuccess.
VFW_E_NOT_STOPPEDThe filter is active and the pin does not support dynamic reconnection.

Remarks

The Disconnect method delegates the disconnect process to this method. This method calls the BreakConnect method. It also releases the reference count on the other pin, which is held by the m_Connected member variable.

CBasePin::DisplayPinInfo

CBasePin Class

Traces a pin connection during debugging.

Syntax

void DisplayPinInfo(
    IPin *pReceivePin
);

Parameters

pReceivePin
Pointer to the receiving pin.

Remarks

In debug builds, this method calls the DbgLog function to trace a connection attempt. In retail builds, this method does nothing.

CBasePin::DisplayTypeInfo

CBasePin Class

Displays media type information during debugging.

Syntax

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

Parameters

pPin
Ignored.
pmt
Pointer to a CMediaType object that specifies the media type.

Remarks

In debug builds, this method calls the DbgLog function to display the specified media type. In retail builds, this method does nothing.

CBasePin::EndOfStream

IPin Interface

Notifies the pin that no additional data is expected. Implements the IPin::EndOfStream method. Call this method only on input pins.

Syntax

HRESULT EndOfStream(void);

Return Value

Returns S_OK.

Remarks

The filter should pass end-of-stream notifications downstream, to the input pins of connected filters. If the filter is a renderer, it should post an EC_COMPLETE event notification to the filter graph manager. For more information, see Data Flow in the Filter Graph.

In the base class, this method does nothing. Derived classes should override this method.

CBasePin::EnumMediaTypes

CBasePin Class

Enumerates the pin's preferred media types. Implements the IPin::EnumMediaTypes method.

Syntax

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

Parameters

ppEnum
Address of a variable that receives a pointer to the IEnumMediaTypes interface.

Return Value

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

S_OKSuccess.
E_OUTOFMEMORY Insufficient memory.
E_POINTER NULL pointer argument.

Remarks

Input pins are not required to enumerate any preferred types. Output pins must enumerate at least one preferred type. Otherwise, both pins could lack a preferred type, making a connection impossible.

The IEnumMediaTypes interface works like a standard COM enumerator. For more information, see Enumerating Objects in a Filter Graph. If the method succeeds, the IEnumMediaTypes interface has an outstanding reference count. Be sure to release it when you are done.

The CEnumMediaTypes base class implements IEnumMediaTypes. It calls the pin's CBasePin::GetMediaType method to enumerate the media types.

CBasePin::GetConnected

CBasePin Class

Retrieves the pin connected to this pin.

Syntax

IPin *GetConnected(void);

Return Value

Returns a pointer to the other pin's IPin interface.

Remarks

If the pin is not connected, this method returns NULL. Call the CBasePin::IsConnected method to determine whether the pin is connected.

CBasePin::GetMediaType

CBasePin Class

Retrieves a preferred media type, by index value.

Syntax

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

Parameters

iPosition
Zero-based index value.
pMediaType
Pointer to a CMediaType object that receives the media type.

Return Value

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

S_OK Success.
VFW_S_NO_MORE_ITEMSIndex out of range.
E_INVALIDARGIndex less than zero.
E_UNEXPECTEDUnexpected error.

Remarks

From the pin's list of preferred media types, this method returns the type with an index value of iPosition. The CEnumMediaTypes class calls this method to enumerate preferred media types.

The base class returns E_UNEXPECTED. Override this method in your derived class.

CBasePin::GetMediaTypeVersion

CBasePin Class

Retrieves a version number for the set of preferred media types.

Syntax

virtual LONG GetMediaTypeVersion(void);

Return Value

Returns the m_TypeVersion member variable.

Remarks

The CBasePin constructor initializes the version number to 1. In the base class, this number never changes. If the pin dynamically changes its list of preferred media types, it should increment the version number whenever the list changes. To increment the version number, call the IncrementTypeVersion method.

The media type enumerator, which is implemented by the CEnumMediaTypes class, uses the version number to keep itself synchronized with the pin.

CBasePin::Inactive

CBasePin Class

Notifies the pin that the filter is no longer active.

Syntax

virtual HRESULT Inactive(void);

Return Value

Returns S_OK.

Remarks

When the filter stops, the CBaseFilter class calls this method on all of the filter's connected pins.

This method does nothing in the base class. Derived classes should override this method to free any resources obtained by the Active method; for example, to decommit the pin's allocators.

The filter graph manager's internal state is not updated until after this method returns, so do not test the state from this method.

CBasePin::IncrementTypeVersion

CBasePin Class

Increments the version number on the set of preferred media types.

Syntax

void IncrementTypeVersion(void);

Remarks

This method increments the m_TypeVersion member variable. If the pin dynamically changes the list of preferred media types, call this method whenever the list changes. For more information, see GetMediaTypeVersion.

CBasePin::IsConnected

CBasePin Class

Determines whether the pin is connected to another pin.

Syntax

BOOL IsConnected(void);

Return Value

Returns TRUE if the pin is connected. Otherwise, returns FALSE.

CBasePin::IsStopped

CBasePin Class

Determines whether the filter containing this pin is stopped.

Syntax

BOOL IsStopped(void);

Return Value

Returns TRUE if the filter is stopped. Otherwise, returns FALSE.

Remarks

Do not call this method from within in the CBasePin constructor method, because the filter might not be initialized yet.

CBasePin::Name

CBasePin Class

Retrieves the pin identifier.

Syntax

LPWSTR Name(void);

Return Value

Returns the value of the m_pName member variable.

CBasePin::NewSegment

CBasePin Class

Notifies the pin that media samples received after this call are grouped as a segment. Implements the IPin::NewSegment method.

Syntax

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

Parameters

tStart
Starting media position of the segment, in 100-nanosecond units.
tStop
End media position of the segment, in 100-nanosecond units.
dRate
Rate at which this segment should be processed, as a percentage of the original rate.

Return Value

Returns S_OK.

Remarks

This method sets the m_tStart, m_tStop, and m_dRate member variables. In your derived class, override this method to pass the notification downstream.

CBasePin::Notify

CBasePin 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 IBaseFilter interface of the filter that delivered the quality-control message.
q
Quality structure that contains the quality-control message.

Return Value

The base class returns E_NOTIMPL.

Remarks

Output pins should override this method to accept quality-control messages.

If an external quality manager was installed (see SetSink), pass the message to that quality manager. Otherwise, the filter should handle the message itself, or pass the message upstream. For more information, see Quality-Control Management.

CBasePin::QueryAccept

CBasePin Class

Determines whether the pin accepts a specified media type. Implements the IPin::QueryAccept method.

Syntax

HRESULT QueryAccept(
    const AM_MEDIA_TYPE *pmt
);

Parameters

pmt
Pointer to an AM_MEDIA_TYPE structure that specifies the media type.

Return Value

Returns S_TRUE if the media type is acceptable. Otherwise, returns S_FALSE.

Remarks

In the base class, this method delegates to the CheckMediaType method. If CheckMediaType fails, QueryAccept returns S_FALSE.

This method does not hold the pin's critical section (m_pLock). If your derived class dynamically modifies the set of acceptable media types, you should override this method to hold the critical section.

CBasePin::QueryDirection

CBasePin Class

Retrieves the direction of the pin (input or output). Implements the IPin::QueryDirection method.

Syntax

HRESULT QueryDirection(
    PIN_DIRECTION *pPinDir
);

Parameters

pPinDir
Pointer to a variable that receives a member of the PIN_DIRECTION enumerated type.

Return Value

Returns S_OK or E_POINTER.

CBasePin::QueryId

CBasePin Class

Retrieves the pin identifier. Implements the IPin::QueryId method.

Syntax

HRESULT QueryId(
    LPWSTR *Id
);

Parameters

Id
Pointer to the pin identifier.

Return Value

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

S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNull pointer argument.

Remarks

This method returns a copy of the m_pName member variable.

CBasePin::QueryInternalConnections

CBasePin Class

Retrieves the pins that are connected internally to this pin (within the filter). Implements the IPin::QueryInternalConnections method.

Syntax

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

Parameters

apPin
Address of an array of IPin pointers.
nPin
On input, specifies the size of the array. When the method returns, the value is set to the number of pointers returned in the array.

Return Value

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

S_FALSEInsufficient array size.
S_OKSuccess.
E_FAILFailure.
E_NOTIMPLNot implemented.

The base class returns E_NOTIMPL.

Remarks

On some filters, input pins correspond to particular output pins. For each pin, this method fills an array with pointers to the corresponding pins. If every input pin provides data for every output pin, return E_NOTIMPL.

CBasePin::QueryPinInfo

CBasePin Class

Retrieves information about the pin. Implements the IPin::QueryPinInfo method.

Syntax

HRESULT QueryPinInfo(
    PIN_INFO *pInfo
);

Parameters

pInfo
Pointer to a PIN_INFO structure that receives the pin information.

Return Value

Returns S_OK or E_POINTER.

Remarks

This method uses the m_pName member variable for the achName member of the PIN_INFO structure.

When the method returns, if the pFilter member of the PIN_INFO structure is non-NULL, it has an outstanding reference count. Be sure to release the interface when you are done.

CBasePin::ReceiveConnection

CBasePin Class

Accepts a connection from another pin. Implements the IPin::ReceiveConnection method.

Syntax

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

Parameters

pConnector
Pointer to the connecting pin's IPin interface.
pmt
Pointer to an AM_MEDIA_TYPE structure that specifies the media type.

Return Value

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

S_OKSuccess.
E_POINTER Null pointer argument.
VFW_E_ALREADY_CONNECTEDThe pin is already connected.
VFW_E_NOT_STOPPEDThe filter is active and the pin does not support dynamic reconnection.
VFW_E_TYPE_NOT_ACCEPTEDThe specified media type is not acceptable.

Remarks

The pin that initiates the connection calls this method on the receiving pin. If the receiving pin returns an error code, the connection fails.

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

If all of these steps succeed, the method calls the CompleteConnect and SetMediaType methods to complete the connection. If CheckConnect or CheckMediaType fail, the method calls the BreakConnect method.

CBasePin::Run

CBasePin Class

Notifies the pin that the filter is now running.

Syntax

HRESULT Run(
    REFERENCE_TIME tStart
);

Parameters

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

Return Value

Returns S_OK.

Remarks

When the filter goes from paused to running, the CBaseFilter class calls this method on all of the filter's pins.

This method does nothing in the base class. Derived classes can override this method. For example, a pin might start a worker thread that delivers samples.

The filter graph manager's internal state is not updated until after this member function returns, so do not test the state from this method.

CBasePin::SetMediaType

CBasePin Class

Sets the media type for the connection.

Syntax

virtual HRESULT SetMediaType(
    const CMediaType *pmt
);

Parameters

pmt
Pointer to a CMediaType object that specifies the media type.

Return Value

Returns S_OK.

Remarks

This method establishes the format for a pin connection. Before calling this method, the pin calls the CBasePin::CheckMediaType method to determine whether the media type is acceptable. Therefore, the pmt parameter is assumed to be an acceptable media type.

In the base class, this method sets the m_mt member variable and returns S_OK. A derived class can override this method if it requires notification when the media type is set.

CBasePin::SetReconnectWhenActive

CBasePin Class

Specifies whether the pin supports dynamic reconnections.

Syntax

void SetReconnectWhenActive(
    bool bCanReconnect
);

Parameters

bCanReconnect
Boolean value that specifies whether the pin can dynamically reconnect. If TRUE, the pin can dynamically reconnect.

Remarks

By default, you must stop a filter before reconnecting any of its pins. If the pin can reconnect while the filter is active, call this method with a value of TRUE. For more information, see Dynamic Graph Building.

CBasePin::SetSink

CBasePin Class

Sets an external quality manager. Implements the IQualityControl::SetSink method.

Syntax

HRESULT SetSink(
    IQualityControl *piqc
);

Parameters

piqc
Pointer to the IQualityControl interface of the quality manager.

Return Value

Returns S_OK.

Remarks

Call this method to redirect quality-control messages to an external quality manager. For more information, see Quality-Control Management.

CBasePin::TryMediaTypes

CBasePin Class

Given a list of media types, tries to complete a connection using one of those types.

Syntax

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

Parameters

pReceivePin
Pointer to the receiving pin's IPin interface.
pmt
Pointer to a CMediaType object that limits the possible media types, or NULL.
pEnum
Pointer to an IEnumMediaTypes interface, used to enumerate the list of media types.

Return Value

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

S_OKSuccess.
VFW_E_NO_ACCEPTABLE_TYPESDid not find an acceptable media type.

Remarks

For each media type returned by the IEnumMediaTypes interface, this method attempts a connection by calling the AttemptConnection method.

If the pmt parameter is non-NULL, the pin skips media types that do not match this type. The pmt parameter can specify a partial media type. A partial media type has a value of GUID_NULL for either the major type, the subtype, or the format. The GUID_NULL value matches any type, similar to a "wildcard" value.