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 
95 //--------------------------------------------------------------------------------------------------
96 /**
97  * Type for handler called when a server disconnects.
98  */
99 //--------------------------------------------------------------------------------------------------
100 typedef void (*le_temp_DisconnectHandler_t)(void *);
101 
102 //--------------------------------------------------------------------------------------------------
103 /**
104  *
105  * Connect the current client thread to the service providing this API. Block until the service is
106  * available.
107  *
108  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
109  * called before any other functions in this API. Normally, ConnectService is automatically called
110  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
111  *
112  * This function is created automatically.
113  */
114 //--------------------------------------------------------------------------------------------------
116 (
117  void
118 );
119 
120 //--------------------------------------------------------------------------------------------------
121 /**
122  *
123  * Try to connect the current client thread to the service providing this API. Return with an error
124  * if the service is not available.
125  *
126  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
127  * called before any other functions in this API. Normally, ConnectService is automatically called
128  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
129  *
130  * This function is created automatically.
131  *
132  * @return
133  * - LE_OK if the client connected successfully to the service.
134  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
135  * bound.
136  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
137  * - LE_COMM_ERROR if the Service Directory cannot be reached.
138  */
139 //--------------------------------------------------------------------------------------------------
141 (
142  void
143 );
144 
145 //--------------------------------------------------------------------------------------------------
146 /**
147  * Set handler called when server disconnection is detected.
148  *
149  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
150  * to continue without exiting, it should call longjmp() from inside the handler.
151  */
152 //--------------------------------------------------------------------------------------------------
154 (
155  le_temp_DisconnectHandler_t disconnectHandler,
156  void *contextPtr
157 );
158 
159 //--------------------------------------------------------------------------------------------------
160 /**
161  *
162  * Disconnect the current client thread from the service providing this API.
163  *
164  * Normally, this function doesn't need to be called. After this function is called, there's no
165  * longer a connection to the service, and the functions in this API can't be used. For details, see
166  * @ref apiFilesC_client.
167  *
168  * This function is created automatically.
169  */
170 //--------------------------------------------------------------------------------------------------
172 (
173  void
174 );
175 
176 
177 //--------------------------------------------------------------------------------------------------
178 /**
179  * Maximum sensor's name string length.
180  */
181 //--------------------------------------------------------------------------------------------------
182 #define LE_TEMP_SENSOR_NAME_MAX_LEN 100
183 
184 //--------------------------------------------------------------------------------------------------
185 /**
186  * Maximum sensor's name string length.
187  * One extra byte is added for the null character.
188  */
189 //--------------------------------------------------------------------------------------------------
190 #define LE_TEMP_SENSOR_NAME_MAX_BYTES 101
191 
192 //--------------------------------------------------------------------------------------------------
193 /**
194  * Maximum threshold's name string length.
195  */
196 //--------------------------------------------------------------------------------------------------
197 #define LE_TEMP_THRESHOLD_NAME_MAX_LEN 100
198 
199 //--------------------------------------------------------------------------------------------------
200 /**
201  * Maximum threshold's name string length.
202  * One extra byte is added for the null character.
203  */
204 //--------------------------------------------------------------------------------------------------
205 #define LE_TEMP_THRESHOLD_NAME_MAX_BYTES 101
206 
207 //--------------------------------------------------------------------------------------------------
208 /**
209  * Reference type for a temperature sensor.
210  */
211 //--------------------------------------------------------------------------------------------------
212 typedef struct le_temp_Sensor* le_temp_SensorRef_t;
213 
214 
215 //--------------------------------------------------------------------------------------------------
216 /**
217  * Reference type used by Add/Remove functions for EVENT 'le_temp_ThresholdEvent'
218  */
219 //--------------------------------------------------------------------------------------------------
220 typedef struct le_temp_ThresholdEventHandler* le_temp_ThresholdEventHandlerRef_t;
221 
222 
223 //--------------------------------------------------------------------------------------------------
224 /**
225  * Handler for Temperature event.
226  */
227 //--------------------------------------------------------------------------------------------------
229 (
230  le_temp_SensorRef_t sensor,
231  ///< Temperature sensor reference.
232  const char* LE_NONNULL threshold,
233  ///< Name of the raised threshold.
234  void* contextPtr
235  ///<
236 );
237 
238 //--------------------------------------------------------------------------------------------------
239 /**
240  * Request a temperature sensor reference.
241  *
242  * @return
243  * - Reference to the temperature sensor.
244  * - NULL when the requested sensor is not supported.
245  */
246 //--------------------------------------------------------------------------------------------------
248 (
249  const char* LE_NONNULL sensorName
250  ///< [IN] Name of the temperature sensor.
251 );
252 
253 //--------------------------------------------------------------------------------------------------
254 /**
255  * Retrieve the temperature sensor's name from its reference.
256  *
257  * @return
258  * - LE_OK The function succeeded.
259  * - LE_OVERFLOW The name length exceed the maximum length.
260  * - LE_FAULT The function failed.
261  */
262 //--------------------------------------------------------------------------------------------------
264 (
265  le_temp_SensorRef_t sensor,
266  ///< [IN] Temperature sensor reference.
267  char* sensorName,
268  ///< [OUT] Name of the temperature sensor.
269  size_t sensorNameSize
270  ///< [IN]
271 );
272 
273 //--------------------------------------------------------------------------------------------------
274 /**
275  * Add handler function for EVENT 'le_temp_ThresholdEvent'
276  *
277  * This event provides information on the threshold reached.
278  *
279  */
280 //--------------------------------------------------------------------------------------------------
282 (
283  le_temp_ThresholdEventHandlerFunc_t ThresholdEventHandlerPtr,
284  ///< [IN]
285  void* contextPtr
286  ///< [IN]
287 );
288 
289 //--------------------------------------------------------------------------------------------------
290 /**
291  * Remove handler function for EVENT 'le_temp_ThresholdEvent'
292  */
293 //--------------------------------------------------------------------------------------------------
295 (
297  ///< [IN]
298 );
299 
300 //--------------------------------------------------------------------------------------------------
301 /**
302  * Get the temperature in degree Celsius.
303  *
304  * @return
305  * - LE_OK The function succeeded.
306  * - LE_FAULT The function failed to get the temperature.
307  */
308 //--------------------------------------------------------------------------------------------------
310 (
311  le_temp_SensorRef_t sensor,
312  ///< [IN] Temperature sensor reference.
313  int32_t* temperaturePtr
314  ///< [OUT] Temperature in degree Celsius.
315 );
316 
317 //--------------------------------------------------------------------------------------------------
318 /**
319  * Set the temperature threshold in degree Celsius. This function does not start the temperature
320  * monitoring, call le_temp_StartMonitoring() to start it.
321  *
322  * @return
323  * - LE_OK The function succeeded.
324  * - LE_FAULT The function failed.
325  */
326 //--------------------------------------------------------------------------------------------------
328 (
329  le_temp_SensorRef_t sensor,
330  ///< [IN] Temperature sensor reference.
331  const char* LE_NONNULL threshold,
332  ///< [IN] Name of the threshold.
333  int32_t temperature
334  ///< [IN] Temperature threshold in degree Celsius.
335 );
336 
337 //--------------------------------------------------------------------------------------------------
338 /**
339  * Get the temperature threshold in degree Celsius.
340  *
341  * @return
342  * - LE_OK The function succeeded.
343  * - LE_FAULT The function failed.
344  */
345 //--------------------------------------------------------------------------------------------------
347 (
348  le_temp_SensorRef_t sensor,
349  ///< [IN] Temperature sensor reference.
350  const char* LE_NONNULL threshold,
351  ///< [IN] Name of the threshold.
352  int32_t* temperaturePtr
353  ///< [OUT] Temperature threshold in degree Celsius.
354 );
355 
356 //--------------------------------------------------------------------------------------------------
357 /**
358  * Start the temperature monitoring with the temperature thresholds configured by
359  * le_temp_SetThreshold() function.
360  *
361  * @return
362  * - LE_OK The function succeeded.
363  * - LE_BAD_PARAMETER There is a mismatch with the configured threshold values.
364  * - LE_FAULT The function failed to apply the thresholds.
365  */
366 //--------------------------------------------------------------------------------------------------
368 (
369  void
370 );
371 
372 #endif // LE_TEMP_INTERFACE_H_INCLUDE_GUARD
void le_temp_DisconnectService(void)
void le_temp_ConnectService(void)
void(* le_temp_ThresholdEventHandlerFunc_t)(le_temp_SensorRef_t sensor, const char *LE_NONNULL threshold, void *contextPtr)
Definition: le_temp_interface.h:229
void le_temp_RemoveThresholdEventHandler(le_temp_ThresholdEventHandlerRef_t handlerRef)
le_result_t
Definition: le_basics.h:35
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:100
le_result_t le_temp_GetTemperature(le_temp_SensorRef_t sensor, int32_t *temperaturePtr)
struct le_temp_Sensor * le_temp_SensorRef_t
Definition: le_temp_interface.h:212
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)
void le_temp_SetServerDisconnectHandler(le_temp_DisconnectHandler_t disconnectHandler, void *contextPtr)
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)
struct le_temp_ThresholdEventHandler * le_temp_ThresholdEventHandlerRef_t
Definition: le_temp_interface.h:220