RxRegisterMinirdr 函式 (mrx.h)

發行項
02/29/2024

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 會將驅動程式分派進入點和網路迷你重新導向器驅動程序物件中的快速 I/O 分派設定為指向 RDBSS 內部的例程。

RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER

設定此旗標時，表示網路迷你重新導向器不希望 RDBSS 初始化其內部網路名稱數據表，以及清除此名稱數據表的清除程式數據結構。此選項會設定為想要處理網路共享名稱本身快取的網路迷你重新導向器，而不會使用 RDBSS 設施進行名稱快取和清除。

[in] DeviceName

緩衝區的指標，其中包含名稱為裝置物件的零終止 Unicode 字串。字串必須是完整路徑名稱。此參數會以 DeviceName 的形式傳遞至 RDBSS 的 IoCreateDevice 例程。

[in] DeviceExtensionSize

迷你重新導向器驅動程式所指定的大小，用於為裝置對象的裝置延伸模組配置位元組數目。裝置延伸模組的內部結構是驅動程式定義的。此參數會新增至 RDBSS 所使用的裝置延伸模組大小，並傳遞為 RDBSS 的 IoCreateDevice 例程的 DeviceExtensionSize 參數。

[in] DeviceType

建立裝置物件時所使用的裝置類型。這會指定其中一個系統定義的FILE_DEVICE_XXX常數，指出裝置類型或新類型裝置的廠商定義值。此值通常FILE_DEVICE_NETWORK_FILE_SYSTEM網路迷你重新導向器驅動程式。此參數會以 DeviceType 的形式傳遞至 RDBSS 的 IoCreateDevice 例程。

[in] DeviceCharacteristics

建立裝置物件時所使用的裝置特性。這會指定一或多個系統定義的常數，結合在一起，以提供驅動程式裝置的其他資訊。此值必須包含網路迷你重新導向器驅動程式的FILE_REMOTE_DEVICE，但這可能會與其他特性結合，例如FILE_DEVICE_SECURE_OPEN。此參數會以 DeviceCharacteristics 的形式傳遞至 RDBSS 的 IoCreateDevice 例程。

傳回值

RxRegisterMinirdr 會在成功時傳回STATUS_SUCCESS，或在失敗時傳回下列其中一個錯誤值：

傳回碼	Description
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 來建立網路迷你重新導向器驅動程式的裝置物件。

在此註冊程式中，網路迷你重新導向器會將參數傳遞至 RxRegisterMinirdr ，這是大型結構的指標，MINIRDR_DISPATCH，其中包含網路迷你重新導向器的組態資訊，以及網路迷你重新導向器驅動程式所實作回呼例程的指標分派表。此組態數據可用來設定內部 RDBSS 數據表，以搭配此網路迷你重新導向器使用。 RDBSS 會使用此結構中傳遞的回呼例程來與網路迷你重新導向器通訊。網路迷你重新導向器可以選擇只實作其中一些回呼例程。未實作的任何回呼例程都應該設定為傳遞至 RDBSS 之分派數據表中的 NULL 指標。 RDBSS 只會呼叫網路迷你重新導向器所實作的回呼例程。

請注意， RxRegisterMinirdr 例程會設定網路迷你重新導向器驅動程式的所有驅動程式分派例程，以指向最上層 RDBSS 分派例程 RxFsdDispatch。網路迷你重新導向器可以藉由儲存其驅動程式分派進入點的複本、呼叫 RxRegisterMinirdr，以及在呼叫 RxRegisterMinirdr 傳回之後，以自己的進入點重寫驅動程式分派，以覆寫此行為。如果 controls 參數中設定了RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH位，網路迷你重新導向器也可以防止其驅動程式分派例程被 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。

網路迷你重新導向器實際上不會啟動作業，直到它收到對 MRxStart 例程的呼叫，這是在MINIRDR_DISPATCH 結構中傳遞的回呼例程之一。如果想要接收作業的回呼，則網路迷你重新導向器驅動程序必須實作 MrxStart 回呼例程，除非網路迷你重新導向器保留自己的驅動程式分派進入點。否則，RDBSS 只會允許下列 I/O 要求封包傳送至驅動程式，直到 MrxStart 成功傳回為止：

IRP 要求裝置建立作業和裝置作業，其中 IRPSP 上的 FileObject->FileName.Length 參數為零， 而 FileObject->RelatedFileObject 參數為 NULL。

對於任何其他 IRP 要求，RDBSS 分派例程 RxFsdDispatch 會傳回STATUS_REDIRECTOR_NOT_STARTED的狀態。

RDBSS 分派例程也會失敗下列 I/O 要求封包的任何要求：

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

呼叫 RxStartMiniRdr 例程時，RDBSS 會呼叫網路迷你重新導向器 MrxStart 例程。 RDBSS RxStartMinirdr 通常會因為來自使用者模式應用程式或服務的 FSCTL 或 IOCTL 要求而呼叫，以啟動網路迷你重新導向器。在成功呼叫 RxRegisterMinirdr 之後，無法從網路迷你重新導向器的 DriverEntry 例程呼叫 RxRegisterMinirdr 進行，因為某些開始處理需要完成驅動程式初始化。收到 RxStartMinirdr 呼叫之後，RDBSS 會藉由呼叫網路迷你重新導向器的 MrxStart 例程來完成啟動程式。如果呼叫 MrxStart 傳回成功，RDBSS 會將 RDBSS 中迷你重新導向器的內部狀態設定為RDBSS_STARTED。