estrutura KSTOPOLOGY_CONNECTION (ks.h)

Artigo
02/26/2024

A estrutura KSTOPOLOGY_CONNECTION descreve uma única conexão de caminho de dados dentro de um filtro de streaming de kernel.

PCCONNECTION_DESCRIPTOR é um alias para KSTOPOLOGY_CONNECTION.

Sintaxe

typedef struct {
  ULONG FromNode;
  ULONG FromNodePin;
  ULONG ToNode;
  ULONG ToNodePin;
} KSTOPOLOGY_CONNECTION, *PKSTOPOLOGY_CONNECTION;

Membros

FromNode

Especifica a ID do nó no upstream final da conexão. Se esse final da conexão for um pino externo no filtro, não um pino lógico em um nó, defina esse membro como o valor nulo node-ID, KSFILTER_NODE.

FromNodePin

Especifica a ID do pino para o final upstream da conexão. Se **FromNode **for KSFILTER_NODE, o pino nessa extremidade da conexão será um pino externo no filtro. Caso contrário, o pino nessa extremidade é um pino lógico em um nó interno.

ToNode

Especifica a ID do nó no final downstream da conexão. Se essa extremidade da conexão for um pino externo no filtro, não um pino lógico em um nó, defina esse membro como o valor nulo node-ID, KSFILTER_NODE.

ToNodePin

Especifica a ID do pino para o final downstream da conexão. Se ToNode for KSFILTER_NODE, o pino nessa extremidade da conexão será um pino externo no filtro. Caso contrário, o pino nessa extremidade é um pino lógico em um nó interno.

Comentários

KSTOPOLOGY_CONNECTION representa uma única conexão dentro de um filtro, entre pinos externos, nós internos ou um pino externo e um nó interno.

Um driver de streaming retorna uma matriz de estruturas KSTOPOLOGY_CONNECTION em resposta a uma solicitação get-property KSPROPERTY_TOPOLOGY_CONNECTIONS .

Ao representar uma conexão entre dois pinos externos, FromNode e ToNode devem ser definidos como KSFILTER_NODE e FromNodePin e ToNodePin devem ser a ID do tipo de pino dos respectivos pinos. Consulte KSPROPSETID_Pin para obter uma descrição das IDs de tipo de pino.

Caso contrário, FromNodePin ou ToNodePin representam um pino lógico de entrada ou saída para a conexão. Os números de pino lógicos são usados exclusivamente para descrever uma conexão entre nós; eles não têm existência fora da propriedade KSPROPERTY_TOPOLOGY_CONNECTIONS.

PCCONNECTION_DESCRIPTOR

O nome da estrutura PCCONNECTION_DESCRIPTOR é um alias para KSTOPOLOGY_CONNECTION. PCCONNECTION_DESCRIPTOR para IMiniport::GetDescription() é uma descrição de uma conexão de nó na topologia do filtro implementado pelo miniporto. Ele é definido da seguinte maneira no cabeçalho portcls.h:

typedef KSTOPOLOGY_CONNECTION PCCONNECTION_DESCRIPTOR, *PPCCONNECTION_DESCRIPTOR;

Observe que, para as descrições de parâmetro, o PCFILTER_NODE é usado com PCCONNECTION_DESCRIPTOR em vez de KSFILTER_NODE.

A estrutura PCCONNECTION_DESCRIPTOR especifica uma única conexão dentro de um filtro. A conexão pode ser uma das seguintes:

Uma conexão entre dois nós internos
Uma conexão entre um nó interno e um pino no filtro
Uma conexão entre dois pinos no filtro

O último tipo de conexão ocorre quando um pino de entrada em um filtro transmite dados diretamente para um pino de saída no mesmo filtro.

Um driver de adaptador usa uma matriz de estruturas para especificar a topologia interna de um filtro.

O fluxo de dados flui da extremidade FromNode para o final do ToNode da conexão.

Para usar a estrutura PCCONNECTION_DESCRIPTOR , o gravador de driver atribui pinos "lógicos" aos nós dentro do filtro. Esses "pinos" são pontos de conexão nos nós e são análogos aos pinos externos que o filtro usa para se conectar a outros filtros. No entanto, os pinos lógicos em nós são usados exclusivamente para especificar as conexões dentro do filtro.

Um nó simples com uma única entrada e uma única saída normalmente numera seus pinos de entrada e saída um e zero, respectivamente. Por convenção, essa numeração é baseada na direção do fluxo irp em vez do fluxo de dados.

Nós mais complexos podem exigir IDs de pino padronizadas para permitir que os clientes determinem com mais facilidade a atribuição de funções a pinos específicos. Por exemplo, o nó KSNODETYPE_ACOUSTIC_ECHO_CANCEL usa IDs padronizadas para seus quatro pinos.

Quando o pino em uma extremidade de uma conexão for um pino de entrada ou saída no filtro em vez de um pino lógico em um nó, defina o membro FromNode ou ToNode (dependendo de qual extremidade da conexão você está especificando) para o valor nulo node-ID, PCFILTER_NODE.

Evite confundir pinos lógicos, que são usados exclusivamente para descrever pontos de conexão em nós dentro de um filtro, com os pinos externos que os filtros usam para se conectar a outros filtros. Os pinos lógicos raramente são usados fora da estrutura PCCONNECTION_DESCRIPTOR . Neste documento, o termo pin refere-se a um pino em um filtro KS em vez de um pino lógico em um nó, a menos que indicado o contrário.

O método IMiniport::GetDescription gera uma estrutura PCFILTER_DESCRIPTOR que contém um ponteiro para uma matriz PCCONNECTION_DESCRIPTOR .

Para obter um exemplo de código simples que mostra como a estrutura de PCCONNECTION_DESCRIPTOR é usada, consulte Expondo topologia de filtro.