NdisIMInitializeDeviceInstanceEx 函数 (ndis.h)

项目
02/29/2024

NdisIMInitializeDeviceInstanceEx 函数启动虚拟微型端口的初始化操作，并选择性地为随后绑定的协议驱动程序设置有关虚拟微型端口的状态信息。

语法

NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
  [in]           NDIS_HANDLE  DriverHandle,
  [in]           PNDIS_STRING DriverInstance,
  [in, optional] NDIS_HANDLE  DeviceContext
);

参数

[in] DriverHandle

微型端口驱动程序处理 NdisMRegisterMiniportDriver 函数在 NdisMiniportDriverHandle 返回。

[in] DriverInstance

指向NDIS_STRING类型的指针，该类型描述系统默认字符集中调用方初始化的计数字符串。字符串包含注册表项的名称，驱动程序在其中存储有关虚拟微型端口的信息，并可能存储特定于绑定的信息。对于 Microsoft Windows 2000 及更高版本的驱动程序，此字符串包含 Unicode 字符。也就是说，对于 Windows 2000 及更高版本，NDIS 将NDIS_STRING类型定义为 UNICODE_STRING 类型。

[in, optional] DeviceContext

指向调用方提供的内存的指针，该内存要设置与驱动程序定义的设备上下文信息相关的虚拟微型端口，后者仍可使用更高级别的协议驱动程序（随后自行绑定到此虚拟微型端口）。如果中间驱动程序没有此类设备上下文区域，此参数可以为 NULL 。

返回值

NdisIMInitializeDeviceInstanceEx 可以返回以下任一项：

返回代码	说明
NDIS_STATUS_SUCCESS	NDIS 为中间驱动程序的虚拟微型端口启动了初始化操作。
NDIS_STATUS_NOT_ACCEPTED	NdisIMInitializeDeviceInstanceEx 失败，因为 DriverHandle 指定的设备已初始化。

注解

NDIS 中间驱动程序应从其 ProtocolBindAdapterEx 函数调用 NdisIMInitializeDeviceInstanceEx。无法从 NDIS 中间驱动程序调用 NdisIMInitializeDeviceInstanceEx 会有效地阻止该驱动程序成功加载。

在调用 NdisIMInitializeDeviceInstanceEx 之前，中间驱动程序的 ProtocolBindAdapterEx 函数应绑定到中间驱动程序正常运行所需的任何基础微型端口驱动程序。 ProtocolBindAdapterEx 函数还可以在 DeviceContext 上分配一个区域，并可能使用有关基础微型端口适配器功能的中间驱动程序确定的信息进行设置，并且是由 ProtocolBindAdapterEx 收集的。中间驱动程序的 MiniportInitializeEx 函数随后可能会使用此类信息来设置此上下文区域，其中包含有关驱动程序的虚拟微型端口的信息。

如果 NDIS 收到启动设备的IRP_MN_START_DEVICE IRP，则中间驱动程序对 NdisIMInitializeDeviceInstanceEx 的调用会导致 NDIS 调用中间驱动程序的 MiniportInitializeEx 函数。如果 NDIS 未收到此类 IRP，则 NDIS 不会调用中间驱动程序的 MiniportInitializeEx 函数。

对 MiniportInitializeEx 的调用可以在以后发生，因此不一定是在调用 NdisIMInitializeDeviceInstanceEx 的上下文中。如果 NDIS 从未为在调用 NdisIMInitializeDeviceInstanceEx 中引用的虚拟微型端口调用 MiniportInitializeEx，并且中间驱动程序不再需要虚拟微型端口，则中间驱动程序应调用 NdisIMCancelInitializeDeviceInstance 函数，用于取消虚拟微型端口的初始化。例如，假设中间驱动程序创建一个虚拟微型端口，以响应成功绑定到基础微型端口适配器。如果在 NDIS 调用 MiniportInitializeEx 之前删除该绑定，中间驱动程序应调用 NdisIMCancelInitializeDeviceInstance 来取消虚拟微型端口的初始化。

MiniportInitializeEx 分配驱动程序执行网络 I/O 操作所需的任何资源，例如调用 NdisMSetMiniportAttributes 函数，并将驱动程序的虚拟微型端口初始化为操作状态。然后，当中间驱动程序的初始化成功完成时，更高级别的协议驱动程序可以将自身绑定到其虚拟微型端口。

MiniportInitializeEx 返回控件后，中间驱动程序的设备上下文区域（如果有）可以包含任何中间驱动程序定义的数据，这些数据随后使绑定到同一虚拟微型端口的所有更高级别的协议驱动程序能够访问该上下文区域中的信息。此类更高级别的协议驱动程序可以使用查询中间驱动程序提供的设备上下文 NdisIMGetBindingContext 函数。

在 NDIS 调用中间驱动程序的 MiniportInitializeEx 函数之前，驱动程序可以调用 NdisIMCancelInitializeDeviceInstance 取消初始化操作。

在 NDIS 调用中间驱动程序的 MiniportInitializeEx 函数后，驱动程序必须调用 NdisIMDeInitializeDeviceInstance 用于反转初始化操作。

要求

要求	值
最低受支持的客户端	支持 NDIS 6.0 和 NDIS 5.1 驱动程序 (请参阅 Windows Vista 中的 NdisIMInitializeDeviceInstanceEx (NDIS 5.1) ) 。 NDIS 5.1 驱动程序支持 (请参阅 Windows XP 中的 NdisIMInitializeDeviceInstanceEx (NDIS 5.1) ) 。
目标平台	桌面
标头	ndis.h (包括 Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI 符合性规则	Irql_IM_Function (ndis)