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  */
  142 //--------------------------------------------------------------------------------------------------
  143 LE_SHARED le_result_t pa_wifiClient_ScanDone
  144 (
  145     void
  146 );
  147 
  148 //--------------------------------------------------------------------------------------------------
  149 /**
  150  * This function connects a wifiClient.
  151  *
  152  * @return LE_FAULT  The function failed.
  153  * @return LE_OK     The function succeeded.
  154  */
  155 //--------------------------------------------------------------------------------------------------
  156 LE_SHARED le_result_t pa_wifiClient_Connect
  157 (
  158     uint8_t ssidBytes[LE_WIFIDEFS_MAX_SSID_BYTES],
  159         /// [IN]
  160         ///< Contains ssidLength number of bytes
  161     uint8_t ssidLength
  162         /// [IN]
  163         ///< The number of bytes in the ssidBytes
  164 );
  165 
  166 //--------------------------------------------------------------------------------------------------
  167 /**
  168  * This function disconnects a wifiClient.
  169  *
  170  * @return LE_FAULT  The function failed.
  171  * @return LE_OK     The function succeeded.
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 LE_SHARED le_result_t pa_wifiClient_Disconnect
  175 (
  176     void
  177 );
  178 
  179 //--------------------------------------------------------------------------------------------------
  180 /**
  181  * Set the username and password (WPA-Entreprise).
  182  *
  183  * @return LE_FAULT  The function failed.
  184  * @return LE_OK     The function succeeded.
  185  */
  186 //--------------------------------------------------------------------------------------------------
  187 LE_SHARED le_result_t pa_wifiClient_SetUserCredentials
  188 (
  189     const char *usernamePtr,
  190         ///< [IN]
  191         ///< Username used for authentication
  192     const char *passwordPtr
  193         ///< [IN]
  194         ///< Password used for authentication
  195 );
  196 
  197 //--------------------------------------------------------------------------------------------------
  198 /**
  199  * Set the PassPhrase used to create PSK (WPA-Personal).
  200  * @see  pa_wifiClient_SetPreSharedKey
  201  *
  202  * @return LE_FAULT  The function failed.
  203  * @return LE_OK     The function succeeded.
  204  */
  205 //--------------------------------------------------------------------------------------------------
  206 LE_SHARED le_result_t pa_wifiClient_SetPassphrase
  207 (
  208     const char *passphrasePtr
  209         ///< [IN]
  210         ///< Passphrase used for authentication
  211 );
  212 
  213 //--------------------------------------------------------------------------------------------------
  214 /**
  215  * Set the PreSharedKey (WPA-Personal)
  216  * @see  pa_wifiClient_SetPassPhrase
  217  *
  218  * @return LE_FAULT  The function failed.
  219  * @return LE_OK     The function succeeded.
  220  */
  221 //--------------------------------------------------------------------------------------------------
  222 LE_SHARED le_result_t pa_wifiClient_SetPreSharedKey
  223 (
  224     const char *preSharedKeyPtr
  225         ///< [IN]
  226         ///< Pre-shared key (PSK) used for authentication
  227 );
  228 
  229 //--------------------------------------------------------------------------------------------------
  230 /**
  231  * Set the WEP key (WEP)
  232  *
  233  * @return LE_FAULT  The function failed.
  234  * @return LE_OK     The function succeeded.
  235  */
  236 //--------------------------------------------------------------------------------------------------
  237 LE_SHARED le_result_t pa_wifiClient_SetWepKey
  238 (
  239     const char *wepKeyPtr
  240         ///< [IN]
  241         ///< Wired Equivalent Privacy (WEP) key used for authentication
  242 );
  243 
  244 //--------------------------------------------------------------------------------------------------
  245 /**
  246  * Set the security protocol for connection
  247  *
  248  * @return LE_FAULT  The function failed.
  249  * @return LE_OK     The function succeeded.
  250  */
  251 //--------------------------------------------------------------------------------------------------
  252 LE_SHARED le_result_t pa_wifiClient_SetSecurityProtocol
  253 (
  254     const le_wifiClient_SecurityProtocol_t securityProtocol
  255         ///< [IN]
  256         ///< Security protocol used for communication.
  257 );
  258 
  259 //--------------------------------------------------------------------------------------------------
  260 /**
  261  * Clears all username, password, pre-shared key, passphrase settings previously made by
  262  * @see  pa_wifiClient_SetPassPhrase
  263  * @see  pa_wifiClient_SetPreSharedKey
  264  * @see  pa_wifiClient_SetUserCredentials
  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_ClearAllCredentials
  271 (
  272     void
  273 );
  274 
  275 //--------------------------------------------------------------------------------------------------
  276 /**
  277  * Start WiFi Client PA
  278  *
  279  * @return LE_FAULT  The function failed.
  280  * @return LE_OK     The function succeeded.
  281  */
  282 //--------------------------------------------------------------------------------------------------
  283 LE_SHARED le_result_t pa_wifiClient_Start
  284 (
  285     void
  286 );
  287 
  288 //--------------------------------------------------------------------------------------------------
  289 /**
  290  * Stop WiFi Client PA
  291  *
  292  * @return LE_FAULT  The function failed.
  293  * @return LE_OK     The function succeeded.
  294  */
  295 //--------------------------------------------------------------------------------------------------
  296 LE_SHARED le_result_t pa_wifiClient_Stop
  297 (
  298     void
  299 );
  300 #endif // PA_WIFI_H
le_wifiClient_SecurityProtocol_t
le_wifiClient_SecurityProtocol_t
Definition: le_wifiClient_interface.h:316
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:240
le_wifiClient_Event_t
le_wifiClient_Event_t
Definition: le_wifiClient_interface.h:299
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