IFilterMapper2 Interface

The IFilterMapper2 interface registers and locates Microsoft® 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:

• Quicker and easier enumeration of hardware devices such as Windows Driver Model/Plug and Play (WDM/PnP).
• Registration in one step (previously you had to register pins and media types with separate calls).
• Register and search by mediums (see "Kernel Streaming" in the Microsoft Windows NT® DDK).

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

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

Syntax

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] Pointer to a descriptive name for the category.

Return Value

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

Enumerates registered filters that meet specified requirements.

Syntax

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] Address of a pointer to the enumerator returned.

dwFlags

[in] Currently reserved, specify zero.

bExactMatch

[in] Value indicating whether an exact match is required. Specify TRUE to indicate an exact match is required, or FALSE to indicate an exact match is not required. If the subtype, category, and/or media are specified, then the bExactMatch parameter determines whether filters that register null for their subtype, major type, category, and/or medium are matched.

dwMerit

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

bInputNeeded

[in] Value indicating whether there must be at least one input pin. TRUE means there must be at least one input pin.

cInputTypes

[in] Number of input major and subtype pairs specified in pInputTypes.

pInputTypes

[in] Pointer to the input major types and subtype required. This is an array of GUIDs equal to twice the amount specified in cInputTypes. Set to NULL if you do not care. Set individual major/sub types to GUID_NULL if those do not matter.

pMedIn

[in] Pointer to the input medium. Set to NULL if not needed.

pPinCategoryIn

[in] Pointer to the input pin category. Set to NULL if not needed.

bRender

[in] Value that indicates whether the specified filter must render the input. Specify TRUE if the specified filter must render the input.

bOutputNeeded

[in] Value indicating whether at least one output pin is required. Specify TRUE if there must be at least one output pin.

cOutputTypes

[in] Number of output major and subtype pairs specified in pOutputTypes.

pOutputTypes

[in] Pointer to the output major type and subtype required. This is an array of GUIDs equal to twice the amount specified in cOutputTypes. Set to NULL if you do not care. Set individual major/sub types to GUID_NULL if those do not matter.

pMedOut

[in] Pointer to the output medium. Set to NULL if not needed.

pPinCategoryOut

[in] Pointer to the output pin category. Set to NULL if not needed.

Return Value

Returns S_OK if successful or E_FAIL upon failure.

Remarks

This method enables you to specify the subtype, major type, category, and/or medium through the three parameters pInputTypes, pPinCategoryIn, pMedIn (and their output counterparts). For each one specified in this method call, the filter must have registered an exact match in the filter if the bExactMatch parameter is set to TRUE.

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.

Syntax

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] Pointer to a 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] Pointer to the category of the filter to register.

szInstance

[in] Pointer to the 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 Value

Returns one of the following values.

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.

Syntax

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

Parameters

pclsidCategory

[in] Pointer to the name of the category that the filter falls under.

szInstance

[in] Pointer to the name of the filter you want to remove.

Filter

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

Return Value

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.

---

 Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.