1 /* 2 * apConnApi.h 3 * 4 * Copyright(c) 1998 - 2010 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 /* 11 */ ROAMING_TRIGGER_TSPEC_REJECTED, /**< TSPEC Rejected */ 115 116 /* 12 */ ROAMING_TRIGGER_LAST /**< Maximum roaming trigger - must be last!!! */ 117 118 } apConn_roamingTrigger_e; 119 120 /** \enum apConn_connStatus_e 121 * \brief Connection Status Types 122 * 123 * \par Description 124 * Lists the possible types of connection status 125 * 126 * \sa 127 */ 128 typedef enum 129 { 130 /* 0 */ CONN_STATUS_CONNECTED, /**< */ 131 /* 1 */ CONN_STATUS_NOT_CONNECTED, /**< */ 132 /* 2 */ CONN_STATUS_HANDOVER_FAILURE, /**< */ 133 /* 3 */ CONN_STATUS_HANDOVER_SUCCESS, /**< */ 134 135 /* 4 */ CONN_STATUS_LAST /**< Maximum connection status - must be last!!! */ 136 137 } apConn_connStatus_e; 138 139 /** \enum REG_DOMAIN_CAPABILITY 140 * \brief Regulatory Domain Capability 141 * 142 * \par Description 143 * 144 * \sa 145 */ 146 typedef enum 147 { 148 /* 0 */ REG_DOMAIN_FIXED, /**< */ 149 /* 1 */ REG_DOMAIN_80211D, /**< */ 150 /* 2 */ REG_DOMAIN_80211H /**< */ 151 152 } REG_DOMAIN_CAPABILITY; 153 154 155 /*----------*/ 156 /* Typedefs */ 157 /*----------*/ 158 /** 159 * \brief Roaming Manager callback type 160 * 161 * \param hRoamingMngr - Handle to Roaming Manager Object 162 * \param pData - Pointer to Data 163 * \return void 164 * 165 * \par Description 166 * 167 * 168 * \sa 169 */ 170 typedef TI_STATUS (*apConn_roamMngrCallb_t) (TI_HANDLE hRoamingMngr, void *pData); 171 172 typedef TI_STATUS (*apConn_roamMngrEventCallb_t) (TI_HANDLE hRoamingMngr, void *pData, TI_UINT16 reasonCode); 173 174 /*------------*/ 175 /* Structures */ 176 /*------------*/ 177 178 /** \struct apConn_staCapabilities_t 179 * \brief Station Capabilities 180 * 181 * \par Description 182 * Holds a Station Capabilities. 183 * Used by the roaming manager when the capabilities of a new AP 184 * are transferred to the AP connection module 185 * 186 * \sa 187 */ 188 typedef struct _apConn_staCapabilities_t 189 { 190 OS_802_11_AUTHENTICATION_MODE authMode; /**< Authentication Mode: None, Shared, AutoSwitch, WPA, WPAPSK, WPANone, WPA2, WPA2PSK */ 191 OS_802_11_ENCRYPTION_TYPES encryptionType; /**< Encription Type: None, WEP, TKIP, AES */ 192 OS_802_11_NETWORK_TYPE networkType; /**< Network Type: 2.4G, 5G or Dual */ 193 OS_802_11_RATES_EX rateMask; /**< An array of 16 octets. Each octet contains a preferred data rate in units of 0.5 Mbps */ 194 TI_BOOL XCCEnabled; /**< TI_TRUE - XCC enabled, TI_FALSE - XCC disabled */ 195 TI_BOOL qosEnabled; /**< TI_TRUE - QOS enabled, TI_FALSE - QOS disabled */ 196 REG_DOMAIN_CAPABILITY regDomain; /**< Fixed, 802.11D, 802.11H */ 197 198 } apConn_staCapabilities_t; 199 200 /** \struct apConn_connStatus_t 201 * \brief Connection Status 202 * 203 * \par Description 204 * Holds the Report Status of the Connection and a buffer for the case 205 * of vendor specific IEs in Association Response Packet 206 * 207 * \sa 208 */ 209 typedef struct _apConn_connStatus_t 210 { 211 apConn_connStatus_e status; /** Reported status of the connection */ 212 TI_UINT32 dataBufLength; /** (Optional) length of attached buffer */ 213 TI_CHAR *dataBuf; /** (Optional) attached buffer - can be used in case of vendor specific IEs in Association Response Packet */ 214 } apConn_connStatus_t; 215 216 /** \struct apConn_connRequest_t 217 * \brief Connection Request 218 * 219 * \par Description 220 * Holds the Type of Request needed to establish the Connection, 221 * and a buffer for the case of vendor specific IEs in Association Request Packet 222 * 223 * \sa 224 */ 225 typedef struct _apConn_connRequest_t 226 { 227 apConn_connRequest_e requestType; /** Type of Request to establish connection */ 228 TI_UINT32 dataBufLength; /** (Optional) length of attached buffer */ 229 TI_CHAR *dataBuf; /** (Optional) attached buffer - can be used in case of vendor specific IEs in Association Request Packet */ 230 } apConn_connRequest_t; 231 232 233 typedef enum 234 { 235 ReAssoc = 0 236 /* The methods below are for 11r support only 237 FT_initial_ReAssoc, 238 FT_over_the_air, 239 FT_over_DS */ 240 } ETransitionMethod; 241 242 243 typedef struct _TargetAP_t 244 { 245 apConn_connRequest_t connRequest; 246 ETransitionMethod transitionMethod; 247 bssEntry_t newAP; 248 } TargetAp_t; 249 250 /*---------------------------*/ 251 /* External data definitions */ 252 /*---------------------------*/ 253 254 /*--------------------------------*/ 255 /* External functions definitions */ 256 /*--------------------------------*/ 257 258 /*---------------------*/ 259 /* Function prototypes */ 260 /*---------------------*/ 261 /** 262 * \brief Configure Roaming Thresholds 263 * 264 * \param hAPConnection - Handle to AP Connection module object 265 * \param pParam - Pointer to input Roaming event thresholds to configure 266 * \return TI_OK on success 267 * 268 * \par Description 269 * This function is used for configuring Roaming Thesholds: 270 * it is called by Roaming Manager when the application sets roaming thresholds 271 * 272 * \sa 273 */ 274 TI_STATUS apConn_setRoamThresholds(TI_HANDLE hAPConnection, roamingMngrThresholdsConfig_t *pParam); 275 /** 276 * \brief Get Roaming Thresholds configuration 277 * 278 * \param hAPConnection - Handle to AP Connection module object 279 * \param pParam - Pointer to output Roaming event thresholds configuration to get 280 * \return TI_OK on success 281 * 282 * \par Description 283 * This function is used for getting current Roaming Thesholds configuration: 284 * it is called by Roaming Manager when the application gets roaming thresholds 285 * 286 * \sa 287 */ 288 TI_STATUS apConn_getRoamThresholds(TI_HANDLE hAPConnection, roamingMngrThresholdsConfig_t *pParam); 289 /** 290 * \brief Register Roaming Manager Callbacks 291 * 292 * \param hAPConnection - Handle to AP Connection module object 293 * \param roamEventCallb - Pointer to input Roaming event callback 294 * \param reportStatusCallb - Pointer to input Connection status callback 295 * \param returnNeighborApsCallb - Pointer to input Neighbor AP callback 296 * \return TI_OK on success 297 * 298 * \par Description 299 * This function stores the roaming manager methods in the internal database of the AP connection module 300 * 301 * \sa 302 */ 303 TI_STATUS apConn_registerRoamMngrCallb(TI_HANDLE hAPConnection, 304 apConn_roamMngrEventCallb_t roamEventCallb, 305 apConn_roamMngrCallb_t reportStatusCallb, 306 apConn_roamMngrCallb_t returnNeighborApsCallb); 307 /** 308 * \brief Un-Register Roaming Manager Callbacks 309 * 310 * \param hAPConnection - Handle to AP Connection module object 311 * \return TI_OK on success 312 * 313 * \par Description 314 * This function erases the roaming manager methods from the internal database of the AP connection module. 315 * From the moment this function was called, any roaming event would cause disconnect. 316 * 317 * \sa 318 */ 319 TI_STATUS apConn_unregisterRoamMngrCallb(TI_HANDLE hAPConnection); 320 /** 321 * \brief AP-Connection disconnect 322 * 323 * \param hAPConnection - Handle to AP Connection module object 324 * \return TI_OK on success 325 * 326 * \par Description 327 * Roaming Manager calls this function when it fails to find a candidate 328 * for roaming and connection with the current AP is not possible 329 * 330 * \sa 331 */ 332 TI_STATUS apConn_disconnect(TI_HANDLE hAPConnection); 333 /** 334 * \brief Get Station Capabilities 335 * 336 * \param hAPConnection - Handle to AP Connection module object 337 * \param ie_list - Pointer to output list of STA Capabilities 338 * \return TI_OK on success 339 * 340 * \par Description 341 * Roaming Manager calls this function during selection of new candidate for roaming. 342 * The local STA capabilities (IEs) of quality and privacy, which are required for 343 * evaluating AP sites suitable for roaming, are returned. 344 * 345 * \sa 346 */ 347 TI_STATUS apConn_getStaCapabilities(TI_HANDLE hAPConnection, 348 apConn_staCapabilities_t *ie_list); 349 350 /** 351 * \brief Connect to New AP 352 * 353 * \param hAPConnection - Handle to AP Connection module object 354 * \param newAP - Pointer to input parameters list of AP candidates for roaming 355 * \param request - The Connection Request Type: Connect to new AP, current AP (retain to current AP or re-connect) 356 * \param reNegotiateTspec - Set to TRUE before handover if requested by roaming manager 357 * \return TI_OK on success 358 * 359 * \par Description 360 * Roaming Manager calls this function when it has completed the process of selection a new AP candidate for roaming. 361 * In addition, the Roaming manager informs the AP Connection module whether this is new AP or the current one, 362 * and whether to perform full roaming procedure or just to retain to current AP. 363 * Precondition: ready for roaming 364 * 365 * \Note 366 * Calling this function with the parameter RETAIN_CURR_AP terminates the roaming process at the stage when the driver 367 * resources are occupied for roaming, but the connection with the current AP is still valid 368 * \sa 369 */ 370 TI_STATUS apConn_connectToAP(TI_HANDLE hAPConnection, 371 bssEntry_t *newAP, 372 apConn_connRequest_t *request, 373 TI_BOOL reNegotiateTspec); 374 375 /** 376 * \brief Connect to New AP 377 * 378 * \param hAPConnection - Handle to AP Connection module object 379 * \return Pointer to BSS entry parameters if successful, NULL otherwise 380 * 381 * \par Description 382 * Roaming Manager calls this function in order to evaluate the quality of new 383 * AP candidates for roaming against the quality of current AP. 384 * The function returns parameters of current AP. 385 * 386 * \sa 387 */ 388 bssEntry_t *apConn_getBSSParams(TI_HANDLE hAPConnection); 389 /** 390 * \brief Check if Site is Banned 391 * 392 * \param hAPConnection - Handle to AP Connection module object 393 * \param bssid - Pointer to input BSSID (MAC Address) of checked site 394 * \return True if the site is banned and Falde otherwise 395 * 396 * \par Description 397 * Roaming Manager calls this function during selection of new candidate for roaming. 398 * Only APs which are not marked as banned are allowed to be selected. 399 * 400 * \sa 401 */ 402 TI_BOOL apConn_isSiteBanned(TI_HANDLE hAPConnection, TMacAddr * bssid); 403 /** 404 * \brief Get AP Pre-Authentication Status 405 * 406 * \param hAPConnection - Handle to AP Connection module object 407 * \param givenAp - Pointer to input BSSID (MAC Address) of checked AP 408 * \return True if AP is pre-authenticated, False otherwise 409 * 410 * \par Description 411 * Roaming Manager calls this function during selection of new candidate for roaming. 412 * Among all candidate APs of acceptable quality that are not neighbor APs, 413 * pre-authenticated APs are preferred. 414 * The function returns the status of the AP, whether or not it is pre-authenticated. 415 * 416 * 417 * \sa 418 */ 419 TI_BOOL apConn_getPreAuthAPStatus(TI_HANDLE hAPConnection, TMacAddr *givenAp); 420 /** 421 * \brief Update Pre-Authentication APs List 422 * 423 * \param hAPConnection - Handle to AP Connection module object 424 * \param listAPs - Pointer to List of APs to pre-authenticate 425 * \return TI_OK if the parameter was set successfully, TI_NOK otherwise 426 * 427 * \par Description 428 * Roaming Manager calls this function periodically in order to update the list 429 * of pre-authenticated APs. The list is managed by WLAN driver and required 430 * by Roaming Manager during selection of roaming candidate process. 431 * 432 * \sa 433 */ 434 TI_STATUS apConn_preAuthenticate(TI_HANDLE hAPConnection, bssList_t *listAPs); 435 /** 436 * \brief Prepare to Roaming 437 * 438 * \param hAPConnection - Handle to AP Connection module object 439 * \param reason - The reason for Roaming trigger 440 * \return TI_OK if the parameter was set successfully, TI_NOK otherwise 441 * 442 * \par Description 443 * This function indicate the driver that Roaming process is starting. 444 * The roaming manager calls this function when roaming event 445 * is received and Roaming Manager wishes to start the roaming process, thus wants to 446 * prevent scan and measurement in the system. 447 * The function will return TI_OK if the allocation is performed, PEND if the allocation is started, 448 * TI_NOK in case the allocation is not possible. In case of successful allocation, 449 * Roaming Manager will be informed via callback about the end of the allocation. 450 * The roaming manager can initiate an immediate scan or call to connect to an AP only 451 * after prepare-to-roam is complete 452 * 453 * \sa 454 */ 455 456 TI_STATUS apConn_prepareToRoaming(TI_HANDLE hAPConnection, apConn_roamingTrigger_e reason); 457 458 TI_STATUS apConn_getAssocRoamingTrigger(TI_HANDLE hAPConnection, apConn_roamingTrigger_e *asssocRoamingTrigger); 459 460 #endif /* _AP_CONNECTION_API_H_*/ 461 462