IAMGraphStreams::FindUpstreamInterface method (strmif.h)

Article
02/22/2024

[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 FindUpstreamInterface method searches the filter graph for a specified interface, upstream from a specified pin.

Syntax

HRESULT FindUpstreamInterface(
  [in]  IPin   *pPin,
  [in]  REFIID riid,
  [out] void   **ppvInterface,
  [in]  DWORD  dwFlags
);

Parameters

[in] pPin

Pointer to the IPin interface of a pin. The pin must belong to a filter in the filter graph.

[in] riid

Reference to an interface identifier (IID) that specifies the interface to find.

[out] ppvInterface

Address of a void pointer. If the method succeeds, this variable receives a pointer to the interface specified by riid.

[in] dwFlags

Combination of flags from the AM_INTF_SEARCH_FLAGS enumeration, specifying what to search (pins or filters).

Return value

Returns one of the following HRESULT values.

Return code	Description
E_NOINTERFACE	Interface not found.
E_POINTER	Invalid pointer.
S_OK	Success.

Remarks

If dwFlags is zero, this method searches for the interface in the following order:

It queries the pin specified by pPin.
If pPin is an input pin, it calls FindUpstreamInterface recursively on the output pin that is connected to pPin, if any.
If pPin is an output pin, it queries the filter that owns pPin. Then it creates a list of input pins on the filter that have internal connections to pPin, and calls FindUpstreamInterface recursively on those input pins.

To create a list of input pins with internal connections, the method does the following:
- Calls IPin::QueryInternalConnections.
- If that fails, calls IBaseFilter::EnumPins and looks for input pins.

It stops at the first object it finds that supports the interface. You can limit the objects that are searched (filters, input pin, or output pins) by setting dwFlags to a non-zero value.

Note The ICaptureGraphBuilder2::FindInterface method implements a more general approach to this problem, and in most situations is preferred.

Requirements

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