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 // Internal includes for this interface
106 #include "le_cellnet_common.h"
107 /** @addtogroup le_cellnet le_cellnet API Reference
108  * @{
109  * @file le_cellnet_common.h
110  * @file le_cellnet_interface.h **/
111 //--------------------------------------------------------------------------------------------------
112 /**
113  * Type for handler called when a server disconnects.
114  */
115 //--------------------------------------------------------------------------------------------------
116 typedef void (*le_cellnet_DisconnectHandler_t)(void *);
117 
118 //--------------------------------------------------------------------------------------------------
119 /**
120  *
121  * Connect the current client thread to the service providing this API. Block until the service is
122  * available.
123  *
124  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
125  * called before any other functions in this API. Normally, ConnectService is automatically called
126  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
127  *
128  * This function is created automatically.
129  */
130 //--------------------------------------------------------------------------------------------------
132 (
133  void
134 );
135 
136 //--------------------------------------------------------------------------------------------------
137 /**
138  *
139  * Try to connect the current client thread to the service providing this API. Return with an error
140  * if the service is not available.
141  *
142  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
143  * called before any other functions in this API. Normally, ConnectService is automatically called
144  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
145  *
146  * This function is created automatically.
147  *
148  * @return
149  * - LE_OK if the client connected successfully to the service.
150  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
151  * bound.
152  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
153  * - LE_COMM_ERROR if the Service Directory cannot be reached.
154  */
155 //--------------------------------------------------------------------------------------------------
157 (
158  void
159 );
160 
161 //--------------------------------------------------------------------------------------------------
162 /**
163  * Set handler called when server disconnection is detected.
164  *
165  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
166  * to continue without exiting, it should call longjmp() from inside the handler.
167  */
168 //--------------------------------------------------------------------------------------------------
170 (
171  le_cellnet_DisconnectHandler_t disconnectHandler,
172  void *contextPtr
173 );
174 
175 //--------------------------------------------------------------------------------------------------
176 /**
177  *
178  * Disconnect the current client thread from the service providing this API.
179  *
180  * Normally, this function doesn't need to be called. After this function is called, there's no
181  * longer a connection to the service, and the functions in this API can't be used. For details, see
182  * @ref apiFilesC_client.
183  *
184  * This function is created automatically.
185  */
186 //--------------------------------------------------------------------------------------------------
188 (
189  void
190 );
191 
192 
193 //--------------------------------------------------------------------------------------------------
194 /**
195  * Reference returned by Request function and used by Release function
196  */
197 //--------------------------------------------------------------------------------------------------
198 
199 
200 //--------------------------------------------------------------------------------------------------
201 /**
202  * Cellular Network states.
203  *
204  */
205 //--------------------------------------------------------------------------------------------------
206 
207 
208 //--------------------------------------------------------------------------------------------------
209 /**
210  * Handler for network state changes
211  */
212 //--------------------------------------------------------------------------------------------------
213 
214 
215 //--------------------------------------------------------------------------------------------------
216 /**
217  * Reference type used by Add/Remove functions for EVENT 'le_cellnet_StateEvent'
218  */
219 //--------------------------------------------------------------------------------------------------
220 
221 
222 //--------------------------------------------------------------------------------------------------
223 /**
224  * Add handler function for EVENT 'le_cellnet_StateEvent'
225  *
226  * This event provides information on network state changes
227  */
228 //--------------------------------------------------------------------------------------------------
230 (
232  ///< [IN]
233  void* contextPtr
234  ///< [IN]
235 );
236 
237 //--------------------------------------------------------------------------------------------------
238 /**
239  * Remove handler function for EVENT 'le_cellnet_StateEvent'
240  */
241 //--------------------------------------------------------------------------------------------------
243 (
245  ///< [IN]
246 );
247 
248 //--------------------------------------------------------------------------------------------------
249 /**
250  * Request a cellular network
251  *
252  * @return
253  * - A reference to the cellular network
254  * - 0 (zero) if the network requested could not be processed
255  */
256 //--------------------------------------------------------------------------------------------------
258 (
259  void
260 );
261 
262 //--------------------------------------------------------------------------------------------------
263 /**
264  * Release a cellular network
265  */
266 //--------------------------------------------------------------------------------------------------
268 (
269  le_cellnet_RequestObjRef_t cellNetRef
270  ///< [IN] Reference to a cellular network request.
271 );
272 
273 //--------------------------------------------------------------------------------------------------
274 /**
275  * Set the PIN code in the secure storage.
276  *
277  * @return
278  * - LE_OUT_OF_RANGE Invalid simId
279  * - LE_FORMAT_ERROR PIN code is not in string format.
280  * - LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
281  * - LE_OK The function succeeded.
282  * - LE_FAULT The function failed on any other errors
283  *
284  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
285  * function will not return.
286  *
287  */
288 //--------------------------------------------------------------------------------------------------
290 (
291  le_sim_Id_t simId,
292  ///< [IN] SIM identifier.
293  const char* LE_NONNULL pinCode
294  ///< [IN] PIN code to insert in the secure storage.
295 );
296 
297 //--------------------------------------------------------------------------------------------------
298 /**
299  * Retrieve the PIN code from the secure storage.
300  *
301  * @return
302  * - LE_OUT_OF_RANGE Invalid simId
303  * - LE_NOT_FOUND PIN code is not found in the secure storage.
304  * - LE_OVERFLOW PIN code exceeds the maximum length of 8 digits.
305  * - LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
306  * - LE_OK The function succeeded.
307  * - LE_FAULT If there are some other errors.
308  */
309 //--------------------------------------------------------------------------------------------------
311 (
312  le_sim_Id_t simId,
313  ///< [IN] SIM identifier.
314  char* pinCode,
315  ///< [OUT] Read the PIN code from the secure storage.
316  size_t pinCodeSize
317  ///< [IN]
318 );
319 
320 //--------------------------------------------------------------------------------------------------
321 /**
322  * Retrieve the current cellular network state.
323  *
324  * @return
325  * - LE_OK The function succeeded.
326  * - LE_FAILED The function failed
327  * - LE_BAD_PARAMETER A bad parameter was passed.
328  *
329  * @note If the caller passes a null pointer to this function, this is a fatal error and the
330  * function will not return.
331  */
332 //--------------------------------------------------------------------------------------------------
334 (
335  le_cellnet_State_t* statePtr
336  ///< [OUT] Cellular network state.
337 );
338 
339 /** @} **/
340 
341 #endif // LE_CELLNET_INTERFACE_H_INCLUDE_GUARD
struct le_cellnet_RequestObj * le_cellnet_RequestObjRef_t
Definition: le_cellnet_common.h:36
struct le_cellnet_StateEventHandler * le_cellnet_StateEventHandlerRef_t
Definition: le_cellnet_common.h:68
le_result_t
Definition: le_basics.h:46
le_cellnet_RequestObjRef_t le_cellnet_Request(void)
le_cellnet_StateEventHandlerRef_t le_cellnet_AddStateEventHandler(le_cellnet_StateHandlerFunc_t handlerPtr, void *contextPtr)
le_cellnet_State_t
Definition: le_cellnet_common.h:45
le_result_t le_cellnet_TryConnectService(void)
void le_cellnet_RemoveStateEventHandler(le_cellnet_StateEventHandlerRef_t handlerRef)
void(* le_cellnet_DisconnectHandler_t)(void *)
Definition: le_cellnet_interface.h:116
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_cellnet_GetSimPinCode(le_sim_Id_t simId, char *pinCode, size_t pinCodeSize)
void le_cellnet_DisconnectService(void)
LE_FULL_API void le_cellnet_SetServerDisconnectHandler(le_cellnet_DisconnectHandler_t disconnectHandler, void *contextPtr)
void(* le_cellnet_StateHandlerFunc_t)(le_cellnet_State_t state, void *contextPtr)
Definition: le_cellnet_common.h:77
void le_cellnet_ConnectService(void)
le_result_t le_cellnet_SetSimPinCode(le_sim_Id_t simId, const char *LE_NONNULL pinCode)
le_sim_Id_t
Definition: le_sim_common.h:228
void le_cellnet_Release(le_cellnet_RequestObjRef_t cellNetRef)
le_result_t le_cellnet_GetNetworkState(le_cellnet_State_t *statePtr)