Microsoft DirectX 8.0 |
Abstract class that implements a generic pin.
Declaration: Amfilter.h
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.
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:
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.
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 State | CBasePin Method |
---|---|
Stop | Inactive |
Pause | Active |
Run | Run |
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.
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_pName | Pin name. |
m_Connected | Pointer to the pin that is connected to this pin. |
m_dir | Direction of the pin. |
m_pLock | Pointer to a critical section object. |
m_bRunTimeError | Flag that indicates whether a run-time error has occurred. |
m_bCanReconnectWhenActive | Flag that indicates whether the pin supports dynamic reconnection. |
m_bTryMyTypesFirst | Flag 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_mt | Media type for the current pin connection. |
m_tStart | Segment start time. |
m_tStop | Segment stop time. |
m_dRate | Segment rate. |
Protected Methods | |
DisplayPinInfo | Traces a pin connection during debugging. |
DisplayTypeInfo | Displays media type information during debugging. |
AttemptConnection | Connects to another pin using a specified media type. |
TryMediaTypes | Given a list of media types, tries to complete a connection using one of those types. |
AgreeMediaType | Searches for a media type to make a pin connection. |
DisconnectInternal | Breaks the current pin connection. |
Public Methods | |
CBasePin | Constructor method. |
~CBasePin | Destructor method. Virtual. |
IsConnected | Determines whether the pin is connected to another pin. |
GetConnected | Retrieves the pin that is connected to this pin. |
IsStopped | Determines whether the filter containing this pin is stopped. |
GetMediaTypeVersion | Retrieves a version number for the set of preferred media types. Virtual. |
IncrementTypeVersion | Increments the version number on the set of preferred media types. |
Active | Notifies the pin that the filter is now active. Virtual. |
Inactive | Notifies the pin that the filter is no longer active. Virtual. |
Run | Notifies the pin that the filter is now running. Virtual. |
SetMediaType | Sets the media type for the connection. Virtual. |
CheckConnect | Determines whether a pin connection is suitable. Virtual. |
BreakConnect | Releases the pin from a connection. Virtual. |
CompleteConnect | Completes a connection to another pin. Virtual. |
GetMediaType | Retrieves a preferred media type, by index value. Virtual. |
CurrentStopTime | Retrieves the segment stop time. |
CurrentStartTime | Retrieves the segment start time. |
CurrentRate | Retrieves the segment rate. |
Name | Retrieves the pin identifier. |
SetReconnectWhenActive | Specifies whether the pin supports dynamic reconnections. |
CanReconnectWhenActive | Queries whether the pin supports dynamic reconnections. |
Pure Virtual Methods | |
CheckMediaType | Determines if the pin accepts a specific media type. |
IBasePin methods | |
Connect | Connects the pin to another pin. |
ReceiveConnection | Accepts a connection from another pin. |
Disconnect | Breaks the current pin connection. |
ConnectedTo | Retrieves the pin connected to this pin. |
ConnectionMediaType | Retrieves the media type for the current pin connection, if any. |
QueryPinInfo | Retrieves information about the pin. |
QueryDirection | Retrieves the direction of the pin (input or output). |
QueryId | Retrieves the pin identifier. |
QueryAccept | Determines whether the pin accepts a specified media type. |
EnumMediaTypes | Enumerates the pin's preferred media types. |
QueryInternalConnections | Retrieves the pins that are connected internally to this pin (within the filter). |
EndOfStream | Notifies the pin that no additional data is expected. |
NewSegment | Notifies the pin that media samples received after this call are grouped as a segment. |
IQualityControl methods | |
Notify | Notifies the pin that a quality change is requested. |
SetSink | Sets an external quality manager. |
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.
Pointer to the pin that is connected to this pin.
Syntax
IPin *m_Connected;
Direction of the pin.
Syntax
PIN_DIRECTION m_dir;
Pointer to a critical section object.
Syntax
CCritSec *m_pLock;
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.
Flag that indicates whether the pin supports dynamic reconnection.
Syntax
bool m_bCanReconnectWhenActive;
Remarks
This flag defaults to FALSE.
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.
Pointer to the filter that created the pin.
Syntax
CBaseFilter *m_pFilter;
Pointer to the object that handles quality messages.
Syntax
IQualityControl *m_pQSink;
Current version of the set of preferred media types.
Syntax
LONG m_TypeVersion;
Media type for the current pin connection.
Syntax
CMediaType m_mt;
Segment start time.
Syntax
CRefTime m_tStart;
Segment stop time.
Syntax
CRefTime m_tStop;
Segment rate.
Syntax
double m_dRate;
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.
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_OK Success. VFW_E_NO_ACCEPTABLE_TYPES No 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:
- The receiving pin's preferred media types.
- 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.
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_OK Success. VFW_E_TYPE_NOT_ACCEPTED The 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.
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.
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.
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.
Destructor method.
Syntax
CBasePin(void);
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_OK Success. VFW_E_INVALID_DIRECTION Pin 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.
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.
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.
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_OK Success. VFW_E_ALREADY_CONNECTED The pin is already connected. VFW_E_NO_ACCEPTABLE_TYPES Could not find an acceptable media type. VFW_E_NOT_STOPPED The filter is active and the pin does not support dynamic reconnection. VFW_E_TYPE_NOT_ACCEPTED The 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.
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_OK Success. E_POINTER NULL pointer argument. VFW_E_NOT_CONNECTED Pin 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.
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_OK Success. E_POINTER Null pointer argument. VFW_E_NOT_CONNECTED Pin 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.
Retrieves the segment rate, set by the CBasePin::NewSegment method.
Syntax
double CurrentRate(void);
Return Value
Returns the value of m_dRate.
Retrieves the segment start time, set by the CBasePin::NewSegment method.
Syntax
REFERENCE_TIME CurrentStartTime(void);
Return Value
Returns the value of m_tStart.
Retrieves the segment stop time, set by the CBasePin::NewSegment method.
Syntax
REFERENCE_TIME CurrentStopTime(void);
Return Value
Returns the value of m_tStop.
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_FALSE The pin was not connected. S_OK Success. VFW_E_NOT_STOPPED The filter is active and the pin does not support dynamic reconnection.
Remarks
The base class delegates most of the work to the DisconnectInternal method.
Breaks the current pin connection.
Syntax
HRESULT DisconnectInternal(void);
Return Value
Returns an HRESULT value. Possible values include those in the following table.
S_FALSE The pin was not connected. S_OK Success. VFW_E_NOT_STOPPED The 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.
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.
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.
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.
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_OK Success. 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.
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.
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_ITEMS Index out of range. E_INVALIDARG Index less than zero. E_UNEXPECTED Unexpected 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.
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.
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.
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.
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.
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.
Retrieves the pin identifier.
Syntax
LPWSTR Name(void);
Return Value
Returns the value of the m_pName member variable.
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.
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.
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.
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.
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_OK Success. E_OUTOFMEMORY Insufficient memory. E_POINTER Null pointer argument.
Remarks
This method returns a copy of the m_pName member variable.
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_FALSE Insufficient array size. S_OK Success. E_FAIL Failure. E_NOTIMPL Not 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.
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.
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_OK Success. E_POINTER Null pointer argument. VFW_E_ALREADY_CONNECTED The pin is already connected. VFW_E_NOT_STOPPED The filter is active and the pin does not support dynamic reconnection. VFW_E_TYPE_NOT_ACCEPTED The 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:
- Checks whether the pin is already connected.
- Checks whether the filter is stopped.
- Calls the CheckConnect method to test whether the connecting pin is suitable.
- Calls the CheckMediaType method to test whether the media type is acceptable.
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.
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.
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.
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.
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.
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_OK Success. VFW_E_NO_ACCEPTABLE_TYPES Did 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.