Edit

IFilterMapper2::EnumMatchingFilters method (strmif.h)

  • Article

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The EnumMatchingFilters method enumerates registered filters that meet specified requirements.

Syntax

HRESULT EnumMatchingFilters(
  [out] IEnumMoniker       **ppEnum,
  [in]  DWORD              dwFlags,
  [in]  BOOL               bExactMatch,
  [in]  DWORD              dwMerit,
  [in]  BOOL               bInputNeeded,
  [in]  DWORD              cInputTypes,
  [in]  const GUID         *pInputTypes,
  [in]  const REGPINMEDIUM *pMedIn,
  [in]  const CLSID        *pPinCategoryIn,
  [in]  BOOL               bRender,
  [in]  BOOL               bOutputNeeded,
  [in]  DWORD              cOutputTypes,
  [in]  const GUID         *pOutputTypes,
  [in]  const REGPINMEDIUM *pMedOut,
  [in]  const CLSID        *pPinCategoryOut
);

Parameters

[out] ppEnum

Receives a pointer to the IEnumMoniker interface. Use this interface pointer to retrieve filter monikers from the enumeration. The caller must release the interface.

[in] dwFlags

Reserved, must be zero.

[in] bExactMatch

Boolean value indicating whether an exact match is required. See Remarks for more information.

[in] dwMerit

Minimum merit value. The enumeration excludes filters with a lesser merit value. For a list of merit values, see Merit. 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.)

[in] bInputNeeded

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.

[in] cInputTypes

Number of input media types specified in pInputTypes.

[in] pInputTypes

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

[in] pMedIn

Pointer to a REGPINMEDIUM structure specifying the medium for the input pins. Set to NULL if not needed.

[in] pPinCategoryIn

Pointer to a GUID that specifies the input pin category. (See Pin Property Set.) Set to NULL if not needed.

[in] bRender

Boolean value that specifies whether the filter must render its input. If TRUE, the specified filter must render its input. (This value corresponds to the bRendered field in the REGFILTERPINS structure, which is used to register information about the filter's pins.)

[in] bOutputNeeded

Boolean value specifying whether the filter must have an output pin. If TRUE, the filter must have at least one output pin.

[in] cOutputTypes

Number of input media types specified in pOutputTypes.

[in] pOutputTypes

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.

[in] pMedOut

Pointer to a REGPINMEDIUM structure specifying the medium for the output pins. Set to NULL if not needed.

[in] pPinCategoryOut

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.

Return code Description
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):

C++ 
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.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header strmif.h (include Dshow.h)
Library Strmiids.lib

See also

Error and Success Codes

IFilterMapper2 Interface