/**
* @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 <sensor.h>
*
* @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
*
* 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 <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
*
-*/
+ */
-/**
+ /**
* @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 <sensor.h>
- * @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 <sensor.h>
*
- * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
+ * @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 <sensor.h>
- * @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 <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
*
+ * @section CAPI_SYSTEM_SENSOR_UTILITY_MODULE_OVERVIEW Overview
+ * This Sensor API provides utility functions.
*
*/
*/
/**
- * @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,
/**
- * @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
*/
/**
- * @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.
/**
+ * @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.
* @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;
/**
/**
+ * @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
*
/**
- * @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
*/
/**
- * @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
* @{
*/
projects / platform / core / api / sensor.git / commitdiff