CBaseFilter Class

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_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

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.
ReconnectPin	Requests pin for a reconnect.

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.

---

CBaseFilter::CBaseFilter

CBaseFilter Class

Constructs a CBaseFilter object.

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

Parameters

pName

Pointer to an object description.

pUnk

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 Values

No return value.

---

CBaseFilter::EnumPins

CBaseFilter Class

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

HRESULT EnumPins(
  IEnumPins ** ppEnum
  );

Parameters

ppEnum

Pointer to the IEnumPins interface to retrieve.

Return Values

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.

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

Parameters

Id

Identifier of the pin.

ppPin

Pointer to the IPin interface for this pin after the filter has been restored.

Return Values

The default implementation by this member function 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).

HRESULT GetClassID(
  CLSID *pClsID
  );

Parameters

pClsID

Pointer to the class identifier to be filled out.

Return Values

Return NOERROR.

---

CBaseFilter::GetFilterGraph

CBaseFilter Class

Retrieves the filter graph associated with the filter.

IFilterGraph *GetFilterGraph( );

Return Values

Returns the value of m_pGraph.

---

CBaseFilter::GetPin

CBaseFilter Class

Retrieves a CBasePin object on the filter.

virtual CBasePin *GetPin(
  int n
  ) PURE;

Parameters

n

Number of the specified pin.

Return Values

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.

virtual int GetPinCount( ) PURE;

Return Values

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.

virtual long GetPinVersion( );

Return Values

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.

virtual LPAMOVIESETUP_FILTER GetSetupData( );

Return Values

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.

HRESULT GetState(
  DWORD dwMilliSecsTimeout,
  FILTER_STATE * State
  );

Parameters

dwMilliSecsTimeout

Duration of the time-out, in milliseconds.

State

Holds the returned state of the filter.

Return Values

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.

HRESULT GetSyncSource(
  IReferenceClock ** pClock
  );

Parameters

pClock

Pointer to a reference clock; will be set to the IReferenceClock interface.

Return Values

Returns an HRESULT value.

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.

void IncrementPinVersion( );

Return Values

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.

BOOL IsActive(void);

Return Values

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.

HRESULT JoinFilterGraph(
  IFilterGraph * pGraph,
  LPCWSTR pName
  );

Parameters

pGraph

Pointer to the filter graph to join.

pName

[in, string] Name of the filter being added.

Return Values

No return value.

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.

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

Parameters

riid

Reference identifier.

ppv

Pointer to the interface.

Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the 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.

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 Values

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.

HRESULT Pause (void);

Return Values

Returns an HRESULT value.

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.

HRESULT QueryFilterInfo(
  FILTER_INFO * pInfo
  );

Parameters

pInfo

Pointer to a FILTER_INFO structure to fill in.

Return Values

Returns an HRESULT value.

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.

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.

---

CBaseFilter::QueryVendorInfo

CBaseFilter Class

Retrieves a vendor information string.

HRESULT QueryVendorInfo(
  LPWSTR * pVendorInfo
  );

Parameters

pVendorInfo

Pointer to a string containing vendor information.

Return Values

Returns an HRESULT value (E_NOTIMPL by default).

Remarks

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.

---

CBaseFilter::ReconnectPin

CBaseFilter Class

Requests pin for a reconnect.

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

Parameters

pPin

Pointer to the pin to reconnect.

pmt

AM_MEDIA_TYPE media type to reconnect with. This can be NULL.

Return Values

Returns an HRESULT value.

Remarks

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

---

CBaseFilter::Register

CBaseFilter Class

Adds the filter to the registry.

HRESULT Register( );

Return Values

Returns an HRESULT value.

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.

HRESULT Run (
  REFERENCE_TIME tStart
  );

Parameters

tStart

Reference time value corresponding to stream time 0.

Return Values

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.

HRESULT SetSyncSource (
  IReferenceClock * pClock
  );

Parameters

pClock

Pointer to the IReferenceClock interface.

Return Values

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.

HRESULT Stop(void);

Return Values

Returns an HRESULT value.

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.

virtual HRESULT StreamTime(
  CRefTime& rtStream
  );

Parameters

rtStream

Current stream time.

Return Values

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.

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.

HRESULT Unregister( );

Return Values

Returns an HRESULT value.

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.

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

Top of Page