IFilterGraph Interface

The IFilterGraph interface is an abstraction representing a graph of filters. All filters in the graph share the same clock. They might or might not also be connected and stream data between them. This interface allows filters to be joined into a graph and operated as a unit. Unlike the IGraphBuilder interface, this interface does not use heuristics to connect and build the filter graph.

When to Implement

This interface is implemented on the filter graph manager and is not intended for implementation by developers.

When to Use

Applications should not use this interface directly but instead should use the IGraphBuilder interface, which inherits this interface.

Methods in Vtable Order

IUnknown methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IFilterGraph methods	Description
AddFilter	Adds a filter to the graph and gives it a name.
RemoveFilter	Removes a filter from the graph.
EnumFilters	Provides an enumerator for all filters in the graph.
FindFilterByName	Finds a filter that was added with a specified name.
ConnectDirect	Connects the two IPin objects directly (without intervening filters).
Reconnect	Breaks the existing pin connection and reconnects it to the same pin.
Disconnect	Disconnects this pin, if connected.
SetDefaultSyncSource	Sets the default synchronization source (a clock).

---

IFilterGraph::AddFilter

IFilterGraph Interface

Adds a filter to the graph and names it by using the pName parameter.

HRESULT AddFilter(
  IBaseFilter * pFilter,
  LPCWSTR pName
  );

Parameters

pFilter

[in] Filter to add to the graph.

pName

[in] Name of the filter.

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 name of the filter can be NULL, in which case the filter graph manager will generate a name. If the name is not NULL and is not unique, this method will modify the name in an attempt to generate a new unique name. If this is successful, this method returns VFW_S_DUPLICATE_NAME. If it cannot generate a unique name, it returns VFW_E_DUPLICATE_NAME.

AddFilter calls the filter's IBaseFilter::JoinFilterGraph method to inform the filter that it has been added. AddFilter must be called before attempting to use the IGraphBuilder::Connect, IFilterGraph::ConnectDirect, or IGraphBuilder::Render method to connect or render pins belonging to the added filter.

---

IFilterGraph::ConnectDirect

IFilterGraph Interface

Connects the two pins directly (without intervening filters).

HRESULT ConnectDirect(
  IPin * ppinOut,
  IPin * ppinIn,
  const AM_MEDIA_TYPE * pmt
  );

Parameters

ppinOut

[in] Output pin.

ppinIn

[in] Input pin.

pmt

[in] Media type to use for the connection (optional; that is, can be NULL).

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.

---

IFilterGraph::Disconnect

IFilterGraph Interface

Disconnects this pin.

HRESULT Disconnect(
  IPin * ppin
  );

Parameters

ppin

[in] Pin to disconnect.

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 does not completely break the connection. To completely break the connection, both ends must be disconnected.

This method results in a successful no operation (no-op) if the pin is not connected.

---

IFilterGraph::EnumFilters

IFilterGraph Interface

Provides an enumerator for all filters in the graph.

HRESULT EnumFilters(
  IEnumFilters ** ppEnum
  );

Parameters

ppEnum

[out] Enumerator.

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.

---

IFilterGraph::FindFilterByName

IFilterGraph Interface

Finds a filter that was added to the filter graph with a specific name.

HRESULT FindFilterByName(
  LPCWSTR pName,
  IBaseFilter ** ppFilter
  );

Parameters

pName

[in, string] Name to search for.

ppFilter

[out] Pointer to an IBaseFilter interface on the found filter.

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 function fails and sets pointers to the ppFilter parameter to NULL if the name is not in this graph.

---

IFilterGraph::Reconnect

IFilterGraph Interface

Disconnects this and the pin to which it connects and then reconnects it to the same pin. This allows the details of the connection, such as media type and allocator, to be renegotiated.

HRESULT Reconnect(
  IPin * ppin
  );

Parameters

ppin

[in] Pin to disconnect and reconnect.

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 performs its operation on a separate thread that will not hold any relevant locks. It can be called by a pin or filter to allow renegotiation of the connection. When a transform filter has its input connected, it must agree upon some media type. When the output is connected, it might discover that, to please both its upstream and downstream connections, it would have been better to have chosen a different media type for the upstream connection. The solution is to reconnect the input pin. The caller of this method should ensure (for example, by calling IPin::QueryAccept) that the resulting renegotiation will succeed, because the reconnection process is performed asynchronously and there is no mechanism for reporting or correcting errors.

---

IFilterGraph::RemoveFilter

IFilterGraph Interface

Removes a filter from the graph.

HRESULT RemoveFilter(
  IBaseFilter * pFilter
  );

Parameters

pFilter

[in] Pointer to the filter to be removed from the graph.

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 graph implementation informs the filter that it is being removed by calling the IBaseFilter::JoinFilterGraph method with a NULL argument.

---

IFilterGraph::SetDefaultSyncSource

IFilterGraph Interface

Sets the default source of synchronization.

HRESULT SetDefaultSyncSource(void);

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 used when no clock has been given to the filter graph, and the filter graph manager consequently must find a clock to use as the synchronization source. The filter graph manager first tries all filters, starting with renderers, to see if any filter exports a clock (by providing an IReferenceClock interface). The filter graph manager will choose the first filter that it finds, providing that filter is connected to an upstream source. If no connected filters are found, the first filter if IReferenceClock is used. Typically, this will be the audio rendering filter. If no filter exports a clock, the filter graph manager uses a system clock.

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

Top of Page