Поделиться через

Подключаемый модуль разгрузки хот-точки Wi-Fi

Заметка о отключении wi-Fi хот-хот-спот

Внимание

Начиная с Windows 10 версии 1709, функция разгрузки хот-точки Wi-Fi устарела и не должна использоваться. Вместо этого рекомендуется писать приложение UWP и использовать API проверки подлинности хот-точки Wi-Fi (Windows.Networking.NetworkOperator).

Пример кода и дополнительные сведения см. в примере проверки подлинности с точки доступа Wi-Fi.

Чтобы включить разгрузку Wi-Fi, создайте и установите подключаемый модуль хот-точки. В этом разделе рассматриваются некоторые из проблем, которые следует учитывать при разработке подключаемого модуля хот-точки. Он также содержит общее описание 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 возможности.

Отображаемые строки пользовательского интерфейса

Пользовательские строки отображения пользовательского интерфейса, используемые подключаемым модулем для взаимодействия с пользователем, должны храниться в строковой таблице (в RC-файле). Подключаемый модуль должен передать идентификаторы строк в службу разгрузки хот-точки, чтобы включить ее для загрузки соответствующих строк. В настоящее время поддерживаются следующие строки отображения:

  • Имя поставщика (до 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. Функции HSPluginGetVersion и HSPluginInitPlugin должны быть предоставлены либо путем указания их в ФАЙЛЕ DEF-библиотеки DLL подключаемого модуля, либо путем добавления ключевого слова "__declspec(dllexport)" в реализацию функции.

Инициализация

API подключаемого модуля вызываются в следующем порядке при инициализации:

HsPluginGetVersion

Подключаемый модуль должен возвращать сведения о версии, чтобы убедиться, что версия подключаемого модуля соответствует версии хост-устройства. Текущая версия хранится в константном HS_CONST_HOST_CURRENT_API_VERSION.

HSPluginInitPlugin

Это основная функция инициализации. Он предоставляет следующие сведения для подключаемого модуля:

  • Дескриптор контекста для подключаемого модуля, который будет использоваться всякий раз, когда вызывает любой из узлов подключаемого модуля хот-точки (HS_HOST_*\*)
  • Номер версии, используемый в настоящее время узлом (dwVerNumUsed)
  • Сведения об устройстве (pDeviceIdentity)
  • Возможности ОС, доступные для подключаемого модуля, указанные как тип HS_FLAG_CAPABILITY_NETWORK_** (dwHostCapabilities)
  • Обработчики функций, используемых подключаемым модулем для обратного вызова узла (pHotspotHostHandlers)

Подключаемый модуль возвращает следующие сведения в узел подключаемого модуля хот-точки:

  • Указатель на структуру, содержащую список API подключаемых модулей (pHotspotPluginAPIs). Дополнительные сведения см. в HOTSPOT_PLUGIN_APIS.
  • Указатель на структуру, содержащую профиль подключаемого модуля (pPluginProfile). Дополнительные сведения см. в HS_PLUGIN_PROFILE.

Профиль включает все возможности, необходимые подключаемым модулем. Это представляется одним значением, которое приводит к объединению применимых значений флагов возможностей (HS_FLAG_CAPABILITY_NETWORK_*) с помощью побитовой операции OR. Если подключаемый модуль задает возможность HS_FLAG_CAPABILITY_NETWORK_AUTH_HTTP или возможности HS_FLAG_CAPABILITY_NETWORK_AUTH_EAP_*, член dwSupportedSIMCount структуры HS_PLUGIN_PROFILE должен иметь значение числа поддерживаемых SIM. Подключаемый модуль также должен указать общее количество сетей, поддерживаемых им, задав элемент dwNumNetworksSupported своей структуры HS_PLUGIN_PROFILE .

HsPluginQueryHiddenNetwork [необязательно]

Если подключаемый модуль указывает возможность HS_FLAG_CAPABILITY_NETWORK_TYPE_HIDDEN и устройство может поддерживать скрытую сеть, эта функция вызывается узлом подключаемого модуля для получения скрытых сетевых сведений из подключаемого модуля. Дополнительные сведения см. в HS_PLUGIN_QUERY_HIDDEN_NETWORK.

HsPluginQuerySupportedSIMs [необязательно]

Узел подключаемого модуля хот-точки вызывает эту функцию, если подключаемый модуль задает ненулевое значение для dwSupportedSIMCount. При вызове аргумент pNetworkIdentity должен иметь значение NULL, и подключаемый модуль требуется для предоставления списка всех SIM, поддерживаемых подключаемым модулем. Эта функция также может вызываться позже для идентификации SIM, связанных с каждой сетью хот-точек (в то время как pNetworkIdentity будет не null). Подключаемый модуль должен предоставить список поддерживаемых SIM. Дополнительные сведения см. в HS_PLUGIN_QUERY_SUPPORTED_SIMS.

Время выполнения

По мере того как сети становятся видимыми, узел подключаемого модуля хот-точки запрашивает подключаемый модуль для каждой сети, чтобы определить, является ли она сетью хот-точки.

HSPluginIsHotspotNetwork

Узел подключаемого модуля хот-точки вызывает эту функцию, чтобы определить, является ли указанная сеть сетью хот-точки. Он передает сведения о сети (SSID, тип проверки подлинности, шифр) через структуру HS_NETWORK_IDENTITY . Подключаемый модуль должен возвращать значение перечисления eHS_NETWORK_STATE , указывающее тип сети. Если это сеть хот-точки, то сведения о сети возвращаются через структуру HS_NETWORK_PROFILE . Дополнительные сведения см. в HS_PLUGIN_IS_HOTSPOT_NETWORK.

HsPluginQuerySupportedSIMs [необязательно]

Узел подключаемого модуля хот-точки вызывает эту функцию, если подключаемый модуль указывает возможности HS_FLAG_CAPABILITY_NETWORK_AUTH_HTTP или HS_FLAG_CAPABILITIES_NETWORK_AUTH_EAP в аргументе HS_NETWORK_PROFILE вызова HS_PLUGIN_IS_HOTSPOT_NETWORK. При вызове в этом экземпляре аргумент pNetworkIdentity должен быть не NULL, а подключаемый модуль должен предоставить список SIM, поддерживаемых только для сети, указанной в pNetworkIdentity. Дополнительные сведения см. в HS_PLUGIN_QUERY_SUPPORTED_SIMS.

HSPluginQueryCellularExceptionHosts [необязательно]

Узел подключаемого модуля хот-точки вызывает эту функцию, если поле dwNumCellularExceptions структуры HS_NETWORK_PROFILE, возвращаемой подключаемым модулем, имеет значение, отличное от нуля. Подключаемый модуль должен возвращать список узлов носителя сотовой связи при вызове. Дополнительные сведения см. в HS_PLUGIN_QUERY_CELLULAR_EXCEPTION_HOSTS.

Время подключения

Если сеть считается подключенной, или сеть выбирается пользователем, происходит следующая последовательность вызовов:

HSPluginPreConnectInit

Узел подключаемого модуля хот-точки вызывает эту функцию, чтобы уведомить подключаемый модуль о том, что подключение к сети хот-точки, указанной в структуре HS_NETWORK_IDENTITY , возвращенной подключаемым модулем, выполняется. Дополнительные сведения см. в HS_PLUGIN_PRE_CONNECT_INIT.

HSPluginStartPostConnectAuth

После завершения подключения L2 узел подключаемого модуля хот-спот вызывает эту функцию, чтобы уведомить подключаемый модуль о запуске проверки подлинности. Подключаемый модуль предоставляет pConnectContext, pNetworkIdentity и pNetworkProfile из предыдущего вызова HSPluginPreConnectInit, но он также предоставляет dwConnectionId и pSIMData. Подключаемый модуль должен хранить идентификатор подключения и использовать его при вызове обработчика HSHostPostConnectAuthCompletion узла, чтобы уведомить ОС о результатах проверки подлинности, а также при вызове HSHostSendUserMessage , если сообщение должно быть передано пользователю. В структуре pSIMData содержатся сведения о конфигурации SIM, которую может потребовать подключаемый модуль во время проверки подлинности. Если подключаемый модуль возвращает success, он должен вызывать HSHostPostConnectAuthCompletion в течение 5 минут или подключение отключено.

Отключение и сброс

Если сеть отключена, либо явным образом каким-либо действием пользователя или устройства, либо неявно в результате внешних факторов, вызываются следующие функции:

HSPluginStopPostConnectAuth

Узел подключаемого модуля хот-точки вызывает эту функцию, чтобы завершить проверку подлинности сети, так как устройство будет отключено от сети. Дополнительные сведения см. в HS_PLUGIN_STOP_POST_CONNECT_AUTH.

HSPluginDisconnectFromNetwork

Узел подключаемого модуля хот-точки вызывает эту функцию для информирования подключаемого модуля о том, что устройство будет отключено от сети. Дополнительные сведения см. в HS_PLUGIN_DISCONNECT_FROM_NETWORK.

HSPluginReset

Узел подключаемого модуля хот-точки вызывает эту функцию для сброса подключаемого модуля в исходное (только что загруженное) состояние. Дополнительные сведения см. в HS_PLUGIN_RESET.

Периодические вызовы

Следующие функции периодически вызываются в зависимости от определенных параметров, заданных подключаемым модулем:

HSPluginSendKeepAlive [необязательно]

Узел подключаемого модуля хот-точки вызывает эту функцию с частотой, указанной в элементе dwKeepAliveTimeMins HS_NETWORK_PROFILE структуры, возвращаемой подключаемым модулем. Дополнительные сведения см. в HS_PLUGIN_SEND_KEEP_ALIVE.

HSPluginCheckForUpdates [Необязательно]

Узел подключаемого модуля хот-точки вызывает эту функцию с частотой, указанной в элементе dwProfileUpdateTimeDays структуры HS_PLUGIN_PROFILE.

Выгрузка подключаемого модуля

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.

Имя поставщика должно быть уникальным для поставщика подключаемого модуля или мобильного оператора.

Следующие значения должны сохраняться в разделе реестра:

Имя. Тип Описание
PluginPath [REG_SZ] Имя и полный путь к библиотеке DLL.
PluginRank [REG_DWORD] Любое положительное значение от 1 до 250 включительно (0 зарезервировано для Майкрософт). Более низкое значение представляет более высокий приоритет. Если два подключаемых модуля имеют одинаковый ранг, служба хот-спот произвольно определяет приоритеты друг друга.

Файлы данных, содержащие сведения о подключении, такие как список SSID, зашифрованные учетные данные и т. д. [Необязательно]

Файлы данных должны сохраняться в: Data\SharedData\HotspotHost\Plugins\<ProviderName>