IEnumFilters Interface

The IFilterGraph::EnumFilters method returns the enumerator interface. It is based on the COM IEnum style of enumerators.

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

This interface is used by applications or other filters to determine what filters exist in the 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.

IEnumFilters methods Description
Next Retrieves the specified number of filters in the enumeration sequence.
Skip Skips a specified number of filters in the enumeration sequence.
Reset Resets the enumeration sequence to the beginning.
Clone Retrieves a duplicate enumerator containing the same enumeration state as the current one.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IEnumFilters methods	Description
Next	Retrieves the specified number of filters in the enumeration sequence.
Skip	Skips a specified number of filters in the enumeration sequence.
Reset	Resets the enumeration sequence to the beginning.
Clone	Retrieves a duplicate enumerator containing the same enumeration state as the current one.

IEnumFilters::Clone

IEnumFilters Interface

Retrieves a duplicate enumerator containing the same enumeration state as the current one.

Syntax

HRESULT Clone(
    IEnumFilters **ppEnum
);

Parameters

ppEnum
[out] Address of a pointer to the duplicate of the enumerator.

Return Value

Returns one of the following HRESULT values.

E_OUTOFMEMORY Insufficient memory.

E_POINTER Null pointer argument.

S_OK Success.

Remarks

This method produces two enumerators (the original and the duplicate); both are set at the same filter. After they are created, however, they are independent; therefore, calling the IEnumFilters::Next method for one does not affect the other.

IEnumFilters::Next

IEnumFilters Interface

Retrieves the specified number of filters in the enumeration sequence.

Syntax

HRESULT Next(
    ULONG cFilters,
    IBaseFilter **ppFilter,
    ULONG *pcFetched
);

Parameters

cFilters
[in] Number of filters to place.
ppFilter
[out] Address of a pointer to the array in which to place IBaseFilter pointers.
pcFetched
[out] Pointer to the actual number of filters placed in the array.

Return Value

Returns one of the following HRESULT values.

E_INVALIDARG Invalid argument.

E_POINTER Null pointer argument.

S_FALSE Fewer filters were retrieved than requested.

S_OK Success.

VFW_E_ENUM_OUT_OF_SYNC The enumerator has become invalid. For more information, see Remarks.

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.

If the filter graph changes (for example, the application removes a filter), the state of the enumerator will no longer be consistent with the state of the graph. As a result, this method will return the VFW_E_ENUM_OUT_OF_SYNC error code. You should discard any data obtained from previous calls to the enumerator, because it might be invalid, and update the enumerator by calling the Reset method. You can then call the Next method safely.

IEnumFilters::Reset

IEnumFilters Interface

Resets the enumeration sequence to the beginning.

Syntax

HRESULT Reset(void);

Return Value

Returns S_OK, which indicates success.

Remarks

This method affects the return value of the next call to the IEnumFilters::Next method.

IEnumFilters::Skip

IEnumFilters Interface

Skips a specified number of filters in the enumeration sequence.

Syntax

HRESULT Skip(
    ULONG cFilter
);

Parameters

cFilter
[in] Number of filters to skip.

Return Value

Returns one of the following HRESULT values.

E_INVALIDARG No additional filters remain in the enumeration list.

S_FALSE Fewer filters were skipped than requested, because not that many remained in the list.

S_OK Success.

VFW_E_ENUM_OUT_OF_SYNC The enumerator has become invalid. For more information, see Remarks.

Remarks

This method affects the return value of the next call to the IEnumFilters::Next method.

If the filter graph changes (for example, the application removes a filter), the state of the enumerator will no longer be consistent with the state of the graph. As a result, this method will return the VFW_E_ENUM_OUT_OF_SYNC error code. You should discard any data obtained from previous calls to the enumerator, because it might be invalid, and update the enumerator by calling the Reset method. You can then call the Skip method safely.

E_OUTOFMEMORY	Insufficient memory.
E_POINTER	Null pointer argument.
S_OK	Success.

E_INVALIDARG	Invalid argument.
E_POINTER	Null pointer argument.
S_FALSE	Fewer filters were retrieved than requested.
S_OK	Success.
VFW_E_ENUM_OUT_OF_SYNC	The enumerator has become invalid. For more information, see Remarks.

E_INVALIDARG	No additional filters remain in the enumeration list.
S_FALSE	Fewer filters were skipped than requested, because not that many remained in the list.
S_OK	Success.
VFW_E_ENUM_OUT_OF_SYNC	The enumerator has become invalid. For more information, see Remarks.