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