le_data_interface.h

Go to the documentation of this file.
1 /*
2  * ====================== WARNING ======================
3  *
4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
5  * DO NOT MODIFY IN ANY WAY.
6  *
7  * ====================== WARNING ======================
8  */
9 
10 /**
11  * @page c_le_data Data Connection
12  *
13  * @ref le_data_interface.h "API Reference"
14  *
15  * <HR>
16  *
17  * A data connection is needed for applications that exchange data with
18  * devices where SMS messages are insufficient or not possible. The data connection can
19  * be over a mobile network, over Wi-Fi, or over a fixed link (e.g., Ethernet).
20  *
21  * The data connection service provides a basic API for requesting and releasing a data connection.
22  *
23  * @section le_data_binding IPC interfaces binding
24  *
25  * All the functions of this API are provided by the @b dataConnectionService application service.
26  *
27  * Here's a code sample binding to Data Connection services:
28  * @verbatim
29  bindings:
30  {
31  clientExe.clientComponent.le_data -> dataConnectionService.le_data
32  }
33  @endverbatim
34  *
35  * @section c_le_data_default Default Data Connection
36  *
37  * Default data connection is obtained using le_data_Request(). Before the data
38  * connection is requested, an application registers a connection state handler using
39  * le_data_AddConnectionStateHandler(). Once the data connection is established, the
40  * handler will be called indicating it's now connected. If the state of the data
41  * connection changes, then the handler will be called with the new state. To release a data
42  * connection, an application can use le_data_Release().
43  *
44  * If the default data connection is not currently available when le_data_Request() is called,
45  * the data connection service first ensures all pre-conditions are satisfied (e.g.,
46  * modem is registered on the network), before trying to start the data connection.
47  *
48  * If the default data connection is already available when le_data_Request() is called, a
49  * new connection will not be started. Instead, the existing data connection will be used. This
50  * happens if another application also requested the default data connection. This
51  * is how multiple applications can share the same data connection.
52  *
53  * Once an application makes a data connection request, it should monitor the connection state
54  * reported to the registered connection state handler. The application
55  * should only try transmitting data when the state is connected, and should stop transmitting
56  * data when the state is not connected. If the state is not connected, the data connection
57  * service will try to re-establish the connection. There's no need for an application to
58  * issue a new connection request.
59  *
60  * The default data connection will not necessarily be released when an application calls
61  * le_data_Release(). The data connection will be released only after le_data_Release
62  * is called by all applications that previously called le_data_Request().
63  *
64  * All configuration data required for the default data connection, like the Access Point Name
65  * (APN), will be stored in the Config database.
66  *
67  * @section c_le_data_configdb Configuration tree
68  *
69  * The configuration database path for the Data Connection Service is:
70  * @verbatim
71  /
72  dataConnectionService/
73  prefTech<string> == <technology>
74 
75  @endverbatim
76  *
77  * 'prefTech' is the preferred technology used for the data connection service. It can be set with
78  * the following choices (string type):
79  * - "wifi"
80  * - "ethernet"
81  * - "cellular"
82  *
83  * For example, with "cellular", the DCS will load a profile regarding a policy.
84  * If the APN is empty the DCS will read a configuration file
85  * (Containing all APN for MCC/MNC) to fill the APN regarding the MCC,MNC
86  * (provided by the IMSI code).
87  *
88  *
89  * @note Only "cellular" choice is available in the present version.
90  *
91  * @note Profile selection policy is not yet implemented. The first found profile of the selected
92  * technology is loaded in the present version.
93  *
94  *
95  * @section c_le_data_options Data Connection Options
96  *
97  * @note Functionality described in this section is not currently implemented; this
98  * description is provided to outline future functionality.
99  *
100  * Some applications may have data connection requirements that are not met by the default data
101  * connection (e.g., use a least cost data link or disable roaming on mobile networks). You can do this
102  * by:
103  * - creating a request object using le_data_CreateRequest(),
104  * - setting optional values on that request object using le_data_SelectLeastCost() or
105  * le_data_DisableRoaming(),
106  * - and then submitting that object to a data connection request using le_data_SubmitRequest
107  *
108  * le_data_AddConnectionStateHandler() and le_data_Release() APIs can continue to be
109  * used, as described above.
110  *
111  * <HR>
112  *
113  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
114  */
115 /**
116  * @file le_data_interface.h
117  *
118  * Legato @ref c_le_data include file.
119  *
120  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
121  */
122 
123 #ifndef LE_DATA_INTERFACE_H_INCLUDE_GUARD
124 #define LE_DATA_INTERFACE_H_INCLUDE_GUARD
125 
126 
127 #include "legato.h"
128 
129 //--------------------------------------------------------------------------------------------------
130 /**
131  *
132  * Connect the current client thread to the service providing this API. Block until the service is
133  * available.
134  *
135  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
136  * called before any other functions in this API. Normally, ConnectService is automatically called
137  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
138  *
139  * This function is created automatically.
140  */
141 //--------------------------------------------------------------------------------------------------
143 (
144  void
145 );
146 
147 //--------------------------------------------------------------------------------------------------
148 /**
149  *
150  * Try to connect the current client thread to the service providing this API. Return with an error
151  * if the service is not available.
152  *
153  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
154  * called before any other functions in this API. Normally, ConnectService is automatically called
155  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
156  *
157  * This function is created automatically.
158  *
159  * @return
160  * - LE_OK if the client connected successfully to the service.
161  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
162  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
163  * - LE_COMM_ERROR if the Service Directory cannot be reached.
164  */
165 //--------------------------------------------------------------------------------------------------
167 (
168  void
169 );
170 
171 //--------------------------------------------------------------------------------------------------
172 /**
173  *
174  * Disconnect the current client thread from the service providing this API.
175  *
176  * Normally, this function doesn't need to be called. After this function is called, there's no
177  * longer a connection to the service, and the functions in this API can't be used. For details, see
178  * @ref apiFilesC_client.
179  *
180  * This function is created automatically.
181  */
182 //--------------------------------------------------------------------------------------------------
184 (
185  void
186 );
187 
188 
189 //--------------------------------------------------------------------------------------------------
190 /**
191  * Reference returned by Request function and used by Release function
192  */
193 //--------------------------------------------------------------------------------------------------
194 typedef struct le_data_RequestObj* le_data_RequestObjRef_t;
195 
196 
197 //--------------------------------------------------------------------------------------------------
198 /**
199  * Reference type used by Add/Remove functions for EVENT 'le_data_ConnectionState'
200  */
201 //--------------------------------------------------------------------------------------------------
202 typedef struct le_data_ConnectionStateHandler* le_data_ConnectionStateHandlerRef_t;
203 
204 
205 //--------------------------------------------------------------------------------------------------
206 /**
207  * Handler for connection state changes
208  *
209  * @param intfName
210  * Interface name for the data connection
211  * @param isConnected
212  * State: connected or disconnected
213  * @param contextPtr
214  */
215 //--------------------------------------------------------------------------------------------------
217 (
218  const char* intfName,
219  bool isConnected,
220  void* contextPtr
221 );
222 
223 //--------------------------------------------------------------------------------------------------
224 /**
225  * Add handler function for EVENT 'le_data_ConnectionState'
226  *
227  * This event provides information on connection state changes
228  */
229 //--------------------------------------------------------------------------------------------------
231 (
233  ///< [IN]
234 
235  void* contextPtr
236  ///< [IN]
237 );
238 
239 //--------------------------------------------------------------------------------------------------
240 /**
241  * Remove handler function for EVENT 'le_data_ConnectionState'
242  */
243 //--------------------------------------------------------------------------------------------------
245 (
247  ///< [IN]
248 );
249 
250 //--------------------------------------------------------------------------------------------------
251 /**
252  * Request the default data connection
253  *
254  * @return
255  * - Reference to the data connection (to be used later for releasing the connection)
256  * - NULL if the data connection requested could not be processed
257  */
258 //--------------------------------------------------------------------------------------------------
260 (
261  void
262 );
263 
264 //--------------------------------------------------------------------------------------------------
265 /**
266  * Release a previously requested data connection
267  */
268 //--------------------------------------------------------------------------------------------------
269 void le_data_Release
270 (
271  le_data_RequestObjRef_t requestRef
272  ///< [IN] Reference to a previously requested data connection
273 );
274 
275 
276 #endif // LE_DATA_INTERFACE_H_INCLUDE_GUARD
277 
void le_data_ConnectService(void)
le_result_t
Definition: le_basics.h:35
void le_data_Release(le_data_RequestObjRef_t requestRef)
void le_data_RemoveConnectionStateHandler(le_data_ConnectionStateHandlerRef_t addHandlerRef)
le_data_RequestObjRef_t le_data_Request(void)
struct le_data_RequestObj * le_data_RequestObjRef_t
Definition: le_data_interface.h:194
void(* le_data_ConnectionStateHandlerFunc_t)(const char *intfName, bool isConnected, void *contextPtr)
Definition: le_data_interface.h:217
le_result_t le_data_TryConnectService(void)
void le_data_DisconnectService(void)
struct le_data_ConnectionStateHandler * le_data_ConnectionStateHandlerRef_t
Definition: le_data_interface.h:202
le_data_ConnectionStateHandlerRef_t le_data_AddConnectionStateHandler(le_data_ConnectionStateHandlerFunc_t handlerPtr, void *contextPtr)