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 {
   22     int16_t  signalStrength;                        ///< 0xffff means value was not found.
   23     uint8_t  ssidLength;                            ///< The number of bytes in the ssidBytes.
   24     uint8_t  ssidBytes[LE_WIFIDEFS_MAX_SSID_BYTES]; ///< Contains ssidLength number of bytes.
   25 } pa_wifiClient_AccessPoint_t;
   26 
   27 //--------------------------------------------------------------------------------------------------
   28 /**
   29  * Event handler for PA WiFi access point changes.
   30  *
   31  * Handles the PA WiFi events.
   32  */
   33 //--------------------------------------------------------------------------------------------------
   34 typedef void (*pa_wifiClient_NewEventHandlerFunc_t)
   35 (
   36     le_wifiClient_Event_t event,
   37         ///< [IN]
   38         ///< WiFi event to process
   39     void *contextPtr
   40         ///< [IN]
   41         ///< Associated WiFi event context
   42 );
   43 
   44 //--------------------------------------------------------------------------------------------------
   45 /**
   46  * Add handler function for PA EVENT 'le_wifiClient_Event_t'
   47  *
   48  * This event provides information on PA WiFi Client event changes.
   49  */
   50 //--------------------------------------------------------------------------------------------------
   51 LE_SHARED le_result_t pa_wifiClient_AddEventHandler
   52 (
   53     pa_wifiClient_NewEventHandlerFunc_t handlerPtr,
   54         ///< [IN]
   55         ///< Event handler function pointer.
   56     void *contextPtr
   57         ///< [IN]
   58         ///< Associated event context.
   59 );
   60 
   61 //--------------------------------------------------------------------------------------------------
   62 /**
   63  * This function must be called to initialize the PA WiFi Module.
   64  *
   65  * @return LE_OK     The function succeeded.
   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 succeeded.
   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.
   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 succeeded.
   95  */
   96 //--------------------------------------------------------------------------------------------------
   97 LE_SHARED le_result_t pa_wifiClient_Scan
   98 (
   99     void
  100 );
  101 
  102 //--------------------------------------------------------------------------------------------------
  103 /**
  104  * This function is used to find out if a scan is currently running.
  105  *
  106  * @return TRUE  Scan is running.
  107  * @return FALSE Scan is not running
  108  */
  109 //--------------------------------------------------------------------------------------------------
  110 LE_SHARED bool pa_wifiClient_IsScanRunning
  111 (
  112     void
  113 );
  114 
  115 //--------------------------------------------------------------------------------------------------
  116 /**
  117  * This function can be called after pa_wifi_Scan.
  118  * When the reading is done, it no longer returns LE_OK
  119  * pa_wifiClient_ScanDone MUST be called.
  120  *
  121  * @return LE_NOT_FOUND  There is no more AP found.
  122  * @return LE_OK     The function succeeded.
  123  * @return LE_FAULT  The function failed.
  124  */
  125 //--------------------------------------------------------------------------------------------------
  126 LE_SHARED le_result_t pa_wifiClient_GetScanResult
  127 (
  128     pa_wifiClient_AccessPoint_t *accessPointPtr
  129     ///< [IN][OUT]
  130     ///< Structure provided by calling function.
  131     ///< Results filled out if result was LE_OK.
  132 );
  133 
  134 //--------------------------------------------------------------------------------------------------
  135 /**
  136  * This function must be called after the pa_wifiClient_Scan() has been done.
  137  * It signals that the scan results are no longer needed and frees some internal resourses.
  138  *
  139  * @return LE_OK     The function succeeded.
  140  */
  141 //--------------------------------------------------------------------------------------------------
  142 LE_SHARED le_result_t pa_wifiClient_ScanDone
  143 (
  144     void
  145 );
  146 
  147 //--------------------------------------------------------------------------------------------------
  148 /**
  149  * This function connects a wifiClient.
  150  *
  151  * @return LE_FAULT  The function failed.
  152  * @return LE_OK     The function succeeded.
  153  */
  154 //--------------------------------------------------------------------------------------------------
  155 LE_SHARED le_result_t pa_wifiClient_Connect
  156 (
  157     uint8_t ssidBytes[LE_WIFIDEFS_MAX_SSID_BYTES],
  158         /// [IN]
  159         ///< Contains ssidLength number of bytes
  160     uint8_t ssidLength
  161         /// [IN]
  162         ///< The number of bytes in the ssidBytes
  163 );
  164 
  165 //--------------------------------------------------------------------------------------------------
  166 /**
  167  * This function disconnects a wifiClient.
  168  *
  169  * @return LE_FAULT  The function failed.
  170  * @return LE_OK     The function succeeded.
  171  */
  172 //--------------------------------------------------------------------------------------------------
  173 LE_SHARED le_result_t pa_wifiClient_Disconnect
  174 (
  175     void
  176 );
  177 
  178 //--------------------------------------------------------------------------------------------------
  179 /**
  180  * Set the username and password (WPA-Entreprise).
  181  *
  182  * @return LE_FAULT  The function failed.
  183  * @return LE_OK     The function succeeded.
  184  */
  185 //--------------------------------------------------------------------------------------------------
  186 LE_SHARED le_result_t pa_wifiClient_SetUserCredentials
  187 (
  188     const char *usernamePtr,
  189         ///< [IN]
  190         ///< Username used for authentication
  191     const char *passwordPtr
  192         ///< [IN]
  193         ///< Password used for authentication
  194 );
  195 
  196 //--------------------------------------------------------------------------------------------------
  197 /**
  198  * Set the PassPhrase used to create PSK (WPA-Personal).
  199  * @see  pa_wifiClient_SetPreSharedKey
  200  *
  201  * @return LE_FAULT  The function failed.
  202  * @return LE_OK     The function succeeded.
  203  */
  204 //--------------------------------------------------------------------------------------------------
  205 LE_SHARED le_result_t pa_wifiClient_SetPassphrase
  206 (
  207     const char *passphrasePtr
  208         ///< [IN]
  209         ///< Passphrase used for authentication
  210 );
  211 
  212 //--------------------------------------------------------------------------------------------------
  213 /**
  214  * Set the PreSharedKey (WPA-Personal)
  215  * @see  pa_wifiClient_SetPassPhrase
  216  *
  217  * @return LE_FAULT  The function failed.
  218  * @return LE_OK     The function succeeded.
  219  */
  220 //--------------------------------------------------------------------------------------------------
  221 LE_SHARED le_result_t pa_wifiClient_SetPreSharedKey
  222 (
  223     const char *preSharedKeyPtr
  224         ///< [IN]
  225         ///< Pre-shared key (PSK) used for authentication
  226 );
  227 
  228 //--------------------------------------------------------------------------------------------------
  229 /**
  230  * Set the WEP key (WEP)
  231  *
  232  * @return LE_FAULT  The function failed.
  233  * @return LE_OK     The function succeeded.
  234  */
  235 //--------------------------------------------------------------------------------------------------
  236 LE_SHARED le_result_t pa_wifiClient_SetWepKey
  237 (
  238     const char *wepKeyPtr
  239         ///< [IN]
  240         ///< Wired Equivalent Privacy (WEP) key used for authentication
  241 );
  242 
  243 //--------------------------------------------------------------------------------------------------
  244 /**
  245  * Set the security protocol for connection
  246  *
  247  * @return LE_FAULT  The function failed.
  248  * @return LE_OK     The function succeeded.
  249  */
  250 //--------------------------------------------------------------------------------------------------
  251 LE_SHARED le_result_t pa_wifiClient_SetSecurityProtocol
  252 (
  253     const le_wifiClient_SecurityProtocol_t securityProtocol
  254         ///< [IN]
  255         ///< Security protocol used for communication.
  256 );
  257 
  258 //--------------------------------------------------------------------------------------------------
  259 /**
  260  * Clears all username, password, pre-shared key, passphrase settings previously made by
  261  * @see  pa_wifiClient_SetPassPhrase
  262  * @see  pa_wifiClient_SetPreSharedKey
  263  * @see  pa_wifiClient_SetUserCredentials
  264  *
  265  * @return LE_FAULT  The function failed.
  266  * @return LE_OK     The function succeeded.
  267  */
  268 //--------------------------------------------------------------------------------------------------
  269 LE_SHARED le_result_t pa_wifiClient_ClearAllCredentials
  270 (
  271     void
  272 );
  273 
  274 //--------------------------------------------------------------------------------------------------
  275 /**
  276  * Start WiFi Client PA
  277  *
  278  * @return LE_FAULT  The function failed.
  279  * @return LE_OK     The function succeeded.
  280  */
  281 //--------------------------------------------------------------------------------------------------
  282 LE_SHARED le_result_t pa_wifiClient_Start
  283 (
  284     void
  285 );
  286 
  287 //--------------------------------------------------------------------------------------------------
  288 /**
  289  * Stop WiFi Client PA
  290  *
  291  * @return LE_FAULT  The function failed.
  292  * @return LE_OK     The function succeeded.
  293  */
  294 //--------------------------------------------------------------------------------------------------
  295 LE_SHARED le_result_t pa_wifiClient_Stop
  296 (
  297     void
  298 );
  299 #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:168
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
0xffff means value was not found. 
Definition: pa_wifi.h:22
legato.h
pa_wifiClient_AccessPoint_t
Definition: pa_wifi.h:20