wlanapi.h (wlanregisterNotification 函数)
重要
某些信息与预发行产品相关，在商业发布之前，该产品可能会进行实质性修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
WlanRegisterNotification 函数用于在所有无线接口上注册和取消注册通知。
语法
DWORD WlanRegisterNotification(
[in] HANDLE hClientHandle,
[in] DWORD dwNotifSource,
[in] BOOL bIgnoreDuplicate,
[in, optional] WLAN_NOTIFICATION_CALLBACK funcCallback,
[in, optional] PVOID pCallbackContext,
[in] PVOID pReserved,
[out, optional] PDWORD pdwPrevNotifSource
);
参数
[in] hClientHandle
客户端的会话句柄，由上一次对 WlanOpenHandle 函数的调用获取。
[in] dwNotifSource
要注册的通知源。 这些标志可以组合在一起。 如果此参数设置为 WLAN_NOTIFICATION_SOURCE_NONE， 则 WlanRegisterNotification 会取消注册所有无线接口上的通知。
此参数的可能值在 Wlanapi.h 和 L2cmn.h 头文件中定义。
下表列出了可能的值。
| 值 | 含义 |
|---|---|
|
取消注册通知。 |
|
注册操作系统版本上可用的所有通知，包括 802.1X 模块生成的通知。
对于 SP3 的 Windows XP 和 SP2 的 Windows XP 无线 LAN API，将 dwNotifSource 设置为 WLAN_NOTIFICATION_SOURCE_ALL 在功能上等效于将 dwNotifSource 设置为 WLAN_NOTIFICATION_SOURCE_ACM。 |
|
注册自动配置模块生成的通知。
具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 只有wlan_notification_acm_connection_complete和wlan_notification_acm_disconnected通知可用。 |
|
注册无线托管网络生成的通知。 此通知源在安装了无线 LAN 服务的 Windows 7 和 Windows Server 2008 R2 上可用。 |
|
注册 802.1X 生成的通知。 |
|
注册 MSM 生成的通知。
如果在 dwNotifSource 中设置了WLAN_NOTIFICATION_SOURCE_MSM标志，则需要 wiFiControl 设备功能 (请参阅应用功能声明) 。 如果未授予该功能，则该函数将返回 ERROR_ACCESS_DENIED。 请求 wiFiControl 设备功能需要用户同意访问位置。 有关详细信息，请参阅 更改 api 行为的 Wi-Fi 访问和位置。 具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 不支持此值。 |
|
注册安全模块生成的通知。
当前未为 WLAN_NOTIFICATION_SOURCE_SECURITY定义通知。 具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 不支持此值。 |
|
注册独立硬件供应商 (IHV) 生成的通知。
具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 不支持此值。 |
|
注册设备服务生成的通知。 |
具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 此参数必须设置为 WLAN_NOTIFICATION_SOURCE_NONE、WLAN_NOTIFICATION_SOURCE_ALL 或 WLAN_NOTIFICATION_SOURCE_ACM。
[in] bIgnoreDuplicate
指定是否忽略重复通知。 如果设置为 TRUE，则不会向客户端发送通知（如果通知与上一个通知相同）。
具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 此参数将被忽略。
[in, optional] funcCallback
定义通知回调函数类型的 WLAN_NOTIFICATION_CALLBACK 类型。
如果 dwNotifSource 参数设置为 WLAN_NOTIFICATION_SOURCE_NONE以在所有无线接口上取消注册通知，则此参数可以为 NULL。
[in, optional] pCallbackContext
指向客户端上下文的指针，该指针将传递给带有通知的回调函数。
[in] pReserved
保留供将来使用。 必须设置为 NULL。
[out, optional] pdwPrevNotifSource
指向以前注册的通知源的指针。
返回值
如果函数成功，则返回值为 ERROR_SUCCESS。
如果函数失败，则返回值可能是以下返回代码之一。
如果在 dwNotifSource 中设置了WLAN_NOTIFICATION_SOURCE_MSM标志，则需要 wiFiControl 设备功能 (请参阅应用功能声明) 。 如果未授予该功能，则该函数将返回 ERROR_ACCESS_DENIED。 请求 wiFiControl 设备功能需要用户同意访问位置。 有关详细信息，请参阅 更改 api 行为的 Wi-Fi 访问和位置。
| 返回代码 | 说明 |
|---|---|
|
参数不正确。 如果 hClientHandle 为 NULL 或无效，或者 pReserved 不为 NULL，则返回此错误。 |
|
在句柄表中找不到句柄 hClientHandle 。 |
|
未能为查询结果分配内存。 |
|
如果在 dwNotifSource 中设置了WLAN_NOTIFICATION_SOURCE_MSM标志，则需要 wiFiControl 设备功能， (请参阅应用功能声明。 如果未授予该功能，则该函数将返回 ERROR_ACCESS_DENIED。 请求 wiFiControl 设备功能需要用户同意访问位置。 有关详细信息，请参阅 更改 api 行为的 Wi-Fi 访问和位置。 |
|
各种错误代码。 |
注解
应用程序使用 WlanRegisterNotification 在所有无线接口上注册和取消注册通知。 注册通知时，应用程序必须提供 funcCallback 参数指向的回调函数。 此回调函数的原型是 WLAN_NOTIFICATION_CALLBACK。 此回调函数将接收已在传递给 WlanRegisterNotification 函数的 dwNotifSource 参数中注册的通知。 回调函数使用指向 WLAN_NOTIFICATION_DATA 结构的指针调用，作为包含通知详细信息的第一个参数。 回调函数还接收第二个参数，该参数包含指向客户端上下文的指针，该指针在 pCallbackContext 参数中传递给 WlanRegisterNotification 函数。
如果 dwNotifSource 不是 WLAN_NOTIFICATION_SOURCE_NONE 并且客户端无法提供回调函数，则 WlanRegisterNotification 函数将返回错误。
注册后，每当通知可用时，都会调用回调函数，直到客户端注销或关闭句柄。
如果调用应用程序通过使用 hClientHandle 参数) 调用 WlanCloseHandle 关闭其调用句柄 (或进程结束，则会自动撤消由此函数引起的任何接收通知的注册。
不要从回调函数调用 WlanRegisterNotification 。 如果在调用 wlanRegisterNotification 时客户端处于通知回调的中间，且 dwNotifSource 设置为 WLAN_NOTIFICATION_SOURCE_NONE (即，当客户端从通知) 注销时， WlanRegisterNotification 将等待回调完成，然后返回值。 在回调函数中调用此函数将导致调用永远不会完成。 如果回调函数和从通知中注销的线程都尝试获取同一锁，则可能会出现死锁。 此外，不要从应用程序 DLL 中的 DllMain 函数调用 WlanRegisterNotification。 这也可能导致死锁。
应用程序可以超时并查询当前接口状态，而不是等待通知。
具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 通知由 Netman 服务处理。 如果 Netman 服务已禁用或不可用，则不会收到通知。 如果在合理的时间段内未收到通知，应用程序应超时并查询当前接口状态。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows Vista、Windows XP 和 SP3 [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | wlanapi.h (包括 Wlanapi.h) |
| Library | Wlanapi.lib |
| DLL | Wlanapi.dll |
| 可再发行组件 | 适用于 Windows XP 的无线 LAN API SP2 |