Home > > Windows WlanAPI文档说明

Windows WlanAPI文档说明

14 June, 2019  

结构体

WLAN_INTERFACE_INFO_LIST

这个结构体是包含着网卡接口信息的阵列。

typedef struct _WLAN_INTERFACE_INFO_LIST {
DWORD dwNumberOfItems;
DWORD dwIndex;
WLAN_INTERFACE_INFO InterfaceInfo[];
} WLAN_INTERFACE_INFO_LIST,
*PWLAN_INTERFACE_INFO_LIST;
dwNumberOfItems :InterfaceInfo[ ]中包含的单元的个数。

dwIndex :当前单元的索引,从0开始到dwNumberOfItems-1

这个参数一般用于在WLAN_INTERFACE_INFO_LIST被用作参数传递时的一个传递偏移量。这个参数在用之前必须要进行初始化。

InterfaceInfo[ ]:包含WLAN_INTERFACE_INFO结构体的阵列,用于记录接口信息。

WLAN_INTERFACE_INFO

这个结构体包含了WLan接口的信息。

typedef struct _WLAN_INTERFACE_INFO {
GUID InterfaceGuid;
WCHAR strInterfaceDescription[256];
WLAN_INTERFACE_STATE isState;
} WLAN_INTERFACE_INFO,
*PWLAN_INTERFACE_INFO;
InterfaceGuid :接口的GUID

strInterfaceDescription :接口的描述信息

isState :包含一个 WLAN_INTERFACE_STATE 值,标示这个接口的当前状态。

WLAN_INTERFACE_STATE

枚举类型,用于标示当前接口的状态。

typedef enum _WLAN_INTERFACE_STATE {
wlan_interface_state_not_ready = 0, // The interface is not ready to operate.
wlan_interface_state_connected= 1,// The interface is connected to a network.
wlan_interface_state_ad_hoc_network_formed = 2,// The interface is the first node in an ad hoc network. No peer has connected.
wlan_interface_state_disconnecting = 3, // The interface is disconnecting from the current network.
wlan_interface_state_disconnected= 4, // The interface is not connected to any network.
wlan_interface_state_associating = 5, // The interface is attempting to associate with a network.
wlan_interface_state_discovering = 6, // Auto configuration is discovering the settings for the network.
wlan_interface_state_authenticating= 7 // The interface is in the process of authenticating.
} WLAN_INTERFACE_STATE,
*PWLAN_INTERFACE_STATE;
注:Wireless LAN API for Windows XP SP2: Only the wlan_interface_state_connected, wlan_interface_state_disconnected, and wlan_interface_state_authenticating values are supported.

WLAN_INTERFACE_CAPABILITY

这个结构体的内容就是接口的能力信息。

typedef struct _WLAN_INTERFACE_CAPABILITY {
WLAN_INTERFACE_TYPE interfaceType;
BOOL bDot11DSupported;
DWORD dwMaxDesiredSsidListSize;
DWORD dwMaxDesiredBssidListSize;
DWORD dwNumberOfSupportedPhys;
DOT11_PHY_TYPE dot11PhyTypes[WLAN_MAX_PHY_INDEX];
} WLAN_INTERFACE_CAPABILITY,
*PWLAN_INTERFACE_CAPABILITY;
interfaceType : WLAN_INTERFACE_TYPE 值,标示这接口的类型。

bDot11DSupported :是否支持 802.11d ,支持则为 TRUE.

dwMaxDesiredSsidListSize :这个接口支持的SSID的列表的最大值

dwMaxDesiredBssidListSize :这个列表支持的 BSSID的列表的最大值

dwNumberOfSupportedPhys :支持几种PHY类型

dot11PhyTypes :支持的PHY类型(DOT11_PHY_TYPE)列表,最大长度为64.

网卡工作在osi的最后两层,物理层(PHY)和数据链路层(MAC)。

物理层定义了数据传送与接收所需要的电与光信号、线路状态、时钟基准、数据编码和电路等,并向数据链路层设备提供标准接口。物理层的芯片称之为PHY。

数据链路层则提供寻址机构、数据帧的构建、数据差错检查、传送控制、向网络层提供标准的数据接口等功能。以太网卡中数据链路层的芯片称之为MAC控制器。

很多网卡的这两个部分是做到一起的。

他们之间的关系是pci总线接mac总线,mac接phy,phy接网线

DOT11_PHY_TYPE

枚举类型,PHY类型。

typedef enum _DOT11_PHY_TYPE{
dot11_phy_type_unknown //Specifies an unknown or uninitialized PHY type.
dot11_phy_type_any //Specifies any PHY type.
dot11_phy_type_fhss //Specifies a frequency-hopping spread-spectrum (FHSS) PHY. Bluetooth devices can use FHSS or an adaptation of FHSS.
dot11_phy_type_dsss //Specifies a direct sequence spread spectrum (DSSS) PHY type.
dot11_phy_type_irbaseband //Specifies an infrared (IR) baseband PHY type.
dot11_phy_type_ofdm //Specifies an orthogonal frequency division multiplexing (OFDM) PHY type. 802.11a devices can use OFDM.
dot11_phy_type_hrdsss //Specifies a high-rate DSSS (HRDSSS) PHY type.
dot11_phy_type_erp //Specifies an extended rate PHY type (ERP). 802.11g devices can use ERP.,
dot11_phy_type_ht //Specifies the 802.11n PHY type.
dot11_phy_type_IHV_start //Specifies the start of the range that is used to define PHY types that are developed by an independent hardware vendor (IHV).
dot11_phy_type_IHV_end //Specifies the start of the range that is used to define PHY types that are developed by an independent hardware vendor (IHV).
} DOT11_PHY_TYPE,
*PDOT11_PHY_TYPE;

DOT11_BSS_TYPE
枚举类型,用于定义BSS网络的类型

typedef enum _DOT11_BSS_TYPE {
dot11_BSS_type_infrastructure,
dot11_BSS_type_independent,
dot11_BSS_type_any,
} DOT11_BSS_TYPE, *PDOT11_BSS_TYPE;

dot11_BSS_type_infrastructure : 为 infrastructure BSS 网络。

dot11_BSS_type_independent :为independent BSS网络

dot11_BSS_type_any :是 infrastructure 或者 independent BSS网络

infrastructure BSS:

中控型基本服务集 (BSS)是一个包含了一个接入点和一些站点的 802.11 网络。这个接入点将信息送入目标站点或者一个固定网络。

independent BSS:

IBSS(Independent Basic Service Set) 独立基本服务集 。是一种无线拓扑结构,IEEE802.11标准的模式

WLAN_CONNECTION_ATTRIBUTES

这个结构体用来定义一个无线连接(a connection)的属性。

typedef struct _WLAN_CONNECTION_ATTRIBUTES {
WLAN_INTERFACE_STATE isState;
WLAN_CONNECTION_MODE wlanConnectionMode;
WCHAR strProfileName[256];
WLAN_ASSOCIATION_ATTRIBUTES wlanAssociationAttributes;
WLAN_SECURITY_ATTRIBUTES wlanSecurityAttributes;
} WLAN_CONNECTION_ATTRIBUTES,
*PWLAN_CONNECTION_ATTRIBUTES;
isState :接口状态。取值见上面的WLAN_INTERFACE_STATE枚举类型介绍。

wlanConnectionMode :连接模式,取值自:WLAN_CONNECTION_MODE

strProfileName : 这个连接采用的profile名称。大小写敏感且必须以NULL结尾,

wlanAssociationAttributes:association的属性 结构体 WLAN_ASSOCIATION_ATTRIBUTES

wlanSecurityAttributes :这个连接的安全属性 结构体 WLAN_SECURITY_ATTRIBUTES

profilename. 指定无线网络连接的配置文件名称
association 和 connection 有什么区别????

WLAN_CONNECTION_MODE

枚举类型,连接模式。

typedef enum _WLAN_CONNECTION_MODE{
wlan_connection_mode_profile //A profile will be used to make the connection.
wlan_connection_mode_temporary_profile //A temporary(temporary :临时的) profile will be used to make the connection.
wlan_connection_mode_discovery_secure //Secure discovery will be used to make the connection.
wlan_connection_mode_discovery_unsecure //Unsecure discovery will be used to make the connection.
wlan_connection_mode_auto //A connection will be made automatically, generally using a persistent profile. (persistent :持续不断的)
wlan_connection_mode_invalid //Not used.
}WLAN_CONNECTION_MODE,
*PWLAN_CONNECTION_MODE;

WLAN_ASSOCIATION_ATTRIBUTES

结构体,contains association attributes for a connection 。(我的理解就是要连接的网络的属性)
typedef struct _WLAN_ASSOCIATION_ATTRIBUTES {
DOT11_SSID dot11Ssid;
DOT11_BSS_TYPE dot11BssType;
DOT11_MAC_ADDRESS dot11Bssid;
DOT11_PHY_TYPE dot11PhyType;
ULONG uDot11PhyIndex;
WLAN_SIGNAL_QUALITY wlanSignalQuality;
USHORT usRxRate;
USHORT usTxRate;
} WLAN_ASSOCIATION_ATTRIBUTES,
*PWLAN_ASSOCIATION_ATTRIBUTES;
dot11Ssid :SSID 见结构体DOT11_SSID

dot11BssType :网络类型 见结构体 DOT11_BSS_TYPE

wlanSignalQuality : 信号强度

usRxRate :接收范围

usTxRate : 传播范围

DOT11_SSID

结构体,定义接口的SSID.
typedef struct _DOT11_SSID {
ULONG uSSIDLength;
UCHAR ucSSID[DOT11_SSID_MAX_LENGTH];
} DOT11_SSID,
*PDOT11_SSID;
uSSIDLength : ucSSID的字节长度

ucSSID :SSID ,DOT11_SSID_MAX_LENGTH 值为32.

DOT11_BSS_TYPE

枚举类型,用来标示这个网络类型是 infrastructure 还是 ad-hoc 。

typedef enum _DOT11_BSS_TYPE {
dot11_BSS_type_infrastructure
dot11_BSS_type_independent
dot11_BSS_type_any
} DOT11_BSS_TYPE,
*PDOT11_BSS_TYPE;

WLAN_CONNECTION_PARAMETERS

在使用WlanConnect 这个函数的时候,这个结构体需要作为参数来设定连接属性。

typedef struct _WLAN_CONNECTION_PARAMETERS {
WLAN_CONNECTION_MODE wlanConnectionMode;
LPCWSTR strProfile;
PDOT11_SSID pDot11Ssid;
PDOT11_BSSID_LIST pDesiredBssidList;
DOT11_BSS_TYPE dot11BssType;
DWORD dwFlags;
} WLAN_CONNECTION_PARAMETERS,
*PWLAN_CONNECTION_PARAMETERS;

WLAN_AVAILABLE_NETWORK_LIST

结构体,包含可用网络(network)的信息的列表。

typedef struct _WLAN_AVAILABLE_NETWORK_LIST {
DWORD dwNumberOfItems;
DWORD dwIndex;
WLAN_AVAILABLE_NETWORK Network[1];
}  WLAN_AVAILABLE_NETWORK_LIST,
*PWLAN_AVAILABLE_NETWORK_LIST;
dwNumberOfItems :Network中包含的单元的个数

dwIndex :当前单元的索引,从0开始到dwNumberOfItems-1;

当这个结构体作为参数时用到。用之前必须赋初值。

Network :一个WLAN_AVAILABLE_NETWORK 的列表,包含接口信息。

WLAN_AVAILABLE_NETWORK

结构体,包含可用无线网络(network)单元的信息。

typedef struct _WLAN_AVAILABLE_NETWORK {
WCHAR strProfileName[256];
DOT11_SSID dot11Ssid;  //SSID
DOT11_BSS_TYPE dot11BssType;
ULONG uNumberOfBssids;
BOOL bNetworkConnectable;
WLAN_REASON_CODE wlanNotConnectableReason;
ULONG uNumberOfPhyTypes;
DOT11_PHY_TYPE dot11PhyTypes[WLAN_MAX_PHY_TYPE_NUMBER];
BOOL bMorePhyTypes;
WLAN_SIGNAL_QUALITY wlanSignalQuality;  //信号强度
BOOL bSecurityEnabled;
DOT11_AUTH_ALGORITHM dot11DefaultAuthAlgorithm;
DOT11_CIPHER_ALGORITHM dot11DefaultCipherAlgorithm;
DWORD dwFlags;
DWORD dwReserved;
} WLAN_AVAILABLE_NETWORK,
*PWLAN_AVAILABLE_NETWORK;

部分API

WlanCloseHandle

函数原型:

DWORD WINAPI WlanCloseHandle(__in HANDLE hClientHandle, PVOID pReserved )

函数功能:

关闭一个与服务器间的连接

参数意义:

hClientHandle :要关闭的连接的客户端句柄(由 WlanOpenHandle 得到)

pReserved :设置为NULL

返回值:

成功:返回 ERROR_SUCCESS

失败:

Return code Description
ERROR_INVALID_PARAMETER

hClientHandle is NULL or invalid, or pReserved is not NULL.

ERROR_INVALID_HANDLE

The handle hClientHandle was not found in the handle table.

RPC_STATUS

Various error codes.

注意:

在连接关闭之后,任何的对于已经关闭的连接的操作都会造成错误;在关闭过程中,任何未解决的通知都会被忽略。

如果在调用这个函数的时候,客户端正处于一个通知的回调函数中,那么,这个函数会等待直到回调函数结束。因此如果把这个函数的调用放在某个通知的回调中,那么会导致永远无法结束。

WlanOpenHandle

函数原型:

DWORD WINAPI WlanOpenHandle( __in DWORD dwClientVersion, PVOID pReserved, __out PDWORD pdwNegotiatedVersion, __out PHANDLE phClientHandle );
函数功能:

打开一个与服务器的连接。

参数:

dwClientVersion :客户端支持的WLAN API的最高版本

Value Meaning
1

Client version for Wireless LAN API for Windows XP SP2.

2

Client version for Windows Vista and Windows Server 2008

pReserved :设置为NULL

pdwNegotiatedVersion :指定这次会话中将会使用的版本

phClientHandle :指定客户端在这次会话中使用的句柄,这个句柄会贯穿整个会话被其他函数使用 。

返回值:

成功:ERROR_SUCCESS

失败:

Return code Description
ERROR_INVALID_PARAMETER

pdwNegotiatedVersion is NULL, phClientHandle is NULL, or pReserved is not NULL.

ERROR_NOT_ENOUGH_MEMORY

Failed to allocate memory to create the client context.

RPC_STATUS

Various error codes.

ERROR_REMOTE_SESSION_LIMIT_EXCEEDED

Too many handles have been issued by the server

注意:

dwClientVersion 和 pdwNegotiatedVersion 指定的版本号,是一个由较大版本值和较小版本值混合而成的版本数。较大版本值由高位值指定,较小值由低位值指定。宏定义 WLAN_API_VERSION_MAJOR(_v) 和 WLAN_API_VERSION_MINOR(_v)各自返回较大版本值和较小版本值。可以通过宏定义WLAN_API_MAKE_VERSION(_major, _minor).组装一个版本号。

如果WZC服务没有开启或者没有响应,这个方法会返回错误。

WlanEnumInterfaces

函数功能:

枚举处当前系统安装的所有无线网卡的接口信息。

函数原型:

DWORD WINAPI WlanEnumInterfaces( __in HANDLE hClientHandle, __in PVOID pReserved, __out PWLAN_INTERFACE_INFO_LIST* ppInterfaceList );
参数:

hClientHandle :客户端会话句柄。由 WlanOpenHandle 得到。

pReserved :需要设置为NULL

ppInterfaceList : 指向包含无线网卡接口信息list的结构体 PWLAN_INTERFACE_INFO_LIST 的指针。

返回值:

成功:ERROR_SUCCESS

失败:

Return code Description
ERROR_INVALID_PARAMETER

hClientHandle is NULL or invalid, pReserved is not NULL, or ppInterfaceList is NULL.

ERROR_INVALID_HANDLE

The handle hClientHandle was not found in the handle table.

RPC_STATUS

Various error codes.

ERROR_NOT_ENOUGH_MEMORY

Failed to allocate memory to create the client context.

注意:

这个函数会给返回接口信息的list分配内存,需要通过 WlanFreeMemory 来释放这部分内存。

WlanFreeMemory

函数功能:

释放内存。任何由 WLAN API 返回的内存都需要进行释放。

函数原型:

VOID WINAPI WlanFreeMemory(
__in PVOID pMemory
);

参数:

pMemory :指向需要释放的内存

注意:

如果这块内存已经释放,那么会有一个 违法接近 或 堆扰乱 产生 。

WlanRegisterNotification

函数功能:

这个函数用于给所有无线接口注册或注销通知(notifications)。

函数原型:

DWORD WINAPI WlanRegisterNotification(
__in HANDLE hClientHandle,
__in DWORD dwNotifSource,
__in BOOL bIgnoreDuplicate,
__in_opt WLAN_NOTIFICATION_CALLBACK funcCallback,
__in_opt PVOID pCallbackContext,
__in PVOID pReserved,
__out_opt PDWORD pdwPrevNotifSource
);
参数意义:

hClientHandle :客户端的会话句柄。由 WlanOpenHandle 得到。

dwNotifSource :要注册的通知源(notification sources),可以是个组合值。当设置为WLAN_NOTIFICATION_SOURCE_NONE 时,这个函数会注销所有无线接口的通知。

Value Meaning
WLAN_NOTIFICATION_SOURCE_NONE

Unregisters notifications.

WLAN_NOTIFICATION_SOURCE_ALL

Registers for all notifications, including those generated by the 802.1X module.

WLAN_NOTIFICATION_SOURCE_ACM

Registers for notifications generated by the auto configuration module.

WLAN_NOTIFICATION_SOURCE_MSM

Registers for notifications generated by MSM.

WLAN_NOTIFICATION_SOURCE_SECURITY

Registers for notifications generated by the security module.

WLAN_NOTIFICATION_SOURCE_IHV

Registers for notifications generated by independent hardware vendors (IHV).

当为XP SP2时,只能设置为 WLAN_NOTIFICATION_SOURCE_NONE, WLAN_NOTIFICATION_SOURCE_ALL, 或者 WLAN_NOTIFICATION_SOURCE_ACM 。

bIgnoreDuplicate :是否忽略相同的通知。如果设置为TRUE,那么与上一个通知相同的通知就不会发给客户端。

funcCallback :WLAN_NOTIFICATION_CALLBACK 类型,用于定义通知的回调函数。

pCallbackContext :指向客户端上下文that will be passed to the callback function with the notification

pReserved :设置为NULL

pdwPrevNotifSource :指向先前注册的通知源

WlanGetAvailableNetworkList

函数功能:

用于检索接口上可用的网络。

函数原型:

DWORD WINAPI WlanGetAvailableNetworkList(
__in HANDLE hClientHandle,
__in const GUID* pInterfaceGuid,
__in DWORD dwFlags,
PVOID pReserved,
__out PWLAN_AVAILABLE_NETWORK_LIST* ppAvailableNetworkList
);
参数:

hClientHandle :客户端的会话句柄

pInterfaceGuid :要检索的接口的GUID

dwFlags :控制list中返回的网络的类型

Value Meaning
WLAN_AVAILABLE_NETWORK_INCLUDE_ALL_ADHOC_PROFILES
0x00000001

Include all ad-hoc network profiles in the available network list, including profiles that are not visible.

WLAN_AVAILABLE_NETWORK_INCLUDE_ALL_MANUAL_HIDDEN_PROFILES
0x00000002

Include all hidden network profiles in the available network list, including profiles that are not visible.

ppAvailableNetworkList :指向返回的可用网络的 WLAN_AVAILABLE_NETWORK_LIST 的指针。

返回值:

成功:ERROR_SUCCESS

失败:

Return code Description
ERROR_INVALID_PARAMETER

hClientHandle is NULL or invalid, pInterfaceGuid is NULL, pReserved is not NULL, ppAvailableNetworkList is NULL, or the dwFlags parameter value is not set to one of the specified values.

ERROR_INVALID_HANDLE

The handle hClientHandle was not found in the handle table.

ERROR_NDIS_DOT11_POWER_STATE_INVALID

The radio for the interface is turned off. There are no available networks when the radio is off.

RPC_STATUS

Various error codes.

ERROR_NOT_ENOUGH_MEMORY

Failed to allocate memory for the query results.

注意:

这个函数会给返回的list分配空间,需要调用 WlanFreeMemory 来释放这部分内存。

WlanConnect

函数功能:

尝试连接一个指定的网络。

函数原型:

DWORD WINAPI WlanConnect(
__in HANDLE hClientHandle,
__in const GUID* pInterfaceGuid,
__in const PWLAN_CONNECTION_PARAMETERS pConnectionParameters,
PVOID pReserved
);

参数:

hClientHandle :客户端句柄

pInterfaceGuid :连接使用的接口的GUID

pConnectionParameters :指向结构体 WLAN_CONNECTION_PARAMETERS ,其中指定了连接类型,模式,网络概况,SSID 等其他参数。

pReserved :需要设置为NULL

返回值:

成功:ERROR_SUCCESS

失败:

Return code Description
ERROR_INVALID_PARAMETER

One of the following conditions occurred:

hClientHandle is NULL or invalid.
pInterfaceGuid is NULL.
pConnectionParameters is NULL.
The dwFlags member of the structure pointed to by pConnectionParameters is not set to one of the values specified on the WLAN_CONNECTION_PARAMETERS page.
The wlanConnectionMode member of the structure pointed to by pConnectionParameters is set to wlan_connection_mode_discovery_secure or wlan_connection_mode_discovery_unsecure, and the pDot11Ssid member of the same structure is NULL.
The wlanConnectionMode member of the structure pointed to by pConnectionParameters is set to wlan_connection_mode_discovery_secure or wlan_connection_mode_discovery_unsecure, and the dot11BssType member of the same structure is set to dot11_BSS_type_any.
The wlanConnectionMode member of the structure pointed to by pConnectionParameters is set to wlan_connection_mode_profile, and the strProfile member of the same structure is NULL or the length of the profile exceeds WLAN_MAX_NAME_LENGTH.
The wlanConnectionMode member of the structure pointed to by pConnectionParameters is set to wlan_connection_mode_profile, and the strProfile member of the same structure is NULL or the length of the profile is zero.
The wlanConnectionMode member of the structure pointed to by pConnectionParameters is set to wlan_connection_mode_invalid.
The dot11BssType member of the structure pointed to by pConnectionParameters is set to dot11_BSS_type_infrastructure, and the dwFlags member of the same structure is set to WLAN_CONNECTION_ADHOC_JOIN_ONLY.
The dot11BssType member of the structure pointed to by pConnectionParameters is set to dot11_BSS_type_independent, and the dwFlags member of the same structure is set to WLAN_CONNECTION_HIDDEN_NETWORK.
The dwFlags member of the structure pointed to by pConnectionParameters is set to WLAN_CONNECTION_IGNORE_PRIVACY_BIT, and either the wlanConnectionMode member of the same structure is not set to wlan_connection_mode_temporary_profile or the dot11BssType member of the same structure is set to dot11_BSS_type_independent.
ERROR_INVALID_HANDLE

The handle hClientHandle was not found in the handle table.

RPC_STATUS

Various error codes.

ERROR_ACCESS_DENIED

The caller does not have sufficient permissions.

注意:

The WlanConnect function returns immediately. To be notified when a connection is established or when no further connections will be attempted, a client must register for notifications by calling WlanRegisterNotification.

The strProfile member of the WLAN_CONNECTION_PARAMETERS structure pointed to by pConnectionParameters specifies the profile to use for connection. If this profile is an all-user profile, the WlanConnect caller must have execute access on the profile. Otherwise, the WlanConnect call will fail with return value ERROR_ACCESS_DENIED. The permissions on an all-user profile are established when the profile is created or saved using WlanSetProfile or WlanSaveTemporaryProfile.

Wireless LAN API for Windows XP SP2: You can only use WlanConnect to connect to networks on the preferred(优先的) network list. To add a network to the preferred network list, call WlanSetProfile.

云服务器PHP并发数优化建议 翼联商平台下载

Leave a Reply