# D-Bus interfaces

All of the HAL D-Bus interfaces are introspectable using the standard D-Bus introspection methods (e.g. they all implement the `org.freedesktop.DBus.Introspectable` interface). For example, a command like

    $ dbus-send --system --print-reply --dest=org.freedesktop.Hal \
                /org/freedesktop/Hal/devices/computer             \
                org.freedesktop.DBus.Introspectable.Introspect

will print out the introspection XML for what interfaces (ie. methods and signals) the given hal device object supports. For brevity, the `org.freedesktop.Hal` prefix have been stripped from the exceptions listed in the following sections.

Also note that other exceptions than the ones listed may be thrown; for example the `org.freedesktop.Hal.Device.InterfaceLocked` exception may be thrown regardless of how the interface is implemented (depending on if some other process is holding a lock on the device cf. locking); if PolicyKit support is enabled, the `org.freedesktop.Hal.Device.PermissionDeniedByPolicy` exception may be thrown (the two first words in the exception detail is resp. a) the privilege the caller didn't have; b) the textual result code from PolicyKit specifying if the caller can obtain the privilege) if the caller is not privileged and so on.

## org.freedesktop.Hal.Device interface

Every hal device object (e.g. objects where the object path is prefixed with `/org/freedesktop/Hal/devices/`) implements this interface. It provides generic functionality. The following methods are available:

Method | Returns | Parameters | Throws | Description
GetProperty | Variant | String key | NoSuchProperty | Get property.
GetPropertyString | String | String key | NoSuchProperty, TypeMismatch | Get property.
GetPropertyStringList | String[] | String key | NoSuchProperty, TypeMismatch | Get property.
GetPropertyInteger | Int | String key | NoSuchProperty, TypeMismatch | Get property.
GetPropertyUInt64 | UInt64 | String key | NoSuchProperty, TypeMismatch | Get property.
GetPropertyBoolean | Bool | String key | NoSuchProperty, TypeMismatch | Get property.
GetPropertyDouble | Double | String key | NoSuchProperty, TypeMismatch | Get property.
SetProperty | Variant | String key | PermissionDenied | Set property.
SetPropertyString | String | String key | PermissionDenied, TypeMismatch | Set property.
SetPropertyStringList | String[] | String key | PermissionDenied, TypeMismatch | Set property.
SetPropertyInteger | Int | String key | PermissionDenied, TypeMismatch | Set property.
SetPropertyUInt64 | UInt64 | String key | PermissionDenied, TypeMismatch | Set property.
SetPropertyBoolean | Bool | String key | PermissionDenied, TypeMismatch | Set property.
SetPropertyDouble | Double | String key | PermissionDenied, TypeMismatch | Set property.
RemoveProperty |  | String key | NoSuchProperty, PermissionDenied | Remove a property.
GetPropertyType | Int | String key | NoSuchProperty | Get the type of a property. Returns the D-Bus type as an integer.
PropertyExists | Bool | String key |  | Determine if a property exists.
AddCapability |  | String capability | PermissionDenied | Adds a capability to a device.
QueryCapability | Bool | String capability |  | Determine if a device have a capability.
Lock | Bool | String reason | DeviceAlreadyLocked | Acquires an advisory lock on the device. Returns TRUE if the lock was acquired.
Unlock | Bool |  | DeviceNotLocked | Releases an advisory lock on the device. Returns TRUE if the lock was released.
AcquireInterfaceLock |  | String interface_name, Bool exclusive | PermissionDenied, Device.InterfaceAlreadyLocked | Acquires a lock on an interface for a specific device. See locking for details.
ReleaseInterfaceLock |  | String interface_name | PermissionDenied, Device.InterfaceNotLocked | Releases a lock on an interface for a specific device. See locking for details.
IsCallerLockedOut | Bool | String interface_name, String caller_unique_name | PermissionDenied | 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. See locking for details.
IsCallerPrivileged | String | String privilege, String caller_unique_name | PermissionDenied, Error | Determines whether a given process on the system message bus is authorized according to PolicyKit on a specific device for a specific PolicyKit privilege. Unprivileged callers (e.g. with a non-zero uid) can only ask about `caller_unique_name` that matches their own uid; if this is violated `PermissionDenied` will be thrown. This can be used ahead of time to see if a given call will succeed or if it requires privilege elevation (TODO: clarify this once PolicyKit can auth over D-Bus). Returns the textual representation of a PolKitResult value on success. If HAL is not built with PolicyKit support, this method always throws the `org.freedesktop.Hal.Device.Error` exception.
IsLockedByOthers | Bool | String interface_name |  | Determines whether a determines other processes than the caller holds a lock on the given device. See locking for details.
StringListAppend |  | String key, String value | PermissionDenied, TypeMismatch | Appends an item to a string list.
StringListPrepend |  | String key, String value | PermissionDenied, TypeMismatch | Prepends an item to a string list.
StringListRemove |  | String key, String value | PermissionDenied, TypeMismatch | Removes an item from a string list.
EmitCondition | Bool | String name, String details | PermissionDenied | Emit a condition on a device object.
Rescan | Bool |  | PermissionDenied | Force an updates of the properties of a device object by rereading data that is not monitored for changes.
Reprobe | Bool |  | PermissionDenied | Cause a synthetic remove and subsequent add of the given device object including all children beneath it. Will generate at least one pair of DeviceRemoved() and DeviceAdded() signals on the Manager interface.
ClaimInterface | Bool | String name, String introspection_xml | PermissionDenied | An addon can use this method for making the HAL daemon route all D-Bus calls on the given interface to the addon via the peer to peer D-Bus connection between the addon and the HAL daemon.
AddonIsReady | Bool |  | PermissionDenied | An addon needs to call this method when it's ready for the device to be announced on D-Bus. The rationale for this method is to allow an addon to modify the device object and claim interfaces before the device is announced on D-Bus.

The following signals are emitted:

Signal | Parameters | Description
PropertyModified | Int num_changes, Array of struct {String property_name, Bool removed, Bool added} | One or more properties on the device object have changed.
Condition | String name, String details | A generic mechanism used to specify a device condition that cannot be expressed in device properties. (NOTE: newly written code should use dedicated signals on a dedicated interface.).
InterfaceLockAcquired | String lock_name, String lock_owner, Int num_holders | Sent when a process acquires an interface lock on the device.
InterfaceLockReleased | String lock_name, String lock_owner, Int num_holders | Sent when a process releases an interface lock on the device.

## org.freedesktop.Hal.Device.AccessControl interface

This interface provides a mechanism for discovering when an ACL is added or removed for a device file. The following signals are available:

Method | Parameters | Description
ACLAdded | UInt unix_user_id | Emitted when an ACL have been added for a UNIX user on a device object with the `access_control` capability.
ACLRemoved | UInt unix_user_id | Emitted when an ACL have been removed for a UNIX user on a device object with the `access_control` capability.

This interface does not export any methods.

## org.freedesktop.Hal.Device.CPUFreq interface

This interface provides a mechanism to configure CPU frequency scaling. The following methods are available:

Method | Returns | Parameters | Throws | Description
GetCPUFreqAvailableGovernors | String[] |  |  | Retrieves a list of available CPU scaling governors.
GetCPUFreqGovernor | String |  |  | Get currently selected CPU Frequency governor.
SetCPUFreqGovernor | Void | String governor | CPUFreq.UnknownGovernor | Selects a CPU frequency scaling governor for all CPUFreq interfaces the kernel provides. If the userspace governor is set, this interface also contains a proper scaling mechanism.
SetCPUFreqPerformance | Void | Int (1 to 100) | CPUFreq.NoSuitableGovernor | Sets the performance of the dynamic scaling mechanism. This method summarizes and abstracts all the different settings which can be taken for dynamic frequency adjustments, like at which load to switch up frequency or how many steps the mechanism should traverse until reaching the maximum frequency. The higher the value, the more performance you get. Respectively, the higher the value, the sooner and the more often the frequency is switched up.
GetCPUFreqPerformance | Int |  | CPUFreq.NoSuitableGovernor | Get the tuning value for the governor.
SetCPUFreqConsiderNice | Void | Bool consider_niced_processes | CPUFreq.NoSuitableGovernor | Whether or not niced processes should be considered on CPU load calculation. If niced processes are considered, they can cause a frequency increment although their absolute load percentage wouldn't trigger the scaling mechanism to switch up the frequency. The default setting is 'false'.
GetCPUFreqConsiderNice | Bool |  | CPUFreq.NoSuitableGovernor | Whether nice'ed processes are considered by the governor.

This interface does not emit any signals.

## org.freedesktop.Hal.Device.DockStation interface

This interface provides a mechanism to deal with dock stations.

Method | Returns | Parameters | Throws | Description
Undock | Int | Void | DockStation.NotDocked | Undock the system from a dock station

This interface does not emit any signals.

## org.freedesktop.Hal.Device.KeyboardBacklight interface

This interface provides a mechanism to get/set the brightness of the keyboard backlight. The following methods are available:

Method | Returns | Parameters | Throws | Description
GetBrightness | Int |  |  | Get the current brightness.
SetBrightness |  | Int brightness |  | Set the current brightness.

This interface does not emit any signals.

## org.freedesktop.Hal.Device.KillSwitch interface

This interface provides a mechanism for both querying whether a radio is on as well as turning it on and off. The following methods are available:

Method | Returns | Parameters | Throws | Description
GetPower | Int |  |  | Returns 1 if, and only if, the power is on.
SetPower |  | Bool |  | Set the power of the radio.

This interface does not emit any signals.

## org.freedesktop.Hal.Device.Leds interface

This interface provides a mechanism to get/set the brightness of a LED (light-emitting diode). The following methods are available:

Method | Returns | Parameters | Throws | Description
GetBrightness | Int |  |  | Get the current brightness of the LED.
SetBrightness |  | Int brightness |  | Set the current brightness of the LED. The value 0 deactivate normally the LED, any higher value active the LED again.

This interface does not emit any signals.

## org.freedesktop.Hal.Device.LaptopPanel interface

This interface provides a mechanism to get/set the brightness of a laptop panel. The following methods are available:

Method | Returns | Parameters | Throws | Description
GetBrightness | Int |  |  | Get the current brightness.
SetBrightness |  | Int brightness |  | Set the current brightness.

This interface does not emit any signals.

## org.freedesktop.Hal.Device.LightSensor interface

This interface provides a mechanism to get information from a light sensor. The following methods are available:

Method | Returns | Parameters | Throws | Description
GetBrightness | Int[] |  |  | The current brightness as measured by the light sensor.

This interface does not emit any signals.

## org.freedesktop.Hal.Device.Storage interface

This interface provides a mechanism to interact with a storage device. The following methods are available:

Method | Returns | Parameters | Throws | Description
Eject | Int | String[] options | Volume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidEjectOption | Unmounts all volumes and possibly ejects the media. Note that this method is not only restricted to optical drives.
CloseTray | Int | String[] options | Storage.InvalidCloseTrayOption | Attempts to close the tray. Only really makes sense for (optical) drives that uses a tray loading mechanism.

This interface does not emit any signals.

## org.freedesktop.Hal.Device.Storage.Removable interface

This interface provides a mechanism to interact with a storage device that uses removable media. The following methods are available:

Method | Returns | Parameters | Throws | Description
CheckForMedia | Bool |  |  | Polls a storage device for media.

This interface does not emit any signals.

## org.freedesktop.Hal.Device.SystemPowerManagement interface

This interface provides a mechanism to affect system-wide power management. Normally only the root computer device object (`/org/freedesktop/Hal/devices/computer`) implements this interface. The following methods are available:

Method | Returns | Parameters | Throws | Description
Suspend | Int | Int num_secs_to_wakeup | SystemPowerManagement.NotSupported, SystemPowerManagement.AlarmNotSupported | Puts the system in a suspended state (typically ACPI S3) for `num_secs_to_wakeup` seconds. If the given time is zero, the system is put in the suspended state indefinitely. If wake-up isn't supported the the AlarmNotSupported exception is thrown. Latency for the system to return to an operational state is in the order of magnitude of 5 seconds.
Hibernate | Int |  | SystemPowerManagement.NotSupported | Save system state to persistent storage and power off the system (typically ACPI S4). Latency for the system to return to an operational state is in the order of magnitude of one minute.
SuspendHybrid | Int | Int num_secs_to_wakeup | SystemPowerManagement.NotSupported, SystemPowerManagement.AlarmNotSupported | Puts the system in a suspended state (typically ACPI S3) for `num_secs_to_wakeup` seconds but also write the system state to persistent storage so the system can resume even if power is removed. Like with Suspend(), if the given time is zero, the system is put in the suspended state indefinitely. If wake-up isn't supported the the AlarmNotSupported exception is thrown.
Shutdown | Int |  | SystemPowerManagement.NotSupported | Shut down the system.
Reboot | Int |  | SystemPowerManagement.NotSupported | Reboot the system.
SetPowerSave | Int | Bool should_save_power | SystemPowerManagement.NotSupported | If the boolean passed is TRUE, the system will be configured to save as much power as possible by e.g. enabling `laptop mode` to avoid spinning up disks. Typically, power management daemons will call this method when it determines that the system is running on battery power.

This interface does not emit any signals.

Implementors of power management daemons should make sure that their software respects the locking guidelines described in interfaces.

## org.freedesktop.Hal.Device.Volume interface

This interface provides a mechanism to interact with a volume that has a mountable file system. The following methods are available:

Method | Returns | Parameters | Throws | Description
Mount | Int | String mount_point, String fstype, String[] options | Volume.PermissionDenied, Volume.AlreadyMounted, Volume.InvalidMountOption, Volume.UnknownFilesystemType, Volume.InvalidMountPoint, Volume.MountPointNotAvailable, Volume.CannotRemount | Mounts a volume.
Unmount | Int | String[] options | Volume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidUnmountOption | Unmount a volume.
Eject | Int | String[] options | Volume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidEjectOption | Unmounts all volumes from the originating drive and possibly ejects the media. Note that this method is not only restricted to optical drives.

This interface does not emit any signals.

If a volume originates from a storage device (and all volumes do), it also is checked whether the caller is locked out of the `org.freedesktop.Hal.Device.Storage` interface of the originating storage device. As a corollary, it is sufficient to just either a) lock the storage device; or b) globally lock the `org.freedesktop.Hal.Device.Storage` interface if one wants to lock out callers from mounting volumes from either a specific drive or all drives.

## org.freedesktop.Hal.Device.Volume.Crypto interface

This interface provides a mechanism to interact with a volume that is encrypted at the block layer. The following methods are available:

Method | Returns | Parameters | Throws | Description
Setup | Int | String passphrase | Volume.Crypto.CryptSetupMissing, Volume.Crypto.SetupError, Volume.Crypto.SetupPasswordError | Unlocks an encrypted file system. If successful, a cleartext volume will appear.
Teardown | Int |  | Volume.Crypto.TeardownError | Teardown the cleartext volume.

This interface does not emit any signals.

For objects implementing this interface, it will also be checked if the caller is locked out of the Volume interface on the device (and per interface-device-volume this includes checking whether the caller is locked out of the `org.freedesktop.Hal.Device.Storage` interface for the storage device that the volume originates from).

## org.freedesktop.Hal.Device.WakeOnLan interface

This interface provides a mechanism to configure Wake On LAN capabilities. The following methods are available:

Method | Returns | Parameters | Throws | Description
GetSupported | Bool |  | WakeOnLan.NoEthtool | Get if device supports Wake On LAN
GetEnabled | Bool |  | WakeOnLan.NoEthtool | Get if Wake On LAN is enabled
SetEnabled | Void | Bool | WakeOnLan.NoEthtool | Enable or disable Wake On LAN

This interface does not emit any signals.

## org.freedesktop.Hal.Manager interface

Only the `/org/freedesktop/Hal/Manager` object implements this interface. It's primarily used to discover devices. The following methods are available:

Method | Returns | Parameters | Throws | Description
GetAllDevices | Objref[] |  |  | Get all UDI's in the database.
DeviceExists | Bool |  |  | Determines if a given object exists.
FindDeviceStringMatch | Objref[] | String key, String value |  | Find devices for which the given string property assumes the given value.
FindDeviceByCapability | Objref[] | String capability |  | Finds devices of the given capability.
NewDevice | Objref |  | PermissionDenied | Creates a new device object in the temporary device list (TDL) and return the UDI. Caller must be uid 0.
Remove |  | Objref tmp_udi | NoSuchDevice, PermissionDenied | Removes a device object that was created in the TDL. Caller must be uid 0.
CommitToGdl |  | Objref tmp_udi, Objref udi | NoSuchDevice, PermissionDenied | Moves a device from the temporary device list (TDL) to the global device list (GDL). Caller must be uid 0.
AcquireGlobalInterfaceLock |  | String interface_name, Bool exclusive | Device.InterfaceAlreadyLocked | Acquires a global lock on an interface. See locking for details.
ReleaseGlobalInterfaceLock |  | String interface_name | Device.InterfaceNotLocked | Releases a global lock on an interface. See locking for details.
SingletonAddonIsReady |  | String command_line | PermissionDenied, SyntaxError | Called by singleton addons to signal that they are ready to handle devices. A singleton addon should implement the org.freedesktop.Hal.Singleton interface.

The following signals are emitted:

Signal | Parameters | Description
DeviceAdded | Objref obj | A device was added to the global device list (GDL).
DeviceRemoved | Objref obj | A device was removed from the global device list (GDL).
NewCapability | Objref obj, String cap | A device gained a new capability.
GlobalInterfaceLockAcquired | String lock_name, String lock_owner, Int num_holders | Sent when a process acquires a global interface lock.
GlobalInterfaceLockReleased | String lock_name, String lock_owner, Int num_holders | Sent when a process releases a global interface lock.

## org.freedesktop.Hal.SingletonAddon interface

This interface is provided by singleton addons to allow the Manager to request handling of new devices and removal of old ones. This differs from other HAL interface definitions in that it is provided by addon processes, rather than the HAL daemon itself. It should be exported on the path `/org/freedesktop/Hal/Manager`.

Method | Returns | Parameters | Throws | Description
`DeviceAdded` | `String udi` `Dict(String,Variant) property_set` |  |  | Called by the HAL Manager when a device is added that has this singleton listed in `info.addons.singleton` An addon implementing this function should start handling the device before returning, and keep track that is is handling this udi.
`DeviceRemoved` | `String udi` `Dict(String,Variant) property_set` |  |  | Called by the HAL Manager when a device is added that has this singleton listed in `info.addons.singleton` The implementer of this function should keep track of which devices it is still handling and exit when no longer handling any devices.

This interface does not export any methods.