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