NdisMRegisterDevice 函数 (ndis.h)

项目
03/10/2023

注意 NDIS 5. x 已弃用，由 NDIS 6 取代。 x。有关新的 NDIS 驱动程序开发，请参阅从 Windows Vista 开始的网络驱动程序。有关移植 NDIS 5 的信息。 NDIS 6 的 x 驱动程序。 x，请参阅将 NDIS 5.x 驱动程序移植到 NDIS 6.0。

NdisMRegisterDevice 函数创建命名设备对象以及设备对象与该设备的用户可见名称之间的符号链接。

语法

NDIS_STATUS NdisMRegisterDevice(
  [in]  NDIS_HANDLE      NdisWrapperHandle,
  [in]  PNDIS_STRING     DeviceName,
  [in]  PNDIS_STRING     SymbolicName,
  [in]  PDRIVER_DISPATCH *MajorFunctions,
  [in]  PDEVICE_OBJECT   *pDeviceObject,
  [out] NDIS_HANDLE      *NdisDeviceHandle
);

参数

[in] NdisWrapperHandle

指定 NdisMInitializeWrapper 返回的句柄。

[in] DeviceName

指向NDIS_STRING类型的指针，该类型包含命名设备对象的以 null 结尾的 Unicode 字符串。字符串必须是完整路径名称，例如 \Device\DeviceName。对于 Windows 2000 及更高版本，NDIS 将NDIS_STRING类型定义为 UNICODE_STRING 类型。

[in] SymbolicName

指向NDIS_STRING类型的指针，该类型包含 Unicode 字符串，该字符串是正在注册的设备的 Win32 可见名称。通常， SymbolicName 具有以下格式： \DosDevices\SymbolicName。

[in] MajorFunctions

指向设备驱动程序调度例程的一个或多个入口点数组的指针。驱动程序必须设置与驱动程序为设备对象处理的IRP_MJ_XXX 代码一样多的单独调度入口点。每个调度例程的声明如下：

NTSTATUS
(*PDRIVER_DISPATCH) (
    IN PDEVICE_OBJECT Device Object,
    IN PIRP Irp
)   ;

驱动程序不得为即插即用或电源管理处理程序提供入口点，因为创建的设备对象不适用于物理设备，因此不会接收即插即用或电源管理 IRP。

[in] pDeviceObject

如果调用成功，则指向新创建的设备对象的指针。

[out] NdisDeviceHandle

指向调用方提供的变量的指针，在该变量中，此函数如果成功，则返回设备对象的句柄。此句柄是驱动程序随后调用的 NdisMDeregisterDevice 函数的必需参数。

返回值

如果成功，则 NdisMRegisterDevice 返回STATUS_SUCCESS;如果调用方不是 NDIS 微型端口驱动程序，则返回NDIS_STATUS_NOT_SUPPORTED，如果失败，则返回失败代码。

注解

中间驱动程序或微型端口驱动程序可能需要单独的独立设备对象。例如，当 NIC 的微型端口驱动程序未启动并运行时，中间微型端口驱动程序可能需要独立设备对象来监视基础 NIC 的状态。在这种情况下，若要获取 NIC 的状态，用户模式应用程序或环境子系统会将 IRP 发送到设备对象。 IRP 由中间驱动程序处理。如果没有独立设备对象，NIC 的状态仅在 NIC 的微型端口驱动程序启动并运行时可用。

在 DriverEntry 调用 NdisMInitializeWrapper 后，中间驱动程序或微型端口驱动程序通过从其 DriverEntry 函数调用 NdisMRegisterDevice 来创建设备对象。 NdisMRegisterDevice 创建命名设备对象，以及设备对象名称和该设备的用户可见名称之间的符号链接。如果调用 NdisMRegisterDevice 成功，I/O 管理器会为设备对象本身和与设备对象关联的所有其他数据结构（包括驱动程序的设备扩展）分配非分页池中的存储。使用 NdisMRegisterDevice 创建的对象的设备扩展保留供 NDIS 使用，驱动程序不能使用。

使用 NdisMRegisterDevice 创建的设备对象的函数与分别使用 IoCreateDevice 和 IoCreateSymbolicLink 创建的设备对象和符号链接的方式相同。微型端口驱动程序负责处理它为设备对象接收的所有 IRP。 (NDIS 处理发送到设备对象的所有即插即用和电源管理 IRP。) 驱动程序使用它在向 NdisMRegisterDevice 提供 MajorFunctions 指针时注册的调度例程来处理发送到设备对象的 IRP。有关设备对象、IRP 和调度例程的详细信息，请参阅设备对象和设备堆栈、处理 IRP 和编写调度例程。

NDIS 微型端口和中间驱动程序不应调用 IoCreateDevice 或 IoCreateSymbolicLink。相反，如果 NDIS 驱动程序必须创建设备对象，则应调用 NdisMRegisterDevice。微型端口和中间驱动程序绝不应尝试通过调用 IoAttachDevice 将设备对象堆叠在物理设备对象上。

使用 NdisMRegisterDevice 创建的设备对象不是物理设备对象，因此不会接收即插即用或电源管理 IRP。因此，NdisMRegisterDevice 的调用方必须省略 MajorFunctions 指向的数组中即插即用或电源管理处理程序的入口点。

请注意，如果使用 NdisMRegisterDevice 创建的设备对象的句柄处于打开状态，则无法卸载创建设备对象的驱动程序。因此，用户模式应用程序应执行以下操作之一：

当应用程序通过调用 RegisterDeviceNotification 函数在基础设备上注册设备事件通知时，请指定DBT_DEVTYP_HANDLE类型通知筛选器。 (有关 RegisterDeviceNotification 函数的详细信息，请参阅Microsoft Windows SDK文档。) 如果应用程序随后收到设备的DBT_DEVICEQUERYREMOVE事件，则应用程序应关闭打开的句柄。
当应用程序通过调用 RegisterDeviceNotification 函数在基础设备上注册设备事件通知时，请指定DBT_DEVTYP_DEVICEINTERFACE类型通知筛选器，并将GUID_NDIS_LAN_CLASS作为接口类 GUID。如果应用程序随后收到句柄所对应的设备接口的DBT_DEVICEREMOVECOMPLETE事件，则应用程序应关闭打开的句柄。

如果驱动程序对 NdisMRegisterDevice 的调用失败，驱动程序可以继续加载或不加载，具体取决于独立设备对象对驱动程序操作的关键程度。

目标平台：通用
版本：Windows Vista 中的 NDIS 6.0 驱动程序不支持。请改用 NdisRegisterDeviceEx。支持 Windows Vista 和 Windows XP 中的 NDIS 5.1 驱动程序。

要求

要求	值
Header	ndis.h (包括 Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL

NdisMRegisterDevice 函数 (ndis.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

反馈

其他资源