le_lpt_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_lpt Low Power Technologies
14  *
15  * @ref le_lpt_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * The Low Power Technologies (LPT) APIs are used to control the low power features of the modem.
20  *
21  * @section le_lpt_binding IPC interfaces binding
22  *
23  * All the functions of this API are provided by the @b modemService service.
24  *
25  * Here's a code sample binding to modem services:
26  * @verbatim
27  bindings:
28  {
29  clientExe.clientComponent.le_lpt -> modemService.le_lpt
30  }
31  @endverbatim
32  *
33  * @section le_lpt_eDRX eDRX
34  *
35  * The extended idle-mode discontinuous reception (eDRX) is a mechanism that reduces power
36  * consumption by extending the sleeping cycle in idle mode. It allows the device to turn part of
37  * its circuitry off during the extended DRX period to save power. During the extended DRX period,
38  * the device is not listening for paging or downlink control channels, so the network should not
39  * try to contact the device.
40  *
41  * @warning Enabling eDRX introduces a longer latency in reaching the device and should therefore
42  * not be used by systems that cannot handle it, e.g. systems supporting mobile-terminated voice.
43  *
44  * The use of eDRX for a given radio access technology (@ref le_lpt_EDrxRat_t) can be enabled and
45  * disabled with le_lpt_SetEDrxState().
46  *
47  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" Set state
48  *
49  * The eDRX feature is controlled by two parameters, which are defined in the standard 3GPP
50  * TS 24.008 Release 13 Section 10.5.5.32: the eDRX value, defining the eDRX cycle length, and
51  * the Paging Time Window. These parameters are negotiated between the device and the network during
52  * an attach or routing area updating procedure.
53  *
54  * The requested eDRX value can be set with le_lpt_SetRequestedEDrxValue() and retrieved with
55  * le_lpt_GetRequestedEDrxValue().
56  *
57  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" eDRX value
58  *
59  * The eDRX value provided by the network can be retrieved with
60  * le_lpt_GetNetworkProvidedEDrxValue().
61  *
62  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" NP eDRX value
63  *
64  * The requested Paging Time Window cannot be set, but the network-provided value can be retrieved
65  * with le_lpt_GetNetworkProvidedPagingTimeWindow().
66  *
67  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" NP PTW
68  *
69  * A handler can also be registered with le_lpt_AddEDrxParamsChangeHandler() in order to be notified
70  * of the changes in the network-provided eDRX parameters.
71  *
72  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" eDRX handler
73  * @snippet "apps/test/modemServices/lpt/lptIntegrationTest/lptTest/lptTest.c" Add eDRX handler
74  *
75  * The handler can be removed with le_lpt_RemoveEDrxParamsChangeHandler().
76  *
77  * <HR>
78  *
79  * Copyright (C) Sierra Wireless Inc.
80  */
81 /**
82  * @file le_lpt_interface.h
83  *
84  * Legato @ref c_lpt include file.
85  *
86  * Copyright (C) Sierra Wireless Inc.
87  */
88 
89 #ifndef LE_LPT_INTERFACE_H_INCLUDE_GUARD
90 #define LE_LPT_INTERFACE_H_INCLUDE_GUARD
91 
92 
93 #include "legato.h"
94 
95 
96 //--------------------------------------------------------------------------------------------------
97 /**
98  * Type for handler called when a server disconnects.
99  */
100 //--------------------------------------------------------------------------------------------------
101 typedef void (*le_lpt_DisconnectHandler_t)(void *);
102 
103 //--------------------------------------------------------------------------------------------------
104 /**
105  *
106  * Connect the current client thread to the service providing this API. Block until the service is
107  * available.
108  *
109  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
110  * called before any other functions in this API. Normally, ConnectService is automatically called
111  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
112  *
113  * This function is created automatically.
114  */
115 //--------------------------------------------------------------------------------------------------
117 (
118  void
119 );
120 
121 //--------------------------------------------------------------------------------------------------
122 /**
123  *
124  * Try to connect the current client thread to the service providing this API. Return with an error
125  * if the service is not available.
126  *
127  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
128  * called before any other functions in this API. Normally, ConnectService is automatically called
129  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
130  *
131  * This function is created automatically.
132  *
133  * @return
134  * - LE_OK if the client connected successfully to the service.
135  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
136  * 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  * Set handler called when server disconnection is detected.
149  *
150  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
151  * to continue without exiting, it should call longjmp() from inside the handler.
152  */
153 //--------------------------------------------------------------------------------------------------
155 (
156  le_lpt_DisconnectHandler_t disconnectHandler,
157  void *contextPtr
158 );
159 
160 //--------------------------------------------------------------------------------------------------
161 /**
162  *
163  * Disconnect the current client thread from the service providing this API.
164  *
165  * Normally, this function doesn't need to be called. After this function is called, there's no
166  * longer a connection to the service, and the functions in this API can't be used. For details, see
167  * @ref apiFilesC_client.
168  *
169  * This function is created automatically.
170  */
171 //--------------------------------------------------------------------------------------------------
173 (
174  void
175 );
176 
177 
178 //--------------------------------------------------------------------------------------------------
179 /**
180  * eDRX Radio Access Technology enum
181  */
182 //--------------------------------------------------------------------------------------------------
183 typedef enum
184 {
186  ///< Unknown
188  ///< EC-GSM-IoT (A/Gb mode)
190  ///< GSM (A/Gb mode)
192  ///< UTRAN (Iu mode)
194  ///< E-UTRAN (WB-S1 mode)
196  ///< E-UTRAN (NB-S1 mode)
198  ///< Invalid
199 }
201 
202 
203 //--------------------------------------------------------------------------------------------------
204 /**
205  * Reference type used by Add/Remove functions for EVENT 'le_lpt_EDrxParamsChange'
206  */
207 //--------------------------------------------------------------------------------------------------
208 typedef struct le_lpt_EDrxParamsChangeHandler* le_lpt_EDrxParamsChangeHandlerRef_t;
209 
210 
211 //--------------------------------------------------------------------------------------------------
212 /**
213  * Handler to report a change in the network-provided eDRX parameters.
214  */
215 //--------------------------------------------------------------------------------------------------
217 (
218  le_lpt_EDrxRat_t rat,
219  ///< Radio Access Technology.
220  le_onoff_t activation,
221  ///< eDRX activation state.
222  uint8_t eDrxValue,
223  ///< eDRX cycle value, defined in 3GPP
224  ///< TS 24.008 Rel-13 section 10.5.5.32.
225  uint8_t pagingTimeWindow,
226  ///< Paging Time Window, defined in 3GPP
227  ///< TS 24.008 Rel-13 section 10.5.5.32.
228  void* contextPtr
229  ///<
230 );
231 
232 //--------------------------------------------------------------------------------------------------
233 /**
234  * Set the eDRX activation state for the given Radio Access Technology.
235  *
236  * @return
237  * - LE_OK The function succeeded.
238  * - LE_BAD_PARAMETER A parameter is invalid.
239  * - LE_UNSUPPORTED eDRX is not supported by the platform.
240  * - LE_FAULT The function failed.
241  */
242 //--------------------------------------------------------------------------------------------------
244 (
245  le_lpt_EDrxRat_t rat,
246  ///< [IN] Radio Access Technology.
247  le_onoff_t activation
248  ///< [IN] eDRX activation state.
249 );
250 
251 //--------------------------------------------------------------------------------------------------
252 /**
253  * Set the requested eDRX cycle value for the given Radio Access Technology.
254  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
255  *
256  * @return
257  * - LE_OK The function succeeded.
258  * - LE_BAD_PARAMETER A parameter is invalid.
259  * - LE_UNSUPPORTED eDRX is not supported by the platform.
260  * - LE_FAULT The function failed.
261  */
262 //--------------------------------------------------------------------------------------------------
264 (
265  le_lpt_EDrxRat_t rat,
266  ///< [IN] Radio Access Technology.
267  uint8_t eDrxValue
268  ///< [IN] Requested eDRX cycle value, defined in 3GPP
269  ///< TS 24.008 Rel-13 section 10.5.5.32.
270 );
271 
272 //--------------------------------------------------------------------------------------------------
273 /**
274  * Get the requested eDRX cycle value for the given Radio Access Technology.
275  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
276  *
277  * @return
278  * - LE_OK The function succeeded.
279  * - LE_BAD_PARAMETER A parameter is invalid.
280  * - LE_UNSUPPORTED eDRX is not supported by the platform.
281  * - LE_UNAVAILABLE No requested eDRX cycle value.
282  * - LE_FAULT The function failed.
283  */
284 //--------------------------------------------------------------------------------------------------
286 (
287  le_lpt_EDrxRat_t rat,
288  ///< [IN] Radio Access Technology.
289  uint8_t* eDrxValuePtr
290  ///< [OUT] Requested eDRX cycle value, defined in 3GPP
291  ///< TS 24.008 Rel-13 section 10.5.5.32.
292 );
293 
294 //--------------------------------------------------------------------------------------------------
295 /**
296  * Get the network-provided eDRX cycle value for the given Radio Access Technology.
297  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
298  *
299  * @return
300  * - LE_OK The function succeeded.
301  * - LE_BAD_PARAMETER A parameter is invalid.
302  * - LE_UNSUPPORTED eDRX is not supported by the platform.
303  * - LE_UNAVAILABLE No network-provided eDRX cycle value.
304  * - LE_FAULT The function failed.
305  */
306 //--------------------------------------------------------------------------------------------------
308 (
309  le_lpt_EDrxRat_t rat,
310  ///< [IN] Radio Access Technology.
311  uint8_t* eDrxValuePtr
312  ///< [OUT] Network-provided eDRX cycle value, defined in
313  ///< 3GPP TS 24.008 Rel-13 section 10.5.5.32.
314 );
315 
316 //--------------------------------------------------------------------------------------------------
317 /**
318  * Get the network-provided Paging Time Window for the given Radio Access Technology.
319  * The Paging Time Window is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
320  *
321  * @return
322  * - LE_OK The function succeeded.
323  * - LE_BAD_PARAMETER A parameter is invalid.
324  * - LE_UNSUPPORTED eDRX is not supported by the platform.
325  * - LE_UNAVAILABLE No defined Paging Time Window.
326  * - LE_FAULT The function failed.
327  */
328 //--------------------------------------------------------------------------------------------------
330 (
331  le_lpt_EDrxRat_t rat,
332  ///< [IN] Radio Access Technology.
333  uint8_t* pagingTimeWindowPtr
334  ///< [OUT] Network-provided Paging Time Window, defined
335  ///< in 3GPP TS 24.008 Rel-13 section 10.5.5.32.
336 );
337 
338 //--------------------------------------------------------------------------------------------------
339 /**
340  * Add handler function for EVENT 'le_lpt_EDrxParamsChange'
341  *
342  * Event to report a change in the network-provided eDRX parameters.
343  */
344 //--------------------------------------------------------------------------------------------------
346 (
348  ///< [IN]
349  void* contextPtr
350  ///< [IN]
351 );
352 
353 //--------------------------------------------------------------------------------------------------
354 /**
355  * Remove handler function for EVENT 'le_lpt_EDrxParamsChange'
356  */
357 //--------------------------------------------------------------------------------------------------
359 (
361  ///< [IN]
362 );
363 
364 #endif // LE_LPT_INTERFACE_H_INCLUDE_GUARD
EC-GSM-IoT (A/Gb mode)
Definition: le_lpt_interface.h:187
le_lpt_EDrxParamsChangeHandlerRef_t le_lpt_AddEDrxParamsChangeHandler(le_lpt_EDrxParamsChangeHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t
Definition: le_basics.h:35
struct le_lpt_EDrxParamsChangeHandler * le_lpt_EDrxParamsChangeHandlerRef_t
Definition: le_lpt_interface.h:208
Invalid.
Definition: le_lpt_interface.h:197
le_result_t le_lpt_GetNetworkProvidedPagingTimeWindow(le_lpt_EDrxRat_t rat, uint8_t *pagingTimeWindowPtr)
le_result_t le_lpt_GetNetworkProvidedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t *eDrxValuePtr)
UTRAN (Iu mode)
Definition: le_lpt_interface.h:191
Unknown.
Definition: le_lpt_interface.h:185
le_result_t le_lpt_GetRequestedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t *eDrxValuePtr)
GSM (A/Gb mode)
Definition: le_lpt_interface.h:189
void(* le_lpt_DisconnectHandler_t)(void *)
Definition: le_lpt_interface.h:101
void le_lpt_DisconnectService(void)
E-UTRAN (NB-S1 mode)
Definition: le_lpt_interface.h:195
le_lpt_EDrxRat_t
Definition: le_lpt_interface.h:183
E-UTRAN (WB-S1 mode)
Definition: le_lpt_interface.h:193
le_result_t le_lpt_SetEDrxState(le_lpt_EDrxRat_t rat, le_onoff_t activation)
le_result_t le_lpt_TryConnectService(void)
void le_lpt_RemoveEDrxParamsChangeHandler(le_lpt_EDrxParamsChangeHandlerRef_t handlerRef)
le_result_t le_lpt_SetRequestedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t eDrxValue)
void le_lpt_ConnectService(void)
void(* le_lpt_EDrxParamsChangeHandlerFunc_t)(le_lpt_EDrxRat_t rat, le_onoff_t activation, uint8_t eDrxValue, uint8_t pagingTimeWindow, void *contextPtr)
Definition: le_lpt_interface.h:217
void le_lpt_SetServerDisconnectHandler(le_lpt_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_onoff_t
Definition: le_basics.h:70