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