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 (e.g. 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 mediatypes with separate calls)
3. Register and search by mediums (see Kernel Streaming pins 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 IFlterMapper2 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 ActiveMovie categories (CLSID_ActiveMovieCategories).
UnregisterFilter	Removes the registration of this filter from the registry.
RegisterFilter	Register a filter, pins, and media types under a category.
EnumMatchingFilters	Provides an enumerator that enumerates registered filters that meet specified requirements.

---

IFilterMapper2::CreateCategory

Adds a new category to the list of ActiveMovie 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. For more information on "merit" see the remarks section of the IFilterMapper::RegisterFilter method.

A filter can appear in one or more categories (e.g. Video Compressors) to restrict the search space.

---

IFilterMapper2::UnregisterFilter

Removes the registration of this filter from the registry.

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

Parameters

pclsidCategory

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

szInstance

[in] Name of the filter you wish 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.

---

IFilterMapper2::RegisterFilter

Register 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] Globally unique identifier (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 which 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 Device. If ppMoniker is not 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::EnumMatchingFilters

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 0.

bExactMatch

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

dwMerit

[in] Enumerate only filters with at least this merit.

bInputNeeded

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

cInputTypes

[in] Number of input types to match.

pInputTypes

[size_is(cInputTypes*2)] Input major type 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 specifies if the input must be rendered by this filter.

bOutputNeeded

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

cOutputTypes

[in] Number of output types to match.

pOutputTypes

[size_is(cOutputTypes*2)] 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.

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.

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