doc/sensor_doc.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
  18 #ifndef __TIZEN_SYSTEM_SENSOR_DOC_H__
  19 #define __TIZEN_SYSTEM_SENSOR_DOC_H__
  20
  21  /**
  22  * @ingroup CAPI_SYSTEM_FRAMEWORK
  23  * @defgroup CAPI_SYSTEM_SENSOR_MODULE Sensor
  24  * @brief The @ref CAPI_SYSTEM_SENSOR_MODULE API provides functions to make use of sensors in the device.
  25  *
  26  * @section CAPI_SYSTEM_SENSOR_MODULE_HEADER Required Header
  27  *   \#include <sensor.h>
  28  *
  29  * @section CAPI_SYSTEM_SENSOR_MODULE_OVERVIEW Overview
  30  * This @ref CAPI_SYSTEM_SENSOR_MODULE API provides functions to make use of sensors in the device,
  31  * define new sensor instances from applications, request to record sensor events,
  32  * and acquire the recorded events.
  33  * It also provides functions for getting information of a sensor, for example,
  34  * the vendor and the resolution of its data.
  35  *
  36  * @section CAPI_SYSTEM_SENSOR_MODULE_FEATURE Related Features
  37  * A variety of sensors are typically available on mobile and wearable devices.
  38  * Regarding the types of sensors, this API is related with the following features:\n
  39  *  - %http://tizen.org/feature/sensor.accelerometer\n
  40  *  - %http://tizen.org/feature/sensor.barometer\n
  41  *  - %http://tizen.org/feature/sensor.gyroscope\n
  42  *  - %http://tizen.org/feature/sensor.magnetometer\n
  43  *  - %http://tizen.org/feature/sensor.photometer\n
  44  *  - %http://tizen.org/feature/sensor.proximity\n
  45  *  - %http://tizen.org/feature/sensor.tiltmeter\n
  46  *  - %http://tizen.org/feature/sensor.ultraviolet\n
  47  *  - %http://tizen.org/feature/sensor.temperature\n
  48  *  - %http://tizen.org/feature/sensor.humidity\n
  49  *  - %http://tizen.org/feature/sensor.linear_acceleration\n
  50  *  - %http://tizen.org/feature/sensor.rotation_vector\n
  51  *  - %http://tizen.org/feature/sensor.gravity\n
  52  *  - %http://tizen.org/feature/sensor.heart_rate_monitor\n
  53  *  - %http://tizen.org/feature/sensor.heart_rate_monitor.led_green\n
  54  *  - %http://tizen.org/feature/sensor.heart_rate_monitor.led_ir\n
  55  *  - %http://tizen.org/feature/sensor.heart_rate_monitor.led_red\n
  56  *  - %http://tizen.org/feature/sensor.heart_rate_monitor.batch\n
  57  *  - %http://tizen.org/feature/sensor.heart_rate_monitor.led_green.batch\n
  58  *  - %http://tizen.org/feature/sensor.gyroscope.uncalibrated\n
  59  *  - %http://tizen.org/feature/sensor.magnetometer.uncalibrated\n
  60  *  - %http://tizen.org/feature/sensor.gyroscope_rotation_vector\n
  61  *  - %http://tizen.org/feature/sensor.geomagnetic_rotation_vector\n
  62  *  - %http://tizen.org/feature/sensor.pedometer\n
  63  *  - %http://tizen.org/feature/sensor.sleep_monitor\n
  64  *  - %http://tizen.org/feature/sensor.stress_monitor\n
  65  *
  66  * It is recommended to design feature related codes in your application for reliability.\n
  67  *
  68  * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
  69  *
  70  * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
  71  *
  72  * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
  73  *
  74  */
  75
  76  /**
  77  * @ingroup CAPI_SYSTEM_SENSOR_MODULE
  78  * @defgroup CAPI_SYSTEM_SENSOR_LISTENER_MODULE Sensor Listener
  79  * @brief The @ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE API provides functions to observe data from sensors in the device.
  80  *
  81  * @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_HEADER Required Header
  82  *   \#include <sensor.h>
  83  *
  84  * @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_OVERVIEW Overview
  85  * This @ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE API provides functions to make use of sensors in the device.
  86  * It allows applications to turn on or turn off sensors, change the parameters of sensors,
  87  * and observe the changes of sensor data.\n
  88  * To control or listen a sensor, its corresponding sensor handle #sensor_h needs to be
  89  * acquired first, and this API provides two different ways to get the handle.\n
  90  * The conventional way is to get the sensor handles corresponding to the types of sensors,
  91  * #sensor_type_e, using sensor_get_sensor_list() or sensor_get_default_sensor().
  92  * You can access to the platform-defined sensors in this way.\n
  93  * Another way is to get the handles with with sensor URIs, using
  94  * sensor_get_sensor_list_by_uri() or sensor_get_default_sensor_by_uri().
  95  * This method allows to get the handles for non-platform-defined sensors,
  96  * \a i.e., sensors not listed in #sensor_type_e.
  97  * For example, a healthcare device may provide a galvanic skin response sensor.
  98  * In addition, application-defined sensors registered via \ref CAPI_SYSTEM_SENSOR_PROVIDER_MODULE API
  99  * also can be accessed using this URI-based method.
 100  *
 101  * @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI Sensor URIs
 102  * A sensor URI is in the form of @"%http://\<vendor\>/sensor/\<category\>/\<sensor-type\>/\<sensor-name\>@".
 103  * where the @"/\<sensor-name\>@" can be omitted.
 104  * In cases of platform-defined sensors, the vendor should be @"tizen.org@".
 105  * The category can be one of @"general@" and @"healthinfo@",
 106  * and @"healthinfo@" means that an application should have the privilege
 107  * %http://tizen.org/privilege/healthinfo to get the corresponding sensor handles.
 108  * If the name is omitted, the URI denotes the sensors of the given type,
 109  * it thus may correspond to more than one sensor.
 110  * Otherwise, it corresponds to a specific sensor in the device.
 111  * For example, the URI %http://tizen.org/sensor/general/light denotes
 112  * all the light sensors in the device, while %http://tizen.org/sensor/general/light/front
 113  * only denotes the light sensor named as @"front@".
 114  *
 115  * Here are the platform-defined sensor URIs corresponding to the sensor types defined in #sensor_type_e:\n
 116  * - %http://tizen.org/sensor/general/accelerometer (#SENSOR_ACCELEROMETER) \n
 117  * - %http://tizen.org/sensor/general/gravity (#SENSOR_GRAVITY) \n
 118  * - %http://tizen.org/sensor/general/linear_acceleration (#SENSOR_LINEAR_ACCELERATION) \n
 119  * - %http://tizen.org/sensor/general/magnetic (#SENSOR_MAGNETIC) \n
 120  * - %http://tizen.org/sensor/general/rotation_vector (#SENSOR_ROTATION_VECTOR) \n
 121  * - %http://tizen.org/sensor/general/orientation (#SENSOR_ORIENTATION) \n
 122  * - %http://tizen.org/sensor/general/gyroscope (#SENSOR_GYROSCOPE) \n
 123  * - %http://tizen.org/sensor/general/light (#SENSOR_LIGHT) \n
 124  * - %http://tizen.org/sensor/general/proximity (#SENSOR_PROXIMITY) \n
 125  * - %http://tizen.org/sensor/general/pressure (#SENSOR_PRESSURE) \n
 126  * - %http://tizen.org/sensor/general/ultraviolet (#SENSOR_ULTRAVIOLET) \n
 127  * - %http://tizen.org/sensor/general/temperature (#SENSOR_TEMPERATURE) \n
 128  * - %http://tizen.org/sensor/general/humidity (#SENSOR_HUMIDITY) \n
 129  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor (#SENSOR_HRM) \n
 130  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_green (#SENSOR_HRM_LED_GREEN) \n
 131  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_ir (#SENSOR_HRM_LED_IR) \n
 132  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_red (#SENSOR_HRM_LED_RED) \n
 133  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.batch (#SENSOR_HRM_BATCH) \n
 134  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_green.batch (#SENSOR_HRM_LED_GREEN_BATCH) \n
 135  * - %http://tizen.org/sensor/general/gyroscope.uncalibrated (#SENSOR_GYROSCOPE_UNCALIBRATED) \n
 136  * - %http://tizen.org/sensor/general/geomagnetic.uncalibrated (#SENSOR_GEOMAGNETIC_UNCALIBRATED) \n
 137  * - %http://tizen.org/sensor/general/gyroscope_rotation_vector (#SENSOR_GYROSCOPE_ROTATION_VECTOR) \n
 138  * - %http://tizen.org/sensor/general/geomagnetic_rotation_vector (#SENSOR_GEOMAGNETIC_ROTATION_VECTOR) \n
 139  * - %http://tizen.org/sensor/healthinfo/human_pedometer (#SENSOR_HUMAN_PEDOMETER) \n
 140  * - %http://tizen.org/sensor/healthinfo/human_sleep_monitor (#SENSOR_HUMAN_SLEEP_MONITOR) \n
 141  * - %http://tizen.org/sensor/healthinfo/human_sleep_detector (#SENSOR_HUMAN_SLEEP_DETECTOR) \n
 142  * - %http://tizen.org/sensor/healthinfo/human_stress_monitor (#SENSOR_HUMAN_STRESS_MONITOR) \n
 143  */
 144
 145  /**
 146  * @ingroup CAPI_SYSTEM_SENSOR_MODULE
 147  * @defgroup CAPI_SYSTEM_SENSOR_PROVIDER_MODULE Sensor Provider
 148  * @brief The @ref CAPI_SYSTEM_SENSOR_PROVIDER_MODULE API provides functions
 149  *        to define a new sensor instance and provide its data.
 150  *
 151  * @section CAPI_SYSTEM_SENSOR_PROVIDER_MODULE_HEADER Required Header
 152  *   \#include <sensor.h>
 153  *
 154  * @section CAPI_SYSTEM_SENSOR_PROVIDER_MODULE_OVERVIEW Overview
 155  * This Sensor API provides functions to define a new sensor instance from an application.
 156  * Other applications are able to be notified whenever a new sensor instance is registered
 157  * and listen to the new sensor.
 158  *
 159  */
 160
 161  /**
 162  * @ingroup CAPI_SYSTEM_SENSOR_MODULE
 163  * @defgroup CAPI_SYSTEM_SENSOR_RECORDER_MODULE Sensor Recorder
 164  * @brief The @ref CAPI_SYSTEM_SENSOR_RECORDER_MODULE API provides functions to start/stop recording sensor events and read the recorded data.
 165  *
 166  * @section CAPI_SYSTEM_SENSOR_RECORDER_MODULE_HEADER Required Header
 167  *   \#include <sensor.h>
 168  *
 169  * @section CAPI_SYSTEM_SENSOR_MODULE_OVERVIEW Overview
 170  * This Sensor API provides functions to record sensors events in the device.
 171  * Several sensors are typically available on mobile devices.
 172  *
 173  */
 174
 175 /**
 176  * @ingroup CAPI_SYSTEM_SENSOR_MODULE
 177  * @defgroup CAPI_SYSTEM_SENSOR_UTILITY_MODULE Sensor Utility
 178  * @brief The @ref CAPI_SYSTEM_SENSOR_UTILITY_MODULE API provides utility functions.
 179  *
 180  * @section CAPI_SYSTEM_SENSOR_UTILITY_MODULE_HEADER Required Header
 181  * \#include <sensor.h>
 182  *
 183  * @section CAPI_SYSTEM_SENSOR_UTILITY_MODULE_OVERVIEW Overview
 184  * This Sensor API provides utility functions.
 185  *
 186  */
 187
 188
 189 #endif // __TIZEN_SYSTEM_SENSORS_DOC_H__