estructura KSTOPOLOGY_CONNECTION (ks.h)

Artículo
03/05/2024

La estructura KSTOPOLOGY_CONNECTION describe una única conexión de ruta de acceso de datos dentro de un filtro de streaming del kernel.

PCCONNECTION_DESCRIPTOR es un alias para KSTOPOLOGY_CONNECTION.

Sintaxis

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

Miembros

FromNode

Especifica el identificador de nodo del nodo en el extremo ascendente de la conexión. Si este final de la conexión es un pin externo en el filtro, no un pin lógico en un nodo, m establezca este miembro en el valor null node-ID, KSFILTER_NODE.

FromNodePin

Especifica el identificador de patilla para el final ascendente de la conexión. Si **FromNode **es KSFILTER_NODE, el pin de este extremo de la conexión es un pin externo en el filtro. Si no es así, el pin de este extremo es un pin lógico en un nodo interno.

ToNode

Especifica el identificador de nodo del nodo en el extremo inferior de la conexión. Si este final de la conexión es un pin externo en el filtro, no un pin lógico en un nodo, establezca este miembro en el valor null node-ID, KSFILTER_NODE.

ToNodePin

Especifica el identificador de patilla para el extremo de bajada de la conexión. Si ToNode es KSFILTER_NODE, el pin de este final de la conexión es un pin externo en el filtro. Si no es así, el pin de este extremo es un pin lógico en un nodo interno.

Comentarios

KSTOPOLOGY_CONNECTION representa una única conexión dentro de un filtro, entre patillas externas, nodos internos o un pin externo y un nodo interno.

Un controlador de streaming devuelve una matriz de estructuras de KSTOPOLOGY_CONNECTION en respuesta a una solicitud get-property de KSPROPERTY_TOPOLOGY_CONNECTIONS .

Al representar una conexión entre dos pines externos, FromNode y ToNode deben establecerse en KSFILTER_NODE, y FromNodePin y ToNodePin deben ser el identificador de tipo de patilla de los pines respectivos. Consulte KSPROPSETID_Pin para obtener una descripción de los identificadores de tipo pin.

De lo contrario, FromNodePin o ToNodePin representan un pin entrante o saliente lógico para la conexión. Los números de patillas lógicas se usan únicamente para describir una conexión entre los nodos; no tienen ninguna existencia fuera de la propiedad KSPROPERTY_TOPOLOGY_CONNECTIONS.

PCCONNECTION_DESCRIPTOR

El nombre de la estructura PCCONNECTION_DESCRIPTOR es un alias para KSTOPOLOGY_CONNECTION. PCCONNECTION_DESCRIPTOR para IMiniport::GetDescription() es una descripción de una conexión de nodo en la topología del filtro implementado por el miniport. Se define de la siguiente manera en el encabezado portcls.h:

typedef KSTOPOLOGY_CONNECTION PCCONNECTION_DESCRIPTOR, *PPCCONNECTION_DESCRIPTOR;

Tenga en cuenta que para las descripciones de parámetros, el PCFILTER_NODE se usa con PCCONNECTION_DESCRIPTOR en lugar de KSFILTER_NODE.

La estructura PCCONNECTION_DESCRIPTOR especifica una única conexión dentro de un filtro. La conexión puede ser una de las siguientes:

Una conexión entre dos nodos internos
Una conexión entre un nodo interno y un pin en el filtro
Una conexión entre dos patillas en el filtro

El último tipo de conexión se produce cuando un pin de entrada en un filtro transmite datos directamente a un pin de salida en el mismo filtro.

Un controlador de adaptador usa una matriz de estructuras para especificar la topología interna de un filtro.

El flujo de datos fluye desde el extremo FromNode hasta el extremo ToNode de la conexión.

Para usar la estructura de PCCONNECTION_DESCRIPTOR , el escritor de controladores asigna patillas "lógicas" a los nodos dentro del filtro. Estos "pines" son puntos de conexión en los nodos y son análogos a los pins externos que el filtro usa para conectarse a otros filtros. Sin embargo, las patillas lógicas en los nodos se usan únicamente para especificar las conexiones dentro del filtro.

Un nodo simple con una sola entrada y una única salida suelen numerar sus patillas de entrada y salida uno y cero, respectivamente. Por convención, esta numeración se basa en la dirección del flujo IRP en lugar del flujo de datos.

Es posible que los nodos más complejos requieran identificadores de pin estandarizados para permitir que los clientes determinen más fácilmente la asignación de funciones a patillas específicas. Por ejemplo, el nodo KSNODETYPE_ACOUSTIC_ECHO_CANCEL usa identificadores estandarizados para sus cuatro pines.

Cuando el pin de un extremo de una conexión es un pin de entrada o salida en el filtro en lugar de un pin lógico en un nodo, establezca el miembro FromNode o ToNode (dependiendo del final de la conexión que especifique) al valor null node-ID, PCFILTER_NODE.

Evite los patillas lógicas confusas, que se usan únicamente para describir los puntos de conexión en los nodos de un filtro, con los pines externos que filtran usar para conectarse a otros filtros. Los pines lógicos rara vez se usan fuera de la estructura de PCCONNECTION_DESCRIPTOR . En este documento, el término pin hace referencia a un pin en un filtro KS en lugar de un pin lógico en un nodo a menos que se indique lo contrario.

El método IMiniport::GetDescription genera una estructura de PCFILTER_DESCRIPTOR que contiene un puntero a una matriz de PCCONNECTION_DESCRIPTOR .

Para obtener un ejemplo de código sencillo que muestra cómo se usa la estructura de PCCONNECTION_DESCRIPTOR , vea Exponer topología de filtro.