Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
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_DIRECTIONenumeration that specifies the pin direction (input or output).

pCategory

[in] A pointer to a pin category from the AMPROPERTY_PIN_CATEGORYproperty 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 pSourceis a pointer to a filter, and more than one pin matches the search criteria, this parameter specifies which pin to retrieve. If pSourceis a pointer to a pin, this parameter is ignored.

ppPin

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

Return Value

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

Remarks

If pSourceis a pointer to a filter, the method searches for the nth pin on that filter that matches the search criteria, where nis given by the numparameter. If the method finds a matching pin, it returns a pointer to the pin in the ppPinparameter.

If pSourceis 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 IPininterface in the ppPinparameter. Otherwise, it returns E_FAIL.

In either case, if the method succeeds, the IPininterface returned in the ppPinparameter 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::RenderStreammethod 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

Windows Embedded CE Windows Embedded CE 6.0 and later
Windows Mobile Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later
Note Microsoft DirectShow applications and DirectShow filters have different include file and Library requirements
For more information, see Setting Up the Build Environment

See Also