KsPinGetConnectedPinInterface

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

NTSTATUS
  KsPinGetConnectedPinInterface(
    IN PKSPIN  Pin,
    IN const GUID*  InterfaceId,
    OUT PVOID*  Interface
  );

Parameters

Pin

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

InterfaceId

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

Interface

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.

Headers

Declared in ks.h. Include ks.h.

Comments

This function is available in Windows XP and DirectX 8.0 and later.

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.

KsPinGetConnectedPinInterface must be called at IRQL = PASSIVE_LEVEL.

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.

See Also

KsPinGetConnectedFilterInterface, KsPinGetReferenceClockInterface, KsGetOuterUnknown, IKsControl, IKsReferenceClock, KsFilterGetOuterUnknown, KsRegisterAggregatedClientUnknown