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 platformConstraintsTemperature Constraints
   17  *
   18  * <HR>
   19  *
   20  * The Temperature API is used to retrieve temperature values and set warning and critical
   21  * thresholds.
   22  *
   23  * @warning When a Critical event occurs, some platform can automatically switch off.
   24  *
   25  * @section le_temp_binding IPC interfaces binding
   26  *
   27  * All the functions of this API are provided by the @b modemService application service.
   28  *
   29  * Here's a code sample binding to modem services:
   30  * @verbatim
   31    bindings:
   32    {
   33       clientExe.clientComponent.le_temp -> modemServices.le_temp
   34    }
   35    @endverbatim
   36  *
   37  *
   38  * @section le_temp_monitoring Monitoring
   39  *
   40  * This functionality allows to monitor the temperature by getting the temperature sensor and
   41  * by setting several temperature thresholds.
   42  *
   43  * @warning Ensure to check the names of supported sensors and thresholds for your specific
   44  * platform. Please refer to @subpage platformConstraintsTemperature platform constraints page.
   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 //--------------------------------------------------------------------------------------------------
  115 void le_temp_ConnectService
  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 //--------------------------------------------------------------------------------------------------
  140 le_result_t le_temp_TryConnectService
  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 //--------------------------------------------------------------------------------------------------
  153 void le_temp_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  171 void le_temp_DisconnectService
  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 //--------------------------------------------------------------------------------------------------
  228 typedef void (*le_temp_ThresholdEventHandlerFunc_t)
  229 (
  230     le_temp_SensorRef_t sensor,
  231         ///< Temperature sensor reference.
  232     const char* 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 //--------------------------------------------------------------------------------------------------
  247 le_temp_SensorRef_t le_temp_Request
  248 (
  249     const char* sensorName
  250         ///< [IN] Name of the temperature sensor.
  251 )
  252 __attribute__(( nonnull(1) ));
  253 
  254 //--------------------------------------------------------------------------------------------------
  255 /**
  256  * Retrieve the temperature sensor's name from its reference.
  257  *
  258  * @return
  259  *      - LE_OK            The function succeeded.
  260  *      - LE_OVERFLOW      The name length exceed the maximum length.
  261  *      - LE_FAULT         The function failed.
  262  */
  263 //--------------------------------------------------------------------------------------------------
  264 le_result_t le_temp_GetSensorName
  265 (
  266     le_temp_SensorRef_t sensor,
  267         ///< [IN] Temperature sensor reference.
  268     char* sensorName,
  269         ///< [OUT] Name of the temperature sensor.
  270     size_t sensorNameSize
  271         ///< [IN]
  272 );
  273 
  274 //--------------------------------------------------------------------------------------------------
  275 /**
  276  * Add handler function for EVENT 'le_temp_ThresholdEvent'
  277  *
  278  * This event provides information on the threshold reached.
  279  *
  280  */
  281 //--------------------------------------------------------------------------------------------------
  282 le_temp_ThresholdEventHandlerRef_t le_temp_AddThresholdEventHandler
  283 (
  284     le_temp_ThresholdEventHandlerFunc_t ThresholdEventHandlerPtr,
  285         ///< [IN]
  286     void* contextPtr
  287         ///< [IN]
  288 );
  289 
  290 //--------------------------------------------------------------------------------------------------
  291 /**
  292  * Remove handler function for EVENT 'le_temp_ThresholdEvent'
  293  */
  294 //--------------------------------------------------------------------------------------------------
  295 void le_temp_RemoveThresholdEventHandler
  296 (
  297     le_temp_ThresholdEventHandlerRef_t handlerRef
  298         ///< [IN]
  299 );
  300 
  301 //--------------------------------------------------------------------------------------------------
  302 /**
  303  * Get the temperature in degree Celsius.
  304  *
  305  * @return
  306  *      - LE_OK            The function succeeded.
  307  *      - LE_FAULT         The function failed to get the temperature.
  308  */
  309 //--------------------------------------------------------------------------------------------------
  310 le_result_t le_temp_GetTemperature
  311 (
  312     le_temp_SensorRef_t sensor,
  313         ///< [IN] Temperature sensor reference.
  314     int32_t* temperaturePtr
  315         ///< [OUT] Temperature in degree Celsius.
  316 );
  317 
  318 //--------------------------------------------------------------------------------------------------
  319 /**
  320  * Set the temperature threshold in degree Celsius. This function does not start the temperature
  321  * monitoring, call le_temp_StartMonitoring() to start it.
  322  *
  323  * @return
  324  *      - LE_OK            The function succeeded.
  325  *      - LE_FAULT         The function failed.
  326  */
  327 //--------------------------------------------------------------------------------------------------
  328 le_result_t le_temp_SetThreshold
  329 (
  330     le_temp_SensorRef_t sensor,
  331         ///< [IN] Temperature sensor reference.
  332     const char* threshold,
  333         ///< [IN] Name of the threshold.
  334     int32_t temperature
  335         ///< [IN] Temperature threshold in degree Celsius.
  336 )
  337 __attribute__(( nonnull(2) ));
  338 
  339 //--------------------------------------------------------------------------------------------------
  340 /**
  341  * Get the temperature threshold in degree Celsius.
  342  *
  343  * @return
  344  *      - LE_OK            The function succeeded.
  345  *      - LE_FAULT         The function failed.
  346  */
  347 //--------------------------------------------------------------------------------------------------
  348 le_result_t le_temp_GetThreshold
  349 (
  350     le_temp_SensorRef_t sensor,
  351         ///< [IN] Temperature sensor reference.
  352     const char* threshold,
  353         ///< [IN] Name of the threshold.
  354     int32_t* temperaturePtr
  355         ///< [OUT] Temperature threshold in degree Celsius.
  356 )
  357 __attribute__(( nonnull(2) ));
  358 
  359 //--------------------------------------------------------------------------------------------------
  360 /**
  361  * Start the temperature monitoring with the temperature thresholds configured by
  362  * le_temp_SetThreshold() function.
  363  *
  364  * @return
  365  *      - LE_OK            The function succeeded.
  366  *      - LE_BAD_PARAMETER There is a mismatch with the configured threshold values.
  367  *      - LE_FAULT         The function failed to apply the thresholds.
  368  */
  369 //--------------------------------------------------------------------------------------------------
  370 le_result_t le_temp_StartMonitoring
  371 (
  372     void
  373 );
  374 
  375 #endif // LE_TEMP_INTERFACE_H_INCLUDE_GUARD
le_temp_DisconnectService
void le_temp_DisconnectService(void)


le_temp_ConnectService
void le_temp_ConnectService(void)


le_temp_RemoveThresholdEventHandler
void le_temp_RemoveThresholdEventHandler(le_temp_ThresholdEventHandlerRef_t handlerRef)


le_result_t
le_result_t
Definition: le_basics.h:35


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


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


le_temp_Request
le_temp_SensorRef_t le_temp_Request(const char *sensorName)


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


le_temp_GetTemperature
le_result_t le_temp_GetTemperature(le_temp_SensorRef_t sensor, int32_t *temperaturePtr)


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


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


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_SetServerDisconnectHandler
void le_temp_SetServerDisconnectHandler(le_temp_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_temp_AddThresholdEventHandler
le_temp_ThresholdEventHandlerRef_t le_temp_AddThresholdEventHandler(le_temp_ThresholdEventHandlerFunc_t ThresholdEventHandlerPtr, void *contextPtr)


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