le_wifiClient_interface.h

Go to the documentation of this file.
1 /*
2  * ====================== WARNING ======================
3  *
4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
5  * DO NOT MODIFY IN ANY WAY.
6  *
7  * ====================== WARNING ======================
8  */
9 
10 /**
11  * @page c_le_wifi_client WiFi Client Service
12  *
13  * @ref le_wifiClient_interface.h "API Reference"
14  *
15  * <HR>
16  *
17  * This API provides WiFi Client setup.
18  * Please note that the WiFi Client cannot be used at the same time as the WiFi Access Points
19  * service, due to the sharing of same wifi hardware.
20  *
21  * @section le_wifi_binding IPC interfaces binding
22  *
23  *
24  * Here's a code sample binding to WiFi service:
25  * @verbatim
26  bindings:
27  {
28  clientExe.clientComponent.le_wifiClient -> wifiService.le_wifiClient
29  }
30  @endverbatim
31  *
32  * @section le_wifiClient_Start Starting the WiFi Client
33  *
34  * First of all the function le_wifiClient_Start() must be called to start the WiFi Service.
35  * - le_wifiClient_Start(): returns LE_OK if the call went ok.
36  * If WiFi Access Point is active, this will fail.
37  *
38  *
39  * To subscribe to wifi events le_wifiClient_AddNewEventHandler() is to be called.
40  * - le_wifiClient_AddNewEventHandler(): returns the handler reference if the call went ok.
41  *
42  * @code
43  *
44  * static void EventHandler
45  * (
46  * le_wifiClient_Event_t clientEvent,
47  * void *contextPtr
48  * )
49  * {
50  * switch( clientEvent )
51  * {
52  * case LE_WIFICLIENT_EVENT_CONNECTED:
53  * {
54  * LE_INFO("WiFi Client Connected.");
55  * }
56  * break;
57  * case LE_WIFICLIENT_EVENT_DISCONNECTED:
58  * {
59  * LE_INFO("WiFi Client Disconnected.");
60  * }
61  * break;
62  * case LE_WIFICLIENT_EVENT_SCAN_DONE:
63  * {
64  * LE_INFO("WiFi Client Scan is done.");
65  * MyHandleScanResult();
66  * }
67  * break;
68  * }
69  * }
70  *
71  * le_wifiClient_NewEventHandler WiFiEventHandlerRef = NULL;
72  *
73  * static void MyInit
74  * (
75  * void
76  * )
77  * {
78  * le_result_t result = le_wifiClient_start();
79  *
80  * if ( LE_OK == result )
81  * {
82  * LE_INFO("WiFi Client started.");
83  * WiFiEventHandlerRef = le_wifiClient_AddNewEventHandler( EventHandler, NULL );
84  * }
85  * else if ( LE_BUSY == result )
86  * {
87  * LE_INFO("ERROR: WiFi Client already started.");
88  * }
89  * else
90  * {
91  * LE_INFO("ERROR: WiFi Client not started.");
92  * }
93  *
94  * }
95  *
96  * @endcode
97  *
98  *
99  * @section le_wifiClient_scan Scanning Access Points with WiFi Client
100  *
101  * To start a scan for Access Points, the le_wifiClient_Scan() should be called.
102  * - le_wifiClient_Scan(): returns the LE_OK if the call went ok.
103  *
104  *
105  * @section le_wifiClient_scan_result Processing the WiFi scan results
106  *
107  * Once the scan results are available, the event LE_WIFICLIENT_EVENT_SCAN_DONE is received.
108  * The found Access Points can then be gotten with
109  * - le_wifiClient_GetFirstAccessPoint(): returns the Access Point if found. Else NULL.
110  * - le_wifiClient_GetNextAccessPoint(): returns the next Access Point if found. Else NULL.
111  *
112  * The Access Points SSID, Service Set Identifier, is not a string.
113  * It does however often contain human readable ASCII values.
114  * It can be read with the following function:
115  * - le_wifiClient_GetSsid() : returns the LE_OK if the SSID was read ok.
116  *
117  * The Access Points signal strength can be read with the following function:
118  * - le_wifiClient_GetSignalStrength() : returns the signal strength in dBm of the AccessPoint
119  *
120  * @code
121  *
122  * static void MyHandleScanResult
123  * (
124  * void
125  * )
126  * {
127  * uint8 ssid[MAX_SSID_BYTES];
128  * le_wifiClient_AccessPointRef_t accessPointRef = le_wifiClient_GetFirstAccessPoint();
129  *
130  * while( NULL != accessPointRef )
131  * {
132  * result = le_wifiClient_GetSsid( accessPointRef, ssid, MAX_SSID_BYTES );
133  * if (( result == LE_OK ) && ( memcmp( ssid, "MySSID", 6) == 0 ))
134  * {
135  * LE_INFO("WiFi Client found.");
136  * break;
137  * }
138  * accessPointRef = le_wifiClient_GetNextAccessPoint();
139  * }
140  * }
141  *
142  * @endcode
143  *
144  * @section le_wifiClient_connect_to_ap Connecting to Access Point
145  *
146  * To connect to an Access Point use the function:
147  * - le_wifiClient_Connect() : returns the LE_OK if the function was called ok.
148  *
149  * To set the pass phrase prior for the Access Point use the function:
150  * - le_wifiClient_SetPassphrase() : returns the LE_OK if the function was called ok.
151  *
152  * WPA-Enterprise requires a username and password to authenticate.
153  * To set them use the function :
154  * - le_wifiClient_SetUserCredentials() : returns the LE_OK if the function was called ok.
155  *
156  * If an Access Point is hidden, it does not announce it's presence,
157  * it will not show up in the scan.
158  * To be able to connect to it, the SSID must be known.
159  * Use the following function to get an Access Point that can be used to connect to:
160  * - le_wifiClient_Create() : returns Access Point.
161  *
162  * @code
163  *
164  * static void MyConnectTo
165  * (
166  * le_wifiClient_AccessPointRef_t accessPointRef
167  * )
168  * {
169  * le_result_t result;
170  * le_wifiClient_SetPassphrase ( accessPointRef, "Secret1" );
171  * result = le_wifiClient_Connect( accessPointRef );
172  * if (result == LE_OK)
173  * {
174  * LE_INFO("Connecting to AP.");
175  * }
176  * }
177  *
178  * @endcode
179  *
180  * <HR>
181  *
182  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
183  */
184 /**
185  * @file le_wifiClient_interface.h
186  *
187  * Legato @ref c_le_wifi_client include file.
188  *
189  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
190  */
191 
192 #ifndef LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
193 #define LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
194 
195 
196 #include "legato.h"
197 
198 // Interface specific includes
199 #include "le_wifiDefs_interface.h"
200 
201 
202 //--------------------------------------------------------------------------------------------------
203 /**
204  *
205  * Connect the current client thread to the service providing this API. Block until the service is
206  * available.
207  *
208  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
209  * called before any other functions in this API. Normally, ConnectService is automatically called
210  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
211  *
212  * This function is created automatically.
213  */
214 //--------------------------------------------------------------------------------------------------
216 (
217  void
218 );
219 
220 //--------------------------------------------------------------------------------------------------
221 /**
222  *
223  * Try to connect the current client thread to the service providing this API. Return with an error
224  * if the service is not available.
225  *
226  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
227  * called before any other functions in this API. Normally, ConnectService is automatically called
228  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
229  *
230  * This function is created automatically.
231  *
232  * @return
233  * - LE_OK if the client connected successfully to the service.
234  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
235  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
236  * - LE_COMM_ERROR if the Service Directory cannot be reached.
237  */
238 //--------------------------------------------------------------------------------------------------
240 (
241  void
242 );
243 
244 //--------------------------------------------------------------------------------------------------
245 /**
246  *
247  * Disconnect the current client thread from the service providing this API.
248  *
249  * Normally, this function doesn't need to be called. After this function is called, there's no
250  * longer a connection to the service, and the functions in this API can't be used. For details, see
251  * @ref apiFilesC_client.
252  *
253  * This function is created automatically.
254  */
255 //--------------------------------------------------------------------------------------------------
257 (
258  void
259 );
260 
261 
262 //--------------------------------------------------------------------------------------------------
263 /**
264  * Reference type for AccessPoint that is returned by the WiFi Scan.
265  */
266 //--------------------------------------------------------------------------------------------------
267 typedef struct le_wifiClient_AccessPoint* le_wifiClient_AccessPointRef_t;
268 
269 
270 //--------------------------------------------------------------------------------------------------
271 /**
272  * WiFi Client Events.
273  */
274 //--------------------------------------------------------------------------------------------------
275 typedef enum
276 {
278  ///< WiFi Client Connected
279 
281  ///< WiFi Client Disconnected
282 
284  ///< WiFi Scan result for available Access Points available
285 }
287 
288 
289 //--------------------------------------------------------------------------------------------------
290 /**
291  * WiFi Client Security Protocol for connection
292  */
293 //--------------------------------------------------------------------------------------------------
294 typedef enum
295 {
297  ///< no security.
298 
300  ///< Using WEP.
301 
303  ///< Using WPA
304 
306  ///< Using WPA2
307 
309  ///< Using WPA Enterprise
310 
312  ///< Using WPA2 Enterprise
313 }
315 
316 
317 //--------------------------------------------------------------------------------------------------
318 /**
319  * Reference type used by Add/Remove functions for EVENT 'le_wifiClient_NewEvent'
320  */
321 //--------------------------------------------------------------------------------------------------
322 typedef struct le_wifiClient_NewEventHandler* le_wifiClient_NewEventHandlerRef_t;
323 
324 
325 //--------------------------------------------------------------------------------------------------
326 /**
327  * Handler for WiFi Client changes
328  *
329  * @param event
330  * Handles the wifi events
331  * @param contextPtr
332  */
333 //--------------------------------------------------------------------------------------------------
335 (
336  le_wifiClient_Event_t event,
337  void* contextPtr
338 );
339 
340 //--------------------------------------------------------------------------------------------------
341 /**
342  * Add handler function for EVENT 'le_wifiClient_NewEvent'
343  *
344  * This event provide information on WiFi Client event changes.
345  */
346 //--------------------------------------------------------------------------------------------------
348 (
350  ///< [IN]
351 
352  void* contextPtr
353  ///< [IN]
354 );
355 
356 //--------------------------------------------------------------------------------------------------
357 /**
358  * Remove handler function for EVENT 'le_wifiClient_NewEvent'
359  */
360 //--------------------------------------------------------------------------------------------------
362 (
364  ///< [IN]
365 );
366 
367 //--------------------------------------------------------------------------------------------------
368 /**
369  * This function starts the WIFI device.
370  *
371  * @return
372  * - LE_FAULT if the function failed.
373  * - LE_BUSY if the WIFI device is already started.
374  * - LE_OK if the function succeeded.
375  *
376  */
377 //--------------------------------------------------------------------------------------------------
379 (
380  void
381 );
382 
383 //--------------------------------------------------------------------------------------------------
384 /**
385  * This function stops the WIFI device.
386  *
387  * @return
388  * - LE_FAULT if the function failed.
389  * - LE_DUPLICATE if the WIFI device is already stopped.
390  * - LE_OK if the function succeeded.
391  *
392  */
393 //--------------------------------------------------------------------------------------------------
395 (
396  void
397 );
398 
399 //--------------------------------------------------------------------------------------------------
400 /**
401  * Start Scanning for WiFi Access points
402  * Will result in event LE_WIFICLIENT_EVENT_SCAN_DONE when the scan results are available.
403  *
404  * @return
405  * - LE_FAULT if the function failed.
406  * - LE_OK if the function succeeded.
407  */
408 //--------------------------------------------------------------------------------------------------
410 (
411  void
412 );
413 
414 //--------------------------------------------------------------------------------------------------
415 /**
416  * Get the first WiFi Access Point found.
417  * Will return the Access Points in the order of found.
418  *
419  * @return
420  * - WiFi Access Point reference if ok.
421  * - NULL if no Access Point reference available.
422  */
423 //--------------------------------------------------------------------------------------------------
425 (
426  void
427 );
428 
429 //--------------------------------------------------------------------------------------------------
430 /**
431  * Get the next WiFi Access Point.
432  * Will return the Access Points in the order of found.
433  * This function must be called in the same context as the GetFirstAccessPoint
434  *
435  * @return
436  * - WiFi Access Point reference if ok.
437  * - NULL if no Access Point reference available.
438 */
439 //--------------------------------------------------------------------------------------------------
441 (
442  void
443 );
444 
445 //--------------------------------------------------------------------------------------------------
446 /**
447  * Get the signal strength of the AccessPoint
448  *
449  * @return
450  * - signal strength in dBm. Example -30 = -30dBm
451  * - if no signal available it will return OxFFFF
452  */
453 //--------------------------------------------------------------------------------------------------
455 (
456  le_wifiClient_AccessPointRef_t accessPointRef
457  ///< [IN] WiFi Access Point reference.
458 );
459 
460 //--------------------------------------------------------------------------------------------------
461 /**
462  * Get the Service set identification (SSID) of the AccessPoint
463  * @note that the SSID does not have to be human readable ASCII values, but often has.
464  *
465  * @return
466  * - LE_FAULT if the function failed.
467  * - LE_BAD_PARAMETER if some parameter is invalid.
468  * - LE_OK if the function succeeded.
469  */
470 //--------------------------------------------------------------------------------------------------
472 (
473  le_wifiClient_AccessPointRef_t accessPointRef,
474  ///< [IN] WiFi Access Point reference.
475 
476  uint8_t* SsidPtr,
477  ///< [OUT] The SSID returned as a octet array.
478 
479  size_t* SsidNumElementsPtr
480  ///< [INOUT]
481 );
482 
483 //--------------------------------------------------------------------------------------------------
484 /**
485  * Set the passphrase used to generate the PSK.
486  *
487  * @note the difference between le_wifiClient_SetPreSharedKey() and this function
488  *
489  * @return
490  * - LE_FAULT if the function failed.
491  * - LE_BAD_PARAMETER if parameter is invalid.
492  * - LE_OK if the function succeeded.
493  *
494  */
495 //--------------------------------------------------------------------------------------------------
497 (
498  le_wifiClient_AccessPointRef_t accessPointRef,
499  ///< [IN] WiFi Access Point reference.
500 
501  const char* PassPhrase
502  ///< [IN] pass-phrase for PSK
503 );
504 
505 //--------------------------------------------------------------------------------------------------
506 /**
507  * Set the Pre Shared Key, PSK.
508  * @note the difference between le_wifiClient_SetPassphrase() and this function
509  *
510  * @return
511  * - LE_FAULT if the function failed.
512  * - LE_BAD_PARAMETER if parameter is invalid.
513  * - LE_OK if the function succeeded.
514  *
515  */
516 //--------------------------------------------------------------------------------------------------
518 (
519  le_wifiClient_AccessPointRef_t accessPointRef,
520  ///< [IN] WiFi Access Point reference.
521 
522  const char* PreSharedKey
523  ///< [IN] PSK. Note the difference between PSK and Pass Phrase.
524 );
525 
526 //--------------------------------------------------------------------------------------------------
527 /**
528  * Set the security protocol for connection
529  *
530  * @return
531  * - LE_FAULT if the function failed.
532  * - LE_BAD_PARAMETER if parameter is invalid.
533  * - LE_OK if the function succeeded.
534  *
535  */
536 //--------------------------------------------------------------------------------------------------
538 (
539  le_wifiClient_AccessPointRef_t accessPointRef,
540  ///< [IN] WiFi Access Point reference.
541 
542  le_wifiClient_SecurityProtocol_t securityProtocol
543  ///< [IN] Security Mode
544 );
545 
546 //--------------------------------------------------------------------------------------------------
547 /**
548  * WPA-Enterprise requires a username and password to authenticate.
549  * This function sets these parameters.
550  *
551  * @return
552  * - LE_FAULT if the function failed.
553  * - LE_BAD_PARAMETER if parameter is invalid.
554  * - LE_OK if the function succeeded.
555  *
556  */
557 //--------------------------------------------------------------------------------------------------
559 (
560  le_wifiClient_AccessPointRef_t accessPointRef,
561  ///< [IN] WiFi Access Point reference.
562 
563  const char* userName,
564  ///< [IN] UserName used for WPA-Enterprise.
565 
566  const char* password
567  ///< [IN] Password used for WPA-Enterprise.
568 );
569 
570 //--------------------------------------------------------------------------------------------------
571 /**
572  * Set the WEP key (WEP)
573  *
574  * @return
575  * - LE_FAULT if the function failed.
576  * - LE_OK if the function succeeded.
577  */
578 //--------------------------------------------------------------------------------------------------
580 (
581  le_wifiClient_AccessPointRef_t accessPointRef,
582  ///< [IN] WiFi Access Point reference.
583 
584  const char* wepKey
585  ///< [IN] The WEP key
586 );
587 
588 //--------------------------------------------------------------------------------------------------
589 /**
590  * If an AccessPoint is not announcing it's precense, it will not show up in the scan.
591  * But if the SSID is known, a connnection can be tried using this create function.
592  * First create the AccessPoint, then le_wifiClient_Connect() to connect to it.
593  * Will fail if called while scan is running.
594  *
595  * @return AccessPoint reference to the current
596  */
597 //--------------------------------------------------------------------------------------------------
599 (
600  const uint8_t* SsidPtr,
601  ///< [IN] The SSID as a octet array.
602 
603  size_t SsidNumElements
604  ///< [IN]
605 );
606 
607 //--------------------------------------------------------------------------------------------------
608 /**
609  * Deletes an accessPointRef.
610  *
611  * @note The handle becomes invalid after it has been deleted.
612  * @return
613  * - LE_BAD_PARAMETER if accessPointRef was not found.
614  * - LE_BUSY if the function was called during a scan.
615  * - LE_OK if the function succeeded.
616  */
617 //--------------------------------------------------------------------------------------------------
619 (
620  le_wifiClient_AccessPointRef_t accessPointRef
621  ///< [IN] WiFi Access Point reference.
622 );
623 
624 //--------------------------------------------------------------------------------------------------
625 /**
626  * Connect to the WiFi Access Point.
627  * All authentication must be set prior to calling this function.
628  *
629  * @return
630  * - LE_BAD_PARAMETER if parameter is invalid.
631  * - LE_OK if the function succeeded.
632  *
633  * @note For PSK credentials see le_wifiClient_SetPassphrase() or le_wifiClient_SetPreSharedKey() .
634  * @note For WPA-Enterprise credentials see le_wifiClient_SetUserCredentials()
635  */
636 //--------------------------------------------------------------------------------------------------
638 (
639  le_wifiClient_AccessPointRef_t accessPointRef
640  ///< [IN] WiFi Access Point reference.
641 );
642 
643 //--------------------------------------------------------------------------------------------------
644 /**
645  * Disconnect from the current connected WiFi Access Point.
646  *
647  * @return
648  * - LE_FAULT if the function failed.
649  * - LE_OK if the function succeeded.
650  */
651 //--------------------------------------------------------------------------------------------------
653 (
654  void
655 );
656 
657 
658 #endif // LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
659 
void le_wifiClient_ConnectService(void)
le_wifiClient_SecurityProtocol_t
Definition: le_wifiClient_interface.h:294
le_wifiClient_Event_t
Definition: le_wifiClient_interface.h:275
WiFi Client Connected.
Definition: le_wifiClient_interface.h:277
le_result_t
Definition: le_basics.h:35
le_result_t le_wifiClient_Start(void)
void le_wifiClient_DisconnectService(void)
le_result_t le_wifiClient_TryConnectService(void)
void(* le_wifiClient_NewEventHandlerFunc_t)(le_wifiClient_Event_t event, void *contextPtr)
Definition: le_wifiClient_interface.h:335
WiFi Client Disconnected.
Definition: le_wifiClient_interface.h:280
struct le_wifiClient_NewEventHandler * le_wifiClient_NewEventHandlerRef_t
Definition: le_wifiClient_interface.h:322
le_result_t le_wifiClient_Disconnect(void)
Using WPA Enterprise.
Definition: le_wifiClient_interface.h:308
struct le_wifiClient_AccessPoint * le_wifiClient_AccessPointRef_t
Definition: le_wifiClient_interface.h:267
le_result_t le_wifiClient_Delete(le_wifiClient_AccessPointRef_t accessPointRef)
no security.
Definition: le_wifiClient_interface.h:296
le_result_t le_wifiClient_SetWepKey(le_wifiClient_AccessPointRef_t accessPointRef, const char *wepKey)
void le_wifiClient_RemoveNewEventHandler(le_wifiClient_NewEventHandlerRef_t addHandlerRef)
Using WPA2.
Definition: le_wifiClient_interface.h:305
le_result_t le_wifiClient_GetSsid(le_wifiClient_AccessPointRef_t accessPointRef, uint8_t *SsidPtr, size_t *SsidNumElementsPtr)
le_wifiClient_AccessPointRef_t le_wifiClient_GetFirstAccessPoint(void)
le_result_t le_wifiClient_SetPassphrase(le_wifiClient_AccessPointRef_t accessPointRef, const char *PassPhrase)
le_wifiClient_NewEventHandlerRef_t le_wifiClient_AddNewEventHandler(le_wifiClient_NewEventHandlerFunc_t handlerPtr, void *contextPtr)
Using WPA2 Enterprise.
Definition: le_wifiClient_interface.h:311
le_result_t le_wifiClient_SetPreSharedKey(le_wifiClient_AccessPointRef_t accessPointRef, const char *PreSharedKey)
Using WEP.
Definition: le_wifiClient_interface.h:299
Using WPA.
Definition: le_wifiClient_interface.h:302
le_wifiClient_AccessPointRef_t le_wifiClient_GetNextAccessPoint(void)
le_result_t le_wifiClient_Connect(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_Scan(void)
le_result_t le_wifiClient_SetUserCredentials(le_wifiClient_AccessPointRef_t accessPointRef, const char *userName, const char *password)
le_result_t le_wifiClient_Stop(void)
int16_t le_wifiClient_GetSignalStrength(le_wifiClient_AccessPointRef_t accessPointRef)
le_wifiClient_AccessPointRef_t le_wifiClient_Create(const uint8_t *SsidPtr, size_t SsidNumElements)
WiFi Scan result for available Access Points available.
Definition: le_wifiClient_interface.h:283