pa_wifi.h

    1 // -------------------------------------------------------------------------------------------------
    2 /**
    3  *  WiFi Client Platform Adapter
    4  *
    5  *  Copyright (C) Sierra Wireless Inc.
    6  *
    7  */
    8 // -------------------------------------------------------------------------------------------------
    9 #ifndef PA_WIFI_H
   10 #define PA_WIFI_H
   11 
   12 #include "legato.h"
   13 #include "interfaces.h"
   14 
   15 //--------------------------------------------------------------------------------------------------
   16 /**
   17  * AccessPoint structure.
   18  */
   19 //--------------------------------------------------------------------------------------------------
   20 typedef struct
   21 {
   22     int16_t  signalStrength;                        ///< LE_WIFICLIENT_NO_SIGNAL_STRENGTH means
   23                                                     ///< value was not found.
   24     uint8_t  ssidLength;                            ///< The number of bytes in the ssidBytes.
   25     uint8_t  ssidBytes[LE_WIFIDEFS_MAX_SSID_BYTES]; ///< Contains ssidLength number of bytes.
   26     char     bssid[LE_WIFIDEFS_MAX_BSSID_BYTES];    ///< Contains the bssid.
   27 } pa_wifiClient_AccessPoint_t;
   28 
   29 //--------------------------------------------------------------------------------------------------
   30 /**
   31  * Event handler for PA WiFi access point changes.
   32  *
   33  * Handles the PA WiFi events.
   34  */
   35 //--------------------------------------------------------------------------------------------------
   36 typedef void (*pa_wifiClient_NewEventHandlerFunc_t)
   37 (
   38     le_wifiClient_Event_t event,
   39         ///< [IN]
   40         ///< WiFi event to process
   41     void *contextPtr
   42         ///< [IN]
   43         ///< Associated WiFi event context
   44 );
   45 
   46 //--------------------------------------------------------------------------------------------------
   47 /**
   48  * Add handler function for PA EVENT 'le_wifiClient_Event_t'
   49  *
   50  * This event provides information on PA WiFi Client event changes.
   51  */
   52 //--------------------------------------------------------------------------------------------------
   53 LE_SHARED le_result_t pa_wifiClient_AddEventHandler
   54 (
   55     pa_wifiClient_NewEventHandlerFunc_t handlerPtr,
   56         ///< [IN]
   57         ///< Event handler function pointer.
   58     void *contextPtr
   59         ///< [IN]
   60         ///< Associated event context.
   61 );
   62 
   63 //--------------------------------------------------------------------------------------------------
   64 /**
   65  * This function must be called to initialize the PA WiFi Module.
   66  *
   67  * @return LE_OK     The function succeeded.
   68  */
   69 //--------------------------------------------------------------------------------------------------
   70 LE_SHARED le_result_t pa_wifiClient_Init
   71 (
   72     void
   73 );
   74 
   75 //--------------------------------------------------------------------------------------------------
   76 /**
   77  * This function must be called to release the PA WiFi Module.
   78  *
   79  * @return LE_OK     The function succeeded.
   80  */
   81 //--------------------------------------------------------------------------------------------------
   82 LE_SHARED le_result_t pa_wifiClient_Release
   83 (
   84     void
   85 );
   86 
   87 //--------------------------------------------------------------------------------------------------
   88 /**
   89  * This function will start a scan and returns when it is done.
   90  * It should NOT return until the scan is done.
   91  * Results are read via pa_wifiClient_GetScanResult.
   92  * When the reading is done pa_wifiClient_ScanDone MUST be called.
   93  *
   94  * @return LE_FAULT  The function failed.
   95  * @return LE_BUSY   The function is already ongoing.
   96  * @return LE_OK     The function succeeded.
   97  */
   98 //--------------------------------------------------------------------------------------------------
   99 LE_SHARED le_result_t pa_wifiClient_Scan
  100 (
  101     void
  102 );
  103 
  104 //--------------------------------------------------------------------------------------------------
  105 /**
  106  * This function is used to find out if a scan is currently running.
  107  *
  108  * @return TRUE  Scan is running.
  109  * @return FALSE Scan is not running
  110  */
  111 //--------------------------------------------------------------------------------------------------
  112 LE_SHARED bool pa_wifiClient_IsScanRunning
  113 (
  114     void
  115 );
  116 
  117 //--------------------------------------------------------------------------------------------------
  118 /**
  119  * This function can be called after pa_wifi_Scan.
  120  * When the reading is done, it no longer returns LE_OK
  121  * pa_wifiClient_ScanDone MUST be called.
  122  *
  123  * @return LE_NOT_FOUND  There is no more AP found.
  124  * @return LE_OK     The function succeeded.
  125  * @return LE_FAULT  The function failed.
  126  */
  127 //--------------------------------------------------------------------------------------------------
  128 LE_SHARED le_result_t pa_wifiClient_GetScanResult
  129 (
  130     pa_wifiClient_AccessPoint_t *accessPointPtr
  131     ///< [IN][OUT]
  132     ///< Structure provided by calling function.
  133     ///< Results filled out if result was LE_OK.
  134 );
  135 
  136 //--------------------------------------------------------------------------------------------------
  137 /**
  138  * This function must be called after the pa_wifiClient_Scan() has been done.
  139  * It signals that the scan results are no longer needed and frees some internal resourses.
  140  *
  141  * @return LE_OK     The function succeeded.
  142  * @return LE_FAULT  The scan failed
  143  */
  144 //--------------------------------------------------------------------------------------------------
  145 LE_SHARED le_result_t pa_wifiClient_ScanDone
  146 (
  147     void
  148 );
  149 
  150 //--------------------------------------------------------------------------------------------------
  151 /**
  152  * This function connects a wifiClient.
  153  *
  154  * @return LE_FAULT  The function failed.
  155  * @return LE_OK     The function succeeded.
  156  */
  157 //--------------------------------------------------------------------------------------------------
  158 LE_SHARED le_result_t pa_wifiClient_Connect
  159 (
  160     uint8_t ssidBytes[LE_WIFIDEFS_MAX_SSID_BYTES],
  161         /// [IN]
  162         ///< Contains ssidLength number of bytes
  163     uint8_t ssidLength
  164         /// [IN]
  165         ///< The number of bytes in the ssidBytes
  166 );
  167 
  168 //--------------------------------------------------------------------------------------------------
  169 /**
  170  * This function disconnects a wifiClient.
  171  *
  172  * @return LE_FAULT  The function failed.
  173  * @return LE_OK     The function succeeded.
  174  */
  175 //--------------------------------------------------------------------------------------------------
  176 LE_SHARED le_result_t pa_wifiClient_Disconnect
  177 (
  178     void
  179 );
  180 
  181 //--------------------------------------------------------------------------------------------------
  182 /**
  183  * Set the username and password (WPA-Entreprise).
  184  *
  185  * @return LE_FAULT  The function failed.
  186  * @return LE_OK     The function succeeded.
  187  */
  188 //--------------------------------------------------------------------------------------------------
  189 LE_SHARED le_result_t pa_wifiClient_SetUserCredentials
  190 (
  191     const char *usernamePtr,
  192         ///< [IN]
  193         ///< Username used for authentication
  194     const char *passwordPtr
  195         ///< [IN]
  196         ///< Password used for authentication
  197 );
  198 
  199 //--------------------------------------------------------------------------------------------------
  200 /**
  201  * Set the PassPhrase used to create PSK (WPA-Personal).
  202  * @see  pa_wifiClient_SetPreSharedKey
  203  *
  204  * @return LE_FAULT  The function failed.
  205  * @return LE_OK     The function succeeded.
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 LE_SHARED le_result_t pa_wifiClient_SetPassphrase
  209 (
  210     const char *passphrasePtr
  211         ///< [IN]
  212         ///< Passphrase used for authentication
  213 );
  214 
  215 //--------------------------------------------------------------------------------------------------
  216 /**
  217  * Set the PreSharedKey (WPA-Personal)
  218  * @see  pa_wifiClient_SetPassPhrase
  219  *
  220  * @return LE_FAULT  The function failed.
  221  * @return LE_OK     The function succeeded.
  222  */
  223 //--------------------------------------------------------------------------------------------------
  224 LE_SHARED le_result_t pa_wifiClient_SetPreSharedKey
  225 (
  226     const char *preSharedKeyPtr
  227         ///< [IN]
  228         ///< Pre-shared key (PSK) used for authentication
  229 );
  230 
  231 //--------------------------------------------------------------------------------------------------
  232 /**
  233  * This function specifies whether the target Access Point is hiding its presence from clients or
  234  * not. When an Access Point is hidden, it cannot be discovered by a scan process.
  235  *
  236  * @note By default, this attribute is not set which means that the client is unable to connect to
  237  * a hidden access point. When enabled, the client will be able to connect to the access point
  238  * whether it is hidden or not.
  239  */
  240 //--------------------------------------------------------------------------------------------------
  241 LE_SHARED void pa_wifiClient_SetHiddenNetworkAttribute
  242 (
  243     bool hidden
  244         ///< [IN]
  245         ///< If TRUE, the WIFI client will be able to connect to a hidden access point.
  246 );
  247 
  248 //--------------------------------------------------------------------------------------------------
  249 /**
  250  * Set the WEP key (WEP)
  251  *
  252  * @return LE_FAULT  The function failed.
  253  * @return LE_OK     The function succeeded.
  254  */
  255 //--------------------------------------------------------------------------------------------------
  256 LE_SHARED le_result_t pa_wifiClient_SetWepKey
  257 (
  258     const char *wepKeyPtr
  259         ///< [IN]
  260         ///< Wired Equivalent Privacy (WEP) key used for authentication
  261 );
  262 
  263 //--------------------------------------------------------------------------------------------------
  264 /**
  265  * Set the security protocol for connection
  266  *
  267  * @return LE_FAULT  The function failed.
  268  * @return LE_OK     The function succeeded.
  269  */
  270 //--------------------------------------------------------------------------------------------------
  271 LE_SHARED le_result_t pa_wifiClient_SetSecurityProtocol
  272 (
  273     const le_wifiClient_SecurityProtocol_t securityProtocol
  274         ///< [IN]
  275         ///< Security protocol used for communication.
  276 );
  277 
  278 //--------------------------------------------------------------------------------------------------
  279 /**
  280  * Clears all username, password, pre-shared key, passphrase settings previously made by
  281  * @see  pa_wifiClient_SetPassPhrase
  282  * @see  pa_wifiClient_SetPreSharedKey
  283  * @see  pa_wifiClient_SetUserCredentials
  284  *
  285  * @return LE_FAULT  The function failed.
  286  * @return LE_OK     The function succeeded.
  287  */
  288 //--------------------------------------------------------------------------------------------------
  289 LE_SHARED le_result_t pa_wifiClient_ClearAllCredentials
  290 (
  291     void
  292 );
  293 
  294 //--------------------------------------------------------------------------------------------------
  295 /**
  296  * Start WiFi Client PA
  297  *
  298  * @return LE_FAULT  The function failed.
  299  * @return LE_OK     The function succeeded.
  300  */
  301 //--------------------------------------------------------------------------------------------------
  302 LE_SHARED le_result_t pa_wifiClient_Start
  303 (
  304     void
  305 );
  306 
  307 //--------------------------------------------------------------------------------------------------
  308 /**
  309  * Stop WiFi Client PA
  310  *
  311  * @return LE_FAULT  The function failed.
  312  * @return LE_OK     The function succeeded.
  313  */
  314 //--------------------------------------------------------------------------------------------------
  315 LE_SHARED le_result_t pa_wifiClient_Stop
  316 (
  317     void
  318 );
  319 #endif // PA_WIFI_H
pa_wifiClient_AccessPoint_t::ssidLength
uint8_t ssidLength
The number of bytes in the ssidBytes. 
Definition: pa_wifi.h:24
pa_wifiClient_AccessPoint_t::signalStrength
int16_t signalStrength
Definition: pa_wifi.h:22
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:240
le_result_t
le_result_t
Definition: le_basics.h:35
le_wifiClient_Event_t
le_wifiClient_Event_t
Definition: le_wifiClient_interface.h:310
le_wifiClient_SecurityProtocol_t
le_wifiClient_SecurityProtocol_t
Definition: le_wifiClient_interface.h:329
LE_WIFIDEFS_MAX_BSSID_BYTES
#define LE_WIFIDEFS_MAX_BSSID_BYTES
Definition: le_wifiDefs_interface.h:252
LE_WIFIDEFS_MAX_SSID_BYTES
#define LE_WIFIDEFS_MAX_SSID_BYTES
Definition: le_wifiDefs_interface.h:236
legato.h
pa_wifiClient_AccessPoint_t
Definition: pa_wifi.h:20