wlanapi.h) (WlanSetProfile 函数

  • 项目

WlanSetProfile 函数设置特定配置文件的内容。

语法

DWORD WlanSetProfile(
  [in]           HANDLE     hClientHandle,
  [in]           const GUID *pInterfaceGuid,
  [in]           DWORD      dwFlags,
  [in]           LPCWSTR    strProfileXml,
  [in, optional] LPCWSTR    strAllUserProfileSecurity,
  [in]           BOOL       bOverwrite,
  [in]           PVOID      pReserved,
  [out]          DWORD      *pdwReasonCode
);

参数

[in] hClientHandle

客户端的会话句柄，由先前对 WlanOpenHandle 函数的调用获取。

[in] pInterfaceGuid

接口的 GUID。

[in] dwFlags

要对配置文件设置的标志。

带 SP3 的 Windows XP 和带有 SP2 的 Windows XP 无线 LAN API： dwFlags 必须为 0。 不支持每用户配置文件。

值 含义
0
 配置文件是一个全用户配置文件。
WLAN_PROFILE_GROUP_POLICY
0x00000001
 配置文件是组策略配置文件。
WLAN_PROFILE_USER
0x00000002
 配置文件是每用户配置文件。

[in] strProfileXml

包含配置文件的 XML 表示形式。 WLANProfile 元素是根配置文件元素。 若要查看示例配置文件，请参阅 无线配置文件示例。 没有预定义的最大字符串长度。

带 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 无线 LAN API： 提供的配置文件必须满足 无线配置文件兼容性中所述的兼容性条件。

[in, optional] strAllUserProfileSecurity

在所有用户配置文件上设置安全描述符字符串。 有关配置文件权限的详细信息，请参阅“备注”部分。

如果 dwFlags 设置为 WLAN_PROFILE_USER，则忽略此参数。

如果对于新的所有用户配置文件，此参数设置为 NULL ，则使用与 wlan_secure_add_new_all_user_profiles 对象关联的安全描述符。 如果 WlanSetSecuritySettings 调用未修改安全描述符，则所有用户都对新的所有用户配置文件具有默认权限。 调用 WlanGetSecuritySettings 以获取与 wlan_secure_add_new_all_user_profiles 对象关联的默认权限。

如果现有所有用户配置文件的此参数设置为 NULL ，则配置文件的权限不会更改。

如果此参数对于所有用户配置文件不为 NULL ，则会在创建安全描述符对象并将其分析为字符串后，创建或修改与该配置文件关联的安全描述符字符串。

带 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 无线 LAN API： 此参数必须为 NULL。

[in] bOverwrite

指定此配置文件是否覆盖现有配置文件。 如果此参数为 FALSE 且配置文件已存在，则不会覆盖现有配置文件，并且将返回错误。

[in] pReserved

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

[out] pdwReasonCode

WLAN_REASON_CODE值，该值指示配置文件无效的原因。

返回值

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

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

返回代码 说明
ERROR_ACCESS_DENIED
 调用方没有足够的权限来设置配置文件。

当将 dwFlags 设置为 0（即设置全用户配置文件时）调用时， WlanSetProfile 将检索随 wlan_secure_add_new_all_user_profiles 对象一起存储 (DACL ) 自由访问控制列表。 当将 dwFlags 设置为 WLAN_PROFILE_USER （即设置每用户配置文件时）调用时， WlanSetProfile 将检索随 wlan_secure_add_new_per_user_profiles 对象一起存储 (DACL) 自由访问控制列表。 在任一情况下，如果 DACL 不包含授予对调用线程的访问令牌WLAN_WRITE_ACCESS权限的 ACE) (访问控制项，则 WlanSetProfile 将返回 ERROR_ACCESS_DENIED。
ERROR_ALREADY_EXISTS
 strProfileXml 指定已存在的网络。 通常，当 bOverwrite 为 FALSE 时，将使用此返回值;但是，如果 bOverwrite 为 TRUE 且 dwFlags 指定的配置文件类型与现有配置文件使用的配置文件类型不同，则不会覆盖现有配置文件，并且将返回 ERROR_ALREADY_EXISTS 。
ERROR_BAD_PROFILE
 strProfileXml 指定的配置文件无效。 如果返回此值， 则 pdwReasonCode 将指定配置文件无效的原因。
ERROR_INVALID_PARAMETER
 出现以下情况之一：
  • hClientHandle 为 NULL 或无效。
  • pInterfaceGuid 为 NULL。
  • pReserved 不为 NULL。
  • strProfileXml 为 NULL。
    • [ConfigBlob] (/windows/desktop/eaphost/eaphostconfigschema-configblob-eaphostconfig-element) 。 如果配置文件必须具有空 的 ConfigBlob，请在 <ConfigBlob>00</ConfigBlob> 配置文件中使用 。
  • pdwReasonCode 为 NULL。
  • dwFlags 未设置为指定的值之一。
  • dwFlags 设置为 WLAN_PROFILE_GROUP_POLICY bOverwrite 设置为 FALSE。
ERROR_NO_MATCH
 接口不支持配置文件中指定的一个或多个功能。 例如，如果配置文件指定在 NIC 仅支持 WPA 时使用 WPA2，则返回此错误代码。 此外，如果配置文件指定在 NIC 不支持 FIPS 模式时使用 FIPS 模式，则返回此错误代码。
RPC_STATUS
 各种错误代码。

注解

WlanSetProfile 函数可用于添加新的无线 LAN 配置文件或替换现有的无线 LAN 配置文件。

新配置文件将添加到列表顶部的组策略配置文件后面。 如果覆盖现有配置文件，则配置文件在列表中的位置不会更改。带 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 无线 LAN API：

临时配置文件显示在配置文件列表中的基础结构配置文件之后。 如果创建新的临时配置文件，则会将其置于临时列表顶部的组策略和基础结构配置文件之后。

不支持 802.1X 来宾配置文件、无线预配服务 (WPS) 配置文件，以及具有 Wi-Fi Protected Access-None (WPA-None) 身份验证的配置文件。 这意味着无法使用 Native Wifi 函数创建、删除、枚举或访问此类配置文件。 已在首选配置文件列表中的任何此类配置文件都将保留在列表中，并且其相对于其他配置文件在列表中的位置是固定的，除非其他配置文件的位置发生更改。

可以在包含纯文本键 (配置文件上调用 WlanSetProfile ，即存在 受保护 元素并设置为 FALSE) 的配置文件。 在配置文件保存到配置文件存储中之前，会自动加密密钥材料。 随后通过调用 WlanGetProfile 从配置文件存储中检索配置文件时，将返回加密密钥材料。带 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 无线 LAN API： 密钥材料永远不会加密。

所有用户配置文件具有三个关联的权限：读取、写入和执行。 如果用户具有读取访问权限，则用户可以查看配置文件权限。 如果用户具有执行访问权限，则用户具有读取访问权限，并且用户也可以使用配置文件连接到网络并断开其连接。 如果用户具有写入访问权限，则用户具有执行访问权限，并且用户还可以修改和删除与配置文件关联的权限。

下面介绍了创建安全描述符对象并将其分析为字符串的过程。

  1. 调用 InitializeSecurityDescriptor 以在内存中创建安全描述符。
  2. 调用 SetSecurityDescriptorOwner。
  3. 调用 InitializeAcl 以在内存中创建自由访问控制列表 (DACL) 。
  4. 调用 AddAccessAllowedAce 或 AddAccessDeniedAce (ACE) 添加到 DACL。 根据需要将 AccessMask 参数设置为以下值之一：
    • WLAN_READ_ACCESS
    • WLAN_EXECUTE_ACCESS
    • WLAN_WRITE_ACCESS
  5. 调用 SetSecurityDescriptorDacl 将 DACL 添加到安全描述符。
  6. 调用 ConvertSecurityDescriptorToStringSecurityDescriptor 将描述符转换为字符串。
然后，在调用 WlanSetProfile 时，ConvertSecurityDescriptorToStringSecurityDescriptor 返回的字符串可用作 strAllUserProfileSecurity 参数值。

对于 Native Wifi AutoConfig 服务使用的每个无线 LAN 配置文件，Windows 维护自定义用户数据的概念。 此自定义用户数据最初不存在，但可以通过调用 WlanSetProfileCustomUserData 函数进行设置。 每当通过调用 WlanSetProfile 函数修改配置文件时，自定义用户数据都会重置为空。 设置自定义用户数据后，可以使用 WlanGetProfileCustomUserData 函数访问此数据。

执行配置文件操作时，所有无线 LAN 函数都需要无线接口的接口 GUID。 删除无线接口时，其状态将从无线 LAN 服务 (WLANSVC) 清除，并且无法执行配置文件操作。

如果已从系统中删除 pInterfaceGuid 参数中指定的无线接口， (已删除的 USB 无线适配器（例如 ) ），WlanSetProfile 函数可能会失败并ERROR_INVALID_PARAMETER。

netsh wlan add profile 命令在命令行中提供类似的功能。 有关详细信息，请参阅 适用于无线局域网的 Netsh 命令 (wlan) 。

要求

要求 值
最低受支持的客户端 Windows Vista、Windows XP SP3 [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 wlanapi.h (包括 Wlanapi.h)
Library Wlanapi.lib
DLL Wlanapi.dll
可再发行组件 带有 SP2 的 Windows XP 无线 LAN API

另请参阅

ConvertSecurityDescriptorToStringSecurityDescriptor

InitializeAcl

InitializeSecurityDescriptor

本机 Wifi API 权限

SetSecurityDescriptorDacl

WlanGetProfile

WlanGetProfileCustomUserData

WlanGetProfileList

WlanQueryInterface

WlanSetProfileCustomUserData

WlanSetProfileEapUserData

WlanSetProfileEapXmlUserData