le_data_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_data Data Connection
14  *
15  * @ref le_data_interface.h "API Reference" <br>
16  * @ref le_data_sample <br>
17  *
18  * A data connection is needed for applications that exchange data with devices where SMS messages
19  * are insufficient or not possible. The data connection can be established over a mobile network,
20  * WiFi or a fixed link (e.g., ethernet).
21  *
22  * The data connection service provides a basic API for requesting and releasing a data connection.
23  *
24  * @note This interface does not support yet data connection over a fixed link.
25  *
26  * @warning Dependency between the @c cellNetService and @c dataConnectionService has been removed. A
27  * data connection request will no longer ensure that the radio is on, or verify that the SIM is
28  * valid and unlocked.
29  *
30  * @section le_data_IPCbinding IPC interfaces binding
31  *
32  * All the functions of this API are provided by the @b dataConnectionService application service.
33  *
34  * Here's a code sample binding to Data Connection services:
35  * @verbatim
36  bindings:
37  {
38  clientExe.clientComponent.le_data -> dataConnectionService.le_data
39  }
40  @endverbatim
41  *
42  * @section c_le_data_default Default Data Connection
43  *
44  * Default data connection is obtained using le_data_Request(). Before the data connection is
45  * requested, an application registers a connection state handler using
46  * le_data_AddConnectionStateHandler(). Once the data connection is established, the handler will
47  * be called indicating it's now connected. The interface name is sent only when the data connection
48  * is in connected state. If the state of the data connection changes, then the handler will be
49  * called with the new state. To release a data connection, an application can use le_data_Release().
50  *
51  * The technology of the established connection can be retrieved with le_data_GetTechnology().
52  *
53  * If the default data connection is not currently available when le_data_Request() is called, the
54  * data connection service first ensures all pre-conditions are satisfied (e.g., modem is registered
55  * on the network), before trying to start the data connection.
56  *
57  * If the default data connection is already available when le_data_Request() is called, a new
58  * connection will not be started. Instead, the existing data connection will be used. This happens
59  * if another application also requested the default data connection. This is how multiple
60  * applications can share the same data connection.
61  *
62  * Once an application makes a data connection request, it should monitor the connection state
63  * reported to the registered connection state handler. The application should only try
64  * transmitting data when the state is connected, and should stop transmitting data when the state
65  * is not connected. If the state is not connected, the data connection service will try to
66  * establish or re-establish the connection endlessly until le_data_Release() is called. There's no
67  * need for an application to issue a new connection request.
68  *
69  * The default data connection will not necessarily be released when an application calls
70  * le_data_Release(). The data connection will be released only after le_data_Release() is called by
71  * all applications that previously called le_data_Request().
72  *
73  * @note When using the cellular technology, the data connection service can use a specific cellular
74  * data profile if it has been set with the le_data_SetCellularProfileIndex() API or in the
75  * configuration tree. Otherwise the default cellular profile is used. The profile in use can be
76  * retrieved by le_data_GetCellularProfileIndex(). The profile to use is loaded when the first data
77  * connection is initiated. The cellular data profile can be configured by le_mdc APIs or
78  * cm data tool.
79  *
80  * @section le_data_sample Code sample
81  *
82  * A sample code that implements the establishment of a data connection service can be found in
83  * \b dcsTest.c file (please refer to @ref c_dataConnectionServiceSample page).
84  *
85  * @section c_le_data_routing Data connection routing
86  *
87  * @subsection c_le_data_defaultRoute Default route
88  *
89  * By default, the default route is automatically configured by the data connection service using
90  * the modem parameters when the cellular technology is connected. If an application wishes to
91  * configure its own default route, it should deactivate it in the data connection service by
92  * setting the parameter @c useDefaultRoute to false in the configuration tree (see @ref
93  * c_le_data_configdb):
94  * @verbatim
95  $ config set dataConnectionService:/routing/useDefaultRoute false bool
96  @endverbatim
97  *
98  * @note The default route activation status can be retrieved with le_data_GetDefaultRouteStatus().
99  *
100  * @warning The default route activation status is only read at start-up and the change will only
101  * be effective after a Legato restart.
102  *
103  * A sample code showing how to set the modem default route if it isn't set by the data connection
104  * server is presented below:
105  * @snippet "apps/test/dataConnectionService/dataConnectionServiceRouteTest/dcsRouteTestComp/dcsRouteTest.c" DefaultRoute
106  *
107  * @subsection c_le_data_addRemoveRoute Add or remove a route
108  *
109  * Specific routes can be added for the cellular connection with le_data_AddRoute(), which is
110  * used to route IP packets to a specific address through the data connection service interface.
111  * When the routes are not necessary anymore, they can be removed with le_data_DelRoute().
112  * @code
113  * // Add a route to the 8.8.8.8 IP address for the cellular connection
114  * le_data_AddRoute("8.8.8.8");
115  *
116  * // Remove a route to the 8.8.8.8 IP address for the cellular connection
117  * le_data_DelRoute("8.8.8.8");
118  * @endcode
119  *
120  * @section c_le_data_rank Technology rank
121  *
122  * The technology to use for the default data connection can be chosen by the applications
123  * with an ordered list. If the connection becomes unavailable through a technology, the next
124  * one in the list is used for the default data connection. If the connection is also unavailable
125  * through the last technology of the list, the first technology will be used again.
126  * The default sequence is @ref LE_DATA_WIFI at rank #1 and @ref LE_DATA_CELLULAR at rank #2.
127  *
128  * @note
129  * - Only one list is available and therefore only one application should set the technology
130  * preferences for the default data connection.
131  * - The list should not be modified while the default data connection is established.
132  * .
133  *
134  *
135  * - le_data_SetTechnologyRank() sets the rank of the technology to use for the data connection
136  * service.
137  * le_data_SetTechnologyRank() inserts a technology into a list, so all the technologies
138  * previously set with ranks @c r and @c r+n are automatically shifted to ranks @c r+1
139  * and @c r+n+1. Technologies with ranks under @c r are not impacted. If the technology is already
140  * in the list, it is removed from its current rank and added to the new rank.
141  *
142  * - le_data_GetFirstUsedTechnology() and le_data_GetNextUsedTechnology() let you retrieve
143  * the different technologies of the ordered list to use for the default connection data.
144  *
145  * @section c_le_data_time Date and time
146  *
147  * When the data connection service is connected, the date and time can be retrieved from a distant
148  * server using le_data_GetDate() and le_data_GetTime(). The time protocol and time server to use
149  * are configured through the @ref c_le_data_configdb database:
150  * - Time protocol:
151  * - @ref LE_DATA_TP to use the Time Protocol, defined in
152  * <a href="https://tools.ietf.org/html/rfc868">RFC 868</a>.
153  * - @ref LE_DATA_NTP to use the Network Time Protocol, defined in
154  * <a href="https://tools.ietf.org/html/rfc5905">RFC 5905</a>.
155  * - Time server: address of the time server to connect to. If not set, the default value is
156  * <tt> time.nist.gov </tt> for @ref LE_DATA_TP and to <tt> pool.ntp.org </tt> for @ref LE_DATA_NTP.
157  *
158  * @note The configured time protocol needs to be supported by your platform to be used by the data
159  * connection service.
160  *
161  * @section c_le_data_configdb Configuration tree
162  * @copydoc c_le_data_configdbPage_Hide
163  *
164  * <HR>
165  *
166  * Copyright (C) Sierra Wireless Inc.
167  */
168 /**
169  * @interface c_le_data_configdbPage_Hide
170  *
171  * The configuration database of the @c dataConnectionService allows configuring:
172  * - the default routing
173  * - the Wi-Fi access point
174  * - the cellular profile
175  * - the time protocol and server.
176  *
177  * The configuration is stored under the following path:
178  * @verbatim
179  dataConnectionService:/
180  routing/
181  useDefaultRoute<bool> == true
182  wifi/
183  SSID<string> == TestSsid
184  secProtocol<int> == 3
185  passphrase<string> == Passw0rd
186  cellular/
187  profileIndex<int> == index
188  time/
189  protocol<int> == 0
190  server<string> == my.time.server.com
191  @endverbatim
192  *
193  * @note
194  * - The security protocol is one of the supported protocols defined in the
195  * @ref le_wifiClient_SecurityProtocol_t enumerator.
196  * - The time protocol is one of the supported protocols defined in the
197  * @ref le_data_TimeProtocol_t enumerator.
198  *
199  * @todo This solution is temporary, as the list of access points to connect to should be
200  * managed by the Wi-Fi client. Until its API is modified, the config tree is used to configure
201  * the only access point to use for the default data connection.
202  *
203  */
204 /**
205  * @file le_data_interface.h
206  *
207  * Legato @ref c_le_data include file.
208  *
209  * Copyright (C) Sierra Wireless Inc.
210  */
211 /**
212  * @page c_dataConnectionServiceSample Sample code for data connection service establishment
213  *
214  * @include "apps/test/dataConnectionService/dataConnectionServiceTest/dcsTestComp/dcsTest.c"
215  */
216 
217 #ifndef LE_DATA_INTERFACE_H_INCLUDE_GUARD
218 #define LE_DATA_INTERFACE_H_INCLUDE_GUARD
219 
220 
221 #include "legato.h"
222 
223 // Interface specific includes
224 #include "le_mdc_interface.h"
225 #include "le_dcs_interface.h"
226 
227 
228 //--------------------------------------------------------------------------------------------------
229 /**
230  * Type for handler called when a server disconnects.
231  */
232 //--------------------------------------------------------------------------------------------------
233 typedef void (*le_data_DisconnectHandler_t)(void *);
234 
235 //--------------------------------------------------------------------------------------------------
236 /**
237  *
238  * Connect the current client thread to the service providing this API. Block until the service is
239  * available.
240  *
241  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
242  * called before any other functions in this API. Normally, ConnectService is automatically called
243  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
244  *
245  * This function is created automatically.
246  */
247 //--------------------------------------------------------------------------------------------------
249 (
250  void
251 );
252 
253 //--------------------------------------------------------------------------------------------------
254 /**
255  *
256  * Try to connect the current client thread to the service providing this API. Return with an error
257  * if the service is not available.
258  *
259  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
260  * called before any other functions in this API. Normally, ConnectService is automatically called
261  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
262  *
263  * This function is created automatically.
264  *
265  * @return
266  * - LE_OK if the client connected successfully to the service.
267  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
268  * bound.
269  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
270  * - LE_COMM_ERROR if the Service Directory cannot be reached.
271  */
272 //--------------------------------------------------------------------------------------------------
274 (
275  void
276 );
277 
278 //--------------------------------------------------------------------------------------------------
279 /**
280  * Set handler called when server disconnection is detected.
281  *
282  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
283  * to continue without exiting, it should call longjmp() from inside the handler.
284  */
285 //--------------------------------------------------------------------------------------------------
287 (
288  le_data_DisconnectHandler_t disconnectHandler,
289  void *contextPtr
290 );
291 
292 //--------------------------------------------------------------------------------------------------
293 /**
294  *
295  * Disconnect the current client thread from the service providing this API.
296  *
297  * Normally, this function doesn't need to be called. After this function is called, there's no
298  * longer a connection to the service, and the functions in this API can't be used. For details, see
299  * @ref apiFilesC_client.
300  *
301  * This function is created automatically.
302  */
303 //--------------------------------------------------------------------------------------------------
305 (
306  void
307 );
308 
309 
310 //--------------------------------------------------------------------------------------------------
311 /**
312  * Interface name string length.
313  */
314 //--------------------------------------------------------------------------------------------------
315 #define LE_DATA_INTERFACE_NAME_MAX_LEN 100
316 
317 //--------------------------------------------------------------------------------------------------
318 /**
319  * Interface name string length. One extra byte is added for the null character.
320  */
321 //--------------------------------------------------------------------------------------------------
322 #define LE_DATA_INTERFACE_NAME_MAX_BYTES 101
323 
324 //--------------------------------------------------------------------------------------------------
325 /**
326  * Reference returned by Request function and used by Release function
327  */
328 //--------------------------------------------------------------------------------------------------
329 typedef struct le_data_RequestObj* le_data_RequestObjRef_t;
330 
331 
332 //--------------------------------------------------------------------------------------------------
333 /**
334  * Technologies.
335  */
336 //--------------------------------------------------------------------------------------------------
337 typedef enum
338 {
340  ///< Wi-Fi
342  ///< Cellular
344  ///< Unknown state.
345 }
347 
348 
349 //--------------------------------------------------------------------------------------------------
350 /**
351  * Time protocols.
352  */
353 //--------------------------------------------------------------------------------------------------
354 typedef enum
355 {
357  ///< Time Protocol, defined in RFC 868
359  ///< Network Time Protocol, defined in RFC 5905
360 }
362 
363 
364 //--------------------------------------------------------------------------------------------------
365 /**
366  * Reference type used by Add/Remove functions for EVENT 'le_data_ConnectionState'
367  */
368 //--------------------------------------------------------------------------------------------------
369 typedef struct le_data_ConnectionStateHandler* le_data_ConnectionStateHandlerRef_t;
370 
371 
372 //--------------------------------------------------------------------------------------------------
373 /**
374  * Handler for connection state changes
375  */
376 //--------------------------------------------------------------------------------------------------
378 (
379  const char* LE_NONNULL intfName,
380  ///< Interface name for the data connection
381  bool isConnected,
382  ///< State: connected or disconnected
383  void* contextPtr
384  ///<
385 );
386 
387 //--------------------------------------------------------------------------------------------------
388 /**
389  * Add handler function for EVENT 'le_data_ConnectionState'
390  *
391  * This event provides information on connection state changes
392  */
393 //--------------------------------------------------------------------------------------------------
395 (
397  ///< [IN]
398  void* contextPtr
399  ///< [IN]
400 );
401 
402 //--------------------------------------------------------------------------------------------------
403 /**
404  * Remove handler function for EVENT 'le_data_ConnectionState'
405  */
406 //--------------------------------------------------------------------------------------------------
408 (
410  ///< [IN]
411 );
412 
413 //--------------------------------------------------------------------------------------------------
414 /**
415  * Request the default data connection
416  *
417  * @return
418  * - Reference to the data connection (to be used later for releasing the connection)
419  * - NULL if the data connection requested could not be processed
420  */
421 //--------------------------------------------------------------------------------------------------
423 (
424  void
425 );
426 
427 //--------------------------------------------------------------------------------------------------
428 /**
429  * Release a previously requested data connection
430  */
431 //--------------------------------------------------------------------------------------------------
432 void le_data_Release
433 (
434  le_data_RequestObjRef_t requestRef
435  ///< [IN] Reference to a previously requested data connection
436 );
437 
438 //--------------------------------------------------------------------------------------------------
439 /**
440  * Set the rank of the technology used for the data connection service
441  *
442  * @return
443  * - @ref LE_OK if the technology is added to the list
444  * - @ref LE_BAD_PARAMETER if the technology is unknown
445  * - @ref LE_UNSUPPORTED if the technology is not available
446  */
447 //--------------------------------------------------------------------------------------------------
449 (
450  uint32_t rank,
451  ///< [IN] Rank of the used technology
452  le_data_Technology_t technology
453  ///< [IN] Technology
454 );
455 
456 //--------------------------------------------------------------------------------------------------
457 /**
458  * Get the first technology to use
459  * @return
460  * - One of the technologies from @ref le_data_Technology_t enumerator if the list is not empty
461  * - @ref LE_DATA_MAX if the list is empty
462  */
463 //--------------------------------------------------------------------------------------------------
465 (
466  void
467 );
468 
469 //--------------------------------------------------------------------------------------------------
470 /**
471  * Get the next technology to use
472  * @return
473  * - One of the technologies from @ref le_data_Technology_t enumerator if the list is not empty
474  * - @ref LE_DATA_MAX if the list is empty or the end of the list is reached
475  */
476 //--------------------------------------------------------------------------------------------------
478 (
479  void
480 );
481 
482 //--------------------------------------------------------------------------------------------------
483 /**
484  * Get the technology currently used for the default data connection
485  *
486  * @return
487  * - One of the technologies from @ref le_data_Technology_t enumerator
488  * - @ref LE_DATA_MAX if the current technology is not set
489  *
490  * @note The supported technologies are @ref LE_DATA_WIFI and @ref LE_DATA_CELLULAR
491  */
492 //--------------------------------------------------------------------------------------------------
494 (
495  void
496 );
497 
498 //--------------------------------------------------------------------------------------------------
499 /**
500  * Get the default route activation status for the data connection service interface.
501  *
502  * @return
503  * - true: the default route is set by the data connection service
504  * - false: the default route is not set by the data connection service
505  */
506 //--------------------------------------------------------------------------------------------------
508 (
509  void
510 );
511 
512 //--------------------------------------------------------------------------------------------------
513 /**
514  * Add a route on the data connection service interface, if the data session is connected using
515  * the cellular technology and has an IPv4 or IPv6 address.
516  *
517  * @return
518  * - LE_OK on success
519  * - LE_UNSUPPORTED cellular technology not currently used
520  * - LE_BAD_PARAMETER incorrect IP address
521  * - LE_FAULT for all other errors
522  *
523  * @note Limitations:
524  * - only IPv4 is supported for the moment
525  * - route only added for a cellular connection
526  */
527 //--------------------------------------------------------------------------------------------------
529 (
530  const char* LE_NONNULL ipDestAddrStr
531  ///< [IN] The destination IP address in dotted
532  ///< format
533 );
534 
535 //--------------------------------------------------------------------------------------------------
536 /**
537  * Delete a route on the data connection service interface, if the data session is connected using
538  * the cellular technology and has an IPv4 or IPv6 address.
539  *
540  * @return
541  * - LE_OK on success
542  * - LE_UNSUPPORTED cellular technology not currently used
543  * - LE_BAD_PARAMETER incorrect IP address
544  * - LE_FAULT for all other errors
545  *
546  * @note Limitations:
547  * - only IPv4 is supported for the moment
548  * - route only removed for a cellular connection
549  */
550 //--------------------------------------------------------------------------------------------------
552 (
553  const char* LE_NONNULL ipDestAddrStr
554  ///< [IN] The destination IP address in dotted
555  ///< format
556 );
557 
558 //--------------------------------------------------------------------------------------------------
559 /**
560  * Get the cellular profile index used by the data connection service when the cellular technology
561  * is active.
562  *
563  * @return
564  * - Cellular profile index
565  */
566 //--------------------------------------------------------------------------------------------------
568 (
569  void
570 );
571 
572 //--------------------------------------------------------------------------------------------------
573 /**
574  * Set the cellular profile index used by the data connection service when the cellular technology
575  * is active.
576  *
577  * @return
578  * - LE_OK on success
579  * - LE_BAD_PARAMETER if the profile index is invalid
580  * - LE_BUSY the cellular connection is in use
581  */
582 //--------------------------------------------------------------------------------------------------
584 (
585  int32_t profileIndex
586  ///< [IN] Cellular profile index to be used
587 );
588 
589 //--------------------------------------------------------------------------------------------------
590 /**
591  * Get the date from the configured server using the configured time protocol.
592  *
593  * @warning An active data connection is necessary to retrieve the date.
594  *
595  * @return
596  * - LE_OK on success
597  * - LE_BAD_PARAMETER if a parameter is incorrect
598  * - LE_FAULT if an error occurred
599  */
600 //--------------------------------------------------------------------------------------------------
602 (
603  uint16_t* yearPtr,
604  ///< [OUT] UTC Year A.D. [e.g. 2017].
605  uint16_t* monthPtr,
606  ///< [OUT] UTC Month into the year [range 1...12].
607  uint16_t* dayPtr
608  ///< [OUT] UTC Days into the month [range 1...31].
609 );
610 
611 //--------------------------------------------------------------------------------------------------
612 /**
613  * Get the time from the configured server using the configured time protocol.
614  *
615  * @warning An active data connection is necessary to retrieve the time.
616  *
617  * @return
618  * - LE_OK on success
619  * - LE_BAD_PARAMETER if a parameter is incorrect
620  * - LE_FAULT if an error occurred
621  */
622 //--------------------------------------------------------------------------------------------------
624 (
625  uint16_t* hoursPtr,
626  ///< [OUT] UTC Hours into the day [range 0..23].
627  uint16_t* minutesPtr,
628  ///< [OUT] UTC Minutes into the hour [range 0..59].
629  uint16_t* secondsPtr,
630  ///< [OUT] UTC Seconds into the minute [range 0..59].
631  uint16_t* millisecondsPtr
632  ///< [OUT] UTC Milliseconds into the second [range 0..999].
633 );
634 
635 #endif // LE_DATA_INTERFACE_H_INCLUDE_GUARD
le_result_t le_data_GetDate(uint16_t *yearPtr, uint16_t *monthPtr, uint16_t *dayPtr)
Cellular.
Definition: le_data_interface.h:341
le_data_Technology_t
Definition: le_data_interface.h:337
void le_data_ConnectService(void)
le_result_t
Definition: le_basics.h:35
void le_data_Release(le_data_RequestObjRef_t requestRef)
le_data_RequestObjRef_t le_data_Request(void)
void(* le_data_ConnectionStateHandlerFunc_t)(const char *LE_NONNULL intfName, bool isConnected, void *contextPtr)
Definition: le_data_interface.h:378
struct le_data_RequestObj * le_data_RequestObjRef_t
Definition: le_data_interface.h:329
void le_data_RemoveConnectionStateHandler(le_data_ConnectionStateHandlerRef_t handlerRef)
le_result_t le_data_SetTechnologyRank(uint32_t rank, le_data_Technology_t technology)
le_data_Technology_t le_data_GetNextUsedTechnology(void)
le_result_t le_data_AddRoute(const char *LE_NONNULL ipDestAddrStr)
Unknown state.
Definition: le_data_interface.h:343
Wi-Fi.
Definition: le_data_interface.h:339
int32_t le_data_GetCellularProfileIndex(void)
le_result_t le_data_TryConnectService(void)
Network Time Protocol, defined in RFC 5905.
Definition: le_data_interface.h:358
void le_data_DisconnectService(void)
le_result_t le_data_GetTime(uint16_t *hoursPtr, uint16_t *minutesPtr, uint16_t *secondsPtr, uint16_t *millisecondsPtr)
Time Protocol, defined in RFC 868.
Definition: le_data_interface.h:356
le_data_TimeProtocol_t
Definition: le_data_interface.h:354
le_result_t le_data_SetCellularProfileIndex(int32_t profileIndex)
void le_data_SetServerDisconnectHandler(le_data_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_data_Technology_t le_data_GetTechnology(void)
le_result_t le_data_DelRoute(const char *LE_NONNULL ipDestAddrStr)
void(* le_data_DisconnectHandler_t)(void *)
Definition: le_data_interface.h:233
struct le_data_ConnectionStateHandler * le_data_ConnectionStateHandlerRef_t
Definition: le_data_interface.h:369
bool le_data_GetDefaultRouteStatus(void)
le_data_Technology_t le_data_GetFirstUsedTechnology(void)
le_data_ConnectionStateHandlerRef_t le_data_AddConnectionStateHandler(le_data_ConnectionStateHandlerFunc_t handlerPtr, void *contextPtr)