RxRegisterMinirdr 関数 (mrx.h)

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

RxRegisterMinirdr は、RDBSS にドライバーを登録するネットワークミニリダイレクタードライバーによって呼び出されます。これにより、登録情報が内部登録テーブルに追加されます。 RDBSS では、ネットワークミニリダイレクター用のデバイスオブジェクトもビルドされます。

構文

NTSTATUS RxRegisterMinirdr(
  [out]     OUT PRDBSS_DEVICE_OBJECT *DeviceObject,
  [in, out] IN OUT PDRIVER_OBJECT    DriverObject,
  [in]      IN PMINIRDR_DISPATCH     MrdrDispatch,
  [in]      IN ULONG                 Controls,
  [in]      IN PUNICODE_STRING       DeviceName,
  [in]      IN ULONG                 DeviceExtensionSize,
  [in]      IN DEVICE_TYPE           DeviceType,
  [in]      IN ULONG                 DeviceCharacteristics
);

パラメーター

[out] DeviceObject

作成されたデバイスオブジェクトが格納される場所へのポインター。

[in, out] DriverObject

ネットワークミニリダイレクタードライバーのドライバーオブジェクトへのポインター。各ドライバーは、 DriverEntry ルーチンへのパラメーターで、ドライバーオブジェクトへのポインターを受け取ります。このドライバーオブジェクトは、ネットワークミニリダイレクタードライバーのデバイスオブジェクトを作成するために使用されます。

[in] MrdrDispatch

ネットワークミニリダイレクターのディスパッチテーブルへのポインター。このディスパッチテーブルには、ネットワークミニリダイレクターの構成情報と、ネットワークミニリダイレクターカーネルドライバーによって実装されたコールバックルーチンへのポインターのテーブルが含まれています。 RDBSS は、このコールバックルーチンの一覧を使用して、ネットワークミニリダイレクタードライバーを呼び出します。

[in] Controls

ネットワークミニリダイレクタードライバーの機能と、RDBSS でネットワークミニリダイレクタードライバーの初期化と名前テーブルキャッシュを処理する方法を決定するオプションのセット。これらのオプションには、次のビットの任意の組み合わせを含めることができます。

RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS

このフラグを設定すると、ネットワークミニリダイレクターが UNC 名をサポートしていないことを示します。

RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS

このフラグを設定すると、ネットワークミニリダイレクターが mailslot をサポートしていないことを示します。

RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH

このフラグを設定すると、ネットワークミニリダイレクターが RDBSS 内部ルーチンを指すようにミニリダイレクタードライバーのドライバーディスパッチエントリポイントを初期化する RDBSS を望まないことを示します。このオプションは、通常とは異なる状況でのみ使用されます。通常、RDBSS は、RDBSS 内部のルーチンを指すように、ドライバーディスパッチエントリポイントと、ネットワークミニリダイレクタードライバーオブジェクト内の高速 I/O ディスパッチを設定します。

RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER

このフラグを設定すると、ネットワークミニリダイレクターは、RDBSS がこの名前テーブルを清掃するための内部ネットワーク名テーブルとスカベンジャーデータ構造を初期化することを望まないことを示します。このオプションは、ネットワーク共有名自体のキャッシュを処理し、名前のキャッシュと清掃に RDBSS 機能を使用しないネットワークミニリダイレクターに設定されます。

[in] DeviceName

デバイスオブジェクトの名前を指定する 0 で終わる Unicode 文字列を含むバッファーへのポインター。文字列は完全なパス名である必要があります。このパラメーターは、RDBSS によって DeviceName として IoCreateDevice ルーチンに渡されます。

[in] DeviceExtensionSize

デバイスオブジェクトのデバイス拡張機能に割り当てられるバイト数のミニリダイレクタードライバーによって指定されたサイズ。デバイス拡張機能の内部構造はドライバー定義です。このパラメーターは、RDBSS によって使用されるデバイス拡張機能のサイズに追加され、 DeviceExtensionSize パラメーターとして RDBSS によって IoCreateDevice ルーチンに渡されます。

[in] DeviceType

デバイスオブジェクトの作成時に使用されるデバイスの種類。これは、デバイスの種類を示すシステム定義のFILE_DEVICE_XXX定数の 1 つ、または新しい種類のデバイスのベンダー定義値を指定します。通常、この値は、ネットワークミニリダイレクタードライバーに対してFILE_DEVICE_NETWORK_FILE_SYSTEMされます。このパラメーターは、 RDBSS によって DeviceType として IoCreateDevice ルーチンに渡されます。

[in] DeviceCharacteristics

デバイスオブジェクトの作成時に使用されるデバイス特性。これは、ドライバーのデバイスに関する追加情報を提供する 1 つ以上のシステム定義定数を組み合わせて指定します。この値には、ネットワークミニリダイレクタードライバーのFILE_REMOTE_DEVICEを含める必要がありますが、これは、FILE_DEVICE_SECURE_OPENなどの他の特性と組み合わせることができます。このパラメーターは、RDBSS によって IoCreateDevice ルーチンに DeviceCharacteristics として渡されます。

戻り値

RxRegisterMinirdr は、成功した場合はSTATUS_SUCCESSを返し、失敗した場合は次のいずれかのエラー値を返します。

リターンコード	説明
STATUS_INSUFFICIENT_RESOURCES	デバイスオブジェクトを作成するためのリソースが不足していました。
STATUS_INVALID_PARAMETER	無効なパラメーターがルーチンに渡されました。このエラーは、 DeviceObject パラメーターが NULL ポインターの場合に返されます。
STATUS_OBJECT_NAME_COLLISION	このデバイスオブジェクトを作成しようとしたときに、名前の競合が発生しました。
STATUS_OBJECT_NAME_EXISTS	この名前のデバイスオブジェクトは既に存在します。
STATUS_UNSUCCESSFUL	デバイスオブジェクトを作成するための呼び出しで NULL デバイスオブジェクトが返されました。

注釈

ドライバーがカーネルによって読み込まれるたびに、ネットワークミニリダイレクターが RDBSS に登録され、ドライバーがアンロードされると RDBSS で登録解除されます。非モノリシックドライバー (SMB ネットワークミニリダイレクター) は、別のカーネルドライバー であるRdbss.sysと通信します。 Rdbsslib.lib と静的にリンクするモノリシックネットワークミニリダイレクタードライバーの場合、この通信は単に Rdbsslib.lib ライブラリルーチンの呼び出しにすぎません。

ネットワークミニリダイレクターは、RDBSS からエクスポートされた登録ルーチン RxRegisterMinirdr を呼び出すことによって読み込まれたことを RDBSS に通知します。ネットワークミニリダイレクタードライバーが最初に ( DriverEntry ルーチンで) 起動すると、ドライバーは RDBSS RxRegisterMinirdr ルーチンを呼び出して、ネットワークミニリダイレクタードライバーを RDBSS に登録します。 RxRegisterMinirdr に渡されるパラメーターに基づいて、RDBSS は IoCreateDevice を呼び出して、ネットワークミニリダイレクタードライバーのデバイスオブジェクトを作成します。

この登録プロセスの一環として、ネットワークミニリダイレクターは、ネットワークミニリダイレクターの構成情報と MINIRDR_DISPATCH、ネットワークミニリダイレクタードライバーによって実装されたコールバックルーチンへのポインターのディスパッチテーブルを含む大きな構造体へのポインターである RxRegisterMinirdr にパラメーターを渡します。この構成データは、このネットワークミニリダイレクターで使用する内部 RDBSS テーブルを構成するために使用されます。 RDBSS では、この構造体で渡されたコールバックルーチンを使用して、ネットワークミニリダイレクターと通信します。ネットワークミニリダイレクターは、これらのコールバックルーチンの一部のみを実装するように選択できます。実装されていないコールバックルーチンは、RDBSS に渡されるディスパッチテーブル内の NULL ポインターに設定する必要があります。ネットワークミニリダイレクターによって実装されたコールバックルーチンのみが RDBSS によって呼び出されます。

RxRegisterMinirdr ルーチンは、最上位レベルの RDBSS ディスパッチルーチン RxFsdDispatch を指すネットワークミニリダイレクタードライバーのすべてのドライバーディスパッチルーチンを設定します。ネットワークミニリダイレクターは、ドライバーディスパッチエントリポイントのコピーを保存し、 RxRegisterMinirdr を呼び出し、 RxRegisterMinirdr への呼び出しが返された後にドライバーディスパッチを独自のエントリポイントで書き換えることで、この動作をオーバーライドできます。また、ネットワークミニリダイレクターは、RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH ビットが Controls パラメーターに設定されている場合に、ドライバーディスパッチルーチンが RxRegisterMinirdr ルーチンによってコピーされないようにすることもできます。

RxRegisterMinirdr 呼び出しが成功した場合、DeviceObject パラメーターによって指RDBSS_DEVICE_OBJECT内のメンバーの数が初期化されます。

Dispatch メンバーは MrdrDispatch パラメーターに設定されます。
RegistrationControls メンバーは Controls パラメーターに設定されます。
DeviceName メンバーは DeviceName パラメーターに設定されます。
Controls パラメーターのRX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS ビットが設定されていない場合、RegisterUncProvider メンバーは TRUE に設定されます。
Controls パラメーターのRX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS ビットが設定されていない場合、RegisterMailSlotProvider メンバーは TRUE に設定されます。
NetworkProviderPriority メンバーは、MUP が使用するネットワークプロバイダーの優先順位に設定されます。

RxRegisterMinirdr 呼び出しが成功し、Controls パラメーターのRX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER ビットが設定されていない場合は、DeviceObject パラメーターによって指RDBSS_DEVICE_OBJECT他のメンバーの数が初期化されます。これには、次が含まれます。

pRxNetNameTable メンバー構造体が初期化されます。
RxNetNameTableInDeviceObject.IsNetNameTable メンバーは TRUE に設定されています。
pRdbssScavenger メンバー構造体が初期化されます。

RxRegisterMinirdr 呼び出しが成功した場合、RDBSS は RDBSS のネットワークミニリダイレクターの内部状態をRDBSS_STARTABLEに設定します。

ネットワークミニリダイレクターは、MINIRDR_DISPATCH構造体で渡されたコールバックルーチンの 1 つである MRxStart ルーチンの呼び出しを受け取るまで、実際には操作を開始しません。 MrxStart コールバックルーチンは、ネットワークミニリダイレクターが独自のドライバーディスパッチエントリポイントを保持しない限り、操作のコールバックを受信する場合は、ネットワークミニリダイレクタードライバーによって実装する必要があります。それ以外の場合、RDBSS では、 MrxStart が正常に返されるまで、ドライバーへの次の I/O 要求パケットのみが許可されます。

IRPSP の FileObject->FileName.Length パラメーターが 0 で、 FileObject->RelatedFileObject パラメーターが NULL であるデバイス作成操作とデバイス操作に対する IRP 要求。

その他の IRP 要求の場合、RDBSS ディスパッチルーチン RxFsdDispatch は、STATUS_REDIRECTOR_NOT_STARTEDの状態を返します。

RDBSS ディスパッチルーチンは、次の I/O 要求パケットに対する要求も失敗します。

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

ネットワークミニリダイレクター MrxStart ルーチンは、 RxStartMiniRdr ルーチンが呼び出されたときに RDBSS によって呼び出されます。 RDBSS RxStartMinirdr は、通常、ネットワークミニリダイレクターを開始するユーザーモードのアプリケーションまたはサービスからの FSCTL または IOCTL 要求の結果として呼び出されます。 RxRegisterMinirdr の呼び出しが成功した後、ネットワークミニリダイレクターの DriverEntry ルーチンから RxStartMinirdr を呼び出すことはできません。これは、一部の開始処理でドライバーの初期化が完了する必要があるためです。 RxStartMinirdr 呼び出しを受信すると、RDBSS は、ネットワークミニリダイレクターの MrxStart ルーチンを呼び出すことによって開始プロセスを完了します。 MrxStart の呼び出しで成功が返された場合、RDBSS は RDBSS のミニリダイレクターの内部状態をRDBSS_STARTEDに設定します。