KSTOPOLOGY_CONNECTION 構造体 (ks.h)

[アーティクル]
08/07/2023

KSTOPOLOGY_CONNECTION構造体では、カーネルストリーミングフィルター内の単一のデータパス接続について説明します。

PCCONNECTION_DESCRIPTORは、KSTOPOLOGY_CONNECTIONのエイリアスです。

構文

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

メンバー

FromNode

接続のアップストリーム側のノードのノード ID を指定します。接続のこの終了が、ノード上の論理ピンではなく、フィルター上の外部ピンである場合は、このメンバーを null node-ID 値に設定KSFILTER_NODE。

FromNodePin

接続のアップストリーム側のピン ID を指定します。 **FromNode **がKSFILTER_NODEの場合、接続のこの端のピンはフィルターの外部ピンです。そうでない場合、この端のピンは内部ノードの論理ピンです。

ToNode

接続のダウンストリーム側のノードのノード ID を指定します。接続のこの終了が、ノード上の論理ピンではなく、フィルターの外部ピンである場合は、このメンバーを null node-ID 値に設定KSFILTER_NODE。

ToNodePin

接続のダウンストリーム側のピン ID を指定します。 ToNode がKSFILTER_NODE場合、接続のこの端のピンはフィルターの外部ピンです。そうでない場合、この端のピンは内部ノードの論理ピンです。

注釈

KSTOPOLOGY_CONNECTIONは、外部ピン、内部ノード、または外部ピンと内部ノードの間の、フィルター内の単一の接続を表します。

ストリーミングドライバーは、KSPROPERTY_TOPOLOGY_CONNECTIONS get-property 要求に応答して、KSTOPOLOGY_CONNECTION 構造体の配列を返します。

2 つの外部ピン間の接続を表す場合は、 FromNode と ToNode の 両方をKSFILTER_NODEに設定し、 FromNodePin と ToNodePin を それぞれのピンのピンの種類 ID にする必要があります。ピンの種類 ID の説明については、「 KSPROPSETID_Pin 」を参照してください。

それ以外の場合、 FromNodePin または ToNodePin は 、接続の論理受信または送信ピンを表します。論理ピン番号は、ノード間の接続を記述するためにのみ使用されます。KSPROPERTY_TOPOLOGY_CONNECTIONS プロパティの外部には存在しません。

PCCONNECTION_DESCRIPTOR

PCCONNECTION_DESCRIPTOR構造体名は、KSTOPOLOGY_CONNECTIONの別名です。 IMiniport::GetDescription() のPCCONNECTION_DESCRIPTORは、ミニポートによって実装されるフィルターのトポロジにおけるノード接続の説明です。 portcls.h ヘッダーでは、次のように定義されています。

typedef KSTOPOLOGY_CONNECTION PCCONNECTION_DESCRIPTOR, *PPCCONNECTION_DESCRIPTOR;

パラメーターの説明では、 PCFILTER_NODEはKSFILTER_NODE ではなくPCCONNECTION_DESCRIPTORで使用されることに注意してください。

PCCONNECTION_DESCRIPTOR構造体は、フィルター内の 1 つの接続を指定します。接続には、次のいずれかを指定できます。

2 つの内部ノード間の接続
内部ノードとフィルター上のピン間の接続
フィルター上の 2 つのピン間の接続

最後の種類の接続は、フィルターの入力ピンがデータを同じフィルターの出力ピンに直接ストリーミングするときに発生します。

アダプタードライバーは、構造体の配列を使用して、フィルターの内部トポロジを指定します。

データストリームは 、FromNode の末尾から接続の ToNode の末尾に流れます。

PCCONNECTION_DESCRIPTOR構造を使用するために、ドライバーライターはフィルター内のノードに "論理" ピンを割り当てます。これらの "ピン" はノード上の接続ポイントであり、フィルターが他のフィルターに接続するために使用する外部ピンに似ています。ただし、ノード上の論理ピンは、フィルター内の接続を指定するためにのみ使用されます。

1 つの入力と 1 つの出力を持つ単純なノードでは、通常、入力ピンと出力ピンにそれぞれ 1 と 0 の番号が付けられます。規則により、この番号付けは、データフローではなく IRP フローの方向に基づいています。

より複雑なノードでは、クライアントが特定のピンへの関数の割り当てをより簡単に判断できるようにするために、標準化されたピン ID が必要になる場合があります。たとえば、 KSNODETYPE_ACOUSTIC_ECHO_CANCEL ノードでは、その 4 つのピンに標準化された ID が使用されます。

接続の一方の端のピンが、ノード上の論理ピンではなくフィルターの入力ピンまたは出力ピンである場合は、 FromNode または ToNode メンバー (指定する接続の終了に応じて) を null ノード ID 値に設定PCFILTER_NODE。

フィルター内のノード上の接続ポイントのみを記述するために使用される論理ピンを、フィルターが他のフィルターへの接続に使用する外部ピンと混同しないようにします。論理ピンは、 PCCONNECTION_DESCRIPTOR 構造の外部で使用されることはほとんどありません。このドキュメントでは、" pin " という用語は、特に記載がない限り、ノード上の論理ピンではなく、KS フィルター上のピンを指します。

IMiniport::GetDescription メソッドは、PCCONNECTION_DESCRIPTOR配列へのポインターを含むPCFILTER_DESCRIPTOR構造体を出力します。

PCCONNECTION_DESCRIPTOR構造の使用方法を示す簡単なコード例については、「フィルタートポロジの公開」を参照してください。