PMRX_CREATE_V_NET_ROOT コールバック関数 (mrx.h)

[アーティクル]
10/13/2023

MRxCreateVNetRoot ルーチンは RDBSS によって呼び出され、ネットワークミニリダイレクターがV_NET_ROOT構造を作成し、場合によってはNET_ROOT構造体を作成するように要求します。

構文

PMRX_CREATE_V_NET_ROOT PmrxCreateVNetRoot;

NTSTATUS PmrxCreateVNetRoot(
  IN OUT PMRX_CREATENETROOT_CONTEXT Context
)
{...}

パラメーター

Context

[入力、出力]呼び出しが最後に完了したときに RDBSS に通知するためにネットワークミニリダイレクターによって使用されるコールバックコンテキストへのポインター。これには、Context-RxContext> での要求のRX_CONTEXT構造が含まれます。 Context パラメーターには、Context-pVNetRoot> で構築されるV_NET_ROOT構造体が含まれます。このV_NET_ROOT構造体には、pVNetRoot-pNetRoot> にあるNET_ROOT構造体へのポインターが含まれています。 NET_ROOT構造体には、pNetRoot-pSrvCall> のSRV_CALL構造体へのポインターも含まれています。

戻り値

RDBSS は、 MRxCreateVNetRoot が成功または失敗時にSTATUS_PENDINGを返す必要があります。 RDBSS では、この呼び出しが非同期的に完了することが想定されているため、この動作が発生します。ネットワークミニリダイレクターは、 STATUS_SUCCESSを MRxCreateVNetRoot の戻り値としてSTATUS_PENDINGにマップする必要があります。

呼び出しが完了し、Context 構造体の > Callback メンバーのルーチンがネットワークミニリダイレクターによって呼び出されると、最終的な完了状態は Context-VirtualNetRootStatus> メンバーと Context-NetRootStatus メンバーで返されます。これらのメンバーには、最初に、ネットワークミニリダイレクターが完了時にこの値を変更するまで、STATUS_SUCCESSが含まれます。呼び出しが正常に完了した場合、両方のメンバーにSTATUS_SUCCESSが含まれます。

V_NET_ROOTまたはNET_ROOT構造体を作成できなかった場合は、VirtualNetRootStatus または NetRootStatus メンバーに対して次のいずれかの一般的なエラーコードが返されます (ただし、他のエラーコードも可能です)。

リターンコード	説明
STATUS_CONNECTION_RESET	リモートリソースへの接続がリセットされました。
STATUS_IO_TIMEOUT	I/O 要求でタイムアウトが発生しました。
STATUS_RETRY	リモートブートサーバーが要求を満たす準備ができていません。
STATUS_UNEXPECTED_NETWORK_ERROR	通常、無効なハンドルによって予期しないネットワークエラーが発生しました。

注釈

RDBSS とネットワークミニリダイレクターの間のインターフェイスで使用される 2 つの重要な抽象化は、SRV_CALL構造とNET_ROOT/V_NET_ROOT構造です。 SRV_CALL構造体は、接続が確立されたサーバーに関連付けられているコンテキストに対応します。 NET_ROOT構造体は、サーバー上の共有に対応します。 V_NET_ROOT構造体は、ネットワークミニリダイレクターによって要求されたNET_ROOT構造の下の名前空間の一部として表示できます。

通常、NET_ROOT/V_NET_ROOT構造の作成には、少なくとも 1 つのネットワークラウンドトリップが含まれます。リモートリソースとのネットワーク接続を確立する必要があるため、この操作の完了にはかなりの時間がかかる場合があります。非同期操作を確実に続行するために、NET_ROOT/V_NET_ROOT構造体の作成は 2 フェーズアクティビティとしてモデル化されます。 NET_ROOT/V_NET_ROOT構造体を作成するためのネットワークミニリダイレクターに対する各呼び出しの後に、ネットワークミニリダイレクターから RDBSS へのコールバックが行われます。これは、RDBSS への要求の完了状態をネットワークミニリダイレクターに示します。 RDBSS は MRxCreateVNetRoot が非同期的に完了することを想定しているため、RDBSS は MRxCreateVNetRoot がSTATUS_PENDINGを返す必要があります。呼び出しが最後に完了すると、RDBSS はコールバックルーチンを使用して通知されます。

MRxCreateVNetRoot は、次の 2 つの問題を処理する必要があります。

新しいV_NET_ROOT構造体と、関連付けられている新しいNET_ROOT構造体が作成されています。
既存のNET_ROOT構造体に関連付けられている新しいV_NET_ROOT構造体が作成されています。

これら 2 つのケースは、NET_ROOT構造体に関連付けられているコンテキストが NULL かどうかを確認することで区別できます。

MRxCreateVNetRoot のネットワークミニリダイレクターの実装では、最初の呼び出しにSTATUS_PENDINGを返す必要があります。処理が完了すると、ネットワークミニリダイレクターは Context パラメーターの一部として渡されたコールバックルーチンを呼び出して、呼び出しが完了したことを RDBSS に通知し、完了状態を返します。ネットワークミニリダイレクターが呼び出すコールバックルーチンは、Context パラメーターとして渡されるMRX_CREATENETROOT_CONTEXT構造体の Callback メンバーとして指定されます。 MRxCreateVNetRoot 呼び出しの最終完了状態は、Context パラメーターの VirtualNetRootStatus メンバーと NetRootStatus メンバーに格納する必要があります。 NET_ROOT および V_NET_ROOT 構造体に対して個別の状態が返されることに注意してください。

ネットワークミニリダイレクターでの MRxCreateVNetRoot の実装も、トランスポートハンドルの必要性によって複雑になります。特定のトランスポート関連インターフェイスでは、すべての通信にハンドルを作成して使用する必要があります。 NET_ROOTまたはV_NET_ROOT構造を作成するには、ネットワーク通信用にトランスポート関連のハンドルを確立する必要があります。ネットワーク接続を確立するプロセスには時間がかかる場合があるため、接続が確立されたら、可能な限り通信に接続を使用するのが理にかなっています。リモートネットワークリソースへのトランスポートハンドルが確立されると、他の任意の数のアプリケーション要求で再利用できます。ユーザーアプリケーションが終了すると、プロセスに関連付けられているハンドルが削除されます。このため、有効期間が短い可能性がある一時的なユーザーモードプロセスのコンテキストでトランスポートハンドルを確立しても意味がありません。そのため、通常、NET_ROOTまたはV_NET_ROOT構造体は、これらのトランスポートハンドルが通信に使用されている間は消えない既知のプロセスのコンテキストで初期化する必要があります。

ネットワークミニリダイレクターでこれを管理するために使用される方法の 1 つは、RDBSS システムプロセスにこれらのトランスポートハンドルを割り当てることです。これは 、MRxCreateVNetRoot ルーチンの実行方法に影響します。 MRxCreateVNetRoot への要求が RDBSS システムプロセスのコンテキストで発行された場合、この呼び出しは直ちに実行でき、作業キューにポストする必要はありません。ただし、問題を回避するために、 MRxCreateVNetRoot への要求が他のプロセスからの場合、要求は後で実行するために RxDispatchToWorkerThread を 使用してシステム作業キューにポストされます。 RDBSS は、後でシステムスレッドの 1 つを使用して作業キュー要求を処理し、 MRxCreateVNetRoot を実行します。これにより、すべてのトランスポートハンドルがシステムプロセスによって所有されるようになります。

ネットワークミニリダイレクターは、RxGetRDBSSProcess を呼び出すことによって、MRxCreateVNetRoot の呼び出しが RDBSS から直接受信されたかどうかを判断できます。 RxGetRDBSSProcess は RDBBS プロセスを返します。この値は 、IoGetCurrentProcess を呼び出すことによって返される現在のプロセスと比較できます。 RDBSS システムプロセスのコンテキストで MRxCreateVNetRoot の呼び出しが開始されなかった場合、 MRxCreateVNetRoot はSTATUS_PENDINGを返し、RDBSS によって後で実行するために RxDispatchToWorkerThread を 使用して作業キューに呼び出しをポストできます。通常、これらの呼び出しは DelayedWorkQueue にポストされます。

MRxCreateVNetRoot の実装方法を決定するのは、ネットワークミニリダイレクターです。このプロセスにかなりの時間がかかる場合は、この呼び出しを非同期的に完了する必要があります。トランスポートハンドルが必要な場合、ネットワークミニリダイレクターでは、これらのハンドルを確立するために有効期間の長いシステムプロセスが必要な場合があります。

接続を確立できない場合、ネットワークミニリダイレクターは、NET_ROOTとV_NET_ROOT構造体を切断モードに切り替えて (これがサポートされている場合)、接続をオフラインで確立しようと試みることができます。

MRxCreateVNetRoot が完了すると、Context パラメーターは、ネットワークミニリダイレクターから更新された適切なNET_ROOTとV_NET_ROOT構造体情報で変更する必要があります。