IFilterMapper2 Interface

IFilterMapper2 is an interface for registering and locating DirectShow filters with greater flexibility than IFilterMapper allowed. Applications and filters should use IFilterMapper2 instead of IFilterMapper, although both interfaces can find filters registered with the other interface.

One major change from IFilterMapper to IFilterMapper2 is that IFilterMapper2 provides support for filter categories. A filter can appear in one or more categories (for example, Video Compressors) to restrict the search space. The RegisterFilter method takes a category, and the EnumMatchingFilters method searches across categories.

Other changes include:

1. Quicker and easier enumeration of hardware devices such as WDM/PnP
2. Registration in one step (previously you had to register pins and media types with separate calls)
3. Register and search by mediums (see Kernel Streaming in the NT DDK)

When to Implement

This interface is implemented on the filter graph and is not intended to be implemented by developers.

When to Use

Applications and filters should use IFilterMapper2 when they need to register or unregister filters. IFilterMapper2 should be used instead of IFilterMapper.

Methods in Vtable Order

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

IFilterMapper2 methods	Description
CreateCategory	Adds a new category to the list of filter categories (CLSID_ActiveMovieCategories).
UnregisterFilter	Removes the registration of the specified filter from the registry.
RegisterFilter	Registers a filter, pins, and media types under a category.
EnumMatchingFilters	Provides an enumerator that enumerates registered filters that meet specified requirements.

---

IFilterMapper2::CreateCategory

IFilterMapper2 Interface

Adds a new category to the list of filter categories (CLSID_ActiveMovieCategories).

HRESULT CreateCategory(
  REFCLSID clsidCategory,
  DWORD dwCategoryMerit,
  LPCWSTR Description );

Parameters

clsidCategory

[in] Name of the new filter category.

dwCategoryMerit

[in] Merit value of the category. Categories with higher merit are enumerated first.

Description

[in] Descriptive name for the category.

Return Values

Returns S_OK on success; HRESULT_FROM_WIN32 on failure.

Remarks

The graph builder initially skips all categories with merit less than DO_NOT_USE to speed up the IGraphBuilder::RenderFile method. Categories of filters that should not be considered for playback should be marked DO_NOT_USE.

A filter can appear in one or more categories (for example, Video Compressors) to restrict the search space.

---

IFilterMapper2::EnumMatchingFilters

IFilterMapper2 Interface

Provides an enumerator that enumerates registered filters that meet specified requirements.

HRESULT EnumMatchingFilters(
  IEnumMoniker **ppEnum,
  DWORD dwFlags,
  BOOL bExactMatch,
  DWORD dwMerit,
  BOOL bInputNeeded,
  DWORD cInputTypes,
  const GUID *pInputTypes,
  const REGPINMEDIUM *pMedIn,
  const CLSID *pPinCategoryIn,
  BOOL bRender,
  BOOL bOutputNeeded,
  DWORD cOutputTypes,
  const GUID *pOutputTypes,
  const REGPINMEDIUM *pMedOut,
  const CLSID *pPinCategoryOut,);

Parameters

ppEnum

[out] Enumerator returned.

dwFlags

[in] Currently reserved, specify zero.

bExactMatch

[in] Specify TRUE to indicate wildcards not allowed; FALSE indicates wildcards allowed.

dwMerit

[in] Enumerate only filters with at least the specified merit value.

bInputNeeded

[in] TRUE if there must be at least one input pin.

cInputTypes

[in] Number of input types to match.

pInputTypes

[in] Input major types and subtype required. Set to GUID_NULL if you do not care.

pMedIn

[in] Input medium. Set to NULL if not needed.

pPinCategoryIn

[in] Input pin category. Set to NULL if not needed.

bRender

[in] Option that indicates if the specified filter must render the input.

bOutputNeeded

[in] TRUE if there must be at least one output pin.

cOutputTypes

[in] Number of output types to match.

pOutputTypes

[in] Output major type and subtype required. Set to GUID_NULL if you do not care.

pMedOut

[in] Output medium. Set to NULL if not needed.

pPinCategoryOut

[in] Output pin category. Set to NULL if not needed.

Return Values

Returns S_OK if successful or E_FAIL upon failure.

Remarks

If a pin hasn't registered any media types, this method will not consider a match for the media type passed in for the pInputTypes or pOutputTypes parameters.

---

IFilterMapper2::RegisterFilter

IFilterMapper2 Interface

Registers a filter, pins, and media types under a category.

HRESULT RegisterFilter(
  REFCLSID clsidFilter,
  LPCWSTR Name,
  IMoniker **ppMoniker,
  const CLSID *pclsidCategory,
  const OLECHAR *szInstance,
  const REGFILTER2 *prf2 );

Parameters

clsidFilter

[in] GUID of the filter. CoCreateInstance will be called with this GUID when the filter is instantiated.

Name

[in] Descriptive name for the filter.

ppMoniker

[in, out] Address of a pointer to a device moniker that determines where this filter's data will be written. This parameter will be set to NULL upon return.

pclsidCategory

[in] Category of the filter to register.

szInstance

[in] Unique identifier for the filter (can be the friendly name or the filter CLSID).

prf2

[in] Pointer to a REGFILTER2 structure containing merit and pin information.

Return Values

Returns one of the following values:

Value	Meaning
VFW_E_BAD_KEY	Couldn't get registry key.
HRESULT_FROM_WIN32	Failure.
NOERROR	Success.

Remarks

Specify the moniker in the ppMoniker parameter if you are registering a filter for a WDM/PnP (Windows Driver Model/Plug and Play) device. If ppMoniker is non-null, the moniker returned can be used to write additional private values in the property bag.

The pclsidCategory parameter defaults to CLSID_ActiveMovieFilters if NULL is passed in.

Set ppMoniker to NULL if you don't want to provide or receive the moniker.

---

IFilterMapper2::UnregisterFilter

IFilterMapper2 Interface

Removes the registration of the specified filter from the registry.

HRESULT UnregisterFilter(
  const CLSID *pclsidCategory,
  const OLECHAR *szInstance,
  REFCLSID Filter );

Parameters

pclsidCategory

[in] Name of the category that the filter falls under.

szInstance

[in] Name of the filter you want to remove.

Filter

[in] Globally unique identifier (GUID) of the filter.

Return Values

Returns S_OK on success; HRESULT_FROM_WIN32 on failure.

Remarks

If szInstance is NULL, this method uses the filter GUID passed in Filter.

This method might return an error if the filter was not registered.

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

Top of Page