libhal

## libhal libhal |

## Synopsis

    #define             DBUS_API_SUBJECT_TO_CHANGE
    #define             LIBHAL_DEPRECATED
    #define             LIBHAL_FREE_DBUS_ERROR              (_dbus_error_)
    #define             LIBHAL_CHECK_LIBHALCONTEXT          (_ctx_, _ret_)
    enum                LibHalPropertyType;
    typedef             LibHalContext;
    typedef             LibHalProperty;
    typedef             LibHalPropertySet;
    void                (*LibHalIntegrateDBusIntoMainLoop)  (LibHalContext *ctx,
                                                             DBusConnection *dbus_connection);
    void                (*LibHalDeviceAdded)                (LibHalContext *ctx,
                                                             const char *udi);
    void                (*LibHalDeviceRemoved)              (LibHalContext *ctx,
                                                             const char *udi);
    void                (*LibHalDeviceNewCapability)        (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *capability);
    void                (*LibHalDeviceLostCapability)       (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *capability);
    void                (*LibHalDevicePropertyModified)     (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             dbus_bool_t is_removed,
                                                             dbus_bool_t is_added);
    void                (*LibHalDeviceCondition)            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *condition_name,
                                                             const char *condition_detail);
    void                (*LibHalGlobalInterfaceLockAcquired)
                                                            (LibHalContext *ctx,
                                                             const char *interface_name,
                                                             const char *lock_owner,
                                                             int num_locks);
    void                (*LibHalGlobalInterfaceLockReleased)
                                                            (LibHalContext *ctx,
                                                             const char *interface_name,
                                                             const char *lock_owner,
                                                             int num_locks);
    void                (*LibHalInterfaceLockAcquired)      (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface_name,
                                                             const char *lock_owner,
                                                             int num_locks);
    void                (*LibHalInterfaceLockReleased)      (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface_name,
                                                             const char *lock_owner,
                                                             int num_locks);
    void                (*LibHalSingletonDeviceAdded)       (LibHalContext *ctx,
                                                             const char *udi,
                                                             const LibHalPropertySet *properties);
    void                (*LibHalSingletonDeviceRemoved)     (LibHalContext *ctx,
                                                             const char *udi,
                                                             const LibHalPropertySet *properties);
    LibHalContext*      libhal_ctx_new                      (void);
    dbus_bool_t         libhal_ctx_set_cache                (LibHalContext *ctx,
                                                             dbus_bool_t use_cache);
    dbus_bool_t         libhal_ctx_set_dbus_connection      (LibHalContext *ctx,
                                                             DBusConnection *conn);
    DBusConnection*     libhal_ctx_get_dbus_connection      (LibHalContext *ctx);
    dbus_bool_t         libhal_ctx_set_user_data            (LibHalContext *ctx,
                                                             void *user_data);
    void*               libhal_ctx_get_user_data            (LibHalContext *ctx);
    dbus_bool_t         libhal_ctx_set_device_added         (LibHalContext *ctx,
                                                             LibHalDeviceAdded callback);
    dbus_bool_t         libhal_ctx_set_device_removed       (LibHalContext *ctx,
                                                             LibHalDeviceRemoved callback);
    dbus_bool_t         libhal_ctx_set_device_new_capability
                                                            (LibHalContext *ctx,
                                                             LibHalDeviceNewCapability callback);
    dbus_bool_t         libhal_ctx_set_device_lost_capability
                                                            (LibHalContext *ctx,
                                                             LibHalDeviceLostCapability callback);
    dbus_bool_t         libhal_ctx_set_device_property_modified
                                                            (LibHalContext *ctx,
                                                             LibHalDevicePropertyModified callback);
    dbus_bool_t         libhal_ctx_set_device_condition     (LibHalContext *ctx,
                                                             LibHalDeviceCondition callback);
    dbus_bool_t         libhal_ctx_set_global_interface_lock_acquired
                                                            (LibHalContext *ctx,
                                                             LibHalGlobalInterfaceLockAcquired callback);
    dbus_bool_t         libhal_ctx_set_global_interface_lock_released
                                                            (LibHalContext *ctx,
                                                             LibHalGlobalInterfaceLockReleased callback);
    dbus_bool_t         libhal_ctx_set_interface_lock_acquired
                                                            (LibHalContext *ctx,
                                                             LibHalInterfaceLockAcquired callback);
    dbus_bool_t         libhal_ctx_set_interface_lock_released
                                                            (LibHalContext *ctx,
                                                             LibHalInterfaceLockReleased callback);
    dbus_bool_t         libhal_ctx_set_singleton_device_added
                                                            (LibHalContext *ctx,
                                                             LibHalSingletonDeviceAdded callback);
    dbus_bool_t         libhal_ctx_set_singleton_device_removed
                                                            (LibHalContext *ctx,
                                                             LibHalSingletonDeviceRemoved callback);
    dbus_bool_t         libhal_ctx_init                     (LibHalContext *ctx,
                                                             DBusError *error);
    dbus_bool_t         libhal_ctx_shutdown                 (LibHalContext *ctx,
                                                             DBusError *error);
    dbus_bool_t         libhal_ctx_free                     (LibHalContext *ctx);
    LibHalContext*      libhal_ctx_init_direct              (DBusError *error);
    char**              libhal_get_all_devices              (LibHalContext *ctx,
                                                             int *num_devices,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_exists                (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_print                 (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_property_exists       (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             DBusError *error);
    char*               libhal_device_get_property_string   (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             DBusError *error);
    dbus_int32_t        libhal_device_get_property_int      (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             DBusError *error);
    dbus_uint64_t       libhal_device_get_property_uint64   (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             DBusError *error);
    double              libhal_device_get_property_double   (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_get_property_bool     (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             DBusError *error);
    char**              libhal_device_get_property_strlist  (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_set_property_string   (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             const char *value,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_set_property_int      (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             dbus_int32_t value,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_set_property_uint64   (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             dbus_uint64_t value,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_set_property_double   (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             double value,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_set_property_bool     (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             dbus_bool_t value,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_property_strlist_append
                                                            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             const char *value,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_property_strlist_prepend
                                                            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             const char *value,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_property_strlist_remove_index
                                                            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             unsigned int idx,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_property_strlist_remove
                                                            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             const char *value,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_remove_property       (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             DBusError *error);
    LibHalPropertyType  libhal_device_get_property_type     (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             DBusError *error);
    struct              LibHalChangeSet_s;
    typedef             LibHalChangeSet;
    LibHalChangeSet*    libhal_device_new_changeset         (const char *udi);
    dbus_bool_t         libhal_changeset_set_property_string
                                                            (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             const char *value);
    dbus_bool_t         libhal_changeset_set_property_int   (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             dbus_int32_t value);
    dbus_bool_t         libhal_changeset_set_property_uint64
                                                            (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             dbus_uint64_t value);
    dbus_bool_t         libhal_changeset_set_property_double
                                                            (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             double value);
    dbus_bool_t         libhal_changeset_set_property_bool  (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             dbus_bool_t value);
    dbus_bool_t         libhal_changeset_set_property_strlist
                                                            (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             const char **value);
    dbus_bool_t         libhal_device_commit_changeset      (LibHalContext *ctx,
                                                             LibHalChangeSet *changeset,
                                                             DBusError *error);
    void                libhal_device_free_changeset        (LibHalChangeSet *changeset);
    LibHalPropertySet*  libhal_device_get_all_properties    (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);
    void                libhal_property_set_sort            (LibHalPropertySet *set);
    void                libhal_free_property_set            (LibHalPropertySet *set);
    unsigned int        libhal_property_set_get_num_elems   (LibHalPropertySet *set);
    LibHalPropertyType  libhal_ps_get_type                  (const LibHalPropertySet *set,
                                                             const char *key);
    const char*         libhal_ps_get_string                (const LibHalPropertySet *set,
                                                             const char *key);
    dbus_int32_t        libhal_ps_get_int32                 (const LibHalPropertySet *set,
                                                             const char *key);
    dbus_uint64_t       libhal_ps_get_uint64                (const LibHalPropertySet *set,
                                                             const char *key);
    double              libhal_ps_get_double                (const LibHalPropertySet *set,
                                                             const char *key);
    dbus_bool_t         libhal_ps_get_bool                  (const LibHalPropertySet *set,
                                                             const char *key);
    struct              LibHalPropertySetIterator_s;
    typedef             LibHalPropertySetIterator;
    void                libhal_psi_init                     (LibHalPropertySetIterator *iter,
                                                             LibHalPropertySet *set);
    dbus_bool_t         libhal_psi_has_more                 (LibHalPropertySetIterator *iter);
    void                libhal_psi_next                     (LibHalPropertySetIterator *iter);
    LibHalPropertyType  libhal_psi_get_type                 (LibHalPropertySetIterator *iter);
    char*               libhal_psi_get_key                  (LibHalPropertySetIterator *iter);
    char*               libhal_psi_get_string               (LibHalPropertySetIterator *iter);
    dbus_int32_t        libhal_psi_get_int                  (LibHalPropertySetIterator *iter);
    dbus_uint64_t       libhal_psi_get_uint64               (LibHalPropertySetIterator *iter);
    double              libhal_psi_get_double               (LibHalPropertySetIterator *iter);
    dbus_bool_t         libhal_psi_get_bool                 (LibHalPropertySetIterator *iter);
    char**              libhal_psi_get_strlist              (LibHalPropertySetIterator *iter);
    unsigned int        libhal_string_array_length          (char **str_array);
    void                libhal_free_string_array            (char **str_array);
    void                libhal_free_string                  (char *str);
    char*               libhal_new_device                   (LibHalContext *ctx,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_commit_to_gdl         (LibHalContext *ctx,
                                                             const char *temp_udi,
                                                             const char *udi,
                                                             DBusError *error);
    dbus_bool_t         libhal_remove_device                (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);
    dbus_bool_t         libhal_merge_properties             (LibHalContext *ctx,
                                                             const char *target_udi,
                                                             const char *source_udi,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_matches               (LibHalContext *ctx,
                                                             const char *udi1,
                                                             const char *udi2,
                                                             const char *property_namespace,
                                                             DBusError *error);
    char**              libhal_manager_find_device_string_match
                                                            (LibHalContext *ctx,
                                                             const char *key,
                                                             const char *value,
                                                             int *num_devices,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_add_capability        (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *capability,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_query_capability      (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *capability,
                                                             DBusError *error);
    char**              libhal_find_device_by_capability    (LibHalContext *ctx,
                                                             const char *capability,
                                                             int *num_devices,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_property_watch_all    (LibHalContext *ctx,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_add_property_watch    (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_remove_property_watch (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_lock                  (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *reason_to_lock,
                                                             char **reason_why_locked,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_unlock                (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);
    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);
    dbus_bool_t         libhal_device_claim_interface       (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface_name,
                                                             const char *introspection_xml,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_addon_is_ready        (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_singleton_addon_is_ready
                                                            (LibHalContext *ctx,
                                                             const char *command_line,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_acquire_interface_lock
                                                            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface,
                                                             dbus_bool_t exclusive,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_release_interface_lock
                                                            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface,
                                                             DBusError *error);
    dbus_bool_t         libhal_acquire_global_interface_lock
                                                            (LibHalContext *ctx,
                                                             const char *interface,
                                                             dbus_bool_t exclusive,
                                                             DBusError *error);
    dbus_bool_t         libhal_release_global_interface_lock
                                                            (LibHalContext *ctx,
                                                             const char *interface,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_is_caller_locked_out  (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface,
                                                             const char *caller,
                                                             DBusError *error);
    dbus_bool_t         libhal_device_is_locked_by_others   (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface,
                                                             DBusError *error);
    char*               libhal_device_is_caller_privileged  (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *action,
                                                             const char *caller,
                                                             DBusError *error);

## Description

## Details

### DBUS_API_SUBJECT_TO_CHANGE

    #define DBUS_API_SUBJECT_TO_CHANGE

### LIBHAL_DEPRECATED

    #define             LIBHAL_DEPRECATED

### LIBHAL_FREE_DBUS_ERROR()

    #define             LIBHAL_FREE_DBUS_ERROR(_dbus_error_)

`_dbus_error_` : |

### LIBHAL_CHECK_LIBHALCONTEXT()

    #define             LIBHAL_CHECK_LIBHALCONTEXT(_ctx_, _ret_)

Handy macro for checking whether a context is valid.

`_ctx_` : | the context
`_ret_` : | what to use for return value if context is invalid

### enum LibHalPropertyType

    typedef enum {
            /** Used to report error condition */
    	LIBHAL_PROPERTY_TYPE_INVALID =    DBUS_TYPE_INVALID,

    	/** Type for 32-bit signed integer property */
    	LIBHAL_PROPERTY_TYPE_INT32   =    DBUS_TYPE_INT32,

    	/** Type for 64-bit unsigned integer property */
    	LIBHAL_PROPERTY_TYPE_UINT64  =    DBUS_TYPE_UINT64,

    	/** Type for double precision floating point property */
    	LIBHAL_PROPERTY_TYPE_DOUBLE  =    DBUS_TYPE_DOUBLE,

    	/** Type for boolean property */
    	LIBHAL_PROPERTY_TYPE_BOOLEAN =    DBUS_TYPE_BOOLEAN,

    	/** Type for UTF-8 string property */
    	LIBHAL_PROPERTY_TYPE_STRING  =    DBUS_TYPE_STRING,

    	/** Type for list of UTF-8 strings property */
    	LIBHAL_PROPERTY_TYPE_STRLIST =    ((int) (DBUS_TYPE_STRING<<8)+('l'))
    } LibHalPropertyType;

Possible types for properties on hal device objects

### LibHalContext

    typedef struct LibHalContext_s LibHalContext;

Context for connection to the HAL daemon. Opaque, use the libhal_ctx_*() family of functions to access it.

### LibHalProperty

    typedef struct LibHalProperty_s LibHalProperty;

Represents a property. Opaque.

### LibHalPropertySet

    typedef struct LibHalPropertySet_s LibHalPropertySet;

Represents a set of properties. Opaque; use the libhal_property_set_*() family of functions to access it.

### LibHalIntegrateDBusIntoMainLoop ()

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

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

`ctx` : | context for connection to hald
`dbus_connection` : | DBus connection to use in ctx

### LibHalDeviceAdded ()

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

Type for callback when a device is added.

`ctx` : | context for connection to hald
`udi` : | the Unique Device Id

### LibHalDeviceRemoved ()

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

Type for callback when a device is removed.

`ctx` : | context for connection to hald
`udi` : | the Unique Device Id

### LibHalDeviceNewCapability ()

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

Type for callback when a device gains a new capability.

`ctx` : | context for connection to hald
`udi` : | the Unique Device Id
`capability` : | capability of the device

### LibHalDeviceLostCapability ()

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

Type for callback when a device loses a capability.

`ctx` : | context for connection to hald
`udi` : | the Unique Device Id
`capability` : | capability of the device

### LibHalDevicePropertyModified ()

    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.

`ctx` : | context for connection to hald
`udi` : | the 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

### LibHalDeviceCondition ()

    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.

`ctx` : | context for connection to hald
`udi` : | the Unique Device Id
`condition_name` : | name of the condition, e.g. ProcessorOverheating. Consult the HAL spec for details
`condition_detail` : | detail of condition

### LibHalGlobalInterfaceLockAcquired ()

    void                (*LibHalGlobalInterfaceLockAcquired)
                                                            (LibHalContext *ctx,
                                                             const char *interface_name,
                                                             const char *lock_owner,
                                                             int num_locks);

Type for callback when someone acquires a global lock.

`ctx` : | context for connection to hald
`interface_name` : | the name of the interface
`lock_owner` : | what service acquired the lock
`num_locks` : | number of locks on the interface

### LibHalGlobalInterfaceLockReleased ()

    void                (*LibHalGlobalInterfaceLockReleased)
                                                            (LibHalContext *ctx,
                                                             const char *interface_name,
                                                             const char *lock_owner,
                                                             int num_locks);

Type for callback when someone releases a global lock.

`ctx` : | context for connection to hald
`interface_name` : | the name of the interface
`lock_owner` : | what service released the lock
`num_locks` : | number of locks on the interface

### LibHalInterfaceLockAcquired ()

    void                (*LibHalInterfaceLockAcquired)      (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface_name,
                                                             const char *lock_owner,
                                                             int num_locks);

Type for callback when someone acquires a lock on a device.

`ctx` : | context for connection to hald
`udi` : | the Unique Device Id
`interface_name` : | the name of the interface
`lock_owner` : | what service acquired the lock
`num_locks` : | number of locks on the interface

### LibHalInterfaceLockReleased ()

    void                (*LibHalInterfaceLockReleased)      (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface_name,
                                                             const char *lock_owner,
                                                             int num_locks);

Type for callback when someone acquires a lock on a device.

`ctx` : | context for connection to hald
`udi` : | the Unique Device Id
`interface_name` : | the name of the interface
`lock_owner` : | what service released the lock
`num_locks` : | number of locks on the interface

### LibHalSingletonDeviceAdded ()

    void                (*LibHalSingletonDeviceAdded)       (LibHalContext *ctx,
                                                             const char *udi,
                                                             const LibHalPropertySet *properties);

Type for callback for addon singletons when a device is added

`ctx` : | context for connection to hald
`udi` : | the Unique Device Id
`properties` : | the device's properties

### LibHalSingletonDeviceRemoved ()

    void                (*LibHalSingletonDeviceRemoved)     (LibHalContext *ctx,
                                                             const char *udi,
                                                             const LibHalPropertySet *properties);

Type for callback for addon singletons when a device is added

`ctx` : | context for connection to hald
`udi` : | the Unique Device Id
`properties` : | the device's properties

### libhal_ctx_new ()

    LibHalContext*      libhal_ctx_new                      (void);

Create a new LibHalContext

Returns : | a new uninitialized LibHalContext object

### libhal_ctx_set_cache ()

    dbus_bool_t         libhal_ctx_set_cache                (LibHalContext *ctx,
                                                             dbus_bool_t use_cache);

Enable or disable caching. Note: Caching is not actually implemented yet.

`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

### libhal_ctx_set_dbus_connection ()

    dbus_bool_t         libhal_ctx_set_dbus_connection      (LibHalContext *ctx,
                                                             DBusConnection *conn);

Set DBus connection to use to talk to hald.

`ctx` : | context to set connection for
`conn` : | DBus connection to use
Returns : | TRUE if connection was successfully set, FALSE otherwise

### libhal_ctx_get_dbus_connection ()

    DBusConnection*     libhal_ctx_get_dbus_connection      (LibHalContext *ctx);

Get DBus connection used for talking to hald.

`ctx` : | context to get connection for
Returns : | DBus connection to use or NULL

### libhal_ctx_set_user_data ()

    dbus_bool_t         libhal_ctx_set_user_data            (LibHalContext *ctx,
                                                             void *user_data);

Set user data for the context.

`ctx` : | the context for the connection to hald
`user_data` : | user data
Returns : | TRUE if user data was successfully set, FALSE if otherwise

### libhal_ctx_get_user_data ()

    void*               libhal_ctx_get_user_data            (LibHalContext *ctx);

Get user data for the context.

`ctx` : | the context for the connection to hald
Returns : | opaque pointer stored through `libhal_ctx_set_user_data()` or NULL if not set.

### libhal_ctx_set_device_added ()

    dbus_bool_t         libhal_ctx_set_device_added         (LibHalContext *ctx,
                                                             LibHalDeviceAdded callback);

Set the callback for when a device is added

`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

### libhal_ctx_set_device_removed ()

    dbus_bool_t         libhal_ctx_set_device_removed       (LibHalContext *ctx,
                                                             LibHalDeviceRemoved callback);

Set the callback for when a device is removed.

`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

### libhal_ctx_set_device_new_capability ()

    dbus_bool_t         libhal_ctx_set_device_new_capability
                                                            (LibHalContext *ctx,
                                                             LibHalDeviceNewCapability callback);

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

`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

### libhal_ctx_set_device_lost_capability ()

    dbus_bool_t         libhal_ctx_set_device_lost_capability
                                                            (LibHalContext *ctx,
                                                             LibHalDeviceLostCapability callback);

Set the callback for when a device loses a capability

`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

### libhal_ctx_set_device_property_modified ()

    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.

`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

### libhal_ctx_set_device_condition ()

    dbus_bool_t         libhal_ctx_set_device_condition     (LibHalContext *ctx,
                                                             LibHalDeviceCondition callback);

Set the callback for when a device emits a condition

`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

### libhal_ctx_set_global_interface_lock_acquired ()

    dbus_bool_t         libhal_ctx_set_global_interface_lock_acquired
                                                            (LibHalContext *ctx,
                                                             LibHalGlobalInterfaceLockAcquired callback);

Set the callback for when a global interface lock is acquired.

`ctx` : | the context for the connection to hald
`callback` : | the callback
Returns : | TRUE if callback was successfully set, FALSE otherwise

### libhal_ctx_set_global_interface_lock_released ()

    dbus_bool_t         libhal_ctx_set_global_interface_lock_released
                                                            (LibHalContext *ctx,
                                                             LibHalGlobalInterfaceLockReleased callback);

Set the callback for when a global interface lock is released.

`ctx` : | the context for the connection to hald
`callback` : | the callback
Returns : | TRUE if callback was successfully set, FALSE otherwise

### libhal_ctx_set_interface_lock_acquired ()

    dbus_bool_t         libhal_ctx_set_interface_lock_acquired
                                                            (LibHalContext *ctx,
                                                             LibHalInterfaceLockAcquired callback);

Set the callback for when an interface lock is acquired.

`ctx` : | the context for the connection to hald
`callback` : | the callback
Returns : | TRUE if callback was successfully set, FALSE otherwise

### libhal_ctx_set_interface_lock_released ()

    dbus_bool_t         libhal_ctx_set_interface_lock_released
                                                            (LibHalContext *ctx,
                                                             LibHalInterfaceLockReleased callback);

Set the callback for when an interface lock is released.

`ctx` : | the context for the connection to hald
`callback` : | the callback
Returns : | TRUE if callback was successfully set, FALSE otherwise

### libhal_ctx_set_singleton_device_added ()

    dbus_bool_t         libhal_ctx_set_singleton_device_added
                                                            (LibHalContext *ctx,
                                                             LibHalSingletonDeviceAdded callback);

Set the callback for when a singleton should handle a new device

`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

### libhal_ctx_set_singleton_device_removed ()

    dbus_bool_t         libhal_ctx_set_singleton_device_removed
                                                            (LibHalContext *ctx,
                                                             LibHalSingletonDeviceRemoved callback);

Set the callback for when a singleton should discard a device

`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

### libhal_ctx_init ()

    dbus_bool_t         libhal_ctx_init                     (LibHalContext *ctx,
                                                             DBusError *error);

Initialize the connection to hald.

`ctx` : | Context for connection to hald (D-BUS 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

### libhal_ctx_shutdown ()

    dbus_bool_t         libhal_ctx_shutdown                 (LibHalContext *ctx,
                                                             DBusError *error);

Shut down a connection to hald.

`ctx` : | the context for the 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

### libhal_ctx_free ()

    dbus_bool_t         libhal_ctx_free                     (LibHalContext *ctx);

Free a LibHalContext resource.

`ctx` : | pointer to a LibHalContext
Returns : | TRUE

### libhal_ctx_init_direct ()

    LibHalContext*      libhal_ctx_init_direct              (DBusError *error);

Create an already initialized connection to hald. This function should only be used by HAL helpers.

`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | A pointer to an already initialized LibHalContext

### libhal_get_all_devices ()

    char**              libhal_get_all_devices              (LibHalContext *ctx,
                                                             int *num_devices,
                                                             DBusError *error);

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

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

### libhal_device_exists ()

    dbus_bool_t         libhal_device_exists                (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);

Determine if a device exists.

`ctx` : | the context for the connection to hald
`udi` : | the Unique device id.
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | TRUE if the device exists

### libhal_device_print ()

    dbus_bool_t         libhal_device_print                 (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);

Print a device to stdout; useful for debugging.

`ctx` : | the context for the connection to hald
`udi` : | the 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

### libhal_device_property_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.

`ctx` : | the context for the connection to hald
`udi` : | the 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

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

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id
`key` : | the 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.

### libhal_device_get_property_int ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the 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)

### libhal_device_get_property_uint64 ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the 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)

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

`ctx` : | the context for the connection to hald
`udi` : | the 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)

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

`ctx` : | the context for the connection to hald
`udi` : | the 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)

### libhal_device_get_property_strlist ()

    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.

`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

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

`ctx` : | the context for the connection to hald
`udi` : | the 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.

### libhal_device_set_property_int ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the 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.

### libhal_device_set_property_uint64 ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the 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.

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

`ctx` : | the context for the connection to hald
`udi` : | the 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.

### libhal_device_set_property_bool ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the 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.

### libhal_device_property_strlist_append ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the 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.

### libhal_device_property_strlist_prepend ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the 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.

### libhal_device_property_strlist_remove_index ()

    dbus_bool_t         libhal_device_property_strlist_remove_index
                                                            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *key,
                                                             unsigned int idx,
                                                             DBusError *error);

Remove a specified string from a property of type strlist.

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id
`key` : | name of the property
`idx` : | 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.

### libhal_device_property_strlist_remove ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id
`key` : | name of the property
`value` : | the string to 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.

### libhal_device_remove_property ()

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

Remove a property.

`ctx` : | the context for the connection to hald
`udi` : | the 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

### libhal_device_get_property_type ()

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

Query a property type of a device.

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id
`key` : | name of the property
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | A LibHalPropertyType. LIBHAL_PROPERTY_TYPE_INVALID is return if the property doesn't exist.

### struct LibHalChangeSet_s

    struct LibHalChangeSet_s;

### LibHalChangeSet

    typedef struct LibHalChangeSet_s LibHalChangeSet;

### libhal_device_new_changeset ()

    LibHalChangeSet*    libhal_device_new_changeset         (const char *udi);

Request a new changeset object. Used for changing multiple properties at once. Useful when performance is critical and also for atomically updating several properties.

`udi` : | unique device identifier
Returns : | A new changeset object or NULL on error

### libhal_changeset_set_property_string ()

    dbus_bool_t         libhal_changeset_set_property_string
                                                            (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             const char *value);

Set a property.

`changeset` : | the changeset
`key` : | key of property
`value` : | the value to set
Returns : | FALSE on OOM

### libhal_changeset_set_property_int ()

    dbus_bool_t         libhal_changeset_set_property_int   (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             dbus_int32_t value);

Set a property.

`changeset` : | the changeset
`key` : | key of property
`value` : | the value to set
Returns : | FALSE on OOM

### libhal_changeset_set_property_uint64 ()

    dbus_bool_t         libhal_changeset_set_property_uint64
                                                            (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             dbus_uint64_t value);

Set a property.

`changeset` : | the changeset
`key` : | key of property
`value` : | the value to set
Returns : | FALSE on OOM

### libhal_changeset_set_property_double ()

    dbus_bool_t         libhal_changeset_set_property_double
                                                            (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             double value);

Set a property.

`changeset` : | the changeset
`key` : | key of property
`value` : | the value to set
Returns : | FALSE on OOM

### libhal_changeset_set_property_bool ()

    dbus_bool_t         libhal_changeset_set_property_bool  (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             dbus_bool_t value);

Set a property.

`changeset` : | the changeset
`key` : | key of property
`value` : | the value to set
Returns : | FALSE on OOM

### libhal_changeset_set_property_strlist ()

    dbus_bool_t         libhal_changeset_set_property_strlist
                                                            (LibHalChangeSet *changeset,
                                                             const char *key,
                                                             const char **value);

Set a property.

`changeset` : | the changeset
`key` : | key of property
`value` : | the value to set - NULL terminated array of strings
Returns : | FALSE on OOM

### libhal_device_commit_changeset ()

    dbus_bool_t         libhal_device_commit_changeset      (LibHalContext *ctx,
                                                             LibHalChangeSet *changeset,
                                                             DBusError *error);

Commit a changeset to the daemon.

`ctx` : | the context for the connection to hald
`changeset` : | the changeset to commit
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | True if the changeset was committed on the daemon side

### libhal_device_free_changeset ()

    void                libhal_device_free_changeset        (LibHalChangeSet *changeset);

Free a changeset.

`changeset` : | the changeset to free

### libhal_device_get_all_properties ()

    LibHalPropertySet*  libhal_device_get_all_properties    (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);

Retrieve all the properties on a device.

`ctx` : | the context for the connection to hald
`udi` : | the 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()`.

### libhal_property_set_sort ()

    void                libhal_property_set_sort            (LibHalPropertySet *set);

Sort all properties according to property name.

`set` : | property-set to sort

### libhal_free_property_set ()

    void                libhal_free_property_set            (LibHalPropertySet *set);

Free a property set earlier obtained with `libhal_device_get_all_properties()`.

`set` : | property-set to free

### libhal_property_set_get_num_elems ()

    unsigned int        libhal_property_set_get_num_elems   (LibHalPropertySet *set);

Get the number of properties in a property set.

`set` : | property set to consider
Returns : | number of properties in given property set

### libhal_ps_get_type ()

    LibHalPropertyType  libhal_ps_get_type                  (const LibHalPropertySet *set,
                                                             const char *key);

Get the type of a given property.

`set` : | property set
`key` : | name of property to inspect
Returns : | the LibHalPropertyType of the given property, LIBHAL_PROPERTY_TYPE_INVALID if property is not in the set

### libhal_ps_get_string ()

    const char*         libhal_ps_get_string                (const LibHalPropertySet *set,
                                                             const char *key);

Get the value of a property of type string.

`set` : | property set
`key` : | name of property to inspect
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. NULL if property is not in the set or not a string

### libhal_ps_get_int32 ()

    dbus_int32_t        libhal_ps_get_int32                 (const LibHalPropertySet *set,
                                                             const char *key);

`set` : |
`key` : |
Returns : |

### libhal_ps_get_uint64 ()

    dbus_uint64_t       libhal_ps_get_uint64                (const LibHalPropertySet *set,
                                                             const char *key);

Get the value of a property of type unsigned integer.

`set` : | property set
`key` : | name of property to inspect
Returns : | property value (64-bit unsigned integer)

### libhal_ps_get_double ()

    double              libhal_ps_get_double                (const LibHalPropertySet *set,
                                                             const char *key);

Get the value of a property of type double.

`set` : | property set
`key` : | name of property to inspect
Returns : | property value (IEEE754 double precision float)

### libhal_ps_get_bool ()

    dbus_bool_t         libhal_ps_get_bool                  (const LibHalPropertySet *set,
                                                             const char *key);

Get the value of a property of type bool.

`set` : | property set
`key` : | name of property to inspect
Returns : | property value (bool)

### struct LibHalPropertySetIterator_s

    struct LibHalPropertySetIterator_s {
    	LibHalPropertySet *set;    /**< Property set we are iterating over */
    	unsigned int idx;          /**< Index into current element */
    	LibHalProperty *cur_prop;  /**< Current property being visited */
    	void *reservered0;         /**< Reserved for future use */
    	void *reservered1;         /**< Reserved for future use */
    };

### LibHalPropertySetIterator

    typedef struct LibHalPropertySetIterator_s LibHalPropertySetIterator;

Iterator for inspecting all properties. Do not access any members; use the libhal_psi_* family of functions instead.

### libhal_psi_init ()

    void                libhal_psi_init                     (LibHalPropertySetIterator *iter,
                                                             LibHalPropertySet *set);

Initialize a property set iterator.

`iter` : | iterator object
`set` : | property set to iterate over

### libhal_psi_has_more ()

    dbus_bool_t         libhal_psi_has_more                 (LibHalPropertySetIterator *iter);

Determine whether there are more properties to iterate over.

`iter` : | iterator object
Returns : | TRUE if there are more properties, FALSE otherwise.

### libhal_psi_next ()

    void                libhal_psi_next                     (LibHalPropertySetIterator *iter);

Advance iterator to next property.

`iter` : | iterator object

### libhal_psi_get_type ()

    LibHalPropertyType  libhal_psi_get_type                 (LibHalPropertySetIterator *iter);

Get type of property.

`iter` : | iterator object
Returns : | the property type at the iterator's position

### libhal_psi_get_key ()

    char*               libhal_psi_get_key                  (LibHalPropertySetIterator *iter);

Get the key of a property.

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

### libhal_psi_get_string ()

    char*               libhal_psi_get_string               (LibHalPropertySetIterator *iter);

Get the value of a property of type string.

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

### libhal_psi_get_int ()

    dbus_int32_t        libhal_psi_get_int                  (LibHalPropertySetIterator *iter);

Get the value of a property of type signed integer.

`iter` : | iterator object
Returns : | property value (32-bit signed integer)

### libhal_psi_get_uint64 ()

    dbus_uint64_t       libhal_psi_get_uint64               (LibHalPropertySetIterator *iter);

Get the value of a property of type unsigned integer.

`iter` : | iterator object
Returns : | property value (64-bit unsigned integer)

### libhal_psi_get_double ()

    double              libhal_psi_get_double               (LibHalPropertySetIterator *iter);

Get the value of a property of type double.

`iter` : | iterator object
Returns : | property value (IEEE754 double precision float)

### libhal_psi_get_bool ()

    dbus_bool_t         libhal_psi_get_bool                 (LibHalPropertySetIterator *iter);

Get the value of a property of type bool.

`iter` : | iterator object
Returns : | property value (bool)

### libhal_psi_get_strlist ()

    char**              libhal_psi_get_strlist              (LibHalPropertySetIterator *iter);

Get the value of a property of type string list.

`iter` : | iterator object
Returns : | pointer to array of strings

### libhal_string_array_length ()

    unsigned int        libhal_string_array_length          (char **str_array);

Get the length of an array of strings.

`str_array` : | array of strings to consider
Returns : | Number of strings in array

### libhal_free_string_array ()

    void                libhal_free_string_array            (char **str_array);

Frees a NULL-terminated array of strings. If passed NULL, does nothing.

`str_array` : | the array to be freed

### libhal_free_string ()

    void                libhal_free_string                  (char *str);

Used to free strings returned by libhal.

`str` : | the nul-terminated sting to free

### libhal_new_device ()

    char*               libhal_new_device                   (LibHalContext *ctx,
                                                             DBusError *error);

Create a new device object which will be hidden from applications until the `CommitToGdl()`, ie. `libhal_device_commit_to_gdl()`, method is called. Note that the program invoking this method needs to run with super user privileges.

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

### libhal_device_commit_to_gdl ()

    dbus_bool_t         libhal_device_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_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.

`ctx` : | the context for the connection to hald
`temp_udi` : | the temporary unique device id as returned by `libhal_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.

### libhal_remove_device ()

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

`ctx` : | the context for the connection to hald
`udi` : | the 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

### libhal_merge_properties ()

    dbus_bool_t         libhal_merge_properties             (LibHalContext *ctx,
                                                             const char *target_udi,
                                                             const char *source_udi,
                                                             DBusError *error);

Merge properties from one device to another.

`ctx` : | the context for the connection to hald
`target_udi` : | the Unique device id of target device to merge to
`source_udi` : | the 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

### libhal_device_matches ()

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

`ctx` : | the context for the connection to hald
`udi1` : | the Unique Device Id for device 1
`udi2` : | the Unique Device Id for device 2
`property_namespace` : | the 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.

### libhal_manager_find_device_string_match ()

    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.

`ctx` : | the context for the connection to hald
`key` : | name of the property
`value` : | the 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()`

### libhal_device_add_capability ()

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

Assign a capability to a device.

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id
`capability` : | the capability name to add
`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

### libhal_device_query_capability ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id
`capability` : | the 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

### libhal_find_device_by_capability ()

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

Find devices with a given capability.

`ctx` : | the context for the connection to hald
`capability` : | the 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()`

### libhal_device_property_watch_all ()

    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.

`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

### libhal_device_add_property_watch ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | TRUE only if the operation succeeded

### libhal_device_remove_property_watch ()

    dbus_bool_t         libhal_device_remove_property_watch (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);

Remove a watch on a device.

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | TRUE only if the operation succeeded

### libhal_device_lock ()

    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.

`ctx` : | the context for the connection to hald
`udi` : | the 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

### libhal_device_unlock ()

    dbus_bool_t         libhal_device_unlock                (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);

Release an advisory lock on the device.

`ctx` : | the context for the connection to hald
`udi` : | the 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

### libhal_device_rescan ()

    dbus_bool_t         libhal_device_rescan                (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);

TODO document me.

`ctx` : | the context for the connection to hald
`udi` : | the Unique id of device
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | Whether the operation succeeded

### libhal_device_reprobe ()

    dbus_bool_t         libhal_device_reprobe               (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);

TODO document me.

`ctx` : | the context for the connection to hald
`udi` : | the Unique id of device
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | Whether the operation succeeded

### libhal_device_emit_condition ()

    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. Can only be used from hald helpers.

`ctx` : | the context for the connection to hald
`udi` : | the 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

### libhal_device_claim_interface ()

    dbus_bool_t         libhal_device_claim_interface       (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface_name,
                                                             const char *introspection_xml,
                                                             DBusError *error);

Claim an interface for a device. All messages to this interface will be forwarded to the helper. Can only be used from hald helpers.

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id
`interface_name` : | Name of interface to claim, e.g. org.freedesktop.Hal.Device.FoobarKindOfThing
`introspection_xml` : | Introspection XML containing what would be inside the interface XML tag
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | TRUE if interface was claimed, FALSE otherwise

### libhal_device_addon_is_ready ()

    dbus_bool_t         libhal_device_addon_is_ready        (LibHalContext *ctx,
                                                             const char *udi,
                                                             DBusError *error);

HAL addon's must call this method when they are done initializing the device object. The HAL daemon will wait for all addon's to call this.

Can only be used from hald helpers.

`ctx` : | the context for the connection to hald
`udi` : | the Unique Device Id this addon is handling
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | TRUE if the HAL daemon received the message, FALSE otherwise

### libhal_device_singleton_addon_is_ready ()

    dbus_bool_t         libhal_device_singleton_addon_is_ready
                                                            (LibHalContext *ctx,
                                                             const char *command_line,
                                                             DBusError *error);

HAL singleton addon's must call this method when they are done initializing the device object. The HAL daemon will wait for all addon's to call this.

Can only be used from hald helpers.

`ctx` : | the context for the connection to hald
`command_line` : | commandline singleton was started with
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | TRUE if the HAL daemon received the message, FALSE otherwise

### libhal_device_acquire_interface_lock ()

    dbus_bool_t         libhal_device_acquire_interface_lock
                                                            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface,
                                                             dbus_bool_t exclusive,
                                                             DBusError *error);

Releases a lock on an interface for a specific device.

`ctx` : | the context for the connection to hald
`udi` : | the Unique id of device
`interface` : | the intername name to lock
`exclusive` : | whether the lock should be exclusive
`error` : | pointer to an initialized dbus error object for returning errors
Returns : | TRUE iff the lock was acquired

### libhal_device_release_interface_lock ()

    dbus_bool_t         libhal_device_release_interface_lock
                                                            (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface,
                                                             DBusError *error);

Acquires a lock on an interface for a specific device.

`ctx` : | the context for the connection to hald
`udi` : | the Unique id of device
`interface` : | the intername name to unlock
`error` : | pointer to an initialized dbus error object for returning errors
Returns : | TRUE iff the lock was released.

### libhal_acquire_global_interface_lock ()

    dbus_bool_t         libhal_acquire_global_interface_lock
                                                            (LibHalContext *ctx,
                                                             const char *interface,
                                                             dbus_bool_t exclusive,
                                                             DBusError *error);

Acquires a global lock on an interface.

`ctx` : | the context for the connection to hald
`interface` : | the intername name to lock
`exclusive` : | whether the lock should be exclusive
`error` : | pointer to an initialized dbus error object for returning errors
Returns : | TRUE iff the lock was acquired

### libhal_release_global_interface_lock ()

    dbus_bool_t         libhal_release_global_interface_lock
                                                            (LibHalContext *ctx,
                                                             const char *interface,
                                                             DBusError *error);

Releases a global lock on an interface.

`ctx` : | the context for the connection to hald
`interface` : | the intername name to unlock
`error` : | pointer to an initialized dbus error object for returning errors
Returns : | TRUE iff the lock was released

### libhal_device_is_caller_locked_out ()

    dbus_bool_t         libhal_device_is_caller_locked_out  (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface,
                                                             const char *caller,
                                                             DBusError *error);

Determines whether a given process on the system message bus is locked out from an interface on a specific device. Only HAL helpers are privileged to use this method.

`ctx` : | the context for the connection to hald
`udi` : | the Unique id of device
`interface` : | the intername name to check
`caller` : | the caller to check for
`error` : | pointer to an initialized dbus error object for returning errors
Returns : | Whether the given caller is locked out

### libhal_device_is_locked_by_others ()

    dbus_bool_t         libhal_device_is_locked_by_others   (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *interface,
                                                             DBusError *error);

Determines whether a determines other processes than the caller holds a lock on the given device.

`ctx` : | the context for the connection to hald
`udi` : | the Unique id of device
`interface` : | the intername name to check
`error` : | pointer to an initialized dbus error object for returning errors or NULL
Returns : | If another process is holding a lock on the device

### libhal_device_is_caller_privileged ()

    char*               libhal_device_is_caller_privileged  (LibHalContext *ctx,
                                                             const char *udi,
                                                             const char *action,
                                                             const char *caller,
                                                             DBusError *error);

Determines if a given caller have a given privilege on a given device. Will always error out if HAL is not built with PolicyKit support.

`ctx` : | the context for the connection to hald
`udi` : | the Unique id of device
`action` : | the action to check for
`caller` : | the caller to check for
`error` : | pointer to an initialized dbus error object for returning errors
Returns : | The textual reply from PolicyKit. See the PolicyKitResult enumeration in the PolicyKit documentation for details. The caller is responsible for freeing this string with the function `libhal_free_string()`.