le_temp_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_temp Temperature Monitoring
14  *
15  * @ref le_temp_interface.h "API Reference" <br>
16  * @ref SwiPlatforms Sierra Wireless Platforms Constraints
17  *
18  * <HR>
19  *
20  * The temperature monitoring API allows an application to monitor the temperature by receiving
21  * temperature values from sensors and sets warnings and critical temperature thresholds.
22  *
23  * @warning When a Critical event occurs, some platform can automatically switch off.
24  *
25  * @warning Some of the functions in this API may not be supported by your target. Please refer to
26  * @ref platformConstraintsTemperature page for full details.
27  *
28  * @section le_temp_binding IPC interfaces binding
29  *
30  * All the functions of this API are provided by the @b modemService application service.
31  *
32  * Here's a code sample binding to modem services:
33  * @verbatim
34  bindings:
35  {
36  clientExe.clientComponent.le_temp -> modemServices.le_temp
37  }
38  @endverbatim
39  *
40  *
41  * @section le_temp_monitoring Monitoring
42  *
43  * @warning Ensure to check the names of supported sensors and thresholds for your specific
44  * platform. Please refer to @ref platformConstraintsTemperature page for full details.
45  *
46  * @warning An hysteresis can be dependent of the platform. Be sure to verify your platform's
47  * specifications.
48  *
49  * @warning On some platforms, the thresholds parameters are persistent and a Platform reboot is
50  * required for thresholds change takes effect.
51  *
52  * When temperature thresholds are reached, an event is sent with a string type that specifies the
53  * raised threshold.
54  *
55  * - le_temp_Request() function allows the application to monitor a requested temperature sensor.
56  *
57  * - le_temp_GetSensorName() function allows the application to retrieve the temperature sensor's
58  * name from its reference.
59  *
60  * - le_temp_GetTemperature() function allows the application to retrieve the temperature of a
61  * sensor.
62  *
63  * - le_temp_GetThreshold() function allows the application to get the configured threshold
64  * for a sensor.
65  *
66  * - le_temp_SetThreshold() function allows the application to configure a threshold for a sensor.
67  *
68  * - le_temp_StartMonitoring() function allows to start the temperature monitoring with the
69  * thresholds configured by le_temp_SetThreshold() function.
70  *
71  * - le_temp_AddThresholdEventHandler() API adds a handler to notify when a temperature
72  * threshold is reached.
73  *
74  * - le_temp_RemoveThresholdEventHandler() API removes the temperature handler.
75  *
76  * <HR>
77  *
78  * Copyright (C) Sierra Wireless Inc.
79  */
80 /**
81  * @file le_temp_interface.h
82  *
83  * Legato @ref c_temp include file.
84  *
85  * Copyright (C) Sierra Wireless Inc.
86  */
87 
88 #ifndef LE_TEMP_INTERFACE_H_INCLUDE_GUARD
89 #define LE_TEMP_INTERFACE_H_INCLUDE_GUARD
90 
91 
92 #include "legato.h"
93 
94 // Internal includes for this interface
95 #include "le_temp_common.h"
96 //--------------------------------------------------------------------------------------------------
97 /**
98  * Type for handler called when a server disconnects.
99  */
100 //--------------------------------------------------------------------------------------------------
101 typedef void (*le_temp_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_temp_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  * Reference type for a temperature sensor.
181  */
182 //--------------------------------------------------------------------------------------------------
183 
184 
185 //--------------------------------------------------------------------------------------------------
186 /**
187  * Handler for Temperature event.
188  */
189 //--------------------------------------------------------------------------------------------------
190 
191 
192 //--------------------------------------------------------------------------------------------------
193 /**
194  * Reference type used by Add/Remove functions for EVENT 'le_temp_ThresholdEvent'
195  */
196 //--------------------------------------------------------------------------------------------------
197 
198 
199 //--------------------------------------------------------------------------------------------------
200 /**
201  * Request a temperature sensor reference.
202  *
203  * @return
204  * - Reference to the temperature sensor.
205  * - NULL when the requested sensor is not supported.
206  */
207 //--------------------------------------------------------------------------------------------------
208 le_temp_SensorRef_t le_temp_Request
209 (
210  const char* LE_NONNULL sensorName
211  ///< [IN] Name of the temperature sensor.
212 );
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  * Retrieve the temperature sensor's name from its reference.
217  *
218  * @return
219  * - LE_OK The function succeeded.
220  * - LE_OVERFLOW The name length exceed the maximum length.
221  * - LE_FAULT The function failed.
222  */
223 //--------------------------------------------------------------------------------------------------
225 (
226  le_temp_SensorRef_t sensor,
227  ///< [IN] Temperature sensor reference.
228  char* sensorName,
229  ///< [OUT] Name of the temperature sensor.
230  size_t sensorNameSize
231  ///< [IN]
232 );
233 
234 //--------------------------------------------------------------------------------------------------
235 /**
236  * Add handler function for EVENT 'le_temp_ThresholdEvent'
237  *
238  * This event provides information on the threshold reached.
239  *
240  */
241 //--------------------------------------------------------------------------------------------------
242 le_temp_ThresholdEventHandlerRef_t le_temp_AddThresholdEventHandler
243 (
244  le_temp_ThresholdEventHandlerFunc_t ThresholdEventHandlerPtr,
245  ///< [IN]
246  void* contextPtr
247  ///< [IN]
248 );
249 
250 //--------------------------------------------------------------------------------------------------
251 /**
252  * Remove handler function for EVENT 'le_temp_ThresholdEvent'
253  */
254 //--------------------------------------------------------------------------------------------------
256 (
257  le_temp_ThresholdEventHandlerRef_t handlerRef
258  ///< [IN]
259 );
260 
261 //--------------------------------------------------------------------------------------------------
262 /**
263  * Get the temperature in degree Celsius.
264  *
265  * @return
266  * - LE_OK The function succeeded.
267  * - LE_FAULT The function failed to get the temperature.
268  */
269 //--------------------------------------------------------------------------------------------------
271 (
272  le_temp_SensorRef_t sensor,
273  ///< [IN] Temperature sensor reference.
274  int32_t* temperaturePtr
275  ///< [OUT] Temperature in degree Celsius.
276 );
277 
278 //--------------------------------------------------------------------------------------------------
279 /**
280  * Set the temperature threshold in degree Celsius. This function does not start the temperature
281  * monitoring, call le_temp_StartMonitoring() to start it.
282  *
283  * @return
284  * - LE_OK The function succeeded.
285  * - LE_FAULT The function failed.
286  */
287 //--------------------------------------------------------------------------------------------------
289 (
290  le_temp_SensorRef_t sensor,
291  ///< [IN] Temperature sensor reference.
292  const char* LE_NONNULL threshold,
293  ///< [IN] Name of the threshold.
294  int32_t temperature
295  ///< [IN] Temperature threshold in degree Celsius.
296 );
297 
298 //--------------------------------------------------------------------------------------------------
299 /**
300  * Get the temperature threshold in degree Celsius.
301  *
302  * @return
303  * - LE_OK The function succeeded.
304  * - LE_FAULT The function failed.
305  */
306 //--------------------------------------------------------------------------------------------------
308 (
309  le_temp_SensorRef_t sensor,
310  ///< [IN] Temperature sensor reference.
311  const char* LE_NONNULL threshold,
312  ///< [IN] Name of the threshold.
313  int32_t* temperaturePtr
314  ///< [OUT] Temperature threshold in degree Celsius.
315 );
316 
317 //--------------------------------------------------------------------------------------------------
318 /**
319  * Start the temperature monitoring with the temperature thresholds configured by
320  * le_temp_SetThreshold() function.
321  *
322  * @return
323  * - LE_OK The function succeeded.
324  * - LE_BAD_PARAMETER There is a mismatch with the configured threshold values.
325  * - LE_FAULT The function failed to apply the thresholds.
326  */
327 //--------------------------------------------------------------------------------------------------
329 (
330  void
331 );
332 
333 #endif // LE_TEMP_INTERFACE_H_INCLUDE_GUARD
void le_temp_DisconnectService(void)
void le_temp_ConnectService(void)
LE_FULL_API void le_temp_SetServerDisconnectHandler(le_temp_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_temp_RemoveThresholdEventHandler(le_temp_ThresholdEventHandlerRef_t handlerRef)
le_result_t
Definition: le_basics.h:45
le_result_t le_temp_GetSensorName(le_temp_SensorRef_t sensor, char *sensorName, size_t sensorNameSize)
void(* le_temp_DisconnectHandler_t)(void *)
Definition: le_temp_interface.h:101
le_result_t le_temp_GetTemperature(le_temp_SensorRef_t sensor, int32_t *temperaturePtr)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_temp_TryConnectService(void)
le_temp_SensorRef_t le_temp_Request(const char *LE_NONNULL sensorName)
le_result_t le_temp_GetThreshold(le_temp_SensorRef_t sensor, const char *LE_NONNULL threshold, int32_t *temperaturePtr)
le_temp_ThresholdEventHandlerRef_t le_temp_AddThresholdEventHandler(le_temp_ThresholdEventHandlerFunc_t ThresholdEventHandlerPtr, void *contextPtr)
le_result_t le_temp_SetThreshold(le_temp_SensorRef_t sensor, const char *LE_NONNULL threshold, int32_t temperature)
le_result_t le_temp_StartMonitoring(void)