include/sensor.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __SENSOR_H__
  18 #define __SENSOR_H__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27 /**
  28  * @addtogroup CAPI_SYSTEM_SENSOR_MODULE
  29  * @{
  30  */
  31
  32 /**
  33  * @brief   The upper bound of #sensor_event_s::value_count.
  34  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  35  */
  36 #define MAX_VALUE_SIZE 16
  37
  38
  39 /**
  40  * @brief   Sensor handle.
  41  * @details The handle for controlling a specific sensor can be retrieved using sensor_get_default_sensor().@n
  42  *          The function returns the handle of the default sensor of a given type, and usually,
  43  *          a device has one sensor for one type.
  44  *          However, if the device supports multiple sensors of the same type,
  45  *          sensor_get_sensor_list() function can be used to get the list of all the sensors of the type.
  46  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  47  */
  48 typedef void* sensor_h;
  49
  50
  51 /**
  52  * @brief   Sensor listener handle.
  53  * @details For each #sensor_h, one or more sensor listeners can be created by using sensor_create_listener().
  54  *          Then the sensor's data can observed asynchronously, can be read synchronously if available, via the listener.
  55  *          Applications are also able to control the behavior of each sensor, for example,
  56  *          update interval of sensor readings.
  57  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  58  */
  59 typedef struct sensor_listener_s *sensor_listener_h;
  60
  61
  62 /**
  63  * @brief   Sensor data event delivered via sensor_event_cb().
  64  * @details A sensor data is delivered as a structure, which contains the accuracy of the data,
  65  *          the time when the data was observed, and the data array.
  66  *          The data array is a fixed size @c float array, and the number of data fields
  67  *          stored in the array varies with the sensor type.
  68  *          For example, #SENSOR_ACCELEROMETER reports 3-dimensional data,
  69  *          #sensor_event_s::value_count is thus set to 3.@n
  70  *          Note that, even if the data values are @c float, in some cases,
  71  *          it may contain one or more categorical data as in #sensor_proximity_e.
  72  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  73  * @see     #sensor_pedometer_state_e
  74  * @see     #sensor_sleep_state_e
  75  */
  76 typedef struct
  77 {
  78         int accuracy;                  /**< Accuracy of sensor data */
  79         unsigned long long timestamp;  /**< Time when the sensor data was observed */
  80         int value_count;               /**< Number of sensor data values stored in #sensor_event_s::values */
  81         float values[MAX_VALUE_SIZE];  /**< Sensor data values */
  82 } sensor_event_s;
  83
  84
  85 /**
  86  * @brief   Enumeration for sensor data accuracy.
  87  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  88  */
  89 typedef enum
  90 {
  91         SENSOR_DATA_ACCURACY_UNDEFINED   = -1,  /**< Undefined */
  92         SENSOR_DATA_ACCURACY_BAD         = 0,   /**< Not accurate */
  93         SENSOR_DATA_ACCURACY_NORMAL      = 1,   /**< Moderately accurate */
  94         SENSOR_DATA_ACCURACY_GOOD        = 2,   /**< Highly accurate */
  95         SENSOR_DATA_ACCURACY_VERYGOOD    = 3    /**< Very highly accurate */
  96 } sensor_data_accuracy_e;
  97
  98
  99 /**
 100  * @brief   Enumeration for errors.
 101  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 102  */
 103 typedef enum
 104 {
 105         SENSOR_ERROR_NONE                  = TIZEN_ERROR_NONE,                 /**< Successful */
 106         SENSOR_ERROR_IO_ERROR              = TIZEN_ERROR_IO_ERROR,             /**< I/O error */
 107         SENSOR_ERROR_INVALID_PARAMETER     = TIZEN_ERROR_INVALID_PARAMETER,    /**< Invalid parameter */
 108         SENSOR_ERROR_NOT_SUPPORTED         = TIZEN_ERROR_NOT_SUPPORTED,        /**< Not supported */
 109         SENSOR_ERROR_PERMISSION_DENIED     = TIZEN_ERROR_PERMISSION_DENIED,    /**< Permission denied */
 110         SENSOR_ERROR_OUT_OF_MEMORY         = TIZEN_ERROR_OUT_OF_MEMORY,        /**< Out of memory */
 111         SENSOR_ERROR_NOT_NEED_CALIBRATION  = TIZEN_ERROR_SENSOR | 0x03,        /**< Sensor doesn't need calibration */
 112         SENSOR_ERROR_OPERATION_FAILED      = TIZEN_ERROR_SENSOR | 0x06,        /**< Operation failed */
 113 } sensor_error_e;
 114
 115
 116 /**
 117  * @brief   Enumeration for proximity sensor events.
 118  * @details In its #sensor_event_s, #SENSOR_PROXIMITY reports the existence of
 119  *          nearby objects in front of the sensor as one of the followings.
 120  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 121  */
 122 typedef enum
 123 {
 124         SENSOR_PROXIMITY_NEAR = 0,    /**< An object is placed near the proximity sensor */
 125         SENSOR_PROXIMITY_FAR = 5,     /**< No object is placed near the proximity sensor */
 126 } sensor_proximity_e;
 127
 128
 129 /**
 130  * @brief   Enumeration for pedestrian state.
 131  * @details In its #sensor_event_s, #SENSOR_HUMAN_PEDOMETER reports the user's
 132  *          pedestrian state as one of the followings.
 133  * @since_tizen 3.0
 134  */
 135 typedef enum
 136 {
 137         SENSOR_PEDOMETER_STATE_UNKNOWN = 0, /**< Uncertain */
 138         SENSOR_PEDOMETER_STATE_STOP,        /**< The user is not moving */
 139         SENSOR_PEDOMETER_STATE_WALK,        /**< The user is walking */
 140         SENSOR_PEDOMETER_STATE_RUN,         /**< The user is running */
 141 } sensor_pedometer_state_e;
 142
 143
 144 /**
 145  * @brief   Enumeration for sleep state.
 146  * @details In its #sensor_event_s, #SENSOR_HUMAN_SLEEP_MONITOR reports the user's
 147  *          sleep state as one of the followings.
 148  * @since_tizen 3.0
 149  */
 150 typedef enum
 151 {
 152         SENSOR_SLEEP_STATE_UNKNOWN = 0, /**< Uncertain */
 153         SENSOR_SLEEP_STATE_SLEEP,       /**< The user is asleep */
 154         SENSOR_SLEEP_STATE_AWAKE,       /**< The user is awake */
 155 } sensor_sleep_state_e;
 156
 157
 158 /**
 159  * @brief   Enumeration for sensor types.
 160  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 161  */
 162 typedef enum
 163 {
 164         SENSOR_ALL = -1,                        /**< All sensors. This can be used to retrieve #sensor_h for all available sensors. */
 165         SENSOR_ACCELEROMETER,                   /**< Accelerometer */
 166         SENSOR_GRAVITY,                         /**< Gravity sensor */
 167         SENSOR_LINEAR_ACCELERATION,             /**< Linear acceleration sensor */
 168         SENSOR_MAGNETIC,                        /**< Magnetic sensor */
 169         SENSOR_ROTATION_VECTOR,                 /**< Rotation vector sensor */
 170         SENSOR_ORIENTATION,                     /**< Orientation sensor */
 171         SENSOR_GYROSCOPE,                       /**< Gyroscope */
 172         SENSOR_LIGHT,                           /**< Light sensor */
 173         SENSOR_PROXIMITY,                       /**< Proximity sensor */
 174         SENSOR_PRESSURE,                        /**< Pressure sensor */
 175         SENSOR_ULTRAVIOLET,                     /**< Ultraviolet sensor */
 176         SENSOR_TEMPERATURE,                     /**< Temperature sensor */
 177         SENSOR_HUMIDITY,                        /**< Humidity sensor */
 178         SENSOR_HRM,                             /**< Heart-rate monitor
 179                                                      @if MOBILE (Since 2.4) @endif @n
 180                                                      Privilege : http://tizen.org/privilege/healthinfo */
 181         SENSOR_HRM_LED_GREEN,                   /**< Green LED sensor of HRM
 182                                                      @if MOBILE (Since 2.4) @endif @n
 183                                                      Privilege : http://tizen.org/privilege/healthinfo */
 184         SENSOR_HRM_LED_IR,                      /**< Infra-Red LED sensor of HRM
 185                                                      @if MOBILE (Since 2.4) @endif @n
 186                                                      Privilege : http://tizen.org/privilege/healthinfo */
 187         SENSOR_HRM_LED_RED,                     /**< Red LED sensor of HRM
 188                                                      @if MOBILE (Since 2.4) @endif @n
 189                                                      Privilege : http://tizen.org/privilege/healthinfo */
 190         SENSOR_GYROSCOPE_UNCALIBRATED,          /**< Uncalibrated Gyroscope sensor
 191                                                      @if MOBILE (Since 2.4) @elseif WEARABLE (Since 3.0) @endif */
 192         SENSOR_GEOMAGNETIC_UNCALIBRATED,        /**< Uncalibrated Geomagnetic sensor
 193                                                      @if MOBILE (Since 2.4) @elseif WEARABLE (Since 3.0) @endif */
 194         SENSOR_GYROSCOPE_ROTATION_VECTOR,       /**< Gyroscope-based rotation vector sensor
 195                                                      @if MOBILE (Since 2.4) @elseif WEARABLE (Since 3.0) @endif */
 196         SENSOR_GEOMAGNETIC_ROTATION_VECTOR,     /**< Geomagnetic-based rotation vector sensor
 197                                                      @if MOBILE (Since 2.4) @elseif WEARABLE (Since 3.0) @endif */
 198         SENSOR_ACTIVITY_STATIONARY = 0x100,     /**< Activity sensor detecting that the device is not moving (Since 3.0) */
 199         SENSOR_ACTIVITY_WALK,                   /**< Activity sensor detecting that the device is on a user who is walking (Since 3.0) */
 200         SENSOR_ACTIVITY_RUN,                    /**< Activity sensor detecting that the device is on a user who is running (Since 3.0) */
 201         SENSOR_ACTIVITY_IN_VEHICLE,             /**< Activity sensor detecting that the device is in a moving vehicle, like a car (Since 3.0) */
 202         SENSOR_ACTIVITY_ON_BICYCLE,             /**< Activity sensor detecting that the device is on a bicycle (Since 3.0) */
 203         SENSOR_GESTURE_MOVEMENT = 0x200,        /**< Gesture sensor detecting any significant movements (Since 3.0) */
 204         SENSOR_GESTURE_WRIST_UP,                /**< Gesture sensor detecting wrist-up gestures (Since 3.0) */
 205         SENSOR_GESTURE_WRIST_DOWN,              /**< Gesture sensor detecting wrist-down gestures (Since 3.0) */
 206         SENSOR_HUMAN_PEDOMETER = 0x300,         /**< Pedometer (Since 3.0) @n Privilege : http://tizen.org/privilege/healthinfo */
 207         SENSOR_HUMAN_SLEEP_MONITOR,             /**< Sleep monitor (Since 3.0) @n Privilege : http://tizen.org/privilege/healthinfo */
 208         SENSOR_LAST,                            /**< End of sensor enum values (Deprecated since 3.0) */
 209         SENSOR_CUSTOM = 0x2710,                 /**< Custom sensor (Deprecated since 3.0) */
 210 } sensor_type_e;
 211
 212
 213 /**
 214  * @brief   Enumeration for sensor options.
 215  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 216  */
 217 #ifndef __SENSOR_COMMON_H__
 218 typedef enum
 219 {
 220         SENSOR_OPTION_DEFAULT,              /**< Does not receive data when the LCD is off and in the power save mode */
 221         SENSOR_OPTION_ON_IN_SCREEN_OFF,     /**< Receives data when the LCD is off */
 222         SENSOR_OPTION_ON_IN_POWERSAVE_MODE, /**< Receives data in the power save mode */
 223         SENSOR_OPTION_ALWAYS_ON,            /**< Receives data when the LCD is off and in the power save mode */
 224 } sensor_option_e;
 225 #endif
 226
 227
 228 /**
 229  * @brief   Enumeration for sensor listener behavior attributes
 230  * @since_tizen 3.0
 231  * @see     #sensor_axis_e
 232  * @see     #sensor_pause_e
 233  */
 234 typedef enum
 235 {
 236         SENSOR_ATTRIBUTE_AXIS_ORIENTATION = 1,  /**< Reference orientation of sensor data to be reported */
 237         SENSOR_ATTRIBUTE_PAUSE_POLICY,          /**< Pause-and-resume policy of sensors */
 238 } sensor_attribute_e;
 239
 240
 241 /**
 242  * @brief   Enumeration for reference orientations of sensor data
 243  * @details The sensor's physical orientation may differ from what applications are aware of,
 244  *          in cases that the device has a rotated screen, physically or logically.
 245  *          For example, a watch device may have right hand mode, which logically rotates
 246  *          the display 180 degrees.
 247  *          Applications may not be aware of such situations, thus they may receives
 248  *          sensor data inverted in X and Y directions.
 249  *          With #SENSOR_AXIS_DISPLAY_ORIENTED option, applications can get data that
 250  *          are properly aligned with the orientation of which they are aware.@n
 251  *          By default, #SENSOR_AXIS_DISPLAY_ORIENTED is used.
 252  *          If you need to use the data that are not affected by display orientations,
 253  *          #SENSOR_AXIS_DEVICE_ORIENTED needs to be set.
 254  * @since_tizen 3.0
 255  */
 256 typedef enum
 257 {
 258         SENSOR_AXIS_DEVICE_ORIENTED = 1,    /**< Using the device orientation as the reference coordinate system */
 259         SENSOR_AXIS_DISPLAY_ORIENTED,       /**< Using the display orientation as the reference coordinate system */
 260 } sensor_axis_e;
 261
 262
 263 /**
 264  * @brief   Enumeration for pause policies of sensor listeners
 265  * @details To be power-efficient, you can set the policy of how to pause and resume
 266  *          a sensor listener regarding the system status.
 267  *          By default, #SENSOR_PAUSE_ALL is used to obtain the maximum power efficiency.
 268  * @since_tizen 3.0
 269  */
 270 typedef enum
 271 {
 272         SENSOR_PAUSE_NONE = 0,              /**< The sensor will not pause, unless the system goes into sleep mode */
 273         SENSOR_PAUSE_ON_DISPLAY_OFF = 1,    /**< The sensor pauses while the display is off*/
 274         SENSOR_PAUSE_ON_POWERSAVE_MODE = 2, /**< The sensor pauses while the power-save mode is enabled */
 275         SENSOR_PAUSE_ALL = 3,               /**< The sensor pauses in all the above cases */
 276 } sensor_pause_e;
 277
 278
 279 /**
 280  * @brief   Checks whether a given sensor type is supported in the current device.
 281  * @details If the given sensor type is not supported, sensor_get_default_sensor() will return an error.
 282  *          It is thus recommended to check the availability of the sensor before actually acquiring #sensor_h.
 283  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 284  *
 285  * @param[in]   type        A sensor type to check
 286  * @param[out]  supported   If supported, @c true; Otherwise @c false
 287  *
 288  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
 289  * @retval  #SENSOR_ERROR_NONE                 Successful
 290  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 291  */
 292 int sensor_is_supported(sensor_type_e type, bool *supported);
 293
 294
 295 /**
 296  * @brief   Gets the handle for the default sensor of a given type.
 297  * @details This function returns the handle for the sensor of a given type,
 298  *          if the device has one sensor of the given type.
 299  *          In case that the device has more than one sensors of the type,
 300  *          this returns only the default sensor, which is designated by the device.@n
 301  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 302  *
 303  * @privlevel   public
 304  * @privilege   http://tizen.org/privilege/healthinfo
 305  *
 306  * @remarks Some sensor types are privileged, that is, application should have
 307  *          the corresponding privilege to use one of them. @n
 308  *          #SENSOR_HRM, #SENSOR_HRM_LED_GREEN, #SENSOR_HRM_LED_IR, #SENSOR_HRM_LED_RED,
 309  *          #SENSOR_HUMAN_PEDOMETER, and #SENSOR_HUMAN_SLEEP_MONITOR require the privilege
 310  *          http://tizen.org/privilege/healthinfo.
 311  *
 312  * @param[in]  type     A sensor type to get the handle of its default sensor
 313  * @param[out] sensor   The sensor handle of the default sensor
 314  *
 315  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
 316  * @retval  #SENSOR_ERROR_NONE                 Successful
 317  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 318  * @retval  #SENSOR_ERROR_NOT_SUPPORTED        The sensor type is not supported in the current device
 319  * @retval  #SENSOR_ERROR_PERMISSION_DENIED    Permission denied
 320  *
 321  * @see     sensor_get_sensor_list()
 322  */
 323 int sensor_get_default_sensor(sensor_type_e type, sensor_h *sensor);
 324
 325
 326 /**
 327  * @brief   Gets the handle list of the sensors of a given type.
 328  * @details A device may have more than one sensors of the given type.
 329  *          In such case, this function can be used to get the handles of all sensors of the type.@n
 330  *          The first element of the @c list denotes the default sensor,
 331  *          which can be retrieved by sensor_get_default_sensor().
 332  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 333  *
 334  * @privlevel   public
 335  * @privilege   http://tizen.org/privilege/healthinfo
 336  *
 337  * @remarks The @c list must be released using @c free().
 338  * @remarks If this function is called with #SENSOR_ALL,
 339  *          it returns the handles of all types of sensors supported in the device.
 340  * @remarks Some sensor types are privileged, that is, application should have
 341  *          the corresponding privilege to use one of them. @n
 342  *          #SENSOR_HRM, #SENSOR_HRM_LED_GREEN, #SENSOR_HRM_LED_IR, #SENSOR_HRM_LED_RED,
 343  *          #SENSOR_HUMAN_PEDOMETER, and #SENSOR_HUMAN_SLEEP_MONITOR require the privilege
 344  *          http://tizen.org/privilege/healthinfo.
 345  *
 346  * @param[in]  type         A sensor type to get the list of sensor handles
 347  * @param[out] list         An array of the sensor handles
 348  * @param[out] sensor_count The number of handles contained in @c list
 349  *
 350  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
 351  * @retval  #SENSOR_ERROR_NONE                 Successful
 352  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 353  * @retval  #SENSOR_ERROR_NOT_SUPPORTED        The sensor type is not supported in the current device
 354  * @retval  #SENSOR_ERROR_PERMISSION_DENIED    Permission denied
 355  * @retval  #SENSOR_ERROR_OUT_OF_MEMORY        Out of memory
 356  */
 357 int sensor_get_sensor_list(sensor_type_e type, sensor_h **list, int *sensor_count);
 358
 359
 360 /**
 361  * @brief   Checks whether a given sensor is a wake-up sensor or not.
 362  * @details If a sensor is a wake-up sensor, the sensor is able to wake-up the system
 363  *          to report its sensor data even if the system is in sleep mode.
 364  * @since_tizen 3.0
 365  *
 366  * @param[in]   sensor  A sensor handle to check
 367  * @param[out]  wakeup  If the sensor is a wake-up sensor, @c true;
 368  *                      Otherwise @c false
 369  *
 370  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 371  * @retval  #SENSOR_ERROR_NONE                 Successful
 372  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 373  *
 374  * @pre     The handle @c sensor needs to be initialized using
 375  *          sensor_get_default_sensor() or sensor_get_sensor_list() in advance.
 376  */
 377 int sensor_is_wake_up(sensor_h sensor, bool *wakeup);
 378
 379
 380 /**
 381  * @brief   Called when a sensor event occurs.
 382  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 383  *
 384  * @param[in] sensor    The corresponding sensor handle
 385  * @param[in] event     A sensor event
 386  * @param[in] data      The user data had passed to sensor_listener_set_event_cb()
 387  *
 388  * @pre     The sensor needs to be started regarding a listener handle, using sensor_listener_start().
 389  */
 390 typedef void (*sensor_event_cb)(sensor_h sensor, sensor_event_s *event, void *data);
 391
 392
 393 /**
 394  * @brief   Creates a sensor listener.
 395  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 396  *
 397  * @remarks The @c listener must be released using sensor_destroy_listener().
 398  *
 399  * @param[in]  sensor          A sensor handle
 400  * @param[out] listener        A listener handle of @c sensor
 401  *
 402  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 403  * @retval  #SENSOR_ERROR_NONE                 Successful
 404  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 405  * @retval  #SENSOR_ERROR_OUT_OF_MEMORY        Out of memory
 406  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 407  *
 408  * @pre     The handle @c sensor needs to be initialized using
 409  *          sensor_get_default_sensor() or sensor_get_sensor_list() in advance.
 410  */
 411 int sensor_create_listener(sensor_h sensor, sensor_listener_h *listener);
 412
 413
 414 /**
 415  * @brief   Releases all the resources allocated for a listener.
 416  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 417  *
 418  * @remarks If this function is called while the sensor is still running,
 419  *          that is, sensor_listener_start() was called but sensor_listener_stop() was not,
 420  *          then it is implicitly stopped.
 421  *
 422  * @param[in] listener  A listener handle
 423  *
 424  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 425  * @retval  #SENSOR_ERROR_NONE                 Successful
 426  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 427  *
 428  * @see     sensor_create_listener()
 429  */
 430 int sensor_destroy_listener(sensor_listener_h listener);
 431
 432
 433 /**
 434  * @brief   Starts observing the sensor events regarding a given sensor listener.
 435  * @details If a sensor listener is started, its event callback function starts to be called
 436  *          whenever the corresponding sensor events occur.@n
 437  *          For example, #SENSOR_ACCELEROMETER reports its sensor readings repeatedly,
 438  *          with a specific update interval.
 439  *          Note that, unlike the accelerometer, sensors like #SENSOR_PROXIMITY emit events
 440  *          only if their states change.
 441  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 442  *
 443  * @param[in]   listener  A listener handle
 444  *
 445  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 446  * @retval  #SENSOR_ERROR_NONE                 Successful
 447  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 448  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 449  *
 450  * @pre     The @c listener needs to be created in advance, by using sensor_create_listener().
 451  *          Then the callback function needs to be attached to the @c listener, by using
 452  *          sensor_listener_set_event_cb().
 453  * @see     sensor_listener_stop()
 454  */
 455 int sensor_listener_start(sensor_listener_h listener);
 456
 457
 458 /**
 459  * @brief   Stops observing the sensor events regarding a given sensor listener.
 460  * @details The listener's event callback function stops being called.
 461  *          But the sensor itself may not be stopped if there are other listeners
 462  *          that are using the same sensor.
 463  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 464  *
 465  * @param[in]   listener  A listener handle
 466  *
 467  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 468  * @retval  #SENSOR_ERROR_NONE                 Successful
 469  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 470  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 471  *
 472  * @see     sensor_listener_start()
 473  */
 474 int sensor_listener_stop(sensor_listener_h listener);
 475
 476
 477 /**
 478  * @brief   Registers the callback function to be invoked when sensor events are delivered via a sensor listener.
 479  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 480  *
 481  * @param[in]   listener    A listener handle
 482  * @param[in]   interval_ms A desired update interval between sensor events in milliseconds.@n
 483  *                          If 0, it will be automatically set to the default interval of the corresponding sensor.
 484  *                          Commonly the default interval is 100 ms, but it varies with the sensor and the device.@n
 485  *                          Regarding sensors, there update intervals also have valid ranges.
 486  *                          That is, any input values exceeding the valid range of a sensor will be
 487  *                          implicitly adjusted into the valid range.
 488  *                          The valid range of a sensor's update interval is usually from 10 ms to 1000 ms,
 489  *                          however, it also can varies with the sensor and the device.
 490  * @param[in]   callback    A callback function to attach with the @c listener handle
 491  * @param[in]   data        A user data to be passed to the callback function
 492  *
 493  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 494  * @retval  #SENSOR_ERROR_NONE                 Successful
 495  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 496  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 497  *
 498  * @see sensor_listener_unset_event_cb()
 499  */
 500 int sensor_listener_set_event_cb(sensor_listener_h listener, unsigned int interval_ms, sensor_event_cb callback, void *data);
 501
 502
 503 /**
 504  * @brief   Unregisters the sensor event callback function attached to a given sensor listener.
 505  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 506  *
 507  * @param[in]   listener    A listener handle
 508  *
 509  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 510  * @retval  #SENSOR_ERROR_NONE                 Successful
 511  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 512  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 513  *
 514  * @see     sensor_listener_set_event_cb()
 515  */
 516 int sensor_listener_unset_event_cb(sensor_listener_h listener);
 517
 518
 519 /**
 520  * @brief   Called when the accuracy of a sensor changes.
 521  * @details Sensors can be affected by the environment.
 522  *          For example, #SENSOR_MAGNETIC is sensitive to any surrounding objects that can influence
 523  *          electromagnetic fields. This function is called if the accuracy of the corresponding sensor is changed.
 524  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 525  *
 526  * @param[in]   sensor      A sensor handle
 527  * @param[in]   timestamp   The time in milliseconds when the accuracy changed
 528  * @param[in]   accuracy    The current accuracy of the sensor
 529  * @param[in]   data        The user data had passed to sensor_listener_set_accuracy_cb()
 530  */
 531 typedef void (*sensor_accuracy_changed_cb)(sensor_h sensor, unsigned long long timestamp, sensor_data_accuracy_e accuracy, void *data);
 532
 533
 534 /**
 535  * @brief   Registers the callback function to be invoked when the accuracy of a sensor changes.
 536  * @details In addition to sensor_event_cb(), sensor_accuracy_changed_cb() also can be attached
 537  *          to sensor listeners. With this accuracy callback function, applications can be notified
 538  *          the changes of the corresponding sensors separately.
 539  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 540  *
 541  * @param[in]   listener    A listener handle
 542  * @param[in]   callback    A callback function to attach with the @c listener handle
 543  * @param[in]   data        A user data to be passed to the callback function
 544  *
 545  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 546  * @retval  #SENSOR_ERROR_NONE                 Successful
 547  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 548  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 549  *
 550  * @pre     The @c listener needs to be started to get the change callbacks.
 551  * @see     sensor_listener_unset_accuracy_cb()
 552  */
 553 int sensor_listener_set_accuracy_cb(sensor_listener_h listener, sensor_accuracy_changed_cb callback, void *data);
 554
 555
 556 /**
 557  * @brief   Unregisters the sensor accuracy change callback function attached to a given sensor listener.
 558  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 559  *
 560  * @param[in]   listener    A listener handle
 561  *
 562  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 563  * @retval  #SENSOR_ERROR_NONE                 Successful
 564  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 565  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 566  *
 567  * @see     sensor_listener_set_accuracy_cb()
 568  */
 569 int sensor_listener_unset_accuracy_cb(sensor_listener_h listener);
 570
 571
 572 /**
 573  * @brief   Reads the current sensor data via a given sensor listener.
 574  * @details This function synchronously reads the sensor reading of the corresponding sensor, if available.
 575  *          Otherwise, if the sensor is not ready to report its values, this function fails and returns
 576  *          #SENSOR_ERROR_OPERATION_FAILED.
 577  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 578  *
 579  * @remark  As a sensor usually works in an event-driven manner, it may not be able to read its data on demand.
 580  *          Then this function tries to return the last known values.@n
 581  *          To be able to read the current values or the last known values, the sensor needs to be
 582  *          enabled in advance. As an application cannot be sure that the sensor is already enabled
 583  *          by other applications, it is recommended to start the sensor explicitly by using sensor_listener_start().@n
 584  *          But note that, even if the sensor is started, on-demand reading can fail always,
 585  *          thus it would be better to use the asynchronous callback approach.
 586  *
 587  * @param[in]   listener    A listener handle
 588  * @param[out]  event       The retrieved sensor data
 589  *
 590  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 591  * @retval  #SENSOR_ERROR_NONE                 Successful
 592  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 593  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 594  */
 595 int sensor_listener_read_data(sensor_listener_h listener, sensor_event_s *event);
 596
 597
 598 /**
 599  * @brief   Changes the update interval of a sensor.
 600  * @details The specified interval is only a suggested interval between sensor measurements.
 601  *          You will get at least one sensor measurement within the interval you specify,
 602  *          but the actual interval between sensor measurements can be affected by other applications and the system.
 603  *          To reduce the system overhead, it is recommended to set the longest interval that you can,
 604  *          because the system usually chooses the shortest interval among all intervals specified.
 605  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 606  *
 607  * @param[in]   listener    A listener handle
 608  * @param[in]   interval_ms A desired update interval between sensor events in milliseconds.@n
 609  *                          If 0, it will be automatically set to the default interval of the corresponding sensor.
 610  *                          Commonly the default interval is 100 ms, but it varies with the sensor and the device.@n
 611  *                          Regarding sensors, there update intervals also have valid ranges.
 612  *                          That is, any input values exceeding the valid range of a sensor will be
 613  *                          implicitly adjusted into the valid range.
 614  *                          The valid range of a sensor's update interval is usually from 10 ms to 1000 ms,
 615  *                          however, it also can varies with the sensor and the device.
 616  *
 617  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 618  * @retval  #SENSOR_ERROR_NONE                 Successful
 619  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 620  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 621  */
 622 int sensor_listener_set_interval(sensor_listener_h listener, unsigned int interval_ms);
 623
 624
 625 /**
 626  * @brief   Sets the desired max batch latency of a sensor.
 627  * @details Sensors that support batching may allow applications to change their maximum batch latencies.
 628  *          For example, if you set the latency as 10,000 ms, the sensor may store its data
 629  *          up to 10,000 ms, before delivering the data through the HAL.@n
 630  *          In cases of non-batching sensors, this function returns #SENSOR_ERROR_NONE,
 631  *          but nothing is affected by the input latency value.
 632  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 633  *
 634  * @remarks Even if you set a batch latency, the sensor may not work as you intended,
 635  *          as one sensor can be used by more than one listeners.
 636  *          In addition, some batch sensors may already have fixed batching latency
 637  *          or batching queue size, which cannot be altered by applications.
 638  *
 639  * @param[in]   listener           A listener handle
 640  * @param[in]   max_batch_latency  A desired batch latency in milliseconds
 641  *
 642  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 643  * @retval  #SENSOR_ERROR_NONE                 Successful
 644  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 645  */
 646 int sensor_listener_set_max_batch_latency(sensor_listener_h listener, unsigned int max_batch_latency);
 647
 648
 649 /**
 650  * @brief   Sets an attribute to control the behavior of a sensor listener.
 651  * @details Applications can change the behavior of a sensor listener, for example,
 652  *          what is the reference coordinate of the sensor values,
 653  *          and when the system is allowed to turn off the sensor implicitly to reduce the power consumption.
 654  *          See #sensor_attribute_e for more details about the available control parameters.
 655  * @since_tizen 3.0
 656  *
 657  * @param[in]   listener        A listener handle
 658  * @param[in]   attribute       An attribute to change
 659  * @param[in]   value           An attribute value
 660  *
 661  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 662  * @retval  #SENSOR_ERROR_NONE                 Successful
 663  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 664  */
 665 int sensor_listener_set_attribute_int(sensor_listener_h listener, sensor_attribute_e attribute, int value);
 666
 667
 668 /**
 669  * @brief   Changes the power-saving behavior of a sensor listener.
 670  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 671  *
 672  * @remark  sensor_listener_set_attribute_int() with #SENSOR_ATTRIBUTE_PAUSE_POLICY replaces this function.
 673  *
 674  * @param[in]   listener        A listener handle
 675  * @param[in]   option          A sensor option
 676  *
 677  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 678  * @retval  #SENSOR_ERROR_NONE                 Successful
 679  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 680  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 681  */
 682 int sensor_listener_set_option(sensor_listener_h listener, sensor_option_e option);
 683
 684 /**
 685  * @}
 686  */
 687
 688 /**
 689  * @addtogroup CAPI_SYSTEM_SENSOR_INFORMATION_MODULE
 690  * @{
 691  */
 692
 693 /**
 694  * @brief   Gets the name of a sensor.
 695  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 696  *
 697  * @param[in]   sensor  A sensor handle
 698  * @param[out]  name    The name of the sensor
 699  *
 700  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 701  * @retval  #SENSOR_ERROR_NONE                 Successful
 702  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 703  */
 704 int sensor_get_name(sensor_h sensor, char **name);
 705
 706
 707 /**
 708  * @brief   Gets the vendor of a sensor.
 709  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 710  *
 711  * @param[in]   sensor  A sensor handle
 712  * @param[out]  vendor  The vendor of the sensor
 713  *
 714  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 715  * @retval  #SENSOR_ERROR_NONE                 Successful
 716  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 717  */
 718 int sensor_get_vendor(sensor_h sensor, char **vendor);
 719
 720
 721 /**
 722  * @brief   Gets the sensor type of a sensor.
 723  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 724  *
 725  * @param[in]   sensor  A sensor handle
 726  * @param[out]  type    The type of the sensor
 727  *
 728  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 729  * @retval  #SENSOR_ERROR_NONE                 Successful
 730  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 731  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 732  */
 733 int sensor_get_type(sensor_h sensor, sensor_type_e *type);
 734
 735
 736 /**
 737  * @brief   Gets the lower bound of the sensor reading of a sensor.
 738  * @details This function returns the lower bound of the range of possible sensor values,
 739  *          which are generated by the corresponding sensor denoted by a sensor handle.@n
 740  *          If all sensor values are in the same unit, e.g., \f$\mbox{m/s}^2\f$ or degrees,
 741  *          the lower bound of all sensor values is returned.
 742  *          Otherwise, the lower bound of the representative sensor value, e.g.,
 743  *          the step count of #SENSOR_HUMAN_PEDOMETER, is returned.
 744  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 745  *
 746  * @param[in]   sensor      A sensor handle
 747  * @param[out]  min_range   The lower bound
 748  *
 749  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 750  * @retval  #SENSOR_ERROR_NONE                 Successful
 751  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 752  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 753  *
 754  * @see     sensor_get_max_range()
 755  */
 756 int sensor_get_min_range(sensor_h sensor, float *min_range);
 757
 758
 759 /**
 760  * @brief   Gets the upper bound of the sensor readings of a sensor.
 761  * @details This function returns the upper bound of the range of possible sensor values,
 762  *          which are generated by the corresponding sensor denoted by a sensor handle.@n
 763  *          If all sensor values are in the same unit, e.g., \f$\mbox{m/s}^2\f$ or degrees,
 764  *          the upper bound of all sensor values is returned.
 765  *          Otherwise, the upper bound of the representative sensor value, e.g.,
 766  *          the step count of #SENSOR_HUMAN_PEDOMETER, is returned.
 767  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 768  *
 769  * @param[in]   sensor      A sensor handle
 770  * @param[out]  max_range   The upper bound
 771  *
 772  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 773  * @retval  #SENSOR_ERROR_NONE                 Successful
 774  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 775  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 776  *
 777  * @see     sensor_get_min_range()
 778  */
 779 int sensor_get_max_range(sensor_h sensor, float *max_range);
 780
 781
 782 /**
 783  * @brief   Gets the resolution of the sensor readings of a sensor.
 784  * @details This function returns the resolution of the sensor readings.
 785  *          The resolution denotes the smallest difference between sensor readings,
 786  *          each of which is in the range that can be verified by
 787  *          sensor_get_min_range() and sensor_get_max_range().
 788  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 789  *
 790  * @param[in]   sensor      A sensor handle
 791  * @param[out]  resolution  The resolution
 792  *
 793  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 794  * @retval  #SENSOR_ERROR_NONE                 Successful
 795  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 796  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 797  */
 798 int sensor_get_resolution(sensor_h sensor, float *resolution);
 799
 800
 801 /**
 802  * @brief   Gets the possible shorted update interval of a sensor.
 803  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 804  *
 805  * @param[in]   sensor          A sensor handle
 806  * @param[out]  min_interval    The shorted interval in milliseconds
 807  *
 808  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 809  * @retval  #SENSOR_ERROR_NONE                 Successful
 810  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 811  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 812  */
 813 int sensor_get_min_interval(sensor_h sensor, int *min_interval);
 814
 815
 816 /**
 817  * @brief   Gets the size of the hardware FIFO of a sensor.
 818  * @details This function returns the size of the hardware FIFO that may be used by
 819  *          a specific sensor to support batching.
 820  *          However, regarding the underlying hardware configuration,
 821  *          the returned count may not mean the maximum number of sensor data that can be batched.
 822  *          See sensor_get_max_batch_count() for such purpose, finding out the
 823  *          possible maximum number of batched data.
 824  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 825  *
 826  * @param[in]   sensor          A sensor handle
 827  * @param[out]  fifo_count      The FIFO count
 828  *
 829  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 830  * @retval  #SENSOR_ERROR_NONE                 Successful
 831  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 832  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 833  */
 834 int sensor_get_fifo_count(sensor_h sensor, int *fifo_count);
 835
 836
 837 /**
 838  * @brief   Gets the maximum batch count of a sensor.
 839  * @details This function returns the maximum number of sensor data events
 840  *          that can be possibly delivered when the batched data are flushed.
 841  *          Therefore, this count can be used to check whether the sensor supports
 842  *          batching or not.@n
 843  *          If this returns a positive count, i.e., the sensor supports batching,
 844  *          the count also can be used to guess the possible longest batch latency
 845  *          of the sensor, with respect to the update interval to use.
 846  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 847  *
 848  * @param[in]   sensor          A sensor handle
 849  * @param[out]  max_batch_count If the sensor does not support batching, 0;
 850  *                              Otherwise a positive integer.
 851  *
 852  * @return  #SENSOR_ERROR_NONE on success, otherwise a negative error value
 853  * @retval  #SENSOR_ERROR_NONE                 Successful
 854  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 855  * @retval  #SENSOR_ERROR_OPERATION_FAILED     Operation failed
 856  *
 857  * @see     sensor_listener_set_max_batch_latency()
 858  */
 859 int sensor_get_max_batch_count(sensor_h sensor, int *max_batch_count);
 860 /**
 861  * @}
 862  */
 863
 864 /**
 865  * @addtogroup CAPI_SYSTEM_SENSOR_UTILITY_MODULE
 866  * @{
 867  */
 868
 869 /**
 870  * @brief   Enumeration of the axis used in sensor_util_remap_coordinate_system().
 871  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 872  */
 873 typedef enum
 874 {
 875     SENSOR_UTIL_AXIS_X = 0x01,          /**< +X */
 876     SENSOR_UTIL_AXIS_Y = 0x02,          /**< +Y */
 877     SENSOR_UTIL_AXIS_Z = 0x03,          /**< +Z */
 878     SENSOR_UTIL_AXIS_MINUS_X = 0x81,    /**< -X */
 879     SENSOR_UTIL_AXIS_MINUS_Y = 0x82,    /**< -Y */
 880     SENSOR_UTIL_AXIS_MINUS_Z = 0x83,    /**< -Z */
 881     sensor_util_axis_x = 0x01,
 882     sensor_util_axis_y = 0x02,
 883     sensor_util_axis_z = 0x03,
 884     sensor_util_axis_minus_x = 0x81,
 885     sensor_util_axis_minus_y = 0x82,
 886     sensor_util_axis_minus_z = 0x83,
 887 } sensor_util_axis_e;
 888
 889 /**
 890  * @brief   Gets the inclination matrix "I" and rotation matrix "R" transforming a vector from the device coordinate to the world's coordinate.
 891  *
 892  * @details [0 0 g] = R * gravity (g = magnitude of gravity) \n
 893  *          [0 m 0] = I * R * geomagnetic (m = magnitude of the geomagnetic field) \n
 894  *          R is the identity matrix when the device is aligned with the world's coordinate system, that is, when the device's X axis points towards the East, the Y axis points to the North Pole and the device is facing the sky. \n
 895  *          I is a rotation matrix transforming the geomagnetic vector into the same coordinate space as gravity (the world's coordinate space). I is a simple rotation around the X axis. \n
 896  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 897  *
 898  * @remarks Parameters Gx, Gy, and Gz can be obtained from the values returned by #SENSOR_GRAVITY. \n
 899  *          Parameters Mx, My, and Mz can be obtained from the values returned by #SENSOR_MAGNETIC.
 900  *          Output parameter R and I are always returned as a 3x3 matrix array of 9 floats like this form:
 901  *          <pre>
 902  *          { R[0], R[1], R[2],
 903  *            R[3], R[4], R[5],
 904  *            R[6], R[7], R[6] }
 905  *          </pre>
 906  *
 907  *
 908  * @param[in]  Gx   The X-axis gravity vector in the device's coordinate
 909  * @param[in]  Gy   The Y-axis gravity vector in the device's coordinate
 910  * @param[in]  Gz   The Z-axis gravity vector in the device's coordinate
 911  * @param[in]  Mx   The X-axis geomagnetic vector in the device's coordinate
 912  * @param[in]  My   The Y-axis geomagnetic vector in the device's coordinate
 913  * @param[in]  Mz   The Z-axis geomagnetic vector in the device's coordinate
 914  * @param[out] R    The array of 9 floats that represent the rotation matrix "R" \n
 915  *                  It can be null.
 916  * @param[out] I    The array of 9 floats that represent the inclination matrix "I" \n
 917  *                  It can be null.
 918  *
 919  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
 920  * @retval  #SENSOR_ERROR_NONE                 Successful
 921  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 922  */
 923 int sensor_util_get_rotation_matrix(float Gx, float Gy, float Gz,
 924         float Mx, float My, float Mz,
 925         float R[], float I[]);
 926
 927 /**
 928  * @brief Converts a rotation vector to a rotation matrix.
 929  *
 930  * @details Rotation vectors (Vx, Vy, Vz) can be obtained from #SENSOR_ROTATION_VECTOR.
 931  *          It returns a 9 element rotation matrix in the array R. R must have length as 9.
 932  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 933  *
 934  * @param[in]  Vx   The X-axis rotation vector
 935  * @param[in]  Vy   The Y-axis rotation vector
 936  * @param[in]  Vz   The Z-axis rotation vector
 937  * @param[out] R    A 9 element rotation matrix in the array R that must have length as 9
 938  *
 939  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
 940  * @retval  #SENSOR_ERROR_NONE                 Successful
 941  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 942  */
 943 int sensor_util_get_rotation_matrix_from_vector(float Vx, float Vy, float Vz, float R[]);
 944
 945 /**
 946  * @brief Rotates the supplied rotation matrix so that it is expressed in a different coordinate system.
 947  *
 948  * @details This is typically used when an application needs to compute the three orientation angles of the device in a different coordinate system.
 949  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 950  *
 951  * @remarks inR and outR can be the same array, but this is not recommended for performance reasons.
 952  *          This returns an error when X and Y define the same axis.
 953  *
 954  * @param[in]  inR  The rotation matrix (3x3) to be transformed
 955  * @param[in]  x    The world axis and direction on which the X axis of the device is mapped
 956  * @param[in]  y    The world axis and direction on which the Y axis of the device is mapped
 957  * @param[out] outR The transformed rotation matrix (3x3)
 958  *
 959  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
 960  * @retval  #SENSOR_ERROR_NONE                 Successful
 961  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 962  *
 963  */
 964 int sensor_util_remap_coordinate_system(float inR[], sensor_util_axis_e x, sensor_util_axis_e y, float outR[]);
 965
 966 /**
 967  * @brief Computes the geomagnetic inclination angle in radians from the inclination matrix I returned by sensor_util_get_rotation_matrix().
 968  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 969  *
 970  * @param[in]  I            The inclination matrix from sensor_util_get_rotation_matrix()
 971  * @param[out] inclination  The geomagnetic inclination angle in radians
 972  *
 973  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
 974  * @retval  #SENSOR_ERROR_NONE                 Successful
 975  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 976  *
 977  * @see sensor_util_get_rotation_matrix()
 978  */
 979 int sensor_util_get_inclination(float I[], float* inclination);
 980
 981 /**
 982  * @brief Computes the device's orientation based on the rotation matrix.
 983  *
 984  * @details When it returns, the array values are filled with the result:
 985  *          - values[0]: azimuth, rotation around the Z axis.
 986  *          - values[1]: pitch, rotation around the X axis.
 987  *          - values[2]: roll, rotation around the Y axis.
 988  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 989  *
 990  * @remarks Parameter R must be an array of 9 floats from sensor_util_get_rotation_matrix() \n
 991  *          Returned values are always arrays of 3 floats.
 992  *
 993  * @param[in]  R         A 9 element rotation matrix in the array
 994  * @param[out] values    An array of 3 floats to hold the result
 995  *
 996  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
 997  * @retval  #SENSOR_ERROR_NONE                 Successful
 998  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
 999  *
1000  * @see sensor_util_get_rotation_matrix()
1001  *
1002  */
1003 int sensor_util_get_orientation(float R[], float values[]);
1004
1005 /**
1006  * @brief Computes the angle change between two rotation matrices.
1007  *
1008  * @details Given a current rotation matrix (R) and a previous rotation matrix (prevR), it computes
1009  *          the rotation around the x,y, and z axes which transforms prevR to R.
1010  *          It outputs a 3 element vector containing the x,y, and z angle change at indexes 0, 1, and 2 respectively. \n
1011  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1012  *
1013  * @remarks Each input matrix is a 3x3 matrix like this form:
1014  *          <pre>
1015  *          { R[0], R[1], R[2],
1016  *            R[3], R[4], R[5],
1017  *            R[6], R[7], R[6] }
1018  *          </pre>
1019  *
1020  * @param[in] R             The current rotation matrix
1021  * @param[in] prevR         The previous rotation matrix
1022  * @param[out] angleChange  An array of floats in which the angle change is stored
1023  *
1024  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
1025  * @retval  #SENSOR_ERROR_NONE                 Successful
1026  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
1027  */
1028 int sensor_util_get_angle_change(float R[], float prevR[], float angleChange[]);
1029
1030 /**
1031  * @brief Gets the declination of the horizontal component of the magnetic field from true north, in degrees.
1032  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1033  *
1034  * @param[in]  latitude     The latitude in geodetic coordinates
1035  * @param[in]  longitude    The longitude in geodetic coordinates
1036  * @param[in]  altitude     The altitude in geodetic coordinates
1037  * @param[out] declination  The declination of the horizontal component of the magnetic field in degrees
1038  *
1039  * @return  #SENSOR_ERROR_NONE on success; Otherwise a negative error value
1040  * @retval  #SENSOR_ERROR_NONE                 Successful
1041  * @retval  #SENSOR_ERROR_INVALID_PARAMETER    Invalid parameter
1042  */
1043 int sensor_util_get_declination(float latitude, float longitude, float altitude, float* declination);
1044 /**
1045  * @}
1046  */
1047
1048 #ifdef __cplusplus
1049 }
1050 #endif
1051
1052 #endif /* __SENSOR_H__ */