KS ピン

ミニドライバーは、インスタンス化するピンの種類ごとに KSPIN_DESCRIPTOR 構造体を提供します。 ピン記述子構造体は、ピン ファクトリと呼ばれます。 各ピン ファクトリは、特定の種類の 1 つ以上のピン インスタンスをインスタンス化できます。 ピン ファクトリには、この記述子がインスタンス化するピンの種類を記述する配列がいくつか含まれています。

ミニドライバーは、この記述子によって作成されたピンが KSPIN_DESCRIPTOR のカテゴリ メンバーに属する 1 つ以上の KS カテゴリ を指定します。 KS では、フィルター グラフを構築するときに、カテゴリを使用してピン インスタンスを接続します。 KSPROPERTY_TOPOLOGY_CATEGORIES プロパティは、ドライバーがサポートする機能カテゴリの配列に対してクエリを実行します。

ミニドライバーは、1 つ以上のピン デバイス名を登録する INF ファイルを提供します。 インストール時に、オペレーティング システムは名前と対応するカテゴリをシステム レジストリに読み込みます。 その後、クライアントは、これらのデバイス名を使用してファイルの作成呼び出しを行って、ピンをインスタンス化できます。

ユーザーモード クライアントは、Win32 関数 CreateFile をデバイスの名前で呼び出します。 たとえば、"\\.\filters\audio\default renderer" は、既定の出力用に構成されているオーディオ デバイスへのリンクである可能性があります。 カーネルモード クライアントは、カーネル モードから ZwCreateFile を呼び出します。 ファイル作成ルーチンがファイル ハンドルを返した後、KS クライアントは KS プロパティを介してピン インスタンスと通信します。

ピン記述子構造体では、ミニドライバーは、そのピン ファクトリでサポートされているインターフェイスとメディアを指定する KSPIN_INTERFACE 構造体と KSPIN_MEDIUM 構造体の配列をレイアウトします。 KSPIN_DESCRIPTOR は、ミニドライバーがそのファクトリによって作成されたピンの有効なデータ範囲を指定する場所でもあります。 これを行うには、KSDATARANGE 構造体の配列へのポインターを指定します。 ミニドライバーは、このピン ファクトリによって作成された新しいピンのデータと通信フローの方向も指定します。

ミニドライバーは、KSPROPSETID_Pin プロパティ セットをサポートすることによって、ピン ファクトリの実行時検出を有効にします。

ピン接続を作成するには、KsCreatePin ルーチンを呼び出します。 この呼び出しでは、ミニドライバーは、要求された接続を記述する KSPIN_CONNECT 型の構造体へのポインターを渡します。 ピンが作成されると、フィルターは新しいピンを、そのフィルターのファイル オブジェクトの下位にあるファイル オブジェクトと見なします。

ミニドライバーは、結果の IRP_MJ_CREATE で提供される記述子構造体を使用して KsValidateConnectRequest を呼び出します。 このルーチンは、これらの構造体を検証し、接続構造体とルート ファイル オブジェクトへのポインターを返します。

ミニドライバーは、KSPIN_DESCRIPTOR 構造体の DataFlow および コミュニケーション メンバーを使用して、次のピンの詳細を定義します。

• IRP ソース ピンと IRP シンク ピン

  IRP ソース ピンは IRP を発行します。IRP シンク ピンは IRP を受け取ります。 ユーザーモード クライアントは、関連するファイル ハンドルを介して IRP シンク ピンに直接 I/O 要求を送信します。 クライアントは、KSPROPERTY_PIN_COMMUNICATION を使用して、データがピンの種類に入るかどうかをチェックします。

• データ ソースのピンとデータ シンクのピン

  データ ソース ピンはフィルターの出力ピンです。データ シンク ピンは入力ピンです。 データ ソースまたはシンクのプロパティは、IRP ソースまたはシンクとは無関係です。 たとえば、クライアントは、データ ソース、IRP シンクピンをデータ シンク、IRP ソースピンに接続できます。 クライアントは、KSPROPERTY_PIN_DATAFLOW を使用して、データがピンの種類に入るかどうかをチェックします。

接続を終了するときは、基になるファイル オブジェクトが破棄される前に、ソース ピンのハンドルを閉じる必要があります。 ソース ピンがシンク ピンによって提供されるリソースに依存している場合、接続が終了したときにソースに通知するのはシンク ピンの役割です。

クライアントは、IRP_MJ_DEVICE_CONTROL を使用して DeviceIoControl ルーチン (Microsoft Windows SDK ドキュメントで説明) を呼び出すことによって、カーネル ストリーミング ピンと対話操作します。 呼び出し元は、I/O スタックの場所構造体の Parameters.DeviceIoControl.IoControlCode に配置する I/O コントロール コードによって要求を識別します。

要求をサポートするために、ミニドライバーは KsAllocateObjectHeader の呼び出しで KSDISPATCH_TABLE 構造体へのポインターを提供します。

書き込み要求には、ストリーム データへのポインターを含む KSSTREAM_HEADER 構造体の配列へのポインターが含まれます。 読み取り要求には、読み取りデータを返す空のヘッダー構造の配列へのポインターが含まれています。