From 77b2e630027d057221c471906344d9a588f54f3d Mon Sep 17 00:00:00 2001 From: Stefan Schmidt Date: Thu, 13 Dec 2012 14:17:14 +0000 Subject: [PATCH] eeze/sensor: Add more documentation and comment the code. SVN revision: 80861 --- legacy/eeze/src/bin/eeze_sensor_test.c | 1 - legacy/eeze/src/lib/Eeze_Sensor.h | 31 ++++++-- legacy/eeze/src/lib/eeze_sensor.c | 61 ++++++++++++--- legacy/eeze/src/lib/eeze_sensor_private.h | 24 +++++- legacy/eeze/src/modules/eeze_sensor_fake.c | 34 ++++++--- legacy/eeze/src/modules/eeze_sensor_tizen.c | 82 +++++++++++++++++++-- 6 files changed, 197 insertions(+), 36 deletions(-) diff --git a/legacy/eeze/src/bin/eeze_sensor_test.c b/legacy/eeze/src/bin/eeze_sensor_test.c index d158ee1de6..2c7387691e 100644 --- a/legacy/eeze/src/bin/eeze_sensor_test.c +++ b/legacy/eeze/src/bin/eeze_sensor_test.c @@ -171,4 +171,3 @@ main(void) return 0; } - diff --git a/legacy/eeze/src/lib/Eeze_Sensor.h b/legacy/eeze/src/lib/Eeze_Sensor.h index a853ab72fc..0f53f0b601 100644 --- a/legacy/eeze/src/lib/Eeze_Sensor.h +++ b/legacy/eeze/src/lib/Eeze_Sensor.h @@ -52,7 +52,9 @@ * * All sensor types known by Eeze Sensor. This list of types include real * physical types like proximity or light as well as "aggregated" types like - * facedown or doubletap. + * facedown or doubletap. All types with MOTION in their name can be used as + * real events coming from the underlying system. This is not supported on all + * systems. * * @since 1.8 */ @@ -81,7 +83,9 @@ typedef enum * * 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 facedown or shake. + * generated events like facedown or shake. Subscribing to these events in your + * application allowsyou to react on these changes in an efficient way without + * polling for new updates and wasting power and computing cycles. * * @since 1.8 * @{ @@ -142,6 +146,10 @@ extern "C" { * to do. Create the object from the type and everything else the operates on * this object. * + * This also takes into account what runtime modules are loaded and handles + * them in a given priority to pick up the best sensor source for your sensor + * object. + * * @since 1.8 */ EAPI Eeze_Sensor_Obj *eeze_sensor_new(Eeze_Sensor_Type type); @@ -150,7 +158,8 @@ EAPI Eeze_Sensor_Obj *eeze_sensor_new(Eeze_Sensor_Type type); * @brief Free a sensor object. * @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. Always use this function + * to cleanup unused sensor objects. * * @since 1.8 */ @@ -239,7 +248,10 @@ 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 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. + * the easiest way to use the API. A more efficient way is to use + * #eeze_sensor_async_read which allows the sensor readout to happen in the + * background and the application would check the timestamp of the data to + * determine how recent the data is. * * @since 1.8 */ @@ -253,8 +265,15 @@ 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 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. + * calling. Instead the given the application can determine how recent the + * values are from the timestamp value that can be accessed through + * #eeze_sensor_timestamp_get. + * + * This function is more efficient but needs a bit more work in the application. + * An easier way is to use the synchronous #eeze_sensor_read functions. The + * downside of it is that it blocks until the data was read out from the + * physical sensor. That might be a long time depending on the hardware and its + * interface. * * @since 1.8 */ diff --git a/legacy/eeze/src/lib/eeze_sensor.c b/legacy/eeze/src/lib/eeze_sensor.c index 4c23c34978..566c4c5d96 100644 --- a/legacy/eeze/src/lib/eeze_sensor.c +++ b/legacy/eeze/src/lib/eeze_sensor.c @@ -11,10 +11,10 @@ Eeze_Sensor *g_handle; -/* 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. +/* 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[] = { "tizen", @@ -22,6 +22,9 @@ static const char *_module_priority[] = { NULL }; +/* Search through the list of loaded module and return the one with the highest + * priority. + */ Eeze_Sensor_Module * _highest_priority_module_get(void) { @@ -37,6 +40,9 @@ _highest_priority_module_get(void) return NULL; } +/* Utility function to take the given sensor type and get the matching sensor + * object from the highest priority module. + */ EAPI Eeze_Sensor_Obj * eeze_sensor_obj_get(Eeze_Sensor_Type sensor_type) { @@ -69,7 +75,8 @@ eeze_sensor_modules_load(void) /* Check for available runtime modules and load them. In some cases the * un-installed modules to be used from the local build dir. Coverage check * is one of these items. We do load the modules from the builddir if the - * environment is set. Normal case is to use installed modules from system */ + * environment is set. Normal case is to use installed modules from system + */ if (getenv("EEZE_USE_IN_TREE_MODULES")) g_handle->modules_array = eina_module_list_get(NULL, PACKAGE_BUILD_DIR "/src/modules/.libs/", 0, NULL, NULL); else @@ -80,7 +87,6 @@ eeze_sensor_modules_load(void) ERR("No modules found!"); return; } - eina_module_list_load(g_handle->modules_array); } @@ -94,6 +100,10 @@ eeze_sensor_modules_unload(void) g_handle->modules_array = NULL; } +/* This function is offered to the modules to register itself after they have + * been loaded in initialized. They stay in the hash funtion until they + * unregister themself. + */ Eina_Bool eeze_sensor_module_register(const char *name, Eeze_Sensor_Module *mod) { @@ -114,6 +124,9 @@ eeze_sensor_module_register(const char *name, Eeze_Sensor_Module *mod) return eina_hash_add(g_handle->modules, name, module); } +/* This function is offered to the modules to unregsiter itself. When requested + * we remove them safely from the hash. + */ Eina_Bool eeze_sensor_module_unregister(const char *name) { @@ -128,6 +141,13 @@ eeze_sensor_module_unregister(const char *name) return eina_hash_del(g_handle->modules, name, NULL); } +/* Create a new sensor object for a given sensor type. This functions allocates + * the needed memory and links it with the matching sensor from the loaded + * modules. It also does an initial synchronous read to fill the sensor object + * with values. + * Make sure to use the eeze_sensor_free function to remove this sensor object + * when it is no longer needed. + */ EAPI Eeze_Sensor_Obj * eeze_sensor_new(Eeze_Sensor_Type type) { @@ -145,14 +165,20 @@ eeze_sensor_new(Eeze_Sensor_Type type) if (!module->read) return NULL; + /* The read is asynchronous here as we want to make sure that the sensor + * object has valid data when created. As we give back cached values we + * have a race condition when we do a asynchronous read here and the + * application asks for cached data before the reply came in. This logic has + * the downside that the sensor creation takes longer. But that is only a + *initial cost. + */ if (module->read(sens->type, sens)) - { - return sens; - } - else - return NULL; + return sens; + + return NULL; } +/* Free sensor object created with eeze_sensor_new */ EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens) { @@ -160,6 +186,10 @@ eeze_sensor_free(Eeze_Sensor_Obj *sens) free(sens); } +/* All of the below getter function do access the cached data from the last + * sensor read. It is way faster this way but also means that the timestamp + * should be checked to ensure recent data if needed. + */ EAPI Eina_Bool eeze_sensor_accuracy_get(Eeze_Sensor_Obj *sens, int *accuracy) { @@ -208,6 +238,9 @@ eeze_sensor_timestamp_get(Eeze_Sensor_Obj *sens, unsigned long long *timestamp) return EINA_TRUE; } +/* Synchronous read. Blocked until the data was readout from the hardware + * sensor + */ EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens) { @@ -224,6 +257,9 @@ eeze_sensor_read(Eeze_Sensor_Obj *sens) return EINA_FALSE; } +/* Asynchronous read. Schedule a new read out that will update the cached values + * as soon as it arrives. + */ EAPI Eina_Bool eeze_sensor_async_read(Eeze_Sensor_Obj *sens, void *user_data) { @@ -263,6 +299,7 @@ eeze_sensor_init(void) g_handle->modules = eina_hash_string_small_new(NULL); if (!g_handle->modules) return EINA_FALSE; + /* Make sure we create new ecore event types before using them */ EEZE_SENSOR_EVENT_SNAP = ecore_event_type_new(); EEZE_SENSOR_EVENT_SHAKE = ecore_event_type_new(); EEZE_SENSOR_EVENT_DOUBLETAP = ecore_event_type_new(); @@ -270,8 +307,8 @@ eeze_sensor_init(void) EEZE_SENSOR_EVENT_FACEDOWN = ecore_event_type_new(); EEZE_SENSOR_EVENT_ACCELEROMETER = ecore_event_type_new(); + /* Core is ready so we can load the modules from disk now */ eeze_sensor_modules_load(); return EINA_TRUE; } - diff --git a/legacy/eeze/src/lib/eeze_sensor_private.h b/legacy/eeze/src/lib/eeze_sensor_private.h index 5464ae8f2d..88c45e2367 100644 --- a/legacy/eeze/src/lib/eeze_sensor_private.h +++ b/legacy/eeze/src/lib/eeze_sensor_private.h @@ -13,7 +13,6 @@ extern int _eeze_sensor_log_dom; #ifdef CRI #undef CRI #endif - #ifdef ERR #undef ERR #endif @@ -62,6 +61,29 @@ typedef struct _Eeze_Sensor_Module Eina_List *sensor_list; /**< List of sensor objects attached to the module */ } Eeze_Sensor_Module; +/** + * @brief Register a module to eeze_sensor core. + * @param name Module name used for reference internally. + * @param mod Sensor module to be registered. + * @return EINA_TRUE is the module was successfully registered. EINA_FALSE is not. + * + * Private functions for modules to register itself to eeze sensor core to + * advertise their functionality. These registered modules will then be accessed + * based on a priority that is currently hardcoded in the code. Once more module + * are available we need to re-consider this approach. + * + * @since 1.8 + */ Eina_Bool eeze_sensor_module_register(const char *name, Eeze_Sensor_Module *mod); + +/** + * @brief Unregister a module from eeze_sensor core. + * @param name Module name used for reference internally. + * @return EINA_TRUE is the module was successfully unregistered. EINA_FALSE is not. + * + * Private functions for modules to unregister itself from eeze sensor core. + * + * @since 1.8 + */ Eina_Bool eeze_sensor_module_unregister(const char *name); #endif // EEZE_SENSOR_PRIVATE_H diff --git a/legacy/eeze/src/modules/eeze_sensor_fake.c b/legacy/eeze/src/modules/eeze_sensor_fake.c index cbb65ac8bc..ab2373d5be 100644 --- a/legacy/eeze/src/modules/eeze_sensor_fake.c +++ b/legacy/eeze/src/modules/eeze_sensor_fake.c @@ -10,9 +10,9 @@ #include #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. +/* 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; @@ -20,7 +20,9 @@ Eeze_Sensor_Module *esensor_module; Eina_Bool fake_init(void) { - /* Set a list with fake sensors */ + /* For the fake module we prepare a list with all potential sensors. Even if + * we only have a small subset at the moment. + */ Eeze_Sensor_Type type; for (type = 0; type <= EEZE_SENSOR_TYPE_LAST; type++) @@ -33,6 +35,9 @@ fake_init(void) return EINA_TRUE; } +/* We don't have anything to clear when we get unregistered from the core here. + * This is different in other modules. + */ Eina_Bool fake_shutdown(void) { @@ -58,7 +63,8 @@ fake_read(Eeze_Sensor_Type sensor_type, Eeze_Sensor_Obj *lobj) case EEZE_SENSOR_TYPE_MAGNETIC: case EEZE_SENSOR_TYPE_ORIENTATION: case EEZE_SENSOR_TYPE_GYROSCOPE: - obj->accuracy = 0; + /* This is only a test harness so we supply hardcoded values here */ + obj->accuracy = -1; obj->data[0] = 7; obj->data[1] = 23; obj->data[2] = 42; @@ -70,7 +76,7 @@ fake_read(Eeze_Sensor_Type sensor_type, Eeze_Sensor_Obj *lobj) case EEZE_SENSOR_TYPE_PROXIMITY: case EEZE_SENSOR_TYPE_BAROMETER: case EEZE_SENSOR_TYPE_TEMPERATURE: - obj->accuracy = 0; + obj->accuracy = -1; obj->data[0] = 7; gettimeofday(&tv, NULL); obj->timestamp = ((tv.tv_sec * 1000000) + tv.tv_usec); @@ -106,7 +112,7 @@ fake_async_read(Eeze_Sensor_Type sensor_type, void *user_data EINA_UNUSED) case EEZE_SENSOR_TYPE_MAGNETIC: case EEZE_SENSOR_TYPE_ORIENTATION: case EEZE_SENSOR_TYPE_GYROSCOPE: - obj->accuracy = 0; + obj->accuracy = -1; obj->data[0] = 7; obj->data[1] = 23; obj->data[2] = 42; @@ -118,7 +124,7 @@ fake_async_read(Eeze_Sensor_Type sensor_type, void *user_data EINA_UNUSED) case EEZE_SENSOR_TYPE_PROXIMITY: case EEZE_SENSOR_TYPE_BAROMETER: case EEZE_SENSOR_TYPE_TEMPERATURE: - obj->accuracy = 0; + obj->accuracy = -1; obj->data[0] = 7; gettimeofday(&tv, NULL); obj->timestamp = ((tv.tv_sec * 1000000) + tv.tv_usec); @@ -128,10 +134,13 @@ fake_async_read(Eeze_Sensor_Type sensor_type, void *user_data EINA_UNUSED) ERR("Not possible to set a callback for this sensor type."); return EINA_FALSE; } - return EINA_TRUE; } +/* This function gets called when the module is loaded from the disk. Its the + * entry point to anything in this module. After settign ourself up we register + * into the core of eeze sensor to make our functionality available. + */ Eina_Bool sensor_fake_init(void) { @@ -142,6 +151,9 @@ sensor_fake_init(void) esensor_module = calloc(1, sizeof(Eeze_Sensor_Module)); if (!esensor_module) return EINA_FALSE; + /* Setup our function pointers to allow the core accessing this modules + * functions + */ esensor_module->init = fake_init; esensor_module->shutdown = fake_shutdown; esensor_module->read = fake_read; @@ -152,10 +164,12 @@ sensor_fake_init(void) ERR("Failed to register fake module."); return EINA_FALSE; } - return EINA_TRUE; } +/* Cleanup when the module gets unloaded. Unregister ourself from the core to + * avoid calls into a not loaded module. + */ void sensor_fake_shutdown(void) { diff --git a/legacy/eeze/src/modules/eeze_sensor_tizen.c b/legacy/eeze/src/modules/eeze_sensor_tizen.c index ffcc263e66..29154883e5 100644 --- a/legacy/eeze/src/modules/eeze_sensor_tizen.c +++ b/legacy/eeze/src/modules/eeze_sensor_tizen.c @@ -14,8 +14,13 @@ #include "eeze_sensor_private.h" Eeze_Sensor_Module *esensor_module; -sensor_h sensor_handle; // Tizen sensor handle +/* Tizen sensor handle */ +sensor_h sensor_handle; +/* The Tizen sensor type ENUM has shown to not be stable regarding its + * numbering scheme so we better translate between the Tizen types and the + * ones we use here. + */ static sensor_type_e eeze_to_tizen(Eeze_Sensor_Type type) { @@ -60,6 +65,15 @@ eeze_to_tizen(Eeze_Sensor_Type type) } } +/* All following callback function work with the same scheme. + * They are callbacks coming in from the tizen system sensor library. With the + * data we receive we update the matching sensor object to always have the + * latest data available. That includes updating the timestamp to show when the + * data was measured from the underlying system. + * After that we send out an ecore event to let all interested parties now that + * new data is available and then stop the sensor server to safe power. It will be + * started again the next time data gets requested. + */ void accelerometer_cb(unsigned long long timestamp, sensor_data_accuracy_e accuracy, float x, float y, float z, void *user_data) { @@ -151,7 +165,8 @@ light_cb(unsigned long long timestamp, float lux, void *user_data) ERR("No matching sensor object found in list."); return; } - obj->accuracy = 0; + /* We have to set this ourselves because we don't get it for this type */ + obj->accuracy = -1; obj->data[0] = lux; obj->timestamp = timestamp; ecore_event_add(EEZE_SENSOR_EVENT_LIGHT, obj, NULL, NULL); @@ -169,7 +184,8 @@ proximity_cb(unsigned long long timestamp, float distance, void *user_data) ERR("No matching sensor object found in list."); return; } - obj->accuracy = 0; + /* We have to set this ourselves because we don't get it for this type */ + obj->accuracy = -1; obj->data[0] = distance; obj->timestamp = timestamp; ecore_event_add(EEZE_SENSOR_EVENT_PROXIMITY, obj, NULL, NULL); @@ -187,6 +203,8 @@ snap_cb(unsigned long long timestamp, sensor_motion_snap_e snap, void *user_data ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ + obj->accuracy = -1; obj->data[0] = snap; obj->timestamp = timestamp; ecore_event_add(EEZE_SENSOR_EVENT_SNAP, obj, NULL, NULL); @@ -204,6 +222,8 @@ shake_cb(unsigned long long timestamp, sensor_motion_shake_e shake, void *user_d ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ + obj->accuracy = -1; obj->data[0] = shake; obj->timestamp = timestamp; ecore_event_add(EEZE_SENSOR_EVENT_SHAKE, obj, NULL, NULL); @@ -221,6 +241,8 @@ panning_cb(unsigned long long timestamp, int x, int y, void *user_data) ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ + obj->accuracy = -1; obj->data[0] = x; obj->data[1] = y; obj->timestamp = timestamp; @@ -239,8 +261,13 @@ facedown_cb(unsigned long long timestamp, void *user_data) ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ + obj->accuracy = -1; obj->timestamp = timestamp; ecore_event_add(EEZE_SENSOR_EVENT_FACEDOWN, obj, NULL, NULL); + /* We are not stopping the sensor here because we want to keep it as a motion + * event coming in at any time. + */ } void @@ -254,8 +281,13 @@ doubletap_cb(unsigned long long timestamp, void *user_data) ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ + obj->accuracy = -1; obj->timestamp = timestamp; ecore_event_add(EEZE_SENSOR_EVENT_DOUBLETAP, obj, NULL, NULL); + /* We are not stopping the sensor here because we want to keep it as a motion + * event coming in at any time. + */ } void @@ -359,6 +391,7 @@ light_read_cb(unsigned long long timestamp, float lux, void *user_data) ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ obj->accuracy = -1; obj->data[0] = lux; obj->timestamp = timestamp; @@ -379,7 +412,8 @@ proximity_read_cb(unsigned long long timestamp, float distance, void *user_data) ERR("No matching sensor object found in list."); return; } - obj->accuracy = -1; + /* We have to set this ourselves because we don't get it for this type */ + bj->accuracy = -1; obj->data[0] = distance; obj->timestamp = timestamp; ecore_event_add(EEZE_SENSOR_EVENT_PROXIMITY, obj, NULL, NULL); @@ -399,6 +433,7 @@ snap_read_cb(unsigned long long timestamp, sensor_motion_snap_e snap, void *user ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ obj->accuracy = -1; obj->data[0] = snap; obj->timestamp = timestamp; @@ -419,6 +454,7 @@ shake_read_cb(unsigned long long timestamp, sensor_motion_shake_e shake, void *u ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ obj->accuracy = -1; obj->data[0] = shake; obj->timestamp = timestamp; @@ -439,6 +475,7 @@ panning_read_cb(unsigned long long timestamp, int x, int y, void *user_data) ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ obj->accuracy = -1; obj->data[0] = x; obj->data[1] = y; @@ -460,6 +497,8 @@ facedown_read_cb(unsigned long long timestamp, void *user_data) ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ + obj->accuracy = -1; obj->timestamp = timestamp; ecore_event_add(EEZE_SENSOR_EVENT_FACEDOWN, obj, NULL, NULL); sensor_stop(sensor_handle, eeze_to_tizen(EEZE_SENSOR_TYPE_MOTION_FACEDOWN)); @@ -478,11 +517,18 @@ doubletap_read_cb(unsigned long long timestamp, void *user_data) ERR("No matching sensor object found in list."); return; } + /* We have to set this ourselves because we don't get it for this type */ + obj->accuracy = -1; obj->timestamp = timestamp; ecore_event_add(EEZE_SENSOR_EVENT_DOUBLETAP, obj, NULL, NULL); sensor_stop(sensor_handle, eeze_to_tizen(EEZE_SENSOR_TYPE_MOTION_DOUBLETAP)); } +/* Synchronous read function for sensor data. It uses the blocking calls to read + * out the data and returns after it finishes the readout. Be aware that this + * might take quite some time depending on the sensor and how it is connected to + * the system. Normally it is better to use the asynchronous reading functions. + */ Eina_Bool eeze_sensor_tizen_read(Eeze_Sensor_Type sensor_type, Eeze_Sensor_Obj *lobj) { @@ -495,6 +541,9 @@ eeze_sensor_tizen_read(Eeze_Sensor_Type sensor_type, Eeze_Sensor_Obj *lobj) type = eeze_to_tizen(sensor_type); + /* Don't attempt to do anything if the sensor is not available on the system + * we are running on. + */ sensor_is_supported(type, &supported); if (!supported) { @@ -550,6 +599,7 @@ eeze_sensor_tizen_read(Eeze_Sensor_Type sensor_type, Eeze_Sensor_Obj *lobj) case SENSOR_LIGHT: sensor_light_read_data(sensor_handle, &lux); + /* As we do not get any accuracy value from the system we go with -1 */ obj->accuracy = -1; obj->data[0] = lux; obj->timestamp = 0; @@ -557,6 +607,7 @@ eeze_sensor_tizen_read(Eeze_Sensor_Type sensor_type, Eeze_Sensor_Obj *lobj) case SENSOR_PROXIMITY: sensor_proximity_read_data(sensor_handle, &distance); + /* As we do not get any accuracy value from the system we go with -1 */ obj->accuracy = -1; obj->data[0] = distance; obj->timestamp = 0; @@ -632,6 +683,12 @@ eeze_sensor_tizen_cb_set(Eeze_Sensor *handle, Eeze_Sensor_Type sensor_type, void } #endif +/* For the asynchronous reads we only start the sensor her and trigger the + * readout. The callbacks above are actually taking care about putting the data + * into the matching sensor objects and informing all subscribers with an ecore + * event. The public API function does actually return right away with the cached + * data. This is handled in the core and not in the different modules though. + */ Eina_Bool eeze_sensor_tizen_async_read(Eeze_Sensor_Type sensor_type, void *user_data) { @@ -694,6 +751,10 @@ eeze_sensor_tizen_async_read(Eeze_Sensor_Type sensor_type, void *user_data) return EINA_TRUE; } +/* Go through all potential Tizen sensor and test if they are available on the + * system we are running on. If yes, create a matching sensor object and put it + * the list of available sensor for the core. + */ static void eeze_sensor_tizen_sensors_find(void) { @@ -713,6 +774,7 @@ eeze_sensor_tizen_sensors_find(void) } } +/* Cleanup when getting the shutdown callback from core */ Eina_Bool eeze_sensor_tizen_shutdown(void) { @@ -729,10 +791,12 @@ eeze_sensor_tizen_shutdown(void) ERR("Failing to destroy sensor handle."); return EINA_FALSE; } - return EINA_TRUE; } +/* Callback from core once we registered as a module. Create the Tizen sensor + * handle and find all available sensors. + */ Eina_Bool eeze_sensor_tizen_init(void) { @@ -754,6 +818,10 @@ eeze_sensor_tizen_init(void) return EINA_TRUE; } +/* This function gets called when the module is loaded from the disk. Its the + * entry point to anything in this module. After setting ourself up we register + * into the core of eeze sensor to make our functionality available. + */ Eina_Bool sensor_tizen_init(void) { @@ -774,10 +842,12 @@ sensor_tizen_init(void) ERR("Failed to register tizen module"); return EINA_FALSE; } - return EINA_TRUE; } +/* Cleanup when the module gets unloaded. Unregister ourself from the core to + * avoid calls into a not loaded module. + */ void sensor_tizen_shutdown(void) {