Microsoft DirectX 8.0 |
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 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 filter category to the registry. UnregisterFilter Removes filter information from the registry. RegisterFilter Adds filter information to the registry. EnumMatchingFilters Enumerates registered filters that meet specified requirements.
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.
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_OK Success E_FAIL Failure E_OUTOFMEMORY Insufficient memory E_POINTER NULL 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.
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_OK Success. VFW_E_BAD_KEY Could 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:
- The address of an IMoniker interface pointer for an existing device moniker
- The address of a NULL IMoniker interface pointer
- NULL
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.
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.