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