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