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


le_temp_GetTemperature
le_result_t le_temp_GetTemperature(le_temp_SensorRef_t sensor, int32_t *temperaturePtr)


le_result_t
le_result_t
Definition: le_basics.h:46


le_temp_TryConnectService
le_result_t le_temp_TryConnectService(void)


le_temp_SetServerDisconnectHandler
LE_FULL_API void le_temp_SetServerDisconnectHandler(le_temp_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_temp_DisconnectHandler_t
void(* le_temp_DisconnectHandler_t)(void *)
Definition: le_temp_interface.h:105


le_temp_SetThreshold
le_result_t le_temp_SetThreshold(le_temp_SensorRef_t sensor, const char *LE_NONNULL threshold, int32_t temperature)


le_temp_RemoveThresholdEventHandler
void le_temp_RemoveThresholdEventHandler(le_temp_ThresholdEventHandlerRef_t handlerRef)


le_temp_ThresholdEventHandlerRef_t
struct le_temp_ThresholdEventHandler * le_temp_ThresholdEventHandlerRef_t
Definition: le_temp_common.h:71


le_temp_ThresholdEventHandlerFunc_t
void(* le_temp_ThresholdEventHandlerFunc_t)(le_temp_SensorRef_t sensor, const char *LE_NONNULL threshold, void *contextPtr)
Definition: le_temp_common.h:80


le_temp_StartMonitoring
le_result_t le_temp_StartMonitoring(void)


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40



le_temp_DisconnectService
void le_temp_DisconnectService(void)


le_temp_SensorRef_t
struct le_temp_Sensor * le_temp_SensorRef_t
Definition: le_temp_common.h:63


le_temp_common.h


le_temp_Request
le_temp_SensorRef_t le_temp_Request(const char *LE_NONNULL sensorName)


le_temp_GetThreshold
le_result_t le_temp_GetThreshold(le_temp_SensorRef_t sensor, const char *LE_NONNULL threshold, int32_t *temperaturePtr)


le_temp_AddThresholdEventHandler
le_temp_ThresholdEventHandlerRef_t le_temp_AddThresholdEventHandler(le_temp_ThresholdEventHandlerFunc_t ThresholdEventHandlerPtr, void *contextPtr)


le_temp_ConnectService
void le_temp_ConnectService(void)