KSTOPOLOGY_CONNECTION-Struktur (ks.h)

Artikel
02/29/2024

Die KSTOPOLOGY_CONNECTION-Struktur beschreibt eine einzelne Datenpfadverbindung innerhalb eines Kernelstreamingfilters.

PCCONNECTION_DESCRIPTOR ist ein Alias für KSTOPOLOGY_CONNECTION.

Syntax

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

Member

FromNode

Gibt die Knoten-ID des Knotens am Upstream Ende der Verbindung an. Wenn dieses Ende der Verbindung ein externer Pin am Filter und kein logischer Pin auf einem Knoten ist, legen Sie diesen Member auf den Nullknoten-ID-Wert fest, KSFILTER_NODE.

FromNodePin

Gibt die Pin-ID für das Upstream Ende der Verbindung an. Wenn **FromNode ** KSFILTER_NODE ist, ist der Pin an diesem Ende der Verbindung ein externer Pin am Filter. Wenn dies nicht der Fall ist, ist die Pin an diesem Ende ein logischer Pin auf einem internen Knoten.

ToNode

Gibt die Knoten-ID des Knotens am Downstreamende der Verbindung an. Wenn es sich bei diesem Ende der Verbindung um einen externen Pin im Filter und nicht um einen logischen Pin auf einem Knoten handelt, legen Sie diesen Member auf den NULL-Wert node-ID fest, KSFILTER_NODE.

ToNodePin

Gibt die Pin-ID für das Downstreamende der Verbindung an. Wenn ToNode KSFILTER_NODE ist, ist der Pin an diesem Ende der Verbindung ein externer Pin am Filter. Wenn dies nicht der Fall ist, ist die Pin an diesem Ende ein logischer Pin auf einem internen Knoten.

Hinweise

KSTOPOLOGY_CONNECTION stellt eine einzelne Verbindung innerhalb eines Filters zwischen externen Pins, internen Knoten oder einem externen Pin und einem internen Knoten dar.

Ein Streamingtreiber gibt als Reaktion auf eine KSPROPERTY_TOPOLOGY_CONNECTIONS get-property-Anforderung ein Array von KSTOPOLOGY_CONNECTION-Strukturen zurück.

Bei der Darstellung einer Verbindung zwischen zwei externen Pins sollten sowohl FromNode als auch ToNode auf KSFILTER_NODE festgelegt werden, und FromNodePin und ToNodePin sollten die Pintyp-ID der jeweiligen Pins sein. Eine Beschreibung der Pintyp-IDs finden Sie unter KSPROPSETID_Pin .

Andernfalls stellen FromNodePin oder ToNodePin einen logischen eingehenden oder ausgehenden Pin für die Verbindung dar. Die logischen Pinnummern werden ausschließlich verwendet, um eine Verbindung zwischen Knoten zu beschreiben. sie haben keine Existenz außerhalb der KSPROPERTY_TOPOLOGY_CONNECTIONS-Eigenschaft.

PCCONNECTION_DESCRIPTOR

Der name der PCCONNECTION_DESCRIPTOR-Struktur ist ein Alias für KSTOPOLOGY_CONNECTION. PCCONNECTION_DESCRIPTOR für IMiniport::GetDescription() ist eine Beschreibung einer Knotenverbindung in der Topologie des vom Miniport implementierten Filters. Sie wird im portcls.h-Header wie folgt definiert:

typedef KSTOPOLOGY_CONNECTION PCCONNECTION_DESCRIPTOR, *PPCCONNECTION_DESCRIPTOR;

Beachten Sie, dass für die Parameterbeschreibungen die PCFILTER_NODE mit PCCONNECTION_DESCRIPTOR anstelle von KSFILTER_NODE verwendet wird.

Die PCCONNECTION_DESCRIPTOR-Struktur gibt eine einzelne Verbindung innerhalb eines Filters an. Die Verbindung kann eine der folgenden Sein:

Eine Verbindung zwischen zwei internen Knoten
Eine Verbindung zwischen einem internen Knoten und einer Pin im Filter
Eine Verbindung zwischen zwei Pins am Filter

Der letzte Verbindungstyp tritt auf, wenn ein Eingabepin an einem Filter Daten direkt an einen Ausgabepin auf demselben Filter streamt.

Ein Adaptertreiber verwendet ein Array von Strukturen, um die interne Topologie eines Filters anzugeben.

Der Datenstrom fließt vom FromNode-Ende zum ToNode-Ende der Verbindung.

Um die PCCONNECTION_DESCRIPTOR-Struktur zu verwenden, weist der Treiberwriter den Knoten innerhalb des Filters "logische" Pins zu. Diese "Pins" sind Verbindungspunkte auf den Knoten und analog zu den externen Pins, die der Filter zum Herstellen einer Verbindung mit anderen Filtern verwendet. Logische Pins auf Knoten werden jedoch ausschließlich verwendet, um die Verbindungen innerhalb des Filters anzugeben.

Ein einfacher Knoten mit einer einzelnen Eingabe und einer einzelnen Ausgabe nummeriert in der Regel die Eingabe- und Ausgabepins 1 bzw. null. Gemäß Konvention basiert diese Nummerierung auf der Richtung des IRP-Flusses und nicht auf dem Datenfluss.

Komplexere Knoten erfordern möglicherweise standardisierte Pin-IDs, damit Clients die Zuweisung von Funktionen zu bestimmten Pins einfacher bestimmen können. Beispielsweise verwendet der knoten KSNODETYPE_ACOUSTIC_ECHO_CANCEL für seine vier Pins standardisierte IDs.

Wenn der Pin an einem Ende einer Verbindung ein Eingabe- oder Ausgabepin auf dem Filter und nicht ein logischer Pin auf einem Knoten ist, legen Sie den FromNode - oder ToNode-Member (je nachdem, welches Ende der Verbindung Sie angeben) auf den NULL-Knoten-ID-Wert fest, PCFILTER_NODE.

Vermeiden Sie verwirrende logische Pins, die ausschließlich zur Beschreibung von Verbindungspunkten auf Knoten innerhalb eines Filters verwendet werden, mit den externen Pins, die Filter verwenden, um eine Verbindung mit anderen Filtern herzustellen. Logische Pins werden nur selten außerhalb der PCCONNECTION_DESCRIPTOR-Struktur verwendet. In diesem Dokument bezieht sich der Begriff Pin auf einen Pin an einem KS-Filter und nicht auf einen logischen Pin auf einem Knoten, sofern nicht anders angegeben.

Die IMiniport::GetDescription-Methode gibt eine PCFILTER_DESCRIPTOR-Struktur aus, die einen Zeiger auf ein PCCONNECTION_DESCRIPTOR Array enthält.

Ein einfaches Codebeispiel, das zeigt, wie die PCCONNECTION_DESCRIPTOR-Struktur verwendet wird, finden Sie unter Verfügbarmachen der Filtertopologie.