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.orientation\n
  63  *  - %http://tizen.org/feature/sensor.gyroscope_orientation\n
  64  *  - %http://tizen.org/feature/sensor.geomagnetic_orientation\n
  65  *  - %http://tizen.org/feature/sensor.pedometer\n
  66  *  - %http://tizen.org/feature/sensor.sleep_monitor\n
  67  *  - %http://tizen.org/feature/sensor.stress_monitor\n
  68  *
  69  * It is recommended to design feature related codes in your application for reliability.\n
  70  *
  71  * 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
  72  *
  73  * 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
  74  *
  75  * 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>
  76  *
  77  */
  78
  79  /**
  80  * @ingroup CAPI_SYSTEM_SENSOR_MODULE
  81  * @defgroup CAPI_SYSTEM_SENSOR_LISTENER_MODULE Sensor Listener
  82  * @brief The @ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE API provides functions to observe data from sensors in the device.
  83  *
  84  * @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_HEADER Required Header
  85  *   \#include <sensor.h>
  86  *
  87  * @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_OVERVIEW Overview
  88  * This @ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE API provides functions to make use of sensors in the device.
  89  * It allows applications to turn on or turn off sensors, change the parameters of sensors,
  90  * and observe the changes of sensor data.\n
  91  * To control or listen a sensor, its corresponding sensor handle #sensor_h needs to be
  92  * acquired first, and this API provides two different ways to get the handle.\n
  93  * The conventional way is to get the sensor handles corresponding to the types of sensors,
  94  * #sensor_type_e, using sensor_get_sensor_list() or sensor_get_default_sensor().
  95  * You can access to the platform-defined sensors in this way.\n
  96  * Another way is to get the handles with with sensor URIs, using
  97  * sensor_get_sensor_list_by_uri() or sensor_get_default_sensor_by_uri().
  98  * This method allows to get the handles for non-platform-defined sensors,
  99  * \a i.e., sensors not listed in #sensor_type_e.
 100  * For example, a healthcare device may provide a galvanic skin response sensor.
 101  * In addition, application-defined sensors registered via \ref CAPI_SYSTEM_SENSOR_PROVIDER_MODULE API
 102  * also can be accessed using this URI-based method.
 103  *
 104  * @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI Sensor URIs
 105  * A sensor URI is in the form of @"%http://\<vendor\>/sensor/\<category\>/\<sensor-type\>/\<sensor-name\>@".
 106  * where the @"/\<sensor-name\>@" can be omitted.
 107  * In cases of platform-defined sensors, the vendor should be @"tizen.org@".
 108  * The category can be one of @"general@" and @"healthinfo@",
 109  * and @"healthinfo@" means that an application should have the privilege
 110  * %http://tizen.org/privilege/healthinfo to get the corresponding sensor handles.
 111  * If the name is omitted, the URI denotes the sensors of the given type,
 112  * it thus may correspond to more than one sensor.
 113  * Otherwise, it corresponds to a specific sensor in the device.
 114  * For example, the URI %http://tizen.org/sensor/general/light denotes
 115  * all the light sensors in the device, while %http://tizen.org/sensor/general/light/front
 116  * only denotes the light sensor named as @"front@".
 117  *
 118  * Here are the platform-defined sensor URIs corresponding to the sensor types defined in #sensor_type_e:\n
 119  * - %http://tizen.org/sensor/general/accelerometer (#SENSOR_ACCELEROMETER) \n
 120  * - %http://tizen.org/sensor/general/gravity (#SENSOR_GRAVITY) \n
 121  * - %http://tizen.org/sensor/general/linear_acceleration (#SENSOR_LINEAR_ACCELERATION) \n
 122  * - %http://tizen.org/sensor/general/magnetic (#SENSOR_MAGNETIC) \n
 123  * - %http://tizen.org/sensor/general/rotation_vector (#SENSOR_ROTATION_VECTOR) \n
 124  * - %http://tizen.org/sensor/general/orientation (#SENSOR_ORIENTATION) \n
 125  * - %http://tizen.org/sensor/general/gyroscope (#SENSOR_GYROSCOPE) \n
 126  * - %http://tizen.org/sensor/general/light (#SENSOR_LIGHT) \n
 127  * - %http://tizen.org/sensor/general/proximity (#SENSOR_PROXIMITY) \n
 128  * - %http://tizen.org/sensor/general/pressure (#SENSOR_PRESSURE) \n
 129  * - %http://tizen.org/sensor/general/ultraviolet (#SENSOR_ULTRAVIOLET) \n
 130  * - %http://tizen.org/sensor/general/temperature (#SENSOR_TEMPERATURE) \n
 131  * - %http://tizen.org/sensor/general/humidity (#SENSOR_HUMIDITY) \n
 132  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor (#SENSOR_HRM) \n
 133  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_green (#SENSOR_HRM_LED_GREEN) \n
 134  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_ir (#SENSOR_HRM_LED_IR) \n
 135  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_red (#SENSOR_HRM_LED_RED) \n
 136  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.batch (#SENSOR_HRM_BATCH) \n
 137  * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_green.batch (#SENSOR_HRM_LED_GREEN_BATCH) \n
 138  * - %http://tizen.org/sensor/general/gyroscope.uncalibrated (#SENSOR_GYROSCOPE_UNCALIBRATED) \n
 139  * - %http://tizen.org/sensor/general/geomagnetic.uncalibrated (#SENSOR_GEOMAGNETIC_UNCALIBRATED) \n
 140  * - %http://tizen.org/sensor/general/gyroscope_rotation_vector (#SENSOR_GYROSCOPE_ROTATION_VECTOR) \n
 141  * - %http://tizen.org/sensor/general/geomagnetic_rotation_vector (#SENSOR_GEOMAGNETIC_ROTATION_VECTOR) \n
 142  * - %http://tizen.org/sensor/general/gyroscope_orientation (#SENSOR_GYROSCOPE_ORIENTATION) \n
 143  * - %http://tizen.org/sensor/general/geomagnetic_orientation (#SENSOR_GEOMAGNETIC_ORIENTATION) \n
 144  * - %http://tizen.org/sensor/healthinfo/human_pedometer (#SENSOR_HUMAN_PEDOMETER) \n
 145  * - %http://tizen.org/sensor/healthinfo/human_sleep_monitor (#SENSOR_HUMAN_SLEEP_MONITOR) \n
 146  * - %http://tizen.org/sensor/healthinfo/human_sleep_detector (#SENSOR_HUMAN_SLEEP_DETECTOR) \n
 147  * - %http://tizen.org/sensor/healthinfo/human_stress_monitor (#SENSOR_HUMAN_STRESS_MONITOR) \n
 148  */
 149
 150  /**
 151  * @ingroup CAPI_SYSTEM_SENSOR_MODULE
 152  * @defgroup CAPI_SYSTEM_SENSOR_PROVIDER_MODULE Sensor Provider
 153  * @brief The @ref CAPI_SYSTEM_SENSOR_PROVIDER_MODULE API provides functions
 154  *        to define a new sensor instance and provide its data.
 155  *
 156  * @section CAPI_SYSTEM_SENSOR_PROVIDER_MODULE_HEADER Required Header
 157  *   \#include <sensor.h>
 158  *
 159  * @section CAPI_SYSTEM_SENSOR_PROVIDER_MODULE_OVERVIEW Overview
 160  * This Sensor API provides functions to define a new sensor instance from an application.
 161  * Other applications are able to be notified whenever a new sensor instance is registered
 162  * and listen to the new sensor.
 163  *
 164  */
 165
 166  /**
 167  * @ingroup CAPI_SYSTEM_SENSOR_MODULE
 168  * @defgroup CAPI_SYSTEM_SENSOR_RECORDER_MODULE Sensor Recorder
 169  * @brief The @ref CAPI_SYSTEM_SENSOR_RECORDER_MODULE API provides functions to start/stop recording sensor events and read the recorded data.
 170  *
 171  * @section CAPI_SYSTEM_SENSOR_RECORDER_MODULE_HEADER Required Header
 172  *   \#include <sensor.h>
 173  *
 174  * @section CAPI_SYSTEM_SENSOR_MODULE_OVERVIEW Overview
 175  * This Sensor API provides functions to record sensors events in the device.
 176  * Several sensors are typically available on mobile devices.
 177  *
 178  */
 179
 180 /**
 181  * @ingroup CAPI_SYSTEM_SENSOR_MODULE
 182  * @defgroup CAPI_SYSTEM_SENSOR_UTILITY_MODULE Sensor Utility
 183  * @brief The @ref CAPI_SYSTEM_SENSOR_UTILITY_MODULE API provides utility functions.
 184  *
 185  * @section CAPI_SYSTEM_SENSOR_UTILITY_MODULE_HEADER Required Header
 186  * \#include <sensor.h>
 187  *
 188  * @section CAPI_SYSTEM_SENSOR_UTILITY_MODULE_OVERVIEW Overview
 189  * This Sensor API provides utility functions.
 190  *
 191  */
 192
 193
 194 #endif // __TIZEN_SYSTEM_SENSORS_DOC_H__