通过

Wi-Fi 热点卸载插件

Wi-Fi 热点卸载弃用说明

重要

从 Windows 10 版本 1709 开始，Wi-Fi 热点卸载功能已弃用，不应使用。 相反，我们建议编写 UWP 应用并使用 Wi-Fi 热点身份验证 API（Windows.Networking.NetworkOperators）。

有关代码示例和详细信息，请参阅 Wi-Fi 热点身份验证示例。

若要启用 Wi-Fi 卸载，请创建并安装热点插件。 本主题讨论开发热点插件时要考虑的一些问题。 它还提供插件 API 的一般说明，这些 API 作为插件包的一部分实现。

规划插件

在开始插件开发之前，请确保解决以下问题：

支持的身份验证方法

确定插件将支持的网络所需的身份验证方法。 热点卸载框架支持三类网络：

  • 使用 WISPr 1.0 或某些变体通过 HTTP 对用户和/或设备进行身份验证的网络。 这些网络由以下功能表示：

    • HS_FLAG_CAPABILITY_NETWORK_AUTH_HTTP

  • 使用 EAP-SIM/AKA/AKA' 对设备进行身份验证的网络。 这些网络由以下功能表示：

    • HS_FLAG_CAPABILITY_NETWORK_AUTH_EAP_SIM
    • HS_FLAG_CAPABILITY_NETWORK_AUTH_EAP_AKA
    • HS_FLAG_CAPABILITY_NETWORK_AUTH_EAP_AKA_PRIME

    对于基于 EAP 的网络，插件还可以使用 HS_FLAG_CAPABILITY_NETWORK_CUSTOM_REALM 功能指定自定义领域。

  • 不需要任何身份验证的网络或插件具有不要求任何设备凭据的独立身份验证机制的网络。 这些网络由以下功能表示：

    • HS_FLAG_CAPABILITY_NETWORK_AUTH_NO_SIM

隐藏网络

必须在初始化时预先指定隐藏网络，因为网络在扫描结果中不可见。 由于隐藏网络的电源和隐私影响，框架在全球最多支持一个隐藏网络。 因此，如果另一个插件还请求连接到隐藏的网络，则第二个插件的请求将被拒绝。 如果插件需要配置隐藏网络，则必须为该网络指定 HS_FLAG_CAPABILITY_NETWORK_TYPE_HIDDEN 功能。

对于所有其他网络，插件应指定 HS_FLAG_CAPABILITY_NETWORK_TYPE_VISIBLE 功能。

用户界面显示字符串

插件用来与用户通信的自定义 UI 显示字符串必须存储在字符串表中（在 .rc 文件中）。 该插件必须将字符串 ID 传递到热点卸载服务，使它能够加载相应的字符串。 目前，支持以下显示字符串：

  • 提供程序名称（最多 HS_CONST_MAX_PROVIDER_NAME_LENGTH 长度）
  • 网络名称（最多 HS_CONST_MAX_NETWORK_DISPLAY_NAME_LENGTH 长度）
  • “高级”页面上的消息（最多 HS_CONST_MAX_ADVANCED_PAGE_STRING_LENGTH 长度）
  • 使用 HSHostSendUserMessage 函数传递给用户的任何其他字符串（最多 MAX_PATH 长度）。 有关详细信息，请参阅 HS_HOST_SEND_USER_MESSAGE。

注意： 有关 Wi-Fi 热点卸载功能和常量的详细信息，请参阅 Wi-Fi 热点卸载常量。

实现插件

插件以 DLL 的形式实现。 必须在插件 DLL 的 .def 文件中指定函数 HSPluginGetVersion 和 HSPluginInitPlugin ，或者在函数实现中向其添加“__declspec（dllexport）”关键字来公开这些函数。

初始化

在初始化时按以下顺序调用插件 API：

HsPluginGetVersion

插件应返回其版本信息，以验证插件版本是否与主机设备版本匹配。 当前版本存储在常量 HS_CONST_HOST_CURRENT_API_VERSION中。

HSPluginInitPlugin

这是主要的初始化函数。 它向插件提供以下信息：

  • 每当插件调用任何热点插件主机（HS_HOST_*\*）函数时要使用的上下文句柄
  • 主机当前使用的版本号（dwVerNumUsed）
  • 有关设备的信息（pDeviceIdentity）
  • 插件可用的 OS 功能，指定为HS_FLAG_CAPABILITY_NETWORK_** 类型（dwHostCapabilities）
  • 插件用于回调主机的函数的处理程序（pHotspotHostHandlers）

该插件将以下信息返回到热点插件主机：

  • 指向包含插件 API 列表（pHotspotPluginAPIs）的结构的指针。 有关详细信息，请参阅 HOTSPOT_PLUGIN_APIS。
  • 指向包含插件配置文件（pPluginProfile）的结构的指针。 有关详细信息，请参阅 HS_PLUGIN_PROFILE。

配置文件包括插件所需的所有功能。 这由单个值表示，该值通过使用按位 OR 操作合并适用的功能标志值（HS_FLAG_CAPABILITY_NETWORK_*）。 如果插件指定HS_FLAG_CAPABILITY_NETWORK_AUTH_HTTP功能或 HS_FLAG_CAPABILITY_NETWORK_AUTH_EAP_* 功能，则必须将HS_PLUGIN_PROFILE结构的 dwSupportedSIMCount 成员设置为受支持的 SIM 数。 该插件还必须通过设置其HS_PLUGIN_PROFILE结构的 dwNumNetworksSupported 成员来指定它支持的网络总数。

HsPluginQueryHiddenNetwork [可选]

如果插件指定 了HS_FLAG_CAPABILITY_NETWORK_TYPE_HIDDEN 功能，并且设备可以支持隐藏网络，则热点插件主机会调用此函数，以便从插件获取隐藏的网络信息。 有关详细信息，请参阅 HS_PLUGIN_QUERY_HIDDEN_NETWORK。

HsPluginQuerySupportedSIM [可选]

如果插件为 dwSupportedSIMCount 指定非零值，则热点插件主机将调用此函数。 调用时， pNetworkIdentity 参数应为 NULL，并且插件需要提供插件支持的所有 SIM 的列表。 稍后还可以调用此函数来标识与每个热点网络关联的 SIM（此时 ，pNetworkIdentity 将为非 NULL）。 该插件必须提供受支持的 SIM 列表。 有关详细信息，请参阅 HS_PLUGIN_QUERY_SUPPORTED_SIMS。

运行时间

当网络变得可见时，热点插件主机会查询每个网络的插件，以确定它是否是热点网络。

HSPluginIsHotspotNetwork

热点插件主机调用此函数以确定指定的网络是否为热点网络。 它通过 HS_NETWORK_IDENTITY 结构传递有关网络（SSID、身份验证类型、密码）的信息。 插件必须返回指示 网络类型的eHS_NETWORK_STATE 枚举值。 如果它是热点网络，则通过 HS_NETWORK_PROFILE 结构返回有关网络的信息。 有关详细信息，请参阅 HS_PLUGIN_IS_HOTSPOT_NETWORK。

HsPluginQuerySupportedSIM [可选]

如果插件指定调用HS_PLUGIN_IS_HOTSPOT_NETWORK的HS_NETWORK_PROFILE参数中的功能HS_FLAG_CAPABILITY_NETWORK_AUTH_HTTP或HS_FLAG_CAPABILITIES_NETWORK_AUTH_EAP，则热点插件主机将调用此函数。 在此实例中调用时，pNetworkIdentity 参数应为非 NULL，插件必须仅提供 pNetworkIdentity 中指定的网络支持的 SIM 列表。 有关详细信息，请参阅 HS_PLUGIN_QUERY_SUPPORTED_SIMS。

HSPluginQueryCellularExceptionHosts [可选]

如果插件返回的 HS_NETWORK_PROFILE 结构的 dwNumCellularExceptions 字段设置为非零值，则热点插件主机将调用此函数。 调用时，该插件必须返回手机网络持有者主机的列表。 有关详细信息，请参阅 HS_PLUGIN_QUERY_CELLULAR_EXCEPTION_HOSTS。

连接时间

当网络被视为可连接或用户选择网络时，将进行以下调用序列：

HSPluginPreConnectInit

热点插件主机调用此函数以通知插件，该插件与插件返回的HS_NETWORK_IDENTITY结构中指定的热点网络的连接正在进行中。 有关详细信息，请参阅 HS_PLUGIN_PRE_CONNECT_INIT。

HSPluginStartPostConnectAuth

L2 连接完成后，热点插件主机将调用此函数以通知插件开始身份验证。 该插件提供之前对 HSPluginPreConnectInit 的调用中的 pConnectContext、pNetworkIdentity 和 pNetworkProfile，但它也提供 dwConnectionId 和 pSIMData。 插件必须存储连接 ID，并在调用主机的 HSHostPostConnectAuthCompletion 处理程序以通知 OS 身份验证结果时使用它，并在需要将消息传达给用户的情况下，在调用 HSHostSendUserMessage 时使用该 ID。 pSIMData 结构包含有关插件在身份验证期间可能需要的 SIM 配置的更多信息。 如果插件返回 Success，则必须在 5 分钟内调用 HSHostPostConnectAuthCompletion 或连接断开连接。

断开连接和重置

当网络断开连接时，由某些用户或设备操作显式或隐式作为外部因素的结果，将调用以下函数：

HSPluginStopPostConnectAuth

热点插件主机调用此函数以终止网络身份验证，因为设备即将与网络断开连接。 有关详细信息，请参阅 HS_PLUGIN_STOP_POST_CONNECT_AUTH。

HSPluginDisconnectFromNetwork

热点插件主机调用此函数，以通知插件设备将从网络断开连接。 有关详细信息，请参阅 HS_PLUGIN_DISCONNECT_FROM_NETWORK。

HSPluginReset

热点插件主机调用此函数，将插件重置为其初始（刚刚加载）状态。 有关详细信息，请参阅 HS_PLUGIN_RESET。

定期调用

根据插件设置的特定参数，定期调用以下函数：

HSPluginSendKeepAlive [可选]

热点插件主机以插件返回的 HS_NETWORK_PROFILE 结构的 dwKeepAliveTimeMins 成员中指定的频率调用此函数。 有关详细信息，请参阅 HS_PLUGIN_SEND_KEEP_ALIVE。

HSPluginCheckForUpdates [可选]

热点插件主机以 HS_PLUGIN_PROFILE 结构的 dwProfileUpdateTimeDays 成员中指定的频率调用此函数。

卸载插件

HSPluginDeinit

热点插件主机调用此函数，使插件能够刷新任何未保存的信息，并在卸载前关闭任何打开的句柄。 将在 UnloadReason 参数中提供卸载的原因。 有关详细信息，请参阅 HS_PLUGIN_DEINIT。

插件安装包

THe 插件安装包应包括以下内容：

插件 DLL 文件

DLL 文件必须签名并放置在 Programs\HotspotHost\<ProviderName 下，其中 <ProviderName>> 是 DLL 提供程序的名称。

有关对 DLL 进行签名的信息，请参阅 对二进制文件和包进行签名。

命名 DLL 文件没有特定的约定，因此请确保注册表中文件的路径正确无误。 例如，可以在包中指定注册表信息，如下所示：

<RegKeys>
        <RegKey KeyName="$(hklm.software)\Microsoft\Windows Phone\HotspotOffload\Plugins\<ProviderName>">
          <RegValue Name="PluginRank" Type="REG_DWORD" Value="00000005" />
          <RegValue Name="PluginPath" Type="REG_SZ" Value="%SystemDrive%\Programs\HotspotHost\Orange\<ProviderName>\<HotspotPlugin.dll>" />
        </RegKey>
      </RegKeys>

注册表配置

所需的注册表设置保存在创建的新条目中： HKEY_LOCAL_MACHINE\Software\Microsoft\Windows Phone\HotspotOffload\Plugins\ ProviderName。

ProviderName 必须对插件提供程序或移动运营商是唯一的。

必须在注册表项下保存以下值：

名称 Type 描述
PluginPath [REG_SZ] DLL 的名称和完整路径。
PluginRank [REG_DWORD] 任何介于 1 和 250 之间的正值（0 保留为Microsoft）。 值越小，表示优先级越高。 如果两个插件具有相同的排名，则热点服务会任意将一个插件优先于另一个插件。

包含特定于连接的信息的数据文件，例如 SSID 列表、加密凭据等。[可选]

数据文件应保存在： Data\SharedData\HotspotHost\Plugins\<ProviderName>下。