summaryrefslogtreecommitdiff
path: root/legacy
diff options
context:
space:
mode:
authorStefan Schmidt <stefan@datenfreihafen.org>2012-12-03 14:44:33 +0000
committerStefan Schmidt <stefan@datenfreihafen.org>2012-12-03 14:44:33 +0000
commita423b298b8bec5e21fffd91f275a3c2aa3994cea (patch)
tree652642d9ee628e8208125bb2c624694579c0b773 /legacy
parent4f48fd72d09e8924971fcddf9e350d7aa445ceca (diff)
eeze: Give the eeze_sensor doxygen an overhaul.
Wrap at 80 chars, fix some typos and add more descriptions. SVN revision: 80070
Diffstat (limited to 'legacy')
-rw-r--r--legacy/eeze/src/lib/Eeze_Sensor.h95
1 files changed, 55 insertions, 40 deletions
diff --git a/legacy/eeze/src/lib/Eeze_Sensor.h b/legacy/eeze/src/lib/Eeze_Sensor.h
index ffc6266e88..6a6e85c86b 100644
--- a/legacy/eeze/src/lib/Eeze_Sensor.h
+++ b/legacy/eeze/src/lib/Eeze_Sensor.h
@@ -21,13 +21,14 @@
21 * @file Eeze_Sensor.h 21 * @file Eeze_Sensor.h
22 * @brief Sensor information 22 * @brief Sensor information
23 * 23 *
24 * Eeze sensor functions allow you to gather sensor information from different sensor sources 24 * Eeze sensor functions allow you to gather sensor information from different
25 * available on the hardware. It supports a plugin architecture to support different hardware 25 * sensor sources available on the hardware. It supports a plugin architecture
26 * platforms and devices. These plugins can be loaded at runtime to allow support for a specific 26 * to support different hardware platforms and devices. These plugins can be
27 * set of hardware or platform. 27 * loaded at runtime to allow support for a specific set of hardware or
28 * platform.
28 * 29 *
29 * Right now we have support for the Tizen sensor framework as well as a simple fake plugin to be 30 * Right now we have support for the Tizen sensor framework as well as a simple
30 * used as a test harness for developing. 31 * fake plugin to be used as a test harness for developing.
31 * 32 *
32 * @since 1.8 33 * @since 1.8
33 * 34 *
@@ -37,10 +38,12 @@
37 38
38/** 39/**
39 * @enum Eeze_Sensor_Type 40 * @enum Eeze_Sensor_Type
40 * @since 1.8
41 * 41 *
42 * All sensor types known by Eeze Sensor. This list of types include real physical types like 42 * All sensor types known by Eeze Sensor. This list of types include real
43 * proximity or light as well as "aggregated" types like facedown or doubletap. 43 * physical types like proximity or light as well as "aggregated" types like
44 * facedown or doubletap.
45 *
46 * @since 1.8
44 */ 47 */
45typedef enum 48typedef enum
46{ 49{
@@ -65,9 +68,9 @@ typedef enum
65 * @defgroup Sensor_Events Available eeze sensor events 68 * @defgroup Sensor_Events Available eeze sensor events
66 * @brief Sensor events that are emitted from the library as ecore events 69 * @brief Sensor events that are emitted from the library as ecore events
67 * 70 *
68 * Event types used to register #ecore_event_handler on. These events are used for 71 * Event types used to register #ecore_event_handler on. These events are used
69 * #eeze_sensor_async_read to deliver read out data. It is also used for generated events like 72 * for #eeze_sensor_async_read to deliver read out data. It is also used for
70 * facedown or shake. 73 * generated events like facedown or shake.
71 * 74 *
72 * @since 1.8 75 * @since 1.8
73 * @{ 76 * @{
@@ -90,14 +93,14 @@ EAPI int EEZE_SENSOR_EVENT_TEMPERATURE;
90/** 93/**
91 * @typedef Eeze_Sensor_Obj; 94 * @typedef Eeze_Sensor_Obj;
92 * 95 *
93 * Object for a sensor type. Keeps information about the type and holds the data for the accessor 96 * Object for a sensor type. Keeps information about the type and holds the
94 * functions. As this information gets also updated by asynchronous reads it might be a good idea 97 * data for the accessor functions. As this information gets also updated by
95 * to check the timestamp value to see when the data has been updated. The timestamp is given in 98 * asynchronous reads it might be a good idea to check the timestamp value to
96 * microseconds. 99 * see when the data has been updated. The timestamp is given in microseconds.
97 * 100 *
98 * You are not supposed to access the raw data values from here but use the getter functions for it. 101 * You are not supposed to access the raw data values from here but use the
99 * Using the raw values from this struct might break your applications later if the internal 102 * getter functions for it. Using the raw values from this struct might break
100 * structure changes. 103 * your applications later if the internal structure changes.
101 * 104 *
102 * @since 1.8 105 * @since 1.8
103 */ 106 */
@@ -119,12 +122,14 @@ extern "C" {
119 * @param type Sensor type to create object from. 122 * @param type Sensor type to create object from.
120 * @return Sensor object for the given type. 123 * @return Sensor object for the given type.
121 * 124 *
122 * Takes the sensor type and create an object for it to operate on. During this it also does an 125 * Takes the sensor type and create an object for it to operate on. During this
123 * initial sensor data read to fill the sensor data into the object. 126 * it also does an initial sensor data read to fill the sensor data into the
124 * The #eeze_sensor_free function must be used to destroy the object and release its memory. 127 * object. The #eeze_sensor_free function must be used to destroy the object
128 * and release its memory.
125 * 129 *
126 * For every sensor type you want to work with this is the first thing you have to do. Create the 130 * For every sensor type you want to work with this is the first thing you have
127 * object from the type and everything else the operates on this object. 131 * to do. Create the object from the type and everything else the operates on
132 * this object.
128 * 133 *
129 * @since 1.8 134 * @since 1.8
130 */ 135 */
@@ -146,8 +151,8 @@ EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens);
146 * @param accuracy Pointer to write accuracy value into. 151 * @param accuracy Pointer to write accuracy value into.
147 * @return EINA_TRUE for success and EINA_FALSE for failure 152 * @return EINA_TRUE for success and EINA_FALSE for failure
148 * 153 *
149 * Access function to get the accuracy property from the sensor object. The accuracy value can have 154 * Access function to get the accuracy property from the sensor object. The
150 * the following values and meaning: 155 * accuracy value can have the following values and meaning:
151 * -1 Undefined accuracy 156 * -1 Undefined accuracy
152 * 0 Bad accurancy 157 * 0 Bad accurancy
153 * 1 Normal accuracy 158 * 1 Normal accuracy
@@ -166,8 +171,9 @@ EAPI Eina_Bool eeze_sensor_accuracy_get(Eeze_Sensor_Obj *sens, int *accuracy);
166 * @param z Pointer to write third data property value into. 171 * @param z Pointer to write third data property value into.
167 * @return EINA_TRUE for success and EINA_FALSE for failure 172 * @return EINA_TRUE for success and EINA_FALSE for failure
168 * 173 *
169 * Access function to get all three data properties from the sensor object. This is used for sensor 174 * Access function to get all three data properties from the sensor object.
170 * types that offer all three values. Like accelerometer and magnetic. 175 * This is used for sensor types that offer all three values. Like accelerometer
176 * and magnetic.
171 * 177 *
172 * @since 1.8 178 * @since 1.8
173 */ 179 */
@@ -180,8 +186,8 @@ EAPI Eina_Bool eeze_sensor_xyz_get(Eeze_Sensor_Obj *sens, float *x, float *y, fl
180 * @param y Pointer to write second data property value into. 186 * @param y Pointer to write second data property value into.
181 * @return EINA_TRUE for success and EINA_FALSE for failure 187 * @return EINA_TRUE for success and EINA_FALSE for failure
182 * 188 *
183 * Access function to get the first two data properties from the sensor object. This is used for 189 * Access function to get the first two data properties from the sensor object.
184 * sensor types that offer two values. Like panning. 190 * This is used for sensor types that offer two values. Like panning.
185 * 191 *
186 * @since 1.8 192 * @since 1.8
187 */ 193 */
@@ -193,8 +199,8 @@ EAPI Eina_Bool eeze_sensor_xy_get(Eeze_Sensor_Obj *sens, float *x, float *y);
193 * @param x Pointer to write first data property value into. 199 * @param x Pointer to write first data property value into.
194 * @return EINA_TRUE for success and EINA_FALSE for failure 200 * @return EINA_TRUE for success and EINA_FALSE for failure
195 * 201 *
196 * Access function to get the first data property from the sensor object. This is used for sensor 202 * Access function to get the first data property from the sensor object. This
197 * types that only offer one value. Like light or proximity. 203 * is used for sensor types that only offer one value. Like light or proximity.
198 * 204 *
199 * @since 1.8 205 * @since 1.8
200 */ 206 */
@@ -206,8 +212,9 @@ EAPI Eina_Bool eeze_sensor_x_get(Eeze_Sensor_Obj *sens, float *x);
206 * @param timestamp Pointer to write timestamp value into. 212 * @param timestamp Pointer to write timestamp value into.
207 * @return EINA_TRUE for success and EINA_FALSE for failure 213 * @return EINA_TRUE for success and EINA_FALSE for failure
208 * 214 *
209 * Access function to get the timestamp property from the sensor object. It allows you to determine 215 * Access function to get the timestamp property from the sensor object. It
210 * if the values have been updated since the last time you requested them. 216 * allows you to determine if the values have been updated since the last time
217 * you requested them.
211 * 218 *
212 * @since 1.8 219 * @since 1.8
213 */ 220 */
@@ -218,9 +225,10 @@ EAPI Eina_Bool eeze_sensor_timestamp_get(Eeze_Sensor_Obj *sens, unsigned long lo
218 * @param sens Sensor object to operate on. 225 * @param sens Sensor object to operate on.
219 * @return EINA_TRUE for success and EINA_FALSE for failure 226 * @return EINA_TRUE for success and EINA_FALSE for failure
220 * 227 *
221 * This function reads sensor data from the device and fills the sensor object with the data. This 228 * This function reads sensor data from the device and fills the sensor object
222 * call is synchronous and blocks until the data is read out and updated in the sensor object. 229 * with the data. This call is synchronous and blocks until the data is read out
223 * For simple applications this is fine and the easiest way to use the API. 230 * and updated in the sensor object. For simple applications this is fine and
231 * the easiest way to use the API.
224 * 232 *
225 * @since 1.8 233 * @since 1.8
226 */ 234 */
@@ -232,9 +240,10 @@ EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens);
232 * @param user_data Data to pass to the callback function. 240 * @param user_data Data to pass to the callback function.
233 * @return EINA_TRUE for success and EINA_FALSE for failure 241 * @return EINA_TRUE for success and EINA_FALSE for failure
234 * 242 *
235 * This function reads sensor data from the device and fills the sensor object with the data. The 243 * This function reads sensor data from the device and fills the sensor object
236 * read is done asynchronously and thus does not block after calling. Instead the given callback 244 * with the data. The read is done asynchronously and thus does not block after
237 * function is called once the read is finished and the object filled. 245 * calling. Instead the given callback function is called once the read is
246 * finished and the object filled.
238 * 247 *
239 * @since 1.8 248 * @since 1.8
240 */ 249 */
@@ -253,6 +262,9 @@ EAPI Eeze_Sensor_Obj *eeze_sensor_obj_get(Eeze_Sensor_Type type);
253 * @brief Initialize the Eeze sensor subsystem. 262 * @brief Initialize the Eeze sensor subsystem.
254 * @return EINA_TRUE for success and EINA_FALSE for failure 263 * @return EINA_TRUE for success and EINA_FALSE for failure
255 * 264 *
265 * This function must be called before using any of the Eeze_Sensor
266 * functionality to make sure the subsystem is setup correctly for usage.
267 *
256 * @since 1.8 268 * @since 1.8
257 */ 269 */
258Eina_Bool eeze_sensor_init(void); 270Eina_Bool eeze_sensor_init(void);
@@ -260,6 +272,9 @@ Eina_Bool eeze_sensor_init(void);
260/** 272/**
261 * @brief Clean up and shutdown the Eeze sensor subsystem. 273 * @brief Clean up and shutdown the Eeze sensor subsystem.
262 * 274 *
275 * This function must be called when now longer using Eeze_Sensor to allow the
276 * subsystem to shutdown cleanly.
277 *
263 * @since 1.8 278 * @since 1.8
264 */ 279 */
265void eeze_sensor_shutdown(void); 280void eeze_sensor_shutdown(void);