The IBaseFilter interface abstracts an object that has typed input and output connections and can be aggregated dynamically. All DirectShow™ filters expose this interface.
Since the IBaseFilter interface derives from the IMediaFilter interface, it inherits IPersist.
When to Implement
Implement this interface on every DirectShow filter. It is recommended that you use the CBaseFilter class library to implement this interface.
When to Use
The filter graph manager is the primary user of this interface. Applications or other filters can use IBaseFilter methods directly to enumerate or retrieve pins or to get vendor information, but should not use any methods derived from IMediaFilter to control media streaming (use the IMediaControl methods on the filter graph manager instead).
Methods in Vtable Order
IUnknown methods | Description |
QueryInterface | Returns pointers to supported interfaces. |
AddRef | Increments the reference count. |
Release | Decrements the reference count. |
IMediaFilter methods | Description |
Stop | Informs the filter to transition to the new (stopped) state. |
Pause | Informs the filter to transition to the new (paused) state. |
Run | Informs the filter to transition to the new (running) state. |
GetState | Determines the state of the filter. |
SetSyncSource | Identifies the reference clock to which the filter should synchronize activity. |
GetSyncSource | Retrieves the current reference clock (or NULL if there is no clock). Passes a time value to synchronize independent streams. |
IBaseFilter methods | Description |
EnumPins | Enumerates the specified pins available on this filter. |
FindPin | Retrieves a pointer to the pin with the specified identifier. |
QueryFilterInfo | Retrieves information about the specified filter. |
JoinFilterGraph | Notifies a filter that it has joined a filter graph. |
QueryVendorInfo | Retrieves optional information supplied by a vendor for the specified filter. |
Enumerates all the pins available on this filter.
HRESULT EnumPins(
IEnumPins ** ppEnum
);
Returns an HRESULT value.
The interface returned by this method has had its reference count incremented. Be sure to use IUnknown::Release on the interface to decrement the reference count when you have finished using the interface.
Retrieves the pin with the specified identifier.
HRESULT FindPin(
LPCWSTR Id,
IPin **ppPin
);
Returns an HRESULT value.
This method, 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 by using the IBaseFilter::FindPin method.
The ppPin parameter is set to NULL if the identifier cannot be matched.
Notifies a filter that it has joined a filter graph.
HRESULT JoinFilterGraph(
IFilterGraph * pGraph,
LPCWSTR pName
);
Returns an HRESULT value.
The filter should store this interface for later use because it might need to notify the interface about events. The filter should not add a reference count to this interface. Doing so causes circular references and prevents the graph or the filter from ever being correctly released. The filter graph manager does hold a reference on the filter. The filter does not need to hold a reference to ensure that the interface does not disappear; it is notified of any such disappearance by a further call to IBaseFilter::JoinFilterGraph, with a null value for the pGraph parameter to indicate that the filter is no longer part of the graph.
Returns information about the filter.
HRESULT QueryFilterInfo(
FILTER_INFO * pInfo
);
Returns an HRESULT value.
The FILTER_INFO structure is defined as follows:
typedef struct _FilterInfo { [string] WCHAR achName[MAX_FILTER_NAME]; // allowed to be null IFilterGraph * pGraph; // null if not part of graph } FILTER_INFO ;
Note that on return, if the pGraph member of the FILTER_INFO structure is non-NULL, it will have an outstanding reference count and should be released when the interface is no longer needed.
Returns a vendor information string.
HRESULT QueryVendorInfo(
LPWSTR * pVendorInfo
);
Returns an HRESULT value.
This method is optional and can return E_NOTIMPL. If implemented, memory returned should be freed using the Microsoft® Win32® CoTaskMemFree function when the application is done using it.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.