структура KSTOPOLOGY_CONNECTION (ks.h)

Статья
02/07/2025

Структура KSTOPOLOGY_CONNECTION описывает одно подключение к пути к данным в фильтре потоковой передачи ядра.

PCCONNECTION_DESCRIPTOR — это псевдоним для KSTOPOLOGY_CONNECTION.

Синтаксис

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

Члены

FromNode

Указывает идентификатор узла узла в верхнем конце соединения. Если этот конец подключения является внешним закреплением фильтра, а не логическим закреплением на узле, то для этого элемента задано значение null node-ID, KSFILTER_NODE.

FromNodePin

Указывает идентификатор пин-кода для вышестоящего конца подключения. Если **FromNode **KSFILTER_NODE, пин-код на этом конце подключения является внешним закреплением фильтра. В противном случае пин-код на этом конце является логическим закреплением на внутреннем узле.

ToNode

Указывает идентификатор узла узла в нижнем конце подключения. Если этот конец подключения является внешним закреплением фильтра, а не логическим закреплением на узле, задайте для этого элемента значение null node-ID, KSFILTER_NODE.

ToNodePin

Указывает идентификатор пин-кода для нижнего конца подключения. Если ToNode KSFILTER_NODE, то закрепление на этом конце соединения является внешним закреплением фильтра. В противном случае пин-код на этом конце является логическим закреплением на внутреннем узле.

Замечания

KSTOPOLOGY_CONNECTION представляет одно соединение внутри фильтра между внешними закреплениями, внутренними узлами или внешним закреплением и внутренним узлом.

Драйвер потоковой передачи возвращает массив структур KSTOPOLOGY_CONNECTION в ответ на запрос get-property KSPROPERTY_TOPOLOGY_CONNECTIONS.

При представлении соединения между двумя внешними закреплениями FromNode и ToNode должно быть задано значение KSFILTER_NODE, а FromNodePin и ToNodePin должен быть идентификатором типа пин-кода соответствующих закреплений. См. KSPROPSETID_Pin описание идентификаторов типов закреплений.

В противном случае FromNodePin или ToNodePin представляют логический входящий или исходящий пин-код подключения. Логические номера пин-кода используются исключительно для описания соединения между узлами; они не имеют существования за пределами свойства KSPROPERTY_TOPOLOGY_CONNECTIONS.

PCCONNECTION_DESCRIPTOR

Имя структуры PCCONNECTION_DESCRIPTOR — это псевдоним для KSTOPOLOGY_CONNECTION. PCCONNECTION_DESCRIPTOR для IMiniport::GetDescription() — это описание подключения узла в топологии фильтра, реализованного мини-портом. Он определен следующим образом в заголовке portcls.h:

typedef KSTOPOLOGY_CONNECTION PCCONNECTION_DESCRIPTOR, *PPCCONNECTION_DESCRIPTOR;

Обратите внимание, что для описания параметров PCFILTER_NODE используется PCCONNECTION_DESCRIPTOR вместо KSFILTER_NODE.

Структура PCCONNECTION_DESCRIPTOR указывает одно соединение внутри фильтра. Подключение может быть одним из следующих вариантов:

Соединение между двумя внутренними узлами
Соединение между внутренним узлом и закреплением фильтра
Соединение между двумя закреплениями в фильтре

Последний тип подключения возникает, когда входной пин-код в потоке фильтров передает данные непосредственно в выходной пин-код в том же фильтре.

Драйвер адаптера использует массив структур для указания внутренней топологии фильтра.

Поток данных передается из fromNode конца ToNode конца подключения.

Чтобы использовать структуру PCCONNECTION_DESCRIPTOR, модуль записи драйверов назначает "логические" закрепления узлам внутри фильтра. Эти "закрепления" являются точками подключения на узлах и аналогичны внешним контактам, которые фильтр использует для подключения к другим фильтрам. Однако логические закрепления на узлах используются исключительно для указания подключений внутри фильтра.

Простой узел с одним входным и одним выходным данным обычно чисел его входных и выходных закреплений один и ноль соответственно. По соглашению это нумерирование основано на направлении потока IRP, а не потока данных.

Более сложные узлы могут требовать стандартизированных идентификаторов пин-кодов, чтобы клиенты могли проще определить назначение функций определенным закреплениям. Например, узел KSNODETYPE_ACOUSTIC_ECHO_CANCEL использует стандартные идентификаторы для четырех закреплений.

Если пин-код на одном конце подключения является входным или выходным закреплением фильтра, а не логическим закреплением на узле, задайте FromNode или элемент ToNode (в зависимости от того, какой конец указанного соединения) имеет значение null node-ID, PCFILTER_NODE.

Избегайте запутанных логических закреплений, которые используются исключительно для описания точек подключения на узлах в фильтре с внешними закреплениями, которые фильтруют для подключения к другим фильтрам. Логические закрепления редко используются за пределами структуры PCCONNECTION_DESCRIPTOR. В этом документе термин закреплении относится к закреплению фильтра KS, а не логическому закреплению на узле, если не указано иное.

Метод IMiniport::GetDescription выводит PCFILTER_DESCRIPTOR структуру, содержащую указатель на массив PCCONNECTION_DESCRIPTOR.

Простой пример кода, показывающий, как используется структура PCCONNECTION_DESCRIPTOR, см. в разделе предоставления топологии фильтров.