Microsoft DirectX 8.0

IBaseFilter Interface

Provides methods for controlling a filter. All Microsoft® DirectShow® filters expose this interface. This interface derives from the IMediaFilter interface, and inherits the IPersist interface through IMediaFilter.

The filter graph manager uses this interface to control filters. Applications and other filters can use this interface to enumerate pins and query for filter information. They should not use it to change the state of a filter. Instead, call IMediaControl interfaces on the filter graph manager.

Filter developers: Implement this interface on every DirectShow filter. The CBaseFilter base class implements this interface.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IMediaFilter methodsDescription
StopStops the filter.
PausePauses the filter.
RunRuns the filter.
GetStateRetrieves the filter's state (running, stopped, or paused).
SetSyncSourceSets a reference clock for the filter.
GetSyncSourceRetrieves the reference clock that the filter is using.
IBaseFilter methods Description
EnumPinsEnumerates the pins on this filter.
FindPinRetrieves the pin with the specified identifier.
QueryFilterInfoRetrieves information about the filter.
JoinFilterGraphNotifies the filter that it has joined or left the filter graph.
QueryVendorInfoRetrieves a string containing vendor information.

IBaseFilter::EnumPins

IBaseFilter Interface

Enumerates the pins on this filter.

Syntax

HRESULT EnumPins(
    IEnumPins **ppEnum
);

Parameters

ppEnum
[out] Address of a variable that receives a pointer to the IEnumPins interface.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess
E_OUTOFMEMORYInsufficient memory
E_POINTER Null pointer argument

Remarks

This method returns an enumerator that supports the IEnumPins interface, which works like a standard COM enumerator. For more information, see Enumerating Pins.

If the method succeeds, the IEnumPins interface has an outstanding reference count. Be sure to release the interface when you are done.

IBaseFilter::FindPin

IBaseFilter Interface

Retrieves the pin with the specified identifier.

Syntax

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

Parameters

Id
[in] Pointer to a constant, null-terminated Unicode™ string that identifies the pin. Call the IPin::QueryId method to retrieve a pin's identifier.
ppPin
[out] Address of a variable that receives a pointer to the pin's IPin interface. If the method fails, *ppPin is set to NULL.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
E_POINTER Null pointer argument.
VFW_E_NOT_FOUNDCould not find a pin with this identifier.

Remarks

This method supports graph persistence. Use the IPin::QueryId method to save a pin's state, and use this method to restore the state. The pin's identifier string is defined by the filter implementation. The identifier must be unique within the filter.

If the method succeeds, the IPin interface that it returns has an outstanding reference count. Be sure to release the interface when you are done.

IBaseFilter::JoinFilterGraph

IBaseFilter Interface

Notifies the filter that it has joined or left the filter graph.

Syntax

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph,
    LPCWSTR pName
);

Parameters

pGraph
[in] Pointer to the filter graph manager's IFilterGraph interface, or NULL if the filter is leaving the graph.
pName
[in, string] Pointer to a null-terminated Unicode™ string that specifies a name for the filter.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

When the filter graph manager adds a filter to the filter graph, it calls this method with a pointer to itself. When it removes the filter from the graph, it calls this method with a NULL pointer.

Applications should never call this method. To add a filter to the graph, call the IFilterGraph::AddFilter method on the filter graph manager.

The filter should store the IFilterGraph interface pointer, so that it can post event notifications. However, it must not add a reference count to this interface. Doing so would create a circular reference count, because the filter graph manager keeps a reference count on the filter. A circular reference will prevent the interface from being released properly. The IFilterGraph interface is guaranteed to be valid until the filter graph manager notifies the filter that it has been removed from the graph.

The name passed in the pName parameter can be retrieved by calling the QueryFilterInfo method.

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. Possible values include those shown in the following table.

S_OKSuccess
E_POINTERNull pointer argument

Remarks

This method fills the FILTER_INFO structure with the filter information. On return, if the pGraph member of the FILTER_INFO structure is non-NULL, the IFilterGraph interface has an outstanding reference count. Be sure to release the interface when you are done.

IBaseFilter::QueryVendorInfo

IBaseFilter Interface

Retrieves a string containing vendor information.

Syntax

HRESULT QueryVendorInfo(
    LPWSTR *pVendorInfo
);

Parameters

pVendorInfo
[out] Address of a variable that receives a pointer to a wide-character string containing the vendor information.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
E_NOTIMPLMethod is not supported.
E_POINTERNull pointer argument.

Remarks

This method is optional; filters are not required to support it.

If the method is supported, it uses the CoTaskMemAlloc function to allocate memory for the string. Call the CoTaskMemFree function to free the memory.