ICaptureGraphBuilder2::FindPin

  • Article
 
Microsoft DirectShow 9.0

ICaptureGraphBuilder2::FindPin

The FindPin method retrieves a particular pin on a filter, or determines whether a given pin matches the specified criteria.

Syntax

  HRESULT FindPin(
  IUnknown *pSource,
  PIN_DIRECTION pindir,
  const GUID *pCategory,
  const GUID *pType,
  BOOL fUnconnected,
  int num,
  IPin **ppPin
);

Parameters

pSource

[in] Pointer to an interface on a filter, or to an interface on a pin.

pindir

[in] Member of the PIN_DIRECTION enumeration that specifies the pin direction (input or output).

pCategory

[in] Pointer to a member of the AMPROPERTY_PIN_CATEGORY structure of the Pin Property Set property set, specifying a pin category. Use NULL to match any category.

pType

[in] Pointer to a major type GUID that specifies the media type. Use NULL to match any media type.

fUnconnected

[in] Boolean value that specifies whether the pin must be unconnected. If TRUE, the pin must be unconnected. If FALSE, the pin can be connected or unconnected.

num

[in] Zero-based index of the pin to retrieve, from the set of matching pins. If pSource is a pointer to a filter, and more than one pin matches the search criteria, this parameter specifies which pin to retrieve. If pSource is a pointer to a pin, this parameter is ignored.

ppPin

[out] Address of a pointer to receive the IPin interface of the matching pin.

Return Values

Returns S_OK if a matching pin is found, or E_FAIL otherwise.

Remarks

If pSource is a pointer to a filter, the method searches for the nth pin on that filter that matches the search criteria, where n is given by the num parameter. If the method finds a matching pin, it returns a pointer to the pin in the ppPin parameter.

If pSource is a pointer to a pin, the method tests that pin against the search criteria. If the pin matches the criteria, the method returns S_OK, and returns a pointer to the pin's IPin interface in the ppPin parameter. Otherwise, it returns E_FAIL.

In either case, if the method succeeds, the IPin interface returned in the ppPin parameter has an outstanding reference count. Be sure to release the interface when you are done using it.

Typically, an application will not need to use this method. It is provided for unusually complex tasks, when the ICaptureGraphBuilder2::RenderStream method cannot build the filter graph. Use this method to retrieve a desired pin from a capture filter, and then build the rest of the graph manually.

Requirements

Header: Declared in Strmif.h; include Dshow.h.

Library: Use Strmiids.lib.

See Also