IFilterMapper Interface


		Index Topic Contents
	Previous Topic: IFilterInfo Interface Next Topic: IFilterMapper2 Interface

IFilterMapper Interface

The IFilterMapper interface is an abstraction that represents registered information about filters. This allows properties of filters to be looked up during loading.
When to Implement
This interface is implemented on the filter mapper and is not intended to be implemented by developers.
When to Use
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 Returns 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.
HRESULT EnumMatchingFilters(
  IEnumRegFilters ** ppEnum,
  DWORD dwMerit,
  BOOL bInputNeeded,
  CLSID clsInMaj,
  CLSID clsInSub,
  BOOL bRender,
  BOOL bOutputNeeded,
  CLSID clsOutMaj,
  CLSID clsOutSub
  );
Parameters

ppEnum
[out] Enumerator returned.
dwMerit
[in] Enumerate only filters with at least this merit.
bInputNeeded
TRUE if there must be at least one input pin.
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] Option that specifies if the input must be rendered by this filter.
bOutputNeeded
TRUE if there must be at least one output pin.
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 Values

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

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 may 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.
HRESULT RegisterFilterInstance(
  CLSID clsid,
  LPCWSTR Name,
  CLSID *MRId
  );
Parameters

clsid
[in] Globally unique identifier (GUID) of the filter.
Name
[in] Descriptive name of the instance.
MRId
[out] Returned media resource ID. This parameter is a locally unique identifier for this instance of this filter.

Return Values

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.
HRESULT RegisterPin(
  CLSID Filter,
  LPCWSTR Name,
  BOOL bRendered,
  BOOL bOutput,
  BOOL bZero,
  BOOL bMany,
  CLSID ConnectsToFilter,
  LPWSTR ConnectsToPin
  );
Parameters

Filter
[in] Globally unique identifier (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. Note that pin names longer than 99 characters should not be used, because this causes filter enumeration problems.
bRendered
[in] Set to TRUE if the filter renders this input; otherwise, set to FALSE.
bOutput
[in] Set to TRUE if this is an output pin; otherwise, set to FALSE.
bZero
[in] If the filter can have zero instances of this pin, set to TRUE; otherwise, set to FALSE. For example, a decompression filter might choose to not create a sound output pin for a movie without a sound track.
bMany
[in] If the filter can have many instances of this pin, 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 Values

Returns an HRESULT value.
IFilterMapper::RegisterPinType
IFilterMapper Interface
Registers this pin type.
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 Values

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.
HRESULT UnregisterFilter(
  CLSID Filter
  );
Parameters

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

Return Values

Returns an HRESULT value.
IFilterMapper::UnregisterFilterInstance
IFilterMapper Interface
Removes the registration of this filter instance from the registry.
HRESULT UnregisterFilterInstance(
  CLSID MRId
  );
Parameters

MRId
[in] Media resource identifier of this instance.

Return Values

Returns an HRESULT value.
IFilterMapper::UnregisterPin
IFilterMapper Interface
Removes the registration of this pin from the registry.
HRESULT UnregisterPin(
  CLSID Filter,
  LPCWSTR Name
  );
Parameters

Filter
[in] Globally unique identifier (GUID) of the filter that this pin is part of.
Name
[in] Name of the pin.

Return Values

Returns an HRESULT value.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.
Top of Page

IUnknown methods	Description
QueryInterface	Returns 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.

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