From 54959ad476c391d34d64730e6e2c67d5cb175e50 Mon Sep 17 00:00:00 2001 From: Mike Blumenkrantz Date: Sat, 22 May 2010 21:44:26 +0000 Subject: [PATCH] dox overhaul, should be easier to navigate now SVN revision: 49147 --- legacy/eeze/src/lib/Eeze.h | 173 +++++++++++------- legacy/eeze/src/lib/Makefile.am | 2 +- legacy/eeze/src/lib/eeze_main.c | 32 ++++ legacy/eeze/src/lib/eeze_udev_find.c | 24 ++- legacy/eeze/src/lib/eeze_udev_private.c | 6 +- .../lib/{eeze_udev.c => eeze_udev_syspath.c} | 148 ++++++--------- legacy/eeze/src/lib/eeze_udev_walk.c | 12 ++ legacy/eeze/src/lib/eeze_udev_watch.c | 16 +- 8 files changed, 240 insertions(+), 173 deletions(-) rename legacy/eeze/src/lib/{eeze_udev.c => eeze_udev_syspath.c} (87%) diff --git a/legacy/eeze/src/lib/Eeze.h b/legacy/eeze/src/lib/Eeze.h index 4e7f7d7501..e1d9182699 100644 --- a/legacy/eeze/src/lib/Eeze.h +++ b/legacy/eeze/src/lib/Eeze.h @@ -21,94 +21,139 @@ #endif /** - * @defgroup Subsystem_Types Subsystem_Types - * - * ac97 - * acpi - * bdi - * block - * bsg - * dmi - * graphics - * hid - * hwmon - * i2c - * input - * mem - * misc - * net - * pci - * pci_bus - * pci_express - * platform - * pnp - * rtc - * scsi - * scsi_device - * scsi_disk - * scsi_generic - * scsi_host - * serio - * sound - * thermal - * tty - * usb - * usb_device - * vc - * vtconsole + * @file Eeze.h + * @brief Easy device manipulation. + * + * This header provides Eeze device handling functions. Included are + * types and defines for accessing udev, mounting devices, and others. + */ + +/** + * @defgroup subsystems Subsystems + * @brief These are the device subsystems of udev. + * + * - ac97 + * - acpi + * - bdi + * - block + * - bsg + * - dmi + * - graphics + * - hid + * - hwmon + * - i2c + * - input + * - mem + * - misc + * - net + * - pci + * - pci_bus + * - pci_express + * - platform + * - pnp + * - rtc + * - scsi + * - scsi_device + * - scsi_disk + * - scsi_generic + * - scsi_host + * - serio + * - sound + * - thermal + * - tty + * - usb + * - usb_device + * - vc + * - vtconsole * * @ingroup udev */ /** - * @defgroup Device_Types Device_Types + * @defgroup devices Device_Types + * @brief These are the devtypes of udev. * - * atapi - * audio - * block - * cd - * char - * disk - * floppy - * generic - * hid - * hub - * media - * optical - * printer - * rbc - * scsi - * storage - * tape - * video + * - atapi + * - audio + * - block + * - cd + * - char + * - disk + * - floppy + * - generic + * - hid + * - hub + * - media + * - optical + * - printer + * - rbc + * - scsi + * - storage + * - tape + * - video * * @ingroup udev */ -/*bitmasks for watch events*/ -#define EEZE_UDEV_EVENT_NONE 0x0000 -#define EEZE_UDEV_EVENT_ADD 0x0001 -#define EEZE_UDEV_EVENT_REMOVE 0x0002 -#define EEZE_UDEV_EVENT_CHANGE 0x0004 -#define EEZE_UDEV_EVENT_ONLINE 0x0008 -#define EEZE_UDEV_EVENT_OFFLINE 0x0010 +/** + * @defgroup event EEZE_UDEV_EVENT + * @brief These are event types used in udev functions. + * @ingroup udev + * + * @{ + */ +/** - No event specified */ +#define EEZE_UDEV_EVENT_NONE 0x0000 +/** - Device added */ +#define EEZE_UDEV_EVENT_ADD 0x0001 +/** - Device removed */ +#define EEZE_UDEV_EVENT_REMOVE 0x0002 +/** - Device changed */ +#define EEZE_UDEV_EVENT_CHANGE 0x0004 +/** - Device has come online */ +#define EEZE_UDEV_EVENT_ONLINE 0x0008 +/** - Device has gone offline */ +#define EEZE_UDEV_EVENT_OFFLINE 0x0010 +/** @} */ + +/** + * @defgroup type Eeze_Udev_Type + * @brief Convenience types to simplify udev access. + * + * These types allow easy access to certain udev device types. They + * may only be used in specified functions. + * + * @ingroup udev + * @{ + */ /*FIXME: these probably need to be bitmasks with categories*/ typedef enum -{ +{ /** - No type */ EEZE_UDEV_TYPE_NONE, + /** - Keyboard device */ EEZE_UDEV_TYPE_KEYBOARD, + /** - Mouse device */ EEZE_UDEV_TYPE_MOUSE, + /** - Touchpad device */ EEZE_UDEV_TYPE_TOUCHPAD, + /** - Mountable drive */ EEZE_UDEV_TYPE_DRIVE_MOUNTABLE, + /** - Internal drive */ EEZE_UDEV_TYPE_DRIVE_INTERNAL, + /** - Removable drive */ EEZE_UDEV_TYPE_DRIVE_REMOVABLE, + /** - cd drive */ EEZE_UDEV_TYPE_DRIVE_CDROM, + /** - AC adapter */ EEZE_UDEV_TYPE_POWER_AC, + /** - Battery */ EEZE_UDEV_TYPE_POWER_BAT, + /** - Temperature sensor */ EEZE_UDEV_TYPE_IS_IT_HOT_OR_IS_IT_COLD_SENSOR /* EEZE_UDEV_TYPE_ANDROID */ } Eeze_Udev_Type; +/**@}*/ struct Eeze_Udev_Watch; typedef struct Eeze_Udev_Watch Eeze_Udev_Watch; @@ -126,6 +171,7 @@ extern "C" { EAPI Eina_List *eeze_udev_find_by_type(const Eeze_Udev_Type type, const char *name); EAPI Eina_List *eeze_udev_find_by_filter(const char *subsystem, const char *type, const char *name); + EAPI const char *eeze_udev_devpath_get_syspath(const char *devpath); EAPI const char *eeze_udev_syspath_get_parent(const char *syspath); EAPI Eina_List *eeze_udev_syspath_get_parents(const char *syspath); EAPI const char *eeze_udev_syspath_get_devpath(const char *syspath); @@ -133,9 +179,6 @@ extern "C" { EAPI const char *eeze_udev_syspath_get_property(const char *syspath, const char *property); EAPI const char *eeze_udev_syspath_get_sysattr(const char *syspath, const char *sysattr); - EAPI const char *eeze_udev_devpath_get_syspath(const char *devpath); - EAPI const char *eeze_udev_devpath_get_subsystem(const char *devpath); - EAPI Eina_Bool eeze_udev_syspath_is_mouse(const char *syspath); EAPI Eina_Bool eeze_udev_syspath_is_kbd(const char *syspath); EAPI Eina_Bool eeze_udev_syspath_is_touchpad(const char *syspath); diff --git a/legacy/eeze/src/lib/Makefile.am b/legacy/eeze/src/lib/Makefile.am index 5607e214c4..dfda52a6c6 100644 --- a/legacy/eeze/src/lib/Makefile.am +++ b/legacy/eeze/src/lib/Makefile.am @@ -6,7 +6,7 @@ lib_LTLIBRARIES = libeeze.la include_HEADERS = Eeze.h libeeze_la_SOURCES = \ -eeze_udev.c \ +eeze_udev_syspath.c \ eeze_udev_watch.c \ eeze_main.c \ eeze_udev_find.c \ diff --git a/legacy/eeze/src/lib/eeze_main.c b/legacy/eeze/src/lib/eeze_main.c index b9628ade7a..2b196cd41a 100644 --- a/legacy/eeze/src/lib/eeze_main.c +++ b/legacy/eeze/src/lib/eeze_main.c @@ -6,11 +6,34 @@ #include "eeze_private.h" #include "eeze_udev_private.h" +/** + * @defgroup udev udev + * + * These are functions which interact directly with udev. + */ + _udev *udev; int _eeze_log_dom = -1; int _eeze_init_count = 0; + +/** + * @defgroup main main + * + * These are general eeze functions which include init and shutdown. + */ + + +/** + * Initialize the eeze library. + * @return The number of times the function has been called, or -1 on failure. + * + * This function should be called prior to using any eeze functions, and MUST + * be called prior to using any udev functions to avoid a segv. + * + * @ingroup main + */ EAPI int eeze_init(void) { @@ -43,6 +66,15 @@ fail: return _eeze_init_count; } +/** + * Shut down the eeze library. + * @return The number of times the eeze_init has been called, or -1 when + * all occurrences of eeze have been shut down. + * + * This function should be called when no further eeze functions will be called. + * + * @ingroup main + */ EAPI int eeze_shutdown(void) { diff --git a/legacy/eeze/src/lib/eeze_udev_find.c b/legacy/eeze/src/lib/eeze_udev_find.c index e2b4441bae..5b70f6815e 100644 --- a/legacy/eeze/src/lib/eeze_udev_find.c +++ b/legacy/eeze/src/lib/eeze_udev_find.c @@ -8,6 +8,14 @@ extern _udev *udev; +/** + * @defgroup find Find + * + * These are functions which find/supplement lists of devices. + * + * @ingroup udev + */ + /** * Returns a list of all syspaths that are (or should be) the same * device as the device pointed at by @p syspath. @@ -15,7 +23,7 @@ extern _udev *udev; * @param syspath The syspath of the device to find matches for * @return All devices which are the same as the one passed * - * @ingroup udev + * @ingroup find */ EAPI Eina_List * eeze_udev_find_similar_from_syspath(const char *syspath) @@ -93,7 +101,7 @@ eeze_udev_find_similar_from_syspath(const char *syspath) * This function will update @p list to include all devices matching * devices with syspaths currently stored in @p list. * - * @ingroup udev + * @ingroup find */ EAPI void eeze_udev_find_unlisted_similar(Eina_List * list) @@ -153,15 +161,15 @@ eeze_udev_find_unlisted_similar(Eina_List * list) } /** - * Find devices using a EEZE_UDEV_TYPE_* and/or a name. + * Find devices using an @ref type and/or a name. * - * @param type A Eeze_Udev_Type or 0 + * @param type An @ref Eeze_Udev_Type or 0 * @param name A filter for the device name or NULL - * @return A Eina_List* of matched devices or NULL on failure + * @return An Eina_List of matched devices or NULL on failure * * Return a list of syspaths (/sys/$syspath) for matching udev devices. * - * @ingroup udev + * @ingroup find */ EAPI Eina_List * eeze_udev_find_by_type(const Eeze_Udev_Type etype, const char *name) @@ -311,7 +319,7 @@ out: * Return a list of syspaths (/sys/$syspath) for matching udev devices. * Requires at least one filter. * - * @ingroup udev + * @ingroup find */ EAPI Eina_List * eeze_udev_find_by_filter(const char *subsystem, const char *type, @@ -361,6 +369,8 @@ out: * @param value Optional: the value that the attribute should have * * @return A list of the devices found with the attribute + * + * @ingroup find */ EAPI Eina_List * eeze_udev_find_by_sysattr(const char *sysattr, const char *value) diff --git a/legacy/eeze/src/lib/eeze_udev_private.c b/legacy/eeze/src/lib/eeze_udev_private.c index 84ac33d7c0..15e45d005b 100644 --- a/legacy/eeze/src/lib/eeze_udev_private.c +++ b/legacy/eeze/src/lib/eeze_udev_private.c @@ -8,7 +8,7 @@ extern _udev *udev; -/** +/* * copies a device */ _udev_device * @@ -22,7 +22,7 @@ _copy_device(_udev_device * device) return udev_device_new_from_syspath(udev, syspath); } -/** +/* * private function to simulate udevadm info -a * walks up the device tree checking each node for sysattr * with value $value @@ -74,7 +74,7 @@ _walk_parents_get_attr(_udev_device * device, const char *sysattr) return NULL; } -/** +/* * check a list for all parents of a device, * stringshare adding all devices that are not in the list */ diff --git a/legacy/eeze/src/lib/eeze_udev.c b/legacy/eeze/src/lib/eeze_udev_syspath.c similarity index 87% rename from legacy/eeze/src/lib/eeze_udev.c rename to legacy/eeze/src/lib/eeze_udev_syspath.c index 7d327cc0f5..f5d93c5bae 100644 --- a/legacy/eeze/src/lib/eeze_udev.c +++ b/legacy/eeze/src/lib/eeze_udev_syspath.c @@ -9,9 +9,12 @@ extern _udev *udev; /** - * @defgroup udev udev + * @defgroup syspath Syspath * - * These are functions which interact directly with udev. + * These are functions which interact with the syspath (/sys/$PATH) of + * a device. + * + * @ingroup udev */ /** @@ -22,7 +25,7 @@ extern _udev *udev; * * Return a syspath (/sys/$syspath) for the parent device. * - * @ingroup udev + * @ingroup syspath */ EAPI const char * eeze_udev_syspath_get_parent(const char *syspath) @@ -54,7 +57,7 @@ eeze_udev_syspath_get_parent(const char *syspath) * @param syspath The device to find parents of * @return A list of the parent devices of @p syspath * - * @ingroup udev + * @ingroup syspath */ EAPI Eina_List * eeze_udev_syspath_get_parents(const char *syspath) @@ -96,7 +99,7 @@ eeze_udev_syspath_get_parents(const char *syspath) * * Takes /sys/$PATH and turns it into the corresponding "/dev/x/y". * - * @ingroup udev + * @ingroup syspath */ EAPI const char * eeze_udev_syspath_get_devpath(const char *syspath) @@ -134,7 +137,7 @@ eeze_udev_syspath_get_devpath(const char *syspath) * Takes /sys/$PATH and returns the corresponding device subsystem, * such as "input" for keyboards/mice. * - * @ingroup udev + * @ingroup syspath */ EAPI const char * eeze_udev_syspath_get_subsystem(const char *syspath) @@ -167,7 +170,7 @@ eeze_udev_syspath_get_subsystem(const char *syspath) * @param property The property to get; full list of these is a FIXME * @return A const char* with the property or NULL on failure * - * @ingroup udev + * @ingroup syspath */ EAPI const char * eeze_udev_syspath_get_property(const char *syspath, const char *property) @@ -202,7 +205,7 @@ eeze_udev_syspath_get_property(const char *syspath, const char *property) * @param sysattr The sysattr to get; full list of these is a FIXME * @return A const char* with the sysattr or NULL on failure * - * @ingroup udev + * @ingroup syspath */ EAPI const char * eeze_udev_syspath_get_sysattr(const char *syspath, const char *sysattr) @@ -230,95 +233,13 @@ eeze_udev_syspath_get_sysattr(const char *syspath, const char *sysattr) return value; } -/** - * Get the syspath of a device from the /dev/ path. - * - * @param devpath The /dev/ path of the device - * @return A const char* which corresponds to the /sys/ path of the device or NULL on failure - * - * Takes "/dev/path" and returns the corresponding /sys/ path (without the "/sys/") - * - * @ingroup udev - */ -EAPI const char * -eeze_udev_devpath_get_syspath(const char *devpath) -{ - _udev_enumerate *en; - _udev_list_entry *devs, *cur; - _udev_device *device; - const char *name, *ret = NULL; - - if (!devpath) - return NULL; - - en = udev_enumerate_new((udev)); - - if (!en) - return NULL; - - udev_enumerate_add_match_property(en, "DEVNAME", devpath); - udev_enumerate_scan_devices(en); - devs = udev_enumerate_get_list_entry(en); - udev_list_entry_foreach(cur, devs) - { - name = udev_list_entry_get_name(cur); - device = udev_device_new_from_syspath(udev, name); - ret = eina_stringshare_add(udev_device_get_sysname(device)); - udev_device_unref(device); - break; /*just in case there's more than one somehow */ - } - udev_enumerate_unref(en); - return ret; -} - -/** - * Get the subsystem of a device from the /dev/ path. - * - * @param devpath The /dev/ path of the device - * @return A const char* with the subsystem of the device or NULL on failure - * - * Takes "/dev/path" and returns the subsystem of the device. - * - * @ingroup udev - */ -EAPI const char * -eeze_udev_devpath_get_subsystem(const char *devpath) -{ - _udev_enumerate *en; - _udev_list_entry *devs, *cur; - _udev_device *device; - const char *name, *ret = NULL; - - if (!devpath) - return NULL; - - en = udev_enumerate_new((udev)); - - if (!en) - return NULL; - - udev_enumerate_add_match_property(en, "DEVNAME", devpath); - udev_enumerate_scan_devices(en); - devs = udev_enumerate_get_list_entry(en); - udev_list_entry_foreach(cur, devs) - { - name = udev_list_entry_get_name(cur); - device = udev_device_new_from_syspath(udev, name); - ret = eina_stringshare_add(udev_device_get_subsystem(device)); - udev_device_unref(device); - break; /*just in case there's more than one somehow */ - } - udev_enumerate_unref(en); - return ret; -} - /** * Checks whether the device is a mouse. * * @param syspath The /sys/ path with or without the /sys/ * @return If true, the device is a mouse * - * @ingroup udev + * @ingroup syspath */ EAPI Eina_Bool eeze_udev_syspath_is_mouse(const char *syspath) @@ -367,7 +288,7 @@ eeze_udev_syspath_is_mouse(const char *syspath) * @param syspath The /sys/ path with or without the /sys/ * @return If true, the device is a keyboard * - * @ingroup udev + * @ingroup syspath */ EAPI Eina_Bool eeze_udev_syspath_is_kbd(const char *syspath) @@ -416,7 +337,7 @@ eeze_udev_syspath_is_kbd(const char *syspath) * @param syspath The /sys/ path with or without the /sys/ * @return If true, the device is a touchpad * - * @ingroup udev + * @ingroup syspath */ EAPI Eina_Bool eeze_udev_syspath_is_touchpad(const char *syspath) @@ -449,3 +370,44 @@ eeze_udev_syspath_is_touchpad(const char *syspath) eina_strbuf_free(sbuf); return touchpad; } + +/** + * Get the syspath of a device from the /dev/ path. + * + * @param devpath The /dev/ path of the device + * @return A const char* which corresponds to the /sys/ path of the device or NULL on failure + * + * Takes "/dev/path" and returns the corresponding /sys/ path (without the "/sys/") + * + * @ingroup syspath + */ +EAPI const char * +eeze_udev_devpath_get_syspath(const char *devpath) +{ + _udev_enumerate *en; + _udev_list_entry *devs, *cur; + _udev_device *device; + const char *name, *ret = NULL; + + if (!devpath) + return NULL; + + en = udev_enumerate_new((udev)); + + if (!en) + return NULL; + + udev_enumerate_add_match_property(en, "DEVNAME", devpath); + udev_enumerate_scan_devices(en); + devs = udev_enumerate_get_list_entry(en); + udev_list_entry_foreach(cur, devs) + { + name = udev_list_entry_get_name(cur); + device = udev_device_new_from_syspath(udev, name); + ret = eina_stringshare_add(udev_device_get_sysname(device)); + udev_device_unref(device); + break; /*just in case there's more than one somehow */ + } + udev_enumerate_unref(en); + return ret; +} diff --git a/legacy/eeze/src/lib/eeze_udev_walk.c b/legacy/eeze/src/lib/eeze_udev_walk.c index 16a636212e..be2b202bba 100644 --- a/legacy/eeze/src/lib/eeze_udev_walk.c +++ b/legacy/eeze/src/lib/eeze_udev_walk.c @@ -8,6 +8,14 @@ extern _udev *udev; +/** + * @defgroup walks Walks + * + * These are functions which walk up the device chain. + * + * @ingroup udev + */ + /** * Walks up the device chain starting at @p syspath, * checking each device for @p sysattr with (optional) @p value. @@ -17,6 +25,8 @@ extern _udev *udev; * @param value OPTIONAL: The value that @p sysattr should have, or NULL * * @return If the sysattr (with value) is found, returns TRUE. Else, false. + * + * @ingroup walks */ EAPI Eina_Bool eeze_udev_walk_check_sysattr(const char *syspath, const char *sysattr, @@ -73,6 +83,8 @@ eeze_udev_walk_check_sysattr(const char *syspath, const char *sysattr, * @param sysattr The attribute to find * * @return The value of @p sysattr if found, or NULL + * + * @ingroup walks */ EAPI const char * eeze_udev_walk_get_sysattr(const char *syspath, const char *sysattr) diff --git a/legacy/eeze/src/lib/eeze_udev_watch.c b/legacy/eeze/src/lib/eeze_udev_watch.c index 28ce8a4956..344fd705d8 100644 --- a/legacy/eeze/src/lib/eeze_udev_watch.c +++ b/legacy/eeze/src/lib/eeze_udev_watch.c @@ -27,6 +27,14 @@ struct _store_data Eeze_Udev_Watch *watch; }; +/** + * @defgroup watch Watch + * + * These are functions which monitor udev for events. + * + * @ingroup udev + */ + /* private function to further filter watch results based on Eeze_Udev_Type * specified; helpful for new udev versions, but absolutely required for * old udev, which does not implement filtering in device monitors. @@ -265,15 +273,15 @@ error: /** * Add a watch for a device type * - * @param type The Eeze_Udev_Type to watch - * @param event The events to watch; an OR list of EEZE_UDEV_EVENTs (ie (EEZE_UDEV_EVENT_ADD | EEZE_UDEV_EVENT_REMOVE)), or 0 for all events + * @param type The @ref Eeze_Udev_Type to watch + * @param event The events to watch; an OR list of @ref event (ie (EEZE_UDEV_EVENT_ADD | EEZE_UDEV_EVENT_REMOVE)), or 0 for all events * @param func The function to call when the watch receives data; * must take (const char *device, const char *event_type, void *data, Eeze_Udev_Watch *watch) * @param user_data Data to pass to the callback function * * @return A watch struct for the watch type specified, or NULL on failure * - * @ingroup udev + * @ingroup watch */ EAPI Eeze_Udev_Watch * eeze_udev_watch_add(Eeze_Udev_Type type, int event, @@ -372,7 +380,7 @@ error: * * Deletes a watch, closing file descriptors and freeing related udev memory. * - * @ingroup udev + * @ingroup watch */ EAPI void * eeze_udev_watch_del(Eeze_Udev_Watch * watch)