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 会将网络微型重定向器驱动程序对象中的驱动程序调度入口点和快速 I/O 调度设置为指向 RDBSS 内部的例程。

RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER

设置此标志后，表示网络微型重定向程序不希望 RDBSS 初始化其内部网络名称表和清除程序数据结构以清理此名称表。将为希望处理网络共享名称本身的缓存而不使用 RDBSS 设施进行名称缓存和清理的网络微型重定向程序设置此选项。

[in] DeviceName

指向缓冲区的指针，该缓冲区包含命名设备对象的以零结尾的 Unicode 字符串。字符串必须是完整路径名称。此参数由 RDBSS 作为 DeviceName 传递到 IoCreateDevice 例程。

[in] DeviceExtensionSize

微型重定向程序驱动程序为要为设备对象的设备扩展分配的字节数指定的大小。设备扩展的内部结构是驱动程序定义的。此参数将添加到 RDBSS 使用的设备扩展的大小中，并由 RDBSS 作为 DeviceExtensionSize 参数传递给 IoCreateDevice 例程。

[in] DeviceType

创建设备对象时使用的设备类型。这指定系统定义的FILE_DEVICE_XXX常量之一，这些常量指示设备类型或供应商为新类型的设备定义值。对于网络微型重定向程序驱动程序，此值通常FILE_DEVICE_NETWORK_FILE_SYSTEM。此参数作为 DeviceType 由 RDBSS 传递到 IoCreateDevice 例程。

[in] DeviceCharacteristics

创建设备对象时使用的设备特征。这指定一个或多个系统定义的常量（组合在一起），这些常量提供有关驱动程序设备的其他信息。此值必须包含网络微型重定向程序驱动程序的FILE_REMOTE_DEVICE，但这可以与其他特征（例如FILE_DEVICE_SECURE_OPEN）结合使用。此参数由 RDBSS 作为 DeviceCharacteristics 传递到 IoCreateDevice 例程。

返回值

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 为网络微型重定向程序驱动程序创建设备对象。

作为此注册过程的一部分，网络微型重定向程序将参数传递给 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 回调例程必须由网络微型重定向程序驱动程序实现，除非网络微型重定向程序保留其自己的驱动程序调度入口点。否则，在 MrxStart 成功返回之前，RDBSS 将仅允许以下 I/O 请求数据包通过驱动程序：

设备创建操作和设备操作的 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 例程调用 RxStartMinirdr ，因为某些启动处理需要完成驱动程序初始化。收到 RxStartMinirdr 调用后，RDBSS 将通过调用网络微型重定向器的 MrxStart 例程来完成启动过程。如果对 MrxStart 的调用返回成功，则 RDBSS 将 RDBSS 中微型重定向器的内部状态设置为RDBSS_STARTED。