wlanSetPsdIEDataList 函数 (wlanapi.h)

  • 项目

WlanSetPsdIeDataList 函数 (PSD) 信息元素 (IE) 数据列表设置邻近服务发现。

语法

DWORD WlanSetPsdIEDataList(
  [in] HANDLE                    hClientHandle,
  [in] LPCWSTR                   strFormat,
  [in] const PWLAN_RAW_DATA_LIST pPsdIEDataList,
       PVOID                     pReserved
);

参数

[in] hClientHandle

客户端的会话句柄，由上一次对 WlanOpenHandle 函数的调用获取。

[in] strFormat

在 pPsdIEDataList 参数中传递的 PSD IE 数据列表中 PSD IE 的格式。 这是一个以 NULL 结尾的 URI 字符串，用于指定用于发现的协议的命名空间。

[in] pPsdIEDataList

指向包含要设置的 PSD IE 数据列表 的WLAN_RAW_DATA_LIST 结构的指针。

pReserved

保留供将来使用。 必须设置为 NULL。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。

如果函数失败，则返回值可能是以下返回代码之一。

返回代码 说明
ERROR_INVALID_PARAMETER
 参数不正确。 如果 hClientHandle 为 NULL 或无效或 pReserved 不为 NULL，则返回此错误。
ERROR_INVALID_HANDLE
 在句柄表中找不到句柄 hClientHandle 。
ERROR_NOT_SUPPORTED
 此函数是从不受支持的平台调用的。 如果函数是从具有 SP3 的 Windows XP 或具有 SP2 客户端的 Windows XP 无线 LAN API 调用的，则返回此值。
RPC_STATUS
 各种错误代码。

注解

邻近感应服务发现协议是一种 Microsoft 专有协议，它允许客户端发现其物理邻近度（由无线电范围定义）的服务。 邻近感应服务发现协议的目的是将服务发现信息（如服务广告）作为信标帧的一部分进行传递。 接入点 (AP) 和工作站 (STA) 定期广播信标帧。 信标帧可以包含一个或多个专有信息元素，这些元素携带与设备提供的服务相关的发现信息。

PSD IE 用于传输由更高级别发现协议提供的压缩信息，以便进行被动发现。 用于发现的此类更高级别协议之一是 WS-Discovery 协议。 任何协议都可用于发现。

安装了无线 LAN 服务的 Windows Vista 和 Windows Server 2008 支持临时客户端、临时服务和基础结构客户端的被动发现。 这意味着即席服务可以通过在一个或多个信标中传输 PSD IE 来播发可用的资源或服务。 无法保证临时客户端或基础结构客户端会接收此信标。

安装了无线 LAN 服务的 Windows 7 和 Windows Server 2008 R2 支持临时客户端、即席服务和基础结构客户端的被动发现，其方式与 Windows Vista 相同。 此外，无线托管网络（基于软件的无线接入点 (AP) ）也支持 PSD IE。 运行无线托管网络的本地计算机上的应用程序可以使用 WlanSetPsdIeDataList 函数在启动无线托管网络之前设置 PSD IE。 设置后，PSD IE 将包含在无线托管网络启动后的信标和探测响应中。

发送或接收信标的每个应用程序都维护自己的 PSD IE 数据列表。 pPsdIEDataList 参数指向应用程序生成的 PSD IE 列表。 每个 PSD IE 具有以下格式。

字段 说明和值
元素 ID (1 字节) 221
长度 (1 字节) 数据字段加 8 的长度（以字节为单位）。
OUI (3 个字节) 组织唯一标识符 (OUI) 必须包含值 00-50-F2。 此公共 OUI 已注册到 Microsoft。
OUI 类型 (1 字节) 对于邻近服务发现协议，OUI 类型必须包含值 6。
格式化标识符哈希 (4 个字节) 从 strFormat 参数计算的 HMAC 的位 31-0。
数据 (变量) 包含用于发现的用户定义的数据。 此字段的长度不得超过 240 个字节。
 

元素 ID 221 指定 IEEE 802.11 标准中定义的特定于供应商的信息元素。 组织唯一标识符 (OUI) 包含供应商的 3 字节 IEEE 分配的 OUI，该供应商定义信息元素的内容，顺序与在 IEEE 802.11 地址字段中传输 OUI 的顺序相同。 元素 ID、Length、OUI 和 OUI 类型字段由自动配置服务控制，而应用程序控制其余字段。

格式标识符哈希字段描述 PSD IE 中携带的信息的格式。 为了确保唯一性，同时避免对格式标识符进行集中管理的需求，使用 RFC 3986 中指定的统一资源标识符 (URI) 形式的字符串来区分格式。 但是，由于传输必须高效且信息元素中的空间有限，因此不会实际传输字符串，而是传输其哈希。 在客户端（信标的接收方）上，哈希与一组已知的格式标识符匹配。

格式标识符哈希字段由位 0 表示...基于哈希的消息身份验证代码的 31 (HMAC) strFormat 参数中指定的格式标识符字符串。 HMAC 用于指定 PSD IE 的“数据”字段的格式。 RFC 2104 中介绍了用于计算 HMAC 的公式。 HMAC 计算的示例代码是 RFC 4634 中指定的。 计算 HMAC 时，请将 SHA-256 用于哈希函数。 使用的密钥是指向身份验证密钥 (NULL 指针的“null”密钥，以及 RFC 4634) 中每个源代码的零长度身份验证密钥。 使用 strFormat 参数的值 (包括任何空格，但不包括 NULL 终止字符) 作为以 little endian 格式编码为 Unicode 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。

通过网络发送 HMAC 的前 4 个八位字节时，首先发送第一个 (最左) 八位字节。

请注意，截断的 HMAC 中可能存在冲突，这意味着可能无法从 HMAC 的给定位唯一确定与 PSD IE 有效负载对应的发现协议。 接收 PSD IE 的应用程序必须对给定 HMAC 中使用的发现协议进行最佳猜测，然后在建立连接后重新运行更高级别的发现协议。

最多可以在一个列表中传递五个 PSD IDE。 此外，PSD IE 列表的总长度（以字节为单位）可能会受到信标长度的硬件限制。

应用程序可以多次调用 WlanSetPsdIeDataList 。 使用同一 strFormat 调用 WlanSetPsdIeDataList 两次时，第一个函数调用填充的WLAN_RAW_DATA_LIST的内容将被第二次调用WLAN_RAW_DATA_LIST有效负载覆盖。 调用 WlanSetPsdIeDataList 且 pPsdIEDataList 参数设置为 NULL 时，将清除与 strFormat 关联的 PSD IE 列表。 调用 WlanSetPsdIeDataList 时，同时 将 pPsdIEDataList 和 strFormat 参数设置为 NULL 时，将清除应用程序设置的所有 PSD IE 列表。

无线服务处理由不同应用程序设置的 PSD IE 数据列表，并生成原始 IE 数据 Blob。 当计算机在任何无线适配器上创建或加入即席网络时，它会将包含与网络关联的 PSD IE 数据 Blob 的信标发送到其他计算机。

工作站可以在从计算机接收信标后调用 WlanExtractPsdIEDataList 函数来获取 PSD IE 数据列表。

要求

   
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 wlanapi.h (包括 Wlanapi.h)
Library Wlanapi.lib
DLL Wlanapi.dll

另请参阅

关于无线托管网络

WLAN_RAW_DATA_LIST

WlanExtractPsdIEDataList

WlanScan