CBaseFilter is an abstract base class from which all filters are derived. It supports the Component Object Model (COM) IBaseFilter interface and is derived from the CUnknown class. This class supports the enumeration of pins by calling the pure virtual member functions CBaseFilter::GetPin and GetPinCount. These member functions must be overridden by any derived class.
The CBaseFilter class assumes that all the filter's pins are derived from the CBasePin class. CBaseFilter::GetPin must return a pointer to CBasePin.
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_pName | Filter name. |
m_PinVersion | Current version of the pins used on the filter. |
m_tStart | Offset from the stream time to the reference time. |
m_State | Current state: running or paused. |
m_pClock | Filter graph's reference clock. |
m_pGraph | Pointer to a graph to which this filter belongs. |
m_pLock | Pointer to the critical section used for locking. |
m_pSink | Pointer to the IMediaEventSink interface on the filter graph manager. |
m_clsid | Class identifier (CLSID) used for serialization using IPersist. |
Member Functions
Name | Description |
CBaseFilter | Constructs a CBaseFilter object. |
GetFilterGraph | Returns the filter graph associated with the filter. This is used in the implementation of CEnumPins. |
IncrementPinVersion | Adds 1 to the pin version stored in m_PinVersion. |
IsActive | Determines if the filter is currently active (running or paused) or stopped. |
NotifyEvent | Sends an event notification to the filter graph. |
Overridable Member Functions
Name | Description |
GetPin | Returns a pointer to the requested pin. |
GetPinCount | Returns the number of pins currently available on this object. |
GetPinVersion | Returns the current version of the base filter for comparison with the version with which the pin was initialized. This member function can be overridden if pins are being created dynamically. |
GetSetupData | Retrieves the registration data associated with the filter. |
StreamTime | Returns the current stream time. |
Implemented IPersist Methods
Name | Description |
GetClassID | Returns the class identifier of this filter. |
Implemented IMediaFilter Methods
Name | Description |
GetState | Retrieves the current state of the filter. |
GetSyncSource | Retrieves the current reference clock in use by this filter. |
Pause | Instructs the filter to transition to State_Paused state. |
Run | Instructs the filter to transition to State_Running state. Passes a time value to synchronize independent streams. |
SetSyncSource | Informs the filter of the reference clock with which it should synchronize activity. |
Stop | Instructs the filter to transition to the State_Stopped state. |
Implemented IBaseFilter Methods
Name | Description |
EnumPins | Provides an enumerator for this pin's preferred media types (implemented by this class). |
FindPin | Retrieves the pin with the specified identifier. |
JoinFilterGraph | Notifies a filter that it has joined a filter graph (implemented by this class). |
QueryFilterInfo | Gets information about the specified filter (implemented by this class). |
QueryVendorInfo | Retrieves optional information supplied by a vendor for the specified filter. |
Implemented IAMovieSetup Methods
Name | Description |
Register | Adds the filter to the registry. |
Unregister | Removes the filter from the registry. |
Implemented INonDelegatingUnknown Methods
Name | Description |
NonDelegatingQueryInterface | Passes out pointers to any interfaces added to the derived filter class. |
Constructs a CBaseFilter object.
CBaseFilter(
TCHAR *pName,
LPUNKNOWN pUnk,
CCritSec *pLock,
REFCLSID clsid
);
No return value.
Retrieves an IEnumPins pointer that can be used to enumerate all the pins available on this filter.
HRESULT EnumPins(
IEnumPins ** ppEnum
);
Returns an HRESULT value.
This member function implements the IBaseFilter::EnumPins method. It uses the CEnumPins object to construct an enumerator and retrieves the IEnumPins interface from the CEnumPins object. The implementation of CEnumPins::Next calls the CBaseFilter::GetPin member function, which the derived class must provide. The IEnumPins interface is used by the filter graph manager when adding the filter to the filter graph.
Retrieves the pin with the specified identifier.
HRESULT FindPin(
LPCWSTR Id,
IPin **ppPin
);
The default implementation by this member function returns S_OK if the pin name was found or VFW_E_NOT_FOUND otherwise.
This member function provides a base class definition of the IBaseFilter::FindPin method that, along with the IPin::QueryId method, is used to implement persistent filter graphs. A filter must be able to translate the IPin interface pointers to its pins into identifiers that can be saved along with the configuration of the filter graph. It does this by using the IPin::QueryId method. It must then be able to convert those identifiers back into IPin interface pointers when the filter and its connections are restored as part of a persistent filter graph. This is accomplished using the IBaseFilter::FindPin method.
By default, the base classes use the pin name in the CBasePin::m_pName data member, so implementing this member function in your derived filter class is not normally required.
The ppPin parameter is set to NULL if the identifier cannot be matched.
Fills the pClsID parameter with the class identifier of this filter (from m_clsid).
HRESULT GetClassID(
CLSID *pClsID
);
Returns an HRESULT value.
Retrieves the filter graph associated with the filter.
IFilterGraph *GetFilterGraph( );
Returns the value of m_pGraph.
Retrieves a CBasePin object on the filter.
virtual CBasePin *GetPin(
int n
) PURE;
Returns a pointer to the pin specified by the n parameter.
Override this member function to return a pointer to the nth pin on this filter. CBaseFilter adds a reference to it, when necessary, before passing it to any other object. This member function is called by the base class CEnumPins::Next member function to retrieve pins for the IEnumPins interface, which is used by the filter graph manager.
Retrieves the number of supported pins.
virtual int GetPinCount( ) PURE;
Returns the pin count.
Override this member function to return the count of pins currently available on this object.
Retrieves the version number of the pin.
virtual long GetPinVersion( );
By default, returns the value of m_PinVersion. If overridden, this member function should return the pin version number.
Returns the current version of the filter that matches the version used to initialize the pin. The enumerator calling this member function performs the matching.
A filter provides an enumerator to gain access to the input and output pins it keeps. Each time a pin enumerator's method is called, the pin enumerator calls the CBaseFilter::GetPinVersion member function to ensure that the base filter's version matches the version with which the pin enumerator was initialized.
A filter class can override CBaseFilter::GetPinVersion if there is a need to increment the version by changing the available pins dynamically. Or, it can more easily call IncrementPinVersion.
GetPinVersion does not lock the filter because the enumerators are designed to be separate objects. The derived class's GetPinVersion will likely have to do some specialized locking with the part of the object responsible for creating and deleting pins.
Retrieves the registration data associated with the filter.
virtual LPAMOVIESETUP_FILTER GetSetupData( );
Returns a pointer to an AMOVIESETUP_FILTER structure containing registration information for the filter.
You must override this member function and implement it to return an AMOVIESETUP_FILTER structure containing its associated AMOVIESETUP_PIN and AMOVIESETUP_MEDIATYPE structures for pin and media type information. This member function is called from the CBaseFilter::Register member function.
Retrieves the current state of the filter.
HRESULT GetState(
DWORD dwMilliSecsTimeout,
FILTER_STATE * State
);
Returns S_OK.
This member function implements the IMediaFilter::GetState method. It returns the value of the m_State data member. Override this member function if the state changes in your filter are not synchronous.
Retrieves the current reference clock in use by this filter.
HRESULT GetSyncSource(
IReferenceClock ** pClock
);
Returns an HRESULT value.
This member function implements the IMediaFilter::GetSyncSource method. It returns the value of m_pClock after adding a reference to it. Be sure to release the interface by calling the IUnknown::Release method when finished with the pointer.
Adds 1 to the version number of the pin.
void IncrementPinVersion( );
No return value.
By default, increments the value of m_PinVersion.
Determines if the filter is currently active (running or paused) or stopped.
BOOL IsActive(void);
Returns TRUE if the filter is paused or running, or FALSE if the filter is stopped.
Notifies a filter that it has joined a filter graph.
HRESULT JoinFilterGraph(
IFilterGraph * pGraph,
LPCWSTR pName
);
No return value.
This member function implements the IBaseFilter::JoinFilterGraph method. It assigns the pGraph filter graph pointer to the m_pGraph data member and obtains the IMediaEventSink interface from the filter graph manager to allow the filter to post event notifications to the filter graph manager.
The filter should store the IMediaEventSink interface for later use, because it might need to notify the interface about events, but it should not increase the reference count on the filter graph manager object. A null pointer indicates that the filter is no longer part of a graph.
Retrieves an interface and increments the reference count.
HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);
Returns a pointer to the interface.
This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IBaseFilter, IMediaFilter, IPersist, IAMovieSetup, and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.
Sends an event notification to the filter graph.
HRESULT NotifyEvent(
long EventCode,
long EventParam1,
long EventParam2
);
Returns S_OK if delivered, S_FALSE if the filter graph does not sink events, or an error otherwise.
For a list of notification codes and event parameter values, see Event Notification Codes.
Transitions the filter to State_Paused state if it is not in this state already.
HRESULT Pause (void);
Returns an HRESULT value.
This member function implements the IMediaFilter::Pause method. If the filter is in State_Stopped state, the CBasePin::Active member function is called for each of the filter's pins to which it is connected. If this member function succeeds, the filter's m_State member variable is set to State_Paused. If any pin returns a failure return value from its Active method, the function fails and the state is not changed.
This member function holds the filter's lock.
Retrieves information about the filter.
HRESULT QueryFilterInfo(
FILTER_INFO * pInfo
);
Returns an HRESULT value.
This member function implements the IBaseFilter::QueryFilterInfo method. It copies the filter's name from m_pName, and copies the pointer to the filter graph interface from m_pGraph into the FILTER_INFO structure before returning.
Note that the IFilterGraph interface passed out by this member function is reference counted, and so must be released when the caller has finished with it.
Retrieves a vendor information string.
HRESULT QueryVendorInfo(
LPWSTR * pVendorInfo
);
Returns an HRESULT value (E_NOTIMPL by default).
This member function implements the IBaseFilter::QueryVendorInfo method, but only to return E_NOTIMPL. Filters that want to expose vendor information must override this member function. If implemented in a derived class, callers should free memory when they are done using it by calling the Microsoft® Win32® CoTaskMemFree function.
Adds the filter to the registry.
HRESULT Register( );
Returns an HRESULT value.
This member function implements the IAMovieSetup::Register method and registers the filter, its pins, and the media type associated with the pins. It does this by first calling GetSetupData to retrieve the setup data, and then calling the IFilterMapper::RegisterFilter, IFilterMapper::RegisterPin, and IFilterMapper::RegisterPinType methods.
Transitions the filter from paused to running state if it is not in this state already.
HRESULT Run (
REFERENCE_TIME tStart
);
Returns an HRESULT value.
If the filter is in State_Stopped state, the CBaseFilter::Pause method is called first to transition the filter to State_Paused state, which has the effect of activating any of the filter's connected pins. If any pin returns a failure return code from its Active method, the function fails and the state is not changed. If this member function succeeds, the filter's m_State member variable is set to State_Running.
This member function holds the filter's lock.
Identifies the reference clock to which the filter should synchronize activity.
HRESULT SetSyncSource (
IReferenceClock * pClock
);
Returns an HRESULT value.
This member function implements the IMediaFilter::SetSyncSource method. It sets the m_pClock data member to the pClock parameter and increments the reference count on the IReferenceClock interface passed in.
This member function is most important to rendering filters and might not apply to other filters.
Transitions the filter to State_Stopped state if it is not in this state already.
HRESULT Stop(void);
Returns an HRESULT value.
This member function implements the IMediaFilter::Stop method. It first calls the CBasePin::Inactive member function on all its pins that have a connection, and then sets the filter's m_State member variable to State_Stopped.
This member function holds the filter's lock.
Retrieves the current stream time.
virtual HRESULT StreamTime(
CRefTime& rtStream
);
Returns an HRESULT value, which can include the following values.
Value | Meaning |
E_FAIL | Unable to get time from clock. |
S_OK | Stream time returned in the rtStream parameter. |
VFW_E_NO_CLOCK | No reference clock is available. |
Current stream time is the reference clock time minus the stream time offset. All samples with time stamps less than or equal to this time should have been presented.
Removes the filter from the registry.
HRESULT Unregister( );
Returns an HRESULT value.
This member function implements the IAMovieSetup::Unregister method and calls the IFilterMapper::UnregisterFilter method to remove the filter from the registry. This effectively removes the pins and media types as well.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.