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 
   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* LE_NONNULL 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* LE_NONNULL sensorName
  250         ///< [IN] Name of the temperature sensor.
  251 );
  252 
  253 //--------------------------------------------------------------------------------------------------
  254 /**
  255  * Retrieve the temperature sensor's name from its reference.
  256  *
  257  * @return
  258  *      - LE_OK            The function succeeded.
  259  *      - LE_OVERFLOW      The name length exceed the maximum length.
  260  *      - LE_FAULT         The function failed.
  261  */
  262 //--------------------------------------------------------------------------------------------------
  263 le_result_t le_temp_GetSensorName
  264 (
  265     le_temp_SensorRef_t sensor,
  266         ///< [IN] Temperature sensor reference.
  267     char* sensorName,
  268         ///< [OUT] Name of the temperature sensor.
  269     size_t sensorNameSize
  270         ///< [IN]
  271 );
  272 
  273 //--------------------------------------------------------------------------------------------------
  274 /**
  275  * Add handler function for EVENT 'le_temp_ThresholdEvent'
  276  *
  277  * This event provides information on the threshold reached.
  278  *
  279  */
  280 //--------------------------------------------------------------------------------------------------
  281 le_temp_ThresholdEventHandlerRef_t le_temp_AddThresholdEventHandler
  282 (
  283     le_temp_ThresholdEventHandlerFunc_t ThresholdEventHandlerPtr,
  284         ///< [IN]
  285     void* contextPtr
  286         ///< [IN]
  287 );
  288 
  289 //--------------------------------------------------------------------------------------------------
  290 /**
  291  * Remove handler function for EVENT 'le_temp_ThresholdEvent'
  292  */
  293 //--------------------------------------------------------------------------------------------------
  294 void le_temp_RemoveThresholdEventHandler
  295 (
  296     le_temp_ThresholdEventHandlerRef_t handlerRef
  297         ///< [IN]
  298 );
  299 
  300 //--------------------------------------------------------------------------------------------------
  301 /**
  302  * Get the temperature in degree Celsius.
  303  *
  304  * @return
  305  *      - LE_OK            The function succeeded.
  306  *      - LE_FAULT         The function failed to get the temperature.
  307  */
  308 //--------------------------------------------------------------------------------------------------
  309 le_result_t le_temp_GetTemperature
  310 (
  311     le_temp_SensorRef_t sensor,
  312         ///< [IN] Temperature sensor reference.
  313     int32_t* temperaturePtr
  314         ///< [OUT] Temperature in degree Celsius.
  315 );
  316 
  317 //--------------------------------------------------------------------------------------------------
  318 /**
  319  * Set the temperature threshold in degree Celsius. This function does not start the temperature
  320  * monitoring, call le_temp_StartMonitoring() to start it.
  321  *
  322  * @return
  323  *      - LE_OK            The function succeeded.
  324  *      - LE_FAULT         The function failed.
  325  */
  326 //--------------------------------------------------------------------------------------------------
  327 le_result_t le_temp_SetThreshold
  328 (
  329     le_temp_SensorRef_t sensor,
  330         ///< [IN] Temperature sensor reference.
  331     const char* LE_NONNULL threshold,
  332         ///< [IN] Name of the threshold.
  333     int32_t temperature
  334         ///< [IN] Temperature threshold in degree Celsius.
  335 );
  336 
  337 //--------------------------------------------------------------------------------------------------
  338 /**
  339  * Get the temperature threshold in degree Celsius.
  340  *
  341  * @return
  342  *      - LE_OK            The function succeeded.
  343  *      - LE_FAULT         The function failed.
  344  */
  345 //--------------------------------------------------------------------------------------------------
  346 le_result_t le_temp_GetThreshold
  347 (
  348     le_temp_SensorRef_t sensor,
  349         ///< [IN] Temperature sensor reference.
  350     const char* LE_NONNULL threshold,
  351         ///< [IN] Name of the threshold.
  352     int32_t* temperaturePtr
  353         ///< [OUT] Temperature threshold in degree Celsius.
  354 );
  355 
  356 //--------------------------------------------------------------------------------------------------
  357 /**
  358  * Start the temperature monitoring with the temperature thresholds configured by
  359  * le_temp_SetThreshold() function.
  360  *
  361  * @return
  362  *      - LE_OK            The function succeeded.
  363  *      - LE_BAD_PARAMETER There is a mismatch with the configured threshold values.
  364  *      - LE_FAULT         The function failed to apply the thresholds.
  365  */
  366 //--------------------------------------------------------------------------------------------------
  367 le_result_t le_temp_StartMonitoring
  368 (
  369     void
  370 );
  371 
  372 #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_ThresholdEventHandlerFunc_t
void(* le_temp_ThresholdEventHandlerFunc_t)(le_temp_SensorRef_t sensor, const char *LE_NONNULL threshold, void *contextPtr)
Definition: le_temp_interface.h:229


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


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


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_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_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)


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