Wi-Fi 访问和位置的 API 行为变更

项目
10/07/2024

变更摘要

为了更好地管理哪些应用有权访问位置，Windows 计划增加新的隐私控件。

目前，应用可以查看运行此应用的设备附近的 Wi-Fi 网络，并使用这些网络来确定设备的精确位置。但今后，对提供必要基本服务集标识符 (BSSID) 的 API 的访问将仅限于用户配置为允许访问用户精确位置的应用。使用定位服务的许可是在 Windows 的“设置”>“隐私和安全”>“位置”中配置的。它可以在设备级别、用户级别或单个应用级别进行设置。实现此变更后，如果用户未获得所需的许可，则系统将在首次阻止应用时触发一次性提示。

下面是系统提示的示例：

系统提示的一个示例

如果你的应用调用 wlanapi.h 或 Windows.Devices.WiFi 命名空间、NetworkInformation 或 Geolocator 中的 Wi-Fi API，则本主题适合你。本主题详细介绍了如何优化应用的行为以改善用户体验。

变更何时实施？

这些变更最初 Windows Insider Preview 版本中进行，然后在 Windows 功能版（商业版）中进行。

在 Windows Insider Preview 版本中，上述变更将于 2023 年 10 月生效。
在 2024 年秋季发布以下 Windows 功能版之前，你可以测试你的应用场景并进行任何必要的变更。在此日期之后，Windows 设备将开始获取包含上述行为变更的更新。

如前所述，在功能正式发布之前，本文档中的细节也可能会发生更改。

如何为变更做好准备？

此变更会影响多个 API 表面。而且，正如我们稍后所述，某些 API 在某些条件下将开始返回“访问被拒绝”代码。因此，我们建议测试应用，以确保一旦应用开始在用户计算机上接收到这些“访问被拒绝”返回值，一切都会按预期运行。

简而言之，我们鼓励你作为应用开发人员对应用的代码进行以下更改。这些更改将帮助用户（如有必要）授予应用对用户精确位置的访问权限，并改进用户体验：

除非绝对必要，否则请勿在应用中进行 Wi-Fi 扫描调用。
如果出于位置目的使用 Wi-Fi 扫描，请将此扫描替换为位置 API 调用。
控制系统提示何时出现，以便提示与应用内场景一起显示。
在应用中内置提示，告知用户他们需要调整 Windows 的“设置”才能授予访问权限。

哪些 API 将受到影响？

如果应用调用以下任一 API，应用将受到影响：

涉及 BSSID 的 wlanapi.h 标头中的 Win32 API。
Windows.Devices.WiFi 命名空间中的 Windows 运行时 (WinRT) API。
WinRT 方法 Windows.Networking.Connectivity.NetworkInformation.GetLanIdentifiers。
WinRT 方法 Windows.Devices.Geolocation.Geolocator.RequestAccessAsync。
此外，请求 wifiControl 设备功能需要用户许可访问位置。请参阅应用功能声明。

Win32 的 wlanapi.h 或 WinRT 的 Windows.Devices.WiFi 中的 Wi-Fi API

如果用户尚未许可应用进行精确位置访问，当应用首次调用受影响的 API 时，如果此进程正在用户上下文内部和 C:\Windows\System32 文件夹外部运行，将为每个应用显示一次系统提示。根据应用调用这些 API 的方式，提示可能会以不同的方式在应用的用户界面中显示。
如果用户尚未许可精确位置访问，则 wlanapi.h 标头中的以下 Win32 API 将返回 ERROR_ACCESS_DENIED：
- WlanGetAvailableNetworkList
- WlanGetNetworkBssList
- WlanQueryInterface（如果 OpCode 的参数是 wlan_intf_opcode_current_connection ）
- WlanScan
如果用户尚未许可精确位置访问，则 Windows.Devices.WiFi.WiFiAdapter.RequestAccessAsync API 将返回 DeniedBySystem。 Windows.Devices.WiFi 命名空间中的其他 API 将引发“访问被拒绝”异常。
对这些 API 的调用将显示在正在使用的系统托盘和位置最近的活动中。

WlanRegisterNotification 也会受影响，具体取决于传递给它的参数。如果在 dwNotifSource 中设置了 WLAN_NOTIFICATION_SOURCE_MSM 标志，则 wiFiControl 设备功能是必需的（请参阅应用功能声明）。如果未授予该功能，则该函数将返回 ERROR_ACCESS_DENIED。请求 wifiControl 设备功能需要用户同意有关对位置的访问。

Wi-Fi API 所需的操作

若要为应用的用户创建更好的体验并确保操作顺利，应对应用的行为进行以下变更，以便控制何时显示系统提示：

如果应用需要了解主机设备的位置，则应调用 Geolocation API，而不是使用 Wi-Fi 扫描。
为了使一次性应用系统提示在用户体验中的适当时间点显示，你的应用应调用 WiFiAdapter.RequestAccessAsync。进程必须正在用户上下文内部和 C:\Windows\System32 文件夹外部运行。此调用应与需要 Wi-Fi 或位置的用户操作保持一致（与安装后立即提示用户相比，许可率更高）。
你的应用可以通过使用 AppCapability.CheckAccess API 和 wiFiControl 设备功能来查询其位置访问状态。如果以下访问将触发对话框，则 API 将返回 AppCapabilityAccessStatus.UserPromptRequired。
为了在用户更改位置许可时收到通知并做出相应响应，你的应用应订阅 AppCapability.AccessChanged 事件。
应为拒绝被访问的场景添加应用内应用体验。在这种情况下，应用会将用户重定向到 Windows 的“设置”，以便用户可以允许应用访问其精确位置。为此，可以将字符串“ms-settings:privacy-location”传递给 Launcher.LaunchUriAsync 方法。
你的应用应将请求限制在合理的水平，以便使用中的位置图标不会频繁出现在系统托盘中。

WinRT NetworkInformation.GetLanIdentifiers 方法

如果用户尚未许可精确位置访问，则 Windows.Networking.Connectivity.NetworkInformation.GetLanIdentifiers API 不会返回 WLAN 相关信息。
对这些 API 的调用将显示在正在使用的系统托盘和位置最近的活动中。

NetworkInformation 所需的操作

与上述 Wi-Fi API 相同，应用应请求/查询访问权限、监视变更，并将用户引导至“设置”。

WinRT Geolocator.RequestAccessAsync 方法

如果用户尚未许可精确位置访问，则首次调用 Windows.Devices.Geolocation.Geolocator.RequestAccessAsync 时，将显示一次性应用系统提示。

Geolocation 所需的操作