PROTOCOL_NET_PNP_EVENT回调函数 (ndis.h)

项目
08/07/2023

NDIS 调用 ProtocolNetPnPEvent 函数，以向协议驱动程序指示网络即插即用事件、NDIS PnP 事件或电源管理事件。

注意必须使用 PROTOCOL_NET_PNP_EVENT 类型声明函数。有关详细信息，请参阅以下示例部分。

语法

PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;

NDIS_STATUS ProtocolNetPnpEvent(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}

参数

[in] ProtocolBindingContext

协议驱动程序分配的上下文区域的句柄，此驱动程序在其中维护每个绑定的运行时状态信息。协议驱动程序在调用 NdisOpenAdapterEx 函数时提供了此句柄。使用 NULLProtocolBindingContext 指示的 NetEventXxx 事件适用于所有绑定。 NetEventBindList 和 NetEventBindsComplete 始终使用 NULLProtocolBindingContext 进行指示。可以使用指定的 ProtocolBindingContext 或 NULLProtocolBindingContext 来指示 NetEventReconfigure。

[in] NetPnPEventNotification

指向 NET_PNP_EVENT_NOTIFICATION结构，用于描述 NDIS 向协议驱动程序指示的即插即用事件或电源管理事件。

返回值

ProtocolNetPnPEvent 可以返回以下任一项：

返回代码	说明
NDIS_STATUS_SUCCESS	协议驱动程序已成功处理指示的网络即插即用事件、NDIS PnP 事件或电源管理事件。此状态代码的含义取决于缓冲中的 NetEvent 代码NetPnPEvent 的NET_PNP_EVENT_NOTIFICATION结构： NetEventSetPower 协议驱动程序已执行任何特定于驱动程序的操作，这些操作是准备设备转换为所请求设备电源状态所必需的。 NetEventQueryPower 基础适配器可以转换为请求的设备电源状态。 NetEventQueryRemoveDevice 可以删除基础适配器。 NetEventCancelRemoveDevice 协议驱动程序已执行任何特定于驱动程序的操作，这些操作是准备取消删除基础适配器所必需的。 NetEventReconfigure 协议驱动程序已接受更改的配置。 NetEventBindList 协议驱动程序具有新的绑定列表，并已执行相关处理。 NetEventBindsComplete 协议驱动程序已确认 NDIS 指示协议驱动程序绑定到所有可用的基础适配器。 NetEventPnPCapabilities 协议驱动程序已确认它已收到与指定绑定关联的基础适配器的当前唤醒功能。 NetEventPause 指定的协议绑定已进入暂停状态。 NDIS 完成绑定的所有未完成发送请求后，绑定将进入 “已暂停” 状态。有关暂停操作的详细信息，请参阅暂停绑定。 NetEventRestart 指定的协议绑定已进入 “正在重启” 状态。协议驱动程序准备好恢复绑定的发送和接收操作后，绑定将进入 “正在运行” 状态。 NetEventPortActivation 协议驱动程序已确认激活与指定绑定关联的端口。有关端口激活的详细信息，请参阅激活 NDIS 端口。 NetEventPortDeactivation 协议驱动程序已确认激活与指定绑定关联的端口。
NDIS_STATUS_PENDING	协议驱动程序将通过调用以异步方式返回对所指示事件的响应 NdisCompleteNetPnPEvent 函数。
NDIS_STATUS_RESOURCES	协议驱动程序无法获取必要的系统资源来满足指定的即插即用或电源管理事件。
NDIS_STATUS_NOT_SUPPORTED	NDIS 6.0 及更高版本的协议驱动程序不得返回此状态。 NDIS 5。不支持即插即用的 x 协议驱动程序可以返回此状态以响应 NetEventSetPower，以指示 NDIS 应将其与基础适配器取消绑定。
NDIS_STATUS_FAILURE	协议驱动程序由于上述列表中未说明的原因而使指示的事件失败。

协议驱动程序可能会使 NetEventQueryRemoveDevice 和 NetEventPortActivation 事件失败。

如果协议驱动程序失败 NetEventPortActivation 事件，则不应在后续操作中使用任何关联的端口。

协议驱动程序应始终通过返回 NDIS_STATUS_SUCCESS，使 NetEventRestart、 NetEventIMReEnableDevice、 NetEventCancelRemoveDevice、 NetEventReconfigure、 NetEventBindList、 NetEventBindsComplete、 NetEventPause、 NetEventPortDeactivation 和 NetEventPnPCapabilities 事件成功。

注解

协议驱动程序中需要 ProtocolNetPnPEvent 函数来支持即插即用和电源管理。 NDIS 调用 ProtocolNetPnPEvent 以通知协议驱动程序发生了网络即插即用事件、NDIS PnP 事件或电源管理事件。

The传递给 ProtocolNetPnPEvent 的NET_PNP_EVENT_NOTIFICATION结构描述事件。 ProtocolNetPnPEvent 解释NET_PNP_EVENT_NOTIFICATION结构中的两条基本信息：

NetEvent 成员中的一个代码，用于标识即插即用或电源管理事件的类型。
特定于事件的信息。例如，对于 NetEventSetPower 事件， Buffer 成员包含设备要转换到的设备电源状态。

协议驱动程序应保存 NetPnPEvent 指针。此指针是指向 NdisCompleteNetPnPEvent 函数的必需输入参数，如果 ProtocolNetPnPEvent 返回NDIS_STATUS_PENDING，协议驱动程序随后必须调用该函数。

协议驱动程序应始终成功 NetEventQueryPower 事件。建立活动连接后，协议驱动程序可以调用 PoRegisterSystemState 函数来注册持续繁忙状态。只要状态注册生效，电源管理器就不会尝试使系统进入睡眠状态。连接变为非活动状态后，协议驱动程序通过调用 PoUnregisterSystemState 函数取消状态注册。协议驱动程序绝不应尝试通过失败 NetEventQueryPower 事件来阻止系统转换到睡眠状态。请注意， NetEventQueryPower 事件始终后跟 NetEventSetPower 事件。指定基础设备的当前电源状态的 NetEventSetPower 事件将取消 NetEventQueryPower 事件。

例如，如果协议驱动程序无法释放设备 (，因为设备正在使用) 它必须通过返回NDIS_STATUS_FAILURE使 NetEventQueryRemoveDevice 事件失败。

协议驱动程序应始终通过返回 NDIS_STATUS_SUCCESS，使 NetEventCancelRemoveDevice、 NetEventReconfigure、 NetEventBindList、NetEventBindsComplete、 NetEventPnPCapabilities、 NetEventPause 或 NetEventPortDeactivation 成功。

处理 NetEventReconfigure 或 NetEventBindList 时，协议驱动程序应验证与事件关联的数据。有关此类数据的详细信息，请参阅 NET_PNP_EVENT_NOTIFICATION。

NDIS 在 IRQL = PASSIVE_LEVEL 调用 ProtocolNetPnPEvent 。

示例

若要定义 ProtocolNetPnPEvent 函数，必须首先提供一个函数声明，用于标识要定义的函数类型。 Windows 为驱动程序提供一组函数类型。使用函数类型声明函数可帮助驱动程序的代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是编写 Windows 操作系统驱动程序的要求。

例如，若要定义名为“ MyNetPnPEvent ”的 ProtocolNetPnPEvent 函数，请使用 PROTOCOL_NET_PNP_EVENT 类型，如以下代码示例所示：

PROTOCOL_NET_PNP_EVENT MyNetPnPEvent;

然后，按如下所示实现函数：

_Use_decl_annotations_
NDIS_STATUS
 MyNetPnPEvent(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_PNP_EVENT_NOTIFICATION  NetPnPEvent
    )
  {...}

PROTOCOL_NET_PNP_EVENT函数类型在 Ndis.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations批注可确保使用应用于头文件中PROTOCOL_NET_PNP_EVENT函数类型的注释。有关函数声明要求的详细信息，请参阅使用 NDIS 驱动程序的函数角色类型声明函数。

有关 Use_decl_annotations的信息，请参阅批注函数行为。