NET_PNP_EVENT 结构 (netpnp.h)
NET_PNP_EVENT结构描述网络即插即用 (PnP) 事件、NDIS PnP 事件或电源管理事件。
语法
typedef struct _NET_PNP_EVENT {
NET_PNP_EVENT_CODE NetEvent;
PVOID Buffer;
ULONG BufferLength;
ULONG_PTR NdisReserved[4];
ULONG_PTR TransportReserved[4];
ULONG_PTR TdiReserved[4];
ULONG_PTR TdiClientReserved[4];
} NET_PNP_EVENT, *PNET_PNP_EVENT;
成员
NetEvent
将事件描述为下列事件之一的事件代码：
NetEventSetPower
指示电源管理器已发送设置电源请求，该请求指定转换到系统电源状态。 NDIS 将此状态转换为设备的相应设备电源状态。
有关详细信息，请参见“备注”部分。
NetEventQueryPower
指示电源管理器已发送查询电源请求，请求转换到系统电源状态。 NDIS 将此状态转换为设备的相应设备电源状态。
有关详细信息，请参见“备注”部分。
NetEventQueryRemoveDevice
指示 PnP 管理器已发送查询删除设备请求。 PnP 管理器发送此请求来查询是否可以在不中断操作的情况下删除设备。
NetEventCancelRemoveDevice
指示 PnP 管理器已发送取消删除设备请求。 在 PnP 管理器发送“删除设备查询”请求后，PnP 管理器发送此请求以取消删除设备。
NetEventReconfigure
指示网络组件的配置已更改。 例如，如果用户通过“网络”和“拨号Connections”文件夹更改 TCP/IP 的 IP 地址，则 NDIS 会将 NetEventReconfigure 事件指示为 TCP/IP 协议。 此外，中间驱动程序通常使用此事件作为触发器来调用 NdisIMInitializeDeviceInstanceEx 函数并启动其虚拟微型端口。 有关 NetEventReconfigure 的详细信息，请参阅 NetEventIMReEnableDevice。
NetEventBindList
向协议驱动程序指示其绑定列表处理顺序已重新配置。 此列表指示在处理时应用于绑定的相对顺序，例如，用户请求可能路由到多个绑定之一。 随此事件一起传递的缓冲区包含格式化为以 null 结尾的 Unicode 字符串的设备名称列表。 每个设备名称的格式与传递给 ProtocolBindAdapterEx 函数调用的 AdapterName 成员相同。
NetEventBindsComplete
指示协议驱动程序已绑定到它可以绑定到的所有 NIC。 除非将 PnP NIC 插入系统，否则 NDIS 不会向协议指示任何其他 NIC。
NetEventPnPCapabilities
指示用户启用或禁用基础适配器的唤醒功能。 (绑定由传递给 ProtocolNetPnPEvent 函数的 ProtocolBindingContext 参数指定 )
NetEventPause
指示指定的协议绑定应进入暂停状态。 在 NDIS 完成绑定的所有未完成发送请求后，绑定将进入“已暂停”状态。
NetEventRestart
指示指定的协议绑定已进入“正在重启”状态。 协议驱动程序准备好恢复绑定的发送和接收操作后，绑定将进入“正在运行”状态。
NetEventPortActivation
指示激活与指定绑定关联的端口列表。
NetEventPortDeactivation
指示停用与指定绑定关联的端口列表。
NetEventIMReEnableDevice
指示已更改 NDIS 6.0 或更高版本中间驱动程序的虚拟微型端口的配置。 NetEventIMReEnableDevice 类似于 NetEventReconfigure 事件，只是中间驱动程序接收单个虚拟微型端口的此事件， NetEventReconfigure 事件适用于所有中间驱动程序的虚拟微型端口。 例如，当用户禁用并从设备管理器或其他源启用单个虚拟微型端口时，中间驱动程序会收到 NetEventIMReEnableDevice 事件。 有关中间驱动程序电源管理的示例，请参阅 GitHub 上的 Windows 驱动程序示例存储库中提供的 NDIS MUX 中间驱动程序和通知对象驱动程序示例。
NetEventNDKEnable
指示当前已启用网络直接内核 (NDK) 。
NetEventNDKDisable
指示当前已禁用 NDK。
NetEventFilterPreDetach
指示筛选器即将分离，以便筛选器可以执行 FilterDetach 处理程序 (中无法执行的任何必要清理，因为此时 OID 和指示路径) 关闭。
NetEventBindFailed
指示发生了绑定事件失败。
NetEventSwitchActivate
指示 Hyper-V 可扩展交换机已完成激活，交换机扩展现在可以安全地查询进一步的交换机配置。 该指示仅在扩展微型端口发出的 Hyper-V 可扩展交换机堆栈中使用。 有关更多详细信息 ，请参阅查询 Hyper-V 可扩展交换机配置 和 NDIS_SWITCH_PARAMETERS 。
NetEventInhibitBindsAbove
阻止其他筛选器和协议绑定到微型端口适配器的同步事件。 之前绑定的任何筛选器或协议都将在事件完成之前取消绑定。 使用规则如下。
- 避免使微型端口适配器处于抑制状态，超过 1000 毫秒。
- 此事件只能在 MiniportInitializeEx 开始后发出，不得在 MiniportHaltEx 返回后发出。
- 仅当微型端口适配器处于 D0 状态时，才能发出此事件。
- 由于此事件处于阻塞状态，因此不应由任何会导致死锁的上下文发出。
- 发出此事件时，不得持有锁。
- 必须在PASSIVE_LEVEL发出此事件。
NetEventAllowBindsAbove
反转 NetEventInhibitBindsAbove 效果的异步事件。 使用规则如下。
- 此事件只能在 MiniportInitializeEx 开始后发出，不得在 MiniportHaltEx 返回后发出。
- 仅当微型端口适配器处于 D0 状态时，才能发出此事件。
- 发出此事件时，不得持有锁。
- 必须在PASSIVE_LEVEL发出此事件。
NetEventRequirePause
指示协议和筛选器（包括微型端口适配器）必须暂停的同步事件。 当 NdisMNetPnPEvent 例程返回时，保证会暂停协议和筛选器以及微型端口适配器。 使用规则如下。
- 避免在 NetEventAllowStart 和 NetEventRequirePause 事件之间延迟超过 1000 毫秒，以防止用户应用程序出现延迟。
- 此事件只能在 MiniportInitializeEx 开始后发出，不得在 MiniportHaltEx 返回后发出。
- 无法保证 NDIS 会在发出此事件后调用 MiniportPause 。 特别是，如果微型端口适配器已暂停，NDIS 不会引入额外的启动-暂停循环。 这意味着 MiniportPause 调用的次数不大于、小于或等于此事件的发出量。
- 由于此事件处于阻塞状态，因此不应由任何会导致死锁的上下文发出。
- 发出此事件时不得持有锁。
NetEventAllowStart
指示协议和筛选器（包括微型端口适配器）的异步事件不需要暂停。 使用规则如下所示。 在 NdisMNetPnPEvent 例程返回后，无法保证协议和筛选器中的任何驱动程序处于暂停状态。
- 此事件只能在 MiniportInitializeEx 开始后发出，不得在 MiniportHaltEx 返回后发出。
- 由于此事件是阻塞事件，因此不应由任何会导致死锁的上下文发出。
- 发出此事件时不得持有锁。
Buffer
缓冲区的地址，该缓冲区包含特定于 NetEvent 成员中指示的事件的信息。 对于每种类型的事件，缓冲区包含以下信息：
NetEventSetPower
缓冲区包含设备要转换到的设备电源状态。
当 NDIS 调用协议驱动程序的 ProtocolNetPnPEvent 函数时，设备状态NDIS_DEVICE_POWER_STATE，可以是以下值之一：
NdisDeviceStateUnspecified
网络设备不支持电源管理。
NdisDeviceStateD0
完全供电状态，设备提供完整的功能和性能。
NdisDeviceStateD1
低功耗状态，设备不接受来自主机的传输请求，设备接收的数据不会传输到主机内存，并且不会发生中断。 某些设备上下文可能会丢失。 根据 NIC 及其微型端口驱动程序的功能，设备可能能够生成唤醒信号。
NdisDeviceStateD2
类似于 NdisDeviceStateD1 的低功率状态，只不过通常节省更多功率和更少的上下文，并且转换到完全供电状态需要更多时间。
NdisDeviceStateD3
关闭状态，其中已从设备中完全移除电源。
对于协议驱动程序， NdisDeviceStateD0 表示 NIC 已完全供电，可用于正常操作。 任何其他设备状态意味着设备未完全供电，无法发送和接收网络数据。
NetEventQueryPower
缓冲区包含为设备请求的设备电源状态。 设备状态NDIS_DEVICE_POWER_STATE (NetEventSetPower 值说明) 中所述。
NetEventQueryRemoveDevice
缓冲区内容为 NULL。
NetEventCancelRemoveDevice
缓冲区内容为 NULL。
NetEventReconfigure
缓冲区可以包含特定于协议的数据。 协议驱动程序负责验证此数据。
NetEventBindList
缓冲区包含已修改的网络组件的绑定列表， 将 结构传递给NET_PNP_EVENT_NOTIFICATION。 绑定列表是一系列以 null 结尾的 Unicode 字符串，具有REG_MULTI_SZ格式。 每个字符串都是适配器名称。 绑定到协议的 TDI 客户端使用此绑定列表对其绑定重新排序。 协议驱动程序负责验证此列表。
NetEventBindsComplete
缓冲区内容为 NULL。
NetEventPnPCapabilities
缓冲区是包含位掩码的 ULONG。 在位掩码中设置NDIS_DEVICE_WAKE_UP_ENABLE标志时，将启用 NIC 的唤醒功能。 否则，将禁用 NIC 的唤醒功能。 (绑定由传递给 ProtocolNetPnPEvent.) 的 ProtocolBindingContext 参数指定当设置为零时，此标志指示禁用 NIC 的唤醒功能。
NetEventPause
缓冲区包含 NDIS_PROTOCOL_PAUSE_PARAMETERS 结构。
NetEventRestart
缓冲区可能包含 NULL 或 NDIS_PROTOCOL_RESTART_PARAMETERS 结构。 NDIS 提供指向 NDIS_PROTOCOL_RESTART_PARAMETERS 结构的 RestartAttributes 成员中的 NDIS_RESTART_ATTRIBUTES 结构的指针。
NetEventPortActivation
缓冲区包含标识 NDIS 将激活的端口的 NDIS_PORT 结构列表中的第一个条目。 可以使用 NDIS_PORT 结构的 Next 成员获取列表中的下一个结构。
NetEventPortDeactivation
缓冲区包含一个端口号数组，这些端口号的类型NDIS_PORT_NUMBER (定义为 ULONG) ，用于标识 NDIS 将停用的 NDIS 端口。 若要计算数组中的元素数，请将 BufferLength 成员的值除以 NET_PNP_EVENT_NOTIFICATION的NetPnPEvent 成员中指定的 NET_PNP_EVENT结构中，按大小 (NDIS_PORT_NUMBER) 。
NetEventIMReEnableDevice
缓冲区包含指向 NDIS_STRING 类型的变量的指针，该变量包含以 null 结尾的 Unicode 字符串，该字符串为启用的设备命名虚拟微型端口的设备对象。 字符串是一个完整路径名称，例如\Device\DeviceName。
NetEventNDKEnable
Buffer 成员为 NULL。
NetEventNDKDisable
Buffer 成员为 NULL。
NetEventFilterPreDetach
Buffer 成员为 NULL。
NetEventBindFailed
缓冲区包含 NDIS_BIND_FAILED_NOTIFICATION 结构。
NetEventSwitchActivate
缓冲区内容为 NULL。
NetEventAllowBindsAbove
缓冲区内容为 NULL。
NetEventInhibitBindsAbove
缓冲区内容为 NULL。
NetEventAllowStart
缓冲区内容为 NULL。
NetEventRequirePause
缓冲区内容为 NULL。
BufferLength
Buffer 中特定于事件的信息的字节数。
NdisReserved[4]
保留供 NDIS 使用的区域。
TransportReserved[4]
为传输驱动程序保留的区域。
TdiReserved[4]
保留供 TDI 使用的区域。
TdiClientReserved[4]
保留供 TDI 客户端使用的区域。
注解
在 NDIS 6.0 及更高版本中，当操作系统向表示微型端口适配器的目标设备对象发出系统 PnP 事件或电源管理事件时，NDIS 会将事件转换为 NET_PNP_EVENT_NOTIFICATION 结构。 NET_PNP_EVENT_NOTIFICATION 结构的 NetPnPEvent 成员是NET_PNP_EVENT结构。
NDIS 通过调用协议驱动程序的 ProtocolNetPnPEvent 函数，将指向NET_PNP_EVENT 结构的指针传递给绑定到微型端口适配器的每个协议驱动程序。 协议驱动程序应保存此指针，因为指针是 指向 NdisCompleteNetPnPEvent 函数的 输入参数，驱动程序调用该函数以异步方式完成对 ProtocolNetPnPEvent 的调用。
NDIS 通过调用筛选器驱动程序的 FilterNetPnPEvent 函数，将指向NET_PNP_EVENT 结构的指针传递给绑定到微型端口适配器的每个筛选器驱动程序。 筛选器驱动程序不必保存此指针，因为驱动程序必须同步完成对 FilterNetPnPEvent 的调用。
从 NDIS 6.30 开始，当 NDIS 调用 ProtocolNetPnPEvent 或 FilterNetPnPEvent 函数时，协议或筛选器驱动程序必须遵循以下准则：
-
如果 NET_PNP_EVENT 结构的 NetEvent 成员设置为 NetEventSetPower，则驱动程序必须停止生成新的 I/O 请求。 此外，驱动程序不得等待任何挂起的 I/O 请求完成。
协议或筛选器驱动程序从 ProtocolNetPnPEvent 或 FilterNetPnPEvent 返回后，如果满足以下条件，NDIS 将不会在电源状态转换期间暂停和重启这些驱动程序：
- 基础微型端口驱动程序在 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 结构中设置 NDIS_MINIPORT_ATTRIBUTES_NO_PAUSE_ON_SUSPEND 标志。 驱动程序在调用 NdisMSetMiniportAttributes 函数时传递指向此结构的指针。
- 附加到微型端口驱动程序的所有筛选器驱动程序都支持 NDIS 6.30 或更高版本的 NDIS。
- 绑定到微型端口驱动程序的所有协议驱动程序都支持 NDIS 6.30 或更高版本的 NDIS。
- 如果 NET_PNP_EVENT 结构的 NetEvent 成员设置为 NetEventSetPower 或 NetEventQueryPower，则驱动程序不得等待任何挂起的 I/O 请求完成。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | 在 NDIS 5.1 和 NDIS 6.0 及更高版本中受支持。 有关此结构的 NDIS 5.1 版本的详细信息，请参阅 NET_PNP_EVENT (NDIS 5.1) 。 |
| 标头 | netpnp.h (包括 Ndis.h、Netpnp.h) |