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


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_GetSensorName
le_result_t le_temp_GetSensorName(le_temp_SensorRef_t sensor, char *sensorName, size_t sensorNameSize)


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


le_temp_GetTemperature
le_result_t le_temp_GetTemperature(le_temp_SensorRef_t sensor, int32_t *temperaturePtr)


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40


le_temp_TryConnectService
le_result_t le_temp_TryConnectService(void)


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_SetThreshold
le_result_t le_temp_SetThreshold(le_temp_SensorRef_t sensor, const char *LE_NONNULL threshold, int32_t temperature)


le_temp_StartMonitoring
le_result_t le_temp_StartMonitoring(void)