Home | History | Annotate | Download | only in Connection_Managment 
      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