wlanHostedNetworkSetSecondaryKey 函数 (wlanapi.h)

项目
08/28/2023

WlanHostedNetworkSetSecondaryKey 函数配置无线托管网络将使用的辅助安全密钥。

语法

DWORD WlanHostedNetworkSetSecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [in]            DWORD                       dwKeyLength,
  [in]            PUCHAR                      pucKeyData,
  [in]            BOOL                        bIsPassPhrase,
  [in]            BOOL                        bPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

参数

[in] hClientHandle

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

[in] dwKeyLength

pucKeyData 参数指向的键数据数组中的有效数据字节数。如果密钥是通行短语，则此密钥长度应包含终止“\0”。

[in] pucKeyData

指向包含键数据的缓冲区的指针。缓冲区中的有效数据字节数必须至少为 dwKeyLength 参数中指定的值。

[in] bIsPassPhrase

一个布尔值，指示 pucKeyData 参数指向的键数据数组是否采用通行短语格式。

如果此参数为 TRUE，则键数据数组采用通行短语格式。如果此参数为 FALSE，则键数据数组不采用通行短语格式。

[in] bPersistent

一个布尔值，该值指示 pucKeyData 参数指向的键数据数组是稍后存储并重复使用，还是仅供一次性使用。

如果此参数为 TRUE，则稍后将存储并重复使用密钥数据数组。如果此参数为 FALSE，则如果托管网络未) 启动，则将将密钥数据数组用于当前会话或下一个会话 (。

[out, optional] pFailReason

如果对 WlanHostedNetworkSetSecondaryKey 函数的调用失败，则为指向接收失败原因的值的可选指针。失败原因的可能值来自 wlanapi.h 头文件中定义的 WLAN_HOSTED_NETWORK_REASON 枚举类型。

pvReserved

保留供将来使用。此参数必须为 NULL。

返回值

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

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

返回代码	说明
ERROR_INVALID_HANDLE	句柄无效。如果在句柄表中找不到 hClientHandle 参数中指定的句柄，则返回此错误。
ERROR_INVALID_PARAMETER	参数不正确。如果出现以下任一情况，将返回此错误： hClientHandle 为 NULL。 pucKeyData 为 NULL。 pucKeyData 不指向格式正确的有效密钥。 pvReserved 不为 NULL。
ERROR_INVALID_STATE	资源未处于执行所请求操作的正确状态。如果无线托管网络正在关闭，则可能会发生这种情况。
ERROR_SERVICE_NOT_ACTIVE	该服务尚未启动。如果 WLAN 自动配置服务未运行，则返回此错误。
其他	各种 RPC 和其他错误代码。使用 FormatMessage 获取返回错误的消息字符串。

注解

WlanHostedNetworkSetSecondaryKey 函数是本机无线 API 的扩展，添加了支持 Windows 7 和 Windows Server 2008 R2 上安装了无线 LAN 服务的无线托管网络。

客户端应用程序调用 WlanHostedNetworkSetSecondaryKey 函数来配置无线托管网络将使用的辅助安全密钥。如果调用应用程序通过调用具有 hClientHandle) 参数的 WlanCloseHandle 关闭其调用句柄 (，则此函数引起的任何托管网络更改都不会自动撤消，或者如果进程结束。

启动后，无线托管网络将允许无线对等互连与此辅助安全密钥以及主要安全密钥相关联。辅助安全密钥始终由用户根据需要指定，而主要安全密钥由具有更大安全强度的操作系统生成。

在 pucKeyData 参数指向的缓冲区中传递的辅助安全密钥用于 WPA2-Personal 身份验证，应采用以下格式之一：

由 8 到 63 个字符的 ASCII 字符数组组成的密钥通行短语。 dwKeyLength 参数应在通行短语中包含终止符“\0”。 dwKeyLength 参数的值应在 9 到 64 的范围内。
由 32 个字节的二进制键数据组成的二进制键。对于二进制 键，dwKeyLength 参数应为 32。

若要配置有效的辅助安全密钥， dwKeyLength 参数应位于正确的范围内， pucKeyData 参数应指向包含指定数据字节的有效内存缓冲区。若要从系统中删除当前配置的辅助安全密钥，应用程序应调用 wlanHostedNetworkSetSecondaryKey 函数，dwKeyLength 参数中为零，pucKeyData 参数中为 NULL。

如果 pucKeyData 参数为 NULL，但 dwKeyLength 参数不为零，WlanHostedNetworkSetSecondaryKey 函数将返回ERROR_INVALID_PARAMETER。如果 dwKeyLength 参数为零，但 pucKeyData 参数不为 NULL，WlanHostedNetworkSetSecondaryKey 函数也将返回ERROR_INVALID_PARAMETER。

辅助安全密钥通常在无线托管网络启动之前设置。然后，它将在下次启动托管网络时使用。

也可以在启动托管网络后设置辅助安全密钥。在这种情况下，将立即使用辅助安全密钥。使用以前的辅助安全密钥的任何客户端将保持连接状态，但如果由于任何原因断开连接或重新启动无线托管网络，它们将无法重新连接。

如果 bPersistent 参数设置为 TRUE，则可以将辅助安全密钥指定为永久性。指定为永久性时，如果已启动托管网络，则会立即使用辅助安全密钥，并在将来每次启动托管网络时重复使用。

如果未将辅助安全密钥指定为永久性密钥，则当托管网络已启动时，将立即使用该密钥，或仅在下次启动托管网络时使用。停止托管网络后，此辅助安全密钥将永远不会再次使用，并且将从系统中删除。

任何用户都可以调用此函数来配置要用于托管网络中的辅助安全密钥。但是，启用无线托管网络的能力可能会受到域中的组策略的限制。

在 Windows 7 及更高版本上，如果计算机上存在支持托管网络的无线适配器，则操作系统将安装虚拟设备。如果计算机具有单个无线网络适配器，此虚拟设备通常会在“网络连接文件夹”中显示为“无线网络连接 2”，设备名称为“Microsoft 虚拟 WiFi 微型端口适配器”。此虚拟设备专门用于执行软接入点 (SoftAP) 连接，并且不存在于 WlanEnumInterfaces 函数返回的列表中。此虚拟设备的生存期与物理无线适配器相关联。如果物理无线适配器处于禁用状态，此虚拟设备也将被删除。此功能在安装了无线 LAN 服务的 Windows Server 2008 R2 上也可用。

要求


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