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


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:156


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:198