From 93af6b737ec532dbf3942f839161e528c6ade568 Mon Sep 17 00:00:00 2001 From: "kibak.yoon" Date: Fri, 3 Jun 2016 13:27:45 +0900 Subject: [PATCH] capi-sensor: regrouping sensor api modules and update doxygen Change-Id: Ida1639dd8d84810f22cfc140d443ba8ca317402a Signed-off-by: kibak.yoon --- doc/sensor_doc.h | 97 ++------ include/sensor.h | 655 +++++++++++++++++++++++++++---------------------------- 2 files changed, 346 insertions(+), 406 deletions(-) diff --git a/doc/sensor_doc.h b/doc/sensor_doc.h index 81e6262..4cee887 100644 --- a/doc/sensor_doc.h +++ b/doc/sensor_doc.h @@ -21,15 +21,16 @@ /** * @ingroup CAPI_SYSTEM_FRAMEWORK * @defgroup CAPI_SYSTEM_SENSOR_MODULE Sensor - * @brief The @ref CAPI_SYSTEM_SENSOR_MODULE API provides functions to start/stop sensors and receive sensor information. + * @brief The @ref CAPI_SYSTEM_SENSOR_MODULE API provides sensor types and sensor information * * @section CAPI_SYSTEM_SENSOR_MODULE_HEADER Required Header * \#include * * @section CAPI_SYSTEM_SENSOR_MODULE_OVERVIEW Overview - * This Sensor API provides functions to make use of sensors in the - * device. A variety of hardware sensors are typically available on + * This Sensor API provides sensor types and sensor error types to make use of sensors in the + * device. A variety of hardware/virtual sensors are typically available on * mobile devices. + * This Sensor API also provides functions for sensor information, such as name, vendor. * * @section CAPI_SYSTEM_SENSOR_MODULE_FEATURE Related Features * This API is related with the following features:\n @@ -59,99 +60,39 @@ * * It is recommended to design feature related codes in your application for reliability.\n * - * You can check if a devrice supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n * * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n * * More details on featuring your application can be found from Feature Element. * -*/ + */ -/** + /** * @ingroup CAPI_SYSTEM_SENSOR_MODULE - * @defgroup CAPI_SYSTEM_SENSOR_INFORMATION_MODULE Hardware Information - * @brief The @ref CAPI_SYSTEM_SENSOR_INFORMATION_MODULE API provides information about hardware. - * @section CAPI_SYSTEM_SENSOR_INFORMATION_MODULE_HEADER Required Header - * \#include - * @section CAPI_SYSTEM_SENSOR_INFORMATION_MODULE_OVERVIEW Overview - * This API provides functions for hardware features, such as name, vendor and other information - * @section CAPI_SYSTEM_SENSOR_INFORMATION_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/sensor.accelerometer\n - * - http://tizen.org/feature/sensor.barometer\n - * - http://tizen.org/feature/sensor.gyroscope\n - * - http://tizen.org/feature/sensor.magnetometer\n - * - http://tizen.org/feature/sensor.photometer\n - * - http://tizen.org/feature/sensor.proximity\n - * - http://tizen.org/feature/sensor.tiltmeter\n - * - http://tizen.org/feature/sensor.ultraviolet\n - * - http://tizen.org/feature/sensor.temperature\n - * - http://tizen.org/feature/sensor.humidity\n - * - http://tizen.org/feature/sensor.linear_acceleration\n - * - http://tizen.org/feature/sensor.rotation_vector\n - * - http://tizen.org/feature/sensor.gravity\n - * - http://tizen.org/feature/sensor.heart_rate_monitor\n - * - http://tizen.org/feature/sensor.heart_rate_monitor.led_green\n - * - http://tizen.org/feature/sensor.heart_rate_monitor.led_ir\n - * - http://tizen.org/feature/sensor.heart_rate_monitor.led_red\n - * - http://tizen.org/feature/sensor.gyroscope.uncalibrated\n - * - http://tizen.org/feature/sensor.magnetometer.uncalibrated\n - * - http://tizen.org/feature/sensor.gyroscope_rotation_vector\n - * - http://tizen.org/feature/sensor.geomagnetic_rotation_vector\n - * - http://tizen.org/feature/sensor.pedometer\n - * - http://tizen.org/feature/sensor.sleep_monitor\n - * - * It is recommended to design feature related codes in your application for reliability.\n + * @defgroup CAPI_SYSTEM_SENSOR_LISTENER_MODULE Sensor Listener + * @brief The @ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE API provides functions to start/stop sensors and receive sensor events. * - * You can check if a devrice supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_HEADER Required Header + * \#include * - * More details on featuring your application can be found from Feature Element. + * @section CAPI_SYSTEM_SENSOR_MODULE_OVERVIEW Overview + * This Sensor API provides functions to make use of sensors in the + * device. A variety of hardware/virtual sensors are typically available on + * mobile devices. * - */ +*/ /** * @ingroup CAPI_SYSTEM_SENSOR_MODULE * @defgroup CAPI_SYSTEM_SENSOR_UTILITY_MODULE Utility * @brief The @ref CAPI_SYSTEM_SENSOR_UTILITY_MODULE API provides utility functions. + * * @section CAPI_SYSTEM_SENSOR_UTILITY_MODULE_HEADER Required Header * \#include - * @section CAPI_SYSTEM_SENSOR_UTILITY_MODULE_OVERVIEW Overview - * @section CAPI_SYSTEM_SENSOR_UTILITY_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/sensor.accelerometer\n - * - http://tizen.org/feature/sensor.barometer\n - * - http://tizen.org/feature/sensor.gyroscope\n - * - http://tizen.org/feature/sensor.magnetometer\n - * - http://tizen.org/feature/sensor.photometer\n - * - http://tizen.org/feature/sensor.proximity\n - * - http://tizen.org/feature/sensor.tiltmeter\n - * - http://tizen.org/feature/sensor.ultraviolet\n - * - http://tizen.org/feature/sensor.temperature\n - * - http://tizen.org/feature/sensor.humidity\n - * - http://tizen.org/feature/sensor.linear_acceleration\n - * - http://tizen.org/feature/sensor.rotation_vector\n - * - http://tizen.org/feature/sensor.gravity\n - * - http://tizen.org/feature/sensor.heart_rate_monitor\n - * - http://tizen.org/feature/sensor.heart_rate_monitor.led_green\n - * - http://tizen.org/feature/sensor.heart_rate_monitor.led_ir\n - * - http://tizen.org/feature/sensor.heart_rate_monitor.led_red\n - * - http://tizen.org/feature/sensor.gyroscope.uncalibrated\n - * - http://tizen.org/feature/sensor.magnetometer.uncalibrated\n - * - http://tizen.org/feature/sensor.gyroscope_rotation_vector\n - * - http://tizen.org/feature/sensor.geomagnetic_rotation_vector\n - * - http://tizen.org/feature/sensor.pedometer\n - * - http://tizen.org/feature/sensor.sleep_monitor\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a devrice supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n - * - * More details on featuring your application can be found from Feature Element. * + * @section CAPI_SYSTEM_SENSOR_UTILITY_MODULE_OVERVIEW Overview + * This Sensor API provides utility functions. * */ diff --git a/include/sensor.h b/include/sensor.h index 3f843ee..d74bc77 100644 --- a/include/sensor.h +++ b/include/sensor.h @@ -30,13 +30,6 @@ extern "C" */ /** - * @brief The upper bound of #sensor_event_s::value_count. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - */ -#define MAX_VALUE_SIZE 16 - - -/** * @brief Sensor handle. * @details The handle for controlling a specific sensor can be retrieved using sensor_get_default_sensor().@n * The function returns the handle of the default sensor of a given type, and usually, @@ -49,54 +42,6 @@ typedef void* sensor_h; /** - * @brief Sensor listener handle. - * @details For each #sensor_h, one or more sensor listeners can be created by using sensor_create_listener(). - * Then the sensor's data can observed asynchronously, can be read synchronously if available, via the listener. - * Applications are also able to control the behavior of each sensor, for example, - * update interval of sensor readings. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - */ -typedef struct sensor_listener_s *sensor_listener_h; - - -/** - * @brief Sensor data event delivered via sensor_event_cb(). - * @details A sensor data is delivered as a structure, which contains the accuracy of the data, - * the time when the data was observed, and the data array. - * The data array is a fixed size @c float array, and the number of data fields - * stored in the array varies with the sensor type. - * For example, #SENSOR_ACCELEROMETER reports 3-dimensional data, - * #sensor_event_s::value_count is thus set to 3.@n - * Note that, even if the data values are @c float, in some cases, - * it may contain one or more categorical data as in #sensor_proximity_e. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * @see #sensor_pedometer_state_e - * @see #sensor_sleep_state_e - */ -typedef struct -{ - int accuracy; /**< Accuracy of sensor data */ - unsigned long long timestamp; /**< Time when the sensor data was observed */ - int value_count; /**< Number of sensor data values stored in #sensor_event_s::values */ - float values[MAX_VALUE_SIZE]; /**< Sensor data values */ -} sensor_event_s; - - -/** - * @brief Enumeration for sensor data accuracy. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - */ -typedef enum -{ - SENSOR_DATA_ACCURACY_UNDEFINED = -1, /**< Undefined */ - SENSOR_DATA_ACCURACY_BAD = 0, /**< Not accurate */ - SENSOR_DATA_ACCURACY_NORMAL = 1, /**< Moderately accurate */ - SENSOR_DATA_ACCURACY_GOOD = 2, /**< Highly accurate */ - SENSOR_DATA_ACCURACY_VERYGOOD = 3 /**< Very highly accurate */ -} sensor_data_accuracy_e; - - -/** * @brief Enumeration for errors. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ @@ -203,72 +148,6 @@ typedef enum /** - * @brief Enumeration for sensor options. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - */ -#ifndef __SENSOR_COMMON_H__ -typedef enum -{ - SENSOR_OPTION_DEFAULT, /**< Does not receive data when the LCD is off and in the power save mode */ - SENSOR_OPTION_ON_IN_SCREEN_OFF, /**< Receives data when the LCD is off */ - SENSOR_OPTION_ON_IN_POWERSAVE_MODE, /**< Receives data in the power save mode */ - SENSOR_OPTION_ALWAYS_ON, /**< Receives data when the LCD is off and in the power save mode */ -} sensor_option_e; -#endif - - -/** - * @brief Enumeration for sensor listener behavior attributes - * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif - */ -typedef enum -{ - SENSOR_ATTRIBUTE_AXIS_ORIENTATION = 1, /**< Reference orientation of sensor data to be reported.@n - See #sensor_axis_e for available attribute values. */ - SENSOR_ATTRIBUTE_PAUSE_POLICY, /**< Pause-and-resume policy of sensors.@n - See #sensor_pause_e for available attribute values. */ -} sensor_attribute_e; - - -/** - * @brief Enumeration for reference orientations of sensor data - * @details The sensor's physical orientation may differ from what applications are aware of, - * in cases that the device has a rotated screen, physically or logically. - * For example, a watch device may have right hand mode, which logically rotates - * the display 180 degrees. - * Applications may not be aware of such situations, thus they may receives - * sensor data inverted in X and Y directions. - * With #SENSOR_AXIS_DISPLAY_ORIENTED option, applications can get data that - * are properly aligned with the orientation of which they are aware.@n - * By default, #SENSOR_AXIS_DISPLAY_ORIENTED is used. - * If you need to use the data that are not affected by display orientations, - * #SENSOR_AXIS_DEVICE_ORIENTED needs to be set. - * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif - */ -typedef enum -{ - SENSOR_AXIS_DEVICE_ORIENTED = 1, /**< Using the device orientation as the reference coordinate system */ - SENSOR_AXIS_DISPLAY_ORIENTED, /**< Using the display orientation as the reference coordinate system */ -} sensor_axis_e; - - -/** - * @brief Enumeration for pause policies of sensor listeners - * @details To be power-efficient, you can set the policy of how to pause and resume - * a sensor listener regarding the system status. - * By default, #SENSOR_PAUSE_ALL is used to obtain the maximum power efficiency. - * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif - */ -typedef enum -{ - SENSOR_PAUSE_NONE = 0, /**< The sensor will not pause, unless the system goes into sleep mode */ - SENSOR_PAUSE_ON_DISPLAY_OFF = 1, /**< The sensor pauses while the display is off*/ - SENSOR_PAUSE_ON_POWERSAVE_MODE = 2, /**< The sensor pauses while the power-save mode is enabled */ - SENSOR_PAUSE_ALL = 3, /**< The sensor pauses in all the above cases */ -} sensor_pause_e; - - -/** * @brief Checks whether a given sensor type is supported in the current device. * @details If the given sensor type is not supported, sensor_get_default_sensor() will return an error. * It is thus recommended to check the availability of the sensor before actually acquiring #sensor_h. @@ -285,6 +164,25 @@ int sensor_is_supported(sensor_type_e type, bool *supported); /** + * @brief Checks whether a given sensor is a wake-up sensor or not. + * @details If a sensor is a wake-up sensor, the sensor is able to wake-up the system + * to report its sensor data even if the system is in sleep mode. + * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif + * + * @param[in] sensor A sensor handle to check + * @param[out] wakeup If the sensor is a wake-up sensor, @c true; + * Otherwise @c false + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + * + * @pre The handle @c sensor needs to be initialized using + * sensor_get_default_sensor() or sensor_get_sensor_list() in advance. + */ +int sensor_is_wake_up(sensor_h sensor, bool *wakeup); + +/** * @brief Gets the handle for the default sensor of a given type. * @details This function returns the handle for the sensor of a given type, * if the device has one sensor of the given type. @@ -338,27 +236,304 @@ int sensor_get_default_sensor(sensor_type_e type, sensor_h *sensor); * @retval #SENSOR_ERROR_PERMISSION_DENIED Permission denied * @retval #SENSOR_ERROR_OUT_OF_MEMORY Out of memory */ -int sensor_get_sensor_list(sensor_type_e type, sensor_h **list, int *sensor_count); +int sensor_get_sensor_list(sensor_type_e type, sensor_h **list, int *sensor_count); + + +/** + * @brief Gets the name of a sensor. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[out] name The name of the sensor + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + */ +int sensor_get_name(sensor_h sensor, char **name); + + +/** + * @brief Gets the vendor of a sensor. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[out] vendor The vendor of the sensor + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + */ +int sensor_get_vendor(sensor_h sensor, char **vendor); + + +/** + * @brief Gets the sensor type of a sensor. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[out] type The type of the sensor + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + */ +int sensor_get_type(sensor_h sensor, sensor_type_e *type); + + +/** + * @brief Gets the lower bound of the sensor reading of a sensor. + * @details This function returns the lower bound of the range of possible sensor values, + * which are generated by the corresponding sensor denoted by a sensor handle.@n + * If all sensor values are in the same unit, e.g., \f$\mbox{m/s}^2\f$ or degrees, + * the lower bound of all sensor values is returned. + * Otherwise, the lower bound of the representative sensor value, e.g., + * the step count of #SENSOR_HUMAN_PEDOMETER, is returned. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[out] min_range The lower bound + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + * + * @see sensor_get_max_range() + */ +int sensor_get_min_range(sensor_h sensor, float *min_range); + + +/** + * @brief Gets the upper bound of the sensor readings of a sensor. + * @details This function returns the upper bound of the range of possible sensor values, + * which are generated by the corresponding sensor denoted by a sensor handle.@n + * If all sensor values are in the same unit, e.g., \f$\mbox{m/s}^2\f$ or degrees, + * the upper bound of all sensor values is returned. + * Otherwise, the upper bound of the representative sensor value, e.g., + * the step count of #SENSOR_HUMAN_PEDOMETER, is returned. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[out] max_range The upper bound + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + * + * @see sensor_get_min_range() + */ +int sensor_get_max_range(sensor_h sensor, float *max_range); + + +/** + * @brief Gets the resolution of the sensor readings of a sensor. + * @details This function returns the resolution of the sensor readings. + * The resolution denotes the smallest difference between sensor readings, + * each of which is in the range that can be verified by + * sensor_get_min_range() and sensor_get_max_range(). + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[out] resolution The resolution + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + */ +int sensor_get_resolution(sensor_h sensor, float *resolution); + + +/** + * @brief Gets the possible shorted update interval of a sensor. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[out] min_interval The shorted interval in milliseconds + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + */ +int sensor_get_min_interval(sensor_h sensor, int *min_interval); + + +/** + * @brief Gets the size of the hardware FIFO of a sensor. + * @details This function returns the size of the hardware FIFO that may be used by + * a specific sensor to support batching. + * However, regarding the underlying hardware configuration, + * the returned count may not mean the maximum number of sensor data that can be batched. + * See sensor_get_max_batch_count() for such purpose, finding out the + * possible maximum number of batched data. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[out] fifo_count The FIFO count + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + */ +int sensor_get_fifo_count(sensor_h sensor, int *fifo_count); + + +/** + * @brief Gets the maximum batch count of a sensor. + * @details This function returns the maximum number of sensor data events + * that can be possibly delivered when the batched data are flushed. + * Therefore, this count can be used to check whether the sensor supports + * batching or not.@n + * If this returns a positive count, i.e., the sensor supports batching, + * the count also can be used to guess the possible longest batch latency + * of the sensor, with respect to the update interval to use. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[out] max_batch_count If the sensor does not support batching, 0; + * Otherwise a positive integer. + * + * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value + * @retval #SENSOR_ERROR_NONE Successful + * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + * + * @see sensor_listener_set_max_batch_latency() + */ +int sensor_get_max_batch_count(sensor_h sensor, int *max_batch_count); + +/** + * @} + */ + +/** + * @addtogroup CAPI_SYSTEM_SENSOR_LISTENER_MODULE + * @{ + */ + +/** + * @brief The upper bound of #sensor_event_s::value_count. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#define MAX_VALUE_SIZE 16 + +/** + * @brief Sensor listener handle. + * @details For each #sensor_h, one or more sensor listeners can be created by using sensor_create_listener(). + * Then the sensor's data can observed asynchronously, can be read synchronously if available, via the listener. + * Applications are also able to control the behavior of each sensor, for example, + * update interval of sensor readings. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef struct sensor_listener_s *sensor_listener_h; + + +/** + * @brief Sensor data event delivered via sensor_event_cb(). + * @details A sensor data is delivered as a structure, which contains the accuracy of the data, + * the time when the data was observed, and the data array. + * The data array is a fixed size @c float array, and the number of data fields + * stored in the array varies with the sensor type. + * For example, #SENSOR_ACCELEROMETER reports 3-dimensional data, + * #sensor_event_s::value_count is thus set to 3.@n + * Note that, even if the data values are @c float, in some cases, + * it may contain one or more categorical data as in #sensor_proximity_e. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * @see #sensor_pedometer_state_e + * @see #sensor_sleep_state_e + */ +typedef struct +{ + int accuracy; /**< Accuracy of sensor data */ + unsigned long long timestamp; /**< Time when the sensor data was observed */ + int value_count; /**< Number of sensor data values stored in #sensor_event_s::values */ + float values[MAX_VALUE_SIZE]; /**< Sensor data values */ +} sensor_event_s; + + +/** + * @brief Enumeration for sensor data accuracy. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +typedef enum +{ + SENSOR_DATA_ACCURACY_UNDEFINED = -1, /**< Undefined */ + SENSOR_DATA_ACCURACY_BAD = 0, /**< Not accurate */ + SENSOR_DATA_ACCURACY_NORMAL = 1, /**< Moderately accurate */ + SENSOR_DATA_ACCURACY_GOOD = 2, /**< Highly accurate */ + SENSOR_DATA_ACCURACY_VERYGOOD = 3 /**< Very highly accurate */ +} sensor_data_accuracy_e; + + +/** + * @brief Enumeration for sensor listener behavior attributes + * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif + */ +typedef enum +{ + SENSOR_ATTRIBUTE_AXIS_ORIENTATION = 1, /**< Reference orientation of sensor data to be reported.@n + See #sensor_axis_e for available attribute values. */ + SENSOR_ATTRIBUTE_PAUSE_POLICY, /**< Pause-and-resume policy of sensors.@n + See #sensor_pause_e for available attribute values. */ +} sensor_attribute_e; + + +/** + * @brief Enumeration for sensor options. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + */ +#ifndef __SENSOR_COMMON_H__ +typedef enum +{ + SENSOR_OPTION_DEFAULT, /**< Does not receive data when the LCD is off and in the power save mode */ + SENSOR_OPTION_ON_IN_SCREEN_OFF, /**< Receives data when the LCD is off */ + SENSOR_OPTION_ON_IN_POWERSAVE_MODE, /**< Receives data in the power save mode */ + SENSOR_OPTION_ALWAYS_ON, /**< Receives data when the LCD is off and in the power save mode */ +} sensor_option_e; +#endif + + +/** + * @brief Enumeration for reference orientations of sensor data + * @details The sensor's physical orientation may differ from what applications are aware of, + * in cases that the device has a rotated screen, physically or logically. + * For example, a watch device may have right hand mode, which logically rotates + * the display 180 degrees. + * Applications may not be aware of such situations, thus they may receives + * sensor data inverted in X and Y directions. + * With #SENSOR_AXIS_DISPLAY_ORIENTED option, applications can get data that + * are properly aligned with the orientation of which they are aware.@n + * By default, #SENSOR_AXIS_DISPLAY_ORIENTED is used. + * If you need to use the data that are not affected by display orientations, + * #SENSOR_AXIS_DEVICE_ORIENTED needs to be set. + * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif + */ +typedef enum +{ + SENSOR_AXIS_DEVICE_ORIENTED = 1, /**< Using the device orientation as the reference coordinate system */ + SENSOR_AXIS_DISPLAY_ORIENTED, /**< Using the display orientation as the reference coordinate system */ +} sensor_axis_e; /** - * @brief Checks whether a given sensor is a wake-up sensor or not. - * @details If a sensor is a wake-up sensor, the sensor is able to wake-up the system - * to report its sensor data even if the system is in sleep mode. + * @brief Enumeration for pause policies of sensor listeners + * @details To be power-efficient, you can set the policy of how to pause and resume + * a sensor listener regarding the system status. + * By default, #SENSOR_PAUSE_ALL is used to obtain the maximum power efficiency. * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif - * - * @param[in] sensor A sensor handle to check - * @param[out] wakeup If the sensor is a wake-up sensor, @c true; - * Otherwise @c false - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - * - * @pre The handle @c sensor needs to be initialized using - * sensor_get_default_sensor() or sensor_get_sensor_list() in advance. */ -int sensor_is_wake_up(sensor_h sensor, bool *wakeup); +typedef enum +{ + SENSOR_PAUSE_NONE = 0, /**< The sensor will not pause, unless the system goes into sleep mode */ + SENSOR_PAUSE_ON_DISPLAY_OFF = 1, /**< The sensor pauses while the display is off*/ + SENSOR_PAUSE_ON_POWERSAVE_MODE = 2, /**< The sensor pauses while the power-save mode is enabled */ + SENSOR_PAUSE_ALL = 3, /**< The sensor pauses in all the above cases */ +} sensor_pause_e; /** @@ -375,6 +550,21 @@ typedef void (*sensor_event_cb)(sensor_h sensor, sensor_event_s *event, void *da /** + * @brief Called when the accuracy of a sensor changes. + * @details Sensors can be affected by the environment. + * For example, #SENSOR_MAGNETIC is sensitive to any surrounding objects that can influence + * electromagnetic fields. This function is called if the accuracy of the corresponding sensor is changed. + * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif + * + * @param[in] sensor A sensor handle + * @param[in] timestamp The time in milliseconds when the accuracy changed + * @param[in] accuracy The current accuracy of the sensor + * @param[in] data The user data had passed to sensor_listener_set_accuracy_cb() + */ +typedef void (*sensor_accuracy_changed_cb)(sensor_h sensor, unsigned long long timestamp, sensor_data_accuracy_e accuracy, void *data); + + +/** * @brief Creates a sensor listener. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * @@ -496,21 +686,6 @@ int sensor_listener_unset_event_cb(sensor_listener_h listener); /** - * @brief Called when the accuracy of a sensor changes. - * @details Sensors can be affected by the environment. - * For example, #SENSOR_MAGNETIC is sensitive to any surrounding objects that can influence - * electromagnetic fields. This function is called if the accuracy of the corresponding sensor is changed. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[in] timestamp The time in milliseconds when the accuracy changed - * @param[in] accuracy The current accuracy of the sensor - * @param[in] data The user data had passed to sensor_listener_set_accuracy_cb() - */ -typedef void (*sensor_accuracy_changed_cb)(sensor_h sensor, unsigned long long timestamp, sensor_data_accuracy_e accuracy, void *data); - - -/** * @brief Registers the callback function to be invoked when the accuracy of a sensor changes. * @details In addition to sensor_event_cb(), sensor_accuracy_changed_cb() also can be attached * to sensor listeners. With this accuracy callback function, applications can be notified @@ -669,182 +844,6 @@ int sensor_listener_set_option(sensor_listener_h listener, sensor_option_e optio */ /** - * @addtogroup CAPI_SYSTEM_SENSOR_INFORMATION_MODULE - * @{ - */ - -/** - * @brief Gets the name of a sensor. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[out] name The name of the sensor - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - */ -int sensor_get_name(sensor_h sensor, char **name); - - -/** - * @brief Gets the vendor of a sensor. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[out] vendor The vendor of the sensor - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - */ -int sensor_get_vendor(sensor_h sensor, char **vendor); - - -/** - * @brief Gets the sensor type of a sensor. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[out] type The type of the sensor - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed - */ -int sensor_get_type(sensor_h sensor, sensor_type_e *type); - - -/** - * @brief Gets the lower bound of the sensor reading of a sensor. - * @details This function returns the lower bound of the range of possible sensor values, - * which are generated by the corresponding sensor denoted by a sensor handle.@n - * If all sensor values are in the same unit, e.g., \f$\mbox{m/s}^2\f$ or degrees, - * the lower bound of all sensor values is returned. - * Otherwise, the lower bound of the representative sensor value, e.g., - * the step count of #SENSOR_HUMAN_PEDOMETER, is returned. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[out] min_range The lower bound - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed - * - * @see sensor_get_max_range() - */ -int sensor_get_min_range(sensor_h sensor, float *min_range); - - -/** - * @brief Gets the upper bound of the sensor readings of a sensor. - * @details This function returns the upper bound of the range of possible sensor values, - * which are generated by the corresponding sensor denoted by a sensor handle.@n - * If all sensor values are in the same unit, e.g., \f$\mbox{m/s}^2\f$ or degrees, - * the upper bound of all sensor values is returned. - * Otherwise, the upper bound of the representative sensor value, e.g., - * the step count of #SENSOR_HUMAN_PEDOMETER, is returned. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[out] max_range The upper bound - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed - * - * @see sensor_get_min_range() - */ -int sensor_get_max_range(sensor_h sensor, float *max_range); - - -/** - * @brief Gets the resolution of the sensor readings of a sensor. - * @details This function returns the resolution of the sensor readings. - * The resolution denotes the smallest difference between sensor readings, - * each of which is in the range that can be verified by - * sensor_get_min_range() and sensor_get_max_range(). - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[out] resolution The resolution - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed - */ -int sensor_get_resolution(sensor_h sensor, float *resolution); - - -/** - * @brief Gets the possible shorted update interval of a sensor. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[out] min_interval The shorted interval in milliseconds - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed - */ -int sensor_get_min_interval(sensor_h sensor, int *min_interval); - - -/** - * @brief Gets the size of the hardware FIFO of a sensor. - * @details This function returns the size of the hardware FIFO that may be used by - * a specific sensor to support batching. - * However, regarding the underlying hardware configuration, - * the returned count may not mean the maximum number of sensor data that can be batched. - * See sensor_get_max_batch_count() for such purpose, finding out the - * possible maximum number of batched data. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[out] fifo_count The FIFO count - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed - */ -int sensor_get_fifo_count(sensor_h sensor, int *fifo_count); - - -/** - * @brief Gets the maximum batch count of a sensor. - * @details This function returns the maximum number of sensor data events - * that can be possibly delivered when the batched data are flushed. - * Therefore, this count can be used to check whether the sensor supports - * batching or not.@n - * If this returns a positive count, i.e., the sensor supports batching, - * the count also can be used to guess the possible longest batch latency - * of the sensor, with respect to the update interval to use. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] sensor A sensor handle - * @param[out] max_batch_count If the sensor does not support batching, 0; - * Otherwise a positive integer. - * - * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value - * @retval #SENSOR_ERROR_NONE Successful - * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed - * - * @see sensor_listener_set_max_batch_latency() - */ -int sensor_get_max_batch_count(sensor_h sensor, int *max_batch_count); -/** - * @} - */ - -/** * @addtogroup CAPI_SYSTEM_SENSOR_UTILITY_MODULE * @{ */ -- 2.7.4