IEnumRegFilters Interface

The IEnumRegFilters interface is a Component Object Model (COM) enumerator. This interface is implemented by the filter mapper and need not be implemented elsewhere.

The purpose of the mapper is to help the filter graph manager avoid loading filters when attempting to build a filter graph to render a given media type. By looking at filter properties recorded in the registry, the number of filters that must be loaded and tried can be reduced.

The IFilterMapper::EnumMatchingFilters method returns the enumerator that enumerates the filters that match specific requirements. The enumerator returns descriptors of filters, including the globally unique identifiers (GUID) that the Microsoft® Win32® CoCreateInstance function can instantiate. The filters are not loaded.

Although the filter graph manager is the primary user of this interface, applications can also use it to determine available filters in the system—for example, to construct a unique filter graph by adding and connecting filters itself, or to allow users to choose from a list of available filters.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IEnumRegFilters methods Description
Next Fills an array with the next filters that meet the requirements.
Skip Not currently implemented.
Reset Makes the Next method start again, beginning at the first filter.
Clone Not currently implemented.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IEnumRegFilters methods	Description
Next	Fills an array with the next filters that meet the requirements.
Skip	Not currently implemented.
Reset	Makes the Next method start again, beginning at the first filter.
Clone	Not currently implemented.

IEnumRegFilters::Clone

IEnumRegFilters Interface

Creates another enumerator with the same enumeration state as the current one.

This method is not currently implemented and returns E_NOTIMPL.

Syntax

HRESULT Clone(
    IEnumRegFilters **ppEnum
);

Parameters

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

Return Value

Returns E_NOTIMPL.

IEnumRegFilters::Next

IEnumRegFilters Interface

Fills the array with descriptions of the next set of filters (specified by the cFilters parameter) that meet the requirements specified upon creation of the enumerator.

Syntax

HRESULT Next(
    ULONG cFilters,
    REGFILTER **apRegFilter,
    ULONG *pcFetched
);

Parameters

cFilters
[in] Number of filters.
apRegFilter
[out] Address of a pointer to an array of REGFILTER pointers.
pcFetched
[out] Pointer to the actual number of filters passed.

Return Value

Returns one of the following HRESULT values.

E_INVALIDARG Invalid argument.

E_OUTOFMEMORY Insufficient memory.

E_POINTER Null pointer argument.

E_UNEXPECTED Unexpected error.

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 calling application must use the Microsoft Win32 CoTaskMemFree function to free each REGFILTER pointer returned in the array. Do not free the Name member of the REGFILTER structure separately, because IEnumRegFilters::Next allocates memory for this string as part of the REGFILTER structure.
If the number of registered filters changes, the state of the enumerator will no longer be consistent with the state of the registry. As a result, this method will return VFW_E_ENUM_OUT_OF_SYNC. 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.

IEnumRegFilters::Reset

IEnumRegFilters Interface

Resets the enumerator so that the next call to the IEnumRegFilters::Next method begins again at the first filter, if any.

Syntax

HRESULT Reset(void);

Return Value

Returns S_OK, which indicates success.

IEnumRegFilters::Skip

IEnumRegFilters Interface

Skips a specified number of items in the enumeration sequence.

This method is not currently implemented and returns E_NOTIMPL.

Syntax

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of items to skip.

Return Value

Returns E_NOTIMPL.

E_INVALIDARG	Invalid argument.
E_OUTOFMEMORY	Insufficient memory.
E_POINTER	Null pointer argument.
E_UNEXPECTED	Unexpected error.
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.