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