le_cellnet_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_cellnet Cellular Network
12  *
13  * @ref le_cellnet_interface.h "API Reference"
14  *
15  * <HR>
16  *
17  * The Cellular Network service ensures that the modem is registered on the network when an user
18  * application makes a request for network access. This includes:
19  * - ensuring that the radio is turned on.
20  * - ensuring that there is a valid SIM, and it is unlocked.
21  * - ensuring that the modem is registered on the network.
22  *
23  * If all of the above conditions are met, then the service indicates that the network is available.
24  *
25  * @section le_cellnet_binding IPC interfaces binding
26  *
27  * All the functions of this API are provided by the @b cellNetService application service.
28  *
29  * Here's a code sample binding to Cellular Network services:
30  * @verbatim
31  bindings:
32  {
33  clientExe.clientComponent.le_cellnet -> cellNetService.le_cellnet
34  }
35  @endverbatim
36  *
37  * @section c_le_cellnet_requesting Requesting the Cellular Network
38  *
39  * The Cellular Network can be requested using le_cellnet_Request(). The le_cellnet_Request
40  * function will turn on the radio if it is switched off and it will unlock the SIM if a PIN code
41  * is required (it will retrieve the needed information from the config tree,
42  * cf. @ref c_le_cellnet_config).
43  * Before the cellular network is requested, an application should register a network state
44  * handler using le_cellnet_AddStateEventHandler(). Once the cellular network becomes available,
45  * the handler will be called to indicate that the modem is now registered on the network.
46  *
47  * If the state of the network changes, then the handler will be called with the new state.
48  *
49  * To release the cellular network, an application can use le_cellnet_Release(). Once all user
50  * applications release the cellular network access, then the service will turn off the radio.
51  *
52  * All configuration data required for a network registration, such as the PIN code of the SIM,
53  * will be stored in the Config tree by the use of the le_cellnet_SetSimPinCode() function.
54  *
55  *
56  * @section c_le_cellnet_config Cellular Network configuration
57  *
58  * Setting the SIM PIN code in the config tree and retreiving it is performed by two functions:
59  * le_cellnet_SetSimPinCode() and le_cellnet_GetSimPinCode().
60  *
61  * The le_cellnet_SetSimPinCode() function takes two parameters : SIM identifier and SIM card
62  * PIN code and stores the PIN code in the rigth path of the config tree.
63  * Note that the function erases the previous stored SIM card PIN code.
64  * Note that it is possible to set and retry a void entry ("") corresponding to an unlocked SIM.
65  *
66  * The le_cellnet_GetSimPinCode() function takes one parameter: the SIM identifier and retreives
67  * the SIM card PIN code from the config tree.
68  *
69  * @note
70  * when a new SIM is inserted and :
71  * - is locked, Cellular Network Service will read automatically the config tree in order to try
72  * to enter the pin for the SIM card.
73  * - is blocked, Cellular Network Service just log an error and did not try to enter the puk code.
74  * - when setting a too long PIN code (max 8 digits), a fatal error occurs, the function will
75  * not return.
76  *
77  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
78  */
79 /**
80  * @file le_cellnet_interface.h
81  *
82  * Legato @ref c_le_cellnet include file.
83  *
84  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
85  */
86 
87 #ifndef LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
88 #define LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
89 
90 
91 #include "legato.h"
92 
93 // Interface specific includes
94 #include "le_sim_interface.h"
95 
96 
97 //--------------------------------------------------------------------------------------------------
98 /**
99  *
100  * Connect the current client thread to the service providing this API. Block until the service is
101  * available.
102  *
103  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
104  * called before any other functions in this API. Normally, ConnectService is automatically called
105  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
106  *
107  * This function is created automatically.
108  */
109 //--------------------------------------------------------------------------------------------------
111 (
112  void
113 );
114 
115 //--------------------------------------------------------------------------------------------------
116 /**
117  *
118  * Try to connect the current client thread to the service providing this API. Return with an error
119  * if the service is not available.
120  *
121  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
122  * called before any other functions in this API. Normally, ConnectService is automatically called
123  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
124  *
125  * This function is created automatically.
126  *
127  * @return
128  * - LE_OK if the client connected successfully to the service.
129  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
130  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
131  * - LE_COMM_ERROR if the Service Directory cannot be reached.
132  */
133 //--------------------------------------------------------------------------------------------------
135 (
136  void
137 );
138 
139 //--------------------------------------------------------------------------------------------------
140 /**
141  *
142  * Disconnect the current client thread from the service providing this API.
143  *
144  * Normally, this function doesn't need to be called. After this function is called, there's no
145  * longer a connection to the service, and the functions in this API can't be used. For details, see
146  * @ref apiFilesC_client.
147  *
148  * This function is created automatically.
149  */
150 //--------------------------------------------------------------------------------------------------
152 (
153  void
154 );
155 
156 
157 //--------------------------------------------------------------------------------------------------
158 /**
159  * Reference returned by Request function and used by Release function
160  */
161 //--------------------------------------------------------------------------------------------------
162 typedef struct le_cellnet_RequestObj* le_cellnet_RequestObjRef_t;
163 
164 
165 //--------------------------------------------------------------------------------------------------
166 /**
167  * Cellular Network states.
168  *
169  */
170 //--------------------------------------------------------------------------------------------------
171 typedef enum
172 {
174  ///< The radio is Off.
175 
177  ///< Only Emergency calls are allowed.
178 
180  ///< Registered, home network.
181 
183  ///< Registered to a roaming network.
184 
186  ///< Unknown state.
187 }
189 
190 
191 //--------------------------------------------------------------------------------------------------
192 /**
193  * Reference type used by Add/Remove functions for EVENT 'le_cellnet_StateEvent'
194  */
195 //--------------------------------------------------------------------------------------------------
196 typedef struct le_cellnet_StateEventHandler* le_cellnet_StateEventHandlerRef_t;
197 
198 
199 //--------------------------------------------------------------------------------------------------
200 /**
201  * Handler for network state changes
202  *
203  * @param state
204  * The cellular network state
205  * @param contextPtr
206  */
207 //--------------------------------------------------------------------------------------------------
208 typedef void (*le_cellnet_StateHandlerFunc_t)
209 (
210  le_cellnet_State_t state,
211  void* contextPtr
212 );
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  * Add handler function for EVENT 'le_cellnet_StateEvent'
217  *
218  * This event provides information on network state changes
219  */
220 //--------------------------------------------------------------------------------------------------
222 (
224  ///< [IN]
225 
226  void* contextPtr
227  ///< [IN]
228 );
229 
230 //--------------------------------------------------------------------------------------------------
231 /**
232  * Remove handler function for EVENT 'le_cellnet_StateEvent'
233  */
234 //--------------------------------------------------------------------------------------------------
236 (
238  ///< [IN]
239 );
240 
241 //--------------------------------------------------------------------------------------------------
242 /**
243  * Request a cellular network
244  *
245  * @return
246  * - A reference to the cellular network
247  * - 0 (zero) if the network requested could not be processed
248  */
249 //--------------------------------------------------------------------------------------------------
251 (
252  void
253 );
254 
255 //--------------------------------------------------------------------------------------------------
256 /**
257  * Release a cellular network
258  */
259 //--------------------------------------------------------------------------------------------------
261 (
262  le_cellnet_RequestObjRef_t cellNetRef
263  ///< [IN] Reference to a cellular network request.
264 );
265 
266 //--------------------------------------------------------------------------------------------------
267 /**
268  * Set the PIN code in the config tree.
269  *
270  * @return
271  * LE_OUT_OF_RANGE Invalid simId
272  * - LE_FORMAT_ERROR PIN code is not in string format.
273  * - LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
274  * - LE_OK The function succeeded.
275  * - LE_FAULT The function failed on any other errors
276  *
277  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
278  * function will not return.
279  *
280  */
281 //--------------------------------------------------------------------------------------------------
283 (
284  le_sim_Id_t simId,
285  ///< [IN] SIM identifier.
286 
287  const char* pinCode
288  ///< [IN] PIN code to insert in the config tree.
289 );
290 
291 //--------------------------------------------------------------------------------------------------
292 /**
293  * Retreive the PIN code from the config tree.
294  *
295  * @return
296  * LE_OUT_OF_RANGE Invalid simId
297  * - LE_NOT_FOUND PIN code is not found in the config tree.
298  * - LE_OVERFLOW PIN code exceeds the maximum length of 8 digits.
299  * - LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
300  * - LE_OK The function succeeded.
301  */
302 //--------------------------------------------------------------------------------------------------
304 (
305  le_sim_Id_t simId,
306  ///< [IN] SIM identifier.
307 
308  char* pinCode,
309  ///< [OUT] Read the PIN code from the config tree.
310 
311  size_t pinCodeNumElements
312  ///< [IN]
313 );
314 
315 
316 #endif // LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
317 
le_sim_Id_t
Definition: le_sim_interface.h:544
void(* le_cellnet_StateHandlerFunc_t)(le_cellnet_State_t state, void *contextPtr)
Definition: le_cellnet_interface.h:209
le_result_t
Definition: le_basics.h:35
Unknown state.
Definition: le_cellnet_interface.h:185
le_result_t le_cellnet_TryConnectService(void)
Only Emergency calls are allowed.
Definition: le_cellnet_interface.h:176
void le_cellnet_DisconnectService(void)
The radio is Off.
Definition: le_cellnet_interface.h:173
le_cellnet_State_t
Definition: le_cellnet_interface.h:171
void le_cellnet_Release(le_cellnet_RequestObjRef_t cellNetRef)
le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler(le_cellnet_StateHandlerFunc_t handlerPtr, void *contextPtr)
le_cellnet_RequestObjRef_t le_cellnet_Request(void)
void le_cellnet_ConnectService(void)
struct le_cellnet_StateEventHandler * le_cellnet_StateEventHandlerRef_t
Definition: le_cellnet_interface.h:196
struct le_cellnet_RequestObj * le_cellnet_RequestObjRef_t
Definition: le_cellnet_interface.h:162
Registered, home network.
Definition: le_cellnet_interface.h:179
void le_cellnet_RemoveStateEventHandler(le_cellnet_StateEventHandlerRef_t addHandlerRef)
Registered to a roaming network.
Definition: le_cellnet_interface.h:182
le_result_t le_cellnet_GetSimPinCode(le_sim_Id_t simId, char *pinCode, size_t pinCodeNumElements)
le_result_t le_cellnet_SetSimPinCode(le_sim_Id_t simId, const char *pinCode)