Index Topic Contents | |||
Previous Topic: CBaseDispatch Class Next Topic: CBaseInputPin Class |
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 Class
CBaseFilter::CBaseFilterConstructs 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 Class
CBaseFilter::EnumPinsRetrieves 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 Class
CBaseFilter::FindPinRetrieves 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 Class
CBaseFilter::GetClassIDFills 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 Class
CBaseFilter::GetFilterGraphRetrieves the filter graph associated with the filter.
IFilterGraph *GetFilterGraph( );
Return Values
Returns the value of m_pGraph.
CBaseFilter Class
CBaseFilter::GetPinRetrieves 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 Class
CBaseFilter::GetPinCountRetrieves 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 Class
CBaseFilter::GetPinVersionRetrieves 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 Class
CBaseFilter::GetSetupDataRetrieves 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 Class
CBaseFilter::GetStateRetrieves 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 Class
CBaseFilter::GetSyncSourceRetrieves 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 Class
CBaseFilter::IncrementPinVersionAdds 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 Class
CBaseFilter::IsActiveDetermines 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 Class
CBaseFilter::JoinFilterGraphNotifies 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 Class
CBaseFilter::NonDelegatingQueryInterfaceRetrieves 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 Class
CBaseFilter::NotifyEventSends 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 Class
CBaseFilter::PauseTransitions 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 Class
CBaseFilter::QueryFilterInfoRetrieves 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 Class
CBaseFilter::QueryVendorInfoRetrieves 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 Class
CBaseFilter::ReconnectPinRequests 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 Class
CBaseFilter::RegisterAdds 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 Class
CBaseFilter::RunTransitions 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 Class
CBaseFilter::SetSyncSourceIdentifies 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 Class
CBaseFilter::StopTransitions 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 Class
CBaseFilter::StreamTimeRetrieves 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 Class
CBaseFilter::UnregisterRemoves 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.