IGraphBuilder Interface

The IGraphBuilder interface allows applications to call upon the filter graph manager to attempt to build a complete filter graph, or parts of a filter graph given only partial information, such as the name of a file or the interfaces of two separate pins. The filter mapper looks up filters in the registry to configure the filter graph in a meaningful way.

IGraphBuilder inherits from the IFilterGraph interface and exposes all its methods. For this reason, IFilterGraph should normally not be used directly.

When to Implement

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

When to Use

Applications use this interface to create a filter graph, add filters to or remove filters from a filter graph, enumerate all the filters in a filter graph, and force connections when adding a filter. Filters typically use the interface to reconnect pins during the connection and negotiation process of building a filter graph.

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

IGraphBuilder methods	Description
Connect	Connects two IPin objects. If they will not connect directly, this method connects them with intervening transforms.
Render	Adds a chain of filters to this output pin to render it.
RenderFile	Builds a filter graph that renders the specified file.
AddSourceFilter	Adds a source filter to the filter graph for a specific file. The IGraphBuilder::RenderFile method calls this to find the source filter.
SetLogFile	Sets the log file into which actions taken in attempting to perform an operation are logged.

---

IGraphBuilder::AddSourceFilter

IGraphBuilder Interface

Adds a source filter to the filter graph for a specific file.

HRESULT AddSourceFilter(
  LPCWSTR lpwstrFileName,
  LPCWSTR lpwstrFilterName,
  IBaseFilter* * ppFilter
  );

Parameters

lpwstrFileName

[in] Pointer to the file.

lpwstrFilterName

[in] Name to give the source filter when it is added.

ppFilter

[out] Pointer to an IBaseFilter interface on the filter that was added.

Return Values

Returns an HRESULT value.

Remarks

This method allows you to obtain and retain more control over building the rest of the graph. For example, you can use the IFilterGraph::AddFilter method to add a renderer of your choice, and then use the IGraphBuilder::Connect method to connect the two filters. The IBaseFilter interface exposed by the source filter is returned in the ppFilter parameter, and the reference is already added by the IUnknown::AddRef method. The lpwstrFilterName parameter is used to allow the filter to be identified by this name in this filter graph. For more information, see FindFilterByName.

It is the application's responsibility to find the output pin of the added source filter in order to build the rest of the filter graph, which can be done by calling IGraphBuilder::Render on the output pin, to build the entire filter graph automatically, or by adding and connecting filters individually. Note that, when adding filters individually, the asynchronous file reader source filter and the URL moniker source filter do not parse the data, so the output pins of these source filters can be connected only to a parser filter, such as the MPEG splitter filter.

Note that the IGraphBuilder::RenderFile method adds the same source filter.

---

IGraphBuilder::Connect

IGraphBuilder Interface

Connects the two pins, using intermediates if necessary.

HRESULT Connect(
  IPin * ppinOut,
  IPin * ppinIn
  );

Parameters

ppinOut

[in] Output pin.

ppinIn

[in] Input pin.

Return Values

Returns an HRESULT value.

Remarks

This method connects these two pins directly or indirectly, using transform filters if necessary. The method either succeeds or leaves the filter graph unchanged. The filter graph manager attempts a direct connection. If that fails, it attempts to use any available transforms provided by filters that are already in the filter graph. (It enumerates these in an arbitrary order.) If that fails, it attempts to find filters from the registry to provide a transform. These will be tried in order of merit.

---

IGraphBuilder::Render

IGraphBuilder Interface

Builds a filter graph that renders the data from this output pin.

HRESULT Render(
  IPin * ppinOut
  );

Parameters

ppinOut

[in] Output pin.

Return Values

Returns an HRESULT value, which can include one of the following:

VFW_S_AUDIO_NOT_RENDERED

VFW_S_DUPLICATE_NAME

VFW_S_PARTIAL_RENDER

VFW_S_RPZA

VFW_S_VIDEO_NOT_RENDERED

Remarks

This method connects this output pin directly or indirectly to a filter or filters that will render it, using transform filters as intermediary filters if necessary. Filters are tried in the same order as for the IGraphBuilder::Connect method.

---

IGraphBuilder::RenderFile

IGraphBuilder Interface

Builds a filter graph that renders the specified file.

HRESULT RenderFile(
  LPCWSTR lpwstrFile,
  LPCWSTR lpwstrPlayList
  );

Parameters

lpwstrFile

[in] Name of the file containing the data to be rendered.

lpwstrPlayList

[in] Playlist name. Reserved; must be NULL. (This parameter is currently unimplemented.)

Return Values

Returns an HRESULT value, which can include one of the following:

VFW_S_AUDIO_NOT_RENDERED

VFW_S_DUPLICATE_NAME

VFW_S_PARTIAL_RENDER

VFW_S_RPZA

VFW_S_VIDEO_NOT_RENDERED

Remarks

If the lpwstrPlayList parameter is NULL, this method would use the default playlist, which typically renders the entire file.

---

IGraphBuilder::SetLogFile

IGraphBuilder Interface

Sets the file into which actions taken in attempting to perform an operation are logged.

HRESULT SetLogFile(
  HANDLE hFile
  );

Parameters

hFile

Handle to the log file.

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 hFile parameter must be an open file handle. After calling this method with a valid file handle, actions taken by IGraphBuilder methods when attempting to build a filter graph are logged to this file. This is intended to help you determine the cause of any failure to automatically build a filter graph.

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

Top of Page