Microsoft DirectX 8.0

IFilterMapper2 Interface

Registers and unregisters filters, and locates filters in the registry. The Filter Mapper helper object implements this interface.

Filters use this interface to register and unregister themselves. When the filter graph manager builds a filter graph, it uses this interface to look up filters and determine their characteristics. Applications can also use this interface to look up filters. For more information, see Using the Filter Mapper and How to Register DirectShow Filters.

Note  This interface replaces the IFilterMapper interface. IFilterMapper2 adds support for filter categories, pin mediums, and pin categories. In addition, it combines filter registration into one method call.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IFilterMapper2 methodsDescription
CreateCategoryAdds a new filter category to the registry.
UnregisterFilterRemoves filter information from the registry.
RegisterFilterAdds filter information to the registry.
EnumMatchingFiltersEnumerates registered filters that meet specified requirements.

IFilterMapper2::CreateCategory

IFilterMapper2 Interface

Adds a new filter category to the registry.

Syntax

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

Parameters

clsidCategory
[in] Class identifier (CLSID) 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 Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

The filter graph manager initially skips all categories with a merit value less than or equal to MERIT_DO_NOT_USE, to speed up the graph-building process. Filter categories that should not be considered for playback should have a merit of MERIT_DO_NOT_USE or less.

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 that receives the IEnumMoniker interface. If the method succeeds, use this interface pointer to retrieve filter monikers from the enumeration. Be sure to release the interface when you are done.
dwFlags
[in] Reserved, must be zero.
bExactMatch
[in] Boolean value indicating whether an exact match is required. See Remarks for more information.
dwMerit
[in] Minimum merit value.
bInputNeeded
[in] Boolean value indicating whether the filter must have an input pin. If the value is TRUE, the filter must have at least one input pin.
cInputTypes
[in] Number of input media types specified in pInputTypes.
pInputTypes
[in] Pointer to an array of GUID pairs that specify major types and subtypes, for the input pins to match. The size of the array is 2 * cInputTypes. The array can be NULL. Individual array members can be GUID_NULL, which matches any type.
pMedIn
[in] Pointer to a REGPINMEDIUM structure specifying the medium for the input pins. Set to NULL if not needed.
pPinCategoryIn
[in] Pointer to a GUID that specifies the input pin category. Set to NULL if not needed.
bRender
[in] Boolean value that specifies whether the filter must render its input. If TRUE, the specified filter must render input.
bOutputNeeded
[in] Boolean value specifying whether the filter must have an output pin. If TRUE, the filter must have at least one output pin.
cOutputTypes
[in] Number of input media types specified in pOutputTypes.
pOutputTypes
[in] Pointer to an array of GUID pairs that specify major types and subtypes, for the output pins to match. The size of the array is 2 * cOutputTypes. The array can be NULL. Individual array members can be GUID_NULL, which matches any type.
pMedOut
[in] Pointer to a REGPINMEDIUM structure specifying the medium for the output pins. Set to NULL if not needed.
pPinCategoryOut
[in] Pointer to a GUID that specifies the output pin category. Set to NULL if not needed.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess
E_FAILFailure
E_OUTOFMEMORYInsufficient memory
E_POINTERNULL pointer argument

Remarks

To find filters whose input pins match a given set of media types, declare an array with major-type GUIDs and subtype GUIDs ordered in pairs. Pass the array address in the pInputTypes parameter, and set the cInputTypes parameter equal to the number of pairs (that is, half the array size):

GUID arrayInTypes[2];
arrayInTypes[0] = MEDIATYPE_Video;
arrayInTypes[1] = GUID_NULL;

DWORD cInTypes = 1;

For output pins, pass a similar array in the pOutputTypes parameter, and specify the number of GUID pairs in the cOutputTypes parameter.

If the value of the bExactMatch parameter is TRUE, this method looks for filters that exactly match the values you specify for media type, pin category, and pin medium. If the value is FALSE, filters that register a value of NULL for any of these items are considered a match. (In effect, a NULL value in the registry acts as a wildcard.)

If you specify NULL for media type, pin category, or pin medium, any filter is considered a match for that parameter.

If a pin did not register any media types, this method will not consider it a match for the media type.

IFilterMapper2::RegisterFilter

IFilterMapper2 Interface

Adds filter information to the registry.

Syntax

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

Parameters

clsidFilter
[in] Class identifier (CLSID) of the filter.
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. Can be NULL.
pclsidCategory
[in] Pointer to the filter category of the filter. If NULL, the default category is CLSID_ActiveMovieFilters.
szInstance
[in] Instance data for constructing the device moniker's display name. Can be the friendly name, or the string representation of the filter CLSID. If NULL, defaults to the filter CLSID.
prf2
[in] Pointer to a REGFILTER2 structure containing filter information.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
VFW_E_BAD_KEYCould not get registry key.

Remarks

This method adds information about the filter to the registry, under the registry entry for the specified filter category. It does not register the in-process server that creates the filter (usually a DLL). To register the server, you can call the AMovieDllRegisterServer2 function.

For the ppMoniker parameter, use one of the following:

If you are registering a filter for a Windows Driver Model (WDM) or Plug and Play device, pass the address of the existing device moniker. The filter will be registered using this moniker. When the method returns, *ppMoniker is set to NULL.

Otherwise, the method creates a new moniker. If ppMoniker is non-NULL, the method sets *ppMoniker to point to the new moniker. The application can use this moniker to write additional private values in the property bag. Be sure to release the interface.

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

IFilterMapper2::UnregisterFilter

IFilterMapper2 Interface

Removes filter information from the registry.

Syntax

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

Parameters

pclsidCategory
[in] Pointer to the filter category from which to remove the filter.
szInstance
[in] Instance data used to construct the device moniker's display name. Use the value that was originally passed to the RegisterFilter method.
Filter
[in] Class identifier (CLSID) of the filter.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

If the filter was not registered, the method might return an error.