IEnumRegFilters Interface

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 (GUIDs) that the Microsoft® Win32® CoCreateInstance function can instantiate. The filters are not loaded. The IEnumRegFilters interface is a Component Object Model (COM) enumerator.

When to Implement

This interface is implemented by the filter mapper and need not be implemented elsewhere.

When to Use

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	Returns 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	Skips a specified number of elements in the enumeration sequence.
Reset	Makes the Next method start again, beginning at the first filter.
Clone	Returns another enumerator containing the same enumeration state as the current one.

---

IEnumRegFilters::Clone

IEnumRegFilters Interface

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

HRESULT Clone(
  IEnumRegFilters **ppEnum
  );

Parameters

ppEnum

[out] Pointer to the duplicate enumerator interface.

Return Values

Returns an HRESULT value. Currently returns E_NOTIMPL.

Remarks

Currently, this method is not implemented.

---

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.

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

Parameters

cFilters

[in] Number of filters.

apRegFilter

[out] Pointer to an array of REGFILTER pointers.

pcFetched

[out] Actual number of filters passed.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

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

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.

---

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.

HRESULT Reset(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

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

---

IEnumRegFilters::Skip

IEnumRegFilters Interface

Skips a specified number of items in the enumeration sequence.

HRESULT Skip(
  ULONG celt
  );

Parameters

celt

[in] Number of items to skip.

Return Values

Returns an HRESULT value. Currently returns E_NOTIMPL.

Remarks

Currently, this method is not implemented.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page