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