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