hal/libhal libhal.c,1.48,1.49 libhal.h,1.26,1.27
David Zeuthen
david at freedesktop.org
Wed May 11 10:20:57 PDT 2005
Update of /cvs/hal/hal/libhal
In directory gabe:/tmp/cvs-serv11788/libhal
Modified Files:
libhal.c libhal.h
Log Message:
2005-05-11 David Zeuthen <davidz at redhat.com>
* libhal/libhal.[ch]: Patch from Rohan McGovern <rohan.pm at gmail.com>
to fix up Doxygen documentation. Thanks!
Index: libhal.c
===================================================================
RCS file: /cvs/hal/hal/libhal/libhal.c,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -d -r1.48 -r1.49
--- libhal.c 27 Apr 2005 18:53:39 -0000 1.48
+++ libhal.c 11 May 2005 17:20:55 -0000 1.49
@@ -69,7 +69,7 @@
/** Frees a NULL-terminated array of strings. If passed NULL, does nothing.
*
- * @param str_array The array to be freed
+ * @param str_array The array to be freed
*/
void
libhal_free_string_array (char **str_array)
@@ -144,7 +144,7 @@
/** Frees a nul-terminated string
[...1059 lines suppressed...]
{
unsigned int i;
@@ -3007,6 +3199,17 @@
return result;
}
+/** Emit a condition from a device
+ *
+ * @param ctx Context for connection to hald
+ * @param udi Unique Device Id
+ * @param condition_name User-readable name of condition
+ * @param condition_details User-readable details of condition
+ * @param error Pointer to an initialized dbus error object for
+ * returning errors or #NULL
+ * @return TRUE if condition successfully emitted,
+ * FALSE otherwise
+ */
dbus_bool_t libhal_device_emit_condition (LibHalContext *ctx,
const char *udi,
const char *condition_name,
Index: libhal.h
===================================================================
RCS file: /cvs/hal/hal/libhal/libhal.h,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -d -r1.26 -r1.27
--- libhal.h 8 Apr 2005 18:10:20 -0000 1.26
+++ libhal.h 11 May 2005 17:20:55 -0000 1.27
@@ -70,15 +70,17 @@
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
/** Type for function in application code that integrates a DBusConnection
- * object into it's own mainloop.
+ * object into its own mainloop.
*
- * @param udi Unique Device Id
+ * @param ctx Context for connection to hald
+ * @param dbus_connection DBus connection to use in ctx
*/
typedef void (*LibHalIntegrateDBusIntoMainLoop) (LibHalContext *ctx,
DBusConnection *dbus_connection);
/** Type for callback when a device is added.
*
+ * @param ctx Context for connection to hald
* @param udi Unique Device Id
*/
typedef void (*LibHalDeviceAdded) (LibHalContext *ctx,
@@ -86,6 +88,7 @@
/** Type for callback when a device is removed.
*
+ * @param ctx Context for connection to hald
* @param udi Unique Device Id
*/
typedef void (*LibHalDeviceRemoved) (LibHalContext *ctx,
@@ -93,6 +96,7 @@
/** Type for callback when a device gains a new capability
*
+ * @param ctx Context for connection to hald
* @param udi Unique Device Id
* @param capability Capability of the device
*/
@@ -102,6 +106,7 @@
/** Type for callback when a device loses a capability
*
+ * @param ctx Context for connection to hald
* @param udi Unique Device Id
* @param capability Capability of the device
*/
@@ -111,10 +116,11 @@
/** Type for callback when a property of a device changes.
*
+ * @param ctx Context for connection to hald
* @param udi Unique Device Id
* @param key Name of the property that has changed
- * @param is_removed Property removed
- * @param is_added Property added
+ * @param is_removed Whether or not property was removed
+ * @param is_added Whether or not property was added
*/
typedef void (*LibHalDevicePropertyModified) (LibHalContext *ctx,
const char *udi,
@@ -122,14 +128,14 @@
dbus_bool_t is_removed,
dbus_bool_t is_added);
-/** Type for callback when a non-continuos condition occurs on a device
+/** Type for callback when a non-continuous condition occurs on a device
*
+ * @param ctx Context for connection to hald
* @param udi Unique Device Id
* @param condition_name Name of the condition, e.g.
* ProcessorOverheating. Consult the HAL spec
* for possible conditions
- * @param message D-BUS message with variable parameters
- * depending on condition
+ * @param condition_detail User-readable details of condition
*/
typedef void (*LibHalDeviceCondition) (LibHalContext *ctx,
const char *udi,
@@ -137,128 +143,172 @@
const char *condition_detail);
+/* Create a new context for a connection with hald */
LibHalContext *libhal_ctx_new (void);
+
+/* Enable or disable caching */
dbus_bool_t libhal_ctx_set_cache (LibHalContext *ctx, dbus_bool_t use_cache);
+
+/* Set DBus connection to use to talk to hald. */
dbus_bool_t libhal_ctx_set_dbus_connection (LibHalContext *ctx, DBusConnection *conn);
+
+/* Set user data for the context */
dbus_bool_t libhal_ctx_set_user_data (LibHalContext *ctx, void *user_data);
+
+/* Get user data for the context */
void* libhal_ctx_get_user_data (LibHalContext *ctx);
+
+/* Set the callback for when a device is added */
dbus_bool_t libhal_ctx_set_device_added (LibHalContext *ctx, LibHalDeviceAdded callback);
+
+/* Set the callback for when a device is removed */
dbus_bool_t libhal_ctx_set_device_removed (LibHalContext *ctx, LibHalDeviceRemoved callback);
+
+/* Set the callback for when a device gains a new capability */
dbus_bool_t libhal_ctx_set_device_new_capability (LibHalContext *ctx, LibHalDeviceNewCapability callback);
+
+/* Set the callback for when a device loses a capability */
dbus_bool_t libhal_ctx_set_device_lost_capability (LibHalContext *ctx, LibHalDeviceLostCapability callback);
+
+/* Set the callback for when a property is modified on a device */
dbus_bool_t libhal_ctx_set_device_property_modified (LibHalContext *ctx, LibHalDevicePropertyModified callback);
+
+/* Set the callback for when a device emits a condition */
dbus_bool_t libhal_ctx_set_device_condition (LibHalContext *ctx, LibHalDeviceCondition callback);
+
+/* Initialize the connection to hald */
dbus_bool_t libhal_ctx_init (LibHalContext *ctx, DBusError *error);
+
+/* Shut down a connection to hald */
dbus_bool_t libhal_ctx_shutdown (LibHalContext *ctx, DBusError *error);
+
+/* Free a LibHalContext resource */
dbus_bool_t libhal_ctx_free (LibHalContext *ctx);
+/* Create an already initialized connection to hald */
LibHalContext *libhal_ctx_init_direct (DBusError *error);
-
+/* Get all devices in the Global Device List (GDL). */
char **libhal_get_all_devices (LibHalContext *ctx, int *num_devices, DBusError *error);
+
+/* Determine if a device exists. */
dbus_bool_t libhal_device_exists (LibHalContext *ctx, const char *udi, DBusError *error);
+
+/* Print a device to stdout; useful for debugging. */
dbus_bool_t libhal_device_print (LibHalContext *ctx, const char *udi, DBusError *error);
+/* Determine if a property on a device exists. */
dbus_bool_t libhal_device_property_exists (LibHalContext *ctx,
const char *udi,
const char *key,
DBusError *error);
-
+/* Get the value of a property of type string. */
char *libhal_device_get_property_string (LibHalContext *ctx,
const char *udi,
const char *key,
DBusError *error);
+/* Get the value of a property of type signed integer. */
dbus_int32_t libhal_device_get_property_int (LibHalContext *ctx,
const char *udi,
const char *key,
DBusError *error);
+/* Get the value of a property of type unsigned integer. */
dbus_uint64_t libhal_device_get_property_uint64 (LibHalContext *ctx,
const char *udi,
const char *key,
DBusError *error);
+/* Get the value of a property of type double. */
double libhal_device_get_property_double (LibHalContext *ctx,
const char *udi,
const char *key,
DBusError *error);
+/* Get the value of a property of type bool. */
dbus_bool_t libhal_device_get_property_bool (LibHalContext *ctx,
const char *udi,
const char *key,
DBusError *error);
+/* Get the value of a property of type string list. */
char **libhal_device_get_property_strlist (LibHalContext *ctx,
const char *udi,
const char *key,
DBusError *error);
-
-
+/* Set a property of type string. */
dbus_bool_t libhal_device_set_property_string (LibHalContext *ctx,
const char *udi,
const char *key,
const char *value,
DBusError *error);
+/* Set a property of type signed integer. */
dbus_bool_t libhal_device_set_property_int (LibHalContext *ctx,
const char *udi,
const char *key,
dbus_int32_t value,
DBusError *error);
+/* Set a property of type unsigned integer. */
dbus_bool_t libhal_device_set_property_uint64 (LibHalContext *ctx,
const char *udi,
const char *key,
dbus_uint64_t value,
DBusError *error);
+/* Set a property of type double. */
dbus_bool_t libhal_device_set_property_double (LibHalContext *ctx,
const char *udi,
const char *key,
double value,
DBusError *error);
+/* Set a property of type bool. */
dbus_bool_t libhal_device_set_property_bool (LibHalContext *ctx,
const char *udi,
const char *key,
dbus_bool_t value,
DBusError *error);
-
+/* Append to a property of type strlist. */
dbus_bool_t libhal_device_property_strlist_append (LibHalContext *ctx,
const char *udi,
const char *key,
const char *value,
DBusError *error);
+/* Prepend to a property of type strlist. */
dbus_bool_t libhal_device_property_strlist_prepend (LibHalContext *ctx,
const char *udi,
const char *key,
const char *value,
DBusError *error);
+/* Remove a specified string from a property of type strlist. */
dbus_bool_t libhal_device_property_strlist_remove_index (LibHalContext *ctx,
const char *udi,
const char *key,
unsigned int index,
DBusError *error);
+/* Remove a specified string from a property of type strlist. */
dbus_bool_t libhal_device_property_strlist_remove (LibHalContext *ctx,
const char *udi,
const char *key,
const char *value,
DBusError *error);
-
-
+/* Remove a property. */
dbus_bool_t libhal_device_remove_property (LibHalContext *ctx,
const char *udi,
const char *key,
DBusError *error);
+/* Query a property type of a device. */
LibHalPropertyType libhal_device_get_property_type (LibHalContext *ctx,
const char *udi,
const char *key,
@@ -273,13 +323,15 @@
typedef struct LibHalPropertySet_s LibHalPropertySet;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
-
+/* Retrieve all the properties on a device. */
LibHalPropertySet *libhal_device_get_all_properties (LibHalContext *ctx,
const char *udi,
DBusError *error);
+/* Free a property set earlier obtained with libhal_device_get_all_properties(). */
void libhal_free_property_set (LibHalPropertySet *set);
+/* Get the number of properties in a property set. */
unsigned int libhal_property_set_get_num_elems (LibHalPropertySet *set);
/** Iterator for inspecting all properties */
@@ -295,87 +347,138 @@
typedef struct LibHalPropertySetIterator_s LibHalPropertySetIterator;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+/* Initialize a property set iterator. */
void libhal_psi_init (LibHalPropertySetIterator *iter, LibHalPropertySet *set);
+/* Determine whether there are more properties to iterate over */
dbus_bool_t libhal_psi_has_more (LibHalPropertySetIterator *iter);
+
+/* Advance iterator to next property. */
void libhal_psi_next (LibHalPropertySetIterator *iter);
+/* Get type of property. */
LibHalPropertyType libhal_psi_get_type (LibHalPropertySetIterator *iter);
+/* Get the key of a property. */
char *libhal_psi_get_key (LibHalPropertySetIterator *iter);
+/* Get the value of a property of type string. */
char *libhal_psi_get_string (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type signed integer. */
dbus_int32_t libhal_psi_get_int (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type unsigned integer. */
dbus_uint64_t libhal_psi_get_uint64 (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type double. */
double libhal_psi_get_double (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type bool. */
dbus_bool_t libhal_psi_get_bool (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type string list. */
char **libhal_psi_get_strlist (LibHalPropertySetIterator *iter);
+/* Get the length of an array of strings */
unsigned int libhal_string_array_length (char **str_array);
+/* Frees a NULL-terminated array of strings. If passed NULL, does nothing. */
void libhal_free_string_array (char **str_array);
-void libhal_free_string (char *str);
+/* Frees a nul-terminated string */
+void libhal_free_string (char *str);
+/* Create a new device object which will be hidden from applications
+ * until the CommitToGdl(), ie. libhal_agent_commit_to_gdl(), method is called.
+ */
char *libhal_agent_new_device (LibHalContext *ctx, DBusError *error);
+/* When a hidden device has been built using the NewDevice method, ie.
+ * libhal_agent_new_device(), and the org.freedesktop.Hal.Device interface
+ * this function will commit it to the global device list.
+ */
dbus_bool_t libhal_agent_commit_to_gdl (LibHalContext *ctx,
const char *temp_udi,
const char *udi,
DBusError *error);
+/* This method can be invoked when a device is removed. The HAL daemon
+ * will shut down the device. Note that the device may still be in the device
+ * list if the Persistent property is set to true.
+ */
dbus_bool_t libhal_agent_remove_device (LibHalContext *ctx,
const char *udi,
DBusError *error);
+/* Merge properties from one device to another. */
dbus_bool_t libhal_agent_merge_properties (LibHalContext *ctx,
const char *target_udi,
const char *source_udi,
DBusError *error);
+/* Check a set of properties for two devices matches. */
dbus_bool_t libhal_agent_device_matches (LibHalContext *ctx,
const char *udi1,
const char *udi2,
const char *property_namespace,
DBusError *error);
+/* Find a device in the GDL where a single string property matches a
+ * given value.
+ */
char **libhal_manager_find_device_string_match (LibHalContext *ctx,
const char *key,
const char *value,
int *num_devices,
DBusError *error);
-
+/* Assign a capability to a device. */
dbus_bool_t libhal_device_add_capability (LibHalContext *ctx,
const char *udi,
const char *capability,
DBusError *error);
+/* Check if a device has a capability. The result is undefined if the
+ * device doesn't exist.
+ */
dbus_bool_t libhal_device_query_capability (LibHalContext *ctx,
const char *udi,
const char *capability,
DBusError *error);
+/* Find devices with a given capability. */
char **libhal_find_device_by_capability (LibHalContext *ctx,
const char *capability,
int *num_devices,
DBusError *error);
+/* Watch all devices, ie. the device_property_changed callback is
+ * invoked when the properties on any device changes.
+ */
dbus_bool_t libhal_device_property_watch_all (LibHalContext *ctx,
DBusError *error);
+
+/* Add a watch on a device, so the device_property_changed callback is
+ * invoked when the properties on the given device changes.
+ */
dbus_bool_t libhal_device_add_property_watch (LibHalContext *ctx,
const char *udi,
DBusError *error);
+
+/* Remove a watch on a device */
dbus_bool_t libhal_device_remove_property_watch (LibHalContext *ctx,
const char *udi,
DBusError *error);
+/* Take an advisory lock on the device. */
dbus_bool_t libhal_device_lock (LibHalContext *ctx,
const char *udi,
const char *reason_to_lock,
char **reason_why_locked,
DBusError *error);
+/* Release an advisory lock on the device. */
dbus_bool_t libhal_device_unlock (LibHalContext *ctx,
const char *udi,
DBusError *error);
@@ -388,6 +491,7 @@
const char *udi,
DBusError *error);
+/* Emit a condition from a device */
dbus_bool_t libhal_device_emit_condition (LibHalContext *ctx,
const char *udi,
const char *condition_name,
More information about the hal-commit
mailing list