CBaseFilter Class

CBaseFilter class hierarchy

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

m_clsid Class identifier (CLSID) used for serialization using IPersist.

m_pClock Filter graph's reference clock.

m_pGraph Pointer to a graph to which this filter belongs.
m_PinVersion Current version of the pins used on the filter.
m_pLock Pointer to the critical section used for locking.
m_pName Filter name.
m_pSink Pointer to the IMediaEventSink interface on the filter graph manager.
m_State Current state: running or paused.
m_tStart Offset from the stream time to the reference time.

Member Functions

CBaseFilter Constructs a CBaseFilter object.
GetFilterGraph Retrieves 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.
ReconnectPin Requests pin for a reconnect.

Overridable Member Functions

GetPin Retrieves a pointer to the requested pin.
GetPinCount Retrieves the number of pins currently available on this object.
GetPinVersion Retrieves 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 Retrieves the current stream time.

Implemented IPersist Methods

GetClassID Retrieves the class identifier of this filter.

Implemented IMediaFilter Methods

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

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

Register Adds the filter to the registry.
Unregister Removes the filter from the registry.

Implemented INonDelegatingUnknown Methods

NonDelegatingQueryInterface Passes out pointers to any interfaces added to the derived filter class.

CBaseFilter::CBaseFilter

CBaseFilter Class

Constructs a CBaseFilter object.

Syntax

CBaseFilter(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    CCritSec *pLock,
    REFCLSID clsid
    );

Parameters

pName
Pointer to an object description.
pUnk
Pointer to the IUnknown interface of the delegating object.
pLock
Pointer to an object that maintains the lock.
clsid
Class identifier to be used to serialize this filter.

Return Value

No return value.

CBaseFilter::EnumPins

CBaseFilter Class

Retrieves an IEnumPins pointer that can be used to enumerate all the pins available on this filter.

Syntax

HRESULT EnumPins(
    IEnumPins **ppEnum
    );

Parameters

ppEnum
Address of a pointer to the IEnumPins interface to retrieve.

Return Value

Returns E_OUTOFMEMORY if a new enumerate could not be created or NOERROR if successful.

Remarks

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.

CBaseFilter::FindPin

CBaseFilter Class

Retrieves the pin with the specified identifier.

Syntax

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
    );

Parameters

Id
Identifier of the pin.
ppPin
Address of a pointer to the IPin interface for this pin after the filter has been restored.

Return Value

The default implementation returns S_OK if the pin name was found or VFW_E_NOT_FOUND otherwise.

Remarks

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.

CBaseFilter::GetClassID

CBaseFilter Class

Fills the pClsID parameter with the class identifier of this filter (from m_clsid).

Syntax

HRESULT GetClassID(
    CLSID *pClsID
    );

Parameters

pClsID
Pointer to the class identifier to be filled out.

Return Value

Returns NOERROR.

CBaseFilter::GetFilterGraph

CBaseFilter Class

Retrieves the filter graph associated with the filter.

Syntax

IFilterGraph *GetFilterGraph(void);

Return Value

Returns the value of m_pGraph.

CBaseFilter::GetPin

CBaseFilter Class

Retrieves a CBasePin object on the filter.

Syntax

virtual CBasePin *GetPin(
    int n
    ) PURE;

Parameters

n
Number of the specified pin.

Return Value

Returns a pointer to the pin specified by the n parameter.

Remarks

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.

CBaseFilter::GetPinCount

CBaseFilter Class

Retrieves the number of supported pins.

Syntax

virtual int GetPinCount(void) PURE;

Return Value

Returns the pin count.

Remarks

Override this member function to return the count of pins currently available on this object.

CBaseFilter::GetPinVersion

CBaseFilter Class

Retrieves the version number of the pin.

Syntax

virtual long GetPinVersion(void);

Return Value

By default, returns the value of m_PinVersion. If overridden, this member function should return the pin version number.

Remarks

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.

CBaseFilter::GetSetupData

CBaseFilter Class

Retrieves the registration data associated with the filter.

Syntax

virtual LPAMOVIESETUP_FILTER GetSetupData(void);

Return Value

Returns a pointer to an AMOVIESETUP_FILTER structure containing registration information for the filter.

Remarks

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.

CBaseFilter::GetState

CBaseFilter Class

Retrieves the current state of the filter.

Syntax

HRESULT GetState(
    DWORD dwMilliSecsTimeout,
    FILTER_STATE *State
    );

Parameters

dwMilliSecsTimeout
Duration of the time-out, in milliseconds.
State
Pointer to the returned state of the filter.

Return Value

Returns S_OK.

Remarks

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.

CBaseFilter::GetSyncSource

CBaseFilter Class

Retrieves the current reference clock in use by this filter.

Syntax

HRESULT GetSyncSource(
    IReferenceClock **pClock
    );

Parameters

pClock
Address of a pointer to a reference clock; will be set to the IReferenceClock interface.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

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.

CBaseFilter::IncrementPinVersion

CBaseFilter Class

Adds 1 to the version number of the pin.

Syntax

void IncrementPinVersion(void);

Return Value

No return value.

Remarks

By default, increments the value of m_PinVersion.

CBaseFilter::IsActive

CBaseFilter Class

Determines if the filter is currently active (running or paused) or stopped.

Syntax

BOOL IsActive(void);

Return Value

Returns TRUE if the filter is paused or running, or FALSE if the filter is stopped.

CBaseFilter::JoinFilterGraph

CBaseFilter Class

Notifies a filter that it has joined a filter graph.

Syntax

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph,
    LPCWSTR pName
    );

Parameters

pGraph
Pointer to the filter graph to join.
pName
[in, string] Pointer to the name of the filter being added.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

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.

CBaseFilter::NonDelegatingQueryInterface

CBaseFilter Class

Retrieves an interface and increments the reference count.

Syntax

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

Parameters

riid
Reference identifier.
ppv
Address of a pointer to the interface.

Return Value

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 IBaseFilter, IMediaFilter, IPersist, IAMovieSetup, and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

CBaseFilter::NotifyEvent

CBaseFilter Class

Sends an event notification to the filter graph.

Syntax

HRESULT NotifyEvent(
    long EventCode,
    long EventParam1,
    long EventParam2
    );

Parameters

EventCode
Identifier of the event.
EventParam1
First parameter of the event.
EventParam2
Second parameter of the event.

Return Value

Returns S_OK if delivered, S_FALSE if the filter graph does not sink events, or an error otherwise.

Remarks

For a list of notification codes and event parameter values, see Event Notification Codes.

CBaseFilter::Pause

CBaseFilter Class

Transitions the filter to State_Paused state if it is not in this state already.

Syntax

HRESULT Pause(void);

Return Value

Returns S_OK if the transition is complete; otherwise, returns one of the following values.

Error value Transition failed.
S_FALSE Transition is not complete, but no error has occurred.

Remarks

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.

CBaseFilter::QueryFilterInfo

CBaseFilter Class

Retrieves information about the filter.

Syntax

HRESULT QueryFilterInfo(
    FILTER_INFO *pInfo
    );

Parameters

pInfo
Pointer to a FILTER_INFO structure to fill in.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

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.
The IFilterGraph interface passed out by this member function is reference counted, and so must be released when the caller has finished with it.

CBaseFilter::QueryVendorInfo

CBaseFilter Class

Retrieves a vendor information string.

Syntax

HRESULT QueryVendorInfo(
    LPWSTR *pVendorInfo
    );

Parameters

pVendorInfo
Pointer to a string containing vendor information.

Return Value

Returns an HRESULT value (E_NOTIMPL by default).

Remarks

This member function implements the IBaseFilter::QueryVendorInfo method, but only returns E_NOTIMPL. Filters that want to expose vendor information must override this member function. If it is implemented in a derived class, callers should free memory when they are done using it by calling the Microsoft® Win32® CoTaskMemFree function.

CBaseFilter::ReconnectPin

CBaseFilter Class

Requests pin for a reconnect.

Syntax

HRESULT ReconnectPin(
    IPin *pPin,
    AM_MEDIA_TYPE const *pmt
    );

Parameters

pPin
Pointer to the pin to reconnect.
pmt
Pointer to the AM_MEDIA_TYPE media type to reconnect with. This can be NULL.

Return Value

Returns an HRESULT value that depends on the implementation.

Remarks

This function calls the IFilterGraph2::ReconnectEx method on the filter graph.

CBaseFilter::Register

CBaseFilter Class

Adds the filter to the registry.

Syntax

HRESULT Register(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

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.

CBaseFilter::Run

CBaseFilter Class

Transitions the filter from paused to running state if it is not in this state already.

Syntax

HRESULT Run(
    REFERENCE_TIME tStart
    );

Parameters

tStart
Reference time value corresponding to stream time zero.

Return Value

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

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.

CBaseFilter::SetSyncSource

CBaseFilter Class

Identifies the reference clock to which the filter should synchronize activity.

Syntax

HRESULT SetSyncSource(
    IReferenceClock *pClock
    );

Parameters

pClock
Pointer to the IReferenceClock interface.

Return Value

Returns an HRESULT value. The default implementation returns NOERROR.

Remarks

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.

CBaseFilter::Stop

CBaseFilter Class

Transitions the filter to State_Stopped state if it is not in this state already.

Syntax

HRESULT Stop(void);

Return Value

Returns S_OK if the transition is complete; otherwise, returns one of the following values.

Error value Transition failed.
S_FALSE Transition is not complete, but no error has occurred.

Remarks

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.

CBaseFilter::StreamTime

CBaseFilter Class

Retrieves the current stream time.

Syntax

virtual HRESULT StreamTime(
    CRefTime& rtStream
    );

Parameters

rtStream
Current stream time.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

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.

Remarks

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.

CBaseFilter::Unregister

CBaseFilter Class

Removes the filter from the registry.

Syntax

HRESULT Unregister(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

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.

m_clsid	Class identifier (CLSID) used for serialization using IPersist.
m_pClock	Filter graph's reference clock.
m_pGraph	Pointer to a graph to which this filter belongs.
m_PinVersion	Current version of the pins used on the filter.
m_pLock	Pointer to the critical section used for locking.
m_pName	Filter name.
m_pSink	Pointer to the IMediaEventSink interface on the filter graph manager.
m_State	Current state: running or paused.
m_tStart	Offset from the stream time to the reference time.

CBaseFilter	Constructs a CBaseFilter object.
GetFilterGraph	Retrieves 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.
ReconnectPin	Requests pin for a reconnect.

GetPin	Retrieves a pointer to the requested pin.
GetPinCount	Retrieves the number of pins currently available on this object.
GetPinVersion	Retrieves 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	Retrieves the current stream time.

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.

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.

Register	Adds the filter to the registry.
Unregister	Removes the filter from the registry.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Error value	Transition failed.
S_FALSE	Transition is not complete, but no error has occurred.

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.