IFilterMapper Interface

The IFilterMapper interface is an abstraction that represents registered information about filters. This enables properties of filters to be looked up during loading.

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

This interface is used by filters to register and unregister themselves. This is handled in the base classes by the CBaseFilter::Register and CBaseFilter::Unregister member functions. It is also used by the filter graph manager to look up filters and determine their characteristics when building a filter graph to render a given media type.

Methods in Vtable Order

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

IFilterMapper methods Description
RegisterFilter Records the details of a filter in the registry.
RegisterFilterInstance Registers an identifiable instance of a filter.
RegisterPin Records the details of a pin in the registry.
RegisterPinType Adds a type for the pin to the registry.
UnregisterFilter Deletes a filter from the registry.
UnregisterFilterInstance Deletes an identifiable instance of a filter.
UnregisterPin Deletes a pin from the registry.
EnumMatchingFilters Finds all filters matching specific requirements.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IFilterMapper methods	Description
RegisterFilter	Records the details of a filter in the registry.
RegisterFilterInstance	Registers an identifiable instance of a filter.
RegisterPin	Records the details of a pin in the registry.
RegisterPinType	Adds a type for the pin to the registry.
UnregisterFilter	Deletes a filter from the registry.
UnregisterFilterInstance	Deletes an identifiable instance of a filter.
UnregisterPin	Deletes a pin from the registry.
EnumMatchingFilters	Finds all filters matching specific requirements.

IFilterMapper::EnumMatchingFilters

IFilterMapper Interface

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

Syntax

HRESULT EnumMatchingFilters(
    IEnumRegFilters **ppEnum,
    DWORD dwMerit,
    BOOL bInputNeeded,
    CLSID clsInMaj,
    CLSID clsInSub,
    BOOL bRender,
    BOOL bOutputNeeded,
    CLSID clsOutMaj,
    CLSID clsOutSub
);

Parameters

ppEnum
[out] Address of a pointer to the enumerator returned.
dwMerit
[in] Minimum merit value of filters to enumerate.
bInputNeeded
Value indicating whether there must be at least one input pin; TRUE indicates at least one input pin is required.
clsInMaj
[in] Input major type required. Set to GUID_NULL if you do not care.
clsInSub
[in] Input subtype required. Set to GUID_NULL if you do not care.
bRender
[in] Flag that specifies whether the filter must render the input; TRUE means that it must.
bOutputNeeded
Value indicating whether there must be at least one output pin; TRUE indicates at least one output pin is required.
clsOutMaj
[in] Output major type required. Set to GUID_NULL if you do not care.
clsOutSub
[in] Output subtype required. Set to GUID_NULL if you do not care.

Return Value

Returns an HRESULT value.

Remarks

Set the ppEnum parameter to be an enumerator for filters matching the requirements. For a description of merit values for the dwMerit parameter, see the IFilterMapper::RegisterFilter method.

IFilterMapper::RegisterFilter

IFilterMapper Interface

Adds a filter to the registry; the filter can then be enumerated.

Syntax

HRESULT RegisterFilter(
    CLSID clsid,
    LPCWSTR Name,
    DWORD dwMerit
);

Parameters

clsid
[in] Globally unique identifier (GUID) of the filter.
Name
[in] Descriptive name for the filter.
dwMerit
[in] Position in the order of enumeration. Filters with higher merit are enumerated first.

Return Value

Returns an HRESULT value.

Remarks

The merit (as defined by the dwMerit parameter) controls the order in which the filter graph manager tries filters when performing an operation as a result of a call to IGraphBuilder::Connect, IGraphBuilder::Render, or IGraphBuilder::RenderFile. The filter graph manager finds all filters registered with the correct media type and then tries the one with the highest merit, using other criteria in the registration to choose between filters with equal merit.
The following predefined values exist for the dwMerit parameter. Other values, such as MERIT_NORMAL_1, can be used. Using the formula (MERIT_NORMAL+MERIT_UNLIKELY)/2 to calculate the merit value is advisable, because it leaves some low-order bits available for making even finer distinctions.

0x900000 Hardware renderer filter. Filters with this merit value are tried first.
MERIT_PREFERRED (0x800000) Filter, such as a renderer, that is likely to complete the operation directly.
0x680000 MPEG decompression filter. These are tried before AVI decompressors because the latter require more time to determine if they work in the filter graph.
MERIT_NORMAL (0x600000) Filter that might contribute to the completion of a connection. AVI decompression filters and splitter transform filters are registered to this value.
MERIT_UNLIKELY (0x400000) Filter that may contribute to the completion of a connection (a color space conversion filter, for example). The filter graph manager uses this filter only if other options have failed. Register source filters with this value.
MERIT_DO_NOT_USE (0x200000) Filter that will never contribute to the completion of a connection. Filters registered with this value (or less) will never be tried by the filter graph manager when automatically building a filter graph. Use this to register filters that must be added explicitly, either as part of a predefined filter graph or by adding them using IFilterGraph::AddFilter. Examples include tee filters or effects filters.
MERIT_HW_COMPRESSOR (0x100050) Hardware compressor filter. Filters registered with this value will never be tried by the filter graph manager when automatically building a filter graph.
MERIT_SW_COMPRESSOR (0x100000) Software compressor filter. Filters registered with this value will never be tried by the filter graph manager when automatically building a filter graph.

IFilterMapper::RegisterFilterInstance

IFilterMapper Interface

Registers an identifiable instance of a filter.

Syntax

HRESULT RegisterFilterInstance(
    CLSID clsid,
    LPCWSTR Name,
    CLSID *MRId
);

Parameters

clsid
[in] GUID of the filter.
Name
[in] Descriptive name of the instance.
MRId
[out] Pointer to the returned media resource ID. This parameter is a locally unique identifier for this instance of this filter.

Return Value

Returns an HRESULT value.

Remarks

This method handles cases such as when two similar sound cards that are driven by the same driver are available, and it is necessary to choose which card will emit the sound. This is not needed if there is only one instance of the filter (such as when there is only one sound card in the computer), or if all instances of the filter are equivalent.
The filter itself must have already been registered.

IFilterMapper::RegisterPin

IFilterMapper Interface

Records the details of the pin in the registry.

Syntax

HRESULT RegisterPin(
    CLSID Filter,
    LPCWSTR Name,
    BOOL bRendered,
    BOOL bOutput,
    BOOL bZero,
    BOOL bMany,
    CLSID ConnectsToFilter,
    LPWSTR ConnectsToPin
);

Parameters

Filter
[in] GUID of the filter.
Name
[in] Name of the pin. This should be unique within the filter. It has no significance other than to indicate type information. You should not use pin names longer than 99 characters, because this causes filter enumeration problems.
bRendered
[in] Value specifying whether the filter renders this input. Set to TRUE if it does; otherwise, set to FALSE.
bOutput
[in] Value specifying whether this is an output pin. Set to TRUE if it is; otherwise, set to FALSE.
bZero
[in] Value specifying whether the filter can have zero instances of this pin. If it can, set to TRUE; otherwise, set to FALSE. For example, a decompression filter doesn't need to create a sound output pin for a movie without a sound track.
bMany
[in] Value specifying whether the filter can have many instances of this pin. If it can, set to TRUE; otherwise, set to FALSE. For example, a mixer might have multiple instances of its input pin.
ConnectsToFilter
[in] Reserved. Must be NULL. (This is intended for filters such as system-wide mixers that have connections outside the filter graph. It is not yet implemented.)
ConnectsToPin
[in] Reserved. Must be NULL.

Return Value

Returns an HRESULT value.

IFilterMapper::RegisterPinType

IFilterMapper Interface

Registers this pin type.

Syntax

HRESULT RegisterPinType(
    CLSID clsFilter,
    LPCWSTR strName,
    CLSID clsMajorType,
    CCLSID clsSubType
);

Parameters

clsFilter
Class identifier (CLSID) of the filter to which the pin belongs.
strName
Name by which it is known.
clsMajorType
Major type of the media sample supported by this pin class.
clsSubType
Subtype of the media sample supported by this pin class.

Return Value

Returns an HRESULT value.

Remarks

The clsMajorType and clsSubType parameters specify the media type of the pin and correspond to the AM_MEDIA_TYPE structure's majortype and subtype members, respectively.

IFilterMapper::UnregisterFilter

IFilterMapper Interface

Removes the registration of this filter from the registry.

Syntax

HRESULT UnregisterFilter(
    CLSID Filter
);

Parameters

Filter
[in] GUID of the filter.

Return Value

Returns an HRESULT value.

IFilterMapper::UnregisterFilterInstance

IFilterMapper Interface

Removes the registration of this filter instance from the registry.

Syntax

HRESULT UnregisterFilterInstance(
    CLSID MRId
);

Parameters

MRId
[in] Media resource identifier of this instance.

Return Value

Returns an HRESULT value.

IFilterMapper::UnregisterPin

IFilterMapper Interface

Removes the registration of this pin from the registry.

Syntax

HRESULT UnregisterPin(
    CLSID Filter,
    LPCWSTR Name
);

Parameters

Filter
[in] GUID of the filter that this pin is part of.
Name
[in] Name of the pin.

Return Value

Returns an HRESULT value.

0x900000	Hardware renderer filter. Filters with this merit value are tried first.
MERIT_PREFERRED (0x800000)	Filter, such as a renderer, that is likely to complete the operation directly.
0x680000	MPEG decompression filter. These are tried before AVI decompressors because the latter require more time to determine if they work in the filter graph.
MERIT_NORMAL (0x600000)	Filter that might contribute to the completion of a connection. AVI decompression filters and splitter transform filters are registered to this value.
MERIT_UNLIKELY (0x400000)	Filter that may contribute to the completion of a connection (a color space conversion filter, for example). The filter graph manager uses this filter only if other options have failed. Register source filters with this value.
MERIT_DO_NOT_USE (0x200000)	Filter that will never contribute to the completion of a connection. Filters registered with this value (or less) will never be tried by the filter graph manager when automatically building a filter graph. Use this to register filters that must be added explicitly, either as part of a predefined filter graph or by adding them using IFilterGraph::AddFilter. Examples include tee filters or effects filters.
MERIT_HW_COMPRESSOR (0x100050)	Hardware compressor filter. Filters registered with this value will never be tried by the filter graph manager when automatically building a filter graph.
MERIT_SW_COMPRESSOR (0x100000)	Software compressor filter. Filters registered with this value will never be tried by the filter graph manager when automatically building a filter graph.