pa_wifi.h

    1 // -------------------------------------------------------------------------------------------------
    2 /**
    3  *  Wifi Client Platform Adapter
    4  *
    5  *  Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
    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     int16_t signalStrength; ///< if 0xffff, then the value is was not found.
   22     uint8_t ssidBytes[ LE_WIFIDEFS_MAX_SSID_BYTES ]; ///< Contains ssidLength number of bytes
   23     uint8_t ssidLength; ///< The number of Bytes in the ssidBytes
   24 }
   25 pa_wifiClient_AccessPoint_t;
   26 
   27 //--------------------------------------------------------------------------------------------------
   28 /**
   29  * Event Handler for PA Wifi Client changes
   30  *
   31  * @param event
   32  *        Handles the PA  wifi events.
   33  *        Two events are directly generated from the PA
   34  *            LE_WIFICLIENT_EVENT_CONNECTED,
   35  *            LE_WIFICLIENT_EVENT_DISCONNECTED,
   36  * @param contextPtr
   37  */
   38 //--------------------------------------------------------------------------------------------------
   39 typedef void (*pa_wifiClient_NewEventHandlerFunc_t)
   40 (
   41     le_wifiClient_Event_t event,
   42     void* contextPtr
   43 );
   44 
   45 //--------------------------------------------------------------------------------------------------
   46 /**
   47  * Add handler function for PA EVENT 'le_wifiClient_Event_t'
   48  *
   49  * This event provide information on PA Wifi Client event changes.
   50  */
   51 //--------------------------------------------------------------------------------------------------
   52 LE_SHARED le_result_t  pa_wifiClient_AddEventHandler
   53 (
   54     pa_wifiClient_NewEventHandlerFunc_t handlerPtr,
   55         ///< [IN]
   56 
   57     void* contextPtr
   58         ///< [IN]
   59 );
   60 
   61 //--------------------------------------------------------------------------------------------------
   62 /**
   63  * This function must be called to initialize the PA WIFI Module.
   64  *
   65  * @return LE_OK     The function succeed.
   66  */
   67 //--------------------------------------------------------------------------------------------------
   68 LE_SHARED le_result_t pa_wifiClient_Init
   69 (
   70     void
   71 );
   72 
   73 //--------------------------------------------------------------------------------------------------
   74 /**
   75  * This function must be called to release the PA WIFI Module.
   76  *
   77  * @return LE_OK     The function succeed.
   78  */
   79 //--------------------------------------------------------------------------------------------------
   80 LE_SHARED le_result_t pa_wifiClient_Release
   81 (
   82     void
   83 );
   84 
   85 //--------------------------------------------------------------------------------------------------
   86 /**
   87  * This function will start a scan and returns when it is done.
   88  * It should NOT return until the scan is done and results can be read with GetScanResult
   89  * Results are read via pa_wifiClient_GetScanResult.
   90  * When the reading is done pa_wifiClient_ScanDone MUST be called.*
   91  *
   92  * @return LE_FAULT  The function failed.
   93  * @return LE_BUSY   The function is already ongoing.
   94  * @return LE_OK     The function succeed.*/
   95 //--------------------------------------------------------------------------------------------------
   96 LE_SHARED le_result_t pa_wifiClient_Scan
   97 (
   98     void
   99 );
  100 
  101 //--------------------------------------------------------------------------------------------------
  102 /**
  103  * This function to find out if scan is currently running
  104  * @return TRUE  Scan is running.
  105  * @return FALSE Scan is not running
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 LE_SHARED bool pa_wifiClient_IsScanRunning
  109 (
  110     void
  111 );
  112 
  113 //--------------------------------------------------------------------------------------------------
  114 /**
  115  * This function can be called after pa_wifi_Scan.
  116  * When the reading is done, that it no longer returns LE_OK, pa_wifiClient_ScanDone MUST be called.
  117  * @return LE_NOT_FOUND  There is no more AP:s found.
  118  * @return LE_OK     The function succeed.
  119  * @return LE_FAULT  The function failed.
  120  */
  121 //--------------------------------------------------------------------------------------------------
  122 LE_SHARED le_result_t pa_wifiClient_GetScanResult
  123 (
  124     pa_wifiClient_AccessPoint_t * accessPointPtr
  125     ///< [IN][OUT]
  126     ///< Structure provided by calling function.
  127     ///< Results filled out if resullt was LE_OK
  128 );
  129 
  130 //--------------------------------------------------------------------------------------------------
  131 /**
  132  * This function must be called after the pa_wifiClient_Scan() has been done.
  133  * It signals that the scan results are no longer needed and frees some internal resourses.
  134  *
  135  * @return LE_OK     The function succeed.
  136  */
  137 //--------------------------------------------------------------------------------------------------
  138 LE_SHARED le_result_t pa_wifiClient_ScanDone
  139 (
  140     void
  141 );
  142 
  143 //--------------------------------------------------------------------------------------------------
  144 /**
  145  * This function connects a wifiClient.
  146  *
  147  * @return LE_FAULT  The function failed.
  148  * @return LE_OK     The function succeed.*/
  149 //--------------------------------------------------------------------------------------------------
  150 LE_SHARED le_result_t pa_wifiClient_Connect
  151 (
  152     uint8_t ssidBytes[LE_WIFIDEFS_MAX_SSID_BYTES], ///< Contains ssidLength number of bytes
  153     uint8_t ssidLength ///< The number of Bytes in the ssidBytes
  154 );
  155 
  156 //--------------------------------------------------------------------------------------------------
  157 /**
  158  * This function disconnects a wifiClient.
  159  *
  160  * @return LE_FAULT  The function failed.
  161  * @return LE_OK     The function succeed.*/
  162 //--------------------------------------------------------------------------------------------------
  163 LE_SHARED le_result_t pa_wifiClient_Disconnect
  164 (
  165     void
  166 );
  167 
  168 //--------------------------------------------------------------------------------------------------
  169 /**
  170  * Set the username and password (WPA-Entreprise).
  171  *
  172  * @return LE_FAULT  The function failed.
  173  * @return LE_OK     The function succeed.*/
  174 //--------------------------------------------------------------------------------------------------
  175 LE_SHARED le_result_t pa_wifiClient_SetUserCredentials
  176 (
  177     const char* username,
  178     const char* password
  179 );
  180 
  181 //--------------------------------------------------------------------------------------------------
  182 /**
  183  * Set the PassPhrase used to create PSK (WPA-Personal).
  184  * @see  pa_wifiClient_SetPreSharedKey
  185  *
  186  * @return LE_FAULT  The function failed.
  187  * @return LE_OK     The function succeed.*/
  188 //--------------------------------------------------------------------------------------------------
  189 LE_SHARED le_result_t pa_wifiClient_SetPassphrase
  190 (
  191     const char* passphrase
  192 );
  193 
  194 //--------------------------------------------------------------------------------------------------
  195 /**
  196  * Set the PreSharedKey (WPA-Personal)
  197  * @see  pa_wifiClient_SetPassPhrase
  198  *
  199  * @return LE_FAULT  The function failed.
  200  * @return LE_OK     The function succeed.*/
  201 //--------------------------------------------------------------------------------------------------
  202 LE_SHARED le_result_t pa_wifiClient_SetPreSharedKey
  203 (
  204     const char* preSharedKey
  205 );
  206 
  207 //--------------------------------------------------------------------------------------------------
  208 /**
  209  * Set the WEP key (WEP)
  210  *
  211  * @return LE_FAULT  The function failed.
  212  * @return LE_OK     The function succeed.*/
  213 //--------------------------------------------------------------------------------------------------
  214 LE_SHARED le_result_t pa_wifiClient_SetWepKey
  215 (
  216     const char* wepKey
  217 );
  218 
  219 //--------------------------------------------------------------------------------------------------
  220 /**
  221  * Set the security protocol for connection
  222  *
  223  * @return LE_FAULT  The function failed.
  224  * @return LE_OK     The function succeed.*/
  225 //--------------------------------------------------------------------------------------------------
  226 LE_SHARED le_result_t pa_wifiClient_SetSecurityProtocol
  227 (
  228     const le_wifiClient_SecurityProtocol_t securityProtocol
  229 );
  230 
  231 //--------------------------------------------------------------------------------------------------
  232 /**
  233  * Clears all username, password, PreShared Key, passphrase settings previously made by
  234  * @see  pa_wifiClient_SetPassPhrase
  235  * @see  pa_wifiClient_SetPreSharedKey
  236  * @see  pa_wifiClient_SetUserCredentials
  237  *
  238  * @return LE_FAULT  The function failed.
  239  * @return LE_OK     The function succeed.
  240  */
  241 //--------------------------------------------------------------------------------------------------
  242 LE_SHARED le_result_t pa_wifiClient_ClearAllCredentials
  243 (
  244     void
  245 );
  246 
  247 //--------------------------------------------------------------------------------------------------
  248 /**
  249  * Start Wifi Client PA
  250  *
  251  * @return LE_FAULT  The function failed.
  252  * @return LE_OK     The function succeed.*/
  253 //--------------------------------------------------------------------------------------------------
  254 LE_SHARED le_result_t pa_wifiClient_Start
  255 (
  256     void
  257 );
  258 
  259 //--------------------------------------------------------------------------------------------------
  260 /**
  261  * Stop Wifi Client PA
  262  *
  263  * @return LE_FAULT  The function failed.
  264  * @return LE_OK     The function succeed.*/
  265 //--------------------------------------------------------------------------------------------------
  266 LE_SHARED le_result_t pa_wifiClient_Stop
  267 (
  268     void
  269 );
  270 #endif // PA_WIFI_H
le_wifiClient_SecurityProtocol_t
le_wifiClient_SecurityProtocol_t
Definition: le_wifiClient_interface.h:294
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:240
le_wifiClient_Event_t
le_wifiClient_Event_t
Definition: le_wifiClient_interface.h:275
le_result_t
le_result_t
Definition: le_basics.h:35
LE_WIFIDEFS_MAX_SSID_BYTES
#define LE_WIFIDEFS_MAX_SSID_BYTES
Definition: le_wifiDefs_interface.h:141
pa_wifiClient_AccessPoint_t::ssidLength
uint8_t ssidLength
The number of Bytes in the ssidBytes. 
Definition: pa_wifi.h:23
pa_wifiClient_AccessPoint_t::signalStrength
int16_t signalStrength
if 0xffff, then the value is was not found. 
Definition: pa_wifi.h:21
legato.h
pa_wifiClient_AccessPoint_t
Definition: pa_wifi.h:20