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