Main Page | Modules | Data Structures | Directories | File List | Data Fields | Related Pages

HAL convenience library

A convenience library used to communicate with the HAL daemon using D-BUS. More...

Data Structures

struct  LibHalPropertySet_s
 Represents a set of properties. More...
struct  LibHalProperty_s
 Device property class. More...
struct  LibHalContext_s
 Context for connection to the HAL daemon. More...
struct  LibHalPropertySetIterator_s
 Iterator for inspecting all properties. More...

Typedefs

typedef void(* LibHalIntegrateDBusIntoMainLoop )(LibHalContext *ctx, DBusConnection *dbus_connection)
 Type for function in application code that integrates a DBusConnection object into its own mainloop.
typedef void(* LibHalDeviceAdded )(LibHalContext *ctx, const char *udi)
 Type for callback when a device is added.
typedef void(* LibHalDeviceRemoved )(LibHalContext *ctx, const char *udi)
 Type for callback when a device is removed.
typedef void(* LibHalDeviceNewCapability )(LibHalContext *ctx, const char *udi, const char *capability)
 Type for callback when a device gains a new capability.
typedef void(* LibHalDeviceLostCapability )(LibHalContext *ctx, const char *udi, const char *capability)
 Type for callback when a device loses a capability.
typedef void(* LibHalDevicePropertyModified )(LibHalContext *ctx, const char *udi, const char *key, dbus_bool_t is_removed, dbus_bool_t is_added)
 Type for callback when a property of a device changes.
typedef void(* LibHalDeviceCondition )(LibHalContext *ctx, const char *udi, const char *condition_name, const char *condition_detail)
 Type for callback when a non-continuous condition occurs on a device.

Enumerations

enum  LibHalPropertyType {
  LIBHAL_PROPERTY_TYPE_INVALID = DBUS_TYPE_INVALID, LIBHAL_PROPERTY_TYPE_INT32 = DBUS_TYPE_INT32, LIBHAL_PROPERTY_TYPE_UINT64 = DBUS_TYPE_UINT64, LIBHAL_PROPERTY_TYPE_DOUBLE = DBUS_TYPE_DOUBLE,
  LIBHAL_PROPERTY_TYPE_BOOLEAN = DBUS_TYPE_BOOLEAN, LIBHAL_PROPERTY_TYPE_STRING = DBUS_TYPE_STRING, LIBHAL_PROPERTY_TYPE_STRLIST = ((int) (DBUS_TYPE_STRING<<8)+('l'))
}
 Possible types for properties on hal device objects. More...

Functions

void libhal_free_string_array (char **str_array)
 Frees a NULL-terminated array of strings.
static char ** libhal_get_string_array_from_iter (DBusMessageIter *iter, int *num_elements)
 Creates a NULL terminated array of strings from a dbus message iterator.
void libhal_free_string (char *str)
 Frees a nul-terminated string.
dbus_bool_t libhal_ctx_set_user_data (LibHalContext *ctx, void *user_data)
 Set user data for the context.
void * libhal_ctx_get_user_data (LibHalContext *ctx)
 Get user data for the context.
static dbus_bool_t libhal_property_fill_value_from_variant (LibHalProperty *p, DBusMessageIter *var_iter)
 Fills in the value for the LibHalProperty given a variant iterator.
LibHalPropertySet * libhal_device_get_all_properties (LibHalContext *ctx, const char *udi, DBusError *error)
 Retrieve all the properties on a device.
void libhal_free_property_set (LibHalPropertySet *set)
 Free a property set earlier obtained with libhal_device_get_all_properties().
unsigned int libhal_property_set_get_num_elems (LibHalPropertySet *set)
 Get the number of properties in a property set.
void libhal_psi_init (LibHalPropertySetIterator *iter, LibHalPropertySet *set)
 Initialize a property set iterator.
dbus_bool_t libhal_psi_has_more (LibHalPropertySetIterator *iter)
 Determine whether there are more properties to iterate over.
void libhal_psi_next (LibHalPropertySetIterator *iter)
 Advance iterator to next property.
LibHalPropertyType libhal_psi_get_type (LibHalPropertySetIterator *iter)
 Get type of property.
char * libhal_psi_get_key (LibHalPropertySetIterator *iter)
 Get the key of a property.
char * libhal_psi_get_string (LibHalPropertySetIterator *iter)
 Get the value of a property of type string.
dbus_int32_t libhal_psi_get_int (LibHalPropertySetIterator *iter)
 Get the value of a property of type signed integer.
dbus_uint64_t libhal_psi_get_uint64 (LibHalPropertySetIterator *iter)
 Get the value of a property of type unsigned integer.
double libhal_psi_get_double (LibHalPropertySetIterator *iter)
 Get the value of a property of type double.
dbus_bool_t libhal_psi_get_bool (LibHalPropertySetIterator *iter)
 Get the value of a property of type bool.
char ** libhal_psi_get_strlist (LibHalPropertySetIterator *iter)
 Get the value of a property of type string list.
char ** libhal_get_all_devices (LibHalContext *ctx, int *num_devices, DBusError *error)
 Get all devices in the Global Device List (GDL).
LibHalPropertyType libhal_device_get_property_type (LibHalContext *ctx, const char *udi, const char *key, DBusError *error)
 Query a property type of a device.
char ** libhal_device_get_property_strlist (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_string (LibHalContext *ctx, const char *udi, const char *key, DBusError *error)
 Get the value of a property of type string.
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 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 signed integer.
double libhal_device_get_property_double (LibHalContext *ctx, const char *udi, const char *key, DBusError *error)
 Get the value of a property of type double.
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 bool.
static dbus_bool_t libhal_device_set_property_helper (LibHalContext *ctx, const char *udi, const char *key, int type, const char *str_value, dbus_int32_t int_value, dbus_uint64_t uint64_value, double double_value, dbus_bool_t bool_value, DBusError *error)
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 string.
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 signed 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 unsigned integer.
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 double.
dbus_bool_t libhal_device_set_property_bool (LibHalContext *ctx, const char *udi, const char *key, dbus_bool_t value, DBusError *error)
 Set a property of type bool.
dbus_bool_t libhal_device_remove_property (LibHalContext *ctx, const char *udi, const char *key, DBusError *error)
 Remove a property.
dbus_bool_t libhal_device_property_strlist_append (LibHalContext *ctx, const char *udi, const char *key, const char *value, DBusError *error)
 Append 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)
 Prepend to 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 specified string from a property of type strlist.
dbus_bool_t libhal_device_lock (LibHalContext *ctx, const char *udi, const char *reason_to_lock, char **reason_why_locked, DBusError *error)
 Take an advisory lock on the device.
dbus_bool_t libhal_device_unlock (LibHalContext *ctx, const char *udi, DBusError *error)
 Release an advisory lock on the device.
char * libhal_agent_new_device (LibHalContext *ctx, DBusError *error)
 Create a new device object which will be hidden from applications until the CommitToGdl(), ie.
dbus_bool_t libhal_agent_commit_to_gdl (LibHalContext *ctx, const char *temp_udi, const char *udi, DBusError *error)
 When a hidden device has been built using the NewDevice method, ie.
dbus_bool_t libhal_agent_remove_device (LibHalContext *ctx, const char *udi, DBusError *error)
 This method can be invoked when a device is removed.
dbus_bool_t libhal_device_exists (LibHalContext *ctx, const char *udi, DBusError *error)
 Determine if a device exists.
dbus_bool_t libhal_device_property_exists (LibHalContext *ctx, const char *udi, const char *key, DBusError *error)
 Determine if a property on a device exists.
dbus_bool_t libhal_agent_merge_properties (LibHalContext *ctx, const char *target_udi, const char *source_udi, DBusError *error)
 Merge properties from one device to another.
dbus_bool_t libhal_agent_device_matches (LibHalContext *ctx, const char *udi1, const char *udi2, const char *property_namespace, DBusError *error)
 Check a set of properties for two devices matches.
dbus_bool_t libhal_device_print (LibHalContext *ctx, const char *udi, DBusError *error)
 Print a device to stdout; useful for debugging.
char ** libhal_manager_find_device_string_match (LibHalContext *ctx, const char *key, const char *value, int *num_devices, DBusError *error)
 Find a device in the GDL where a single string property matches a given value.
dbus_bool_t libhal_device_add_capability (LibHalContext *ctx, const char *udi, const char *capability, DBusError *error)
 Assign a capability to a device.
dbus_bool_t libhal_device_query_capability (LibHalContext *ctx, const char *udi, const char *capability, DBusError *error)
 Check if a device has a capability.
char ** libhal_find_device_by_capability (LibHalContext *ctx, const char *capability, int *num_devices, DBusError *error)
 Find devices with a given capability.
dbus_bool_t libhal_device_property_watch_all (LibHalContext *ctx, DBusError *error)
 Watch all devices, ie.
dbus_bool_t libhal_device_add_property_watch (LibHalContext *ctx, const char *udi, 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_remove_property_watch (LibHalContext *ctx, const char *udi, DBusError *error)
 Remove a watch on a device.
LibHalContext * libhal_ctx_new (void)
 Create a new LibHalContext.
dbus_bool_t libhal_ctx_set_cache (LibHalContext *ctx, dbus_bool_t use_cache)
 Enable or disable caching.
dbus_bool_t libhal_ctx_set_dbus_connection (LibHalContext *ctx, DBusConnection *conn)
 Set DBus connection to use to talk to hald.
dbus_bool_t libhal_ctx_init (LibHalContext *ctx, DBusError *error)
 Initialize the connection to hald.
LibHalContext * libhal_ctx_init_direct (DBusError *error)
 Create an already initialized connection to hald.
dbus_bool_t libhal_ctx_shutdown (LibHalContext *ctx, DBusError *error)
 Shut down a connection to hald.
dbus_bool_t libhal_ctx_free (LibHalContext *ctx)
 Free a LibHalContext resource.
dbus_bool_t libhal_ctx_set_device_added (LibHalContext *ctx, LibHalDeviceAdded callback)
 Set the callback for when a device is added.
dbus_bool_t libhal_ctx_set_device_removed (LibHalContext *ctx, LibHalDeviceRemoved callback)
 Set the callback for when a device is removed.
dbus_bool_t libhal_ctx_set_device_new_capability (LibHalContext *ctx, LibHalDeviceNewCapability callback)
 Set the callback for when a device gains a new capability.
dbus_bool_t libhal_ctx_set_device_lost_capability (LibHalContext *ctx, LibHalDeviceLostCapability callback)
 Set the callback for when a device loses a capability.
dbus_bool_t libhal_ctx_set_device_property_modified (LibHalContext *ctx, LibHalDevicePropertyModified callback)
 Set the callback for when a property is modified on a device.
dbus_bool_t libhal_ctx_set_device_condition (LibHalContext *ctx, LibHalDeviceCondition callback)
 Set the callback for when a device emits a condition.
unsigned int libhal_string_array_length (char **str_array)
 Get the length of an array of strings.
dbus_bool_t libhal_device_rescan (LibHalContext *ctx, const char *udi, DBusError *error)
dbus_bool_t libhal_device_reprobe (LibHalContext *ctx, const char *udi, DBusError *error)
dbus_bool_t libhal_device_emit_condition (LibHalContext *ctx, const char *udi, const char *condition_name, const char *condition_details, DBusError *error)
 Emit a condition from a device.

Variables

static dbus_bool_t libhal_already_initialized_once = FALSE

Detailed Description

A convenience library used to communicate with the HAL daemon using D-BUS.


Typedef Documentation

typedef void(* LibHalDeviceAdded)(LibHalContext *ctx, const char *udi)
 

Type for callback when a device is added.

Parameters:
ctx Context for connection to hald
udi Unique Device Id

Definition at line 86 of file libhal.h.

typedef void(* LibHalDeviceCondition)(LibHalContext *ctx, const char *udi, const char *condition_name, const char *condition_detail)
 

Type for callback when a non-continuous condition occurs on a device.

Parameters:
ctx Context for connection to hald
udi Unique Device Id
condition_name Name of the condition, e.g. ProcessorOverheating. Consult the HAL spec for possible conditions
condition_detail User-readable details of condition

Definition at line 140 of file libhal.h.

typedef void(* LibHalDeviceLostCapability)(LibHalContext *ctx, const char *udi, const char *capability)
 

Type for callback when a device loses a capability.

Parameters:
ctx Context for connection to hald
udi Unique Device Id
capability Capability of the device

Definition at line 113 of file libhal.h.

typedef void(* LibHalDeviceNewCapability)(LibHalContext *ctx, const char *udi, const char *capability)
 

Type for callback when a device gains a new capability.

Parameters:
ctx Context for connection to hald
udi Unique Device Id
capability Capability of the device

Definition at line 103 of file libhal.h.

typedef void(* LibHalDevicePropertyModified)(LibHalContext *ctx, const char *udi, const char *key, dbus_bool_t is_removed, dbus_bool_t is_added)
 

Type for callback when a property of a device changes.

Parameters:
ctx Context for connection to hald
udi Unique Device Id
key Name of the property that has changed
is_removed Whether or not property was removed
is_added Whether or not property was added

Definition at line 125 of file libhal.h.

typedef void(* LibHalDeviceRemoved)(LibHalContext *ctx, const char *udi)
 

Type for callback when a device is removed.

Parameters:
ctx Context for connection to hald
udi Unique Device Id

Definition at line 94 of file libhal.h.

typedef void(* LibHalIntegrateDBusIntoMainLoop)(LibHalContext *ctx, DBusConnection *dbus_connection)
 

Type for function in application code that integrates a DBusConnection object into its own mainloop.

Parameters:
ctx Context for connection to hald
dbus_connection DBus connection to use in ctx

Definition at line 78 of file libhal.h.


Enumeration Type Documentation

enum LibHalPropertyType
 

Possible types for properties on hal device objects.

Enumeration values:
LIBHAL_PROPERTY_TYPE_INVALID  Used to report error condition.
LIBHAL_PROPERTY_TYPE_INT32  Type for 32-bit signed integer property.
LIBHAL_PROPERTY_TYPE_UINT64  Type for 64-bit unsigned integer property.
LIBHAL_PROPERTY_TYPE_DOUBLE  Type for double precision floating point property.
LIBHAL_PROPERTY_TYPE_BOOLEAN  Type for boolean property.
LIBHAL_PROPERTY_TYPE_STRING  Type for UTF-8 string property.
LIBHAL_PROPERTY_TYPE_STRLIST  Type for list of UTF-8 strings property.

Definition at line 45 of file libhal.h.


Function Documentation

dbus_bool_t libhal_agent_commit_to_gdl LibHalContext *  ctx,
const char *  temp_udi,
const char *  udi,
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.

This means that the device object will be visible to applications and the HAL daemon will possibly attempt to boot the device (depending on the property RequireEnable).

Note that the program invoking this method needs to run with super user privileges.

Parameters:
ctx The context for the connection to hald
temp_udi The temporary unique device id as returned by libhal_agent_new_device()
udi The new unique device id.
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
FALSE if the given unique device id is already in use.

Definition at line 2060 of file libhal.c.

dbus_bool_t libhal_agent_device_matches LibHalContext *  ctx,
const char *  udi1,
const char *  udi2,
const char *  property_namespace,
DBusError *  error
 

Check a set of properties for two devices matches.

Checks that all properties where keys, starting with a given value (namespace), of the first device is in the second device and that they got the same value and type.

Note that the other inclusion isn't tested, so there could be properties (from the given namespace) in the second device not present in the first device.

Parameters:
ctx The context for the connection to hald
udi1 Unique Device Id for device 1
udi2 Unique Device Id for device 2
property_namespace Namespace for set of devices, e.g. "usb"
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if all properties starting with the given namespace parameter from one device is in the other and have the same value.

Definition at line 2354 of file libhal.c.

dbus_bool_t libhal_agent_merge_properties LibHalContext *  ctx,
const char *  target_udi,
const char *  source_udi,
DBusError *  error
 

Merge properties from one device to another.

Parameters:
ctx The context for the connection to hald
target_udi Unique device id of target device to merge to
source_udi Unique device id of device to merge from
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the properties were merged, FALSE otherwise

Definition at line 2292 of file libhal.c.

char * libhal_agent_new_device LibHalContext *  ctx,
DBusError *  error
 

Create a new device object which will be hidden from applications until the CommitToGdl(), ie.

libhal_agent_commit_to_gdl(), method is called.

Note that the program invoking this method needs to run with super user privileges.

Parameters:
ctx The context for the connection to hald
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
Temporary device unique id or NULL if there was a problem. This string must be freed by the caller.
Todo:
FIXME cleanup

Definition at line 1980 of file libhal.c.

dbus_bool_t libhal_agent_remove_device LibHalContext *  ctx,
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.

Note that the program invoking this method needs to run with super user privileges.

Parameters:
ctx The context for the connection to hald
udi The new unique device id.
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the device was removed, FALSE otherwise

Definition at line 2114 of file libhal.c.

dbus_bool_t libhal_ctx_free LibHalContext *  ctx  ) 
 

Free a LibHalContext resource.

Parameters:
ctx Pointer to a LibHalContext
Returns:
TRUE

Definition at line 2983 of file libhal.c.

Referenced by libhal_ctx_init_direct().

void * libhal_ctx_get_user_data LibHalContext *  ctx  ) 
 

Get user data for the context.

Parameters:
ctx The context for the connection to hald
Returns:
Opaque pointer stored through libhal_ctx_set_user_data or NULL if not set

Definition at line 240 of file libhal.c.

dbus_bool_t libhal_ctx_init LibHalContext *  ctx,
DBusError *  error
 

Initialize the connection to hald.

Parameters:
ctx Context for connection to hald (connection should be set with libhal_ctx_set_dbus_connection)
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if initialization succeeds, FALSE otherwise

Definition at line 2868 of file libhal.c.

LibHalContext * libhal_ctx_init_direct DBusError *  error  ) 
 

Create an already initialized connection to hald.

Parameters:
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
A pointer to an already initialized LibHalContext

Definition at line 2906 of file libhal.c.

References libhal_ctx_free(), and libhal_ctx_new().

LibHalContext * libhal_ctx_new void   ) 
 

Create a new LibHalContext.

Returns:
a new uninitialized LibHalContext

Definition at line 2795 of file libhal.c.

Referenced by libhal_ctx_init_direct().

dbus_bool_t libhal_ctx_set_cache LibHalContext *  ctx,
dbus_bool_t  use_cache
 

Enable or disable caching.

Note:
Cache is not actually implemented yet.
Parameters:
ctx Context to enable/disable cache for
use_cache Whether or not to use cache
Returns:
TRUE if cache was successfully enabled/disabled, FALSE otherwise

Definition at line 2830 of file libhal.c.

dbus_bool_t libhal_ctx_set_dbus_connection LibHalContext *  ctx,
DBusConnection *  conn
 

Set DBus connection to use to talk to hald.

Parameters:
ctx Context to set connection for
conn DBus connection to use
Returns:
TRUE if connection was successfully set, FALSE otherwise

Definition at line 2847 of file libhal.c.

dbus_bool_t libhal_ctx_set_device_added LibHalContext *  ctx,
LibHalDeviceAdded  callback
 

Set the callback for when a device is added.

Parameters:
ctx The context for the connection to hald
callback The function to call when a device is added
Returns:
TRUE if callback was successfully set, FALSE otherwise

Definition at line 2997 of file libhal.c.

dbus_bool_t libhal_ctx_set_device_condition LibHalContext *  ctx,
LibHalDeviceCondition  callback
 

Set the callback for when a device emits a condition.

Parameters:
ctx The context for the connection to hald
callback The function to call when a device emits a condition
Returns:
TRUE if callback was successfully set, FALSE otherwise

Definition at line 3080 of file libhal.c.

dbus_bool_t libhal_ctx_set_device_lost_capability LibHalContext *  ctx,
LibHalDeviceLostCapability  callback
 

Set the callback for when a device loses a capability.

Parameters:
ctx The context for the connection to hald
callback The function to call when a device loses a capability
Returns:
TRUE if callback was successfully set, FALSE otherwise

Definition at line 3047 of file libhal.c.

dbus_bool_t libhal_ctx_set_device_new_capability LibHalContext *  ctx,
LibHalDeviceNewCapability  callback
 

Set the callback for when a device gains a new capability.

Parameters:
ctx The context for the connection to hald
callback The function to call when a device gains a new capability
Returns:
TRUE if callback was successfully set, FALSE otherwise

Definition at line 3030 of file libhal.c.

dbus_bool_t libhal_ctx_set_device_property_modified LibHalContext *  ctx,
LibHalDevicePropertyModified  callback
 

Set the callback for when a property is modified on a device.

Parameters:
ctx The context for the connection to hald
callback The function to call when a property is modified on a device
Returns:
TRUE if callback was successfully set, FALSE otherwise

Definition at line 3064 of file libhal.c.

dbus_bool_t libhal_ctx_set_device_removed LibHalContext *  ctx,
LibHalDeviceRemoved  callback
 

Set the callback for when a device is removed.

Parameters:
ctx The context for the connection to hald
callback The function to call when a device is removed
Returns:
TRUE if callback was successfully set, FALSE otherwise

Definition at line 3013 of file libhal.c.

dbus_bool_t libhal_ctx_set_user_data LibHalContext *  ctx,
void *  user_data
 

Set user data for the context.

Parameters:
ctx The context for the connection to hald
user_data Opaque pointer
Returns:
TRUE if user data was successfully set, FALSE if otherwise

Definition at line 225 of file libhal.c.

dbus_bool_t libhal_ctx_shutdown LibHalContext *  ctx,
DBusError *  error
 

Shut down a connection to hald.

Parameters:
ctx Context for connection to hald
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if connection successfully shut down, FALSE otherwise
Todo:
clean up

Definition at line 2947 of file libhal.c.

dbus_bool_t libhal_device_add_capability LibHalContext *  ctx,
const char *  udi,
const char *  capability,
DBusError *  error
 

Assign a capability to a device.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
capability Capability name
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the capability was added, FALSE if the device didn't exist

Definition at line 2573 of file libhal.c.

dbus_bool_t libhal_device_add_property_watch LibHalContext *  ctx,
const char *  udi,
DBusError *  error
 

Add a watch on a device, so the device_property_changed callback is invoked when the properties on the given device changes.

The application itself is responsible for deleting the watch, using libhal_device_remove_property_watch, if the device is removed.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE only if the operation succeeded

Definition at line 2747 of file libhal.c.

dbus_bool_t libhal_device_emit_condition LibHalContext *  ctx,
const char *  udi,
const char *  condition_name,
const char *  condition_details,
DBusError *  error
 

Emit a condition from a device.

Parameters:
ctx Context for connection to hald
udi Unique Device Id
condition_name User-readable name of condition
condition_details User-readable details of condition
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if condition successfully emitted, FALSE otherwise

Definition at line 3213 of file libhal.c.

dbus_bool_t libhal_device_exists LibHalContext *  ctx,
const char *  udi,
DBusError *  error
 

Determine if a device exists.

Parameters:
ctx The context for the connection to hald
udi Unique device id.
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the device exists

Definition at line 2161 of file libhal.c.

LibHalPropertySet * libhal_device_get_all_properties LibHalContext *  ctx,
const char *  udi,
DBusError *  error
 

Retrieve all the properties on a device.

Parameters:
ctx The context for the connection to hald
udi Unique id of device
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
An object represent all properties. Must be freed with libhal_free_property_set
Todo:
FIXME cleanup

Definition at line 341 of file libhal.c.

References libhal_property_fill_value_from_variant().

Referenced by libhal_device_print(), libhal_drive_from_udi(), and libhal_volume_from_udi().

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 bool.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
Property value (boolean)

Definition at line 1369 of file libhal.c.

double libhal_device_get_property_double LibHalContext *  ctx,
const char *  udi,
const char *  key,
DBusError *  error
 

Get the value of a property of type double.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
Property value (IEEE754 double precision float)

Definition at line 1303 of file libhal.c.

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 integer.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
Property value (32-bit signed integer)

Definition at line 1170 of file libhal.c.

char * libhal_device_get_property_string LibHalContext *  ctx,
const char *  udi,
const char *  key,
DBusError *  error
 

Get the value of a property of type string.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
UTF8 nul-terminated string. The caller is responsible for freeing this string with the function libhal_free_string(). Returns NULL if the property didn't exist or we are OOM
Todo:
FIXME cleanup

Definition at line 1097 of file libhal.c.

Referenced by libhal_drive_from_device_file().

char ** libhal_device_get_property_strlist LibHalContext *  ctx,
const char *  udi,
const char *  key,
DBusError *  error
 

Get the value of a property of type string list.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
Array of pointers to UTF8 nul-terminated strings terminated by NULL. The caller is responsible for freeing this string array with the function libhal_free_string_array(). Returns NULL if the property didn't exist or we are OOM

Definition at line 1030 of file libhal.c.

References libhal_get_string_array_from_iter().

Referenced by libhal_device_query_capability().

LibHalPropertyType libhal_device_get_property_type LibHalContext *  ctx,
const char *  udi,
const char *  key,
DBusError *  error
 

Query a property type of a device.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
One of LIBHAL_PROPERTY_TYPE_INT32, LIBHAL_PROPERTY_TYPE_UINT64, LIBHAL_PROPERTY_TYPE_DOUBLE, LIBHAL_PROPERTY_TYPE_BOOLEAN, LIBHAL_PROPERTY_TYPE_STRING, LIBHAL_PROPERTY_TYPE_STRLIST or LIBHAL_PROPERTY_TYPE_INVALID if property doesn't exist.

Definition at line 971 of file libhal.c.

References LIBHAL_PROPERTY_TYPE_INVALID.

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 signed integer.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
Property value (64-bit unsigned integer)

Definition at line 1237 of file libhal.c.

dbus_bool_t libhal_device_lock LibHalContext *  ctx,
const char *  udi,
const char *  reason_to_lock,
char **  reason_why_locked,
DBusError *  error
 

Take an advisory lock on the device.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
reason_to_lock A user-presentable reason why the device is locked.
reason_why_locked A pointer to store the reason why the device cannot be locked on failure, or NULL
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the lock was obtained, FALSE otherwise

Definition at line 1861 of file libhal.c.

dbus_bool_t libhal_device_print LibHalContext *  ctx,
const char *  udi,
DBusError *  error
 

Print a device to stdout; useful for debugging.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if device's information could be obtained, FALSE otherwise

Definition at line 2423 of file libhal.c.

References libhal_device_get_all_properties(), libhal_free_property_set(), LIBHAL_PROPERTY_TYPE_BOOLEAN, LIBHAL_PROPERTY_TYPE_DOUBLE, LIBHAL_PROPERTY_TYPE_INT32, LIBHAL_PROPERTY_TYPE_STRING, LIBHAL_PROPERTY_TYPE_STRLIST, LIBHAL_PROPERTY_TYPE_UINT64, libhal_psi_get_bool(), libhal_psi_get_double(), libhal_psi_get_int(), libhal_psi_get_key(), libhal_psi_get_string(), libhal_psi_get_strlist(), libhal_psi_get_type(), libhal_psi_get_uint64(), libhal_psi_has_more(), libhal_psi_init(), and libhal_psi_next().

dbus_bool_t libhal_device_property_exists LibHalContext *  ctx,
const char *  udi,
const char *  key,
DBusError *  error
 

Determine if a property on a device exists.

Parameters:
ctx The context for the connection to hald
udi Unique device id.
key Name of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the device exists, FALSE otherwise

Definition at line 2227 of file libhal.c.

dbus_bool_t libhal_device_property_strlist_append LibHalContext *  ctx,
const char *  udi,
const char *  key,
const char *  value,
DBusError *  error
 

Append to a property of type strlist.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
value Value to append to property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the value was appended, FALSE if the device didn't exist or the property had a different type.

Definition at line 1659 of file libhal.c.

dbus_bool_t libhal_device_property_strlist_prepend LibHalContext *  ctx,
const char *  udi,
const char *  key,
const char *  value,
DBusError *  error
 

Prepend to a property of type strlist.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
value Value to prepend to property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the value was prepended, FALSE if the device didn't exist or the property had a different type.

Definition at line 1709 of file libhal.c.

dbus_bool_t libhal_device_property_strlist_remove LibHalContext *  ctx,
const char *  udi,
const char *  key,
const char *  value,
DBusError *  error
 

Remove a specified string from a property of type strlist.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
value The string to search for and remove
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the string was removed, FALSE if the device didn't exist or the property had a different type.

Definition at line 1809 of file libhal.c.

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.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
index Index of string to remove in the strlist
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the string was removed, FALSE if the device didn't exist or the property had a different type.

Definition at line 1759 of file libhal.c.

dbus_bool_t libhal_device_property_watch_all LibHalContext *  ctx,
DBusError *  error
 

Watch all devices, ie.

the device_property_changed callback is invoked when the properties on any device changes.

Parameters:
ctx The context for the connection to hald
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE only if the operation succeeded

Definition at line 2721 of file libhal.c.

dbus_bool_t libhal_device_query_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.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
capability Capability name
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the device has the capability, otherwise FALSE

Definition at line 2624 of file libhal.c.

References libhal_device_get_property_strlist(), and libhal_free_string_array().

Referenced by libhal_drive_from_device_file(), libhal_drive_from_udi(), libhal_volume_from_device_file(), and libhal_volume_from_udi().

dbus_bool_t libhal_device_remove_property LibHalContext *  ctx,
const char *  udi,
const char *  key,
DBusError *  error
 

Remove a property.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the property was set, FALSE if the device didn't exist

Definition at line 1638 of file libhal.c.

References libhal_device_set_property_helper().

dbus_bool_t libhal_device_remove_property_watch LibHalContext *  ctx,
const char *  udi,
DBusError *  error
 

Remove a watch on a device.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE only if the operation succeeded

Definition at line 2773 of file libhal.c.

dbus_bool_t libhal_device_set_property_bool LibHalContext *  ctx,
const char *  udi,
const char *  key,
dbus_bool_t  value,
DBusError *  error
 

Set a property of type bool.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
value Value of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the property was set, FALSE if the device didn't exist or the property had a different type.

Definition at line 1618 of file libhal.c.

References libhal_device_set_property_helper().

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 double.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
value Value of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the property was set, FALSE if the device didn't exist or the property had a different type.

Definition at line 1597 of file libhal.c.

References libhal_device_set_property_helper().

static dbus_bool_t libhal_device_set_property_helper LibHalContext *  ctx,
const char *  udi,
const char *  key,
int  type,
const char *  str_value,
dbus_int32_t  int_value,
dbus_uint64_t  uint64_value,
double  double_value,
dbus_bool_t  bool_value,
DBusError *  error
[static]
 

Todo:
sanity check incoming params

Definition at line 1428 of file libhal.c.

Referenced by libhal_device_remove_property(), libhal_device_set_property_bool(), libhal_device_set_property_double(), libhal_device_set_property_int(), libhal_device_set_property_string(), and libhal_device_set_property_uint64().

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 signed integer.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
value Value of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the property was set, FALSE if the device didn't exist or the property had a different type.

Definition at line 1555 of file libhal.c.

References libhal_device_set_property_helper().

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 string.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
value Value of the property; a UTF8 string
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the property was set, FALSE if the device didn't exist or the property had a different type.

Definition at line 1531 of file libhal.c.

References libhal_device_set_property_helper().

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 unsigned integer.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
key Name of the property
value Value of the property
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the property was set, FALSE if the device didn't exist or the property had a different type.

Definition at line 1576 of file libhal.c.

References libhal_device_set_property_helper().

dbus_bool_t libhal_device_unlock LibHalContext *  ctx,
const char *  udi,
DBusError *  error
 

Release an advisory lock on the device.

Parameters:
ctx The context for the connection to hald
udi Unique Device Id
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
TRUE if the device was successfully unlocked, FALSE otherwise

Definition at line 1927 of file libhal.c.

char ** libhal_find_device_by_capability LibHalContext *  ctx,
const char *  capability,
int *  num_devices,
DBusError *  error
 

Find devices with a given capability.

Parameters:
ctx The context for the connection to hald
capability Capability name
num_devices Pointer to store number of devices
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
UDI of devices; free with libhal_free_string_array()

Definition at line 2657 of file libhal.c.

References libhal_get_string_array_from_iter().

void libhal_free_property_set LibHalPropertySet *  set  ) 
 

Free a property set earlier obtained with libhal_device_get_all_properties().

Parameters:
set Property-set to free

Definition at line 473 of file libhal.c.

References libhal_free_string_array(), and LIBHAL_PROPERTY_TYPE_STRLIST.

Referenced by libhal_device_print(), libhal_drive_from_udi(), and libhal_volume_from_udi().

void libhal_free_string char *  str  ) 
 

Frees a nul-terminated string.

Parameters:
str The nul-terminated sting to free
Todo:
implement for UTF8

Definition at line 150 of file libhal.c.

Referenced by libhal_drive_free(), libhal_drive_from_device_file(), libhal_drive_from_udi(), libhal_volume_free(), and libhal_volume_from_udi().

void libhal_free_string_array char **  str_array  ) 
 

Frees a NULL-terminated array of strings.

If passed NULL, does nothing.

Parameters:
str_array The array to be freed

Definition at line 75 of file libhal.c.

Referenced by libhal_device_query_capability(), libhal_drive_free(), libhal_drive_from_device_file(), libhal_free_property_set(), and libhal_volume_from_device_file().

char ** libhal_get_all_devices LibHalContext *  ctx,
int *  num_devices,
DBusError *  error
 

Get all devices in the Global Device List (GDL).

Parameters:
ctx The context for the connection to hald
num_devices The number of devices will be stored here
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
An array of device identifiers terminated with NULL. It is the responsibility of the caller to free with libhal_free_string_array(). If an error occurs NULL is returned.

Definition at line 907 of file libhal.c.

References libhal_get_string_array_from_iter().

static char ** libhal_get_string_array_from_iter DBusMessageIter *  iter,
int *  num_elements
[static]
 

Creates a NULL terminated array of strings from a dbus message iterator.

Parameters:
iter The message iterator to extract the strings from
num_elements Pointer to an integer where to store number of elements (can be NULL)
Returns:
Pointer to the string array

Definition at line 95 of file libhal.c.

Referenced by libhal_device_get_property_strlist(), libhal_find_device_by_capability(), libhal_get_all_devices(), libhal_manager_find_device_string_match(), and libhal_property_fill_value_from_variant().

char ** libhal_manager_find_device_string_match LibHalContext *  ctx,
const char *  key,
const char *  value,
int *  num_devices,
DBusError *  error
 

Find a device in the GDL where a single string property matches a given value.

Parameters:
ctx The context for the connection to hald
key Name of the property
value Value to match
num_devices Pointer to store number of devices
error Pointer to an initialized dbus error object for returning errors or #NULL
Returns:
UDI of devices; free with libhal_free_string_array()

Definition at line 2504 of file libhal.c.

References libhal_get_string_array_from_iter().

Referenced by libhal_drive_from_device_file(), and libhal_volume_from_device_file().

static dbus_bool_t libhal_property_fill_value_from_variant LibHalProperty *  p,
DBusMessageIter *  var_iter
[static]
 

Fills in the value for the LibHalProperty given a variant iterator.

Parameters:
p The property to fill in
var_iter Varient iterator to extract the value from
Todo:
report error

Definition at line 252 of file libhal.c.

References libhal_get_string_array_from_iter(), LIBHAL_PROPERTY_TYPE_BOOLEAN, LIBHAL_PROPERTY_TYPE_DOUBLE, LIBHAL_PROPERTY_TYPE_INT32, LIBHAL_PROPERTY_TYPE_STRING, LIBHAL_PROPERTY_TYPE_STRLIST, and LIBHAL_PROPERTY_TYPE_UINT64.

Referenced by libhal_device_get_all_properties().

unsigned int libhal_property_set_get_num_elems LibHalPropertySet *  set  ) 
 

Get the number of properties in a property set.

Parameters:
set Property set to consider
Returns:
Number of properties in given property set

Definition at line 499 of file libhal.c.

dbus_bool_t libhal_psi_get_bool LibHalPropertySetIterator *  iter  ) 
 

Get the value of a property of type bool.

Parameters:
iter Iterator object
Returns:
Property value (bool)

Definition at line 627 of file libhal.c.

Referenced by libhal_device_print().

double libhal_psi_get_double LibHalPropertySetIterator *  iter  ) 
 

Get the value of a property of type double.

Parameters:
iter Iterator object
Returns:
Property value (IEEE754 double precision float)

Definition at line 616 of file libhal.c.

Referenced by libhal_device_print().

dbus_int32_t libhal_psi_get_int LibHalPropertySetIterator *  iter  ) 
 

Get the value of a property of type signed integer.

Parameters:
iter Iterator object
Returns:
Property value (32-bit signed integer)

Definition at line 594 of file libhal.c.

Referenced by libhal_device_print().

char * libhal_psi_get_key LibHalPropertySetIterator *  iter  ) 
 

Get the key of a property.

Parameters:
iter Iterator object
Returns:
ASCII nul-terminated string. This pointer is only valid until libhal_free_property_set() is invoked on the property set this property belongs to

Definition at line 569 of file libhal.c.

Referenced by libhal_device_print(), libhal_drive_from_udi(), and libhal_volume_from_udi().

char * libhal_psi_get_string LibHalPropertySetIterator *  iter  ) 
 

Get the value of a property of type string.

Parameters:
iter Iterator object
Returns:
UTF8 nul-terminated string. This pointer is only valid until libhal_free_property_set() is invoked on the property set this property belongs to

Definition at line 583 of file libhal.c.

Referenced by libhal_device_print().

char ** libhal_psi_get_strlist LibHalPropertySetIterator *  iter  ) 
 

Get the value of a property of type string list.

Parameters:
iter Iterator object
Returns:
Pointer to array of strings

Definition at line 638 of file libhal.c.

Referenced by libhal_device_print().

LibHalPropertyType libhal_psi_get_type LibHalPropertySetIterator *  iter  ) 
 

Get type of property.

Parameters:
iter Iterator object
Returns:
The property type at the iterator's position

Definition at line 555 of file libhal.c.

Referenced by libhal_device_print(), libhal_drive_from_udi(), and libhal_volume_from_udi().

dbus_uint64_t libhal_psi_get_uint64 LibHalPropertySetIterator *  iter  ) 
 

Get the value of a property of type unsigned integer.

Parameters:
iter Iterator object
Returns:
Property value (64-bit unsigned integer)

Definition at line 605 of file libhal.c.

Referenced by libhal_device_print().

dbus_bool_t libhal_psi_has_more LibHalPropertySetIterator *  iter  ) 
 

Determine whether there are more properties to iterate over.

Parameters:
iter Iterator object
Returns:
TRUE if there are more properties, FALSE otherwise

Definition at line 533 of file libhal.c.

Referenced by libhal_device_print(), libhal_drive_from_udi(), and libhal_volume_from_udi().

void libhal_psi_init LibHalPropertySetIterator *  iter,
LibHalPropertySet *  set
 

Initialize a property set iterator.

Parameters:
iter Iterator object
set Property set to iterate over

Definition at line 518 of file libhal.c.

Referenced by libhal_device_print(), libhal_drive_from_udi(), and libhal_volume_from_udi().

void libhal_psi_next LibHalPropertySetIterator *  iter  ) 
 

Advance iterator to next property.

Parameters:
iter Iterator object

Definition at line 543 of file libhal.c.

Referenced by libhal_device_print(), libhal_drive_from_udi(), and libhal_volume_from_udi().

unsigned int libhal_string_array_length char **  str_array  ) 
 

Get the length of an array of strings.

Parameters:
str_array Array of strings to consider
Returns:
Amount of strings in array

Definition at line 3093 of file libhal.c.


Generated on Mon May 23 10:13:20 2005 for HAL by  doxygen 1.4.2