le_temp_interface.h

Go to the documentation of this file.
    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_temp Temperature Monitoring
   12  *
   13  * @ref le_temp_interface.h "API Reference" <br>
   14  * @ref platformConstraintsTemperature Constraints
   15  *
   16  * <HR>
   17  *
   18  * The Temperature API is used to retrieve temperature values and set warning and critical
   19  * thresholds.
   20  *
   21  * @warning When a Critical event occurs, some platform can automatically switch off.
   22  *
   23  * @section le_temp_binding IPC interfaces binding
   24  *
   25  * All the functions of this API are provided by the @b modemService application service.
   26  *
   27  * Here's a code sample binding to modem services:
   28  * @verbatim
   29    bindings:
   30    {
   31       clientExe.clientComponent.le_temp -> modemServices.le_temp
   32    }
   33    @endverbatim
   34  *
   35  *
   36  * @section le_temp_monitoring Monitoring
   37  *
   38  * This functionality allows to monitor the temperature by getting the temperature sensor and
   39  * by setting several temperature thresholds.
   40  *
   41  * @warning Ensure to check the names of supported sensors and thresholds for your specific
   42  * platform. Please refer to @subpage platformConstraintsTemperature platform constraints page.
   43  *
   44  * @warning An hysteresis can be dependent of the platform. Be sure to verify your platform's
   45  * specifications.
   46  *
   47  * @warning On some platforms, the thresholds parameters are persistent and a Platform reboot is
   48  * required for thresholds change takes effect.
   49  *
   50  * When temperature thresholds are reached, an event is sent with a string type that specifies the
   51  * raised threshold.
   52  *
   53  * - le_temp_Request() function allows the application to monitor a requested temperature sensor.
   54  *
   55  * - le_temp_GetSensorName() function allows the application to retrieve the temperature sensor's
   56  *   name from its reference.
   57  *
   58  * - le_temp_GetTemperature() function allows the application to retrieve the temperature of a
   59  *   sensor.
   60  *
   61  * - le_temp_GetThreshold() function allows the application to get the configured threshold
   62  *   for a sensor.
   63  *
   64  * - le_temp_SetThreshold() function allows the application to configure a threshold for a sensor.
   65  *
   66  * - le_temp_StartMonitoring() function allows to start the temperature monitoring with the
   67  *   thresholds configured by le_temp_SetThreshold() function.
   68  *
   69  * - le_temp_AddThresholdEventHandler() API adds a handler to notify when a temperature
   70  *   threshold is reached.
   71  *
   72  * - le_temp_RemoveThresholdEventHandler() API removes the temperature handler.
   73  *
   74  * <HR>
   75  *
   76  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   77  */
   78 /**
   79  * @file le_temp_interface.h
   80  *
   81  * Legato @ref c_temp include file.
   82  *
   83  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   84  */
   85 
   86 #ifndef LE_TEMP_INTERFACE_H_INCLUDE_GUARD
   87 #define LE_TEMP_INTERFACE_H_INCLUDE_GUARD
   88 
   89 
   90 #include "legato.h"
   91 
   92 //--------------------------------------------------------------------------------------------------
   93 /**
   94  *
   95  * Connect the current client thread to the service providing this API. Block until the service is
   96  * available.
   97  *
   98  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   99  * called before any other functions in this API.  Normally, ConnectService is automatically called
  100  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  101  *
  102  * This function is created automatically.
  103  */
  104 //--------------------------------------------------------------------------------------------------
  105 void le_temp_ConnectService
  106 (
  107     void
  108 );
  109 
  110 //--------------------------------------------------------------------------------------------------
  111 /**
  112  *
  113  * Try to connect the current client thread to the service providing this API. Return with an error
  114  * if the service is not available.
  115  *
  116  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  117  * called before any other functions in this API.  Normally, ConnectService is automatically called
  118  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  119  *
  120  * This function is created automatically.
  121  *
  122  * @return
  123  *  - LE_OK if the client connected successfully to the service.
  124  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  125  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  126  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  127  */
  128 //--------------------------------------------------------------------------------------------------
  129 le_result_t le_temp_TryConnectService
  130 (
  131     void
  132 );
  133 
  134 //--------------------------------------------------------------------------------------------------
  135 /**
  136  *
  137  * Disconnect the current client thread from the service providing this API.
  138  *
  139  * Normally, this function doesn't need to be called. After this function is called, there's no
  140  * longer a connection to the service, and the functions in this API can't be used. For details, see
  141  * @ref apiFilesC_client.
  142  *
  143  * This function is created automatically.
  144  */
  145 //--------------------------------------------------------------------------------------------------
  146 void le_temp_DisconnectService
  147 (
  148     void
  149 );
  150 
  151 
  152 //--------------------------------------------------------------------------------------------------
  153 /**
  154  *  Reference type for a temperature sensor.
  155  */
  156 //--------------------------------------------------------------------------------------------------
  157 typedef struct le_temp_Sensor* le_temp_SensorRef_t;
  158 
  159 
  160 //--------------------------------------------------------------------------------------------------
  161 /**
  162  * Maximum sensor's name string length.
  163  */
  164 //--------------------------------------------------------------------------------------------------
  165 #define LE_TEMP_SENSOR_NAME_MAX_LEN 100
  166 
  167 
  168 //--------------------------------------------------------------------------------------------------
  169 /**
  170  * Maximum sensor's name string length.
  171  * One extra byte is added for the null character.
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 #define LE_TEMP_SENSOR_NAME_MAX_BYTES 101
  175 
  176 
  177 //--------------------------------------------------------------------------------------------------
  178 /**
  179  * Maximum threshold's name string length.
  180  */
  181 //--------------------------------------------------------------------------------------------------
  182 #define LE_TEMP_THRESHOLD_NAME_MAX_LEN 100
  183 
  184 
  185 //--------------------------------------------------------------------------------------------------
  186 /**
  187  * Maximum threshold's name string length.
  188  * One extra byte is added for the null character.
  189  */
  190 //--------------------------------------------------------------------------------------------------
  191 #define LE_TEMP_THRESHOLD_NAME_MAX_BYTES 101
  192 
  193 
  194 //--------------------------------------------------------------------------------------------------
  195 /**
  196  * Reference type used by Add/Remove functions for EVENT 'le_temp_ThresholdEvent'
  197  */
  198 //--------------------------------------------------------------------------------------------------
  199 typedef struct le_temp_ThresholdEventHandler* le_temp_ThresholdEventHandlerRef_t;
  200 
  201 
  202 //--------------------------------------------------------------------------------------------------
  203 /**
  204  * Handler for Temperature event.
  205  *
  206  * @param sensor
  207  *        Temperature sensor reference.
  208  * @param threshold
  209  *        Name of the raised threshold.
  210  * @param contextPtr
  211  */
  212 //--------------------------------------------------------------------------------------------------
  213 typedef void (*le_temp_ThresholdEventHandlerFunc_t)
  214 (
  215     le_temp_SensorRef_t sensor,
  216     const char* threshold,
  217     void* contextPtr
  218 );
  219 
  220 //--------------------------------------------------------------------------------------------------
  221 /**
  222  * Request a temperature sensor reference.
  223  *
  224  * @return
  225  *      - Reference to the temperature sensor.
  226  *      - NULL when the requested sensor is not supported.
  227  */
  228 //--------------------------------------------------------------------------------------------------
  229 le_temp_SensorRef_t le_temp_Request
  230 (
  231     const char* sensorName
  232         ///< [IN] Name of the temperature sensor.
  233 );
  234 
  235 //--------------------------------------------------------------------------------------------------
  236 /**
  237  * Retrieve the temperature sensor's name from its reference.
  238  *
  239  * @return
  240  *      - LE_OK            The function succeeded.
  241  *      - LE_OVERFLOW      The name length exceed the maximum length.
  242  *      - LE_FAULT         The function failed.
  243  */
  244 //--------------------------------------------------------------------------------------------------
  245 le_result_t le_temp_GetSensorName
  246 (
  247     le_temp_SensorRef_t sensor,
  248         ///< [IN] Temperature sensor reference.
  249 
  250     char* sensorName,
  251         ///< [OUT] Name of the temperature sensor.
  252 
  253     size_t sensorNameNumElements
  254         ///< [IN]
  255 );
  256 
  257 //--------------------------------------------------------------------------------------------------
  258 /**
  259  * Add handler function for EVENT 'le_temp_ThresholdEvent'
  260  *
  261  * This event provides information on the threshold reached.
  262  */
  263 //--------------------------------------------------------------------------------------------------
  264 le_temp_ThresholdEventHandlerRef_t le_temp_AddThresholdEventHandler
  265 (
  266     le_temp_ThresholdEventHandlerFunc_t handlerPtr,
  267         ///< [IN]
  268 
  269     void* contextPtr
  270         ///< [IN]
  271 );
  272 
  273 //--------------------------------------------------------------------------------------------------
  274 /**
  275  * Remove handler function for EVENT 'le_temp_ThresholdEvent'
  276  */
  277 //--------------------------------------------------------------------------------------------------
  278 void le_temp_RemoveThresholdEventHandler
  279 (
  280     le_temp_ThresholdEventHandlerRef_t addHandlerRef
  281         ///< [IN]
  282 );
  283 
  284 //--------------------------------------------------------------------------------------------------
  285 /**
  286  * Get the temperature in degree Celsius.
  287  *
  288  * @return
  289  *      - LE_OK            The function succeeded.
  290  *      - LE_FAULT         The function failed to get the temperature.
  291  */
  292 //--------------------------------------------------------------------------------------------------
  293 le_result_t le_temp_GetTemperature
  294 (
  295     le_temp_SensorRef_t sensor,
  296         ///< [IN] Temperature sensor reference.
  297 
  298     int32_t* temperaturePtr
  299         ///< [OUT] Temperature in degree Celsius.
  300 );
  301 
  302 //--------------------------------------------------------------------------------------------------
  303 /**
  304  * Set the temperature threshold in degree Celsius. This function does not start the temperature
  305  * monitoring, call le_temp_StartMonitoring() to start it.
  306  *
  307  * @return
  308  *      - LE_OK            The function succeeded.
  309  *      - LE_FAULT         The function failed.
  310  */
  311 //--------------------------------------------------------------------------------------------------
  312 le_result_t le_temp_SetThreshold
  313 (
  314     le_temp_SensorRef_t sensor,
  315         ///< [IN] Temperature sensor reference.
  316 
  317     const char* threshold,
  318         ///< [IN] Name of the threshold.
  319 
  320     int32_t temperature
  321         ///< [IN] Temperature threshold in degree Celsius.
  322 );
  323 
  324 //--------------------------------------------------------------------------------------------------
  325 /**
  326  * Get the temperature threshold in degree Celsius.
  327  *
  328  * @return
  329  *      - LE_OK            The function succeeded.
  330  *      - LE_FAULT         The function failed.
  331  */
  332 //--------------------------------------------------------------------------------------------------
  333 le_result_t le_temp_GetThreshold
  334 (
  335     le_temp_SensorRef_t sensor,
  336         ///< [IN] Temperature sensor reference.
  337 
  338     const char* threshold,
  339         ///< [IN] Name of the threshold.
  340 
  341     int32_t* temperaturePtr
  342         ///< [OUT] Temperature threshold in degree Celsius.
  343 );
  344 
  345 //--------------------------------------------------------------------------------------------------
  346 /**
  347  * Start the temperature monitoring with the temperature thresholds configured by
  348  * le_temp_SetThreshold() function.
  349  *
  350  * @return
  351  *      - LE_OK            The function succeeded.
  352  *      - LE_BAD_PARAMETER There is a mismatch with the configured threshold values.
  353  *      - LE_FAULT         The function failed to apply the thresholds.
  354  */
  355 //--------------------------------------------------------------------------------------------------
  356 le_result_t le_temp_StartMonitoring
  357 (
  358     void
  359 );
  360 
  361 
  362 #endif // LE_TEMP_INTERFACE_H_INCLUDE_GUARD
  363 
le_temp_DisconnectService
void le_temp_DisconnectService(void)


le_temp_ConnectService
void le_temp_ConnectService(void)


le_temp_ThresholdEventHandlerFunc_t
void(* le_temp_ThresholdEventHandlerFunc_t)(le_temp_SensorRef_t sensor, const char *threshold, void *contextPtr)
Definition: le_temp_interface.h:214


le_result_t
le_result_t
Definition: le_basics.h:35


le_temp_AddThresholdEventHandler
le_temp_ThresholdEventHandlerRef_t le_temp_AddThresholdEventHandler(le_temp_ThresholdEventHandlerFunc_t handlerPtr, void *contextPtr)


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


le_temp_Request
le_temp_SensorRef_t le_temp_Request(const char *sensorName)


le_temp_GetSensorName
le_result_t le_temp_GetSensorName(le_temp_SensorRef_t sensor, char *sensorName, size_t sensorNameNumElements)


le_temp_GetTemperature
le_result_t le_temp_GetTemperature(le_temp_SensorRef_t sensor, int32_t *temperaturePtr)


le_temp_SensorRef_t
struct le_temp_Sensor * le_temp_SensorRef_t
Definition: le_temp_interface.h:157


le_temp_TryConnectService
le_result_t le_temp_TryConnectService(void)



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


le_temp_RemoveThresholdEventHandler
void le_temp_RemoveThresholdEventHandler(le_temp_ThresholdEventHandlerRef_t addHandlerRef)


le_temp_StartMonitoring
le_result_t le_temp_StartMonitoring(void)


le_temp_ThresholdEventHandlerRef_t
struct le_temp_ThresholdEventHandler * le_temp_ThresholdEventHandlerRef_t
Definition: le_temp_interface.h:199