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