le_wifiClient_interface.h

    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_le_wifi_client WiFi Client Service
   14  *
   15  * @ref le_wifiClient_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * This API provides WiFi Client setup.
   20  * Please note that the WiFi Client cannot be used at the same time as the WiFi Access Points
   21  * service, due to the sharing of same wifi hardware.
   22  *
   23  * @section le_wifi_binding IPC interfaces binding
   24  *
   25  *
   26  * Here's a code sample binding to WiFi service:
   27  * @verbatim
   28    bindings:
   29    {
   30       clientExe.clientComponent.le_wifiClient -> wifiService.le_wifiClient
   31    }
   32    @endverbatim
   33  *
   34  * @section le_wifiClient_Start Starting the WiFi Client
   35  *
   36  * First of all the function le_wifiClient_Start() must be called to start the WiFi Service.
   37  * - le_wifiClient_Start(): returns LE_OK if the call went ok.
   38  *   If WiFi Access Point is active, this will fail.
   39  *
   40  *
   41  * To subscribe to wifi events le_wifiClient_AddNewEventHandler() is to be called.
   42  * - le_wifiClient_AddNewEventHandler(): returns the handler reference if the call went ok.
   43  *
   44  * @code
   45  *
   46  * static void EventHandler
   47  * (
   48  *     le_wifiClient_Event_t clientEvent,
   49  *     void *contextPtr
   50  * )
   51  * {
   52  *     switch( clientEvent )
   53  *     {
   54  *          case LE_WIFICLIENT_EVENT_CONNECTED:
   55  *          {
   56  *              LE_INFO("WiFi Client Connected.");
   57  *          }
   58  *          break;
   59  *          case LE_WIFICLIENT_EVENT_DISCONNECTED:
   60  *          {
   61  *              LE_INFO("WiFi Client Disconnected.");
   62  *          }
   63  *          break;
   64  *          case LE_WIFICLIENT_EVENT_SCAN_DONE:
   65  *          {
   66  *              LE_INFO("WiFi Client Scan is done.");
   67  *              MyHandleScanResult();
   68  *          }
   69  *          break;
   70  *     }
   71  * }
   72  *
   73  * le_wifiClient_NewEventHandler WiFiEventHandlerRef = NULL;
   74  *
   75  * static void MyInit
   76  * (
   77  *     void
   78  * )
   79  * {
   80  *     le_result_t result = le_wifiClient_start();
   81  *
   82  *     if ( LE_OK == result )
   83  *     {
   84  *         LE_INFO("WiFi Client started.");
   85  *         WiFiEventHandlerRef = le_wifiClient_AddNewEventHandler( EventHandler, NULL );
   86  *     }
   87  *     else if ( LE_BUSY == result )
   88  *     {
   89  *         LE_INFO("ERROR: WiFi Client already started.");
   90  *     }
   91  *     else
   92  *     {
   93  *         LE_INFO("ERROR: WiFi Client not started.");
   94  *     }
   95  *
   96  * }
   97  *
   98  * @endcode
   99  *
  100  *
  101  * @section le_wifiClient_scan Scanning Access Points with WiFi Client
  102  *
  103  * To start a scan for Access Points, the le_wifiClient_Scan() should be called.
  104  * - le_wifiClient_Scan(): returns the LE_OK if the call went ok.
  105  *
  106  *
  107  * @section le_wifiClient_scan_result Processing the WiFi scan results
  108  *
  109  * Once the scan results are available, the event LE_WIFICLIENT_EVENT_SCAN_DONE is received.
  110  * The found Access Points can then be gotten with
  111  * - le_wifiClient_GetFirstAccessPoint():  returns the Access Point if found. Else NULL.
  112  * - le_wifiClient_GetNextAccessPoint(): returns the next Access Point if found. Else NULL.
  113  *
  114  * The Access Points SSID, Service Set Identifier, is not a string.
  115  * It does however often contain human readable ASCII values.
  116  * It can be read with the following function:
  117  * - le_wifiClient_GetSsid() : returns the LE_OK if the SSID was read ok.
  118  *
  119  * The Access Points signal strength can be read with the following function:
  120  * - le_wifiClient_GetSignalStrength() : returns the signal strength in dBm of the AccessPoint
  121  *
  122  * @code
  123  *
  124  * static void MyHandleScanResult
  125  * (
  126  *     void
  127  * )
  128  * {
  129  *     uint8 ssid[MAX_SSID_BYTES];
  130  *     le_wifiClient_AccessPointRef_t accessPointRef = le_wifiClient_GetFirstAccessPoint();
  131  *
  132  *     while( NULL != accessPointRef )
  133  *     {
  134  *          result = le_wifiClient_GetSsid( accessPointRef, ssid, MAX_SSID_BYTES );
  135  *          if (( result == LE_OK ) && ( memcmp( ssid, "MySSID", 6) == 0 ))
  136  *          {
  137  *               LE_INFO("WiFi Client found.");
  138  *               break;
  139  *          }
  140  *          accessPointRef = le_wifiClient_GetNextAccessPoint();
  141  *     }
  142  * }
  143  *
  144  * @endcode
  145  *
  146  * @section le_wifiClient_connect_to_ap Connecting to Access Point
  147  *
  148  * First of all, an Access Point reference should be created using the SSID of the target Access
  149  * Point. Use the following function to create a reference:
  150  * - le_wifiClient_Create(): returns Access Point reference
  151  *
  152  * To set the pass phrase prior for the Access Point use the function:
  153  * - le_wifiClient_SetPassphrase(): returns the function execution status.
  154  *
  155  * WPA-Enterprise requires a username and password to authenticate.
  156  * To set them use the function:
  157  * - le_wifiClient_SetUserCredentials():  returns the function execution status.
  158  *
  159  * If an Access Point is hidden, it does not announce its presence and will not show up in scan.
  160  * So, the SSID of this Access Point must be known in advance. Then, use the following function to
  161  * allow connections to hidden Access Points:
  162  * le_wifiClient_SetHiddenNetworkAttribute(): returns the function execution status.
  163  *
  164  * Finally and when the Access Point parameters have been configured, use the following function to
  165  * attempt a connection:
  166  * - le_wifiClient_Connect():  returns the function execution status.
  167  *
  168  * @code
  169  *
  170  * static void MyConnectTo
  171  * (
  172  *     le_wifiClient_AccessPointRef_t accessPointRef
  173  * )
  174  * {
  175  *     le_result_t result;
  176  *     le_wifiClient_SetPassphrase ( accessPointRef, "Secret1" );
  177  *     result = le_wifiClient_Connect( accessPointRef );
  178  *     if (result == LE_OK)
  179  *     {
  180  *          LE_INFO("Connecting to AP.");
  181  *     }
  182  * }
  183  *
  184  * @endcode
  185  *
  186  * @section le_wifiClient_config_ssid Configure Wifi client with an SSID
  187  *
  188  * While the prior section lists out the le_wifiClient APIs that can be used together to configure
  189  * the Wifi client to connect to an Access Point over a given SSID, the le_wifiClient_LoadSsid()
  190  * API seeks to simplify these multiple steps, getting:
  191  * - the necessary Access Point reference created for the given SSID which is considered
  192  * selected for establishing a Wifi connection,
  193  * - the necessary Wifi configurations loaded which include the security protocol (i.e. via
  194  * le_wifiClient_SecurityProtocol()), passphrase (i.e. via le_wifiClient_SetPassphrase()),
  195  * and the hidden attribute when necessary (i.e. via le_wifiClient_SetHiddenNetworkAttribute()),
  196  * - the created reference returned to the API caller in its output argument.
  197  *
  198  * In just this one API call, all these steps would be done for the client application. If any
  199  * failure has occurred, subsequent steps in the sequence would be skipped and the failing cause
  200  * will be returned back to the API caller as the API's return value.
  201  *
  202  * This API also achieves the need to keep Wifi configurations back within wifiService instead of
  203  * elsewhere, like "dataConnectionService:/wifi/".
  204  *
  205  * With the use of this API, Wifi configurations need to be stored in the Legato config tree on the
  206  * path "wifiService:/wifi/channel/", under which configurations of multiple SSIDs can be stored at
  207  * the same time. This is done by having an SSID name string as a sub-path under this path and
  208  * then its Wifi configurations go under this sub-path. This is the path for any given SSID from
  209  * which this API will access to retrieve corresponding Wifi configurations and install into the
  210  * wifiClient. Here is an example with 2 SSIDs configured:
  211  *
  212  * root@swi-mdm9x28:~# config get wifiService:/wifi/
  213  *  wifi/
  214  *    channel/
  215  *      MY-MOBILE/
  216  *        secProtocol<string> == 3
  217  *        passphrase<string> == @a1b2c3d4
  218  *      MY-WLAN/
  219  *        secProtocol<string> == 3
  220  *        passphrase<string> == @a1b2c3d4
  221  *        hidden<bool> == true
  222  *
  223  * The following is a sample code to illustrate how this API can be used:
  224  *
  225  * @code
  226  *
  227  *    le_result_t ret = le_wifiClient_LoadSsid(ssid, 0, &apRef);
  228  *    if (ret == LE_OK)
  229  *    {
  230  *        LE_DEBUG("Wifi configs installed to connect over SSID %s with AP reference %p",
  231  *                 ssid, apRef);
  232  *    }
  233  *    else
  234  *    {
  235  *        LE_ERROR("Failed to install wifi configs to connect over SSID %s", ssid);
  236  *    }
  237  *
  238  * @endcode
  239  *
  240  * @section le_wifiClient_get_current_connect Get the currently selected connection
  241  *
  242  * A selected SSID via its AP reference is set for use in Wifi connection establishment since
  243  * the API call to le_wifiClient_Connect(). Note that while the input argument is actually an
  244  * Access Point reference, this reference specifically refers to a given SSID on the device.
  245  * This is considered the selected connection for use until le_wifiClient_Disconnect() is called
  246  * to deselect it.
  247  *
  248  * During the time when this AP reference is set for use, there comes the need to be able to query
  249  * le_wifiClient for it back. This is what this le_wifiClient_GetCurrentConnection() API seeks to
  250  * return. The following is a sample code to illustrate how it can be used. The retrieved AP
  251  * reference is returned in the output argument.
  252  *
  253  * @code
  254  *
  255  *    le_wifiClient_GetCurrentConnection(&apRef);
  256  *    if (!apRef)
  257  *    {
  258  *        return;
  259  *    }
  260  *    ret = le_wifiClient_GetSsid(apRef, &ssid[0], &ssidSize);
  261  *    if (LE_OK != ret)
  262  *    {
  263  *        LE_ERROR("Failed to find SSID of AP reference %p", apRef);
  264  *        return;
  265  *    }
  266  *    ssid[ssidSize] = '\0';
  267  *    LE_DEBUG("Found currently selected Wifi connection to get established: %s, reference %p",
  268  *             ssid, apRef);
  269  *
  270  * @endcode
  271  *
  272  *
  273  * <HR>
  274  *
  275  * Copyright (C) Sierra Wireless Inc.
  276  */
  277 /**
  278  * @file le_wifiClient_interface.h
  279  *
  280  * Legato @ref c_le_wifi_client include file.
  281  *
  282  * Copyright (C) Sierra Wireless Inc.
  283  */
  284 
  285 #ifndef LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
  286 #define LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
  287 
  288 
  289 #include "legato.h"
  290 
  291 // Interface specific includes
  292 #include "le_wifiDefs_interface.h"
  293 
  294 
  295 //--------------------------------------------------------------------------------------------------
  296 /**
  297  * Type for handler called when a server disconnects.
  298  */
  299 //--------------------------------------------------------------------------------------------------
  300 typedef void (*le_wifiClient_DisconnectHandler_t)(void *);
  301 
  302 //--------------------------------------------------------------------------------------------------
  303 /**
  304  *
  305  * Connect the current client thread to the service providing this API. Block until the service is
  306  * available.
  307  *
  308  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  309  * called before any other functions in this API.  Normally, ConnectService is automatically called
  310  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  311  *
  312  * This function is created automatically.
  313  */
  314 //--------------------------------------------------------------------------------------------------
  315 void le_wifiClient_ConnectService
  316 (
  317     void
  318 );
  319 
  320 //--------------------------------------------------------------------------------------------------
  321 /**
  322  *
  323  * Try to connect the current client thread to the service providing this API. Return with an error
  324  * if the service is not available.
  325  *
  326  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  327  * called before any other functions in this API.  Normally, ConnectService is automatically called
  328  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  329  *
  330  * This function is created automatically.
  331  *
  332  * @return
  333  *  - LE_OK if the client connected successfully to the service.
  334  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  335  *    bound.
  336  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  337  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  338  */
  339 //--------------------------------------------------------------------------------------------------
  340 le_result_t le_wifiClient_TryConnectService
  341 (
  342     void
  343 );
  344 
  345 //--------------------------------------------------------------------------------------------------
  346 /**
  347  * Set handler called when server disconnection is detected.
  348  *
  349  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  350  * to continue without exiting, it should call longjmp() from inside the handler.
  351  */
  352 //--------------------------------------------------------------------------------------------------
  353 void le_wifiClient_SetServerDisconnectHandler
  354 (
  355     le_wifiClient_DisconnectHandler_t disconnectHandler,
  356     void *contextPtr
  357 );
  358 
  359 //--------------------------------------------------------------------------------------------------
  360 /**
  361  *
  362  * Disconnect the current client thread from the service providing this API.
  363  *
  364  * Normally, this function doesn't need to be called. After this function is called, there's no
  365  * longer a connection to the service, and the functions in this API can't be used. For details, see
  366  * @ref apiFilesC_client.
  367  *
  368  * This function is created automatically.
  369  */
  370 //--------------------------------------------------------------------------------------------------
  371 void le_wifiClient_DisconnectService
  372 (
  373     void
  374 );
  375 
  376 
  377 //--------------------------------------------------------------------------------------------------
  378 /**
  379  * Value for no signal strength.
  380  */
  381 //--------------------------------------------------------------------------------------------------
  382 #define LE_WIFICLIENT_NO_SIGNAL_STRENGTH 32767
  383 
  384 //--------------------------------------------------------------------------------------------------
  385 /**
  386  * Reference type for AccessPoint that is returned by the WiFi Scan.
  387  */
  388 //--------------------------------------------------------------------------------------------------
  389 typedef struct le_wifiClient_AccessPoint* le_wifiClient_AccessPointRef_t;
  390 
  391 
  392 //--------------------------------------------------------------------------------------------------
  393 /**
  394  * WiFi Client Events.
  395  */
  396 //--------------------------------------------------------------------------------------------------
  397 typedef enum
  398 {
  399     LE_WIFICLIENT_EVENT_CONNECTED = 0,
  400         ///< WiFi Client Connected
  401     LE_WIFICLIENT_EVENT_DISCONNECTED = 1,
  402         ///< WiFi Client Disconnected
  403     LE_WIFICLIENT_EVENT_SCAN_DONE = 2,
  404         ///< WiFi Scan result for available Access Points available
  405     LE_WIFICLIENT_EVENT_SCAN_FAILED = 3
  406         ///< WiFi Scan failed
  407 }
  408 le_wifiClient_Event_t;
  409 
  410 
  411 //--------------------------------------------------------------------------------------------------
  412 /**
  413  * WiFi Client Security Protocol for connection
  414  */
  415 //--------------------------------------------------------------------------------------------------
  416 typedef enum
  417 {
  418     LE_WIFICLIENT_SECURITY_NONE = 0,
  419         ///< no security.
  420     LE_WIFICLIENT_SECURITY_WEP = 1,
  421         ///< Using WEP.
  422     LE_WIFICLIENT_SECURITY_WPA_PSK_PERSONAL = 2,
  423         ///< Using WPA
  424     LE_WIFICLIENT_SECURITY_WPA2_PSK_PERSONAL = 3,
  425         ///< Using WPA2
  426     LE_WIFICLIENT_SECURITY_WPA_EAP_PEAP0_ENTERPRISE = 4,
  427         ///< Using WPA Enterprise
  428     LE_WIFICLIENT_SECURITY_WPA2_EAP_PEAP0_ENTERPRISE = 5
  429         ///< Using WPA2 Enterprise
  430 }
  431 le_wifiClient_SecurityProtocol_t;
  432 
  433 
  434 //--------------------------------------------------------------------------------------------------
  435 /**
  436  * Reference type used by Add/Remove functions for EVENT 'le_wifiClient_NewEvent'
  437  */
  438 //--------------------------------------------------------------------------------------------------
  439 typedef struct le_wifiClient_NewEventHandler* le_wifiClient_NewEventHandlerRef_t;
  440 
  441 
  442 //--------------------------------------------------------------------------------------------------
  443 /**
  444  * Handler for WiFi Client changes
  445  */
  446 //--------------------------------------------------------------------------------------------------
  447 typedef void (*le_wifiClient_NewEventHandlerFunc_t)
  448 (
  449     le_wifiClient_Event_t event,
  450         ///< Handles the wifi events
  451     void* contextPtr
  452         ///<
  453 );
  454 
  455 //--------------------------------------------------------------------------------------------------
  456 /**
  457  * Add handler function for EVENT 'le_wifiClient_NewEvent'
  458  *
  459  * This event provide information on WiFi Client event changes.
  460  *
  461  */
  462 //--------------------------------------------------------------------------------------------------
  463 le_wifiClient_NewEventHandlerRef_t le_wifiClient_AddNewEventHandler
  464 (
  465     le_wifiClient_NewEventHandlerFunc_t handlerPtr,
  466         ///< [IN]
  467     void* contextPtr
  468         ///< [IN]
  469 );
  470 
  471 //--------------------------------------------------------------------------------------------------
  472 /**
  473  * Remove handler function for EVENT 'le_wifiClient_NewEvent'
  474  */
  475 //--------------------------------------------------------------------------------------------------
  476 void le_wifiClient_RemoveNewEventHandler
  477 (
  478     le_wifiClient_NewEventHandlerRef_t handlerRef
  479         ///< [IN]
  480 );
  481 
  482 //--------------------------------------------------------------------------------------------------
  483 /**
  484  * Start the WIFI device.
  485  *
  486  * @return
  487  *      - LE_OK     Function succeeded.
  488  *      - LE_FAULT  Function failed.
  489  *      - LE_BUSY   The WIFI device is already started.
  490  */
  491 //--------------------------------------------------------------------------------------------------
  492 le_result_t le_wifiClient_Start
  493 (
  494     void
  495 );
  496 
  497 //--------------------------------------------------------------------------------------------------
  498 /**
  499  * Stop the WIFI device.
  500  *
  501  * @return
  502  *      - LE_OK        Function succeeded.
  503  *      - LE_FAULT     Function failed.
  504  *      - LE_DUPLICATE The WIFI device is already stopped.
  505  */
  506 //--------------------------------------------------------------------------------------------------
  507 le_result_t le_wifiClient_Stop
  508 (
  509     void
  510 );
  511 
  512 //--------------------------------------------------------------------------------------------------
  513 /**
  514  * Start Scanning for WiFi Access points
  515  * Will result in event LE_WIFICLIENT_EVENT_SCAN_DONE when the scan results are available.
  516  *
  517  * @return
  518  *      - LE_OK     Function succeeded.
  519  *      - LE_FAULT  Function failed.
  520  *      - LE_BUSY   Scan already running.
  521  */
  522 //--------------------------------------------------------------------------------------------------
  523 le_result_t le_wifiClient_Scan
  524 (
  525     void
  526 );
  527 
  528 //--------------------------------------------------------------------------------------------------
  529 /**
  530  * Get the first WiFi Access Point found.
  531  *
  532  * @return
  533  *      - WiFi  Access Point reference if ok.
  534  *      - NULL  If no Access Point reference available.
  535  */
  536 //--------------------------------------------------------------------------------------------------
  537 le_wifiClient_AccessPointRef_t le_wifiClient_GetFirstAccessPoint
  538 (
  539     void
  540 );
  541 
  542 //--------------------------------------------------------------------------------------------------
  543 /**
  544  * Get the next WiFi Access Point.
  545  * Will return the Access Points in the order of found.
  546  * This function must be called in the same context as the GetFirstAccessPoint
  547  *
  548  * @return
  549  *      - WiFi  Access Point reference if ok.
  550  *      - NULL  If no Access Point reference available.
  551  */
  552 //--------------------------------------------------------------------------------------------------
  553 le_wifiClient_AccessPointRef_t le_wifiClient_GetNextAccessPoint
  554 (
  555     void
  556 );
  557 
  558 //--------------------------------------------------------------------------------------------------
  559 /**
  560  * Get the signal strength of the AccessPoint
  561  *
  562  * @return
  563  *      - Signal strength in dBm. Example -30 = -30dBm
  564  *      - If no signal available it will return LE_WIFICLIENT_NO_SIGNAL_STRENGTH
  565  *
  566  * @note The function returns the signal strength as reported at the time of the scan.
  567  */
  568 //--------------------------------------------------------------------------------------------------
  569 int16_t le_wifiClient_GetSignalStrength
  570 (
  571     le_wifiClient_AccessPointRef_t accessPointRef
  572         ///< [IN] WiFi Access Point reference.
  573 );
  574 
  575 //--------------------------------------------------------------------------------------------------
  576 /**
  577  * Get the Basic Service set identifier (BSSID) of the AccessPoint
  578  *
  579  * @return
  580  *         LE_OK            Function succeeded.
  581  *         LE_FAULT         Function failed.
  582  *         LE_BAD_PARAMETER Invalid parameter.
  583  *         LE_OVERFLOW      bssid buffer is too small to contain the BSSID.
  584  */
  585 //--------------------------------------------------------------------------------------------------
  586 le_result_t le_wifiClient_GetBssid
  587 (
  588     le_wifiClient_AccessPointRef_t accessPointRef,
  589         ///< [IN] WiFi Access Point reference.
  590     char* bssid,
  591         ///< [OUT] The BSSID
  592     size_t bssidSize
  593         ///< [IN]
  594 );
  595 
  596 //--------------------------------------------------------------------------------------------------
  597 /**
  598  * Get the Service set identification (SSID) of the AccessPoint
  599  *
  600  * @return
  601  *        LE_OK            Function succeeded.
  602  *        LE_FAULT         Function failed.
  603  *        LE_BAD_PARAMETER Invalid parameter.
  604  *        LE_OVERFLOW      ssid buffer is too small to contain the SSID.
  605  *
  606  * @note The SSID does not have to be human readable ASCII values, but often is.
  607  */
  608 //--------------------------------------------------------------------------------------------------
  609 le_result_t le_wifiClient_GetSsid
  610 (
  611     le_wifiClient_AccessPointRef_t accessPointRef,
  612         ///< [IN] WiFi Access Point reference.
  613     uint8_t* ssidPtr,
  614         ///< [OUT] The SSID returned as a octet array.
  615     size_t* ssidSizePtr
  616         ///< [INOUT]
  617 );
  618 
  619 //--------------------------------------------------------------------------------------------------
  620 /**
  621  * Get the currently selected connection to be established
  622  *
  623  * @return
  624  *      - LE_OK upon successful retrieval of the selected SSID to be connected
  625  *      - LE_FAULT upon failure to retrieve it
  626  */
  627 //--------------------------------------------------------------------------------------------------
  628 void le_wifiClient_GetCurrentConnection
  629 (
  630     le_wifiClient_AccessPointRef_t* apRefPtr
  631         ///< [OUT] currently selected connection's AP reference
  632 );
  633 
  634 //--------------------------------------------------------------------------------------------------
  635 /**
  636  * Set the passphrase used to generate the PSK.
  637  *
  638  * @return
  639  *      - LE_OK            Function succeeded.
  640  *      - LE_FAULT         Function failed.
  641  *      - LE_BAD_PARAMETER Invalid parameter.
  642  *
  643  * @note The difference between le_wifiClient_SetPreSharedKey() and this function
  644  */
  645 //--------------------------------------------------------------------------------------------------
  646 le_result_t le_wifiClient_SetPassphrase
  647 (
  648     le_wifiClient_AccessPointRef_t accessPointRef,
  649         ///< [IN] WiFi Access Point reference.
  650     const char* LE_NONNULL PassPhrase
  651         ///< [IN] pass-phrase for PSK
  652 );
  653 
  654 //--------------------------------------------------------------------------------------------------
  655 /**
  656  * Set the Pre Shared Key, PSK.
  657  *
  658  * @return
  659  *      - LE_OK             Function succeeded.
  660  *      - LE_FAULT          Function failed.
  661  *      - LE_BAD_PARAMETER  Invalid parameter.
  662  *
  663  * @note This is one way to authenticate against the access point. The other one is provided by the
  664  * le_wifiClient_SetPassPhrase() function. Both ways are exclusive and are effective only when used
  665  * with WPA-personal authentication.
  666  */
  667 //--------------------------------------------------------------------------------------------------
  668 le_result_t le_wifiClient_SetPreSharedKey
  669 (
  670     le_wifiClient_AccessPointRef_t accessPointRef,
  671         ///< [IN] WiFi Access Point reference.
  672     const char* LE_NONNULL PreSharedKey
  673         ///< [IN] PSK. Note the difference between PSK and
  674         ///< Pass Phrase.
  675 );
  676 
  677 //--------------------------------------------------------------------------------------------------
  678 /**
  679  * Set the security protocol for connection
  680  *
  681  * @return
  682  *      - LE_OK             Function succeeded.
  683  *      - LE_FAULT          Function failed.
  684  *      - LE_BAD_PARAMETER  Invalid parameter.
  685  */
  686 //--------------------------------------------------------------------------------------------------
  687 le_result_t le_wifiClient_SetSecurityProtocol
  688 (
  689     le_wifiClient_AccessPointRef_t accessPointRef,
  690         ///< [IN] WiFi Access Point reference.
  691     le_wifiClient_SecurityProtocol_t securityProtocol
  692         ///< [IN] Security Mode
  693 );
  694 
  695 //--------------------------------------------------------------------------------------------------
  696 /**
  697  * WPA-Enterprise requires a username and password to authenticate.
  698  * This function sets these parameters.
  699  *
  700  * @return
  701  *      - LE_OK             Function succeeded.
  702  *      - LE_FAULT          Function failed.
  703  *      - LE_BAD_PARAMETER  Invalid parameter.
  704  */
  705 //--------------------------------------------------------------------------------------------------
  706 le_result_t le_wifiClient_SetUserCredentials
  707 (
  708     le_wifiClient_AccessPointRef_t accessPointRef,
  709         ///< [IN] WiFi Access Point reference.
  710     const char* LE_NONNULL userName,
  711         ///< [IN] UserName used for WPA-Enterprise.
  712     const char* LE_NONNULL password
  713         ///< [IN] Password used for WPA-Enterprise.
  714 );
  715 
  716 //--------------------------------------------------------------------------------------------------
  717 /**
  718  * Set the WEP key (WEP)
  719  *
  720  * @return
  721  *      - LE_OK     Function succeeded.
  722  *      - LE_FAULT  Function failed.
  723  */
  724 //--------------------------------------------------------------------------------------------------
  725 le_result_t le_wifiClient_SetWepKey
  726 (
  727     le_wifiClient_AccessPointRef_t accessPointRef,
  728         ///< [IN] WiFi Access Point reference.
  729     const char* LE_NONNULL wepKey
  730         ///< [IN] The WEP key
  731 );
  732 
  733 //--------------------------------------------------------------------------------------------------
  734 /**
  735  * This function specifies whether the target Access Point is hiding its presence from clients or
  736  * not. When an Access Point is hidden, it cannot be discovered by a scan process.
  737  *
  738  * @return
  739  *      - LE_OK             Function succeeded.
  740  *      - LE_BAD_PARAMETER  Invalid parameter.
  741  *
  742  * @note By default, this attribute is not set which means that the client is unable to connect to
  743  * a hidden access point. When enabled, the client will be able to connect to the access point
  744  * whether it is hidden or not.
  745  */
  746 //--------------------------------------------------------------------------------------------------
  747 le_result_t le_wifiClient_SetHiddenNetworkAttribute
  748 (
  749     le_wifiClient_AccessPointRef_t accessPointRef,
  750         ///< [IN] WiFi Access Point reference.
  751     bool hidden
  752         ///< [IN] If TRUE, the WIFI client will be able to connect to a hidden access point.
  753 );
  754 
  755 //--------------------------------------------------------------------------------------------------
  756 /**
  757  * This function creates a reference to an Access Point given its SSID.
  758  * If an Access Point is hidden, it will not show up in the scan. So, its SSID must be known
  759  * in advance in order to create a reference.
  760  *
  761  * @return
  762  *      - AccessPoint reference to the current Access Point.
  763  *
  764  * @note This function fails if called while scan is running.
  765  */
  766 //--------------------------------------------------------------------------------------------------
  767 le_wifiClient_AccessPointRef_t le_wifiClient_Create
  768 (
  769     const uint8_t* SsidPtr,
  770         ///< [IN] The SSID as a octet array.
  771     size_t SsidSize
  772         ///< [IN]
  773 );
  774 
  775 //--------------------------------------------------------------------------------------------------
  776 /**
  777  * Deletes an accessPointRef.
  778  *
  779  * @return
  780  *      - LE_OK             Function succeeded.
  781  *      - LE_BAD_PARAMETER  Invalid parameter.
  782  *      - LE_BUSY           Function called during scan.
  783  *
  784  * @note The handle becomes invalid after it has been deleted.
  785  */
  786 //--------------------------------------------------------------------------------------------------
  787 le_result_t le_wifiClient_Delete
  788 (
  789     le_wifiClient_AccessPointRef_t accessPointRef
  790         ///< [IN] WiFi Access Point reference.
  791 );
  792 
  793 //--------------------------------------------------------------------------------------------------
  794 /**
  795  * Connect to the WiFi Access Point.
  796  * All authentication must be set prior to calling this function.
  797  *
  798  * @return
  799  *      - LE_OK             Function succeeded.
  800  *      - LE_BAD_PARAMETER  Invalid parameter.
  801  *
  802  * @note For PSK credentials see le_wifiClient_SetPassphrase() or le_wifiClient_SetPreSharedKey() .
  803  * @note For WPA-Enterprise credentials see le_wifiClient_SetUserCredentials()
  804  */
  805 //--------------------------------------------------------------------------------------------------
  806 le_result_t le_wifiClient_Connect
  807 (
  808     le_wifiClient_AccessPointRef_t accessPointRef
  809         ///< [IN] WiFi Access Point reference.
  810 );
  811 
  812 //--------------------------------------------------------------------------------------------------
  813 /**
  814  * Disconnect from the current connected WiFi Access Point.
  815  *
  816  * @return
  817  *      - LE_OK     Function succeeded.
  818  *      - LE_FAULT  Function failed.
  819  */
  820 //--------------------------------------------------------------------------------------------------
  821 le_result_t le_wifiClient_Disconnect
  822 (
  823     void
  824 );
  825 
  826 //--------------------------------------------------------------------------------------------------
  827 /**
  828  * Load the given SSID's configurations as it is selected as the connection to be established,
  829  * after creating for it an AP reference
  830  *
  831  * @return
  832  *      - LE_OK     Function succeeded.
  833  *      - LE_FAULT  Function failed.
  834  *      - LE_BAD_PARAMETER  Invalid parameter.
  835  */
  836 //--------------------------------------------------------------------------------------------------
  837 le_result_t le_wifiClient_LoadSsid
  838 (
  839     const char* LE_NONNULL ssid,
  840         ///< [IN] SSID which configs are to be installed
  841     le_wifiClient_AccessPointRef_t* apRefPtr
  842         ///< [OUT] reference to be created
  843 );
  844 
  845 #endif // LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
le_wifiClient_NewEventHandlerRef_t
struct le_wifiClient_NewEventHandler * le_wifiClient_NewEventHandlerRef_t
Definition: le_wifiClient_interface.h:439
le_wifiClient_GetNextAccessPoint
le_wifiClient_AccessPointRef_t le_wifiClient_GetNextAccessPoint(void)
le_wifiClient_LoadSsid
le_result_t le_wifiClient_LoadSsid(const char *LE_NONNULL ssid, le_wifiClient_AccessPointRef_t *apRefPtr)
le_wifiClient_DisconnectHandler_t
void(* le_wifiClient_DisconnectHandler_t)(void *)
Definition: le_wifiClient_interface.h:300
le_wifiClient_ConnectService
void le_wifiClient_ConnectService(void)
le_wifiClient_GetBssid
le_result_t le_wifiClient_GetBssid(le_wifiClient_AccessPointRef_t accessPointRef, char *bssid, size_t bssidSize)
le_wifiClient_SetUserCredentials
le_result_t le_wifiClient_SetUserCredentials(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL userName, const char *LE_NONNULL password)
le_wifiClient_GetSsid
le_result_t le_wifiClient_GetSsid(le_wifiClient_AccessPointRef_t accessPointRef, uint8_t *ssidPtr, size_t *ssidSizePtr)
le_result_t
le_result_t
Definition: le_basics.h:35
le_wifiClient_Start
le_result_t le_wifiClient_Start(void)
le_wifiDefs_interface.h
LE_WIFICLIENT_EVENT_SCAN_DONE
WiFi Scan result for available Access Points available. 
Definition: le_wifiClient_interface.h:403
le_wifiClient_Stop
le_result_t le_wifiClient_Stop(void)
LE_WIFICLIENT_EVENT_DISCONNECTED
WiFi Client Disconnected. 
Definition: le_wifiClient_interface.h:401
le_wifiClient_GetSignalStrength
int16_t le_wifiClient_GetSignalStrength(le_wifiClient_AccessPointRef_t accessPointRef)
le_wifiClient_SetSecurityProtocol
le_result_t le_wifiClient_SetSecurityProtocol(le_wifiClient_AccessPointRef_t accessPointRef, le_wifiClient_SecurityProtocol_t securityProtocol)
LE_WIFICLIENT_SECURITY_NONE
no security. 
Definition: le_wifiClient_interface.h:418
le_wifiClient_SetServerDisconnectHandler
void le_wifiClient_SetServerDisconnectHandler(le_wifiClient_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_wifiClient_Event_t
le_wifiClient_Event_t
Definition: le_wifiClient_interface.h:397
le_wifiClient_SecurityProtocol_t
le_wifiClient_SecurityProtocol_t
Definition: le_wifiClient_interface.h:416
le_wifiClient_SetWepKey
le_result_t le_wifiClient_SetWepKey(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL wepKey)
LE_WIFICLIENT_SECURITY_WPA2_PSK_PERSONAL
Using WPA2. 
Definition: le_wifiClient_interface.h:424
le_wifiClient_SetHiddenNetworkAttribute
le_result_t le_wifiClient_SetHiddenNetworkAttribute(le_wifiClient_AccessPointRef_t accessPointRef, bool hidden)
le_wifiClient_Delete
le_result_t le_wifiClient_Delete(le_wifiClient_AccessPointRef_t accessPointRef)
LE_WIFICLIENT_EVENT_CONNECTED
WiFi Client Connected. 
Definition: le_wifiClient_interface.h:399
le_wifiClient_SetPreSharedKey
le_result_t le_wifiClient_SetPreSharedKey(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL PreSharedKey)
LE_WIFICLIENT_SECURITY_WPA_PSK_PERSONAL
Using WPA. 
Definition: le_wifiClient_interface.h:422
le_wifiClient_Disconnect
le_result_t le_wifiClient_Disconnect(void)
le_wifiClient_RemoveNewEventHandler
void le_wifiClient_RemoveNewEventHandler(le_wifiClient_NewEventHandlerRef_t handlerRef)
legato.h
le_wifiClient_Create
le_wifiClient_AccessPointRef_t le_wifiClient_Create(const uint8_t *SsidPtr, size_t SsidSize)
le_wifiClient_GetCurrentConnection
void le_wifiClient_GetCurrentConnection(le_wifiClient_AccessPointRef_t *apRefPtr)
LE_WIFICLIENT_SECURITY_WPA_EAP_PEAP0_ENTERPRISE
Using WPA Enterprise. 
Definition: le_wifiClient_interface.h:426
LE_WIFICLIENT_SECURITY_WPA2_EAP_PEAP0_ENTERPRISE
Using WPA2 Enterprise. 
Definition: le_wifiClient_interface.h:428
le_wifiClient_NewEventHandlerFunc_t
void(* le_wifiClient_NewEventHandlerFunc_t)(le_wifiClient_Event_t event, void *contextPtr)
Definition: le_wifiClient_interface.h:448
le_wifiClient_TryConnectService
le_result_t le_wifiClient_TryConnectService(void)
LE_WIFICLIENT_EVENT_SCAN_FAILED
WiFi Scan failed. 
Definition: le_wifiClient_interface.h:405
le_wifiClient_AccessPointRef_t
struct le_wifiClient_AccessPoint * le_wifiClient_AccessPointRef_t
Definition: le_wifiClient_interface.h:389
le_wifiClient_Scan
le_result_t le_wifiClient_Scan(void)
le_wifiClient_Connect
le_result_t le_wifiClient_Connect(le_wifiClient_AccessPointRef_t accessPointRef)
le_wifiClient_DisconnectService
void le_wifiClient_DisconnectService(void)
le_wifiClient_GetFirstAccessPoint
le_wifiClient_AccessPointRef_t le_wifiClient_GetFirstAccessPoint(void)
le_wifiClient_AddNewEventHandler
le_wifiClient_NewEventHandlerRef_t le_wifiClient_AddNewEventHandler(le_wifiClient_NewEventHandlerFunc_t handlerPtr, void *contextPtr)
le_wifiClient_SetPassphrase
le_result_t le_wifiClient_SetPassphrase(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL PassPhrase)
LE_WIFICLIENT_SECURITY_WEP
Using WEP. 
Definition: le_wifiClient_interface.h:420