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_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  * To connect to an Access Point use the function:
149  * - le_wifiClient_Connect() : returns the LE_OK if the function was called ok.
150  *
151  * To set the pass phrase prior for the Access Point use the function:
152  * - le_wifiClient_SetPassphrase() : returns the LE_OK if the function was called ok.
153  *
154  * WPA-Enterprise requires a username and password to authenticate.
155  * To set them use the function :
156  * - le_wifiClient_SetUserCredentials() : returns the LE_OK if the function was called ok.
157  *
158  * If an Access Point is hidden, it does not announce it's presence,
159  * it will not show up in the scan.
160  * To be able to connect to it, the SSID must be known.
161  * Use the following function to get an Access Point that can be used to connect to:
162  * - le_wifiClient_Create() : returns Access Point.
163  *
164  * @code
165  *
166  * static void MyConnectTo
167  * (
168  * le_wifiClient_AccessPointRef_t accessPointRef
169  * )
170  * {
171  * le_result_t result;
172  * le_wifiClient_SetPassphrase ( accessPointRef, "Secret1" );
173  * result = le_wifiClient_Connect( accessPointRef );
174  * if (result == LE_OK)
175  * {
176  * LE_INFO("Connecting to AP.");
177  * }
178  * }
179  *
180  * @endcode
181  *
182  * <HR>
183  *
184  * Copyright (C) Sierra Wireless Inc.
185  */
186 /**
187  * @file le_wifiClient_interface.h
188  *
189  * Legato @ref c_le_wifi_client include file.
190  *
191  * Copyright (C) Sierra Wireless Inc.
192  */
193 
194 #ifndef LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
195 #define LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
196 
197 
198 #include "legato.h"
199 
200 // Interface specific includes
201 #include "le_wifiDefs_interface.h"
202 
203 
204 //--------------------------------------------------------------------------------------------------
205 /**
206  * Type for handler called when a server disconnects.
207  */
208 //--------------------------------------------------------------------------------------------------
209 typedef void (*le_wifiClient_DisconnectHandler_t)(void *);
210 
211 //--------------------------------------------------------------------------------------------------
212 /**
213  *
214  * Connect the current client thread to the service providing this API. Block until the service is
215  * available.
216  *
217  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
218  * called before any other functions in this API. Normally, ConnectService is automatically called
219  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
220  *
221  * This function is created automatically.
222  */
223 //--------------------------------------------------------------------------------------------------
225 (
226  void
227 );
228 
229 //--------------------------------------------------------------------------------------------------
230 /**
231  *
232  * Try to connect the current client thread to the service providing this API. Return with an error
233  * if the service is not available.
234  *
235  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
236  * called before any other functions in this API. Normally, ConnectService is automatically called
237  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
238  *
239  * This function is created automatically.
240  *
241  * @return
242  * - LE_OK if the client connected successfully to the service.
243  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
244  * bound.
245  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
246  * - LE_COMM_ERROR if the Service Directory cannot be reached.
247  */
248 //--------------------------------------------------------------------------------------------------
250 (
251  void
252 );
253 
254 //--------------------------------------------------------------------------------------------------
255 /**
256  * Set handler called when server disconnection is detected.
257  *
258  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
259  * to continue without exiting, it should call longjmp() from inside the handler.
260  */
261 //--------------------------------------------------------------------------------------------------
263 (
264  le_wifiClient_DisconnectHandler_t disconnectHandler,
265  void *contextPtr
266 );
267 
268 //--------------------------------------------------------------------------------------------------
269 /**
270  *
271  * Disconnect the current client thread from the service providing this API.
272  *
273  * Normally, this function doesn't need to be called. After this function is called, there's no
274  * longer a connection to the service, and the functions in this API can't be used. For details, see
275  * @ref apiFilesC_client.
276  *
277  * This function is created automatically.
278  */
279 //--------------------------------------------------------------------------------------------------
281 (
282  void
283 );
284 
285 
286 //--------------------------------------------------------------------------------------------------
287 /**
288  * Reference type for AccessPoint that is returned by the WiFi Scan.
289  */
290 //--------------------------------------------------------------------------------------------------
291 typedef struct le_wifiClient_AccessPoint* le_wifiClient_AccessPointRef_t;
292 
293 
294 //--------------------------------------------------------------------------------------------------
295 /**
296  * WiFi Client Events.
297  */
298 //--------------------------------------------------------------------------------------------------
299 typedef enum
300 {
302  ///< WiFi Client Connected
304  ///< WiFi Client Disconnected
306  ///< WiFi Scan result for available Access Points available
307 }
309 
310 
311 //--------------------------------------------------------------------------------------------------
312 /**
313  * WiFi Client Security Protocol for connection
314  */
315 //--------------------------------------------------------------------------------------------------
316 typedef enum
317 {
319  ///< no security.
321  ///< Using WEP.
323  ///< Using WPA
325  ///< Using WPA2
327  ///< Using WPA Enterprise
329  ///< Using WPA2 Enterprise
330 }
332 
333 
334 //--------------------------------------------------------------------------------------------------
335 /**
336  * Reference type used by Add/Remove functions for EVENT 'le_wifiClient_NewEvent'
337  */
338 //--------------------------------------------------------------------------------------------------
339 typedef struct le_wifiClient_NewEventHandler* le_wifiClient_NewEventHandlerRef_t;
340 
341 
342 //--------------------------------------------------------------------------------------------------
343 /**
344  * Handler for WiFi Client changes
345  */
346 //--------------------------------------------------------------------------------------------------
348 (
349  le_wifiClient_Event_t event,
350  ///< Handles the wifi events
351  void* contextPtr
352  ///<
353 );
354 
355 //--------------------------------------------------------------------------------------------------
356 /**
357  * Add handler function for EVENT 'le_wifiClient_NewEvent'
358  *
359  * This event provide information on WiFi Client event changes.
360  *
361  */
362 //--------------------------------------------------------------------------------------------------
364 (
366  ///< [IN]
367  void* contextPtr
368  ///< [IN]
369 );
370 
371 //--------------------------------------------------------------------------------------------------
372 /**
373  * Remove handler function for EVENT 'le_wifiClient_NewEvent'
374  */
375 //--------------------------------------------------------------------------------------------------
377 (
379  ///< [IN]
380 );
381 
382 //--------------------------------------------------------------------------------------------------
383 /**
384  * This function starts the WIFI device.
385  *
386  * @return
387  * - LE_FAULT if the function failed.
388  * - LE_BUSY if the WIFI device is already started.
389  * - LE_OK if the function succeeded.
390  *
391  */
392 //--------------------------------------------------------------------------------------------------
394 (
395  void
396 );
397 
398 //--------------------------------------------------------------------------------------------------
399 /**
400  * This function stops the WIFI device.
401  *
402  * @return
403  * - LE_FAULT if the function failed.
404  * - LE_DUPLICATE if the WIFI device is already stopped.
405  * - LE_OK if the function succeeded.
406  *
407  */
408 //--------------------------------------------------------------------------------------------------
410 (
411  void
412 );
413 
414 //--------------------------------------------------------------------------------------------------
415 /**
416  * Start Scanning for WiFi Access points
417  * Will result in event LE_WIFICLIENT_EVENT_SCAN_DONE when the scan results are available.
418  *
419  * @return
420  * - LE_FAULT if the function failed.
421  * - LE_OK if the function succeeded.
422  */
423 //--------------------------------------------------------------------------------------------------
425 (
426  void
427 );
428 
429 //--------------------------------------------------------------------------------------------------
430 /**
431  * Get the first WiFi Access Point found.
432  * Will return the Access Points in the order of found.
433  *
434  * @return
435  * - WiFi Access Point reference if ok.
436  * - NULL if no Access Point reference available.
437  */
438 //--------------------------------------------------------------------------------------------------
440 (
441  void
442 );
443 
444 //--------------------------------------------------------------------------------------------------
445 /**
446  * Get the next WiFi Access Point.
447  * Will return the Access Points in the order of found.
448  * This function must be called in the same context as the GetFirstAccessPoint
449  *
450  * @return
451  * - WiFi Access Point reference if ok.
452  * - NULL if no Access Point reference available.
453  */
454 //--------------------------------------------------------------------------------------------------
456 (
457  void
458 );
459 
460 //--------------------------------------------------------------------------------------------------
461 /**
462  * Get the signal strength of the AccessPoint
463  *
464  * @return
465  * - signal strength in dBm. Example -30 = -30dBm
466  * - if no signal available it will return OxFFFF
467  */
468 //--------------------------------------------------------------------------------------------------
470 (
471  le_wifiClient_AccessPointRef_t accessPointRef
472  ///< [IN] WiFi Access Point reference.
473 );
474 
475 //--------------------------------------------------------------------------------------------------
476 /**
477  * Get the Service set identification (SSID) of the AccessPoint
478  * @note that the SSID does not have to be human readable ASCII values, but often has.
479  *
480  * @return
481  * - LE_FAULT if the function failed.
482  * - LE_BAD_PARAMETER if some parameter is invalid.
483  * - LE_OK if the function succeeded.
484  */
485 //--------------------------------------------------------------------------------------------------
487 (
488  le_wifiClient_AccessPointRef_t accessPointRef,
489  ///< [IN] WiFi Access Point reference.
490  uint8_t* SsidPtr,
491  ///< [OUT] The SSID returned as a octet array.
492  size_t* SsidSizePtr
493  ///< [INOUT]
494 );
495 
496 //--------------------------------------------------------------------------------------------------
497 /**
498  * Set the passphrase used to generate the PSK.
499  *
500  * @note the difference between le_wifiClient_SetPreSharedKey() and this function
501  *
502  * @return
503  * - LE_FAULT if the function failed.
504  * - LE_BAD_PARAMETER if parameter is invalid.
505  * - LE_OK if the function succeeded.
506  *
507  */
508 //--------------------------------------------------------------------------------------------------
510 (
511  le_wifiClient_AccessPointRef_t accessPointRef,
512  ///< [IN] WiFi Access Point reference.
513  const char* LE_NONNULL PassPhrase
514  ///< [IN] pass-phrase for PSK
515 );
516 
517 //--------------------------------------------------------------------------------------------------
518 /**
519  * Set the Pre Shared Key, PSK.
520  * @note the difference between le_wifiClient_SetPassphrase() and this function
521  *
522  * @return
523  * - LE_FAULT if the function failed.
524  * - LE_BAD_PARAMETER if parameter is invalid.
525  * - LE_OK if the function succeeded.
526  *
527  */
528 //--------------------------------------------------------------------------------------------------
530 (
531  le_wifiClient_AccessPointRef_t accessPointRef,
532  ///< [IN] WiFi Access Point reference.
533  const char* LE_NONNULL PreSharedKey
534  ///< [IN] PSK. Note the difference between PSK and Pass Phrase.
535 );
536 
537 //--------------------------------------------------------------------------------------------------
538 /**
539  * Set the security protocol for connection
540  *
541  * @return
542  * - LE_FAULT if the function failed.
543  * - LE_BAD_PARAMETER if parameter is invalid.
544  * - LE_OK if the function succeeded.
545  *
546  */
547 //--------------------------------------------------------------------------------------------------
549 (
550  le_wifiClient_AccessPointRef_t accessPointRef,
551  ///< [IN] WiFi Access Point reference.
552  le_wifiClient_SecurityProtocol_t securityProtocol
553  ///< [IN] Security Mode
554 );
555 
556 //--------------------------------------------------------------------------------------------------
557 /**
558  * WPA-Enterprise requires a username and password to authenticate.
559  * This function sets these parameters.
560  *
561  * @return
562  * - LE_FAULT if the function failed.
563  * - LE_BAD_PARAMETER if parameter is invalid.
564  * - LE_OK if the function succeeded.
565  *
566  */
567 //--------------------------------------------------------------------------------------------------
569 (
570  le_wifiClient_AccessPointRef_t accessPointRef,
571  ///< [IN] WiFi Access Point reference.
572  const char* LE_NONNULL userName,
573  ///< [IN] UserName used for WPA-Enterprise.
574  const char* LE_NONNULL password
575  ///< [IN] Password used for WPA-Enterprise.
576 );
577 
578 //--------------------------------------------------------------------------------------------------
579 /**
580  * Set the WEP key (WEP)
581  *
582  * @return
583  * - LE_FAULT if the function failed.
584  * - LE_OK if the function succeeded.
585  */
586 //--------------------------------------------------------------------------------------------------
588 (
589  le_wifiClient_AccessPointRef_t accessPointRef,
590  ///< [IN] WiFi Access Point reference.
591  const char* LE_NONNULL wepKey
592  ///< [IN] The WEP key
593 );
594 
595 //--------------------------------------------------------------------------------------------------
596 /**
597  * If an AccessPoint is not announcing it's precense, it will not show up in the scan.
598  * But if the SSID is known, a connnection can be tried using this create function.
599  * First create the AccessPoint, then le_wifiClient_Connect() to connect to it.
600  * Will fail if called while scan is running.
601  *
602  * @return AccessPoint reference to the current
603  */
604 //--------------------------------------------------------------------------------------------------
606 (
607  const uint8_t* SsidPtr,
608  ///< [IN] The SSID as a octet array.
609  size_t SsidSize
610  ///< [IN]
611 );
612 
613 //--------------------------------------------------------------------------------------------------
614 /**
615  * Deletes an accessPointRef.
616  *
617  * @note The handle becomes invalid after it has been deleted.
618  * @return
619  * - LE_BAD_PARAMETER if accessPointRef was not found.
620  * - LE_BUSY if the function was called during a scan.
621  * - LE_OK if the function succeeded.
622  */
623 //--------------------------------------------------------------------------------------------------
625 (
626  le_wifiClient_AccessPointRef_t accessPointRef
627  ///< [IN] WiFi Access Point reference.
628 );
629 
630 //--------------------------------------------------------------------------------------------------
631 /**
632  * Connect to the WiFi Access Point.
633  * All authentication must be set prior to calling this function.
634  *
635  * @return
636  * - LE_BAD_PARAMETER if parameter is invalid.
637  * - LE_OK if the function succeeded.
638  *
639  * @note For PSK credentials see le_wifiClient_SetPassphrase() or le_wifiClient_SetPreSharedKey() .
640  * @note For WPA-Enterprise credentials see le_wifiClient_SetUserCredentials()
641  */
642 //--------------------------------------------------------------------------------------------------
644 (
645  le_wifiClient_AccessPointRef_t accessPointRef
646  ///< [IN] WiFi Access Point reference.
647 );
648 
649 //--------------------------------------------------------------------------------------------------
650 /**
651  * Disconnect from the current connected WiFi Access Point.
652  *
653  * @return
654  * - LE_FAULT if the function failed.
655  * - LE_OK if the function succeeded.
656  */
657 //--------------------------------------------------------------------------------------------------
659 (
660  void
661 );
662 
663 #endif // LE_WIFICLIENT_INTERFACE_H_INCLUDE_GUARD
void le_wifiClient_ConnectService(void)
le_wifiClient_SecurityProtocol_t
Definition: le_wifiClient_interface.h:316
le_wifiClient_Event_t
Definition: le_wifiClient_interface.h:299
void(* le_wifiClient_DisconnectHandler_t)(void *)
Definition: le_wifiClient_interface.h:209
WiFi Client Connected.
Definition: le_wifiClient_interface.h:301
le_result_t
Definition: le_basics.h:35
void le_wifiClient_RemoveNewEventHandler(le_wifiClient_NewEventHandlerRef_t handlerRef)
le_result_t le_wifiClient_Start(void)
void le_wifiClient_DisconnectService(void)
le_result_t le_wifiClient_TryConnectService(void)
WiFi Client Disconnected.
Definition: le_wifiClient_interface.h:303
le_result_t le_wifiClient_SetPassphrase(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL PassPhrase)
struct le_wifiClient_NewEventHandler * le_wifiClient_NewEventHandlerRef_t
Definition: le_wifiClient_interface.h:339
le_result_t le_wifiClient_Disconnect(void)
Using WPA Enterprise.
Definition: le_wifiClient_interface.h:326
struct le_wifiClient_AccessPoint * le_wifiClient_AccessPointRef_t
Definition: le_wifiClient_interface.h:291
le_result_t le_wifiClient_Delete(le_wifiClient_AccessPointRef_t accessPointRef)
no security.
Definition: le_wifiClient_interface.h:318
le_result_t le_wifiClient_SetWepKey(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL wepKey)
Using WPA2.
Definition: le_wifiClient_interface.h:324
void le_wifiClient_SetServerDisconnectHandler(le_wifiClient_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_wifiClient_AccessPointRef_t le_wifiClient_GetFirstAccessPoint(void)
le_wifiClient_NewEventHandlerRef_t le_wifiClient_AddNewEventHandler(le_wifiClient_NewEventHandlerFunc_t handlerPtr, void *contextPtr)
Using WPA2 Enterprise.
Definition: le_wifiClient_interface.h:328
Using WEP.
Definition: le_wifiClient_interface.h:320
Using WPA.
Definition: le_wifiClient_interface.h:322
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_wifiClient_AccessPointRef_t le_wifiClient_Create(const uint8_t *SsidPtr, size_t SsidSize)
le_result_t le_wifiClient_SetPreSharedKey(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL PreSharedKey)
le_result_t le_wifiClient_Scan(void)
le_result_t le_wifiClient_GetSsid(le_wifiClient_AccessPointRef_t accessPointRef, uint8_t *SsidPtr, size_t *SsidSizePtr)
void(* le_wifiClient_NewEventHandlerFunc_t)(le_wifiClient_Event_t event, void *contextPtr)
Definition: le_wifiClient_interface.h:348
le_result_t le_wifiClient_Stop(void)
le_result_t le_wifiClient_SetUserCredentials(le_wifiClient_AccessPointRef_t accessPointRef, const char *LE_NONNULL userName, const char *LE_NONNULL password)
int16_t le_wifiClient_GetSignalStrength(le_wifiClient_AccessPointRef_t accessPointRef)
WiFi Scan result for available Access Points available.
Definition: le_wifiClient_interface.h:305