Функция WlanSetPsdIEDataList (wlanapi.h)
Функция WlanSetPsdIeDataList задает список данных элемента сведений (IE) службы обнаружения близкого взаимодействия (PSD).
Синтаксис
DWORD WlanSetPsdIEDataList(
[in] HANDLE hClientHandle,
[in] LPCWSTR strFormat,
[in] const PWLAN_RAW_DATA_LIST pPsdIEDataList,
PVOID pReserved
);
Параметры
[in] hClientHandle
Дескриптор сеанса клиента, полученный при предыдущем вызове функции WlanOpenHandle .
[in] strFormat
Формат PSD IE в списке данных PSD IE, переданном в параметре pPsdIEDataList . Это строка URI, завершающаяся null, которая указывает пространство имен протокола, используемого для обнаружения.
[in] pPsdIEDataList
Указатель на структуру WLAN_RAW_DATA_LIST , содержащую список данных PSD IE, который необходимо задать.
pReserved
Зарезервировано для последующего использования. Для параметра должно быть задано значение NULL.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.
Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов возврата.
| Код возврата | Описание |
|---|---|
|
Неправильный параметр. Эта ошибка возвращается, если hClientHandle имеет значение NULL или недопустимо или pReserved не равно NULL. |
|
Дескриптор hClientHandle не найден в таблице дескрипторов. |
|
Эта функция была вызвана из неподдерживаемой платформы. Это значение возвращается, если функция была вызвана из клиента Windows XP с пакетом обновления 3 (SP3) или API беспроводной локальной сети для Windows XP с пакетом обновления 2 (SP2). |
|
Различные коды ошибок. |
Комментарии
Протокол обнаружения служб близкого взаимодействия — это проприетарный протокол Майкрософт, который позволяет клиенту обнаруживать службы в физической близости, которая определяется диапазоном радиосвязи. Протокол обнаружения служб близкого взаимодействия предназначен для передачи сведений об обнаружении служб, таких как объявления служб, в составе кадров маяка. Точки доступа (AP) и станции (STA), которые работают в нерегламентированном режиме, периодически транслируют кадры маяков. Рамка маяка может содержать один или несколько собственных информационных элементов, которые содержат сведения об обнаружении, относящиеся к службам, которые предлагает устройство.
PsD IE используется для передачи сжатой информации, предоставляемой протоколами обнаружения более высокого уровня, в целях пассивного обнаружения. Одним из таких протоколов более высокого уровня, используемых для обнаружения, является протокол WS-Discovery. Для обнаружения можно использовать любой протокол.
Windows Vista и Windows Server 2008 с установленной службой беспроводной локальной сети поддерживают пассивное обнаружение для нерегламентированных клиентов, нерегламентированных служб и клиентов инфраструктуры. Это означает, что нерегламентированная служба может объявить доступный ресурс или службу путем передачи PSD IE по одному или нескольким маякам. Нет никакой гарантии, что этот маяк будет получен нерегламентированным клиентом или клиентом инфраструктуры.
Windows 7 и Windows Server 2008 R2 с установленной службой беспроводной локальной сети поддерживают пассивное обнаружение для нерегламентированных клиентов, нерегламентированных служб и клиентов инфраструктуры так же, как и в Windows Vista. Кроме того, PSD IE также поддерживается для беспроводной размещенной сети, программной точки беспроводного доступа (AP). Приложения на локальном компьютере, на котором должна выполняться беспроводная размещенная сеть, могут использовать функцию WlanSetPsdIeDataList для настройки PSD IE перед запуском беспроводной размещенной сети. После установки psd IE будет включен в ответ маяка и пробы после запуска беспроводной размещенной сети.
Каждое приложение, отправляющее или получающее маяки, ведет собственный список данных PSD IE. Параметр pPsdIEDataList указывает на список ИДЕНТИФИКАТОРов PSD, созданных приложением. Каждый PSD IE имеет следующий формат.
| Поле | Описание и значение |
|---|---|
| Идентификатор элемента (1 байт) | 221 |
| Длина (1 байт) | Длина поля данных в байтах плюс 8. |
| OUI (3 байта) | Уникальный идентификатор организации (OUI) должен содержать значение 00-50-F2. Этот общедоступный OUI зарегистрирован в корпорации Майкрософт. |
| Тип OUI (1 байт) | Для протокола обнаружения служб близкого взаимодействия тип OUI должен содержать значение 6. |
| Хэш идентификатора формата (4 байта) | Биты 31–0 HMAC, вычисленного из параметра strFormat . |
| Данные (переменная) | Содержит определяемые пользователем данные для обнаружения. Длина этого поля не должна превышать 240 байт. |
В поле "Хэш идентификатора формата" описывается формат сведений, переносимых в PSD IE. Чтобы обеспечить уникальность и обойти необходимость централизованного администрирования идентификаторов формата, для различения формата используется строка в виде универсального кода ресурса (URI), как указано в RFC 3986. Однако поскольку передача должна быть эффективной и пространство в информационном элементе ограничено, строка фактически не передается, а передается ее хэш. На клиенте, который является принимающей стороной маяка, хэш сопоставляется с известным набором идентификаторов формата.
Поле хэша идентификатора формата представлено битами 0... 31 кода проверки подлинности сообщения на основе хэша (HMAC) в строке идентификатора формата, указанной в параметре strFormat . HMAC используется для указания формата поля Данные PSD IE. Формула, используемая для вычисления HMAC, описана в RFC 2104. Пример кода для вычисления HMAC соответствует спецификации RFC 4634. При вычислении HMAC используйте SHA-256 для хэш-функции. Используемый ключ — это ключ NULL (указатель NULL на ключ проверки подлинности и ключ проверки подлинности нулевой длины в исходном коде в RFC 4634). Используйте значение параметра strFormat (включая любые пробелы, но за исключением символа завершения NULL) в качестве входного текста, закодированного в кодировке Юникод UTF-16 в формате байтов.
Например, если параметр strFormat имеет значение http://schemas.xmlsoaps.org/ws/2004/10/discovery, то первые четыре октета соответствующего HMAC — .0xF8 0xCB 0x35 0x15
Если параметр strFormat имеет значение http://schemas.microsoft.com/networking/discoveryformat/v2, то четыре октета соответствующего HMAC имеют значение 0xCF 0xF1 0x64 0x17.
При отправке первых 4 октетов HMAC по сети сначала отправьте первый (самый левый) октет.
Обратите внимание, что в усеченных HMACs могут возникнуть конфликты, а это означает, что невозможно однозначно определить протокол обнаружения, соответствующий полезным данным PSD IE, из заданных битов HMAC. Приложение, получающее PSD IE, должно лучше всего угадать протокол обнаружения, используемый из заданного HMAC, а затем повторно запустить протокол обнаружения более высокого уровня после установки подключения.
В списке можно передать не более пяти ПСД. Кроме того, общая длина (в байтах) списка PSD IE может быть ограничена аппаратными ограничениями на длину маяка.
Приложение может вызывать WlanSetPsdIeDataList много раз. Если WlanSetPsdIeDataList вызывается дважды с помощью одного и того же strFormat, содержимое WLAN_RAW_DATA_LIST , заполненного первым вызовом функции, перезаписывается полезными данными WLAN_RAW_DATA_LIST второго вызова. При вызове WlanSetPsdIeDataList с параметром pPsdIEDataList , имеющим значение NULL, удаляется список PSD IE, связанный с strFormat . При вызове WlanSetPsdIeDataList с параметрами pPsdIEDataList и strFormat , имеющими значение NULL, все списки PSD IE, заданные приложением, очищаются.
Служба беспроводной связи обрабатывает списки данных PSD IE, заданные различными приложениями, и создает необработанные большие двоичные объекты данных IE. Когда компьютер создает или присоединяет нерегламентированную сеть на любом беспроводном адаптере, он отправляет маяки, включающие большой двоичный объект данных PSD IE, связанный с сетью, на другие компьютеры.
Станции могут вызывать функцию WlanExtractPsdIEDataList , чтобы получить список данных PSD IE после получения маяка с компьютера.
Требования
| Минимальная версия клиента | Windows Vista [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | wlanapi.h (включая Wlanapi.h) |
| Библиотека | Wlanapi.lib |
| DLL | Wlanapi.dll |