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  * This function specifies whether the target Access Point is hiding its presence from clients or
  232  * not. When an Access Point is hidden, it cannot be discovered by a scan process.
  233  *
  234  * @note By default, this attribute is not set which means that the client is unable to connect to
  235  * a hidden access point. When enabled, the client will be able to connect to the access point
  236  * whether it is hidden or not.
  237  */
  238 //--------------------------------------------------------------------------------------------------
  239 LE_SHARED void pa_wifiClient_SetHiddenNetworkAttribute
  240 (
  241     bool hidden
  242         ///< [IN]
  243         ///< If TRUE, the WIFI client will be able to connect to a hidden access point.
  244 );
  245 
  246 //--------------------------------------------------------------------------------------------------
  247 /**
  248  * Set the WEP key (WEP)
  249  *
  250  * @return LE_FAULT  The function failed.
  251  * @return LE_OK     The function succeeded.
  252  */
  253 //--------------------------------------------------------------------------------------------------
  254 LE_SHARED le_result_t pa_wifiClient_SetWepKey
  255 (
  256     const char *wepKeyPtr
  257         ///< [IN]
  258         ///< Wired Equivalent Privacy (WEP) key used for authentication
  259 );
  260 
  261 //--------------------------------------------------------------------------------------------------
  262 /**
  263  * Set the security protocol for connection
  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_SetSecurityProtocol
  270 (
  271     const le_wifiClient_SecurityProtocol_t securityProtocol
  272         ///< [IN]
  273         ///< Security protocol used for communication.
  274 );
  275 
  276 //--------------------------------------------------------------------------------------------------
  277 /**
  278  * Clears all username, password, pre-shared key, passphrase settings previously made by
  279  * @see  pa_wifiClient_SetPassPhrase
  280  * @see  pa_wifiClient_SetPreSharedKey
  281  * @see  pa_wifiClient_SetUserCredentials
  282  *
  283  * @return LE_FAULT  The function failed.
  284  * @return LE_OK     The function succeeded.
  285  */
  286 //--------------------------------------------------------------------------------------------------
  287 LE_SHARED le_result_t pa_wifiClient_ClearAllCredentials
  288 (
  289     void
  290 );
  291 
  292 //--------------------------------------------------------------------------------------------------
  293 /**
  294  * Start WiFi Client PA
  295  *
  296  * @return LE_FAULT  The function failed.
  297  * @return LE_OK     The function succeeded.
  298  */
  299 //--------------------------------------------------------------------------------------------------
  300 LE_SHARED le_result_t pa_wifiClient_Start
  301 (
  302     void
  303 );
  304 
  305 //--------------------------------------------------------------------------------------------------
  306 /**
  307  * Stop WiFi Client PA
  308  *
  309  * @return LE_FAULT  The function failed.
  310  * @return LE_OK     The function succeeded.
  311  */
  312 //--------------------------------------------------------------------------------------------------
  313 LE_SHARED le_result_t pa_wifiClient_Stop
  314 (
  315     void
  316 );
  317 #endif // PA_WIFI_H
le_wifiClient_SecurityProtocol_t
le_wifiClient_SecurityProtocol_t
Definition: le_wifiClient_interface.h:320
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