wlanapi.h (wlanConnect 函数)

  • 项目

WlanConnect 函数尝试连接到特定网络。

语法

DWORD WlanConnect(
  [in] HANDLE                            hClientHandle,
  [in] const GUID                        *pInterfaceGuid,
  [in] const PWLAN_CONNECTION_PARAMETERS pConnectionParameters,
       PVOID                             pReserved
);

参数

[in] hClientHandle

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

[in] pInterfaceGuid

要用于连接的接口的 GUID。

[in] pConnectionParameters

指向 WLAN_CONNECTION_PARAMETERS 结构的指针，该结构指定连接类型、模式、网络配置文件、标识网络的 SSID 和其他参数。

带 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 无线 LAN API： WLAN_CONNECTION_PARAMETERS成员存在一些约束。 这意味着，对 Windows Server 2008 和 Windows Vista 有效的结构对于具有 SP3 的 Windows XP 或适用于 Windows XP SP2 的无线 LAN API 可能无效。 有关约束的列表，请参阅 WLAN_CONNECTION_PARAMETERS。

pReserved

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

返回值

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

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

返回代码 说明
ERROR_INVALID_PARAMETER
 出现以下情况之一：
  • hClientHandle 为 NULL 或无效。
  • pInterfaceGuid 为 NULL。
  • pConnectionParameters 为 NULL。
  • pConnectionParameters 指向的 结构的 dwFlags 成员未设置为WLAN_CONNECTION_PARAMETERS页上指定的值之一。
  • pConnectionParameters 指向的结构的 wlanConnectionMode 成员设置为 wlan_connection_mode_discovery_secure 或 wlan_connection_mode_discovery_unsecure，同一结构的 pDot11Ssid 成员为 NULL。
  • pConnectionParameters 指向的结构的 wlanConnectionMode 成员设置为 wlan_connection_mode_discovery_secure 或 wlan_connection_mode_discovery_unsecure，并且同一结构的 dot11BssType 成员设置为dot11_BSS_type_any。
  • pConnectionParameters 指向的结构的 wlanConnectionMode 成员设置为 wlan_connection_mode_profile，同一结构的 strProfile 成员为 NULL 或配置文件的长度超过 WLAN_MAX_NAME_LENGTH。
  • pConnectionParameters 指向的结构的 wlanConnectionMode 成员设置为 wlan_connection_mode_profile，并且同一结构的 strProfile 成员为 NULL 或配置文件的长度为零。
  • pConnectionParameters 指向的结构的 wlanConnectionMode 成员设置为 wlan_connection_mode_invalid 或 wlan_connection_mode_auto。
  • pConnectionParameters 指向的结构的 dot11BssType 成员设置为 dot11_BSS_type_infrastructure，同一结构的 dwFlags 成员设置为 WLAN_CONNECTION_ADHOC_JOIN_ONLY。
  • pConnectionParameters 指向的结构的 dot11BssType 成员设置为 dot11_BSS_type_independent，同一结构的 dwFlags 成员设置为 WLAN_CONNECTION_HIDDEN_NETWORK。
  • pConnectionParameters 指向的结构的 dwFlags 成员设置为 WLAN_CONNECTION_IGNORE_PRIVACY_BIT，并且同一结构的 wlanConnectionMode 成员未设置为 wlan_connection_mode_temporary_profile或同一结构的 dot11BssType 成员设置为dot11_BSS_type_independent。
ERROR_INVALID_HANDLE
 在句柄表中找不到句柄 hClientHandle 。
RPC_STATUS
 各种错误代码。
ERROR_ACCESS_DENIED
 调用方没有足够的权限。

注解

WlanConnect 函数将立即返回。 若要在建立连接或未尝试进一步连接时收到通知，客户端必须通过调用 WlanRegisterNotification 注册通知。

pConnectionParameters 指向的 WLAN_CONNECTION_PARAMETERS 结构的 strProfile 成员指定要用于连接的配置文件。 如果此配置文件是全用户配置文件， 则 WlanConnect 调用方必须对该配置文件具有执行访问权限。 否则， WlanConnect 调用将失败，返回值ERROR_ACCESS_DENIED。 使用 WlanSetProfile 或 WlanSaveTemporaryProfile 创建或保存配置文件时，将建立对所有用户配置文件的权限。

若要在命令行执行连接操作，请使用 netsh wlan connect 命令。 有关详细信息，请参阅 适用于无线局域网的 Netsh 命令 (wlan) 。

带 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 无线 LAN API： 只能使用 WlanConnect 连接到首选网络列表中的网络。 若要将网络添加到首选网络列表，请调用 WlanSetProfile。

要求

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

另请参阅

WLAN_CONNECTION_PARAMETERS

WlanDisconnect