1 /* 2 * apConnApi.h 3 * 4 * Copyright(c) 1998 - 2009 Texas Instruments. All rights reserved. 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * * Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * * Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * * Neither the name Texas Instruments nor the names of its 18 * contributors may be used to endorse or promote products derived 19 * from this software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 */ 33 34 /** \file apConnApi.h 35 * \brief AP Connection Module API 36 * 37 * \see apConn.c 38 */ 39 40 /**************************************************************************** 41 * * 42 * MODULE: AP Connection * 43 * PURPOSE: AP Connection Module API * 44 * * 45 ****************************************************************************/ 46 47 #ifndef _AP_CONNECTION_API_H_ 48 #define _AP_CONNECTION_API_H_ 49 50 #include "paramOut.h" 51 #include "rsnApi.h" 52 #include "roamingMngrTypes.h" 53 54 /*-----------*/ 55 /* Constants */ 56 /*-----------*/ 57 58 #define AP_CONNECT_TRIGGER_IGNORED 0x0 59 60 /*--------------*/ 61 /* Enumerations */ 62 /*--------------*/ 63 64 /** \enum apConn_connRequest_e 65 * \brief Connect to AP request types 66 * 67 * \par Description 68 * Lists the possible types of connection to AP requests 69 * 70 * \sa 71 */ 72 typedef enum 73 { 74 /* 0 */ AP_CONNECT_RETAIN_CURR_AP, /**< Remain connected to the current AP without authentication. 75 * Give-up on roaming, return to current AP without performing re-connection 76 */ 77 /* 1 */ AP_CONNECT_RECONNECT_CURR_AP, /**< Reconnect to the current AP with fast authentication. 78 * Perform roaming - connect to AP, registered as current AP 79 */ 80 /* 2 */ AP_CONNECT_FAST_TO_AP, /**< Roam to AP with fast authentication. 81 * Perform roaming - re-connect to new AP via RE-Assoc, parameters attached 82 */ 83 /* 3 */ AP_CONNECT_FULL_TO_AP /**< Roam to AP with full authentication. 84 * Perform full connection - connect to new AP via Assoc, parameters attached 85 */ 86 87 } apConn_connRequest_e; 88 89 /** \enum apConn_roamingTrigger_e 90 * \brief Roaming Triggers Types 91 * 92 * \par Description 93 * Lists the possible types of roaming triggers 94 * 95 * \sa 96 */ 97 typedef enum 98 { 99 /* 0 */ ROAMING_TRIGGER_NONE, /**< No roaming trigger */ 100 101 /* 1 */ ROAMING_TRIGGER_LOW_QUALITY_FOR_BG_SCAN, /**< Low quality trigger for background scan */ 102 /* 2 */ ROAMING_TRIGGER_NORMAL_QUALITY_FOR_BG_SCAN, /**< Normal quality trigger for background scan */ 103 104 /* 3 */ ROAMING_TRIGGER_LOW_TX_RATE, /**< Low TX rate */ 105 /* 4 */ ROAMING_TRIGGER_LOW_SNR, /**< Low SNR rate */ 106 /* 5 */ ROAMING_TRIGGER_LOW_QUALITY, /**< Low quality for roaming */ 107 108 /* 6 */ ROAMING_TRIGGER_MAX_TX_RETRIES, /**< Maximum TX retries */ 109 /* 7 */ ROAMING_TRIGGER_BSS_LOSS, /**< Missed beacon and no ACK on Unicast probe requests */ 110 /* 8 */ ROAMING_TRIGGER_SWITCH_CHANNEL, /**< Radar detection */ 111 112 /* 9 */ ROAMING_TRIGGER_AP_DISCONNECT, /**< AP disconnect (de-authenticate or disassociate) */ 113 /* 10 */ ROAMING_TRIGGER_SECURITY_ATTACK, /**< Security attack */ 114 115 /* 11 */ ROAMING_TRIGGER_LAST /**< Maximum roaming trigger - must be last!!! */ 116 117 } apConn_roamingTrigger_e; 118 119 /** \enum apConn_connStatus_e 120 * \brief Connection Status Types 121 * 122 * \par Description 123 * Lists the possible types of connection status 124 * 125 * \sa 126 */ 127 typedef enum 128 { 129 /* 0 */ CONN_STATUS_CONNECTED, /**< */ 130 /* 1 */ CONN_STATUS_NOT_CONNECTED, /**< */ 131 /* 2 */ CONN_STATUS_HANDOVER_FAILURE, /**< */ 132 /* 3 */ CONN_STATUS_HANDOVER_SUCCESS, /**< */ 133 134 /* 4 */ CONN_STATUS_LAST /**< Maximum connection status - must be last!!! */ 135 136 } apConn_connStatus_e; 137 138 /** \enum REG_DOMAIN_CAPABILITY 139 * \brief Regulatory Domain Capability 140 * 141 * \par Description 142 * 143 * \sa 144 */ 145 typedef enum 146 { 147 /* 0 */ REG_DOMAIN_FIXED, /**< */ 148 /* 1 */ REG_DOMAIN_80211D, /**< */ 149 /* 2 */ REG_DOMAIN_80211H /**< */ 150 151 } REG_DOMAIN_CAPABILITY; 152 153 154 /*----------*/ 155 /* Typedefs */ 156 /*----------*/ 157 /** 158 * \brief Roaming Manager callback type 159 * 160 * \param hRoamingMngr - Handle to Roaming Manager Object 161 * \param pData - Pointer to Data 162 * \return void 163 * 164 * \par Description 165 * 166 * 167 * \sa 168 */ 169 typedef TI_STATUS (*apConn_roamMngrCallb_t) (TI_HANDLE hRoamingMngr, void *pData); 170 171 typedef TI_STATUS (*apConn_roamMngrEventCallb_t) (TI_HANDLE hRoamingMngr, void *pData, TI_UINT16 reasonCode); 172 173 /*------------*/ 174 /* Structures */ 175 /*------------*/ 176 177 /** \struct apConn_staCapabilities_t 178 * \brief Station Capabilities 179 * 180 * \par Description 181 * Holds a Station Capabilities. 182 * Used by the roaming manager when the capabilities of a new AP 183 * are transferred to the AP connection module 184 * 185 * \sa 186 */ 187 typedef struct _apConn_staCapabilities_t 188 { 189 OS_802_11_AUTHENTICATION_MODE authMode; /**< Authentication Mode: None, Shared, AutoSwitch, WPA, WPAPSK, WPANone, WPA2, WPA2PSK */ 190 OS_802_11_ENCRYPTION_TYPES encryptionType; /**< Encription Type: None, WEP, TKIP, AES */ 191 OS_802_11_NETWORK_TYPE networkType; /**< Network Type: 2.4G, 5G or Dual */ 192 OS_802_11_RATES_EX rateMask; /**< An array of 16 octets. Each octet contains a preferred data rate in units of 0.5 Mbps */ 193 TI_BOOL XCCEnabled; /**< TI_TRUE - XCC enabled, TI_FALSE - XCC disabled */ 194 TI_BOOL qosEnabled; /**< TI_TRUE - QOS enabled, TI_FALSE - QOS disabled */ 195 REG_DOMAIN_CAPABILITY regDomain; /**< Fixed, 802.11D, 802.11H */ 196 197 } apConn_staCapabilities_t; 198 199 /** \struct apConn_connStatus_t 200 * \brief Connection Status 201 * 202 * \par Description 203 * Holds the Report Status of the Connection and a buffer for the case 204 * of vendor specific IEs in Association Response Packet 205 * 206 * \sa 207 */ 208 typedef struct _apConn_connStatus_t 209 { 210 apConn_connStatus_e status; /** Reported status of the connection */ 211 TI_UINT32 dataBufLength; /** (Optional) length of attached buffer */ 212 TI_CHAR *dataBuf; /** (Optional) attached buffer - can be used in case of vendor specific IEs in Association Response Packet */ 213 } apConn_connStatus_t; 214 215 /** \struct apConn_connRequest_t 216 * \brief Connection Request 217 * 218 * \par Description 219 * Holds the Type of Request needed to establish the Connection, 220 * and a buffer for the case of vendor specific IEs in Association Request Packet 221 * 222 * \sa 223 */ 224 typedef struct _apConn_connRequest_t 225 { 226 apConn_connRequest_e requestType; /** Type of Request to establish connection */ 227 TI_UINT32 dataBufLength; /** (Optional) length of attached buffer */ 228 TI_CHAR *dataBuf; /** (Optional) attached buffer - can be used in case of vendor specific IEs in Association Request Packet */ 229 } apConn_connRequest_t; 230 231 232 typedef enum 233 { 234 ReAssoc = 0 235 /* The methods below are for 11r support only 236 FT_initial_ReAssoc, 237 FT_over_the_air, 238 FT_over_DS */ 239 } ETransitionMethod; 240 241 242 typedef struct _TargetAP_t 243 { 244 apConn_connRequest_t connRequest; 245 ETransitionMethod transitionMethod; 246 bssEntry_t newAP; 247 } TargetAp_t; 248 249 /*---------------------------*/ 250 /* External data definitions */ 251 /*---------------------------*/ 252 253 /*--------------------------------*/ 254 /* External functions definitions */ 255 /*--------------------------------*/ 256 257 /*---------------------*/ 258 /* Function prototypes */ 259 /*---------------------*/ 260 /** 261 * \brief Configure Roaming Thresholds 262 * 263 * \param hAPConnection - Handle to AP Connection module object 264 * \param pParam - Pointer to input Roaming event thresholds to configure 265 * \return TI_OK on success 266 * 267 * \par Description 268 * This function is used for configuring Roaming Thesholds: 269 * it is called by Roaming Manager when the application sets roaming thresholds 270 * 271 * \sa 272 */ 273 TI_STATUS apConn_setRoamThresholds(TI_HANDLE hAPConnection, roamingMngrThresholdsConfig_t *pParam); 274 /** 275 * \brief Get Roaming Thresholds configuration 276 * 277 * \param hAPConnection - Handle to AP Connection module object 278 * \param pParam - Pointer to output Roaming event thresholds configuration to get 279 * \return TI_OK on success 280 * 281 * \par Description 282 * This function is used for getting current Roaming Thesholds configuration: 283 * it is called by Roaming Manager when the application gets roaming thresholds 284 * 285 * \sa 286 */ 287 TI_STATUS apConn_getRoamThresholds(TI_HANDLE hAPConnection, roamingMngrThresholdsConfig_t *pParam); 288 /** 289 * \brief Register Roaming Manager Callbacks 290 * 291 * \param hAPConnection - Handle to AP Connection module object 292 * \param roamEventCallb - Pointer to input Roaming event callback 293 * \param reportStatusCallb - Pointer to input Connection status callback 294 * \param returnNeighborApsCallb - Pointer to input Neighbor AP callback 295 * \return TI_OK on success 296 * 297 * \par Description 298 * This function stores the roaming manager methods in the internal database of the AP connection module 299 * 300 * \sa 301 */ 302 TI_STATUS apConn_registerRoamMngrCallb(TI_HANDLE hAPConnection, 303 apConn_roamMngrEventCallb_t roamEventCallb, 304 apConn_roamMngrCallb_t reportStatusCallb, 305 apConn_roamMngrCallb_t returnNeighborApsCallb); 306 /** 307 * \brief Un-Register Roaming Manager Callbacks 308 * 309 * \param hAPConnection - Handle to AP Connection module object 310 * \return TI_OK on success 311 * 312 * \par Description 313 * This function erases the roaming manager methods from the internal database of the AP connection module. 314 * From the moment this function was called, any roaming event would cause disconnect. 315 * 316 * \sa 317 */ 318 TI_STATUS apConn_unregisterRoamMngrCallb(TI_HANDLE hAPConnection); 319 /** 320 * \brief AP-Connection disconnect 321 * 322 * \param hAPConnection - Handle to AP Connection module object 323 * \return TI_OK on success 324 * 325 * \par Description 326 * Roaming Manager calls this function when it fails to find a candidate 327 * for roaming and connection with the current AP is not possible 328 * 329 * \sa 330 */ 331 TI_STATUS apConn_disconnect(TI_HANDLE hAPConnection); 332 /** 333 * \brief Get Station Capabilities 334 * 335 * \param hAPConnection - Handle to AP Connection module object 336 * \param ie_list - Pointer to output list of STA Capabilities 337 * \return TI_OK on success 338 * 339 * \par Description 340 * Roaming Manager calls this function during selection of new candidate for roaming. 341 * The local STA capabilities (IEs) of quality and privacy, which are required for 342 * evaluating AP sites suitable for roaming, are returned. 343 * 344 * \sa 345 */ 346 TI_STATUS apConn_getStaCapabilities(TI_HANDLE hAPConnection, 347 apConn_staCapabilities_t *ie_list); 348 349 /** 350 * \brief Connect to New AP 351 * 352 * \param hAPConnection - Handle to AP Connection module object 353 * \param newAP - Pointer to input parameters list of AP candidates for roaming 354 * \param request - The Connection Request Type: Connect to new AP, current AP (retain to current AP or re-connect) 355 * \param reNegotiateTspec - Set to TRUE before handover if requested by roaming manager 356 * \return TI_OK on success 357 * 358 * \par Description 359 * Roaming Manager calls this function when it has completed the process of selection a new AP candidate for roaming. 360 * In addition, the Roaming manager informs the AP Connection module whether this is new AP or the current one, 361 * and whether to perform full roaming procedure or just to retain to current AP. 362 * Precondition: ready for roaming 363 * 364 * \Note 365 * Calling this function with the parameter RETAIN_CURR_AP terminates the roaming process at the stage when the driver 366 * resources are occupied for roaming, but the connection with the current AP is still valid 367 * \sa 368 */ 369 TI_STATUS apConn_connectToAP(TI_HANDLE hAPConnection, 370 bssEntry_t *newAP, 371 apConn_connRequest_t *request, 372 TI_BOOL reNegotiateTspec); 373 374 /** 375 * \brief Connect to New AP 376 * 377 * \param hAPConnection - Handle to AP Connection module object 378 * \return Pointer to BSS entry parameters if successful, NULL otherwise 379 * 380 * \par Description 381 * Roaming Manager calls this function in order to evaluate the quality of new 382 * AP candidates for roaming against the quality of current AP. 383 * The function returns parameters of current AP. 384 * 385 * \sa 386 */ 387 bssEntry_t *apConn_getBSSParams(TI_HANDLE hAPConnection); 388 /** 389 * \brief Check if Site is Banned 390 * 391 * \param hAPConnection - Handle to AP Connection module object 392 * \param bssid - Pointer to input BSSID (MAC Address) of checked site 393 * \return True if the site is banned and Falde otherwise 394 * 395 * \par Description 396 * Roaming Manager calls this function during selection of new candidate for roaming. 397 * Only APs which are not marked as banned are allowed to be selected. 398 * 399 * \sa 400 */ 401 TI_BOOL apConn_isSiteBanned(TI_HANDLE hAPConnection, TMacAddr * bssid); 402 /** 403 * \brief Get AP Pre-Authentication Status 404 * 405 * \param hAPConnection - Handle to AP Connection module object 406 * \param givenAp - Pointer to input BSSID (MAC Address) of checked AP 407 * \return True if AP is pre-authenticated, False otherwise 408 * 409 * \par Description 410 * Roaming Manager calls this function during selection of new candidate for roaming. 411 * Among all candidate APs of acceptable quality that are not neighbor APs, 412 * pre-authenticated APs are preferred. 413 * The function returns the status of the AP, whether or not it is pre-authenticated. 414 * 415 * 416 * \sa 417 */ 418 TI_BOOL apConn_getPreAuthAPStatus(TI_HANDLE hAPConnection, TMacAddr *givenAp); 419 /** 420 * \brief Update Pre-Authentication APs List 421 * 422 * \param hAPConnection - Handle to AP Connection module object 423 * \param listAPs - Pointer to List of APs to pre-authenticate 424 * \return TI_OK if the parameter was set successfully, TI_NOK otherwise 425 * 426 * \par Description 427 * Roaming Manager calls this function periodically in order to update the list 428 * of pre-authenticated APs. The list is managed by WLAN driver and required 429 * by Roaming Manager during selection of roaming candidate process. 430 * 431 * \sa 432 */ 433 TI_STATUS apConn_preAuthenticate(TI_HANDLE hAPConnection, bssList_t *listAPs); 434 /** 435 * \brief Prepare to Roaming 436 * 437 * \param hAPConnection - Handle to AP Connection module object 438 * \param reason - The reason for Roaming trigger 439 * \return TI_OK if the parameter was set successfully, TI_NOK otherwise 440 * 441 * \par Description 442 * This function indicate the driver that Roaming process is starting. 443 * The roaming manager calls this function when roaming event 444 * is received and Roaming Manager wishes to start the roaming process, thus wants to 445 * prevent scan and measurement in the system. 446 * The function will return TI_OK if the allocation is performed, PEND if the allocation is started, 447 * TI_NOK in case the allocation is not possible. In case of successful allocation, 448 * Roaming Manager will be informed via callback about the end of the allocation. 449 * The roaming manager can initiate an immediate scan or call to connect to an AP only 450 * after prepare-to-roam is complete 451 * 452 * \sa 453 */ 454 455 TI_STATUS apConn_prepareToRoaming(TI_HANDLE hAPConnection, apConn_roamingTrigger_e reason); 456 457 #endif /* _AP_CONNECTION_API_H_*/ 458 459