KsPinGetConnectedPinInterface function (ks.h)

The KsPinGetConnectedPinInterface function queries the pin to which Pin is connected for a COM style interface.

Syntax

KSDDKAPI NTSTATUS KsPinGetConnectedPinInterface(
  [in]  PKSPIN     Pin,
  [in]  const GUID *InterfaceId,
  [out] PVOID      *Interface
);

Parameters

[in] Pin

A pointer to a KSPIN structure. AVStream queries the pin connected to Pin for the requested interface.

[in] InterfaceId

A pointer to the GUID specifying the interface type to be obtained. A QueryInterface call is automatically performed for this interface.

[out] Interface

A pointer to a pointer that AVStream sets to the location of the COM interface.

Return value

KsPinGetConnectedPinInterface returns STATUS_SUCCESS or STATUS_NOINTERFACE. See details below.

Remarks

Interface has a corresponding reference count and must be released by the caller as in COM.

This routine returns STATUS_SUCCESS if the interface exists on the connected pin or in the AVStream thunk. If STATUS_SUCCESS is returned, AVStream deposits the interface pointer into *Interface. Otherwise, the routine returns STATUS_NOINTERFACE. This corresponds to the COM HRESULT E_NOINTERFACE.

By default, objects support the IUnknown interface and the IKsControl interface. If the connected pin is an AVStream pin, the query and the returned interface pointer are direct calls to the other driver. If, on the other hand, the connected pin does not belong to an AVStream driver, a thunk is created that provides IKsControl support through synchronous calls to the driver containing the connected pin, using IoCallDriver.

The most common usage of KsPinGetConnectedPinInterface is to acquire the control interface for the connected pin. This control interface can be used for property, method, or event calls down to the connected pin or can query for interfaces that have been aggregated onto the connected pin. If the connected pin is an AVStream pin; AVStream only provides thunking for IKsControl and IUnknown for non-AVStream pins.

The thunk is only created if Pin is a source pin; thus, the calls only work if one or more of the following is true:

  • The connection is intra-AVStream (Pin's connected pin is an AVStream pin).
  • Pin is a source pin.
Otherwise, STATUS_UNSUCCESSFUL is returned.

Requirements

Requirement Value
Minimum supported client Available in Microsoft Windows XP and later operating systems and DirectX 8.0 and later DirectX versions.
Target Platform Universal
Header ks.h (include Ks.h)
Library Ks.lib
IRQL PASSIVE_LEVEL

See also

IKsControl

IKsReferenceClock

KsFilterGetOuterUnknown

KsGetOuterUnknown

KsPinGetConnectedFilterInterface

KsPinGetReferenceClockInterface

KsRegisterAggregatedClientUnknown