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. ); 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:
MethodReturnsParametersThrowsDescriptionGetPropertyVariantString keyNoSuchProperty
Get property.
GetPropertyStringStringString keyNoSuchProperty, TypeMismatch
Get property.
GetPropertyStringListString[]String keyNoSuchProperty, TypeMismatch
Get property.
GetPropertyIntegerIntString keyNoSuchProperty, TypeMismatch
Get property.
GetPropertyUInt64UInt64String keyNoSuchProperty, TypeMismatch
Get property.
GetPropertyBooleanBoolString keyNoSuchProperty, TypeMismatch
Get property.
GetPropertyDoubleDoubleString keyNoSuchProperty, TypeMismatch
Get property.
SetPropertyVariantString keyPermissionDenied
Set property.
SetPropertyStringStringString keyPermissionDenied, TypeMismatch
Set property.
SetPropertyStringListString[]String keyPermissionDenied, TypeMismatch
Set property.
SetPropertyIntegerIntString keyPermissionDenied, TypeMismatch
Set property.
SetPropertyUInt64UInt64String keyPermissionDenied, TypeMismatch
Set property.
SetPropertyBooleanBoolString keyPermissionDenied, TypeMismatch
Set property.
SetPropertyDoubleDoubleString keyPermissionDenied, TypeMismatch
Set property.
RemovePropertyString keyNoSuchProperty, PermissionDenied
Remove a property.
GetPropertyTypeIntString keyNoSuchProperty
Get the type of a property. Returns the D-Bus type as an integer.
PropertyExistsBoolString key
Determine if a property exists.
AddCapabilityString capabilityPermissionDenied
Adds a capability to a device.
QueryCapabilityBoolString capability
Determine if a device have a capability.
LockBoolString reasonDeviceAlreadyLocked
Acquires an advisory lock on the device. Returns TRUE if the lock was acquired.
UnlockBoolDeviceNotLocked
Releases an advisory lock on the device. Returns TRUE if the lock was released.
AcquireInterfaceLockString interface_name, Bool exclusivePermissionDenied, Device.InterfaceAlreadyLocked
Acquires a lock on an interface for a specific
device. See for details.
ReleaseInterfaceLockString interface_namePermissionDenied, Device.InterfaceNotLocked
Releases a lock on an interface for a specific device. See
for details.
IsCallerLockedOutBoolString interface_name, String caller_unique_namePermissionDenied
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 for details.
IsCallerPrivilegedStringString privilege, String caller_unique_namePermissionDenied, 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.
IsLockedByOthersBoolString interface_name
Determines whether a determines other processes than the
caller holds a lock on the given device. See
for details.
StringListAppendString key, String valuePermissionDenied, TypeMismatch
Appends an item to a string list.
StringListPrependString key, String valuePermissionDenied, TypeMismatch
Prepends an item to a string list.
StringListRemoveString key, String valuePermissionDenied, TypeMismatch
Removes an item from a string list.
EmitConditionBoolString name, String detailsPermissionDenied
Emit a condition on a device object.
RescanBoolPermissionDenied
Force an updates of the properties of a device object by
rereading data that is not monitored for changes.
ReprobeBoolPermissionDenied
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.
ClaimInterfaceBoolString name, String introspection_xmlPermissionDenied
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.
AddonIsReadyBoolPermissionDenied
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:
SignalParametersDescriptionPropertyModifiedInt num_changes, Array of struct {String property_name, Bool removed, Bool added}
One or more properties on the device object have changed.
ConditionString 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.).
InterfaceLockAcquiredString lock_name, String lock_owner, Int num_holders
Sent when a process acquires an interface lock on the device.
InterfaceLockReleasedString 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:
MethodParametersDescriptionACLAddedUInt unix_user_id
Emitted when an ACL have been added for a UNIX user on a
device object with the access_control
capability.
ACLRemovedUInt 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:
MethodReturnsParametersThrowsDescriptionGetCPUFreqAvailableGovernorsString[]
Retrieves a list of available CPU scaling governors.
GetCPUFreqGovernorString
Get currently selected CPU Frequency governor.
SetCPUFreqGovernorVoidString governorCPUFreq.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.
SetCPUFreqPerformanceVoidInt (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.
GetCPUFreqPerformanceIntCPUFreq.NoSuitableGovernor
Get the tuning value for the governor.
SetCPUFreqConsiderNiceVoidBool consider_niced_processesCPUFreq.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'.
GetCPUFreqConsiderNiceBoolCPUFreq.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.
MethodReturnsParametersThrowsDescriptionUndockIntVoidDockStation.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:
MethodReturnsParametersThrowsDescriptionGetBrightnessInt
Get the current brightness.
SetBrightnessInt 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:
MethodReturnsParametersThrowsDescriptionGetPowerInt
Returns 1 if, and only if, the power is on.
SetPowerBool
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:
MethodReturnsParametersThrowsDescriptionGetBrightnessInt
Get the current brightness of the LED.
SetBrightnessInt 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:
MethodReturnsParametersThrowsDescriptionGetBrightnessInt
Get the current brightness.
SetBrightnessInt 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:
MethodReturnsParametersThrowsDescriptionGetBrightnessInt[]
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:
MethodReturnsParametersThrowsDescriptionEjectIntString[] optionsVolume.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.
CloseTrayIntString[] optionsStorage.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:
MethodReturnsParametersThrowsDescriptionCheckForMediaBool
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:
MethodReturnsParametersThrowsDescriptionSuspendIntInt num_secs_to_wakeupSystemPowerManagement.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.
HibernateIntSystemPowerManagement.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.
SuspendHybridIntInt num_secs_to_wakeupSystemPowerManagement.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.
ShutdownIntSystemPowerManagement.NotSupported
Shut down the system.
RebootIntSystemPowerManagement.NotSupported
Reboot the system.
SetPowerSaveIntBool should_save_powerSystemPowerManagement.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
.
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:
MethodReturnsParametersThrowsDescriptionMountIntString mount_point, String fstype, String[] optionsVolume.PermissionDenied, Volume.AlreadyMounted, Volume.InvalidMountOption, Volume.UnknownFilesystemType, Volume.InvalidMountPoint, Volume.MountPointNotAvailable, Volume.CannotRemount
Mounts a volume.
UnmountIntString[] optionsVolume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidUnmountOption
Unmount a volume.
EjectIntString[] optionsVolume.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:
MethodReturnsParametersThrowsDescriptionSetupIntString passphraseVolume.Crypto.CryptSetupMissing, Volume.Crypto.SetupError, Volume.Crypto.SetupPasswordError
Unlocks an encrypted file system. If successful, a cleartext volume will appear.
TeardownIntVolume.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 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:
MethodReturnsParametersThrowsDescriptionGetSupportedBoolWakeOnLan.NoEthtool
Get if device supports Wake On LAN
GetEnabledBoolWakeOnLan.NoEthtool
Get if Wake On LAN is enabled
SetEnabledVoidBoolWakeOnLan.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:
MethodReturnsParametersThrowsDescriptionGetAllDevicesObjref[]
Get all UDI's in the database.
DeviceExistsBool
Determines if a given object exists.
FindDeviceStringMatchObjref[]String key, String value
Find devices for which the given string property assumes the given value.
FindDeviceByCapabilityObjref[]String capability
Finds devices of the given capability.
NewDeviceObjrefPermissionDenied
Creates a new device object in the temporary device list
(TDL) and return the UDI. Caller must be uid 0.
RemoveObjref tmp_udiNoSuchDevice, PermissionDenied
Removes a device object that was created in the
TDL. Caller must be uid 0.
CommitToGdlObjref tmp_udi, Objref udiNoSuchDevice, PermissionDenied
Moves a device from the temporary device list (TDL) to
the global device list (GDL). Caller must be uid 0.
AcquireGlobalInterfaceLockString interface_name, Bool exclusiveDevice.InterfaceAlreadyLocked
Acquires a global lock on an interface. See
for details.
ReleaseGlobalInterfaceLockString interface_nameDevice.InterfaceNotLocked
Releases a global lock on an interface. See
for details.
SingletonAddonIsReadyString command_linePermissionDenied, 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:
SignalParametersDescriptionDeviceAddedObjref obj
A device was added to the global device list (GDL).
DeviceRemovedObjref obj
A device was removed from the global device list (GDL).
NewCapabilityObjref obj, String cap
A device gained a new capability.
GlobalInterfaceLockAcquiredString lock_name, String lock_owner, Int num_holders
Sent when a process acquires a global interface lock.
GlobalInterfaceLockReleasedString 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.
MethodReturnsParametersThrowsDescriptionDeviceAddedString udiDict(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.
DeviceRemovedString udiDict(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.