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. |
Adds a source filter to the filter graph for a specific file.
HRESULT AddSourceFilter(
LPCWSTR lpwstrFileName,
LPCWSTR lpwstrFilterName,
IBaseFilter* * ppFilter
);
Returns an HRESULT value.
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.
Connects the two pins, using intermediates if necessary.
HRESULT Connect(
IPin * ppinOut,
IPin * ppinIn
);
Returns an HRESULT value.
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.
Builds a filter graph that renders the data from this output pin.
HRESULT Render(
IPin * ppinOut
);
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 |
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.
Builds a filter graph that renders the specified file.
HRESULT RenderFile(
LPCWSTR lpwstrFile,
LPCWSTR lpwstrPlayList
);
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 |
If the lpwstrPlayList parameter is NULL, this method would use the default playlist, which typically renders the entire file.
Sets the file into which actions taken in attempting to perform an operation are logged.
HRESULT SetLogFile(
HANDLE hFile
);
Returns an HRESULT value.
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.