Microsoft DirectX 8.0

IFilterChain Interface

This interface provides methods for starting, stopping, or removing chains of filters in a filter graph. The filter graph manager exposes this interface.

A filter chain is a sequence of filters, each with at most one connected input pin and one connected output pin, that forms an unbroken line of filters. A filter chain is defined by the filter at the start of the chain and the filter at the end of the chain. (These can be the same filter, making a chain of one filter.) By definition, there is a single stream path going from the start of the chain downstream to the end of the chain.

The methods on this interface are useful in situations where an entire stream of data can appear or disappear, such as a video conferencing application that receives multiple streams over a network. For more information, see Dynamic Graph Building. To control individual streams on a capture filter, use the IAMStreamControl interface instead.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IFilterChain methodsDescription
StartChainSwitches all the filters in a filter chain into a running state.
StopChainSwitches all the filters in a filter chain into a stopped state.
RemoveChainRemoves every filter in a filter chain from the filter graph.
PauseChainSwitches all the filters in a filter chain into a paused state.

IFilterChain::PauseChain

IFilterChain Interface

Switches all the filters in a filter chain into a paused state.

Syntax

HRESULT PauseChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter 
);

Parameters

pStartFilter
[in] Pointer to the filter at the start of the chain.
pEndFilter
[in] Pointer to the filter at the end of the chain. If this parameter is NULL, the method uses the longest possible filter chain that extends downstream from the start filter.

Return Value

Returns S_OK if successful. If the method fails, the return value may be VFW_E_NOT_PAUSED or another HRESULT value.

Remarks

If this method cannot switch a given filter into a paused state, it stops all of the filters in chain. The filter graph must be paused when you call this method.

IFilterChain::RemoveChain

IFilterChain Interface

Removes every filter in a filter chain from the filter graph.

Syntax

HRESULT RemoveChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter 
);

Parameters

pStartFilter
[in] Pointer to the filter at the start of the chain.
pEndFilter
[in] Pointer to the filter at the end of the chain. If this parameter is NULL, the method uses the longest possible filter chain that extends downstream from the start filter.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the failure otherwise.

Remarks

You can call this method while the graph is running; the method stops the filters in the chain before removing them from the graph.

IFilterChain::StartChain

IFilterChain Interface

Switches all the filters in a filter chain into a running state.

Syntax

HRESULT StartChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter 
);

Parameters

pStartFilter
[in] Pointer to the filter at the start of the chain.
pEndFilter
[in] Pointer to the filter at the end of the chain. If this parameter is NULL, the method uses the longest possible filter chain that extends downstream from the start filter.

Return Value

Returns S_OK if successful. If the method fails, the return value may be VFW_E_NOT_RUNNING or another HRESULT value.

Remarks

If this method cannot switch a given filter into a running state, it leaves all the filters in a stopped state. The filter graph must be running when you call this method.

IFilterChain::StopChain

IFilterChain Interface

Switches all the filters in a filter chain into a stopped state.

Syntax

HRESULT StopChain( 
    IBaseFilter *pStartFilter, 
    IBaseFilter *pEndFilter 
);

Parameters

pStartFilter
[in] Pointer to the filter at the start of the chain.
pEndFilter
[in] Pointer to the filter at the end of the chain. If this parameter is NULL, the method uses the longest possible filter chain that extends downstream from the start filter.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the failure otherwise.