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