Expand Minimize

KsPinGetConnectedFilterInterface function

The KsPinGetConnectedFilterInterface function queries the filter to which Pin is connected in order to obtain a pointer to a COM interface.

Syntax


NTSTATUS KsPinGetConnectedFilterInterface(
  _In_   PKSPIN Pin,
  _In_   const GUID *InterfaceId,
  _Out_  PVOID *Interface
);

Parameters

Pin [in]

A pointer to a KSPIN structure. The filter to which this pin is attached is queried for the requested interface.

InterfaceId [in]

A pointer to a GUID representing the interface ID for the interface to obtain. A QueryInterface call is automatically performed for this interface.

Interface [out]

A pointer to a PVOID. As in COM, the resulting interface pointer is deposited into *Interface. This interface has a corresponding reference count and must be released by the caller as in COM.

Return value

KsPinGetConnectedFilterInterface returns STATUS_SUCCESS if the interface exists on the connected filter or in the AVStream thunk. If STATUS_SUCCESS is returned, the interface pointer is deposited into *Interface. Otherwise, it returns STATUS_NOINTERFACE. Note that this corresponds to the COM HRESULT E_NOINTERFACE.

Remarks

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

The most common usage of KsPinGetConnectedFilterInterface is to acquire the control interface for the filter to which Pin attaches. This control interface can then 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 filter. (If the connected filter is an AVStream filter; AVStream provides thunking only for IKsControl and IUnknown for non-AVStream filters).

The thunk is created only 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

Version

Available in Microsoft Windows XP and later operating systems and DirectX 8.0 and later DirectX versions.

Header

Ks.h (include Ks.h)

Library

Ks.lib

IRQL

PASSIVE_LEVEL

See also

KsPinGetConnectedPinInterface
KsPinGetReferenceClockInterface
KsGetOuterUnknown
IKsControl
IKsReferenceClock
KsFilterGetOuterUnknown
KsRegisterAggregatedClientUnknown

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft