le_wifiClient_interface.h

Go to the documentation of this file.
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_AddConnectionEventHandler() is to be called. The event
42  * indication contains the event type, interface name, AP bssid, and disconnection cause.
43  * - le_wifiClient_AddConnectionEventHandler(): returns the handler reference if the call went ok.
44  *
45  * @code
46  *
47  * static void EventHandler
48  * (
49  * const le_wifiClient_EventInd_t* wifiEventPtr,
50  * void *contextPtr
51  * )
52  * {
53  * switch( wifiEventPtr->event )
54  * {
55  * case LE_WIFICLIENT_EVENT_CONNECTED:
56  * {
57  * LE_INFO("WiFi Client Connected.");
58  * LE_INFO("Interface: %s, bssid: %s",
59  * &wifiEventPtr->ifName[0],
60  * &wifiEventPtr->apBssid[0]);
61  * }
62  * break;
63  * case LE_WIFICLIENT_EVENT_DISCONNECTED:
64  * {
65  * LE_INFO("WiFi Client Disconnected.");
66  * LE_INFO("Interface: %s, disconnectCause: %d",
67  * &wifiEventPtr->ifName[0],
68  * wifiEventPtr->cause);
69  * }
70  * break;
71  * case LE_WIFICLIENT_EVENT_SCAN_DONE:
72  * {
73  * LE_INFO("WiFi Client Scan is done.");
74  * MyHandleScanResult();
75  * }
76  * break;
77  * }
78  * }
79  *
80  * le_wifiClient_ConnectionEventHandlerRef_t WifiEventHandlerRef = NULL;
81  *
82  * static void MyInit
83  * (
84  * void
85  * )
86  * {
87  * le_result_t result = le_wifiClient_start();
88  *
89  * if ( LE_OK == result )
90  * {
91  * LE_INFO("WiFi Client started.");
92  * WiFiEventHandlerRef = le_wifiClient_AddConnectionEventHandler( EventHandler, NULL );
93  * }
94  * else if ( LE_BUSY == result )
95  * {
96  * LE_INFO("ERROR: WiFi Client already started.");
97  * }
98  * else
99  * {
100  * LE_INFO("ERROR: WiFi Client not started.");
101  * }
102  *
103  * }
104  *
105  * @endcode
106  *
107  *
108  * To subscribe to wifi events le_wifiClient_AddNewEventHandler() is to be called.
109  * - le_wifiClient_AddNewEventHandler(): returns the handler reference if the call went ok.
110  *
111  * @deprecated le_wifiClient_AddNewEventHandler() will be removed in near future.
112  * It will be replaced by le_wifiClient_AddConnectionEventHandler().
113  *
114  * @code
115  *
116  * static void EventHandler
117  * (
118  * le_wifiClient_Event_t clientEvent,
119  * void *contextPtr
120  * )
121  * {
122  * switch( clientEvent )
123  * {
124  * case LE_WIFICLIENT_EVENT_CONNECTED:
125  * {
126  * LE_INFO("WiFi Client Connected.");
127  * }
128  * break;
129  * case LE_WIFICLIENT_EVENT_DISCONNECTED:
130  * {
131  * LE_INFO("WiFi Client Disconnected.");
132  * }
133  * break;
134  * case LE_WIFICLIENT_EVENT_SCAN_DONE:
135  * {
136  * LE_INFO("WiFi Client Scan is done.");
137  * MyHandleScanResult();
138  * }
139  * break;
140  * }
141  * }
142  *
143  * le_wifiClient_NewEventHandler WiFiEventHandlerRef = NULL;
144  *
145  * static void MyInit
146  * (
147  * void
148  * )
149  * {
150  * le_result_t result = le_wifiClient_start();
151  *
152  * if ( LE_OK == result )
153  * {
154  * LE_INFO("WiFi Client started.");
155  * WiFiEventHandlerRef = le_wifiClient_AddNewEventHandler( EventHandler, NULL );
156  * }
157  * else if ( LE_BUSY == result )
158  * {
159  * LE_INFO("ERROR: WiFi Client already started.");
160  * }
161  * else
162  * {
163  * LE_INFO("ERROR: WiFi Client not started.");
164  * }
165  *
166  * }
167  *
168  * @endcode
169  *
170  *
171  * @section le_wifiClient_scan Scanning Access Points with WiFi Client
172  *
173  * To start a scan for Access Points, the le_wifiClient_Scan() should be called.
174  * - le_wifiClient_Scan(): returns the LE_OK if the call went ok.
175  *
176  *
177  * @section le_wifiClient_scan_result Processing the WiFi scan results
178  *
179  * Once the scan results are available, the event LE_WIFICLIENT_EVENT_SCAN_DONE is received.
180  * The found Access Points can then be gotten with
181  * - le_wifiClient_GetFirstAccessPoint(): returns the Access Point if found. Else NULL.
182  * - le_wifiClient_GetNextAccessPoint(): returns the next Access Point if found. Else NULL.
183  *
184  * The Access Points SSID, Service Set Identifier, is not a string.
185  * It does however often contain human readable ASCII values.
186  * It can be read with the following function:
187  * - le_wifiClient_GetSsid() : returns the LE_OK if the SSID was read ok.
188  *
189  * The Access Points signal strength can be read with the following function:
190  * - le_wifiClient_GetSignalStrength() : returns the signal strength in dBm of the AccessPoint
191  *
192  * @code
193  *
194  * static void MyHandleScanResult
195  * (
196  * void
197  * )
198  * {
199  * uint8 ssid[MAX_SSID_BYTES];
200  * le_wifiClient_AccessPointRef_t accessPointRef = le_wifiClient_GetFirstAccessPoint();
201  *
202  * while( NULL != accessPointRef )
203  * {
204  * result = le_wifiClient_GetSsid( accessPointRef, ssid, MAX_SSID_BYTES );
205  * if (( result == LE_OK ) && ( memcmp( ssid, "MySSID", 6) == 0 ))
206  * {
207  * LE_INFO("WiFi Client found.");
208  * break;
209  * }
210  * accessPointRef = le_wifiClient_GetNextAccessPoint();
211  * }
212  * }
213  *
214  * @endcode
215  *
216  * @section le_wifiClient_connect_to_ap Connecting to Access Point
217  *
218  * First of all, an Access Point reference should be created using the SSID of the target Access
219  * Point. Use the following function to create a reference:
220  * - le_wifiClient_Create(): returns Access Point reference
221  *
222  * To set the pass phrase prior for the Access Point use the function:
223  * - le_wifiClient_SetPassphrase(): returns the function execution status.
224  *
225  * WPA-Enterprise requires a username and password to authenticate.
226  * To set them use the function:
227  * - le_wifiClient_SetUserCredentials(): returns the function execution status.
228  *
229  * If an Access Point is hidden, it does not announce its presence and will not show up in scan.
230  * So, the SSID of this Access Point must be known in advance. Then, use the following function to
231  * allow connections to hidden Access Points:
232  * le_wifiClient_SetHiddenNetworkAttribute(): returns the function execution status.
233  *
234  * Finally and when the Access Point parameters have been configured, use the following function to
235  * attempt a connection:
236  * - le_wifiClient_Connect(): returns the function execution status.
237  *
238  * @code
239  *
240  * static void MyConnectTo
241  * (
242  * le_wifiClient_AccessPointRef_t accessPointRef
243  * )
244  * {
245  * le_result_t result;
246  * le_wifiClient_SetPassphrase ( accessPointRef, "Secret1" );
247  * result = le_wifiClient_Connect( accessPointRef );
248  * if (result == LE_OK)
249  * {
250  * LE_INFO("Connecting to AP.");
251  * }
252  * }
253  *
254  * @endcode
255  *
256  * @section le_wifiClient_config_ssid_security Configure security protocol
257  *
258  * The Wifi security configurations are SSID-based so that different SSIDs or Wifi networks can
259  * employ different security protocols independently. The following subsections explain the
260  * wifiClient APIs that can be used to configure the supported security protocols onto an SSID.
261  * The currently supported Wifi security protocols are:
262  * - No or open security.
263  * - WEP,
264  * - WPA PSK and WPA2 PSK,
265  * - WPA EAP PEAP and WPA2 EAP PEAP.
266  *
267  * To ensure high confidentiality, all configured credentials including any keys, usernames,
268  * passwords, phrases, secrets, etc., are stored in Legato's secured storage. There they are
269  * encrypted and can only be accessed by the wifiClient component. But to allow easy cross-checking
270  * and debugging of non-confidential Wifi configurations, an SSID's configured security protocol is
271  * still saved on the config tree under the same path as for other Wifi configurations, i.e.
272  * "dataConnectionService:/wifi/channel/<ssid>/secProtocol" as in the following example. Note that
273  * an application doesn't need to explicitly set this onto the config tree itself, but can use the
274  * APIs to be explained in the upcoming subsections for configuring security to complete this step.
275  *
276  * root@swi-mdm9x28:~# config get wifiService:/wifi/
277  * wifi/
278  * channel/
279  * MY-MOBILE/
280  * secProtocol<string> == 2
281  * hidden<bool> == false
282  * MY-WLAN/
283  * secProtocol<string> == 3
284  * hidden<bool> == true
285  *
286  * @subsection le_wifiClient_config_ssid_nosecurity Clear security
287  *
288  * The le_wifiClient_RemoveSsidSecurityConfigs() function can be used for the following purposes:
289  * - Reset the security protocol type to use no security, i.e. LE_WIFICLIENT_SECURITY_NONE,
290  * - Remove any previously installed Wifi security configurations including security protocol
291  * type and any user credentials.
292  *
293  * The following is an example of how to use this API:
294  *
295  * @code
296  * le_result_t ret = le_wifiClient_RemoveSsidSecurityConfigs(ssid, sizeof(ssid));
297  * if ((ret != LE_OK) && (ret != LE_NOT_FOUND))
298  * {
299  * LE_ERROR("Failed to clear Wifi security configs; retcode %d", ret);
300  * }
301  * else
302  * {
303  * LE_INFO("Succeeded clearing Wifi security configs");
304  * }
305  * @endcode
306  *
307  * @subsection le_wifiClient_config_ssid_wep Configure an SSID with WEP
308  *
309  * The API for configuring a given SSID to use WEP is le_wifiClient_ConfigureWep(). It will set
310  * WEP as the security protocol used for this SSID and saved the provided WEP key into secured
311  * storage for its later use via le_wifiClient_LoadSsid().
312  *
313  * The following is an example of how to use this API. The wepKey input has to be non-null.
314  *
315  * @code
316  * le_wifiClient_AccessPointRef_t ref;
317  * ret = le_wifiClient_ConfigureWep(ssid, sizeof(ssid), wepKey, sizeof(wepKey));
318  * if (ret != LE_OK)
319  * {
320  * LE_ERROR("Failed to configure WEP into secStore; retcode %d", ret);
321  * }
322  * else
323  * {
324  * ret = le_wifiClient_LoadSsid(ssid, sizeof(ssid), &ref);
325  * if (ret != LE_OK)
326  * {
327  * LE_ERROR("LoadSsid failed over WEP; retcode %d", ret);
328  * }
329  * else
330  * {
331  * le_wifiClient_Delete(ref);
332  * ref = NULL;
333  * }
334  * }
335  * @endcode
336  *
337  * @subsection le_wifiClient_config_ssid_psk Configure an SSID with PSK
338  *
339  * The API for configuring a given SSID to use WPA or WPA2 PSK is le_wifiClient_ConfigurePsk().
340  * It will set this security protocoly type as the one used for this SSID and saved the provided
341  * credentials into secured storage for its later use via le_wifiClient_LoadSsid().
342  *
343  * With this protocol type, either a pass phrase or a pre-shared key has to be provided. If both
344  * are provided, pass-phrase has precedence and will be used. But it fails to authenticate during
345  * a connect attempt, wifiClient will not do a second attempt using an available pre-shared key.
346  *
347  * The following is an example of how to use this API. The passphrase input has to be non-null.
348  *
349  * @code
350  * le_wifiClient_AccessPointRef_t ref;
351  * ret = le_wifiClient_ConfigurePsk(ssid, sizeof(ssid), LE_WIFICLIENT_SECURITY_WPA_PSK_PERSONAL,
352  * passphrase, sizeof(passphrase), NULL, 0);
353  * if (ret != LE_OK)
354  * {
355  * LE_ERROR("Failed to configure WPA passphrase into secStore; retcode %d", ret);
356  * }
357  * else
358  * {
359  * ret = le_wifiClient_LoadSsid(ssid, sizeof(ssid), &ref);
360  * if (ret != LE_OK)
361  * {
362  * LE_ERROR("LoadSsid failed over WPA passphrase; retcode %d", ret);
363  * }
364  * else
365  * {
366  * le_wifiClient_Delete(ref);
367  * ref = NULL;
368  * }
369  * }
370  * @endcode
371  *
372  * @subsection le_wifiClient_config_ssid_eap Configure an SSID with EAP
373  *
374  * The API for configuring a given SSID to use WPA or WPA2 EAP is le_wifiClient_ConfigureEap().
375  * It will set this security protocoly type as the one used for this SSID and saved the provided
376  * user name and password into secured storage for its later use via le_wifiClient_LoadSsid().
377  *
378  * The following is an example of how to use this API. Both the user name and password inputs have
379  * to be non-null.
380  *
381  * @code
382  * le_wifiClient_AccessPointRef_t ref;
383  * ret = le_wifiClient_ConfigureEap(ssid, sizeof(ssid),
384  * LE_WIFICLIENT_SECURITY_WPA2_EAP_PEAP0_ENTERPRISE,
385  * username, sizeof(username), password, sizeof(password));
386  * if (ret != LE_OK)
387  * {
388  * LE_ERROR("Failed to configure WPA2 EAP into secStore; retcode %d", ret);
389  * }
390  * else
391  * {
392  * ret = le_wifiClient_LoadSsid(ssid, sizeof(ssid), &ref);
393  * if (ret != LE_OK)
394  * {
395  * LE_ERROR("LoadSsid failed over WPA2 EAP; retcode %d", ret);
396  * }
397  * else
398  * {
399  * le_wifiClient_Delete(ref);
400  * ref = NULL;
401  * }
402  * }
403  * @endcode
404  *
405  * @section le_wifiClient_config_ssid Configure Wifi client with an SSID
406  *
407  * Before a Wifi connection can be established over an SSID via le_wifiClient_Connect(), a few
408  * preparations have to be first done. The following are the ones that can be done via the
409  * le_wifiClient_LoadSsid() function in this component:
410  * - Have the SSID selected: The SSID provided in this function's input argument is considered
411  * the one selected for establishing the Wifi connection.
412  * - Load the pre-configured Wifi security configurations into wifiClient: These include the
413  * security protocol type and its involved user credentials, e.g. WEP key for WEP, pass phrase or
414  * pre-shared key for PSK, user name and password for EAP.
415  * - Load other pre-configured Wifi configuration: So far there is only the Wifi hidden attribute
416  * pre-configured via le_wifiClient_SetHiddenNetworkAttribute().
417  * - Create an AP object reference: This reference is created for this given and configured SSID.
418  * And it is to be returned to the API caller in its output argument so that it can be used as
419  * the reference for subsequent connection operations including connecting, disconnecting, etc.
420  *
421  * The following is a sample code to illustrate how this API can be used:
422  *
423  * @code
424  *
425  * le_result_t ret = le_wifiClient_LoadSsid(ssid, strlen(ssid), &apRef);
426  * if (ret == LE_OK)
427  * {
428  * LE_DEBUG("Wifi configs installed to connect over SSID %s with AP reference %p",
429  * ssid, apRef);
430  * }
431  * else
432  * {
433  * LE_ERROR("Failed to install wifi configs to connect over SSID %s", ssid);
434  * }
435  *
436  * @endcode
437  *
438  * @section le_wifiClient_get_current_connect Get the currently selected connection
439  *
440  * A selected SSID via its AP reference is set for use in Wifi connection establishment since
441  * the API call to le_wifiClient_Connect(). Note that while the input argument is actually an
442  * Access Point reference, this reference specifically refers to a given SSID on the device.
443  * This is considered the selected connection for use until le_wifiClient_Disconnect() is called
444  * to deselect it.
445  *
446  * During the time when this AP reference is set for use, there comes the need to be able to query
447  * le_wifiClient for it back. This is what this le_wifiClient_GetCurrentConnection() API seeks to
448  * return. The following is a sample code to illustrate how it can be used. The retrieved AP
449  * reference is returned in the output argument.
450  *
451  * @code
452  *
453  * le_wifiClient_GetCurrentConnection(&apRef);
454  * if (!apRef)
455  * {
456  * return;
457  * }
458  * ret = le_wifiClient_GetSsid(apRef, &ssid[0], &ssidSize);
459  * if (LE_OK != ret)
460  * {
461  * LE_ERROR("Failed to find SSID of AP reference %p", apRef);
462  * return;
463  * }
464  * ssid[ssidSize] = '\0';
465  * LE_DEBUG("Found currently selected Wifi connection to get established: %s, reference %p",
466  * ssid, apRef);
467  *
468  * @endcode
469  *
470  *
471  * <HR>
472  *
473  * Copyright (C) Sierra Wireless Inc.
474  */
475 /**
476  * @file le_wifiClient_interface.h
477  *
478  * Legato @ref c_le_wifi_client include file.
479  *
480  * Copyright (C) Sierra Wireless Inc.
481  */
482 
483 #ifndef LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
484 #define LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
485 
486 
487 #include "legato.h"
488 
489 // Interface specific includes
490 #include "le_wifiDefs_interface.h"
491 
492 // Internal includes for this interface
493 #include "le_wifiClient_common.h"
494 //--------------------------------------------------------------------------------------------------
495 /**
496  * Type for handler called when a server disconnects.
497  */
498 //--------------------------------------------------------------------------------------------------
499 typedef void (*le_wifiClient_DisconnectHandler_t)(void *);
500 
501 //--------------------------------------------------------------------------------------------------
502 /**
503  *
504  * Connect the current client thread to the service providing this API. Block until the service is
505  * available.
506  *
507  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
508  * called before any other functions in this API. Normally, ConnectService is automatically called
509  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
510  *
511  * This function is created automatically.
512  */
513 //--------------------------------------------------------------------------------------------------
515 (
516  void
517 );
518 
519 //--------------------------------------------------------------------------------------------------
520 /**
521  *
522  * Try to connect the current client thread to the service providing this API. Return with an error
523  * if the service is not available.
524  *
525  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
526  * called before any other functions in this API. Normally, ConnectService is automatically called
527  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
528  *
529  * This function is created automatically.
530  *
531  * @return
532  * - LE_OK if the client connected successfully to the service.
533  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
534  * bound.
535  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
536  * - LE_COMM_ERROR if the Service Directory cannot be reached.
537  */
538 //--------------------------------------------------------------------------------------------------
540 (
541  void
542 );
543 
544 //--------------------------------------------------------------------------------------------------
545 /**
546  * Set handler called when server disconnection is detected.
547  *
548  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
549  * to continue without exiting, it should call longjmp() from inside the handler.
550  */
551 //--------------------------------------------------------------------------------------------------
553 (
554  le_wifiClient_DisconnectHandler_t disconnectHandler,
555  void *contextPtr
556 );
557 
558 //--------------------------------------------------------------------------------------------------
559 /**
560  *
561  * Disconnect the current client thread from the service providing this API.
562  *
563  * Normally, this function doesn't need to be called. After this function is called, there's no
564  * longer a connection to the service, and the functions in this API can't be used. For details, see
565  * @ref apiFilesC_client.
566  *
567  * This function is created automatically.
568  */
569 //--------------------------------------------------------------------------------------------------
571 (
572  void
573 );
574 
575 
576 //--------------------------------------------------------------------------------------------------
577 /**
578  * Reference type for AccessPoint that is returned by the WiFi Scan.
579  */
580 //--------------------------------------------------------------------------------------------------
581 
582 
583 //--------------------------------------------------------------------------------------------------
584 /**
585  * WiFi Client Events.
586  */
587 //--------------------------------------------------------------------------------------------------
588 
589 
590 //--------------------------------------------------------------------------------------------------
591 /**
592  * WiFi Client disconnect cause type enum.
593  */
594 //--------------------------------------------------------------------------------------------------
595 
596 
597 //--------------------------------------------------------------------------------------------------
598 /**
599  * WiFi Client Security Protocol for connection
600  */
601 //--------------------------------------------------------------------------------------------------
602 
603 
604 //--------------------------------------------------------------------------------------------------
605 /**
606  * Handler for WiFi Client changes
607  * @deprecated le_wifiClient_AddNewEventHandler() will be removed in near future.
608  * It is replaced by le_wifiClient_AddConnectionEventHandler().
609  */
610 //--------------------------------------------------------------------------------------------------
611 
612 
613 //--------------------------------------------------------------------------------------------------
614 /**
615  * Reference type used by Add/Remove functions for EVENT 'le_wifiClient_NewEvent'
616  */
617 //--------------------------------------------------------------------------------------------------
618 
619 
620 //--------------------------------------------------------------------------------------------------
621 /**
622  * WiFi event indication structure. The disconnectionCause only applies to event EVENT_DISCONNECTED.
623  */
624 //--------------------------------------------------------------------------------------------------
625 
626 
627 //--------------------------------------------------------------------------------------------------
628 /**
629  * Handler for WiFi Client connection changes
630  */
631 //--------------------------------------------------------------------------------------------------
632 
633 
634 //--------------------------------------------------------------------------------------------------
635 /**
636  * Reference type used by Add/Remove functions for EVENT 'le_wifiClient_ConnectionEvent'
637  */
638 //--------------------------------------------------------------------------------------------------
639 
640 
641 //--------------------------------------------------------------------------------------------------
642 /**
643  * Add handler function for EVENT 'le_wifiClient_NewEvent'
644  *
645  * This event provide information on WiFi Client event changes.
646  * NewEvent will be deprecated.
647  *
648  */
649 //--------------------------------------------------------------------------------------------------
650 le_wifiClient_NewEventHandlerRef_t le_wifiClient_AddNewEventHandler
651 (
652  le_wifiClient_NewEventHandlerFunc_t handlerPtr,
653  ///< [IN]
654  void* contextPtr
655  ///< [IN]
656 );
657 
658 //--------------------------------------------------------------------------------------------------
659 /**
660  * Remove handler function for EVENT 'le_wifiClient_NewEvent'
661  */
662 //--------------------------------------------------------------------------------------------------
664 (
665  le_wifiClient_NewEventHandlerRef_t handlerRef
666  ///< [IN]
667 );
668 
669 //--------------------------------------------------------------------------------------------------
670 /**
671  * Add handler function for EVENT 'le_wifiClient_ConnectionEvent'
672  *
673  * This event provide information on WiFi Client connection event changes.
674  *
675  */
676 //--------------------------------------------------------------------------------------------------
677 le_wifiClient_ConnectionEventHandlerRef_t le_wifiClient_AddConnectionEventHandler
678 (
679  le_wifiClient_ConnectionEventHandlerFunc_t handlerPtr,
680  ///< [IN]
681  void* contextPtr
682  ///< [IN]
683 );
684 
685 //--------------------------------------------------------------------------------------------------
686 /**
687  * Remove handler function for EVENT 'le_wifiClient_ConnectionEvent'
688  */
689 //--------------------------------------------------------------------------------------------------
691 (
692  le_wifiClient_ConnectionEventHandlerRef_t handlerRef
693  ///< [IN]
694 );
695 
696 //--------------------------------------------------------------------------------------------------
697 /**
698  * Start the WIFI device.
699  *
700  * @return
701  * - LE_OK Function succeeded.
702  * - LE_FAULT Function failed.
703  * - LE_BUSY The WIFI device is already started.
704  */
705 //--------------------------------------------------------------------------------------------------
707 (
708  void
709 );
710 
711 //--------------------------------------------------------------------------------------------------
712 /**
713  * Stop the WIFI device.
714  *
715  * @return
716  * - LE_OK Function succeeded.
717  * - LE_FAULT Function failed.
718  * - LE_DUPLICATE The WIFI device is already stopped.
719  */
720 //--------------------------------------------------------------------------------------------------
722 (
723  void
724 );
725 
726 //--------------------------------------------------------------------------------------------------
727 /**
728  * Start Scanning for WiFi Access points
729  * Will result in event LE_WIFICLIENT_EVENT_SCAN_DONE when the scan results are available.
730  *
731  * @return
732  * - LE_OK Function succeeded.
733  * - LE_FAULT Function failed.
734  * - LE_BUSY Scan already running.
735  */
736 //--------------------------------------------------------------------------------------------------
738 (
739  void
740 );
741 
742 //--------------------------------------------------------------------------------------------------
743 /**
744  * Get the first WiFi Access Point found.
745  *
746  * @return
747  * - WiFi Access Point reference if ok.
748  * - NULL If no Access Point reference available.
749  */
750 //--------------------------------------------------------------------------------------------------
751 le_wifiClient_AccessPointRef_t le_wifiClient_GetFirstAccessPoint
752 (
753  void
754 );
755 
756 //--------------------------------------------------------------------------------------------------
757 /**
758  * Get the next WiFi Access Point.
759  * Will return the Access Points in the order of found.
760  * This function must be called in the same context as the GetFirstAccessPoint
761  *
762  * @return
763  * - WiFi Access Point reference if ok.
764  * - NULL If no Access Point reference available.
765  */
766 //--------------------------------------------------------------------------------------------------
767 le_wifiClient_AccessPointRef_t le_wifiClient_GetNextAccessPoint
768 (
769  void
770 );
771 
772 //--------------------------------------------------------------------------------------------------
773 /**
774  * Get the signal strength of the AccessPoint
775  *
776  * @return
777  * - Signal strength in dBm. Example -30 = -30dBm
778  * - If no signal available it will return LE_WIFICLIENT_NO_SIGNAL_STRENGTH
779  *
780  * @note The function returns the signal strength as reported at the time of the scan.
781  */
782 //--------------------------------------------------------------------------------------------------
784 (
785  le_wifiClient_AccessPointRef_t accessPointRef
786  ///< [IN] WiFi Access Point reference.
787 );
788 
789 //--------------------------------------------------------------------------------------------------
790 /**
791  * Get the Basic Service set identifier (BSSID) of the AccessPoint
792  *
793  * @return
794  * LE_OK Function succeeded.
795  * LE_FAULT Function failed.
796  * LE_BAD_PARAMETER Invalid parameter.
797  * LE_OVERFLOW bssid buffer is too small to contain the BSSID.
798  */
799 //--------------------------------------------------------------------------------------------------
801 (
802  le_wifiClient_AccessPointRef_t accessPointRef,
803  ///< [IN] WiFi Access Point reference.
804  char* bssid,
805  ///< [OUT] The BSSID
806  size_t bssidSize
807  ///< [IN]
808 );
809 
810 //--------------------------------------------------------------------------------------------------
811 /**
812  * Get the Service set identification (SSID) of the AccessPoint
813  *
814  * @return
815  * LE_OK Function succeeded.
816  * LE_FAULT Function failed.
817  * LE_BAD_PARAMETER Invalid parameter.
818  * LE_OVERFLOW ssid buffer is too small to contain the SSID.
819  *
820  * @note The SSID does not have to be human readable ASCII values, but often is.
821  */
822 //--------------------------------------------------------------------------------------------------
824 (
825  le_wifiClient_AccessPointRef_t accessPointRef,
826  ///< [IN] WiFi Access Point reference.
827  uint8_t* ssidPtr,
828  ///< [OUT] The SSID returned as a octet array.
829  size_t* ssidSizePtr
830  ///< [INOUT]
831 );
832 
833 //--------------------------------------------------------------------------------------------------
834 /**
835  * Get the currently selected connection to be established
836  *
837  * @return
838  * - LE_OK upon successful retrieval of the selected SSID to be connected
839  * - LE_FAULT upon failure to retrieve it
840  */
841 //--------------------------------------------------------------------------------------------------
843 (
844  le_wifiClient_AccessPointRef_t* apRefPtr
845  ///< [OUT] currently selected connection's AP reference
846 );
847 
848 //--------------------------------------------------------------------------------------------------
849 /**
850  * Set the passphrase used to generate the PSK.
851  *
852  * @return
853  * - LE_OK Function succeeded.
854  * - LE_FAULT Function failed.
855  * - LE_BAD_PARAMETER Invalid parameter.
856  *
857  * @note The difference between le_wifiClient_SetPreSharedKey() and this function
858  */
859 //--------------------------------------------------------------------------------------------------
861 (
862  le_wifiClient_AccessPointRef_t accessPointRef,
863  ///< [IN] WiFi Access Point reference.
864  const char* LE_NONNULL PassPhrase
865  ///< [IN] pass-phrase for PSK
866 );
867 
868 //--------------------------------------------------------------------------------------------------
869 /**
870  * Set the Pre Shared Key, PSK.
871  *
872  * @return
873  * - LE_OK Function succeeded.
874  * - LE_FAULT Function failed.
875  * - LE_BAD_PARAMETER Invalid parameter.
876  *
877  * @note This is one way to authenticate against the access point. The other one is provided by the
878  * le_wifiClient_SetPassPhrase() function. Both ways are exclusive and are effective only when used
879  * with WPA-personal authentication.
880  */
881 //--------------------------------------------------------------------------------------------------
883 (
884  le_wifiClient_AccessPointRef_t accessPointRef,
885  ///< [IN] WiFi Access Point reference.
886  const char* LE_NONNULL PreSharedKey
887  ///< [IN] PSK. Note the difference between PSK and
888  ///< Pass Phrase.
889 );
890 
891 //--------------------------------------------------------------------------------------------------
892 /**
893  * Set the security protocol for connection
894  *
895  * @return
896  * - LE_OK Function succeeded.
897  * - LE_FAULT Function failed.
898  * - LE_BAD_PARAMETER Invalid parameter.
899  */
900 //--------------------------------------------------------------------------------------------------
902 (
903  le_wifiClient_AccessPointRef_t accessPointRef,
904  ///< [IN] WiFi Access Point reference.
905  le_wifiClient_SecurityProtocol_t securityProtocol
906  ///< [IN] Security Mode
907 );
908 
909 //--------------------------------------------------------------------------------------------------
910 /**
911  * WPA-Enterprise requires a username and password to authenticate.
912  * This function sets these parameters.
913  *
914  * @return
915  * - LE_OK Function succeeded.
916  * - LE_FAULT Function failed.
917  * - LE_BAD_PARAMETER Invalid parameter.
918  */
919 //--------------------------------------------------------------------------------------------------
921 (
922  le_wifiClient_AccessPointRef_t accessPointRef,
923  ///< [IN] WiFi Access Point reference.
924  const char* LE_NONNULL userName,
925  ///< [IN] UserName used for WPA-Enterprise.
926  const char* LE_NONNULL password
927  ///< [IN] Password used for WPA-Enterprise.
928 );
929 
930 //--------------------------------------------------------------------------------------------------
931 /**
932  * Set the WEP key (WEP)
933  *
934  * @return
935  * - LE_OK Function succeeded.
936  * - LE_FAULT Function failed.
937  */
938 //--------------------------------------------------------------------------------------------------
940 (
941  le_wifiClient_AccessPointRef_t accessPointRef,
942  ///< [IN] WiFi Access Point reference.
943  const char* LE_NONNULL wepKey
944  ///< [IN] The WEP key
945 );
946 
947 //--------------------------------------------------------------------------------------------------
948 /**
949  * This function specifies whether the target Access Point is hiding its presence from clients or
950  * not. When an Access Point is hidden, it cannot be discovered by a scan process.
951  *
952  * @return
953  * - LE_OK Function succeeded.
954  * - LE_BAD_PARAMETER Invalid parameter.
955  *
956  * @note By default, this attribute is not set which means that the client is unable to connect to
957  * a hidden access point. When enabled, the client will be able to connect to the access point
958  * whether it is hidden or not.
959  */
960 //--------------------------------------------------------------------------------------------------
962 (
963  le_wifiClient_AccessPointRef_t accessPointRef,
964  ///< [IN] WiFi Access Point reference.
965  bool hidden
966  ///< [IN] If TRUE, the WIFI client will be able to connect to a hidden access point.
967 );
968 
969 //--------------------------------------------------------------------------------------------------
970 /**
971  * This function creates a reference to an Access Point given its SSID.
972  * If an Access Point is hidden, it will not show up in the scan. So, its SSID must be known
973  * in advance in order to create a reference.
974  *
975  * @return
976  * - AccessPoint reference to the current Access Point.
977  *
978  * @note This function fails if called while scan is running.
979  */
980 //--------------------------------------------------------------------------------------------------
981 le_wifiClient_AccessPointRef_t le_wifiClient_Create
982 (
983  const uint8_t* SsidPtr,
984  ///< [IN] The SSID as a octet array.
985  size_t SsidSize
986  ///< [IN]
987 );
988 
989 //--------------------------------------------------------------------------------------------------
990 /**
991  * Deletes an accessPointRef.
992  *
993  * @return
994  * - LE_OK Function succeeded.
995  * - LE_BAD_PARAMETER Invalid parameter.
996  * - LE_BUSY Function called during scan.
997  *
998  * @note The handle becomes invalid after it has been deleted.
999  */
1000 //--------------------------------------------------------------------------------------------------
1002 (
1003  le_wifiClient_AccessPointRef_t accessPointRef
1004  ///< [IN] WiFi Access Point reference.
1005 );
1006 
1007 //--------------------------------------------------------------------------------------------------
1008 /**
1009  * Connect to the WiFi Access Point.
1010  * All authentication must be set prior to calling this function.
1011  *
1012  * @return
1013  * - LE_OK Function succeeded.
1014  * - LE_BAD_PARAMETER Invalid parameter.
1015  *
1016  * @note For PSK credentials see le_wifiClient_SetPassphrase() or le_wifiClient_SetPreSharedKey() .
1017  * @note For WPA-Enterprise credentials see le_wifiClient_SetUserCredentials()
1018  */
1019 //--------------------------------------------------------------------------------------------------
1021 (
1022  le_wifiClient_AccessPointRef_t accessPointRef
1023  ///< [IN] WiFi Access Point reference.
1024 );
1025 
1026 //--------------------------------------------------------------------------------------------------
1027 /**
1028  * Disconnect from the current connected WiFi Access Point.
1029  *
1030  * @return
1031  * - LE_OK Function succeeded.
1032  * - LE_FAULT Function failed.
1033  */
1034 //--------------------------------------------------------------------------------------------------
1036 (
1037  void
1038 );
1039 
1040 //--------------------------------------------------------------------------------------------------
1041 /**
1042  * Load the given SSID's configurations as it is selected as the connection to be established,
1043  * after creating for it an AP reference
1044  *
1045  * @return
1046  * - LE_OK Function succeeded.
1047  * - LE_FAULT Function failed.
1048  * - LE_BAD_PARAMETER Invalid parameter.
1049  */
1050 //--------------------------------------------------------------------------------------------------
1052 (
1053  const uint8_t* ssidPtr,
1054  ///< [IN] SSID which configs are to be installed
1055  size_t ssidSize,
1056  ///< [IN]
1057  le_wifiClient_AccessPointRef_t* apRefPtr
1058  ///< [OUT] reference to be created
1059 );
1060 
1061 //--------------------------------------------------------------------------------------------------
1062 /**
1063  * Configure the given SSID to use WEP and the given WEP key in the respective input argument.
1064  * The WEP key is a mandatory input to be provided.
1065  *
1066  * @return
1067  * - LE_OK Succeeded to configure the givwn WEP key for the given SSID.
1068  * - LE_FAULT Failed to configure.
1069  * - LE_BAD_PARAMETER Invalid parameter.
1070  */
1071 //--------------------------------------------------------------------------------------------------
1073 (
1074  const uint8_t* ssidPtr,
1075  ///< [IN] SSID which configs are to be installed
1076  size_t ssidSize,
1077  ///< [IN]
1078  const uint8_t* wepKeyPtr,
1079  ///< [IN] WEP key used for this SSID
1080  size_t wepKeySize
1081  ///< [IN]
1082 );
1083 
1084 //--------------------------------------------------------------------------------------------------
1085 /**
1086  * Configure the given SSID to use PSK and the given pass-phrase or pre-shared key in the
1087  * respective input arguments. The protocol input is mandatory and has to be set to either
1088  * LE_WIFICLIENT_SECURITY_WPA_PSK_PERSONAL or LE_WIFICLIENT_SECURITY_WPA2_PSK_PERSONAL.
1089  * Besides, it's mandatory to have at least one of the pass-phrase and pre-shared key supplied. If
1090  * both are provided as input, the pass-phrase has precedence and will be used. But it fails to
1091  * authenticate, a second attempt using the provided pre-shared key will not be done.
1092  *
1093  * @return
1094  * - LE_OK Succeeded to configure the given pass-phrase or pre-shared key for the given
1095  * SSID.
1096  * - LE_FAULT Failed to configure.
1097  * - LE_BAD_PARAMETER Invalid parameter.
1098  */
1099 //--------------------------------------------------------------------------------------------------
1101 (
1102  const uint8_t* ssidPtr,
1103  ///< [IN] SSID which configs are to be installed
1104  size_t ssidSize,
1105  ///< [IN]
1106  le_wifiClient_SecurityProtocol_t protocol,
1107  ///< [IN] security protocol WPA-PSK or WPA2-PSK
1108  const uint8_t* passPhrasePtr,
1109  ///< [IN] pass-phrase used for this SSID
1110  size_t passPhraseSize,
1111  ///< [IN]
1112  const uint8_t* pskPtr,
1113  ///< [IN] pre-shared key used for this SSID
1114  size_t pskSize
1115  ///< [IN]
1116 );
1117 
1118 //--------------------------------------------------------------------------------------------------
1119 /**
1120  * Configure the given SSID to use EAP and the given EAP username and password in the respective
1121  * input arguments. The protocol input is mandatory and has to be set to either
1122  * LE_WIFICLIENT_SECURITY_WPA_EAP_PEAP0_ENTERPRISE or
1123  * LE_WIFICLIENT_SECURITY_WPA2_EAP_PEAP0_ENTERPRISE. Besides, both the username and password inputs
1124  * are mandatory.
1125  *
1126  * @return
1127  * - LE_OK Succeeded to configure the given EAP username and password for the given
1128  * SSID.
1129  * - LE_FAULT Failed to configure.
1130  * - LE_BAD_PARAMETER Invalid parameter.
1131  */
1132 //--------------------------------------------------------------------------------------------------
1134 (
1135  const uint8_t* ssidPtr,
1136  ///< [IN] SSID which configs are to be installed
1137  size_t ssidSize,
1138  ///< [IN]
1139  le_wifiClient_SecurityProtocol_t protocol,
1140  ///< [IN] security protocol WPA-EAP or WPA2-EAP
1141  const uint8_t* usernamePtr,
1142  ///< [IN] EAP username used for this SSID
1143  size_t usernameSize,
1144  ///< [IN]
1145  const uint8_t* passwordPtr,
1146  ///< [IN] EAP password used for this SSID
1147  size_t passwordSize
1148  ///< [IN]
1149 );
1150 
1151 //--------------------------------------------------------------------------------------------------
1152 /**
1153  * Remove and clear Wifi's security configurations to use with the given SSID from the config tree
1154  * and secured store. This includes the security protocol and all the username, password,
1155  * passphrase, pre-shared key, key, etc., previously configured via le_wifiClient_Configure APIs for
1156  * WEP, PSK and EAP.
1157  *
1158  * @return
1159  * - LE_OK upon success to deconfigure the given SSID's configured user credentials;
1160  * LE_FAULT otherwise
1161  */
1162 //--------------------------------------------------------------------------------------------------
1164 (
1165  const uint8_t* ssidPtr,
1166  ///< [IN] SSID which user credentials to be deconfigured
1167  size_t ssidSize
1168  ///< [IN]
1169 );
1170 
1171 #endif // LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
le_result_t le_wifiClient_RemoveSsidSecurityConfigs(const uint8_t *ssidPtr, size_t ssidSize)
le_result_t le_wifiClient_ConfigureWep(const uint8_t *ssidPtr, size_t ssidSize, const uint8_t *wepKeyPtr, size_t wepKeySize)
le_wifiClient_AccessPointRef_t le_wifiClient_GetNextAccessPoint(void)
void(* le_wifiClient_DisconnectHandler_t)(void *)
Definition: le_wifiClient_interface.h:499
void le_wifiClient_ConnectService(void)
le_result_t le_wifiClient_GetBssid(le_wifiClient_AccessPointRef_t accessPointRef, char *bssid, size_t bssidSize)
le_result_t le_wifiClient_SetUserCredentials(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL userName, const char *LE_NONNULL password)
le_result_t le_wifiClient_GetSsid(le_wifiClient_AccessPointRef_t accessPointRef, uint8_t *ssidPtr, size_t *ssidSizePtr)
le_result_t le_wifiClient_ConfigureEap(const uint8_t *ssidPtr, size_t ssidSize, le_wifiClient_SecurityProtocol_t protocol, const uint8_t *usernamePtr, size_t usernameSize, const uint8_t *passwordPtr, size_t passwordSize)
le_result_t
Definition: le_basics.h:35
le_result_t le_wifiClient_LoadSsid(const uint8_t *ssidPtr, size_t ssidSize, le_wifiClient_AccessPointRef_t *apRefPtr)
le_result_t le_wifiClient_Start(void)
void le_wifiClient_RemoveConnectionEventHandler(le_wifiClient_ConnectionEventHandlerRef_t handlerRef)
le_result_t le_wifiClient_Stop(void)
int16_t le_wifiClient_GetSignalStrength(le_wifiClient_AccessPointRef_t accessPointRef)
le_result_t le_wifiClient_SetSecurityProtocol(le_wifiClient_AccessPointRef_t accessPointRef, le_wifiClient_SecurityProtocol_t securityProtocol)
le_result_t le_wifiClient_SetWepKey(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL wepKey)
le_result_t le_wifiClient_SetHiddenNetworkAttribute(le_wifiClient_AccessPointRef_t accessPointRef, bool hidden)
le_result_t le_wifiClient_Delete(le_wifiClient_AccessPointRef_t accessPointRef)
le_result_t le_wifiClient_SetPreSharedKey(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL PreSharedKey)
le_result_t le_wifiClient_Disconnect(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
void le_wifiClient_RemoveNewEventHandler(le_wifiClient_NewEventHandlerRef_t handlerRef)
LE_FULL_API void le_wifiClient_SetServerDisconnectHandler(le_wifiClient_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_wifiClient_AccessPointRef_t le_wifiClient_Create(const uint8_t *SsidPtr, size_t SsidSize)
void le_wifiClient_GetCurrentConnection(le_wifiClient_AccessPointRef_t *apRefPtr)
le_result_t le_wifiClient_TryConnectService(void)
le_result_t le_wifiClient_ConfigurePsk(const uint8_t *ssidPtr, size_t ssidSize, le_wifiClient_SecurityProtocol_t protocol, const uint8_t *passPhrasePtr, size_t passPhraseSize, const uint8_t *pskPtr, size_t pskSize)
le_result_t le_wifiClient_Scan(void)
le_wifiClient_ConnectionEventHandlerRef_t le_wifiClient_AddConnectionEventHandler(le_wifiClient_ConnectionEventHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_wifiClient_Connect(le_wifiClient_AccessPointRef_t accessPointRef)
void le_wifiClient_DisconnectService(void)
le_wifiClient_AccessPointRef_t le_wifiClient_GetFirstAccessPoint(void)
le_wifiClient_NewEventHandlerRef_t le_wifiClient_AddNewEventHandler(le_wifiClient_NewEventHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_wifiClient_SetPassphrase(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL PassPhrase)