IBaseFilter Interface

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.

---

IBaseFilter::EnumPins

IBaseFilter Interface

Enumerates all the pins available on this filter.

HRESULT EnumPins(
  IEnumPins ** ppEnum
  );

Parameters

ppEnum

[out] Pointer to the IEnumPins interface to retrieve.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

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

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

Parameters

Id

[in] Identifier of the pin.

ppPin

[out] 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 Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

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

HRESULT JoinFilterGraph(
  IFilterGraph * pGraph,
  LPCWSTR pName
  );

Parameters

pGraph

[in] Pointer to the filter graph to join.

pName

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

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
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

Returns information about the filter.

HRESULT QueryFilterInfo(
  FILTER_INFO * pInfo
  );

Parameters

pInfo

[out] Pointer to a FILTER_INFO structure.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
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

Returns a vendor information string.

HRESULT QueryVendorInfo(
  LPWSTR * pVendorInfo
  );

Parameters

pVendorInfo

[out] Pointer to a string containing vendor information.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
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, memory returned should be freed using the Microsoft® Win32® CoTaskMemFree function when the application is done using it.

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

Top of Page