PROTOCOL_NET_PNP_EVENT回调函数 (ndis.h)

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 事件适用于所有绑定。 NetEventBindListNetEventBindsComplete 始终使用 NULLProtocolBindingContext 进行指示。 可以使用指定的 ProtocolBindingContextNULLProtocolBindingContext 来指示 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
The protocol driver will return its response to the indicated event asynchronously with a call to the NdisCompleteNetPnPEvent 函数。
NDIS_STATUS_RESOURCES
协议驱动程序无法获取必要的系统资源来满足所指示的即插即用或电源管理事件。
NDIS_STATUS_NOT_SUPPORTED
NDIS 6.0 及更高版本的协议驱动程序不得返回此状态。 NDIS 5。不支持即插即用的 x 协议驱动程序可以返回此状态,以响应 NetEventSetPower,以指示 NDIS 应将其从基础适配器取消绑定。
NDIS_STATUS_FAILURE
协议驱动程序由于上述列表中所述的原因而失败了指示的事件。
 

协议驱动程序可能会使 NetEventQueryRemoveDeviceNetEventPortActivation 事件失败。

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

协议驱动程序应始终成功 NetEventRestartNetEventIMReEnableDeviceNetEventCancelRemoveDeviceNetEventReconfigureNetEventBindListNetEventBindList、NetEventBindsCompleteNetEventPause、NetEventPortDeactivationNetEventPnPCapabilities 事件,方法是返回NDIS_STATUS_SUCCESS。

备注

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

必须向传递给 ProtocolNetPnPEvent 的NET_PNP_EVENT_NOTIFICATION结构描述事件。 ProtocolNetPnPEvent 解释NET_PNP_EVENT_NOTIFICATION结构中的两个基本信息:

  • NetEvent 成员中的代码,用于标识即插即用或 Power Management 事件的类型。
  • 特定于事件的信息。 例如,使用 NetEventSetPower 事件时, Buffer 成员包含设备正在转换的设备电源状态。
协议驱动程序应保存 NetPnPEvent 指针。 此指针是 NdisCompleteNetPnPEvent 函数的必需输入参数,如果 ProtocolNetPnPEvent 返回NDIS_STATUS_PENDING,协议驱动程序随后必须调用该函数。

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

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

协议驱动程序应始终通过返回NDIS_STATUS_SUCCESS来成功 NetEventCancelRemoveDeviceNetEventReconfigureNetEventBindList、NetEventBindsCompleteNetEventPnPCapabilitiesNetEventPauseNetEventPortDeactivation

处理 NetEventReconfigureNetEventBindList 时,协议驱动程序应验证与事件关联的数据。 有关此类数据的详细信息,请参阅 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的信息,请参阅 批注函数行为

要求

   
最低受支持的客户端 在 NDIS 6.0 及更高版本中受支持。
目标平台 Windows
标头 ndis.h (包括 Ndis.h)
IRQL PASSIVE_LEVEL

另请参阅

NET_PNP_EVENT_NOTIFICATION

NdisCompleteNetPnPEvent

NdisOpenAdapterEx

PoRegisterSystemState

PoUnregisterSystemState