IBaseFilter Interface

The IBaseFilter interface abstracts an object that has typed input and output connections and can be aggregated dynamically. All Microsoft® DirectShow® filters expose this interface.

Because the IBaseFilter interface derives from the IMediaFilter interface, it inherits IPersist.

Implement this interface on every DirectShow filter. It is recommended that you use the CBaseFilter class library to implement this interface.

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 Retrieves 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.

IUnknown methods	Description
QueryInterface	Retrieves 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.

IBaseFilter::EnumPins

IBaseFilter Interface

Enumerates all the pins available on this filter.

Syntax

HRESULT EnumPins(
    IEnumPins **ppEnum
);

Parameters

ppEnum
[out] Address of a pointer to the IEnumPins interface to retrieve.

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

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.

IBaseFilter::FindPin

IBaseFilter Interface

Retrieves the pin with the specified identifier.

Syntax

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

Parameters

Id
[in] Identifier of the pin.
ppPin
[out] Address of a pointer to the IPin interface for this pin after the filter has been restored. The returned IPin pointer has been reference counted. The caller should use the Release method on the pointer when finished with it.

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

IBaseFilter::JoinFilterGraph

IBaseFilter Interface

Notifies a filter that it has joined a filter graph.

Syntax

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph,
    LPCWSTR pName
);

Parameters

pGraph
[in] 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

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.

IBaseFilter::QueryFilterInfo

IBaseFilter Interface

Retrieves information about the filter.

Syntax

HRESULT QueryFilterInfo(
    FILTER_INFO *pInfo
);

Parameters

pInfo
[out] Pointer to a FILTER_INFO structure.

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

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.

IBaseFilter::QueryVendorInfo

IBaseFilter Interface

Retrieves a vendor information string.

Syntax

HRESULT QueryVendorInfo(
    LPWSTR *pVendorInfo
);

Parameters

pVendorInfo
[out] Pointer that will receive the address of a string containing vendor information.

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 method is optional and can return E_NOTIMPL. If implemented, the component allocates memory for the string and your application is responsible for freeing that memory using the Microsoft® Win32® CoTaskMemFree function.

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