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. |
Creates another enumerator with the same enumeration state as the current one.
HRESULT Clone(
IEnumRegFilters **ppEnum
);
Returns an HRESULT value. Currently returns E_NOTIMPL.
Currently, this method is not implemented.
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
);
Returns an HRESULT value.
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.
Resets the enumerator so that the next call to the IEnumRegFilters::Next method begins again at the first filter, if any.
HRESULT Reset(void);
Returns an HRESULT value.
Skips a specified number of items in the enumeration sequence.
HRESULT Skip(
ULONG celt
);
Returns an HRESULT value. Currently returns E_NOTIMPL.
Currently, this method is not implemented.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.