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, you should typically not use IFilterGraph directly.

Any component that acts as a filter graph manager must implement this interface.

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

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

Syntax

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

Parameters

lpwstrFileName
[in] Pointer to the file.
lpwstrFilterName
[in] Pointer to the name to give the source filter when it is added.
ppFilter
[out] Address of a pointer to an IBaseFilter interface on the filter that was added.

Return Value

Returns an HRESULT value.

Remarks

This method enables 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. 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.
The IGraphBuilder::RenderFile method adds the same source filter.

IGraphBuilder::Connect

IGraphBuilder Interface

Connects the two pins, using intermediates if necessary.

Syntax

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

Parameters

ppinOut
[in] Pointer to the output pin.
ppinIn
[in] Pointer to the input pin.

Return Value

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.

Syntax

HRESULT Render(
    IPin *ppinOut
);

Parameters

ppinOut
[in] Pointer to the output pin.

Return Value

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.

Syntax

HRESULT RenderFile(
    LPCWSTR lpwstrFile,
    LPCWSTR lpwstrPlayList
);

Parameters

lpwstrFile
[in] Pointer to the name of the file containing the data to be rendered.
lpwstrPlayList
[in] Pointer to the playlist name. Reserved; must be NULL. (This parameter is currently unimplemented.)

Return Value

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.

Syntax

HRESULT SetLogFile(
    HANDLE hFile
);

Parameters

hFile
Handle to the log file.

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 for use in debugging; it is intended to help you determine the cause of any failure to automatically build a filter graph.
The hFile parameter must be an open file handle. Your application is responsible for opening the file and for closing it when you are done logging. Before closing the file handle, call SetLogFile with a NULL file handle. This will ensure that the component does not attempt to use the file handle after you have closed it.

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