IFilterMapper2::EnumMatchingFilters

The EnumMatchingFilters method 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. The enumeration exludes filters with a lesser merit value. If dwMerit is higher than MERIT_DO_NOT_USE, the enumeration also excludes filters whose category has a merit less than or equal to MERIT_DO_NOT_USE. (See Filter Categories.)

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. (See Media Types.)

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. (See Pin Property Set.) 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. (See Pin Property Set.) Set to NULL if not needed.

Return Value

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

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.

See Also

• Error and Success Codes
• IFilterMapper2 Interface