ICaptureGraphBuilder2::FindInterface method (strmif.h)
[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 FindInterface
method searches the graph for a specified interface, starting from a specified filter. You can restrict the search to a section of the graph upstream or downstream of the filter, or restrict it to a particular pin category or media type.
Syntax
HRESULT FindInterface(
[in] const GUID *pCategory,
[in] const GUID *pType,
[in] IBaseFilter *pf,
[in] REFIID riid,
[out] void **ppint
);
Parameters
[in] pCategory
A pointer to a GUID that specifies the search criteria. See Remarks for more information. The following values are possible:
- &LOOK_UPSTREAM_ONLY.
- &LOOK_DOWNSTREAM_ONLY.
- One of the pin categories listed in Pin Property Set.
- NULL
[in] pType
Pointer to a GUID that specifies the major media type of an output pin, or NULL.
[in] pf
Pointer to the IBaseFilter interface of the filter. The method begins searching from this filter.
[in] riid
Interface identifier (IID) of the interface to locate.
[out] ppint
Address of a variable that receives the interface pointer. Be sure to release the retrieved interface pointer when you are done with the interface.
Return value
Returns an HRESULT value. Possible values include the following.
Return code | Description |
---|---|
|
Success. |
|
Failure. |
|
No such interface supported. |
|
NULL pointer argument. |
Remarks
In a capture graph, various filters and pins might expose interfaces for setting properties such as compression parameters (IAMVideoCompression) or stream formats (IAMStreamConfig). Depending on the capture device, other useful interfaces might include IAMCrossbar, which routes analog signals, or IAMTVTuner, which controls a TV tuner device. You can use this method to find an interface, without writing special code that traverses the graph.
- The filter
- The filter's pins
- All the downstream filters, including their pins
- All the upstream filters, including their pins
- If pCategory equals &LOOK_UPSTREAM_ONLY, the search starts from the filter's input pins and continues upstream. It does not include the filter or anything downstream from the filter. The pType parameter is ignored.
- If pCategory equals &LOOK_DOWNSTREAM_ONLY, the search starts from the filter's output pins and continues downstream. It does not include the filter or anything upstream from the filter. The pType parameter is ignored.
- If pCategory specifies a pin category, the downstream portion of the search is restricted to output pins on the filter that match both the pin category and the media type given in the pType parameter. In this case, the method also searches the filter and everything upstream from the filter.
Pin categories are useful for finding pin interfaces on capture filters. For example, a capture filter might have separate pins for capture and preview. If you specify a pin category, you should also specify the media type, to make certain the method selects the correct filter and pin.
Some video capture filters have a video port pin (PIN_CATEGORY_VIDEOPORT) instead of a preview pin. If you specify PIN_CATEGORY_PREVIEW and MEDIATYPE_Video, the method treats any video port pins as preview pins. Your application does not have to test for this possibility.
Supporting Filters. If a capture device uses a Windows Driver Model (WDM) driver, the graph may require certain filters upstream from the WDM Video Capture filter, such as a TV Tuner filter or an Analog Video Crossbar filter. If the pCategory parameter does not equal NULL, this method automatically inserts any required WDM filters into the graph. To do so, it queries the input pins on the capture filter to determine what mediums they support, and connects them to matching filters. If the pCategory parameter is NULL, the method does not add the upstream filters.
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 |