WLAN_INTERFACE_INFO_LIST
这个结构体是包含着网卡接口信息的阵列。
typedef struct _WLAN_INTERFACE_INFO_LIST {
DWORDdwNumberOfItems;
DWORD dwIndex;
WLAN_INTERFACE_INFOInterfaceInfo[];
} 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, // Theinterface is not ready to operate.
wlan_interface_state_connected= 1,// The interface isconnected to a network.
wlan_interface_state_ad_hoc_network_formed = 2,// Theinterface is the first node in an ad hoc network. No peer has connected.
wlan_interface_state_disconnecting = 3, // The interfaceis disconnecting from the current network.
wlan_interface_state_disconnected= 4, // The interface isnot connected to any network.
wlan_interface_state_associating = 5, // The interface is attempting toassociate with a network.
wlan_interface_state_discovering
wlan_interface_state_authenticating= 7 // The interfaceis in the process of authenticating.
} WLAN_INTERFACE_STATE,
*PWLAN_INTERFACE_STATE;
注:WirelessLAN 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 PHYtype.
dot11_phy_type_any //Specifies any PHY type.
dot11_phy_type_fhss //Specifies a frequency-hoppingspread-spectrum (FHSS) PHY. Bluetooth devices can use FHSS or an adaptation ofFHSS.
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 orthogonalfrequency division multiplexing (OFDM) PHY type. 802.11a devices can useOFDM.
dot11_phy_type_hrdsss //Specifies a high-rate DSSS (HRDSSS) PHY type.
dot11_phy_type_erp //Specifies an extended rate PHYtype (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 ofthe range that is used to define PHY types that are developed by an independenthardware vendor (IHV).
dot11_phy_type_IHV_end //Specifiesthe start of the range that is used to define PHY types that are developed byan 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_STATEisState;
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 theconnection.
wlan_connection_mode_temporary_profile //Atemporary(temporary :临时的)profile will be used to make the connection.
wlan_connection_mode_discovery_secure //Secure discovery will be used tomake the connection.
wlan_connection_mode_discovery_unsecure //Unsecure discovery will be used to make the connection.
wlan_connection_mode_auto //A connection will bemade automatically, generally using a persistent profile. (persistent :持续不断的)
wlan_connection_mode_invalid //Not used.
}WLAN_CONNECTION_MODE,
*PWLAN_CONNECTION_MODE;
WLAN_ASSOCIATION_ATTRIBUTES
结构体,containsassociation attributes for a connection 。(我的理解就是要连接的网络的属性)
typedef struct _WLAN_ASSOCIATION_ATTRIBUTES {
DOT11_SSID dot11Ssid;
DOT11_BSS_TYPE dot11BssType;
DOT11_MAC_ADDRESSdot11Bssid;
DOT11_PHY_TYPE dot11PhyType;
ULONG uDot11PhyIndex;
WLAN_SIGNAL_QUALITY wlanSignalQuality;
USHORTusRxRate;
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 {
ULONGuSSIDLength;
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;
LPCWSTRstrProfile;
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 WINAPIWlanCloseHandle(__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 :客户端支持的WLANAPI的最高版本
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, orpReserved 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, orppInterfaceList 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 WINAPIWlanFreeMemory(
__in PVOID pMemory
);
参数:
pMemory :指向需要释放的内存
注意:
如果这块内存已经释放,那么会有一个违法接近或堆扰乱产生。
WlanRegisterNotification
函数功能:
这个函数用于给所有无线接口注册或注销通知(notifications)。
函数原型:
DWORD WINAPIWlanRegisterNotification(
__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 :要注册的通知源(notificationsources),可以是个组合值。当设置为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 :指向客户端上下文thatwill be passed to the callback function with the notification
pReserved :设置为NULL
pdwPrevNotifSource :指向先前注册的通知源
WlanGetAvailableNetworkList
函数功能:
用于检索接口上可用的网络。
函数原型:
DWORD WINAPIWlanGetAvailableNetworkList(
__in HANDLE hClientHandle,
__in constGUID* 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 | 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 | 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 constGUID* pInterfaceGuid,
__in constPWLAN_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 bypConnectionParameters is not set to one of the values specified on the WLAN_CONNECTION_PARAMETERS page. · The wlanConnectionMode member of the structure pointed to bypConnectionParameters is set to wlan_connection_mode_discovery_secure or wlan_connection_mode_discovery_unsecure, and the pDot11Ssidmember of the same structure is NULL. · The wlanConnectionMode member of the structure pointed to bypConnectionParameters is set to wlan_connection_mode_discovery_secure or wlan_connection_mode_discovery_unsecure, and the dot11BssTypemember of the same structure is set to dot11_BSS_type_any. · The wlanConnectionMode member of the structure pointed to bypConnectionParameters 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 bypConnectionParameters 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 bypConnectionParameters is set to wlan_connection_mode_invalid. · The dot11BssType member of the structure pointed to bypConnectionParameters 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 bypConnectionParameters 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 bypConnectionParameters is set to WLAN_CONNECTION_IGNORE_PRIVACY_BIT, and either thewlanConnectionMode member of the same structure is not set to wlan_connection_mode_temporary_profile or the dot11BssTypemember 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 functionreturns immediately. To be notified when a connection is established or when nofurther connections will be attempted, a client must register for notificationsby callingWlanRegisterNotification.
The strProfile memberof the WLAN_CONNECTION_PARAMETERS structure pointed to bypConnectionParameters specifiesthe profile to use for connection. If this profile is an all-user profile, theWlanConnect callermust have execute access on the profile. Otherwise, the WlanConnect callwill fail with return value ERROR_ACCESS_DENIED. The permissions on an all-userprofile 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 toconnect to networks on the preferred(优先的) network list. To add a network to thepreferred network list, call WlanSetProfile.
转自网络,原作者佚名