ICaptureGraphBuilder2::FindPin

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This 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] A pointer to a pin category from the AMPROPERTY_PIN_CATEGORY property set (see Pin Property Set). 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 Value

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

See Also

Reference

ICaptureGraphBuilder2 Interface
PIN_DIRECTION
IPin Interface
ICaptureGraphBuilder2::RenderStream

Concepts

Pin Property Set