summaryrefslogtreecommitdiff
path: root/legacy/eeze
diff options
context:
space:
mode:
authorStefan Schmidt <stefan@datenfreihafen.org>2012-10-02 08:47:45 +0000
committerStefan Schmidt <stefan@datenfreihafen.org>2012-10-02 08:47:45 +0000
commit0d2fcf9837994bda3b968f35276f132c0b2cf2cc (patch)
treec429da8412c66a49f0fce032d5a3f50c5a7a00e1 /legacy/eeze
parent0f04d5bbfd3d9c36913e7a264744effb100f6427 (diff)
eeze/sensor: Update documentation.
Updating the docs in the header as well as some more comments in the code itself. SVN revision: 77289
Diffstat (limited to 'legacy/eeze')
-rw-r--r--legacy/eeze/src/lib/Eeze_Sensor.h58
-rw-r--r--legacy/eeze/src/lib/eeze_sensor.c6
-rw-r--r--legacy/eeze/src/lib/eeze_sensor_private.h6
-rw-r--r--legacy/eeze/src/modules/eeze_sensor_fake.c5
4 files changed, 64 insertions, 11 deletions
diff --git a/legacy/eeze/src/lib/Eeze_Sensor.h b/legacy/eeze/src/lib/Eeze_Sensor.h
index 9673d8685a..ffc6266e88 100644
--- a/legacy/eeze/src/lib/Eeze_Sensor.h
+++ b/legacy/eeze/src/lib/Eeze_Sensor.h
@@ -20,11 +20,16 @@
20/** 20/**
21 * @file Eeze_Sensor.h 21 * @file Eeze_Sensor.h
22 * @brief Sensor information 22 * @brief Sensor information
23 * @since 1.8
24 * 23 *
25 * 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 sensor sources
26 * available on the hardware. It supports a plugin architecture to support different hardware 25 * available on the hardware. It supports a plugin architecture to support different hardware
27 * platforms and devices. 26 * platforms and devices. These plugins can be loaded at runtime to allow support for a specific
27 * set of hardware or platform.
28 *
29 * Right now we have support for the Tizen sensor framework as well as a simple fake plugin to be
30 * used as a test harness for developing.
31 *
32 * @since 1.8
28 * 33 *
29 * @addtogroup sensor Sensor 34 * @addtogroup sensor Sensor
30 * @{ 35 * @{
@@ -60,9 +65,10 @@ typedef enum
60 * @defgroup Sensor_Events Available eeze sensor events 65 * @defgroup Sensor_Events Available eeze sensor events
61 * @brief Sensor events that are emitted from the library as ecore events 66 * @brief Sensor events that are emitted from the library as ecore events
62 * 67 *
63 * Event types used to register ecore_event_handler on. These events are used for 68 * Event types used to register #ecore_event_handler on. These events are used for
64 * #eeze_sensor_async_read to deliver read out data. It is also used for generated events like 69 * #eeze_sensor_async_read to deliver read out data. It is also used for generated events like
65 * facedown or shake. 70 * facedown or shake.
71 *
66 * @since 1.8 72 * @since 1.8
67 * @{ 73 * @{
68 */ 74 */
@@ -83,12 +89,17 @@ EAPI int EEZE_SENSOR_EVENT_TEMPERATURE;
83 89
84/** 90/**
85 * @typedef Eeze_Sensor_Obj; 91 * @typedef Eeze_Sensor_Obj;
86 * @since 1.8
87 * 92 *
88 * Object for a sensor type. Keeps information about the type and holds the data for the accessor 93 * Object for a sensor type. Keeps information about the type and holds the data for the accessor
89 * functions. As this information gets also updated by asynchronous reads it might be a good idea 94 * functions. As this information gets also updated by asynchronous reads it might be a good idea
90 * to check the timestamp value to see when the data has been updated. The timestamp is given in 95 * to check the timestamp value to see when the data has been updated. The timestamp is given in
91 * microseconds. 96 * microseconds.
97 *
98 * You are not supposed to access the raw data values from here but use the getter functions for it.
99 * Using the raw values from this struct might break your applications later if the internal
100 * structure changes.
101 *
102 * @since 1.8
92 */ 103 */
93typedef struct _Eeze_Sensor_Obj 104typedef struct _Eeze_Sensor_Obj
94{ 105{
@@ -111,6 +122,10 @@ extern "C" {
111 * Takes the sensor type and create an object for it to operate on. During this it also does an 122 * Takes the sensor type and create an object for it to operate on. During this it also does an
112 * initial sensor data read to fill the sensor data into the object. 123 * initial sensor data read to fill the sensor data into the object.
113 * The #eeze_sensor_free function must be used to destroy the object and release its memory. 124 * The #eeze_sensor_free function must be used to destroy the object and release its memory.
125 *
126 * For every sensor type you want to work with this is the first thing you have to do. Create the
127 * object from the type and everything else the operates on this object.
128 *
114 * @since 1.8 129 * @since 1.8
115 */ 130 */
116EAPI Eeze_Sensor_Obj *eeze_sensor_new(Eeze_Sensor_Type type); 131EAPI Eeze_Sensor_Obj *eeze_sensor_new(Eeze_Sensor_Type type);
@@ -120,6 +135,7 @@ EAPI Eeze_Sensor_Obj *eeze_sensor_new(Eeze_Sensor_Type type);
120 * @param sens Sensor object to operate on. 135 * @param sens Sensor object to operate on.
121 * 136 *
122 * Free an sensor object when it is no longer needed. 137 * Free an sensor object when it is no longer needed.
138 *
123 * @since 1.8 139 * @since 1.8
124 */ 140 */
125EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens); 141EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens);
@@ -130,7 +146,14 @@ EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens);
130 * @param accuracy Pointer to write accuracy value into. 146 * @param accuracy Pointer to write accuracy value into.
131 * @return EINA_TRUE for success and EINA_FALSE for failure 147 * @return EINA_TRUE for success and EINA_FALSE for failure
132 * 148 *
133 * Access function to get the accuracy property from the sensor object. 149 * Access function to get the accuracy property from the sensor object. The accuracy value can have
150 * the following values and meaning:
151 * -1 Undefined accuracy
152 * 0 Bad accurancy
153 * 1 Normal accuracy
154 * 2 Good accuracy
155 * 3 Very good accuracy
156 *
134 * @since 1.8 157 * @since 1.8
135 */ 158 */
136EAPI Eina_Bool eeze_sensor_accuracy_get(Eeze_Sensor_Obj *sens, int *accuracy); 159EAPI Eina_Bool eeze_sensor_accuracy_get(Eeze_Sensor_Obj *sens, int *accuracy);
@@ -145,6 +168,7 @@ EAPI Eina_Bool eeze_sensor_accuracy_get(Eeze_Sensor_Obj *sens, int *accuracy);
145 * 168 *
146 * Access function to get all three data properties from the sensor object. This is used for sensor 169 * Access function to get all three data properties from the sensor object. This is used for sensor
147 * types that offer all three values. Like accelerometer and magnetic. 170 * types that offer all three values. Like accelerometer and magnetic.
171 *
148 * @since 1.8 172 * @since 1.8
149 */ 173 */
150EAPI Eina_Bool eeze_sensor_xyz_get(Eeze_Sensor_Obj *sens, float *x, float *y, float *z); 174EAPI Eina_Bool eeze_sensor_xyz_get(Eeze_Sensor_Obj *sens, float *x, float *y, float *z);
@@ -156,8 +180,9 @@ EAPI Eina_Bool eeze_sensor_xyz_get(Eeze_Sensor_Obj *sens, float *x, float *y, fl
156 * @param y Pointer to write second data property value into. 180 * @param y Pointer to write second data property value into.
157 * @return EINA_TRUE for success and EINA_FALSE for failure 181 * @return EINA_TRUE for success and EINA_FALSE for failure
158 * 182 *
159 * Access function to get the first two data properties from the sensor object. This is used for sensor 183 * Access function to get the first two data properties from the sensor object. This is used for
160 * types that offer two values. Like panning. 184 * sensor types that offer two values. Like panning.
185 *
161 * @since 1.8 186 * @since 1.8
162 */ 187 */
163EAPI Eina_Bool eeze_sensor_xy_get(Eeze_Sensor_Obj *sens, float *x, float *y); 188EAPI Eina_Bool eeze_sensor_xy_get(Eeze_Sensor_Obj *sens, float *x, float *y);
@@ -170,6 +195,7 @@ EAPI Eina_Bool eeze_sensor_xy_get(Eeze_Sensor_Obj *sens, float *x, float *y);
170 * 195 *
171 * Access function to get the first data property from the sensor object. This is used for sensor 196 * Access function to get the first data property from the sensor object. This is used for sensor
172 * types that only offer one value. Like light or proximity. 197 * types that only offer one value. Like light or proximity.
198 *
173 * @since 1.8 199 * @since 1.8
174 */ 200 */
175EAPI Eina_Bool eeze_sensor_x_get(Eeze_Sensor_Obj *sens, float *x); 201EAPI Eina_Bool eeze_sensor_x_get(Eeze_Sensor_Obj *sens, float *x);
@@ -180,7 +206,9 @@ EAPI Eina_Bool eeze_sensor_x_get(Eeze_Sensor_Obj *sens, float *x);
180 * @param timestamp Pointer to write timestamp value into. 206 * @param timestamp Pointer to write timestamp value into.
181 * @return EINA_TRUE for success and EINA_FALSE for failure 207 * @return EINA_TRUE for success and EINA_FALSE for failure
182 * 208 *
183 * Access function to get the timestamp property from the sensor object. 209 * Access function to get the timestamp property from the sensor object. It allows you to determine
210 * if the values have been updated since the last time you requested them.
211 *
184 * @since 1.8 212 * @since 1.8
185 */ 213 */
186EAPI Eina_Bool eeze_sensor_timestamp_get(Eeze_Sensor_Obj *sens, unsigned long long *timestamp); 214EAPI Eina_Bool eeze_sensor_timestamp_get(Eeze_Sensor_Obj *sens, unsigned long long *timestamp);
@@ -193,6 +221,7 @@ EAPI Eina_Bool eeze_sensor_timestamp_get(Eeze_Sensor_Obj *sens, unsigned long lo
193 * This function reads sensor data from the device and fills the sensor object with the data. This 221 * This function reads sensor data from the device and fills the sensor object with the data. This
194 * call is synchronous and blocks until the data is read out and updated in the sensor object. 222 * call is synchronous and blocks until the data is read out and updated in the sensor object.
195 * For simple applications this is fine and the easiest way to use the API. 223 * For simple applications this is fine and the easiest way to use the API.
224 *
196 * @since 1.8 225 * @since 1.8
197 */ 226 */
198EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens); 227EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens);
@@ -206,6 +235,7 @@ EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens);
206 * This function reads sensor data from the device and fills the sensor object with the data. The 235 * This function reads sensor data from the device and fills the sensor object with the data. The
207 * read is done asynchronously and thus does not block after calling. Instead the given callback 236 * read is done asynchronously and thus does not block after calling. Instead the given callback
208 * function is called once the read is finished and the object filled. 237 * function is called once the read is finished and the object filled.
238 *
209 * @since 1.8 239 * @since 1.8
210 */ 240 */
211EAPI Eina_Bool eeze_sensor_async_read(Eeze_Sensor_Obj *sens, void *user_data); 241EAPI Eina_Bool eeze_sensor_async_read(Eeze_Sensor_Obj *sens, void *user_data);
@@ -219,7 +249,19 @@ EAPI Eina_Bool eeze_sensor_async_read(Eeze_Sensor_Obj *sens, void *user_da
219 */ 249 */
220EAPI Eeze_Sensor_Obj *eeze_sensor_obj_get(Eeze_Sensor_Type type); 250EAPI Eeze_Sensor_Obj *eeze_sensor_obj_get(Eeze_Sensor_Type type);
221 251
252/**
253 * @brief Initialize the Eeze sensor subsystem.
254 * @return EINA_TRUE for success and EINA_FALSE for failure
255 *
256 * @since 1.8
257 */
222Eina_Bool eeze_sensor_init(void); 258Eina_Bool eeze_sensor_init(void);
259
260/**
261 * @brief Clean up and shutdown the Eeze sensor subsystem.
262 *
263 * @since 1.8
264 */
223void eeze_sensor_shutdown(void); 265void eeze_sensor_shutdown(void);
224 266
225#ifdef __cplusplus 267#ifdef __cplusplus
diff --git a/legacy/eeze/src/lib/eeze_sensor.c b/legacy/eeze/src/lib/eeze_sensor.c
index 344552c441..91103b7dd7 100644
--- a/legacy/eeze/src/lib/eeze_sensor.c
+++ b/legacy/eeze/src/lib/eeze_sensor.c
@@ -11,7 +11,11 @@
11 11
12Eeze_Sensor *g_handle; 12Eeze_Sensor *g_handle;
13 13
14/* Priority order for modules. The one with the highest order of the available ones will be used */ 14/* Priority order for modules. The one with the highest order of the available ones will be used.
15 * This in good enough for now as we only have two modules and one is a test harness anyway. If the
16 * number of modules grows we might re-think the priority handling, but we should do this when the
17 * need arise.
18 */
15static const char *_module_priority[] = { 19static const char *_module_priority[] = {
16 "tizen", 20 "tizen",
17 "fake", 21 "fake",
diff --git a/legacy/eeze/src/lib/eeze_sensor_private.h b/legacy/eeze/src/lib/eeze_sensor_private.h
index 5e56801df2..5464ae8f2d 100644
--- a/legacy/eeze/src/lib/eeze_sensor_private.h
+++ b/legacy/eeze/src/lib/eeze_sensor_private.h
@@ -37,7 +37,8 @@ extern int _eeze_sensor_log_dom;
37 * @typedef Eeze_Sensor 37 * @typedef Eeze_Sensor
38 * @since 1.8 38 * @since 1.8
39 * 39 *
40 * Handle for an Eeze_Sensor. 40 * Internal data structure to hold the information about loaded and available runtime modules of
41 * Eeze_Sensor.
41 */ 42 */
42typedef struct _Eeze_Sensor 43typedef struct _Eeze_Sensor
43{ 44{
@@ -49,7 +50,8 @@ typedef struct _Eeze_Sensor
49 * @typedef Eeze_Sensor_Module; 50 * @typedef Eeze_Sensor_Module;
50 * @since 1.8 51 * @since 1.8
51 * 52 *
52 * Loadable module data structure. 53 * Internal data structure for the modules. It mainly holds function pointers each modules provides
54 * to be called from the Eeze_Sensor core to access the data provided by the module.
53 */ 55 */
54typedef struct _Eeze_Sensor_Module 56typedef struct _Eeze_Sensor_Module
55{ 57{
diff --git a/legacy/eeze/src/modules/eeze_sensor_fake.c b/legacy/eeze/src/modules/eeze_sensor_fake.c
index 0a45b67b0a..30ab5cc3cc 100644
--- a/legacy/eeze/src/modules/eeze_sensor_fake.c
+++ b/legacy/eeze/src/modules/eeze_sensor_fake.c
@@ -10,6 +10,11 @@
10#include <Eeze_Sensor.h> 10#include <Eeze_Sensor.h>
11#include "eeze_sensor_private.h" 11#include "eeze_sensor_private.h"
12 12
13/* This small Eeze_Sensor module is meant to be used as a test harness for developing. It does not
14 * gather any real data from hardware sensors. It uses fixed values for the data, but provides the
15 * correct timestamp value.
16 */
17
13Eeze_Sensor_Module *esensor_module; 18Eeze_Sensor_Module *esensor_module;
14 19
15Eina_Bool 20Eina_Bool