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

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

MRxCreateSrvCall ルーチンは RDBSS によって呼び出され、ネットワークミニリダイレクターがSRV_CALL構造を作成し、サーバーとの接続を確立するように要求します。

構文

PMRX_CREATE_SRVCALL PmrxCreateSrvcall;

NTSTATUS PmrxCreateSrvcall(
  IN OUT PMRX_SRV_CALL SrvCall,
  IN OUT PMRX_SRVCALL_CALLBACK_CONTEXT SrvCallCallBackContext
)
{...}

パラメーター

SrvCall

[入力、出力]作成するSRV_CALL構造体へのポインター。

SrvCallCallBackContext

[入力、出力] MRxCreateSrvCall 要求が最終的に完了したときに RDBSS に通知するためにネットワークミニリダイレクターによって使用されるコールバックコンテキストへのポインター。 SrvCallCallBackContext パラメーターは、この要求のRX_CONTEXT構造体と、MRxCreateSrvCall 要求が最終的に完了したときにミニリダイレクターが呼び出すコールバック ルーチンを含むMRX_SRVCALLDOWN_STRUCTURE構造体を指します。

戻り値

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

呼び出しが完了すると、SrvCallCallBackContext-Status> メンバーで最終的な完了状態が返され、MRX_SRVCALLDOWN_STRUCTURE構造体の Callback メンバー内のルーチンがネットワークミニリダイレクターによって呼び出されます。このメンバーには、ネットワークミニリダイレクターが完了時にこの値を変更するまで、最初はSTATUS_BAD_NETWORK_PATHが含まれています。

SrvCallCallBackContext-Status> メンバーには、呼び出しが完了した後の成功時のSTATUS_SUCCESS、または失敗時の次の一般的なエラーコードのいずれかが含まれます (ただし、他のエラーコードが考えられます)。

リターンコード	説明
STATUS_BAD_NETWORK_PATH	指定されたネットワークパスが正しくありません。
STATUS_NETWORK_UNREACHABLE	ネットワークに到達できませんでした。

注釈

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

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

MRxCreateSrvCall のネットワークミニリダイレクターの実装は、最初の呼び出しにSTATUS_PENDINGを返す必要があります。処理が完了すると、ネットワークミニリダイレクターは 、SrvCallCallBackContext パラメーターの一部として渡されるコールバックルーチンを呼び出して、呼び出しが完了したことを RDBSS に通知し、完了状態を返します。ネットワークミニリダイレクターが呼び出すコールバックルーチンは、SrvCallCallBackContext パラメーターのMRX_SRVCALLDOWN_STRUCTUREの Callback メンバーとして指定されます。呼び出しの最終的な完了状態は、SrvCallCallBackContext パラメーターの Status メンバーに格納する必要があります。

成功した場合、ネットワークミニリダイレクターは、SrvCallCallBackContext の RecommunicateContext メンバーにいくつかの値を格納する必要もあります。 RecommunicateContext メンバーに格納されている値は、MRxCreateSrvCall が成功した場合に RecommunicateContext パラメーターで RDBSS が MRxSrvCallWinnerNotify に渡す値です。また、ネットワークミニリダイレクターは、作成されたSRV_CALL構造体の SrvCall パラメーターに適切なデータを入力する必要があります。 MRxCreateSrvCall に渡される SrvCall パラメーターは、SrvCallCallBackContext パラメーターのMRX_SRVCALLDOWN_STRUCTUREの SrvCall メンバーと同じであることに注意してください。この同じ SrvCall パラメーターは、SrvCall パラメーターの MRxSrvCallWinnerNotify にも渡されます。

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

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

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

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

この呼び出しが完了したら、 SrvCall パラメーターを、ネットワークミニリダイレクターから更新されたSRV_CALL構造体情報で変更する必要があります。

UNC プロバイダーとしてのサポートを示すネットワークミニリダイレクターは、 MRxCreateSrvCall の呼び出しとして、マルチ UNC プロバイダー (MUP) からプレフィックス要求を受け取ります。 UNC の名前付けと MUP の詳細については、「 UNC の名前付けと MUP のサポート」を参照してください。