IPin::QueryInternalConnections method (strmif.h)

Article
07/27/2023

[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 QueryInternalConnections method retrieves the pins that are connected internally to this pin (within the filter).

Syntax

HRESULT QueryInternalConnections(
  [out]     IPin  **apPin,
  [in, out] ULONG *nPin
);

Parameters

[out] apPin

Address of an array of IPin pointers. The caller allocates the array. The method fills the array with IPin pointers. If nPin is zero, this parameter can be NULL.

[in, out] nPin

On input, specifies the size of the array. On output, specifies the number of internally connected pins.

Return value

Returns an HRESULT value. Possible values include the following.

Return code	Description
S_FALSE	Insufficient array size.
S_OK	Success.
E_NOTIMPL	Not implemented.

Remarks

This method returns information about the filter's internal mapping of input pins to output pins. In other words, it describes how the input pins deliver data to the output pins.

In most filters, every input pin connects to every output pin. For example, in a transform filter, one input connects to one output; in a splitter filter, one input connects to multiple outputs. In these cases, the method should simply return E_NOTIMPL.

Otherwise, the method returns an array of IPin pointers, one for each pin that is mapped internally to the pin you have queried. If you call the method on an input pin, the array contains pointers to output pins, and vice versa.

The caller allocates the array of IPin pointers. To get the required array size, call the method once with apPin equal to NULL. The size is returned in the nPin parameter. Then allocate the array and call the method again, setting apPin equal to the address of the array and nPin equal to the array size. The method then fills the array with IPin pointers. Each returned pointer has an outstanding reference count and must be released by the caller.

This method has another use that is now deprecated: The Filter Graph Manager treats a filter as being a renderer filter if at least one input pin implements this method but returns zero in nPin. If you are writing a new renderer filter, however, you should implement the IAMFilterMiscFlags interface instead of using this method to indicate that the filter is a renderer.

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