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 // Internal includes for this interface
96 #include "le_lpt_common.h"
97 //--------------------------------------------------------------------------------------------------
98 /**
99  * Type for handler called when a server disconnects.
100  */
101 //--------------------------------------------------------------------------------------------------
102 typedef void (*le_lpt_DisconnectHandler_t)(void *);
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
137  * bound.
138  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
139  * - LE_COMM_ERROR if the Service Directory cannot be reached.
140  */
141 //--------------------------------------------------------------------------------------------------
143 (
144  void
145 );
146 
147 //--------------------------------------------------------------------------------------------------
148 /**
149  * Set handler called when server disconnection is detected.
150  *
151  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
152  * to continue without exiting, it should call longjmp() from inside the handler.
153  */
154 //--------------------------------------------------------------------------------------------------
156 (
157  le_lpt_DisconnectHandler_t disconnectHandler,
158  void *contextPtr
159 );
160 
161 //--------------------------------------------------------------------------------------------------
162 /**
163  *
164  * Disconnect the current client thread from the service providing this API.
165  *
166  * Normally, this function doesn't need to be called. After this function is called, there's no
167  * longer a connection to the service, and the functions in this API can't be used. For details, see
168  * @ref apiFilesC_client.
169  *
170  * This function is created automatically.
171  */
172 //--------------------------------------------------------------------------------------------------
174 (
175  void
176 );
177 
178 
179 //--------------------------------------------------------------------------------------------------
180 /**
181  * eDRX Radio Access Technology enum
182  */
183 //--------------------------------------------------------------------------------------------------
184 
185 
186 //--------------------------------------------------------------------------------------------------
187 /**
188  * Handler to report a change in the network-provided eDRX parameters.
189  */
190 //--------------------------------------------------------------------------------------------------
191 
192 
193 //--------------------------------------------------------------------------------------------------
194 /**
195  * Reference type used by Add/Remove functions for EVENT 'le_lpt_EDrxParamsChange'
196  */
197 //--------------------------------------------------------------------------------------------------
198 
199 
200 //--------------------------------------------------------------------------------------------------
201 /**
202  * Set the eDRX activation state for the given Radio Access Technology.
203  *
204  * @return
205  * - LE_OK The function succeeded.
206  * - LE_BAD_PARAMETER A parameter is invalid.
207  * - LE_UNSUPPORTED eDRX is not supported by the platform.
208  * - LE_FAULT The function failed.
209  */
210 //--------------------------------------------------------------------------------------------------
212 (
213  le_lpt_EDrxRat_t rat,
214  ///< [IN] Radio Access Technology.
215  le_onoff_t activation
216  ///< [IN] eDRX activation state.
217 );
218 
219 //--------------------------------------------------------------------------------------------------
220 /**
221  * Set the requested eDRX cycle value for the given Radio Access Technology.
222  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
223  *
224  * @return
225  * - LE_OK The function succeeded.
226  * - LE_BAD_PARAMETER A parameter is invalid.
227  * - LE_UNSUPPORTED eDRX is not supported by the platform.
228  * - LE_FAULT The function failed.
229  */
230 //--------------------------------------------------------------------------------------------------
232 (
233  le_lpt_EDrxRat_t rat,
234  ///< [IN] Radio Access Technology.
235  uint8_t eDrxValue
236  ///< [IN] Requested eDRX cycle value, defined in 3GPP
237  ///< TS 24.008 Rel-13 section 10.5.5.32.
238 );
239 
240 //--------------------------------------------------------------------------------------------------
241 /**
242  * Get the requested eDRX cycle value for the given Radio Access Technology.
243  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
244  *
245  * @return
246  * - LE_OK The function succeeded.
247  * - LE_BAD_PARAMETER A parameter is invalid.
248  * - LE_UNSUPPORTED eDRX is not supported by the platform.
249  * - LE_UNAVAILABLE No requested eDRX cycle value.
250  * - LE_FAULT The function failed.
251  */
252 //--------------------------------------------------------------------------------------------------
254 (
255  le_lpt_EDrxRat_t rat,
256  ///< [IN] Radio Access Technology.
257  uint8_t* eDrxValuePtr
258  ///< [OUT] Requested eDRX cycle value, defined in 3GPP
259  ///< TS 24.008 Rel-13 section 10.5.5.32.
260 );
261 
262 //--------------------------------------------------------------------------------------------------
263 /**
264  * Get the network-provided eDRX cycle value for the given Radio Access Technology.
265  * The eDRX cycle value is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
266  *
267  * @return
268  * - LE_OK The function succeeded.
269  * - LE_BAD_PARAMETER A parameter is invalid.
270  * - LE_UNSUPPORTED eDRX is not supported by the platform.
271  * - LE_UNAVAILABLE No network-provided eDRX cycle value.
272  * - LE_FAULT The function failed.
273  */
274 //--------------------------------------------------------------------------------------------------
276 (
277  le_lpt_EDrxRat_t rat,
278  ///< [IN] Radio Access Technology.
279  uint8_t* eDrxValuePtr
280  ///< [OUT] Network-provided eDRX cycle value, defined in
281  ///< 3GPP TS 24.008 Rel-13 section 10.5.5.32.
282 );
283 
284 //--------------------------------------------------------------------------------------------------
285 /**
286  * Get the network-provided Paging Time Window for the given Radio Access Technology.
287  * The Paging Time Window is defined in 3GPP TS 24.008 Release 13 section 10.5.5.32.
288  *
289  * @return
290  * - LE_OK The function succeeded.
291  * - LE_BAD_PARAMETER A parameter is invalid.
292  * - LE_UNSUPPORTED eDRX is not supported by the platform.
293  * - LE_UNAVAILABLE No defined Paging Time Window.
294  * - LE_FAULT The function failed.
295  */
296 //--------------------------------------------------------------------------------------------------
298 (
299  le_lpt_EDrxRat_t rat,
300  ///< [IN] Radio Access Technology.
301  uint8_t* pagingTimeWindowPtr
302  ///< [OUT] Network-provided Paging Time Window, defined
303  ///< in 3GPP TS 24.008 Rel-13 section 10.5.5.32.
304 );
305 
306 //--------------------------------------------------------------------------------------------------
307 /**
308  * Add handler function for EVENT 'le_lpt_EDrxParamsChange'
309  *
310  * Event to report a change in the network-provided eDRX parameters.
311  */
312 //--------------------------------------------------------------------------------------------------
313 le_lpt_EDrxParamsChangeHandlerRef_t le_lpt_AddEDrxParamsChangeHandler
314 (
315  le_lpt_EDrxParamsChangeHandlerFunc_t handlerPtr,
316  ///< [IN]
317  void* contextPtr
318  ///< [IN]
319 );
320 
321 //--------------------------------------------------------------------------------------------------
322 /**
323  * Remove handler function for EVENT 'le_lpt_EDrxParamsChange'
324  */
325 //--------------------------------------------------------------------------------------------------
327 (
328  le_lpt_EDrxParamsChangeHandlerRef_t handlerRef
329  ///< [IN]
330 );
331 
332 #endif // LE_LPT_INTERFACE_H_INCLUDE_GUARD
le_lpt_EDrxParamsChangeHandlerRef_t le_lpt_AddEDrxParamsChangeHandler(le_lpt_EDrxParamsChangeHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t
Definition: le_basics.h:35
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)
le_result_t le_lpt_GetRequestedEDrxValue(le_lpt_EDrxRat_t rat, uint8_t *eDrxValuePtr)
void(* le_lpt_DisconnectHandler_t)(void *)
Definition: le_lpt_interface.h:102
void le_lpt_DisconnectService(void)
LE_FULL_API void le_lpt_SetServerDisconnectHandler(le_lpt_DisconnectHandler_t disconnectHandler, void *contextPtr)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
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)
le_onoff_t
Definition: le_basics.h:71