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