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(). This function will turn on the
40  * radio if it is switched off and it will unlock the SIM if a PIN code is required (the necessary
41  * information will be retrieved from the secure storage, cf. @ref c_le_cellnet_config).
42  *
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  * The current cellular network state can also be retrieved with le_cellnet_GetNetworkState().
49  * @note There might be a discrepancy between the state notified by the handler and the state
50  * retrieved through le_cellnet_GetNetworkState(): the state can have changed between the event
51  * notification and its treatment by the application.
52  *
53  * To release the cellular network, an application can use le_cellnet_Release(). Once all user
54  * applications release the cellular network access, then the service will turn off the radio.
55  *
56  * The application can release the network state handler by calling
57  * le_cellnet_RemoveStateEventHandler() when it is not needed anymore.
58  *
59  * All configuration data required for a network registration, such as the PIN code of the SIM,
60  * will be stored in the secure storage by the use of the le_cellnet_SetSimPinCode() function.
61  *
62  *
63  * @section c_le_cellnet_config Cellular Network configuration
64  *
65  * Setting the SIM PIN code in the secure storage and retrieving it is performed by two functions:
66  * le_cellnet_SetSimPinCode() and le_cellnet_GetSimPinCode().
67  *
68  * The le_cellnet_SetSimPinCode() function stores the PIN code in the secure storage and takes two
69  * parameters: the SIM identifier and the SIM card PIN code.
70  *
71  * @note The function erases the previously stored SIM card PIN code.
72  * @note It is possible to set and retry a void entry ("") corresponding to an unlocked SIM.
73  *
74  * The le_cellnet_GetSimPinCode() function retrieves the SIM card PIN code from the secure storage
75  * and takes one parameter: the SIM identifier.
76  *
77  * @note The action carried out by the Cellular Network Service when a new SIM is inserted depends
78  * on the SIM state:
79  * - if the SIM is locked, it will automatically read the secure storage in order to try to enter
80  * the PIN code for the SIM card. If the PIN code is not set or too long (max 8 digits), an
81  * error will be logged and the SIM will not be unlocked.
82  * - is the SIM is blocked, it just logs an error and does not try to enter the PUK code.
83  *
84  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
85  */
86 /**
87  * @file le_cellnet_interface.h
88  *
89  * Legato @ref c_le_cellnet include file.
90  *
91  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
92  */
93 
94 #ifndef LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
95 #define LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
96 
97 
98 #include "legato.h"
99 
100 // Interface specific includes
101 #include "le_sim_interface.h"
102 
103 
104 //--------------------------------------------------------------------------------------------------
105 /**
106  *
107  * Connect the current client thread to the service providing this API. Block until the service is
108  * available.
109  *
110  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
111  * called before any other functions in this API. Normally, ConnectService is automatically called
112  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
113  *
114  * This function is created automatically.
115  */
116 //--------------------------------------------------------------------------------------------------
118 (
119  void
120 );
121 
122 //--------------------------------------------------------------------------------------------------
123 /**
124  *
125  * Try to connect the current client thread to the service providing this API. Return with an error
126  * if the service is not available.
127  *
128  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
129  * called before any other functions in this API. Normally, ConnectService is automatically called
130  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
131  *
132  * This function is created automatically.
133  *
134  * @return
135  * - LE_OK if the client connected successfully to the service.
136  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
137  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
138  * - LE_COMM_ERROR if the Service Directory cannot be reached.
139  */
140 //--------------------------------------------------------------------------------------------------
142 (
143  void
144 );
145 
146 //--------------------------------------------------------------------------------------------------
147 /**
148  *
149  * Disconnect the current client thread from the service providing this API.
150  *
151  * Normally, this function doesn't need to be called. After this function is called, there's no
152  * longer a connection to the service, and the functions in this API can't be used. For details, see
153  * @ref apiFilesC_client.
154  *
155  * This function is created automatically.
156  */
157 //--------------------------------------------------------------------------------------------------
159 (
160  void
161 );
162 
163 
164 //--------------------------------------------------------------------------------------------------
165 /**
166  * Reference returned by Request function and used by Release function
167  */
168 //--------------------------------------------------------------------------------------------------
169 typedef struct le_cellnet_RequestObj* le_cellnet_RequestObjRef_t;
170 
171 
172 //--------------------------------------------------------------------------------------------------
173 /**
174  * Cellular Network states.
175  *
176  */
177 //--------------------------------------------------------------------------------------------------
178 typedef enum
179 {
181  ///< The radio is switched-off.
182 
184  ///< Only emergency calls are allowed.
185 
187  ///< Registered, home network.
188 
190  ///< Registered to a roaming network.
191 
193  ///< Unknown state.
194 
196  ///< No SIM card available.
197 }
199 
200 
201 //--------------------------------------------------------------------------------------------------
202 /**
203  * Reference type used by Add/Remove functions for EVENT 'le_cellnet_StateEvent'
204  */
205 //--------------------------------------------------------------------------------------------------
206 typedef struct le_cellnet_StateEventHandler* le_cellnet_StateEventHandlerRef_t;
207 
208 
209 //--------------------------------------------------------------------------------------------------
210 /**
211  * Handler for network state changes
212  *
213  * @param state
214  * The cellular network state
215  * @param contextPtr
216  */
217 //--------------------------------------------------------------------------------------------------
218 typedef void (*le_cellnet_StateHandlerFunc_t)
219 (
220  le_cellnet_State_t state,
221  void* contextPtr
222 );
223 
224 //--------------------------------------------------------------------------------------------------
225 /**
226  * Add handler function for EVENT 'le_cellnet_StateEvent'
227  *
228  * This event provides information on network state changes
229  */
230 //--------------------------------------------------------------------------------------------------
232 (
234  ///< [IN]
235 
236  void* contextPtr
237  ///< [IN]
238 );
239 
240 //--------------------------------------------------------------------------------------------------
241 /**
242  * Remove handler function for EVENT 'le_cellnet_StateEvent'
243  */
244 //--------------------------------------------------------------------------------------------------
246 (
248  ///< [IN]
249 );
250 
251 //--------------------------------------------------------------------------------------------------
252 /**
253  * Request a cellular network
254  *
255  * @return
256  * - A reference to the cellular network
257  * - 0 (zero) if the network requested could not be processed
258  */
259 //--------------------------------------------------------------------------------------------------
261 (
262  void
263 );
264 
265 //--------------------------------------------------------------------------------------------------
266 /**
267  * Release a cellular network
268  */
269 //--------------------------------------------------------------------------------------------------
271 (
272  le_cellnet_RequestObjRef_t cellNetRef
273  ///< [IN] Reference to a cellular network request.
274 );
275 
276 //--------------------------------------------------------------------------------------------------
277 /**
278  * Set the PIN code in the secure storage.
279  *
280  * @return
281  * - LE_OUT_OF_RANGE Invalid simId
282  * - LE_FORMAT_ERROR PIN code is not in string format.
283  * - LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
284  * - LE_OK The function succeeded.
285  * - LE_FAULT The function failed on any other errors
286  *
287  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
288  * function will not return.
289  *
290  */
291 //--------------------------------------------------------------------------------------------------
293 (
294  le_sim_Id_t simId,
295  ///< [IN] SIM identifier.
296 
297  const char* pinCode
298  ///< [IN] PIN code to insert in the secure storage.
299 );
300 
301 //--------------------------------------------------------------------------------------------------
302 /**
303  * Retrieve the PIN code from the secure storage.
304  *
305  * @return
306  * - LE_OUT_OF_RANGE Invalid simId
307  * - LE_NOT_FOUND PIN code is not found in the secure storage.
308  * - LE_OVERFLOW PIN code exceeds the maximum length of 8 digits.
309  * - LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
310  * - LE_OK The function succeeded.
311  */
312 //--------------------------------------------------------------------------------------------------
314 (
315  le_sim_Id_t simId,
316  ///< [IN] SIM identifier.
317 
318  char* pinCode,
319  ///< [OUT] Read the PIN code from the secure storage.
320 
321  size_t pinCodeNumElements
322  ///< [IN]
323 );
324 
325 //--------------------------------------------------------------------------------------------------
326 /**
327  * Retrieve the current cellular network state.
328  *
329  * @return
330  * - LE_OK The function succeeded.
331  * - LE_FAILED The function failed
332  * - LE_BAD_PARAMETER A bad parameter was passed.
333  *
334  * @note If the caller passes a null pointer to this function, this is a fatal error and the
335  * function will not return.
336  */
337 //--------------------------------------------------------------------------------------------------
339 (
340  le_cellnet_State_t* statePtr
341  ///< [OUT] Cellular network state.
342 );
343 
344 
345 #endif // LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
346 
le_sim_Id_t
Definition: le_sim_interface.h:550
void(* le_cellnet_StateHandlerFunc_t)(le_cellnet_State_t state, void *contextPtr)
Definition: le_cellnet_interface.h:219
le_result_t
Definition: le_basics.h:35
Unknown state.
Definition: le_cellnet_interface.h:192
le_result_t le_cellnet_TryConnectService(void)
Only emergency calls are allowed.
Definition: le_cellnet_interface.h:183
void le_cellnet_DisconnectService(void)
No SIM card available.
Definition: le_cellnet_interface.h:195
The radio is switched-off.
Definition: le_cellnet_interface.h:180
le_cellnet_State_t
Definition: le_cellnet_interface.h:178
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:206
struct le_cellnet_RequestObj * le_cellnet_RequestObjRef_t
Definition: le_cellnet_interface.h:169
Registered, home network.
Definition: le_cellnet_interface.h:186
void le_cellnet_RemoveStateEventHandler(le_cellnet_StateEventHandlerRef_t addHandlerRef)
Registered to a roaming network.
Definition: le_cellnet_interface.h:189
le_result_t le_cellnet_GetSimPinCode(le_sim_Id_t simId, char *pinCode, size_t pinCodeNumElements)
le_result_t le_cellnet_GetNetworkState(le_cellnet_State_t *statePtr)
le_result_t le_cellnet_SetSimPinCode(le_sim_Id_t simId, const char *pinCode)