forked from enlightenment/efl
eeze/sensor: Update documentation.
Updating the docs in the header as well as some more comments in the code itself. SVN revision: 77289
This commit is contained in:
parent
0f04d5bbfd
commit
0d2fcf9837
|
@ -20,11 +20,16 @@
|
||||||
/**
|
/**
|
||||||
* @file Eeze_Sensor.h
|
* @file Eeze_Sensor.h
|
||||||
* @brief Sensor information
|
* @brief Sensor information
|
||||||
* @since 1.8
|
|
||||||
*
|
*
|
||||||
* Eeze sensor functions allow you to gather sensor information from different sensor sources
|
* Eeze sensor functions allow you to gather sensor information from different sensor sources
|
||||||
* available on the hardware. It supports a plugin architecture to support different hardware
|
* available on the hardware. It supports a plugin architecture to support different hardware
|
||||||
* platforms and devices.
|
* platforms and devices. These plugins can be loaded at runtime to allow support for a specific
|
||||||
|
* set of hardware or platform.
|
||||||
|
*
|
||||||
|
* Right now we have support for the Tizen sensor framework as well as a simple fake plugin to be
|
||||||
|
* used as a test harness for developing.
|
||||||
|
*
|
||||||
|
* @since 1.8
|
||||||
*
|
*
|
||||||
* @addtogroup sensor Sensor
|
* @addtogroup sensor Sensor
|
||||||
* @{
|
* @{
|
||||||
|
@ -60,9 +65,10 @@ typedef enum
|
||||||
* @defgroup Sensor_Events Available eeze sensor events
|
* @defgroup Sensor_Events Available eeze sensor events
|
||||||
* @brief Sensor events that are emitted from the library as ecore events
|
* @brief Sensor events that are emitted from the library as ecore events
|
||||||
*
|
*
|
||||||
* Event types used to register ecore_event_handler on. These events are used for
|
* Event types used to register #ecore_event_handler on. These events are used for
|
||||||
* #eeze_sensor_async_read to deliver read out data. It is also used for generated events like
|
* #eeze_sensor_async_read to deliver read out data. It is also used for generated events like
|
||||||
* facedown or shake.
|
* facedown or shake.
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
* @{
|
* @{
|
||||||
*/
|
*/
|
||||||
|
@ -83,12 +89,17 @@ EAPI int EEZE_SENSOR_EVENT_TEMPERATURE;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @typedef Eeze_Sensor_Obj;
|
* @typedef Eeze_Sensor_Obj;
|
||||||
* @since 1.8
|
|
||||||
*
|
*
|
||||||
* Object for a sensor type. Keeps information about the type and holds the data for the accessor
|
* Object for a sensor type. Keeps information about the type and holds the data for the accessor
|
||||||
* functions. As this information gets also updated by asynchronous reads it might be a good idea
|
* functions. As this information gets also updated by asynchronous reads it might be a good idea
|
||||||
* to check the timestamp value to see when the data has been updated. The timestamp is given in
|
* to check the timestamp value to see when the data has been updated. The timestamp is given in
|
||||||
* microseconds.
|
* microseconds.
|
||||||
|
*
|
||||||
|
* You are not supposed to access the raw data values from here but use the getter functions for it.
|
||||||
|
* Using the raw values from this struct might break your applications later if the internal
|
||||||
|
* structure changes.
|
||||||
|
*
|
||||||
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
typedef struct _Eeze_Sensor_Obj
|
typedef struct _Eeze_Sensor_Obj
|
||||||
{
|
{
|
||||||
|
@ -111,6 +122,10 @@ extern "C" {
|
||||||
* Takes the sensor type and create an object for it to operate on. During this it also does an
|
* Takes the sensor type and create an object for it to operate on. During this it also does an
|
||||||
* initial sensor data read to fill the sensor data into the object.
|
* initial sensor data read to fill the sensor data into the object.
|
||||||
* The #eeze_sensor_free function must be used to destroy the object and release its memory.
|
* The #eeze_sensor_free function must be used to destroy the object and release its memory.
|
||||||
|
*
|
||||||
|
* For every sensor type you want to work with this is the first thing you have to do. Create the
|
||||||
|
* object from the type and everything else the operates on this object.
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
EAPI Eeze_Sensor_Obj *eeze_sensor_new(Eeze_Sensor_Type type);
|
EAPI 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);
|
||||||
* @param sens Sensor object to operate on.
|
* @param sens Sensor object to operate on.
|
||||||
*
|
*
|
||||||
* Free an sensor object when it is no longer needed.
|
* Free an sensor object when it is no longer needed.
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens);
|
EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens);
|
||||||
|
@ -130,7 +146,14 @@ EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens);
|
||||||
* @param accuracy Pointer to write accuracy value into.
|
* @param accuracy Pointer to write accuracy value into.
|
||||||
* @return EINA_TRUE for success and EINA_FALSE for failure
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
||||||
*
|
*
|
||||||
* Access function to get the accuracy property from the sensor object.
|
* Access function to get the accuracy property from the sensor object. The accuracy value can have
|
||||||
|
* the following values and meaning:
|
||||||
|
* -1 Undefined accuracy
|
||||||
|
* 0 Bad accurancy
|
||||||
|
* 1 Normal accuracy
|
||||||
|
* 2 Good accuracy
|
||||||
|
* 3 Very good accuracy
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Bool eeze_sensor_accuracy_get(Eeze_Sensor_Obj *sens, int *accuracy);
|
EAPI 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);
|
||||||
*
|
*
|
||||||
* Access function to get all three data properties from the sensor object. This is used for sensor
|
* Access function to get all three data properties from the sensor object. This is used for sensor
|
||||||
* types that offer all three values. Like accelerometer and magnetic.
|
* types that offer all three values. Like accelerometer and magnetic.
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Bool eeze_sensor_xyz_get(Eeze_Sensor_Obj *sens, float *x, float *y, float *z);
|
EAPI 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
|
||||||
* @param y Pointer to write second data property value into.
|
* @param y Pointer to write second data property value into.
|
||||||
* @return EINA_TRUE for success and EINA_FALSE for failure
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
||||||
*
|
*
|
||||||
* Access function to get the first two data properties from the sensor object. This is used for sensor
|
* Access function to get the first two data properties from the sensor object. This is used for
|
||||||
* types that offer two values. Like panning.
|
* sensor types that offer two values. Like panning.
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Bool eeze_sensor_xy_get(Eeze_Sensor_Obj *sens, float *x, float *y);
|
EAPI 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);
|
||||||
*
|
*
|
||||||
* Access function to get the first data property from the sensor object. This is used for sensor
|
* Access function to get the first data property from the sensor object. This is used for sensor
|
||||||
* types that only offer one value. Like light or proximity.
|
* types that only offer one value. Like light or proximity.
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Bool eeze_sensor_x_get(Eeze_Sensor_Obj *sens, float *x);
|
EAPI 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);
|
||||||
* @param timestamp Pointer to write timestamp value into.
|
* @param timestamp Pointer to write timestamp value into.
|
||||||
* @return EINA_TRUE for success and EINA_FALSE for failure
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
||||||
*
|
*
|
||||||
* Access function to get the timestamp property from the sensor object.
|
* Access function to get the timestamp property from the sensor object. It allows you to determine
|
||||||
|
* if the values have been updated since the last time you requested them.
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Bool eeze_sensor_timestamp_get(Eeze_Sensor_Obj *sens, unsigned long long *timestamp);
|
EAPI 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
|
||||||
* This function reads sensor data from the device and fills the sensor object with the data. This
|
* This function reads sensor data from the device and fills the sensor object with the data. This
|
||||||
* call is synchronous and blocks until the data is read out and updated in the sensor object.
|
* call is synchronous and blocks until the data is read out and updated in the sensor object.
|
||||||
* For simple applications this is fine and the easiest way to use the API.
|
* For simple applications this is fine and the easiest way to use the API.
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens);
|
EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens);
|
||||||
|
@ -206,6 +235,7 @@ EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens);
|
||||||
* This function reads sensor data from the device and fills the sensor object with the data. The
|
* This function reads sensor data from the device and fills the sensor object with the data. The
|
||||||
* read is done asynchronously and thus does not block after calling. Instead the given callback
|
* read is done asynchronously and thus does not block after calling. Instead the given callback
|
||||||
* function is called once the read is finished and the object filled.
|
* function is called once the read is finished and the object filled.
|
||||||
|
*
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Bool eeze_sensor_async_read(Eeze_Sensor_Obj *sens, void *user_data);
|
EAPI 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
|
||||||
*/
|
*/
|
||||||
EAPI Eeze_Sensor_Obj *eeze_sensor_obj_get(Eeze_Sensor_Type type);
|
EAPI Eeze_Sensor_Obj *eeze_sensor_obj_get(Eeze_Sensor_Type type);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Initialize the Eeze sensor subsystem.
|
||||||
|
* @return EINA_TRUE for success and EINA_FALSE for failure
|
||||||
|
*
|
||||||
|
* @since 1.8
|
||||||
|
*/
|
||||||
Eina_Bool eeze_sensor_init(void);
|
Eina_Bool eeze_sensor_init(void);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @brief Clean up and shutdown the Eeze sensor subsystem.
|
||||||
|
*
|
||||||
|
* @since 1.8
|
||||||
|
*/
|
||||||
void eeze_sensor_shutdown(void);
|
void eeze_sensor_shutdown(void);
|
||||||
|
|
||||||
#ifdef __cplusplus
|
#ifdef __cplusplus
|
||||||
|
|
|
@ -11,7 +11,11 @@
|
||||||
|
|
||||||
Eeze_Sensor *g_handle;
|
Eeze_Sensor *g_handle;
|
||||||
|
|
||||||
/* Priority order for modules. The one with the highest order of the available ones will be used */
|
/* Priority order for modules. The one with the highest order of the available ones will be used.
|
||||||
|
* This in good enough for now as we only have two modules and one is a test harness anyway. If the
|
||||||
|
* number of modules grows we might re-think the priority handling, but we should do this when the
|
||||||
|
* need arise.
|
||||||
|
*/
|
||||||
static const char *_module_priority[] = {
|
static const char *_module_priority[] = {
|
||||||
"tizen",
|
"tizen",
|
||||||
"fake",
|
"fake",
|
||||||
|
|
|
@ -37,7 +37,8 @@ extern int _eeze_sensor_log_dom;
|
||||||
* @typedef Eeze_Sensor
|
* @typedef Eeze_Sensor
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*
|
*
|
||||||
* Handle for an Eeze_Sensor.
|
* Internal data structure to hold the information about loaded and available runtime modules of
|
||||||
|
* Eeze_Sensor.
|
||||||
*/
|
*/
|
||||||
typedef struct _Eeze_Sensor
|
typedef struct _Eeze_Sensor
|
||||||
{
|
{
|
||||||
|
@ -49,7 +50,8 @@ typedef struct _Eeze_Sensor
|
||||||
* @typedef Eeze_Sensor_Module;
|
* @typedef Eeze_Sensor_Module;
|
||||||
* @since 1.8
|
* @since 1.8
|
||||||
*
|
*
|
||||||
* Loadable module data structure.
|
* Internal data structure for the modules. It mainly holds function pointers each modules provides
|
||||||
|
* to be called from the Eeze_Sensor core to access the data provided by the module.
|
||||||
*/
|
*/
|
||||||
typedef struct _Eeze_Sensor_Module
|
typedef struct _Eeze_Sensor_Module
|
||||||
{
|
{
|
||||||
|
|
|
@ -10,6 +10,11 @@
|
||||||
#include <Eeze_Sensor.h>
|
#include <Eeze_Sensor.h>
|
||||||
#include "eeze_sensor_private.h"
|
#include "eeze_sensor_private.h"
|
||||||
|
|
||||||
|
/* This small Eeze_Sensor module is meant to be used as a test harness for developing. It does not
|
||||||
|
* gather any real data from hardware sensors. It uses fixed values for the data, but provides the
|
||||||
|
* correct timestamp value.
|
||||||
|
*/
|
||||||
|
|
||||||
Eeze_Sensor_Module *esensor_module;
|
Eeze_Sensor_Module *esensor_module;
|
||||||
|
|
||||||
Eina_Bool
|
Eina_Bool
|
||||||
|
|
Loading…
Reference in New Issue