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

  • 项目

注意

一些信息与预发布产品相关，在商业发行之前可能发生实质性修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

重要

本主题中所述的功能在 Windows 预览体验成员预览 的预发行版本中提供。

变更摘要

为了更好地管理哪些应用有权访问位置，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 在某些条件下将开始返回“访问被拒绝”代码。 因此，我们建议测试应用，以确保一旦应用开始在用户计算机上接收到这些“访问被拒绝”返回值，一切都会按预期运行。

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

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

哪些 API 将受到影响？

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

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

  • 如果用户尚未许可应用进行精确位置访问，当应用首次调用受影响的 API 时，如果此进程正在用户上下文内部和 C:\Windows\System32 文件夹外部运行，将为每个应用显示一次系统提示。 根据应用调用这些 API 的方式，提示可能会以不同的方式在应用的用户界面中显示。
  • 如果用户尚未许可精确位置访问，则 wlanapi.h 标头中的以下 Win32 API 将返回 ERROR_ACCESS_DENIED：
  • 如果用户尚未许可精确位置访问，则 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 方法

NetworkInformation 所需的操作

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

WinRT Geolocator.RequestAccessAsync 方法

Geolocation 所需的操作

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

  • 为了使一次性应用系统提示在用户体验中的适当时间点显示，你的应用应调用 Geolocator.RequestAccessAsync。 进程必须正在用户上下文内部和 C:\Windows\System32 文件夹外部运行。 此调用通常应与需要精确位置的用户操作保持一致（与安装后立即提示用户相比，许可率更高）。
  • 为了在用户更改位置许可时收到通知并做出相应响应，你的应用应订阅 Geolocator.StatusChangedevent 事件，并从 StatusChangedEventArgs.Status 属性检索位置权限状态。
  • 应为拒绝被访问的场景添加应用内应用体验。 在这种情况下，应用会将用户重定向到 Windows 的“设置”，以便用户可以允许应用访问其精确位置。 为此，可以将字符串“ms-settings:privacy-location”传递给 Launcher.LaunchUriAsync 方法。

如何测试应用

  1. 使用已在 Windows 预览体验计划中注册的 Windows 电脑。 它应位于 Canary 渠道上，内部版本 25976 或更高版本。
  2. 关闭 Windows 的“设置>“隐私和安全”>“位置”中的定位服务。
  3. 运行使用位置或 Wi-Fi 信息的应用。
  4. 预期的结果是你会看到系统提示，提示你提供位置许可。

如何提供反馈

感谢你的持续支持和反馈。 请通过反馈中心应用提交任何 bug 报告，并在描述中注明你的应用或其他详细信息。 类别为“设备和驱动程序”>“定位服务”。

反馈中心类别