Função KsPinGetConnectedFilterInterface (ks.h)

Artigo
02/26/2024

A função KsPinGetConnectedFilterInterface consulta o filtro ao qual Pin está conectado para obter um ponteiro para uma interface COM.

Sintaxe

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

Parâmetros

[in] Pin

Um ponteiro para uma estrutura KSPIN . O filtro ao qual esse pino está anexado é consultado para a interface solicitada.

[in] InterfaceId

Um ponteiro para um GUID que representa a ID da interface a ser obtida. Uma chamada QueryInterface é executada automaticamente para essa interface.

[out] Interface

Um ponteiro para um PVOID. Assim como no COM, o ponteiro de interface resultante é depositado em *Interface. Essa interface tem uma contagem de referência correspondente e deve ser liberada pelo chamador como em COM.

Retornar valor

KsPinGetConnectedFilterInterface retornará STATUS_SUCCESS se a interface existir no filtro conectado ou no thunk AVStream. Se STATUS_SUCCESS for retornado, o ponteiro da interface será depositado em *Interface. Caso contrário, ele retornará STATUS_NOINTERFACE. Observe que isso corresponde à E_NOINTERFACE COM HRESULT.

Comentários

Por padrão, os objetos dão suporte à interface IUnknown e à interface IKsControl . Se o filtro e o pino conectado forem objetos AVStream, a consulta e o ponteiro de interface retornado serão chamadas diretas para o outro driver. No entanto, se o pin e o filtro conectados não pertencerem a um driver AVStream, será criado um thunk que fornece suporte a IKsControl por meio de chamadas síncronas para o driver que contém o filtro, usando IoCallDriver.

O uso mais comum de KsPinGetConnectedFilterInterface é adquirir a interface de controle do filtro ao qual o Pin é anexado. Essa interface de controle pode ser usada para chamadas de propriedade, método ou evento até o pino conectado ou pode consultar interfaces que foram agregadas no filtro conectado. (Se o filtro conectado for um filtro AVStream; O AVStream fornece conversão somente para IKsControl e IUnknown para filtros não AVStream).

O thunk será criado somente se Pin for um pino de origem; Portanto, as chamadas só funcionarão se um ou mais dos seguintes itens forem verdadeiros:

A conexão é intra-AVStream (o pino conectado do Pin é um pino AVStream).
Pin é um pino de origem.

Caso contrário, STATUS_UNSUCCESSFUL será retornado.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Microsoft Windows XP e em sistemas operacionais posteriores e no DirectX 8.0 e versões posteriores do DirectX.
Plataforma de Destino	Universal
Cabeçalho	ks.h (inclua Ks.h)
Biblioteca	Ks.lib
IRQL	PASSIVE_LEVEL