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. |
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
);
Returns an HRESULT value.
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.
Adds a filter to the registry; the filter can then be enumerated.
HRESULT RegisterFilter(
CLSID clsid,
LPCWSTR Name,
DWORD dwMerit
);
Returns an HRESULT value.
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. |
Registers an identifiable instance of a filter.
HRESULT RegisterFilterInstance(
CLSID clsid,
LPCWSTR Name,
CLSID *MRId
);
Returns an HRESULT value.
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.
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
);
Returns an HRESULT value.
Registers this pin type.
HRESULT RegisterPinType(
CLSID clsFilter,
LPCWSTR strName,
CLSID clsMajorType,
CCLSID clsSubType
);
Returns an HRESULT value.
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.
Removes the registration of this filter from the registry.
HRESULT UnregisterFilter(
CLSID Filter
);
Returns an HRESULT value.
Removes the registration of this filter instance from the registry.
HRESULT UnregisterFilterInstance(
CLSID MRId
);
Returns an HRESULT value.
Removes the registration of this pin from the registry.
HRESULT UnregisterPin(
CLSID Filter,
LPCWSTR Name
);
Returns an HRESULT value.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.