hal: Branch 'master' - 2 commits
David Zeuthen
david at kemper.freedesktop.org
Sat Mar 24 22:53:41 PDT 2007
configure.in | 16
dev/null |binary
doc/spec/Makefile.am | 17
doc/spec/example-manager.py | 32
doc/spec/hal-arch.dia |binary
doc/spec/hal-arch.png |binary
doc/spec/hal-fdi-example1.png | 0
doc/spec/hal-fdi-example2.png | 0
doc/spec/hal-fdi-example3.png | 0
doc/spec/hal-linux26.dia | 0
doc/spec/hal-linux26.png | 0
doc/spec/hal-sequence-diagram.dia | 0
doc/spec/hal-sequence-diagram.png | 0
doc/spec/hal-spec-examples.xml | 536 ------------
doc/spec/hal-spec-fdi-files.xml | 660 ++++++--------
doc/spec/hal-spec-interfaces.xml | 1099 ++++++++++++++++++++++++
doc/spec/hal-spec-introduction.xml | 328 ++-----
doc/spec/hal-spec-properties.xml | 1650 ++++++++++++++-----------------------
doc/spec/hal-spec.xml.in | 4
hald/hald_dbus.c | 23
20 files changed, 2233 insertions(+), 2132 deletions(-)
New commits:
diff-tree c82997e6bc2ca71aceffc27951747855ab9ab3d7 (from 10a2acb986e2c07a26d7224dcdcef9c4c3db0018)
Author: David Zeuthen <davidz at redhat.com>
Date: Sun Mar 25 01:53:37 2007 -0400
fix up introspection bits
diff --git a/doc/spec/example-manager.py b/doc/spec/example-manager.py
deleted file mode 100755
index 861dc1b..0000000
--- a/doc/spec/example-manager.py
+++ /dev/null
@@ -1,32 +0,0 @@
-#!/usr/bin/python
-
-import gtk
-import dbus
-import dbus.glib
-
-def device_added(udi):
- print 'Device %s was added'%udi
-
-def device_removed(udi):
- print 'Device %s was removed'%udi
-
-
-bus = dbus.Bus (dbus.Bus.TYPE_SYSTEM)
-hal_manager = bus.get_object ('org.freedesktop.Hal',
- '/org/freedesktop/Hal/Manager')
-
-devices = hal_manager.GetAllDevices ()
-for d in devices:
- print 'Found device %s'%d
-
-bus.add_signal_receiver (device_added,
- 'DeviceAdded',
- 'org.freedesktop.Hal.Manager',
- 'org.freedesktop.Hal',
- '/org/freedesktop/Hal/Manager')
-bus.add_signal_receiver (device_removed,
- 'DeviceRemoved',
- 'org.freedesktop.Hal.Manager',
- 'org.freedesktop.Hal',
- '/org/freedesktop/Hal/Manager')
-gtk.main()
diff --git a/doc/spec/hal-fdi-example1.png b/doc/spec/hal-fdi-example1.png
deleted file mode 100644
index be6e88d..0000000
Binary files a/doc/spec/hal-fdi-example1.png and /dev/null differ
diff --git a/doc/spec/hal-fdi-example2.png b/doc/spec/hal-fdi-example2.png
deleted file mode 100644
index 5c1174d..0000000
Binary files a/doc/spec/hal-fdi-example2.png and /dev/null differ
diff --git a/doc/spec/hal-fdi-example3.png b/doc/spec/hal-fdi-example3.png
deleted file mode 100644
index 1449dd6..0000000
Binary files a/doc/spec/hal-fdi-example3.png and /dev/null differ
diff --git a/doc/spec/hal-linux26.dia b/doc/spec/hal-linux26.dia
deleted file mode 100644
index db45860..0000000
Binary files a/doc/spec/hal-linux26.dia and /dev/null differ
diff --git a/doc/spec/hal-linux26.png b/doc/spec/hal-linux26.png
deleted file mode 100644
index 7f3022e..0000000
Binary files a/doc/spec/hal-linux26.png and /dev/null differ
diff --git a/doc/spec/hal-sequence-diagram.dia b/doc/spec/hal-sequence-diagram.dia
deleted file mode 100644
index d448f15..0000000
Binary files a/doc/spec/hal-sequence-diagram.dia and /dev/null differ
diff --git a/doc/spec/hal-sequence-diagram.png b/doc/spec/hal-sequence-diagram.png
deleted file mode 100644
index 71eac97..0000000
Binary files a/doc/spec/hal-sequence-diagram.png and /dev/null differ
diff --git a/doc/spec/hal-spec-examples.xml b/doc/spec/hal-spec-examples.xml
deleted file mode 100644
index ee4c79a..0000000
--- a/doc/spec/hal-spec-examples.xml
+++ /dev/null
@@ -1,536 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-
-<chapter id="examples">
- <title>Examples and other stuff</title>
-
- <sect1 id="callouts">
- <title>Callouts</title>
- <para>
- Callouts are programs invoked when the device object list is
- modified. As such, callouts can be used to maintain system-wide
- policy (that may be specific to the particular OS) such as
- changing permissions on device nodes, updating the systemwide
- <literal>/etc/fstab</literal> file or configuring the networking
- subsystem.
- </para>
- <para>
- There are three different classes of callouts. A callout
- involves sequentially invoking all executable programs in the
- string list in listed order.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Key (type)</entry>
- <entry>Values</entry>
- <entry>Mandatory</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>info.callouts.add</literal> (string list)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- A string list with all programmes/callouts which should be
- executed (with <literal>HALD_ACTION=add</literal>) when the device
- is added to the GDL (global device list) but just before it is
- announced through the D-BUS network API.
- </entry>
- </row>
- <row>
- <entry>
- <literal>info.callouts.remove</literal> (string list)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- A string list with all programmes/callouts which should be
- executed (with <literal>HALD_ACTION=remove</literal>) when the
- device is removed from the GDL (global device list). The device
- isn't removed before the last callout has finished.
- </entry>
- </row>
- <row>
- <entry>
- <literal>info.callouts.preprobe</literal> (string list)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- A string list with all programmes/callouts which should be
- executed (with <literal>HALD_ACTION=preprobe</literal>) before
- the device is added to the GDL (global device list) and before
- the callouts from <literal>info.callouts.add</literal> are executed.
- </entry>
- </row>
- <row>
- <entry>
- <literal>info.callouts.session_add</literal> (string list)
- </entry>
- <entry/>
- <entry>No</entry>
- <entry>
- A string list with all programs/callouts which should be
- executed (with <literal>HALD_ACTION=session_add</literal>) when
- a session is added. Can only be set on the root computer
- device object.
- The environment also contains the variables
- <literal>HALD_SESSION_ADD_SESSION_ID</literal>,
- <literal>HALD_SESSION_ADD_SESSION_UID</literal> and
- <literal>HALD_SESSION_ADD_SESSION_IS_ACTIVE</literal>
- to identify the session.
- </entry>
- </row>
- <row>
- <entry>
- <literal>info.callouts.session_remove</literal> (string list)
- </entry>
- <entry/>
- <entry>No</entry>
- <entry>
- A string list with all programs/callouts which should be
- executed (with <literal>HALD_ACTION=session_remove</literal>) when
- a session is removed. Can only be set on the root computer
- device object.
- The environment also contains the variables
- <literal>HALD_SESSION_REMOVE_SESSION_ID</literal>,
- <literal>HALD_SESSION_REMOVE_SESSION_UID</literal> and
- <literal>HALD_SESSION_REMOVE_SESSION_IS_ACTIVE</literal>
- to identify the session.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>
- All callouts execute in the same environment as which the HAL
- daemon was started. In addition, the UDI of the device object is
- exported in the environment variable <literal>UDI</literal>. All
- properties of the device object are exported in the environment
- prefixed with <literal>HAL_</literal>. If a device is added or
- removed is exported in the environment variable <literal>HALD_ACTION
- </literal>
- ,if HAL is in shutdown mode the variable <literal>
- HALD_SHUTDOWN
- </literal>
- is set to environment.
- If ConsoleKit support is enabled, the variables
- <literal>CK_SEATS</literal> (tab sep. list of seat-id's),
- <literal>CK_SEAT_IS_LOCAL_seat-id</literal> (whether a seat is local),
- <literal>CK_SEAT_seat-id</literal> (tab sep. list of session-id's for a seat),
- <literal>CK_SESSION_IS_ACTIVE_session-id</literal> (whether a given session is active) and
- <literal>CK_SESSION_UID_session-id</literal> (the user of the session)
- will be exported as well.
- </para>
- <para>
- The HAL daemon isn't suspended while callouts are executing. Thus,
- callouts can communicate with the HAL daemon using the D-BUS network
- API. Hence, one application of callouts is to merge or modify
- properties on a device object.
- </para>
- </sect1>
-
- <sect1 id="dbus-api">
- <title>D-BUS Network API</title> <para>
- The HAL daemon is a system-wide process that keeps track of a
- number of device objects. It communicates with the operating
- system and intercepts hotplug events as devices are plugged in
- and removed. The daemon is also responsible for providing
- services to applications that wants to locate devices and
- perform generic operations on them such as obtaining exclusive
- access. Non-generic operations, such as obtaining pictures from
- a camera device, is outside the scope of the HAL daemon; see
- <xref linkend="using-devices"/>
- for more information.
- </para>
- <para>
- HAL has the concept of device stores. When a device is detected
- it is placed in the TDL (temporary device list) and then properties
- are merged from several sources including device information files
- and possibly callouts. Eventually, the device transitions to the
- GDL (global device list) and first then it becomes ''visible'' for
- desktop applications.
- </para>
- <para>
- Using D-BUS terminology, the HAL daemon provides the D-BUS
- service <literal>org.freedesktop.Hal</literal>. This service may
- be used to communicate with the HAL daemon, to get or set device
- properties and to perform some action on the devices. In the
- following sections, this D-BUS interface is expanded.
- </para>
- <para>
- A <literal>C</literal> API is provided by the libhal library.
- This API hides most of the D-BUS complexity and presents the D-BUS
- interface as function call or callbacks.
- </para>
- <sect2>
- <title>Interface org.freedesktop.Hal.Manager</title>
- <para>
- The <literal>org.freedesktop.Hal</literal> D-BUS service
- offers a D-BUS object at a well-known
- location <literal>/org/freedesktop/Hal/Manager</literal>. This
- object offers a D-BUS
- interface, <literal>org.freedesktop.Hal.Manager</literal>, for
- querying device objects with the following methods:
- </para>
- <programlisting>
-# Return a list of all devices in the GDL
-#
-# @return List of UDI's
-#
-array{string} GetAllDevices()
-# Determine if a device with a given Unique Device Id exists in the GDL
-#
-# @param udi Device UDI, for example '/org/freedesktop/Hal/devices/pci_8086_7111'
-# @return TRUE iff the device with the given UDI exists
-#
-bool DeviceExists(string udi)
-# Find the set of devices in the GDL that has a given property matching
-# a given value
-#
-# @param key Key, for example 'block.fstype'
-# @param value Value, for example 'ext3'
-# @return Array of UDI's, may be empty
-#
-array{string} FindDeviceStringMatch(string key, string value)
-# Find the set of devices in the GDL that has a given capability
-#
-# @param capability Capability, for example 'volume'
-# @return Array of UDI's, may be empty
-#
-array{string} FindDeviceByCapability(string capability)
- </programlisting>
- <para>
- This object also emits the following signals on the
- <literal>/org/freedesktop/Hal/Manager</literal> object on the
- <literal>org.freedesktop.Hal.Manager</literal> interface that
- applications can subscribe to using D-BUS:
- </para>
- <programlisting>
-# Notification that a new device have been added to the GDL
-#
-# @param udi Unique Device Id
-#
-void DeviceAdded(string udi)
-# Notification that a new device have been removed from the GDL. The
-# application cannot use this UDI anymore.
-#
-# @param udi Unique Device Id
-#
-void DeviceRemoved(string udi)
-# Notification that a device in the GDL have got a new capability. Note that
-# this is emitted even though the device already had the old capability
-#
-# @param udi Unique Device Id
-#
-void NewCapability(string udi, string capability)
- </programlisting>
- <sect3>
- <title>Example</title>
- <para>
- The following brief Python program demonstrates some of the API
- </para>
- <programlisting>
- <inlinegraphic format="linespecific" fileref="example-manager.py"/>
- </programlisting>
- <para>
- which gives the following output
- </para>
- <programlisting>
-Found device /org/freedesktop/Hal/devices/block_TORiSAN DVD-ROM DRD-U624-00000000000000000001-disc
-Found device /org/freedesktop/Hal/devices/block_TORiSAN DVD-ROM DRD-U624-00000000000000000001
-Found device /org/freedesktop/Hal/devices/block_37332a77-105e-4e76-8e99-27d3746e0531
-Found device /org/freedesktop/Hal/devices/block_3_2
-Found device /org/freedesktop/Hal/devices/block_LS-120 SLIM3 00 UHD Floppy-0208MBA00211
-Found device /org/freedesktop/Hal/devices/block_IC25N020ATCS05-0-CLP225F2G3UR4A
-Found device /org/freedesktop/Hal/devices/ide_1_1
-Found device /org/freedesktop/Hal/devices/ide_0_0
-Found device /org/freedesktop/Hal/devices/ide_1_0
-Found device /org/freedesktop/Hal/devices/usbif_usb_0_0_206_-1_0000:00:07.2_0
-Found device /org/freedesktop/Hal/devices/ide_host_0
-Found device /org/freedesktop/Hal/devices/ide_host_1
-Found device /org/freedesktop/Hal/devices/pci_104c_8400
-Found device /org/freedesktop/Hal/devices/usb_0_0_206_-1_0000:00:07.2
-Found device /org/freedesktop/Hal/devices/pci_1002_4c4d
-Found device /org/freedesktop/Hal/devices/pci_125d_1978
-Found device /org/freedesktop/Hal/devices/pci_8086_7111
-Found device /org/freedesktop/Hal/devices/pci_104c_ac1c/0
-Found device /org/freedesktop/Hal/devices/pci_8086_7112
-Found device /org/freedesktop/Hal/devices/pci_8086_7110
-Found device /org/freedesktop/Hal/devices/input_13_65
-Found device /org/freedesktop/Hal/devices/pci_104c_ac1c
-Found device /org/freedesktop/Hal/devices/pci_8086_7190
-Found device /org/freedesktop/Hal/devices/input_13_64
-Found device /org/freedesktop/Hal/devices/pci_8086_7113
-Found device /org/freedesktop/Hal/devices/pci_8086_7191
-Found device /org/freedesktop/Hal/devices/computer
-(insert USB mouse)
-Device /org/freedesktop/Hal/devices/usb_46d_c001_410_-1_noserial was added
-Device /org/freedesktop/Hal/devices/usbif_usb_46d_c001_410_-1_noserial_0 was added
-(remove USB mouse)
-Device /org/freedesktop/Hal/devices/usb_46d_c001_410_-1_noserial was removed
-Device /org/freedesktop/Hal/devices/usbif_usb_46d_c001_410_-1_noserial_0 was removed
- </programlisting>
- <para>
- </para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Interface org.freedesktop.Hal.Device</title>
- <para>
- Applications use
- the <literal>org.freedesktop.Hal.Manager</literal> interface to
- locate the device objects they are interested in. When a device
- object (which is really a D-BUS object, note that the UDI is the
- objects object_path) is obtained, the HAL daemon provides the
- <literal>org.freedesktop.Hal.Device</literal> interface on the
- object denoted by the UDI. This interface has the following
- methods
- </para>
- <programlisting>
-# Set property
-#
-# @param key Property to set
-# @param value Value to set
-# @raises org.freedesktop.Hal.(NoSuchDevice|TypeMismatch|PermissionDenied)
-#
-void SetProperty(string key, any value)
-void SetPropertyString(string key, string value)
-void SetPropertyInteger(string key, int32 value)
-void SetPropertyBoolean(string key, bool value)
-void SetPropertyDouble(string key, double value)
-# Get property
-#
-# @param key Property to get
-# @return The value of the property
-# @raises org.freedesktop.Hal.(NoSuchDevice|NoSuchProperty|TypeMismatch)
-#
-any GetProperty(string key)
-string GetPropertyString(string key)
-int32 GetPropertyInteger(string key)
-bool GetPropertyBoolean(string key)
-double GetPropertyDouble(string key)
-# Get all properties
-#
-# @return Dictionary from key to value
-# @raises org.freedesktop.Hal.NoSuchDevice
-#
-map{string, any} GetAllProperties()
-# Remove a property
-#
-# @param key Property to remove
-# @raises org.freedesktop.Hal.(NoSuchDevice|NoSuchProperty|PermissionDenied)
-#
-void RemoveProperty(string key)
-# Get the type of a property
-#
-# @param key Property
-# @return D-BUS type of property
-# @raises org.freedesktop.Hal.(NoSuchDevice|NoSuchProperty)
-#
-int32 GetPropertyType(string key)
-# Determine if a property exists
-#
-# @param key Property
-# @return TRUE iff the property exists
-# @raises org.freedesktop.Hal.NoSuchDevice
-#
-bool PropertyExists(string key)
-# Add a capability to a device. Note that this will trigger a NewCapability
-# signal to all client applications subscribing to signals from the Manager
-# interface.
-#
-# @param capability Capability, e.g. 'net.80211'
-# @raises org.freedesktop.Hal.(NoSuchDevice|PermissionDenied)
-#
-void AddCapability(string capability)
-# Determine if a device got a given capability
-#
-# @param capability Capability, e.g. 'storage.cdrom'
-# @return TRUE iff the device got the given capability
-# @raises org.freedesktop.Hal.NoSuchDevice
-#
-bool QueryCapability(string capability)
-# Take an advisory lock on the device.
-#
-# @param reason A user-presentable reason why the device
-# is locked.
-# @raises org.freedesktop.Hal.NoSuchDevice,
-# org.freedesktop.Hal.DeviceAlreadyLocked
-#
-void Lock(string reason)
-# Release an advisory lock on the device.
-#
-# @raises org.freedesktop.Hal.NoSuchDevice,
-# org.freedesktop.Hal.DeviceAlreadyLocked,
-# org.freedesktop.Hal.PermissionDenied
-#
-void Unlock()
- </programlisting>
- <para>
- The device objects also emits the following signals on the
- org.freedesktop.Hal interface that applications can subscribe to
- using D-BUS
- </para>
- <programlisting>
-# Notification that property have been modified
-#
-# @param key Property
-# @param added True iff the property have been added
-# @param removed True iff the property have been removed
-#
-void PropertyModified(string key, bool added, bool removed)
-# Notification that an event happened on the device has occured.
-#
-# Normally this is used to signal events that aren't or can't be expressed
-# in properties, e.g. 'ProcessorOverheating' etc.
-#
-# @param condition Name of condition
-# @param ... Dependent on the condition name
-void Condition(string condition, ...)
- </programlisting>
- <para>
- Note that D-BUS supports that applications can opt to receive
- signals for only a subset of the devices available.
- </para>
- </sect2>
-
- <sect2>
- <title>Interface org.freedesktop.Hal.Device.Volume</title>
- <para>
- The org.freedesktop.Hal.Device.Volume interface is used on objects
- with the "volume" capability. This interface has the following methods.
- </para>
- <programlisting>
-# Mount volume
-#
-# @param mountpoint Desired mount point. If NULL, will be generated based on label.
-# @param fstype Filesystem type
-# @param options Mount options
-# @raises org.freedesktop.Hal.Device.Volume.NoSuchDevice
-# org.freedesktop.Hal.Device.Volume.PermissionDenied
-# org.freedesktop.Hal.Device.Volume.AlreadyMounted
-# org.freedesktop.Hal.Device.Volume.InvalidMountOption
-# org.freedesktop.Hal.Device.Volume.UnknownFilesystemType
-# org.freedesktop.Hal.Device.Volume.InvalidMountpoint
-# org.freedesktop.Hal.Device.Volume.MountPointNotAvailable
-# org.freedesktop.Hal.Device.Volume.PermissionDeniedByPolicy
-#
-void Mount(string mountpoint, string fstype, array{string} options)
-# Unmount volume
-#
-# @param options Unmount options
-# @raises org.freedesktop.Hal.Device.Volume.NoSuchDevice
-# org.freedesktop.Hal.Device.Volume.PermissionDenied
-# org.freedesktop.Hal.Device.Volume.InvalidUnmountOption
-# org.freedesktop.Hal.Device.Volume.InvalidMountpoint
-# org.freedesktop.Hal.Device.Volume.MountPointNotAvailable
-# org.freedesktop.Hal.Device.Volume.PermissionDeniedByPolicy
-#
-void Unmount(array{string} options)
-# Eject volume
-#
-# @param ejectoptions Eject options
-# @raises org.freedesktop.Hal.Device.Volume.NoSuchDevice
-# org.freedesktop.Hal.Device.Volume.PermissionDenied
-# org.freedesktop.Hal.Device.Volume.InvalidEjectOption
-# org.freedesktop.Hal.Device.Volume.PermissionDeniedByPolicy
-#
-void Eject(array{string} options)
- </programlisting>
- </sect2>
-
- <sect2>
- <title>Interface org.freedesktop.Hal.Device.Storage</title>
- <para>
- The org.freedesktop.Hal.Device.Storage interface is used on objects
- with the "storage" capability. This interface has the following methods.
- </para>
- <programlisting>
-# Eject media
-#
-# @param ejectoptions Eject options
-# @raises org.freedesktop.Hal.Device.Storage.NoSuchDevice
-# org.freedesktop.Hal.Device.Storage.PermissionDenied
-# org.freedesktop.Hal.Device.Storage.InvalidEjectOption
-# org.freedesktop.Hal.Device.Storage.PermissionDeniedByPolicy
-#
-void Eject(array{string} options)
-# Close media tray
-#
-# @param closetrayoptions Close tray options
-# @raises org.freedesktop.Hal.Device.Storage.NoSuchDevice
-# org.freedesktop.Hal.Device.Storage.PermissionDenied
-# org.freedesktop.Hal.Device.Storage.InvalidCloseTrayOption
-# org.freedesktop.Hal.Device.Storage.PermissionDeniedByPolicy
-#
-void CloseTray(array{string} options)
- </programlisting>
- </sect2>
- </sect1>
-
- <sect1 id="enforcing-policy">
- <title>Enforcing Policy</title>
- <para>
- Notwithstanding the fact that HAL avoids to enforce any policy,
- it is useful to have a minimal set of guidelines such that
- applications using HAL written for one operating system can
- easily run on another. This section contains recommendations
- about how to enforce policy to achieve that goal.
- </para>
- <sect2 id="enforcing-stor-vol">
- <title>Storage Devices</title>
- <sect3 id="stor-vol-policy">
- <title>Policy for Volumes and Storage devices</title>
- <para>
- The properties in the <literal>storage.policy</literal>,
- <literal>volume.policy</literal> and
- <literal>storage.policy.default</literal> namespaces should
- be the preferred way to determine how and if a filesystem
- can be mounted. See <xref linkend="properties-policy"/>
- for details.
- </para>
- </sect3>
- <sect3 id="enforcing-storage-fstab">
- <title>File systems file</title>
- <para>
- An operating system vendor should maintain the
- <literal>/etc/fstab</literal> file through the HAL callout
- mechanism such that device objects of capability
- <literal>volume</literal> and <literal>storage</literal> has
- a corresponding entry if applicable cf.
- <xref linkend="stor-vol-policy"/>
- .
- </para>
- <para>
- The reasoning behind this is, among other things, to
- maintain the invariant that <literal>/etc/fstab</literal>
- list all available filesystems. In addition
- the <literal>mount(1)</literal> program should enable users
- without superuser privileges to mount filesystems mentioned
- in the <literal>/etc/fstab</literal> file as long as they
- have the <literal>user</literal> option set.
- </para>
- </sect3>
- <sect3 id="enforcing-storage-locking">
- <title>Disabling policy agents</title>
- <para>
- Policy agents like volume mounters should ignore when media
- is inserted into a drive that is locked by another
- application. Thus, CD burning applications should lock the
- device to disable auto mounting or automatic start of the
- users preferred CD burning application when respectively
- non-blank rewritable or blank media is inserted.
- </para>
- </sect3>
- </sect2>
- </sect1>
-
-</chapter>
diff --git a/hald/hald_dbus.c b/hald/hald_dbus.c
index b40746b..f8e95e4 100644
--- a/hald/hald_dbus.c
+++ b/hald/hald_dbus.c
@@ -3756,6 +3756,18 @@ do_introspect (DBusConnection *connecti
" <arg name=\"temporary_udi\" direction=\"in\" type=\"s\"/>\n"
" <arg name=\"global_udi\" direction=\"in\" type=\"s\"/>\n"
" </method>\n"
+
+ " <signal name=\"DeviceAdded\">\n"
+ " <arg name=\"udi\" type=\"s\"/>\n"
+ " </signal>\n"
+ " <signal name=\"DeviceRemoved\">\n"
+ " <arg name=\"udi\" type=\"s\"/>\n"
+ " </signal>\n"
+ " <signal name=\"NewCapability\">\n"
+ " <arg name=\"udi\" type=\"s\"/>\n"
+ " <arg name=\"cap_name\" type=\"s\"/>\n"
+ " </signal>\n"
+
" </interface>\n");
} else {
HalDevice *d;
@@ -3893,6 +3905,14 @@ do_introspect (DBusConnection *connecti
" <method name=\"AddonIsReady\">\n"
" <arg name=\"rc\" direction=\"out\" type=\"b\"/>\n"
" </method>\n"
+ " <signal name=\"PropertyModified\">\n"
+ " <arg name=\"num_updates\" type=\"i\"/>\n"
+ " <arg name=\"updates\" type=\"a(sbb)\"/>\n"
+ " </signal>\n"
+ " <signal name=\"Condition\">\n"
+ " <arg name=\"cond_name\" type=\"s\"/>\n"
+ " <arg name=\"cond_details\" type=\"s\"/>\n"
+ " </signal>\n"
" </interface>\n");
HalDeviceStrListIter if_iter;
@@ -3920,7 +3940,8 @@ do_introspect (DBusConnection *connecti
/* consult local list */
for (i = helper_interface_handlers; i != NULL; i = g_slist_next (i)) {
HelperInterfaceHandler *hih = i->data;
- if (strcmp (hih->udi, path) == 0) {
+ if (strcmp (hih->udi, path) == 0 &&
+ strcmp (hih->interface_name, ifname) == 0) {
xml = g_string_append (xml, hih->introspection_xml);
}
}
diff-tree 10a2acb986e2c07a26d7224dcdcef9c4c3db0018 (from 8e00f386dd4af855116cb1082c0ae6fd8db7ce5e)
Author: David Zeuthen <davidz at redhat.com>
Date: Sun Mar 25 01:53:01 2007 -0400
switch to xmlto and heavily fix up the spec
- remove lots of superfluous text and diagrams
- add documentation for most of our D-Bus interfaces
diff --git a/configure.in b/configure.in
index 2f460ec..b24449a 100644
--- a/configure.in
+++ b/configure.in
@@ -527,13 +527,13 @@ AC_CHECK_FUNCS(strndup)
# DocBook Documentation
-AC_PATH_PROG(DOCBOOK, docbook2html, no)
+AC_PATH_PROG(XMLTO, xmlto, no)
AC_MSG_CHECKING([whether to build DocBook documentation])
-if test x$DOCBOOK = xno ; then
- have_docbook=no
+if test x$XMLTO = xno ; then
+ have_xmlto=no
else
- have_docbook=yes
+ have_xmlto=yes
fi
AC_PATH_PROG(XMLLINT, xmllint, no)
@@ -545,7 +545,7 @@ else
fi
if test x$enable_docbook_docs = xauto ; then
- if test x$have_docbook = xno || test x$have_xmllint = xno ; then
+ if test x$have_xmlto = xno || test x$have_xmllint = xno ; then
enable_docbook_docs=no
else
enable_docbook_docs=yes
@@ -553,8 +553,8 @@ if test x$enable_docbook_docs = xauto ;
fi
if test x$enable_docbook_docs = xyes; then
- if test x$have_docbook = xno; then
- AC_MSG_ERROR([Building DocBook docs explicitly required, but DocBook not found])
+ if test x$have_xmlto = xno; then
+ AC_MSG_ERROR([Building DocBook docs explicitly required, but xmlto not found])
fi
if test x$ve_xmllint = xno; then
AC_MSG_ERROR([Building DocBook docs explicitly required, but xmllint not found])
@@ -909,7 +909,7 @@ echo "
cflags: ${CFLAGS}
ldflags: ${LDFLAGS}
cppflags: ${CPPFLAGS}
- docbook2html: ${DOCBOOK}
+ xmlto: ${XMLTO}
xmllint: ${XMLLINT}
User for HAL: ${HAL_USER}
Group for HAL: ${HAL_GROUP}
diff --git a/doc/spec/Makefile.am b/doc/spec/Makefile.am
index 8d69843..3e49ecd 100644
--- a/doc/spec/Makefile.am
+++ b/doc/spec/Makefile.am
@@ -1,14 +1,10 @@
FIGURE_FILES = \
hal-arch.png \
- hal-devices1.png \
- hal-fdi-example1.png \
- hal-fdi-example2.png \
- hal-fdi-example3.png \
- hal-linux26.png
+ hal-devices1.png
SPEC_XML_EXTRA_FILES = \
- hal-spec-examples.xml \
+ hal-spec-interfaces.xml \
hal-spec-introduction.xml \
hal-spec-fdi-files.xml \
hal-spec-properties.xml
@@ -19,13 +15,14 @@ htmldocdir = $(DOCDIR)/spec
htmldoc_DATA = hal-spec.html $(FIGURE_FILES)
hal-spec.html : hal-spec.xml $(SPEC_XML_EXTRA_FILES) $(FIGURE_FILES)
- ${XMLLINT} --xinclude hal-spec.xml > ~hal-spec.xml
- mv ~hal-spec.xml hal-spec.xml
- $(DOCBOOK) --nochunks hal-spec.xml -o .
+ ${XMLLINT} --xinclude hal-spec.xml > ~hal-spec.xml || rm -f ~hal-spec.xml
+ mv -f ~hal-spec.xml hal-spec.xml
+ $(XMLTO) html-nochunks -m config.xsl hal-spec.xml || rm -f hal-spec.xml
+ rm -f hal-spec.xml
clean-local:
rm -f *~
- rm -f hal-spec.html hal-spec.xml
+ rm -f *.html hal-spec.xml
endif # DOCBOOK_DOCS_ENABLED
diff --git a/doc/spec/hal-arch.dia b/doc/spec/hal-arch.dia
index 89c0e04..445a257 100644
Binary files a/doc/spec/hal-arch.dia and b/doc/spec/hal-arch.dia differ
diff --git a/doc/spec/hal-arch.png b/doc/spec/hal-arch.png
index 5bea012..d0f5ac9 100644
Binary files a/doc/spec/hal-arch.png and b/doc/spec/hal-arch.png differ
diff --git a/doc/spec/hal-spec-fdi-files.xml b/doc/spec/hal-spec-fdi-files.xml
index e2c8b4f..76d65fb 100644
--- a/doc/spec/hal-spec-fdi-files.xml
+++ b/doc/spec/hal-spec-fdi-files.xml
@@ -12,365 +12,311 @@
information files are used for both merging facts and policy
settings about devices.
</para>
- <para>
- Each device information file got a number of
- <literal><match key="some_property"
- [string|int|bool|..]="required_value" >
- </literal>
- directives
- that is tested against the properties of the device object. If
- all the match directives passes then the device information can
- include <literal><[merge|append|prepend] key="some_property"
- type="[string|int|bool|..]">
- </literal>
- directives to
- respectively merge new properties or append to existing
- properties on the device object. It's important to emphasize
- that any previously property stemming from device detection can
- be overridden by a device information file.
- </para>
- <para>
- The <literal><match></literal>,
- <literal><merge></literal>, <literal><append></literal>
- and <literal><prepend></literal> directives always requires
- the <literal>key</literal> attribute which must be either a
- property name on the device object in question or a path to a
- property on another device object. The latter case is expressed
- either through direct specification of the UDI, such as
- <literal>/org/freedesktop/Hal/devices/computer:foo.bar</literal>
- or indirect references such as
- <literal>@info.parent:baz</literal> where the latter means that
- the device object specified by the UDI in the string property
- <literal>info.parent</literal> should be used to query the
- property <literal>baz</literal>. It is also possible to use
- multiple indirections, e.g. for a volume on a USB memory stick
- the indirection <literal>@block.storage_device:@storage.originating_device:usb.vendor_id</literal>
- will reference the <literal>usb.vendor_id</literal> property
- on the device object representing the USB interface.
- </para>
- <para>
- When the property to match have been determined a number of
- attributes can be used within the <literal><match></literal>
- tag:
- <itemizedlist>
- <listitem>
- <para>
- <literal>string</literal> - match a string property; for example
- <literal><match key="foo.bar" string="baz"></literal>
- will match only if 'foo.bar' is a string property assuming the value 'baz'.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>int</literal> - match an integer property
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>uint64</literal> - match property with the 64-bit unsigned type
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>bool</literal> - match a boolean property
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>double</literal> - match a property of type double
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>exists</literal> - used as
- <literal><match key="foo.bar" exists="true"></literal>. Can be used with
- 'true' and 'false' respectively to match when a property exists and it doesn't.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>empty</literal> - can only be used on string or strlist properties
- with 'true' and 'false'.
- The semantics for 'true' is to match only when the string is non-empty.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>is_absolute_path</literal> - matches only when a string
- property represents an absolute path (the path doesn't have to exist).
- Can be used with 'true' or 'false'.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>is_ascii</literal> - matches only when a string property
- contain only ASCII characters. Can be used with 'true' or 'false'.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>compare_lt</literal> - can be used on int, uint64, double
- and string properties to compare with a constant.
- Matches when the given property is less than the given constant
- using the default ordering.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>compare_le</literal> - like <literal>compare_lt</literal>
- but matches when less than or equal.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>compare_gt</literal> - like <literal>compare_lt</literal>
- but matches when greater than.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>compare_ge</literal> - like <literal>compare_lt</literal>
- but matches when greater than or equal.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>compare_ne</literal> - like <literal>compare_lt</literal>
- but matches when not equal.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>contains</literal> - can only be used with string and
- strlist (string list).
- For a string key this matches when the property contains the given
- (sub-)string. For a string list this match if the given string match
- a item of the list.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>contains_not</literal> - can only be used with strlist (string list)
- and string properties.
- For a string list this match if the given string is not match any of the
- item of the list for a string this match of the property not contains the
- (sub-)string. You can use this attribute to construct if/else blocks together
- with e.g. <literal>contains</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>contains_ncase</literal> - like <literal>contains</literal>
- but the property and the given key are converted to lowercase before check.
- </para>
- </listitem>
- </itemizedlist>
- The <literal><merge></literal>, <literal><append></literal>
- and <literal><prepend></literal> directives all require
- the <literal>type</literal> attribute which specifies what to
- merge. The following values are supported
- <itemizedlist>
- <listitem>
- <para>
- <literal>string</literal> - The value is copied to the property. For example
- <literal><merge key="foo.bar" type="string">baz</merge></literal>
- will merge the value 'baz' into the property 'foo.bar'.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>strlist</literal> - For <literal><merge></literal> the value is
- copied to the property and the current property will be overwritten. For
- <literal><append></literal> and <literal><prepend></literal> the
- value is append or prepend to the list as new item. Usage of
- <literal><copy_property></literal> overwrite the complete list with the
- value of the given property to copy from.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>bool</literal> - Can merge the values 'true' or 'false'
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>int</literal> - Merges an integer
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>uint64</literal> - Merges an unsigned 64-bit integer
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>double</literal> - Merges a double precision floating point number
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>copy_property</literal> - Copies the value of a given
- property - supports paths with direct and indirect UDI's. For example
- <literal><merge key="foo.bar" type="copy_property">@info.parent:baz.bat</merge></literal>
- will merge the value of the property <literal>baz.bat</literal> on the device object with the UDI from
- the property <literal>info.parent</literal> into the property <literal>foo.bar</literal> on
- the device object being processed.
- </para>
- </listitem>
- </itemizedlist>
- The <literal><remove></literal>, directive require only a key and can be used with all keys.
- For <literal>strlist</literal> there is additionally a special syntax to remove a item from the
- string list. For example to remove item 'bla' from property 'foo.bar':
- <literal><remove key="foo.bar" type="strlist">bla</remove></literal>
- </para>
- <para>
- Device Information files are stored in the following standard hierachy with the following default
- top level directories <literal>information</literal>, <literal>policy</literal> and
- <literal>preprobe</literal>:
- <itemizedlist>
- <listitem>
- <para>
- <literal>information</literal> - device information files to merge device information
- <itemizedlist>
- <listitem>
- <para>
- <literal>10freedesktop</literal> - device information files included with
- the hal tarball
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>20thirdparty</literal> - device information files from the device
- manufacturer and installed from media accompanying the hardware
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>30user</literal> - device information for specific devices
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>policy</literal> - device information files to merge policy propertys
- <itemizedlist>
- <listitem>
- <para>
- <literal>10osvendor</literal> - device information files included with the
- hal tarball and supplied by the operating system vendor for policy rules
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>20thirdparty</literal> - Policy rules from the device
- manufacturer and installed from media accompanying the hardware
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>30user</literal> - Policy rules for specific devices
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>preprobe</literal> - device information files to information before probe devices
- <itemizedlist>
- <listitem>
- <para>
- <literal>10osvendor</literal> - device information files included with the
- hal tarball and supplied by the operating system vendor
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>20thirdparty</literal> - device information files from the device
- manufacturer and installed from media accompanying the hardware
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>30user</literal> - device information for specific devices
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
- All device information files are matched for every hal device object.
- </para>
- <sect1 id="fdi-facts">
- <title>Facts about devices</title>
- <sect2 id="fdi-example-mp3player">
- <title>Example: MP3 player</title>
- <programlisting>
- <inlinegraphic format="linespecific" fileref="../conf/match-USB-mp3-player.fdi"/>
- </programlisting>
- <para>
- The final set of properties look like this:
- </para>
- <para>
- <inlinegraphic fileref="hal-fdi-example2.png" format="PNG"/>
- </para>
- </sect2>
- <sect2 id="fdi-example-camera">
- <title>Example: Digital Still Camera</title>
- <programlisting>
- <inlinegraphic format="linespecific" fileref="../conf/match-USB-camera.fdi"/>
- </programlisting>
- <para>
- The final set of properties look like this:
- </para>
- <para>
- <inlinegraphic fileref="hal-fdi-example1.png" format="PNG"/>
- </para>
- </sect2>
- <sect2 id="fdi-example-6in1">
- <title>Example: Card Reader</title>
- <programlisting>
- <inlinegraphic format="linespecific" fileref="../conf/match-cardreader.fdi"/>
- </programlisting>
- <para>
- As described in the documentation for the
- <literal>storage.originating_device</literal> property in
- <xref linkend="device-properties-storage"/> this device information
- file export information about each storage port through the
- property <literal>storage.drive_type</literal>. Thus, one
- of the four <literal>storage</literal> devices has the
- following properties that are merged from the device object
- that the device information file targets:
- </para>
- <para>
- <inlinegraphic fileref="hal-fdi-example3.png" format="PNG"/>
- </para>
- </sect2>
+
+ <sect1>
+ <title>Matching</title>
+
+ <para>
+ Each device information file got a number of
+ <literal><match key="some_property"
+ [string|int|bool|..]="required_value" >
+ </literal>
+ directives
+ that is tested against the properties of the device object. If
+ all the match directives passes then the device information can
+ include <literal><[merge|append|prepend] key="some_property"
+ type="[string|int|bool|..]">
+ </literal>
+ directives to
+ respectively merge new properties or append to existing
+ properties on the device object. It's important to emphasize
+ that any previously property stemming from device detection can
+ be overridden by a device information file.
+ </para>
+ <para>
+ The <literal><match></literal>,
+ <literal><merge></literal>, <literal><append></literal>
+ and <literal><prepend></literal> directives always requires
+ the <literal>key</literal> attribute which must be either a
+ property name on the device object in question or a path to a
+ property on another device object. The latter case is expressed
+ either through direct specification of the UDI, such as
+ <literal>/org/freedesktop/Hal/devices/computer:foo.bar</literal>
+ or indirect references such as
+ <literal>@info.parent:baz</literal> where the latter means that
+ the device object specified by the UDI in the string property
+ <literal>info.parent</literal> should be used to query the
+ property <literal>baz</literal>. It is also possible to use
+ multiple indirections, e.g. for a volume on a USB memory stick
+ the indirection <literal>@block.storage_device:@storage.originating_device:usb.vendor_id</literal>
+ will reference the <literal>usb.vendor_id</literal> property
+ on the device object representing the USB interface.
+ </para>
+ <para>
+ When the property to match have been determined a number of
+ attributes can be used within the <literal><match></literal>
+ tag:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>string</literal> - match a string property; for example
+ <literal><match key="foo.bar" string="baz"></literal>
+ will match only if 'foo.bar' is a string property assuming the value 'baz'.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>int</literal> - match an integer property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>uint64</literal> - match property with the 64-bit unsigned type
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>bool</literal> - match a boolean property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>double</literal> - match a property of type double
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>exists</literal> - used as
+ <literal><match key="foo.bar" exists="true"></literal>. Can be used with
+ 'true' and 'false' respectively to match when a property exists and it doesn't.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>empty</literal> - can only be used on string or strlist properties
+ with 'true' and 'false'.
+ The semantics for 'true' is to match only when the string is non-empty.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>is_absolute_path</literal> - matches only when a string
+ property represents an absolute path (the path doesn't have to exist).
+ Can be used with 'true' or 'false'.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>is_ascii</literal> - matches only when a string property
+ contain only ASCII characters. Can be used with 'true' or 'false'.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>compare_lt</literal> - can be used on int, uint64, double
+ and string properties to compare with a constant.
+ Matches when the given property is less than the given constant
+ using the default ordering.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>compare_le</literal> - like <literal>compare_lt</literal>
+ but matches when less than or equal.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>compare_gt</literal> - like <literal>compare_lt</literal>
+ but matches when greater than.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>compare_ge</literal> - like <literal>compare_lt</literal>
+ but matches when greater than or equal.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>compare_ne</literal> - like <literal>compare_lt</literal>
+ but matches when not equal.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>contains</literal> - can only be used with string and
+ strlist (string list).
+ For a string key this matches when the property contains the given
+ (sub-)string. For a string list this match if the given string match
+ a item of the list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>contains_not</literal> - can only be used with strlist (string list)
+ and string properties.
+ For a string list this match if the given string is not match any of the
+ item of the list for a string this match of the property not contains the
+ (sub-)string. You can use this attribute to construct if/else blocks together
+ with e.g. <literal>contains</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>contains_ncase</literal> - like <literal>contains</literal>
+ but the property and the given key are converted to lowercase before check.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect1>
+ <sect1>
+ <title>Merging</title>
+ <para>
+
+ The <literal><merge></literal>, <literal><append></literal>
+ and <literal><prepend></literal> directives all require
+ the <literal>type</literal> attribute which specifies what to
+ merge. The following values are supported
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>string</literal> - The value is copied to the property. For example
+ <literal><merge key="foo.bar" type="string">baz</merge></literal>
+ will merge the value 'baz' into the property 'foo.bar'.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>strlist</literal> - For <literal><merge></literal> the value is
+ copied to the property and the current property will be overwritten. For
+ <literal><append></literal> and <literal><prepend></literal> the
+ value is append or prepend to the list as new item. Usage of
+ <literal><copy_property></literal> overwrite the complete list with the
+ value of the given property to copy from.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>bool</literal> - Can merge the values 'true' or 'false'
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>int</literal> - Merges an integer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>uint64</literal> - Merges an unsigned 64-bit integer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>double</literal> - Merges a double precision floating point number
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>copy_property</literal> - Copies the value of a given
+ property - supports paths with direct and indirect UDI's. For example
+ <literal><merge key="foo.bar" type="copy_property">@info.parent:baz.bat</merge></literal>
+ will merge the value of the property <literal>baz.bat</literal> on the device object with the UDI from
+ the property <literal>info.parent</literal> into the property <literal>foo.bar</literal> on
+ the device object being processed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ The <literal><remove></literal>, directive require only a key and can be used with all keys.
+ For <literal>strlist</literal> there is additionally a special syntax to remove a item from the
+ string list. For example to remove item 'bla' from property 'foo.bar':
+ <literal><remove key="foo.bar" type="strlist">bla</remove></literal>
+ </para>
+
</sect1>
- <sect1 id="fdi-policy">
- <title>Policy settings for devices</title>
+ <sect1>
+ <title>Search Paths</title>
+
<para>
- Policy settings specifies system specific settings that a
- system administrator associates with a device instance. In the
- context of hal, this can be expressed in terms of device
- properties merged on the device object in question. Default
- policy can also be merged on the root computer device object.
+ Device Information files are read from two directories
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>/usr/share/hal/fdi</literal> - for files provided by packages
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>/etc/hal/fdi</literal> - for files provided by the system administrator
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ in exactly that order. This means that the files provided by the
+ system administrator will be processed last such that they can
+ overwrite / change properties caused by the device information
+ files provided by packages.
+
+ The following directory structure is used in <literal>/usr/share/hal/fdi</literal>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>information</literal> - device information files used to merge device information
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>10freedesktop</literal> - included with the hal package
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>20thirdparty</literal> - from a 3rd party, not included in hal package
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>policy</literal> - device information files to merge policy properties such as addons or callouts.
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>10osvendor</literal> - included with the hal package
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>20thirdparty</literal> - from a 3rd party, not included in hal package
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>preprobe</literal> - device information files to information before probe devices
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>10osvendor</literal> - included with the hal package
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>20thirdparty</literal> - from a 3rd party, not included in hal package
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ All device information files are matched for every hal device object.
</para>
- <sect2 id="fdi-example-mountsetting">
- <title>Storage Devices</title>
- <para>
- Policy for storage devices is expressed in the
- <literal>storage.policy.default</literal>,
- <literal>storage.policy</literal> and
- <literal>volume.policy</literal> namespaces, see
- <xref linkend="properties-policy"/>
- for details.
- </para>
- <programlisting>
- <inlinegraphic format="linespecific" fileref="../conf/storage-policy-examples.fdi"/>
- </programlisting>
- </sect2>
</sect1>
</chapter>
diff --git a/doc/spec/hal-spec-interfaces.xml b/doc/spec/hal-spec-interfaces.xml
new file mode 100644
index 0000000..7057e58
--- /dev/null
+++ b/doc/spec/hal-spec-interfaces.xml
@@ -0,0 +1,1099 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<chapter id="interfaces">
+ <title>D-Bus interfaces</title>
+
+ <para>
+ All of the HAL D-Bus interfaces are introspectable using the
+ standard D-Bus introspection methods (e.g. they all implement
+ the <literal>org.freedesktop.DBus.Introspectable</literal>
+ interface). For example, a command like
+ <programlisting>
+$ dbus-send --system --print-reply --dest=org.freedesktop.Hal \
+ /org/freedesktop/Hal/devices/computer \
+ org.freedesktop.DBus.Introspectable.Introspect
+ </programlisting>
+ will print out the introspection XML for what interfaces
+ (ie. methods and signals) the given hal device object
+ supports. For brevity, the <literal>org.freedesktop.Hal</literal>
+ prefix have been stripped from the exceptions listed in the
+ following sections. Also note that other exceptions than the ones
+ listed may be thrown.
+ </para>
+
+ <sect1 id="interface-manager">
+ <title>org.freedesktop.Hal.Manager interface</title>
+ <para>
+ Only the <literal>/org/freedesktop/Hal/Manager</literal> object
+ implements this interface. It's primarily used to discover
+ devices. The following methods are available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>GetAllDevices</entry>
+ <entry>Objref[]</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ Get all UDI's in the database.
+ </entry>
+ </row>
+ <row>
+ <entry>DeviceExists</entry>
+ <entry>Bool</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ Determines if a given object exists.
+ </entry>
+ </row>
+ <row>
+ <entry>FindDeviceStringMatch</entry>
+ <entry>Objref[]</entry>
+ <entry>String key, String value</entry>
+ <entry></entry>
+ <entry>
+ Find devices for which the given string property assumes the given value.
+ </entry>
+ </row>
+ <row>
+ <entry>FindDeviceByCapability</entry>
+ <entry>Objref[]</entry>
+ <entry>String capability</entry>
+ <entry></entry>
+ <entry>
+ Finds devices of the given capability.
+ </entry>
+ </row>
+ <row>
+ <entry>NewDevice</entry>
+ <entry>Objref</entry>
+ <entry></entry>
+ <entry>PermissionDenied</entry>
+ <entry>
+ Creates a new device object in the temporary device list
+ (TDL) and return the UDI. Caller must be uid 0.
+ </entry>
+ </row>
+ <row>
+ <entry>Remove</entry>
+ <entry></entry>
+ <entry>Objref tmp_udi</entry>
+ <entry>NoSuchDevice, PermissionDenied</entry>
+ <entry>
+ Removes a device object that was created in the
+ TDL. Caller must be uid 0.
+ </entry>
+ </row>
+ <row>
+ <entry>CommitToGdl</entry>
+ <entry></entry>
+ <entry>Objref tmp_udi, Objref udi</entry>
+ <entry>NoSuchDevice, PermissionDenied</entry>
+ <entry>
+ Moves a device from the temporary device list (TDL) to
+ the global device list (GDL). Caller must be uid 0.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ The following signals are emitted:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Signal</entry>
+ <entry>Parameters</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>DeviceAdded</entry>
+ <entry>Objref obj</entry>
+ <entry>
+ A device was added to the global device list (GDL).
+ </entry>
+ </row>
+ <row>
+ <entry>DeviceRemoved</entry>
+ <entry>Objref obj</entry>
+ <entry>
+ A device was removed from the global device list (GDL).
+ </entry>
+ </row>
+ <row>
+ <entry>NewCapability</entry>
+ <entry>Objref obj, String cap</entry>
+ <entry>
+ A device gained a new capability.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+
+
+ <sect1 id="interface-device">
+ <title>org.freedesktop.Hal.Device interface</title>
+ <para>
+ Every hal device object (e.g. objects where the object path is
+ prefixed with <literal>/org/freedesktop/Hal/devices/</literal>)
+ implements this interface. It provides generic
+ functionality. The following methods are available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+
+ <row>
+ <entry>GetProperty</entry>
+ <entry>Variant</entry>
+ <entry>String key</entry>
+ <entry>NoSuchProperty</entry>
+ <entry>
+ Get property.
+ </entry>
+ </row>
+ <row>
+ <entry>GetPropertyString</entry>
+ <entry>String</entry>
+ <entry>String key</entry>
+ <entry>NoSuchProperty, TypeMismatch</entry>
+ <entry>
+ Get property.
+ </entry>
+ </row>
+ <row>
+ <entry>GetPropertyStringList</entry>
+ <entry>String[]</entry>
+ <entry>String key</entry>
+ <entry>NoSuchProperty, TypeMismatch</entry>
+ <entry>
+ Get property.
+ </entry>
+ </row>
+ <row>
+ <entry>GetPropertyInteger</entry>
+ <entry>Int</entry>
+ <entry>String key</entry>
+ <entry>NoSuchProperty, TypeMismatch</entry>
+ <entry>
+ Get property.
+ </entry>
+ </row>
+ <row>
+ <entry>GetPropertyUInt64</entry>
+ <entry>UInt64</entry>
+ <entry>String key</entry>
+ <entry>NoSuchProperty, TypeMismatch</entry>
+ <entry>
+ Get property.
+ </entry>
+ </row>
+ <row>
+ <entry>GetPropertyBoolean</entry>
+ <entry>Bool</entry>
+ <entry>String key</entry>
+ <entry>NoSuchProperty, TypeMismatch</entry>
+ <entry>
+ Get property.
+ </entry>
+ </row>
+ <row>
+ <entry>GetPropertyDouble</entry>
+ <entry>Double</entry>
+ <entry>String key</entry>
+ <entry>NoSuchProperty, TypeMismatch</entry>
+ <entry>
+ Get property.
+ </entry>
+ </row>
+
+
+ <row>
+ <entry>SetProperty</entry>
+ <entry>Variant</entry>
+ <entry>String key</entry>
+ <entry>PermissionDenied</entry>
+ <entry>
+ Set property.
+ </entry>
+ </row>
+ <row>
+ <entry>SetPropertyString</entry>
+ <entry>String</entry>
+ <entry>String key</entry>
+ <entry>PermissionDenied, TypeMismatch</entry>
+ <entry>
+ Set property.
+ </entry>
+ </row>
+ <row>
+ <entry>SetPropertyStringList</entry>
+ <entry>String[]</entry>
+ <entry>String key</entry>
+ <entry>PermissionDenied, TypeMismatch</entry>
+ <entry>
+ Set property.
+ </entry>
+ </row>
+ <row>
+ <entry>SetPropertyInteger</entry>
+ <entry>Int</entry>
+ <entry>String key</entry>
+ <entry>PermissionDenied, TypeMismatch</entry>
+ <entry>
+ Set property.
+ </entry>
+ </row>
+ <row>
+ <entry>SetPropertyUInt64</entry>
+ <entry>UInt64</entry>
+ <entry>String key</entry>
+ <entry>PermissionDenied, TypeMismatch</entry>
+ <entry>
+ Set property.
+ </entry>
+ </row>
+ <row>
+ <entry>SetPropertyBoolean</entry>
+ <entry>Bool</entry>
+ <entry>String key</entry>
+ <entry>PermissionDenied, TypeMismatch</entry>
+ <entry>
+ Set property.
+ </entry>
+ </row>
+ <row>
+ <entry>SetPropertyDouble</entry>
+ <entry>Double</entry>
+ <entry>String key</entry>
+ <entry>PermissionDenied, TypeMismatch</entry>
+ <entry>
+ Set property.
+ </entry>
+ </row>
+
+ <row>
+ <entry>RemoveProperty</entry>
+ <entry></entry>
+ <entry>String key</entry>
+ <entry>NoSuchProperty, PermissionDenied</entry>
+ <entry>
+ Remove a property.
+ </entry>
+ </row>
+
+ <row>
+ <entry>GetPropertyType</entry>
+ <entry>Int</entry>
+ <entry>String key</entry>
+ <entry>NoSuchProperty</entry>
+ <entry>
+ Get the type of a property. Returns the D-Bus type as an integer.
+ </entry>
+ </row>
+
+ <row>
+ <entry>PropertyExists</entry>
+ <entry>Bool</entry>
+ <entry>String key</entry>
+ <entry></entry>
+ <entry>
+ Determine if a property exists.
+ </entry>
+ </row>
+
+ <row>
+ <entry>AddCapability</entry>
+ <entry></entry>
+ <entry>String capability</entry>
+ <entry>PermissionDenied</entry>
+ <entry>
+ Adds a capability to a device.
+ </entry>
+ </row>
+
+ <row>
+ <entry>QueryCapability</entry>
+ <entry>Bool</entry>
+ <entry>String capability</entry>
+ <entry></entry>
+ <entry>
+ Determine if a device have a capability.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Lock</entry>
+ <entry>Bool</entry>
+ <entry>String reason</entry>
+ <entry>DeviceAlreadyLocked</entry>
+ <entry>
+ Acquires an advisory lock on the device. Returns TRUE if the lock was acquired.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Unlock</entry>
+ <entry>Bool</entry>
+ <entry></entry>
+ <entry>DeviceNotLocked</entry>
+ <entry>
+ Releases an advisory lock on the device. Returns TRUE if the lock was released.
+ </entry>
+ </row>
+
+ <row>
+ <entry>AcquireMandatoryLock</entry>
+ <entry></entry>
+ <entry>String lock_name</entry>
+ <entry>PermissionDenied, DeviceAlreadyLocked</entry>
+ <entry>
+ Acquires a named mandatory lock. The lock is recursive
+ (multiple callers may hold the lock). See TODO for how
+ mandatory locks work.
+ </entry>
+ </row>
+
+ <row>
+ <entry>ReleaseMandatoryLock</entry>
+ <entry></entry>
+ <entry>String lock_name</entry>
+ <entry>PermissionDenied, DeviceNotLocked</entry>
+ <entry>
+ Releases a named mandatory lock. The lock is recursive
+ (multiple callers may hold the lock). See TODO for how
+ mandatory locks work.
+ </entry>
+ </row>
+
+ <row>
+ <entry>StringListAppend</entry>
+ <entry></entry>
+ <entry>String key, String value</entry>
+ <entry>PermissionDenied, TypeMismatch</entry>
+ <entry>
+ Appends an item to a string list.
+ </entry>
+ </row>
+
+ <row>
+ <entry>StringListPrepend</entry>
+ <entry></entry>
+ <entry>String key, String value</entry>
+ <entry>PermissionDenied, TypeMismatch</entry>
+ <entry>
+ Prepends an item to a string list.
+ </entry>
+ </row>
+
+ <row>
+ <entry>StringListRemove</entry>
+ <entry></entry>
+ <entry>String key, String value</entry>
+ <entry>PermissionDenied, TypeMismatch</entry>
+ <entry>
+ Removes an item from a string list.
+ </entry>
+ </row>
+
+ <row>
+ <entry>EmitCondition</entry>
+ <entry>Bool</entry>
+ <entry>String name, String details</entry>
+ <entry>PermissionDenied</entry>
+ <entry>
+ Emit a condition on a device object.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Rescan</entry>
+ <entry>Bool</entry>
+ <entry></entry>
+ <entry>PermissionDenied</entry>
+ <entry>
+ Force an updates of the properties of a device object by
+ rereading data that is not monitored for changes.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Reprobe</entry>
+ <entry>Bool</entry>
+ <entry></entry>
+ <entry>PermissionDenied</entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+
+ <row>
+ <entry>ClaimInterface</entry>
+ <entry>Bool</entry>
+ <entry>String name, String introspection_xml</entry>
+ <entry>PermissionDenied</entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+
+ <row>
+ <entry>AddonIsReady</entry>
+ <entry>Bool</entry>
+ <entry></entry>
+ <entry>PermissionDenied</entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ The following signals are emitted:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Signal</entry>
+ <entry>Parameters</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>PropertyModified</entry>
+ <entry>Int num_changes, Array of struct {String property_name, Bool added, Bool removed}</entry>
+ <entry>
+ One or more properties on the device object have changed.
+ </entry>
+ </row>
+ <row>
+ <entry>Condition</entry>
+ <entry>String name, String details</entry>
+ <entry>
+ 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.).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+
+
+ <sect1 id="interface-device-systempower">
+ <title>org.freedesktop.Hal.Device.SystemPowerManagement interface</title>
+ <para>
+ This interface provides a mechanism to affect system-wide power
+ management. Normally only the root computer device object
+ (<literal>/org/freedesktop/Hal/devices/computer</literal>)
+ implements this interface. The following methods are available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Suspend</entry>
+ <entry>Int</entry>
+ <entry>Int num_secs_to_wakeup</entry>
+ <entry>SystemPowerManagement.NotSupported, SystemPowerManagement.AlarmNotSupported</entry>
+ <entry>
+ Puts the system in a suspended state (typically ACPI S3)
+ for <literal>num_secs_to_wakeup</literal> 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.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Hibernate</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry>SystemPowerManagement.NotSupported</entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+
+ <row>
+ <entry>SuspendHybrid</entry>
+ <entry>Int</entry>
+ <entry>Int num_secs_to_wakeup</entry>
+ <entry>SystemPowerManagement.NotSupported, SystemPowerManagement.AlarmNotSupported</entry>
+ <entry>
+ Puts the system in a suspended state (typically ACPI S3)
+ for <literal>num_secs_to_wakeup</literal> 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.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Shutdown</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry>SystemPowerManagement.NotSupported</entry>
+ <entry>
+ Shut down the system.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Reboot</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry>SystemPowerManagement.NotSupported</entry>
+ <entry>
+ Reboot the system.
+ </entry>
+ </row>
+
+ <row>
+ <entry>SetPowerSave</entry>
+ <entry>Int</entry>
+ <entry>Bool should_save_power</entry>
+ <entry>SystemPowerManagement.NotSupported</entry>
+ <entry>
+ If the boolean passed is TRUE, the system will be
+ configured to save as much power as possible by
+ e.g. enabling <literal>laptop mode</literal> to avoid
+ spinning up disks. Typically, power management daemons
+ will call this method when it determines that the system
+ is running on battery power.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This interface does not emit any signals.
+ </para>
+ </sect1>
+
+ <sect1 id="interface-cpufreq">
+ <title>org.freedesktop.Hal.Device.CPUFreq interface</title>
+ <para>
+ This interface provides a mechanism to configure CPU frequency
+ scaling. The following methods are available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>GetCPUFreqAvailableGovernors</entry>
+ <entry>String[]</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ Retrieves a list of available CPU scaling governors.
+ </entry>
+ </row>
+ <row>
+ <entry>GetCPUFreqGovernor</entry>
+ <entry>String</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ Get currently selected CPU Frequency governor.
+ </entry>
+ </row>
+ <row>
+ <entry>SetCPUFreqGovernor</entry>
+ <entry>Int</entry>
+ <entry>String governor</entry>
+ <entry>CPUFreq.UnknownGovernor</entry>
+ <entry>
+ Selects a CPU Frequency governor to use.
+ </entry>
+ </row>
+ <row>
+ <entry>SetCPUFreqPerformance</entry>
+ <entry>Int</entry>
+ <entry>Int percent</entry>
+ <entry>CPUFreq.NoSuitableGovernor</entry>
+ <entry>
+ 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.
+ </entry>
+ </row>
+ <row>
+ <entry>GetCPUFreqPerformance</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry>CPUFreq.NoSuitableGovernor</entry>
+ <entry>
+ Get the tuning value for the governor.
+ </entry>
+ </row>
+ <row>
+ <entry>SetCPUFreqConsiderNice</entry>
+ <entry>Int</entry>
+ <entry>Bool consider_niced_processes</entry>
+ <entry>CPUFreq.NoSuitableGovernor</entry>
+ <entry>
+ 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'.
+ </entry>
+ </row>
+ <row>
+ <entry>SetCPUFreqConsiderNice</entry>
+ <entry>Bool</entry>
+ <entry></entry>
+ <entry>CPUFreq.NoSuitableGovernor</entry>
+ <entry>
+ Whether nice'ed processes are considered by the governor.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This interface does not emit any signals.
+ </para>
+ </sect1>
+
+ <sect1 id="interface-device-laptop-panel">
+ <title>org.freedesktop.Hal.Device.LaptopPanel interface</title>
+ <para>
+ This interface provides a mechanism to get/set the brightness of
+ a laptop panel. The following methods are available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>GetBrightness</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ Get the current brightness.
+ </entry>
+ </row>
+ <row>
+ <entry>SetBrightness</entry>
+ <entry></entry>
+ <entry>Int brightness</entry>
+ <entry></entry>
+ <entry>
+ Set the current brightness.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This interface does not emit any signals.
+ </para>
+ </sect1>
+
+ <sect1 id="interface-device-keyboard-backlight">
+ <title>org.freedesktop.Hal.Device.KeyboardBacklight interface</title>
+ <para>
+ This interface provides a mechanism to get/set the brightness of
+ the keyboard backlight. The following methods are available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>GetBrightness</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ Get the current brightness.
+ </entry>
+ </row>
+ <row>
+ <entry>SetBrightness</entry>
+ <entry></entry>
+ <entry>Int brightness</entry>
+ <entry></entry>
+ <entry>
+ Set the current brightness.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This interface does not emit any signals.
+ </para>
+ </sect1>
+
+ <sect1 id="interface-device-light-sensor">
+ <title>org.freedesktop.Hal.Device.LightSensor interface</title>
+ <para>
+ This interface provides a mechanism to get information from a
+ light sensor. The following methods are available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>GetBrightness</entry>
+ <entry>Int[]</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ The current brightness as measured by the light sensor.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This interface does not emit any signals.
+ </para>
+ </sect1>
+
+ <sect1 id="interface-device-storage">
+ <title>org.freedesktop.Hal.Device.Storage interface</title>
+ <para>
+ This interface provides a mechanism to interact with a storage
+ device. The following methods are available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Eject</entry>
+ <entry>Int</entry>
+ <entry>String[] options</entry>
+ <entry>Volume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidEjectOption</entry>
+ <entry>
+ Unmounts all volumes and possibly ejects the media. Note
+ that this method is not only restricted to optical
+ drives.
+ </entry>
+ </row>
+ <row>
+ <entry>CloseTray</entry>
+ <entry>Int</entry>
+ <entry>String[] options</entry>
+ <entry>Storage.InvalidCloseTrayOption</entry>
+ <entry>
+ Attempts to close the tray. Only really makes sense for
+ (optical) drives that uses a tray loading mechanism.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This interface does not emit any signals.
+ </para>
+ </sect1>
+
+ <sect1 id="interface-device-volume">
+ <title>org.freedesktop.Hal.Device.Volume interface</title>
+ <para>
+ This interface provides a mechanism to interact with a volume
+ that has a mountable file system. The following methods are
+ available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Mount</entry>
+ <entry>Int</entry>
+ <entry>String mount_point, String fstype, String[] options</entry>
+ <entry>Volume.PermissionDenied, Volume.AlreadyMounted, Volume.InvalidMountOption, Volume.UnknownFilesystemType, Volume.InvalidMountPoint, Volume.MountPointNotAvailable, Volume.CannotRemount</entry>
+ <entry>
+ Mounts a volume.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Unmount</entry>
+ <entry>Int</entry>
+ <entry>String[] options</entry>
+ <entry>Volume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidUnmountOption</entry>
+ <entry>
+ Unmount a volume.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Eject</entry>
+ <entry>Int</entry>
+ <entry>String[] options</entry>
+ <entry>Volume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidEjectOption</entry>
+ <entry>
+ Unmounts all volumes from the originating drive and
+ possibly ejects the media. Note that this method is not
+ only restricted to optical drives.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This interface does not emit any signals.
+ </para>
+ </sect1>
+
+ <sect1 id="interface-device-volume-crypto">
+ <title>org.freedesktop.Hal.Device.Volume.Crypto interface</title>
+ <para>
+ This interface provides a mechanism to interact with a volume that
+ is encrypted at the block layer. The following methods are
+ available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Setup</entry>
+ <entry>Int</entry>
+ <entry>String passphrase</entry>
+ <entry>Volume.Crypto.CryptSetupMissing, Volume.Crypto.SetupError, Volume.Crypto.SetupPasswordError</entry>
+ <entry>
+ Unlocks an encrypted file system. If successful, a cleartext volume will appear.
+ </entry>
+ </row>
+
+ <row>
+ <entry>Teardown</entry>
+ <entry>Int</entry>
+ <entry></entry>
+ <entry>Volume.Crypto.TeardownError</entry>
+ <entry>
+ Teardown the cleartext volume.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This interface does not emit any signals.
+ </para>
+ </sect1>
+
+<!--
+ <sect1 id="interface-device-foo">
+ <title>org.freedesktop.Hal.Device.Foo interface</title>
+ <para>
+ This interface provides a mechanism... The following methods
+ are available:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ The following signals are emitted:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Signal</entry>
+ <entry>Parameters</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+-->
+
+</chapter>
diff --git a/doc/spec/hal-spec-introduction.xml b/doc/spec/hal-spec-introduction.xml
index c8f514c..90ab644 100644
--- a/doc/spec/hal-spec-introduction.xml
+++ b/doc/spec/hal-spec-introduction.xml
@@ -29,10 +29,10 @@
configure devices based on these properties.
</para>
<para>
- HAL provides an easy-to-use API through D-BUS which is an IPC
+ HAL provides an easy-to-use API through D-Bus which is an IPC
framework that, among other things, provides a system-wide
message-bus that allows applications to talk to one
- another. Specifically, D-BUS provides asynchronous
+ another. Specifically, D-Bus provides asynchronous
notification such that HAL can notify other peers on the
message-bus when devices are added and removed as well as when
properties on a device are changing.
@@ -41,7 +41,7 @@
The most important goal of HAL is to provide plug-and-play
facilities for UNIX-like desktops with focus on providing a
rich and extensible description of device characteristics and
- features. HAL has no other major dependencies apart from D-BUS
+ features. HAL has no other major dependencies apart from D-Bus
which, given sufficient infrastructure, allows it to be
implemented on many UNIX-like systems. The major focus,
initially, is systems running the Linux 2.6 series kernels.
@@ -71,7 +71,7 @@
<para>
The HAL consists of a number of components as outlined in the
diagram below. Note that this diagram is high-level and doesn't
- capture implementation details.
+ capture all implementation details.
</para>
<para>
<inlinegraphic fileref="hal-arch.png" format="PNG"/>
@@ -83,15 +83,11 @@
<emphasis>HAL daemon</emphasis>
</para>
<para>
- A system-wide daemon that maintains a persistent database of
- device objects. The daemon is also responsible for merging
- information from the device information file repository and
- managing the life cycle of device objects. The HAL daemon
- also contains detection and monitoring code for
- buses (such as PCI and USB buses) and devices (such as
- networking and storage devices). The HAL daemon notifies system
- level components through callouts and session level
- components using the D-BUS interface.
+ A system-wide service that maintains a database of device
+ objects. The daemon is responsible for merging information
+ from device information files and managing the life cycle
+ of device objects. The service is implemented as a daemon
+ and uses helpers to query devices for specific information.
</para>
</listitem>
<listitem>
@@ -99,31 +95,9 @@
<emphasis>Applications</emphasis>
</para>
<para>
- This represents the end consumers of the HAL and comprises
- both applications that need to search for a device, but
- also (existing) device specific libraries and/or services
- that provide access to devices. Specifically, the
- application or device library can obtain the ''address''
- (the special device file or other details), of the device
- through HAL, to interact with the device through the
- kernel as usual.
- </para>
- <para>
- In addition, this group include desktop environments such
- as GNOME or KDE. Specifically, using HAL, desktop
- environments may include session-level daemons enforcing
- certain policies when the device database managed by the
- HAL daemon changes. Such policies may include starting a
- photo management application when a camera is plugged in,
- assisting the user in finding driver software and device
- information files for a new device, displaying link status
- information about network devices, mounting removable
- storage and so on.
- </para>
- <para>
- Note that several desktop sessions may be active on the
- same system; it is the responsibility of session-level
- software to arbitrate the device access between sessions.
+ These are applications consuming services from HAL; this
+ includes desktop-wide session daemons for maintaining
+ policy such as power and disk/volume management.
</para>
</listitem>
<listitem>
@@ -131,82 +105,71 @@
<emphasis>Callouts</emphasis>
</para>
<para>
- Callouts are programs invoked when the device object list
- is modified As such, callouts can be used to maintain
- system-wide policy (that may be specific to the particular
- OS) such as changing permissions on device nodes, updating
- the systemwide <literal>/etc/fstab</literal> file or
- configuring the networking subsystem.
+ Callouts are programs that run when device objects are
+ added and removed in the HAL daemon. This is useful for
+ 3rd party software to merge additional information onto
+ the device object before it is announced on
+ D-Bus. Callouts are specified on a per-device basis with
+ the <literal>info.callouts.add</literal> and
+ <literal>info.callouts.remove</literal>. See
+ <xref linkend="device-properties-info"/> for details.
</para>
</listitem>
- </itemizedlist>
- </para>
- <para>
- The HAL uses D-BUS to provide a ''network API'' to
- applications. As D-BUS is designed to be language independent,
- potentially many languages / runtime systems will be able to
- easily access the services offered by HAL. The D-BUS API is
- detailed in <xref linkend="dbus-api"/>
- .
- Note that HAL doesn't
- enforce any policy at all, this is left for desktop environments
- and operating systems vendors to implement. However, to ensure
- interoperability between operating systems and desktop
- environments, recommendations and best practises on how to
- enforce policy is discussed in <xref linkend="enforcing-policy"/>
- .
- </para>
- </sect1>
- <sect1 id="ov_hal_linux26">
- <title>HAL on Linux 2.6</title>
- <para>
- On a Linux 2.6 system HAL is implemented as shown in the diagram
- below:
- </para>
- <para>
- <inlinegraphic fileref="hal-linux26.png" format="PNG"/>
- </para>
- <para>
- Highlights
- <itemizedlist>
<listitem>
<para>
- HAL depends on the <literal>udev</literal> and
- <literal>linux-hotplug</literal> packages
+ <emphasis>Methods</emphasis>
</para>
- </listitem>
- <listitem><para>
- The diagram shows an example callout program,
- <literal>fstab-sync</literal>, that creates/destroys
- mount points and modifies the <literal>/etc/fstab</literal>
- file accordingly whenever storage devices are added or
- removed.
+ <para>
+ It is possible to specify that a given HAL device object
+ implements a specific D-Bus interface,
+ e.g. <literal>org.freedesktop.Hal.Device.Frob</literal>
+ with a set of
+ methods <literal>Foo</literal>, <literal>Bar</literal>
+ and <literal>Baz</literal> and have programs run when
+ applications call into this interface. This is defined in
+ the <literal>info.interfaces</literal> property, consult
+ <xref linkend="device-properties-info"/> for details.
</para>
</listitem>
- <listitem><para>
- A session-level daemon, <literal>*-volume-manager</literal>,
- for mounting storage devices is shown. This piece of software
- depends on a properly updated <literal>/etc/fstab</literal>
- file and a setuid <literal>mount(1)</literal> binary that
- allows an unprivileged user to mount devices marked with option
- <literal>user</literal> in the <literal>/etc/fstab</literal> file.
+ <listitem>
+ <para>
+ <emphasis>Addons</emphasis>
+ </para>
+ <para>
+ An <emphasis>addon</emphasis> can be characterized as a
+ daemon whose life cycle is tied to a device object in
+ HAL. And addon can also <emphasis>claim</emphasis> a
+ specific interface on the device object to provide
+ services to applications for configuring / using the
+ device without having to spawn a new program for every
+ method call. HAL provides a facility to launch/destroy one
+ or more addons per device object using
+ the <literal>info.addons</literal> property. See
+ <xref linkend="device-properties-info"/> for details.
</para>
</listitem>
- <listitem><para>
- The <literal>fstab-sync</literal> and
- <literal>*-volume-manager</literal> programs are only
- examples on how to enforce policy and are not part of HAL
- proper. An OS vendor may choose to enforce policy in a
- different way e.g. he might want to ignore the
- <literal>/etc/fstab</literal> file and mount storage volumes
- in the callout, run a daemon with sufficient privileges
- or use another setuid mount wrapper.
- See <xref linkend="enforcing-policy"/>
- for more details.
+ <listitem>
+ <para>
+ <emphasis>Device Information Files</emphasis>
+ </para>
+ <para>
+ A set of files that matches properties on device objects
+ and merges additional information. These files are used,
+ for among other things, to specify what callouts, methods
+ and addons to associate with a device object. For example,
+ for drives using removable media, HAL includes an add-on
+ daemon which sole purpose is to continously poll the drive
+ to detect media change.
</para>
</listitem>
</itemizedlist>
</para>
+ <para>
+ The D-Bus system message bus is used to provide a ''network
+ API'' to applications. As D-Bus is designed to be language
+ independent, potentially many languages / runtime systems will
+ be able to easily access the services offered by HAL.
+ </para>
</sect1>
<sect1>
@@ -234,29 +197,30 @@
Device objects in HAL are organised on a by-connection basis,
e.g. for a given device object X it is possible to find the
device object Y where X is attached to Y. This gives structure
- to the device database of HAL; it is possible to map the
- devices out in a tree. Further, software emulation devices
- exported by a kernel, such as SCSI emulation for USB Storage
- Devices, are also considered device objects in HAL. This
- implies that kernel specific bits leak into the device object
- database. However users of HAL won't notice, such device
- objects are not referenced anywhere in the device objects that
- users are interested in; they are merely used as glue to build
- the device tree.
- </para>
- <para>
- In addition to provide information about what kind of hardware
- a device object represents (such as a PCI or USB device) and
- how to address it, HAL merges information about the functional
- interfaces the OS kernel provides in order to use the device;
- in most cases this is represented on the device object as a
- string property with the name of the special device file in
- <literal>/dev</literal>. In addition to the special device
- file, a number of other useful properties are merged. This
- means that both hardware and functional properties are on the
- same device object, which is very useful for an application
- programmer. For example, an application might query HAL for
- the device object that exports the special device file
+ to the device database of HAL; it is possible to map the devices
+ out in a tree. Further, software emulation devices exported by
+ the operating system kernel, such as SCSI emulation for USB
+ Storage Devices, are also considered device objects in HAL. This
+ implies that operating system kernel specific bits leak into the
+ device object database. However users of HAL won't notice, such
+ device objects are not referenced anywhere in the device objects
+ that users are interested in; they are merely used as glue to
+ build the device tree.
+ </para>
+ <para>
+ In addition to provide information about what kind of hardware a
+ device object represents (such as a PCI or USB device) and how
+ to address it, HAL merges information about the functional
+ interfaces the operating system kernel provides in order to use
+ the device; in most cases this is represented on the device
+ object as a string property with the name of the special device
+ file in
+ <literal>/dev</literal>. In addition to the special device file,
+ a number of other useful properties are merged. This means that
+ both hardware and functional properties are on the same device
+ object, which may prove to be useful for an application
+ programmer. For example, an application might query HAL for the
+ device object that exports the special device file
<literal>/dev/input/mouse2</literal> and learn that this is
provide by an USB mouse from a certain manufacturer by
checking the properties that export the USB vendor and product
@@ -266,7 +230,7 @@
for details.
</para>
<para>
- On a formal level, a device object is comprised by
+ An HAL device object is comprised by
</para>
<itemizedlist>
<listitem>
@@ -274,12 +238,13 @@
<emphasis>UDI</emphasis>
</para>
<para>
- This is an identifier, the Unique Device Identifer, that is
- unique for a device object - that is, no other device object
- can have the same UDI at the same time. The UDI is computed
- using bus-specific information and is meant to be unique
- across device insertions and independent of the physical
- port or slot the device may be plugged into.
+ This is the the <emphasis>Unique Device
+ Identifer</emphasis>, that is unique for a device object -
+ that is, no other device object can have the same UDI at the
+ same time. The UDI is computed using bus-specific
+ information and is meant to be unique across device
+ insertions and independent of the physical port or slot the
+ device may be plugged into.
</para>
</listitem>
<listitem>
@@ -298,7 +263,7 @@
</listitem>
<listitem>
<para>
- <literal>strlist</literal> - sorted list with UTF8 strings
+ <literal>strlist</literal> - ordered list with UTF8 strings
</para>
</listitem>
<listitem>
@@ -364,19 +329,20 @@
</listitem>
</itemizedlist>
<para>
- The first category is determined by HAL, the next is merged
- from either the hardware itself or device information files,
- the third is intercepted by monitoring the operating system
- and the last is merged from files that only the system
- administrator can edit. This specification is concerned with
- precisely defining several properties; see <xref linkend="device-properties"/>
- and onwards for more
+ The first category is determined by HAL, the second category
+ includes information merged from either querying the hardware
+ itself or from device information files. The third category is
+ intercepted by monitoring the hardware and finally the last is
+ merged from files under control of the system
+ administrator. This document is concerned with precisely
+ defining several properties; see
+ <xref linkend="device-properties"/> and onwards for more
information. As a complement to device properties, HAL also
provides <emphasis>conditions</emphasis> on HAL device
- objects. Conditions are used to relay events that are
- happening on devices which are not easily expressed in
- properties. This includes events such as ''processor is
- overheating'' or ''block device unmounted''.
+ objects. Conditions are used to relay events that are happening
+ on devices which are not easily expressed in properties. This
+ includes events such as ''processor is overheating'' or ''block
+ device unmounted''.
</para>
<para>
There is a special hal device object referred to as the ''root
@@ -406,14 +372,14 @@
<sect1 id="device-capabilities">
<title>Device Capabilities</title>
<para>
- Mainstream hardware isn't very good at reporting what they are,
- they only report, at best, how to interact with them. This is a
+ Mainstream hardware isn't very good at reporting what it really
+ is, it only reports, at best, how to interact with it. This is a
problem; many devices, such as MP3 players or digital still
cameras, appear to the operating system as plain USB Mass
- Storage devices when they in fact are a lot more than just
- that. The core of the problem is that without external
- metadata, the operating system and desktop environment will
- present it to the user as just e.g. a mass storage device.
+ Storage devices when the device in fact is a lot more than just
+ that. The core of the problem is that without external metadata,
+ the operating system and desktop environment will present it to
+ the user as just e.g. a mass storage device.
</para>
<para>
As HAL is concerned with merging of external metadata, through
@@ -432,21 +398,14 @@
HAL itself, assigns capabilities on device detection time by
inspecting the device class (if available, it depends on the
bus type) and looking at information from the operating system
- (most OS'es have a concept of device classes). At this time the
- category is also determined by selecting the most prominent
- capability. However, both capabilities and category can be
- overridden by either device information files or callouts. This
- gives maximum flexibility, while maintaining a base level of
- capability detection.
+ and the hardware itself.
</para>
<para>
- The idea of HAL is that existing device capability specific
- libraries (such as libghoto2), would advertise what kind of HAL
- capabilities they are able to handle. As this happens over
- time, this specification will grow to precisely define what a
- device with a given capability is supposed to do and what
- library, or service, the application programmer can use to
- access the device.
+ User mode drivers such as <literal>libgphoto2</literal>
+ and <literal>sane</literal> provides device information to
+ merge information about devices they can drive. As such,
+ device objects represent an USB interface gain additional
+ properties such as ''scanner'' or ''camera''.
</para>
<para>
Having a capability also means that part of the property
@@ -455,16 +414,10 @@
some properties may even be required such that applications and
device libraries have something to expect. For instance, the
capability for being a MP3 player may require properties
- defining what audio formats the device support, whether it
- support recording of audio, and how to interact with the
- device. For example, the latter may specify ''USB Storage
- Device'' or ''proprietary protocol, use libfooplayer''.
- </para>
- <para>
- Just as device objects can appear and disappear at any time
- (e.g. when a device is plugged in respectively removed),
- capabilities can also appear and disappear - one example of
- this happening is when device drivers are loaded and unloaded.
+ defining what audio formats the device support (e.g. Ogg and
+ MP3), whether it support recording of audio, and how to interact
+ with the device. For example, the latter may specify ''USB
+ Storage Device'' or ''proprietary protocol, use libfooplayer''.
</para>
<para>
Finally, capabilities have an inheritance scheme, e.g. if a device
@@ -473,35 +426,4 @@
</para>
</sect1>
- <sect1 id="using-devices">
- <title>Using devices</title>
- <para>
- While the HAL daemon provides generic operations that apply to
- all devices (though some may be no-ops), HAL is not concerned
- with providing non-generic device operations. Specifically, one
- goal of HAL is to integrate with existing and future libraries
- that target a specific class of devices such as cameras or mp3
- players.
- </para>
- <para>
- For instance, <literal>libgphoto2</literal> could be extended
- such that the application programmer can simply pass the UDI of
- the camera he wishes to interact with
- and <literal>libghoto2</literal> would then, via D-BUS, acquire
- the bus-specific information required, the address so to speak,
- from the HAL daemon, and then interact directly with the
- hardware.
- </para>
- <para>
- Another option is to use the existing API of the device library
- to discover devices (the library would be using HAL under the
- hood) and provide a function to retrieve the HAL UDI of the
- device. When the library is built without HAL support this
- function returns <literal>NULL</literal>, however, when the UDI
- is available, then applications using the library can use the
- UDI both as stable reference to the device and also to extract
- more information directly from the HAL daemon.
- </para>
- </sect1>
-
</chapter>
diff --git a/doc/spec/hal-spec-properties.xml b/doc/spec/hal-spec-properties.xml
index e454143..83263d7 100644
--- a/doc/spec/hal-spec-properties.xml
+++ b/doc/spec/hal-spec-properties.xml
@@ -8,11 +8,12 @@
and are key/value pairs. The value may assume different types; currently
int32, double, bool, UTF8 strings and UTF8 string lists are supported.
The key of a property is always an ASCII string without any whitespace.
- The properties are updated in real-time.
+ When a property changes, HAL will emit a D-Bus signal that applications
+ can catch.
</para>
- <sect1 id="properties-metadata">
- <title>Metadata Properties</title>
+ <sect1 id="properties-general">
+ <title>General Properties</title>
<para>
The section represents properties that aren't tied to either
physical or functional characteristics of what the device
@@ -20,7 +21,7 @@
</para>
<sect2 id="device-properties-info">
<title>
- <literal>info</literal> namespace
+ info namespace
</title>
<para>
The <literal>info</literal> namespace contain properties that
@@ -56,28 +57,6 @@
</row>
<row>
<entry>
- <literal>info.persistent</literal> (bool)
- </entry>
- <entry></entry>
- <entry>
- No, but required if <literal>info.not_available</literal> is set to TRUE
- </entry>
- <entry>If this property is set, the device will remain in the
- the GDL even if the device is unplugged. NOTE: property not implemented yet
- </entry>
- </row>
- <row>
- <entry>
- <literal>info.not_available</literal> (bool)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>The device is currently not available (it may be unplugged
- or powered down) NOTE: property not implemented yet
- </entry>
- </row>
- <row>
- <entry>
<literal>info.capabilities</literal> (strlist)
</entry>
<entry>example: 'block, storage, storage.cdrom'</entry>
@@ -98,7 +77,7 @@
</entry>
<entry>examples: ''SleekKeyboard'', ''MouseMan 2003'', ''Volume'', ''LS-120 SLIM3 00 UHD Floppy''</entry>
<entry>No</entry>
- <entry>The name of the device</entry>
+ <entry>The name of the device; should not be used in any UI; use subsystem / capability specific properties instead.</entry>
</row>
<row>
<entry>
@@ -106,13 +85,13 @@
</entry>
<entry>examples: Logitch, Mustek</entry>
<entry>No</entry>
- <entry>The name of the vendor of the device</entry>
+ <entry>The name of the vendor of the device; should not be used in any UI; use subsystem / capability specific properties instead.</entry>
</row>
<row>
<entry>
<literal>info.parent</literal> (string)
</entry>
- <entry>example: /org/freedesktop/Hal/devices/ide_1_0</entry>
+ <entry>example: /org/freedesktop/Hal/devices/computer</entry>
<entry>Yes, for all non-root device objects</entry>
<entry>The UDI of the device object that this device object
is connected to.
@@ -193,15 +172,59 @@
</tbody>
</tgroup>
</informaltable>
+
</sect2>
- <sect2 id="device-properties-linux">
- <title>
- <literal>linux</literal> namespace
- </title>
+ <sect2 id="device-properties-info-callouts">
+ <title>Callouts</title>
+
+ <para>
+ Callouts are programs invoked when the device object are added
+ and removed. As such, callouts can be used to maintain
+ system-wide policy (that may be specific to the particular OS)
+ such as changing permissions on device nodes, updating the
+ systemwide
+ <literal>/etc/fstab</literal> file or configuring the networking
+ subsystem.
+ </para>
+ <para>
+ There are three different classes of callouts. A callout
+ involves sequentially invoking all executable programs in the
+ string list in listed order.
+ </para>
+
+ <para>
+ All callouts execute in a minimal environment. In addition, the
+ UDI of the device object is exported in the environment
+ variable <literal>UDI</literal>. All properties of the device
+ object are exported in the environment prefixed
+ with <literal>HAL_PROP_</literal>. If a device is added or removed is
+ exported in the environment variable <literal>HALD_ACTION
+ </literal>.
+ </para>
+ <para>
+ If ConsoleKit support is enabled, the variables
+ <literal>CK_SEATS</literal> (tab sep. list of seat-id's),
+ <literal>CK_SEAT_seat-id</literal> (tab sep. list of session-id's for a seat),
+ <literal>CK_SESSION_IS_ACTIVE_session-id</literal> (whether a given session is active) and
+ <literal>CK_SESSION_UID_session-id</literal> (the user of the session)
+ <literal>CK_SESSION_IS_LOCAL_session-id</literal> (whether a session is local),
+ will be exported as well.
+ </para>
+ <para>
+ The HAL daemon is not suspended while callouts are executing. Thus,
+ callouts can communicate with the HAL daemon using the D-BUS network
+ API. Hence, one application of callouts is to merge or modify
+ properties on a device object.
+ </para>
+
<para>
- This namespace is used to store Linux-specific metadata about the
- device object and is only available on Linux systems.
+ To reduce round trips and increase privacy, callouts can (and
+ should) communicate with the HAL daemon using a peer to peer
+ D-Bus connection specified by
+ the <literal>HALD_DIRECT_ADDR</literal> environment
+ variable. There is convience API in libhal to do this.
</para>
+
<informaltable>
<tgroup cols="2">
<thead>
@@ -215,61 +238,291 @@
<tbody>
<row>
<entry>
- <literal>linux.sysfs_path</literal> (string)
+ <literal>info.callouts.add</literal> (string list)
</entry>
- <entry>examples: /sys/block/sda/sda1, /sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0</entry>
- <entry>Yes (only if available for the device) </entry>
- <entry>A fully-qualified path into the sysfs filesystem for the
- device
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ A string list with the programs which should be
+ executed (with <literal>HALD_ACTION=add</literal>)
+ when the device is added to the GDL (global device
+ list) but just before it is announced through the
+ D-BUS network API.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>info.callouts.remove</literal> (string list)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ A string list with the programs that should be
+ executed (with <literal>HALD_ACTION=remove</literal>)
+ when the device is removed from the GDL (global device
+ list). The device isn't removed before the last
+ callout has finished.
</entry>
</row>
<row>
<entry>
- <literal>linux.acpi_path</literal> (string)
+ <literal>info.callouts.preprobe</literal> (string list)
</entry>
- <entry>example: /proc/acpi/button/power/PWRF, /proc/pmu/battery_0</entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ A string list with the programs that should be
+ executed
+ (with <literal>HALD_ACTION=preprobe</literal>) before
+ the device is probed (e.g. investigated) and can be
+ used to avoid causing unnecessary I/O.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>info.callouts.session_add</literal> (string list)
+ </entry>
+ <entry/>
<entry>No</entry>
<entry>
- A fully-qualified path into the procfs filesystem for a
- device object representing an ACPI abstraction.
+ A string list with all programs that should be
+ executed
+ (with <literal>HALD_ACTION=session_add</literal>) when
+ a session is added. Can only be set on the root
+ computer device object. The environment also contains
+ the variables
+ <literal>HALD_SESSION_ADD_SESSION_ID</literal>,
+ <literal>HALD_SESSION_ADD_SESSION_UID</literal> and
+ <literal>HALD_SESSION_ADD_SESSION_IS_ACTIVE</literal>
+ to identify the session. This is only used when HAL is
+ built with ConsoleKit support.
</entry>
</row>
<row>
<entry>
- <literal>linux.driver</literal> (string)
+ <literal>info.callouts.session_remove</literal> (string list)
</entry>
- <entry>examples: agpgart-intel, yenta_cardbus, usb, hub, usbhid</entry>
+ <entry/>
<entry>No</entry>
- <entry>Name of the driver bound to this device</entry>
+ <entry>
+ A string list with all programs which should be
+ executed
+ (with <literal>HALD_ACTION=session_remove</literal>)
+ when a session is removed. Can only be set on the root
+ computer device object. The environment also contains
+ the variables
+ <literal>HALD_SESSION_REMOVE_SESSION_ID</literal>,
+ <literal>HALD_SESSION_REMOVE_SESSION_UID</literal> and
+ <literal>HALD_SESSION_REMOVE_SESSION_IS_ACTIVE</literal>
+ to identify the session. This is only used when HAL is
+ built with ConsoleKit support.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ </sect2>
+ <sect2 id="device-properties-info-addons">
+ <title>Addons</title>
+
+ <para>
+ Addons are programs that run for the life time of the device
+ object. They execute in the same environment as callouts
+ (e.g. with <literal>HAL_PROP_*</literal> set in the
+ environment to represent the device properties) and are
+ launched just before the device is announced on D-Bus (but
+ just after the last add callouts have finished). When the
+ device object goes away, HAL will send
+ a <literal>SIGTERM</literal> to the process.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Key (type)</entry>
+ <entry>Values</entry>
+ <entry>Mandatory</entry>
+ <entry>Description</entry>
</row>
+ </thead>
+ <tbody>
<row>
<entry>
- <literal>linux.kernel_devname</literal> (string)
+ <literal>info.addons</literal> (strlist)
</entry>
- <entry>example: usb-0000:00:07.2-1.2</entry>
+ <entry></entry>
<entry>No</entry>
- <entry>A name used internally in the Linux kernel to identify
- the device. Used internally in HAL.
+ <entry>
+ List of programs to run when device is added. Each
+ program will need to call
+ the <literal>AddonIsReady()</literal> method in order
+ for the device to show up on D-Bus.
</entry>
</row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ </sect2>
+ <sect2 id="device-properties-info-method-calls">
+ <title>Method calls</title>
+
+ <para>
+ Method calls on a specific interface on a device object can be
+ implemented by the HAL daemon running a program. Note that
+ this is not the only way to implement support for method
+ calls; if you expect a lot of method calls it is preferable to
+ implement an addon and use
+ the <literal>ClaimInterface()</literal> API since it reduces
+ the overhead of spawning a process and it can handle both
+ complex incoming and return types as well. See <xref linkend="interface-device"/> for
+ details on claiming interfaces via an addon..
+ </para>
+
+ <para>
+ Note that method calls implemented via running a program are
+ limited to the return type being an a signed 32-bit integer
+ (this will change in a future release). The incoming
+ parameters are limited to only basic types and arrays of
+ strings. The parameters are passed via stdin using a textual
+ representation. As such, there is a lot of overhead with
+ handling method calls by spawning programs and as such it
+ should only be used for situtations where the nature of the
+ method call is that it will not be frequently used.
+ </para>
+
+ <para>
+ As with addons, method calls execute in the same minimal
+ environment as callouts
+ (e.g. with <literal>HAL_PROP_*</literal> set in the
+ environment to represent the device properties) and in
+ addition the environment variables
+ <literal>HAL_METHOD_INVOKED_BY_UID</literal> (the uid of the caller)
+ and
+ <literal>HAL_METHOD_INVOKED_BY_SYSTEMBUS_CONNECTION_NAME</literal>
+ (the unique system bus connection name of the caller) are
+ set (If HAL, or a HAL addon, is invoking a method, then these
+ variables will both assume the value 0.)
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Key (type)</entry>
+ <entry>Values</entry>
+ <entry>Mandatory</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
<row>
<entry>
- <literal>linux.is_selinux_enabled</literal> (bool)
+ <literal>info.interfaces</literal> (strlist)
</entry>
<entry></entry>
- <entry>No; can only appear on the root computer device object</entry>
- <entry>Whether SELinux is enabled on the system</entry>
+ <entry>No</entry>
+ <entry>
+ A list of D-Bus interfaces that the device object
+ supports apart from the
+ standard <literal>org.freedesktop.Hal.Device</literal>
+ interface.
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal><iface>.method_names</literal> (strlist)
+ </entry>
+ <entry>example: <literal>'Foo', 'Bar', 'Baz'</literal></entry>
+ <entry>No</entry>
+ <entry>
+ If a D-Bus interface is implemented by executing a
+ program for every method, this property contains an
+ ordered list of the method names.
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal><iface>.method_argnames</literal> (strlist)
+ </entry>
+ <entry>example: <literal>'foo_arg1 foo_arg2', '', 'baz_arg1'</literal></entry>
+ <entry>No</entry>
+ <entry>
+ This property contains the names of the arguments for
+ each method. Each entry is a white-space separated
+ list for that particular method.
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal><iface>.method_signatures</literal> (strlist)
+ </entry>
+ <entry>example: <literal>'si', '', 'as'</literal></entry>
+ <entry>No</entry>
+ <entry>
+ This property contains the D-Bus signature for each
+ method. The signature should only cover incoming
+ arguments; each method is defined as returning an
+ integer.
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal><iface>.method_execpaths</literal> (strlist)
+ </entry>
+ <entry>example: <literal>'foo-binary', 'bar-binary', 'baz-binary'</literal></entry>
+ <entry>No</entry>
+ <entry>
+ This property contains the name of the program to
+ execute when this method is called. The return code
+ of the program will be passed as the integer result
+ to the D-Bus caller.
+
+ If a program wants to return an error, it just needs
+ to write two lines to stderr; the first line is the
+ exception name to throw and the second line is the
+ exception detail.
+ </entry>
</row>
+
</tbody>
</tgroup>
</informaltable>
+
<para>
+ Items in the <literal><iface>.*</literal> clearly must
+ correspond with each other. The whole mechanism is best
+ explained by an example:
+
+ <programlisting>
+info.interfaces = {'org.freedesktop.Hal.Device.Volume'}
+org.freedesktop.Hal.Device.Volume.method_argnames = {'mount_point fstype extra_options', 'extra_options', 'extra_options'}
+org.freedesktop.Hal.Device.Volume.method_execpaths = {'hal-storage-mount', 'hal-storage-unmount', 'hal-storage-eject'}
+org.freedesktop.Hal.Device.Volume.method_names = {'Mount', 'Unmount', 'Eject'}
+org.freedesktop.Hal.Device.Volume.method_signatures = {'ssas', 'as', 'as'}
+ </programlisting>
+
+ which, for example, shows that the <literal>Mount()</literal>
+ method on the
+ interface <literal>org.freedesktop.Hal.Device.Volume</literal>
+ takes three arguments: <literal>mount_point</literal> (a
+ string), <literal>fstype</literal> (a string)
+ and <literal>extra_options</literal> (an array of strings).
+
</para>
</sect2>
+
</sect1>
<sect1 id="properties-subsystem">
- <title>Properties</title>
+ <title>Subsystem-Specific Properties</title>
<para>
In this section properties for device objects that represent
addressable hardware is described. Availability of
@@ -282,7 +535,7 @@
</para>
<sect2 id="device-properties-pci">
<title>
- <literal>pci</literal> namespace
+ pci namespace
</title>
<para>
This namespace contains properties for device objects representing
@@ -408,7 +661,7 @@
</sect2>
<sect2 id="device-properties-serialif">
<title>
- <literal>serial</literal> namespace
+ serial namespace
</title>
<para>
Device objects that represent serial devices (e.g. /dev/ttyS* or
@@ -468,7 +721,7 @@
</sect2>
<sect2 id="device-properties-usb">
<title>
- <literal>usb_device</literal> namespace
+ usb_device namespace
</title>
<para>
For device objects representing USB devices the property
@@ -711,7 +964,7 @@
</sect2>
<sect2 id="device-properties-usbif">
<title>
- <literal>usb</literal> namespace
+ usb namespace
</title>
<para>
Device objects that represent USB interfaces, ie. when
@@ -789,7 +1042,7 @@
</sect2>
<sect2 id="device-properties-platform">
<title>
- <literal>platform</literal> namespace
+ platform namespace
</title>
<para>
Devices that are built into the platform or present on busses that
@@ -823,7 +1076,7 @@
</sect2>
<sect2 id="device-properties-ide-host">
<title>
- <literal>ide_host</literal> namespace
+ ide_host namespace
</title>
<para>
The <literal>ide_host</literal> namespace is present for
@@ -867,7 +1120,7 @@
</sect2>
<sect2 id="device-properties-ide">
<title>
- <literal>ide</literal> namespace
+ ide namespace
</title>
<para>
ATA and IDE drives are represented by device objects where
@@ -911,7 +1164,7 @@
</sect2>
<sect2 id="device-properties-scsi_host">
<title>
- <literal>scsi_host</literal> namespace
+ scsi_host namespace
</title>
<para>
The <literal>scsi_host</literal> namespace is present for
@@ -945,7 +1198,7 @@
</sect2>
<sect2 id="device-properties-scsi">
<title>
- <literal>scsi</literal> namespace
+ scsi namespace
</title>
<para>
SCSI devices are represented by device objects where
@@ -1073,7 +1326,7 @@
</sect2>
<sect2 id="device-properties-ieee1394_host">
<title>
- <literal>ieee1394_host</literal> namespace
+ ieee1394_host namespace
</title>
<para>
Device objects with <literal>info.subsystem</literal> set to
@@ -1138,7 +1391,7 @@
</sect2>
<sect2 id="device-properties-ieee1394_node">
<title>
- <literal>ieee1394_node</literal> namespace
+ ieee1394_node namespace
</title>
<para>
Device objects with <literal>info.subsystem</literal> set to
@@ -1203,7 +1456,7 @@
</sect2>
<sect2 id="device-properties-ieee1394">
<title>
- <literal>ieee1394</literal> namespace
+ ieee1394 namespace
</title>
<para>
Device objects with <literal>info.subsystem</literal> set to
@@ -1235,7 +1488,7 @@
</sect2>
<sect2 id="device-properties-mmc_host">
<title>
- <literal>mmc_host</literal> namespace
+ mmc_host namespace
</title>
<para>
Device objects with <literal>info.subsystem</literal> set to
@@ -1268,7 +1521,7 @@
</sect2>
<sect2 id="device-properties-mmc">
<title>
- <literal>mmc</literal> namespace
+ mmc namespace
</title>
<para>
Device objects with <literal>info.subsystem</literal> set to
@@ -1367,7 +1620,7 @@
</sect2>
<sect2 id="device-properties-ccw">
<title>
- <literal>ccw</literal> namespace
+ ccw namespace
</title>
<para>
Device objects that represent s390 ccw devices (when <literal>info.subsystem
@@ -1656,7 +1909,7 @@
</sect2>
<sect2 id="device-properties-ccwgroup">
<title>
- <literal>ccwgroup</literal> namespace
+ ccwgroup namespace
</title>
<para>
Device objects that represent groups of <literal>ccw</literal> devices
@@ -2021,7 +2274,7 @@
</sect2>
<sect2 id="device-properties-iucv">
<title>
- <literal>iucv</literal> namespace
+ iucv namespace
</title>
<para>
Device objects with <literal>info.subsystem</literal> set to <literal>iucv
@@ -2088,7 +2341,7 @@
</sect2>
<sect2 id="device-properties-block">
<title>
- <literal>block</literal> namespace
+ block namespace
</title>
<para>
Device objects representing addressable block devices, such as
@@ -2185,7 +2438,7 @@
</informaltable>
</sect2>
<sect2 id="device-properties-xen">
- <title><literal>xen</literal> namespace</title>
+ <title>xen namespace</title>
<para>
Device objects representing virtual devices under the Xen
Virtual Machine Monitor, such as frontend network or block
@@ -2239,18 +2492,15 @@
however, as HAL can merge properties from anywhere, they
may have been merged from device information files or callouts.
</para>
- <sect2 id="device-properties-volume">
+
+ <sect2 id="device-properties-kernel">
<title>
- <literal>volume</literal> namespace
+ system namespace
</title>
<para>
- This namespace is for device objects that represent storage
- devices with a filesystem that can be mounted. Such device
- objects will have the capability <literal>volume</literal> and
- they will export the properties below. Note that device
- objects can only have the <literal>volume</literal> capability
- if they already have the capability <literal>block</literal>
- and the property <literal>block.is_volume</literal> set to TRUE.
+ This namespace is found on the toplevel "Computer" device,
+ and represents information about the system and the currently
+ running kernel.
</para>
<informaltable>
<tgroup cols="2">
@@ -2265,148 +2515,322 @@
<tbody>
<row>
<entry>
- <literal>volume.ignore</literal> (bool)
- </entry>
- <entry></entry>
- <entry>Yes</entry>
- <entry>This is a hint to software higher in the stack
- that this volume should be ignored. If TRUE, the volume
- should be invisible in the UI and mount wrappers should
- refuse to mount it on behalf on an unprivileged
- user. This is useful for hiding e.g. firmware partitions
- (e.g. bootstrap on Mac's) and OS reinstall partitions on
- e.g. OEM systems.
+ <literal>system.kernel.name</literal> (string)
</entry>
- </row>
- <row>
+ <entry>example: Linux</entry>
+ <entry>No</entry>
<entry>
- <literal>volume.is_mounted</literal> (bool)
+ The name of the kernel, usually the equivalent of
+ <literal>uname -s</literal>.
</entry>
- <entry></entry>
- <entry>Yes</entry>
- <entry>This property is TRUE if and only if the volume is mounted</entry>
</row>
<row>
<entry>
- <literal>volume.is_mounted_read_only</literal> (bool)
+ <literal>system.kernel.version</literal> (string)
</entry>
- <entry></entry>
- <entry>Yes</entry>
- <entry>This property is TRUE if and only if the volume is mounted and
- the volume's file-system is read-only.
+ <entry>example: 2.6.5-7.104-default</entry>
+ <entry>No</entry>
+ <entry>
+ The version of the currently running kernel. Usually
+ the equivalent of <literal>uname -r</literal>.
</entry>
</row>
<row>
<entry>
- <literal>volume.mount_point</literal> (string)
+ <literal>system.kernel.machine</literal> (string)
+ </entry>
+ <entry>example: i686</entry>
+ <entry>No</entry>
+ <entry>
+ The "machine hardware name" of the currently running kernel.
+ Usually the equivalent of <literal>uname -m</literal>.
</entry>
- <entry>example: /media/compact_flash1 </entry>
- <entry>Yes (is blank only when volume.is_mounted is FALSE)</entry>
- <entry>A fully qualified path to the mount point of the volume</entry>
</row>
<row>
<entry>
- <literal>volume.fsusage</literal> (string)
+ <literal>system.formfactor</literal> (string)
</entry>
- <entry>example: filesystem</entry>
+ <entry>example: laptop, desktop, server, unknown</entry>
<entry>Yes</entry>
<entry>
- This property specifies the expected usage of the volume
+ The formfactor of the system. Usually the equivalent of
+ <literal>system.chassis.type</literal> or set from information
+ about ACPI/APM/PMU properties.
</entry>
</row>
<row>
- <entry></entry>
- <entry>filesystem</entry>
- <entry></entry>
- <entry>The volume is a mountable filesystem</entry>
- </row>
- <row>
- <entry></entry>
- <entry>partitiontable</entry>
- <entry></entry>
<entry>
- The volume contains a partitiontable.
- </entry>
- </row>
- <row>
- <entry></entry>
- <entry>raid</entry>
- <entry></entry>
- <entry>The volume is a member of a raid set and not mountable</entry>
- </row>
- <row>
- <entry></entry>
- <entry>other</entry>
- <entry></entry>
- <entry>The volume is not mountable like a swap partition</entry>
- </row>
- <row>
- <entry></entry>
- <entry>unused</entry>
+ <literal>system.hardware.vendor</literal> (string)
+ </entry>
<entry></entry>
- <entry>The volume is marked a unused or free</entry>
- </row>
- <row>
+ <entry>No</entry>
<entry>
- <literal>volume.fstype</literal> (string)
+ The name of the manufacturer of the machine.
</entry>
- <entry>examples: ext3, vfat</entry>
- <entry>Yes (is blank if the type is unknown)</entry>
- <entry>The specific type of either the file system or what the volume is used for, cf. volume.fsusage</entry>
</row>
<row>
<entry>
- <literal>volume.fsversion</literal> (string)
+ <literal>system.product</literal> (string)
</entry>
- <entry>example: FAT32</entry>
<entry></entry>
- <entry>Version number or subtype of the filesystem</entry>
- </row>
- <row>
- <entry>
- <literal>volume.label</literal> (string)
- </entry>
- <entry>example: 'Fedora Core 1.90' </entry>
- <entry>Yes (is blank if no label is found)</entry>
- <entry>The label of the volume</entry>
- </row>
- <row>
+ <entry>No</entry>
<entry>
- <literal>volume.uuid</literal> (string)
+ The product name of the machine.
</entry>
- <entry>example: 4060-6C11</entry>
- <entry>Yes (is blank if no UUID is found)</entry>
- <entry>The Universal Unique Identifer for the volume</entry>
</row>
<row>
<entry>
- <literal>volume.is_disc</literal> (bool)
+ <literal>system.hardware.version</literal> (string)
</entry>
<entry></entry>
- <entry>Yes</entry>
- <entry>If the volume stems from an optical disc, this
- property is true and the device object will also have
- the capability <literal>volume.disc</literal>
+ <entry>No</entry>
+ <entry>
+ The version of the machine.
</entry>
</row>
<row>
<entry>
- <literal>volume.block_size</literal> (string)
+ <literal>system.hardware.serial</literal> (string)
</entry>
<entry></entry>
<entry>No</entry>
<entry>
- The block size of the volume
+ The serial number of the machine.
</entry>
</row>
<row>
<entry>
- <literal>volume.num_blocks</literal> (string)
+ <literal>system.hardware.uuid</literal> (string)
</entry>
<entry></entry>
<entry>No</entry>
<entry>
- Number of blocks on the volume
+ The unique ID of the machine.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>system.firmware.vendor</literal> (string)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ The firmware vendor.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>system.firmware.version</literal> (string)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ The firmware version.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>system.firmware.release_date</literal> (string)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ The release date of the firmware.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>system.chassis.manufacturer</literal> (string)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ The manufacturer of the chassis.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>system.chassis.type</literal> (string)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ The chassis type of the machine.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 id="device-properties-volume">
+ <title>
+ volume namespace
+ </title>
+ <para>
+ This namespace is for device objects that represent storage
+ devices with a filesystem that can be mounted. Such device
+ objects will have the capability <literal>volume</literal> and
+ they will export the properties below. Note that device
+ objects can only have the <literal>volume</literal> capability
+ if they already have the capability <literal>block</literal>
+ and the property <literal>block.is_volume</literal> set to TRUE.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Key (type)</entry>
+ <entry>Values</entry>
+ <entry>Mandatory</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>volume.ignore</literal> (bool)
+ </entry>
+ <entry></entry>
+ <entry>Yes</entry>
+ <entry>This is a hint to software higher in the stack
+ that this volume should be ignored. If TRUE, the volume
+ should be invisible in the UI and mount wrappers should
+ refuse to mount it on behalf on an unprivileged
+ user. This is useful for hiding e.g. firmware partitions
+ (e.g. bootstrap on Mac's) and OS reinstall partitions on
+ e.g. OEM systems.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.is_mounted</literal> (bool)
+ </entry>
+ <entry></entry>
+ <entry>Yes</entry>
+ <entry>This property is TRUE if and only if the volume is mounted</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.is_mounted_read_only</literal> (bool)
+ </entry>
+ <entry></entry>
+ <entry>Yes</entry>
+ <entry>This property is TRUE if and only if the volume is mounted and
+ the volume's file-system is read-only.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.mount_point</literal> (string)
+ </entry>
+ <entry>example: /media/compact_flash1 </entry>
+ <entry>Yes (is blank only when volume.is_mounted is FALSE)</entry>
+ <entry>A fully qualified path to the mount point of the volume</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.fsusage</literal> (string)
+ </entry>
+ <entry>example: filesystem</entry>
+ <entry>Yes</entry>
+ <entry>
+ This property specifies the expected usage of the volume
+ </entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>filesystem</entry>
+ <entry></entry>
+ <entry>The volume is a mountable filesystem</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>partitiontable</entry>
+ <entry></entry>
+ <entry>
+ The volume contains a partitiontable.
+ </entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>raid</entry>
+ <entry></entry>
+ <entry>The volume is a member of a raid set and not mountable</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>other</entry>
+ <entry></entry>
+ <entry>The volume is not mountable like a swap partition</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>unused</entry>
+ <entry></entry>
+ <entry>The volume is marked a unused or free</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.fstype</literal> (string)
+ </entry>
+ <entry>examples: ext3, vfat</entry>
+ <entry>Yes (is blank if the type is unknown)</entry>
+ <entry>The specific type of either the file system or what the volume is used for, cf. volume.fsusage</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.fsversion</literal> (string)
+ </entry>
+ <entry>example: FAT32</entry>
+ <entry></entry>
+ <entry>Version number or subtype of the filesystem</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.label</literal> (string)
+ </entry>
+ <entry>example: 'Fedora Core 1.90' </entry>
+ <entry>Yes (is blank if no label is found)</entry>
+ <entry>The label of the volume</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.uuid</literal> (string)
+ </entry>
+ <entry>example: 4060-6C11</entry>
+ <entry>Yes (is blank if no UUID is found)</entry>
+ <entry>The Universal Unique Identifer for the volume</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.is_disc</literal> (bool)
+ </entry>
+ <entry></entry>
+ <entry>Yes</entry>
+ <entry>If the volume stems from an optical disc, this
+ property is true and the device object will also have
+ the capability <literal>volume.disc</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.block_size</literal> (string)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ The block size of the volume
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>volume.num_blocks</literal> (string)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ Number of blocks on the volume
</entry>
</row>
<row>
@@ -2728,14 +3152,15 @@
</tgroup>
</informaltable>
</sect2>
- <sect2 id="device-properties-kernel">
+ <sect2 id="device-properties-volume-disc">
<title>
- <literal>system</literal> namespace
+ volume.disc namespace
</title>
<para>
- This namespace is found on the toplevel "Computer" device,
- and represents information about the system and the currently
- running kernel.
+ This namespace is for device objects that represent optical
+ discs, e.g. device objects with the capability
+ <literal>volume.disc</literal>. Such device objects will
+ also have the capability <literal>volume</literal>.
</para>
<informaltable>
<tgroup cols="2">
@@ -2750,189 +3175,19 @@
<tbody>
<row>
<entry>
- <literal>system.kernel.name</literal> (string)
- </entry>
- <entry>example: Linux</entry>
- <entry>No</entry>
- <entry>
- The name of the kernel, usually the equivalent of
- <literal>uname -s</literal>.
+ <literal>volume.disc.has_audio</literal> (bool)
</entry>
+ <entry></entry>
+ <entry>Yes</entry>
+ <entry>Is true only if the disc contains audio</entry>
</row>
<row>
<entry>
- <literal>system.kernel.version</literal> (string)
- </entry>
- <entry>example: 2.6.5-7.104-default</entry>
- <entry>No</entry>
- <entry>
- The version of the currently running kernel. Usually
- the equivalent of <literal>uname -r</literal>.
+ <literal>volume.disc.has_data</literal> (bool)
</entry>
- </row>
- <row>
- <entry>
- <literal>system.kernel.machine</literal> (string)
- </entry>
- <entry>example: i686</entry>
- <entry>No</entry>
- <entry>
- The "machine hardware name" of the currently running kernel.
- Usually the equivalent of <literal>uname -m</literal>.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.formfactor</literal> (string)
- </entry>
- <entry>example: laptop, desktop, server, unknown</entry>
- <entry>Yes</entry>
- <entry>
- The formfactor of the system. Usually the equivalent of
- <literal>system.chassis.type</literal> or set from information
- about ACPI/APM/PMU properties.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.hardware.vendor</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The name of the manufacturer of the machine.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.product</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The product name of the machine.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.hardware.version</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The version of the machine.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.hardware.serial</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The serial number of the machine.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.hardware.uuid</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The unique ID of the machine.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.firmware.vendor</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The firmware vendor.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.firmware.version</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The firmware version.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.firmware.release_date</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The release date of the firmware.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.chassis.manufacturer</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The manufacturer of the chassis.
- </entry>
- </row>
- <row>
- <entry>
- <literal>system.chassis.type</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The chassis type of the machine.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- <sect2 id="device-properties-volume-disc">
- <title>
- <literal>volume.disc</literal> namespace
- </title>
- <para>
- This namespace is for device objects that represent optical
- discs, e.g. device objects with the capability
- <literal>volume.disc</literal>. Such device objects will
- also have the capability <literal>volume</literal>.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Key (type)</entry>
- <entry>Values</entry>
- <entry>Mandatory</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>volume.disc.has_audio</literal> (bool)
- </entry>
- <entry></entry>
- <entry>Yes</entry>
- <entry>Is true only if the disc contains audio</entry>
- </row>
- <row>
- <entry>
- <literal>volume.disc.has_data</literal> (bool)
- </entry>
- <entry></entry>
- <entry>Yes</entry>
- <entry>Is true only if the disc contains data</entry>
+ <entry></entry>
+ <entry>Yes</entry>
+ <entry>Is true only if the disc contains data</entry>
</row>
<row>
<entry>
@@ -3100,7 +3355,7 @@
</sect2>
<sect2 id="device-properties-storage">
<title>
- <literal>storage</literal> namespace
+ storage namespace
</title>
<para>
This namespace is used to describe storage devices
@@ -3369,16 +3624,7 @@
<entry>
This contains the UDI of the device object
representing the device or blank if
- there is no such device (which is TRUE for legacy
- devices such as x86 floppy drives). Additionally, a
- number of properties are merged from that device
- object. Specifically, all properties prefixed
- with <literal>storage</literal> and, if the
- device has several storage ports,
- <literal>storage_lunX</literal> (where X is number of
- the port starting from zero) are merged and will have
- the prefix <literal>storage</literal>.
- See <xref linkend="fdi-example-6in1"/> for an example.
+ there is no such device.
</entry>
</row>
<row>
@@ -3449,7 +3695,7 @@
</sect2>
<sect2 id="device-properties-storage-cdrom">
<title>
- <literal>storage.cdrom</literal> namespace
+ storage.cdrom namespace
</title>
<para>
This namespace is used to describe optical storage drives
@@ -3636,7 +3882,7 @@
</sect2>
<sect2 id="device-properties-net">
<title>
- <literal>net</literal> namespace
+ net namespace
</title>
<para>
This namespace is used to describe networking devices and
@@ -3721,7 +3967,7 @@
</sect2>
<sect2 id="device-properties-net-80203">
<title>
- <literal>net.80203</literal> namespace
+ net.80203 namespace
</title>
<para>
Ethernet networking devices is described in this namespace
@@ -3788,7 +4034,7 @@
</sect2>
<sect2 id="device-properties-net-80211">
<title>
- <literal>net.80211</literal> namespace
+ net.80211 namespace
</title>
<para>
Wireless ethernet networking devices is described in this namespace
@@ -3827,7 +4073,7 @@
</sect2>
<sect2 id="device-properties-net-irda">
<title>
- <literal>net.irda</literal> namespace
+ net.irda namespace
</title>
<para>
IrDA (Infrared Data Association) Networking devices are described in
@@ -3841,7 +4087,7 @@
</sect2>
<sect2 id="device-properties-net-80211control">
<title>
- <literal>net.80211control</literal> namespace
+ net.80211control namespace
</title>
<para>
Control devices for Wireless ethernet networking devices are described in
@@ -3857,7 +4103,7 @@
</sect2>
<sect2 id="device-properties-input">
<title>
- <literal>input</literal> namespace
+ input namespace
</title>
<para>
This namespace is concerned with human input devices such as
@@ -3890,7 +4136,7 @@
</sect2>
<sect2 id="device-properties-pcmcia_socket">
<title>
- <literal>pcmcia_socket namespace</literal>
+ pcmcia_socket namespace
</title>
<para>
Device objects with the capability <literal>pcmcia_socket</literal>
@@ -3923,7 +4169,7 @@
</sect2>
<sect2 id="device-properties-printer">
<title>
- <literal>printer</literal> namespace
+ printer namespace
</title>
<para>
Device objects with the capability <literal>printer</literal>
@@ -3994,7 +4240,7 @@
</sect2>
<sect2 id="device-properties-portable_audio_player">
<title>
- <literal>portable_audio_player</literal> namespace
+ portable_audio_player namespace
</title>
<para>
Device objects with the capability
@@ -4143,7 +4389,7 @@
</sect2>
<sect2 id="device-properties-alsa">
<title>
- <literal>alsa</literal> namespace
+ alsa namespace
</title>
<para>
Device objects with the capability <literal>alsa</literal>
@@ -4394,7 +4640,7 @@
</sect2>
<sect2 id="device-properties-oss">
<title>
- <literal>oss</literal> namespace
+ oss namespace
</title>
<para>
Device objects with the capability <literal>oss</literal>
@@ -4543,7 +4789,7 @@
</sect2>
<sect2 id="device-properties-camera">
<title>
- <literal>camera</literal> namespace
+ camera namespace
</title>
<para>
Device objects with the capability <literal>camera</literal>
@@ -4623,7 +4869,7 @@
</sect2>
<sect2 id="device-properties-scanner">
<title>
- <literal>scanner</literal> namespace
+ scanner namespace
</title>
<para>
Device objects with the capability <literal>scanner</literal>
@@ -4674,7 +4920,7 @@
</sect2>
<sect2 id="device-properties-laptop-panel">
<title>
- <literal>laptop_panel</literal> namespace
+ laptop_panel namespace
</title>
<para>
Device objects with the capability <literal>laptop_panel</literal>
@@ -4782,7 +5028,7 @@
</sect2>
<sect2 id="device-properties-ac_adaptor">
<title>
- <literal>ac_adaptor</literal> namespace
+ ac_adaptor namespace
</title>
<para>
Device objects with the capability <literal>ac_adaptor</literal>
@@ -4816,7 +5062,7 @@
</sect2>
<sect2 id="device-properties-battery">
<title>
- <literal>battery</literal> namespace
+ battery namespace
</title>
<para>
Device objects with the capability <literal>battery</literal>
@@ -5402,7 +5648,7 @@
</sect2>
<sect2 id="device-properties-button">
<title>
- <literal>button</literal> namespace
+ button namespace
</title>
<para>
Device objects with the capability <literal>button</literal>
@@ -5503,7 +5749,7 @@
</sect2>
<sect2 id="device-properties-processor">
<title>
- <literal>processor</literal> namespace
+ processor namespace
</title>
<para>
Device objects with the capability <literal>processor</literal>
@@ -5553,13 +5799,13 @@
</tgroup>
</informaltable>
</sect2>
- <sect2 id="device-properties-display_device">
+ <sect2 id="device-properties-light-sensor">
<title>
- <literal>display_device</literal> namespace
+ light_sensor namespace
</title>
<para>
- Device objects with the capability <literal>display_device</literal>
- represent display devices attached to the system.
+ Device objects with the capability <literal>sensor</literal>
+ represent light sensors in the system.
</para>
<informaltable>
<tgroup cols="2">
@@ -5574,114 +5820,27 @@
<tbody>
<row>
<entry>
- <literal>display_device.type</literal> (string)
+ <literal>light_sensor.sensor_locations</literal> (strlist)
</entry>
<entry></entry>
<entry>Yes</entry>
- <entry>The type of display device</entry>
- </row>
- <row>
- <entry></entry>
- <entry>lcd</entry>
- <entry></entry>
- <entry>LCD panel</entry>
- </row>
- <row>
- <entry></entry>
- <entry>crt</entry>
- <entry></entry>
- <entry>CRT tube</entry>
- </row>
- <row>
- <entry></entry>
- <entry>tv_out</entry>
- <entry></entry>
- <entry>TV Out</entry>
- </row>
- <row>
- <entry>
- <literal>display_device.lcd.brightness</literal> (int)
- </entry>
- <entry></entry>
- <entry>
- Only if <literal>display_device.type</literal> is lcd
- </entry>
- <entry>Brightness level in percent</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- <sect2 id="device-properties-sensor">
- <title>
- <literal>sensor</literal> namespace
- </title>
- <para>
- Device objects with the capability <literal>sensor</literal>
- represent light or temperature sensors in the system.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Key (type)</entry>
- <entry>Values</entry>
- <entry>Mandatory</entry>
- <entry>Description</entry>
+ <entry>The locations of the sensors</entry>
</row>
- </thead>
- <tbody>
<row>
<entry>
- <literal>sensor.type</literal> (string)
+ <literal>light_sensor.num_sensors</literal> (int)
</entry>
<entry></entry>
<entry>Yes</entry>
- <entry>The type of sensor device</entry>
- </row>
- <row>
- <entry></entry>
- <entry>light</entry>
- <entry></entry>
- <entry>Light sensor</entry>
- </row>
- <row>
- <entry></entry>
- <entry>temperature</entry>
- <entry></entry>
- <entry>Temperature sensor</entry>
+ <entry>Number of physical sensors</entry>
</row>
<row>
<entry>
- <literal>sensor.location</literal> (string)
+ <literal>light_sensor.num_levels</literal> (int)
</entry>
<entry></entry>
<entry>Yes</entry>
- <entry>The location of the sensor device</entry>
- </row>
- <row>
- <entry></entry>
- <entry>gpu</entry>
- <entry></entry>
- <entry>Measures GPU source</entry>
- </row>
- <row>
- <entry></entry>
- <entry>cpu</entry>
- <entry></entry>
- <entry>Measures CPU source</entry>
- </row>
- <row>
- <entry></entry>
- <entry>external</entry>
- <entry></entry>
- <entry>Measures external source</entry>
- </row>
- <row>
- <entry></entry>
- <entry>unknown</entry>
- <entry></entry>
- <entry>Measuring other source</entry>
+ <entry>The number of levels of the sensors</entry>
</row>
</tbody>
</tgroup>
@@ -5689,12 +5848,12 @@
</sect2>
<sect2 id="device-properties-power-management">
<title>
- <literal>power_management</literal> namespace
+ power_management namespace
</title>
<para>
Keys with the prefix <literal>power_management</literal>
provide information about power management supported by
- your computer.
+ the system.
</para>
<informaltable>
<tgroup cols="2">
@@ -5735,6 +5894,16 @@
</row>
<row>
<entry>
+ <literal>power_management.can_suspend_hybrid</literal> (bool)
+ </entry>
+ <entry></entry>
+ <entry>Yes</entry>
+ <entry>
+ If the system is capable of hybrid suspend.
+ </entry>
+ </row>
+ <row>
+ <entry>
<literal>power_management.can_hibernate</literal> (bool)
</entry>
<entry></entry>
@@ -5830,16 +5999,21 @@
</tbody>
</tgroup>
</informaltable>
+ </sect2>
+ <sect2 id="device-properties-tape">
+ <title>
+ tape namespace
+ </title>
<para>
- The following methods exist on the interface
- <literal>org.freedesktop.Hal.Device.SystemPowerManagement</literal>.
+ Device objects with the capability <literal>tape</literal>
+ represent tape devices.
</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
- <entry>Method (parameter types)</entry>
- <entry>Parameters</entry>
+ <entry>Key (type)</entry>
+ <entry>Values</entry>
<entry>Mandatory</entry>
<entry>Description</entry>
</row>
@@ -5847,256 +6021,15 @@
<tbody>
<row>
<entry>
- <literal>Suspend</literal> (integer)
- </entry>
- <entry>
- The number of seconds until we resume automatically, or zero if
- we should not auto-resume.
- </entry>
- <entry>No</entry>
- <entry>
- This method puts the system in a state where little power is consumed.
- The system is not operational while in this state.
- Latency for the system to return to an operational state is in
- the order of magnitude of 5 seconds.
+ <literal>tape.major</literal> (int)
</entry>
+ <entry>example: 254</entry>
+ <entry>Yes</entry>
+ <entry>The device's major number</entry>
</row>
<row>
<entry>
- <literal>Hibernate</literal> (void)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- This method puts the system in a state where no power is consumed.
- The system is not operational while in this state.
- Latency for the system to return to an operational state is in
- the order of magnitude of one minute.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>
- The following methods exist on the interface
- <literal>org.freedesktop.Hal.Device.CPUFreq</literal>.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Method (parameter types)</entry>
- <entry>Parameters</entry>
- <entry>Mandatory</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>SetCPUFreqGovernor</literal> (string)
- </entry>
- <entry>
- The name of the governor to set. Get a list of available governors
- with the GetCPUFreqAvailableGovernors method.
- </entry>
- <entry>No</entry>
- <entry>
- Sets 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. The default performance is set to 50.
- </entry>
- </row>
- <row>
- <entry>
- <literal>SetCPUFreqPerformance</literal> (integer)
- </entry>
- <entry>
- The performance between 1 and 100 to set in dynamic scaling modes.
- </entry>
- <entry>No</entry>
- <entry>
- 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.
- </entry>
- </row>
- <row>
- <entry>
- <literal>SetCPUFreqConsiderNice</literal> (boolean)
- </entry>
- <entry>
- Whether or not niced processes should be considered on CPU
- load calculation.
- </entry>
- <entry>No</entry>
- <entry>
- 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'.
- </entry>
- </row>
- <row>
- <entry>
- <literal>GetCPUFreqGovernor</literal> (void)
- </entry>
- <entry>
- </entry>
- <entry>No</entry>
- <entry>
- Get the current active governor for all CPU frequency interfaces (string).
- </entry>
- </row>
- <row>
- <entry>
- <literal>GetCPUFreqPerformance</literal> (void)
- </entry>
- <entry>
- </entry>
- <entry>No</entry>
- <entry>
- Get the current active performance setting if a dynamic scaling
- mechanism is in use (integer between 1 and 100).
- </entry>
- </row>
- <row>
- <entry>
- <literal>GetCPUFreqConsiderNice</literal> (void)
- </entry>
- <entry>
- </entry>
- <entry>No</entry>
- <entry>
- Returns whether niced processed are considered during CPU load
- calculation or not (returns boolean).
- </entry>
- </row>
- <row>
- <entry>
- <literal>GetCPUFreqAvailableGovernors</literal> (void)
- </entry>
- <entry>
- </entry>
- <entry>No</entry>
- <entry>
- Returns a list of strings of all available governors which
- could be set with the SetCPUFreqGovernor method.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>
- The following errors maybe raised on the interface
- <literal>org.freedesktop.Hal.Device.CPUFreq</literal>.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Error</entry>
- <entry>Description</entry>
- <entry>Detail field</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>GeneralError</literal>
- </entry>
- <entry>
- A general error occured.
- </entry>
- <entry>
- The exact error.
- </entry>
- </row>
- <row>
- <entry>
- <literal>UnknownGovernor</literal>
- </entry>
- <entry>
- The governor which was tried to be set doesn't exist.
- </entry>
- <entry>
- The governor which was tried be to set.
- </entry>
- </row>
- <row>
- <entry>
- <literal>PermissionDenied</literal>
- </entry>
- <entry>
- The caller doesn't have the privilege to execute this
- method.
- </entry>
- <entry>
- The privilege the caller needs to execute the method.
- </entry>
- </row>
- <row>
- <entry>
- <literal>NoSuitableGovernor</literal>
- </entry>
- <entry>
- The method executed doesn't exist for the current active governor.
- </entry>
- <entry>
- The method which was tried to be executed.
- </entry>
- </row>
- <row>
- <entry>
- <literal>GovernorInitFailed</literal>
- </entry>
- <entry>
- The initialization of the governor failed.
- </entry>
- <entry>
- The reason for the failure.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- <sect2 id="device-properties-tape">
- <title>
- <literal>tape</literal> namespace
- </title>
- <para>
- Device objects with the capability <literal>tape</literal>
- represent tape devices.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Key (type)</entry>
- <entry>Values</entry>
- <entry>Mandatory</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>tape.major</literal> (int)
- </entry>
- <entry>example: 254</entry>
- <entry>Yes</entry>
- <entry>The device's major number</entry>
- </row>
- <row>
- <entry>
- <literal>tape.minor</literal> (int)
+ <literal>tape.minor</literal> (int)
</entry>
<entry>example: 0</entry>
<entry>Yes</entry>
@@ -6108,255 +6041,6 @@
</sect2>
</sect1>
- <sect1 id="properties-policy">
- <title>Policy Properties</title>
- <para>
- The properties on a hal device object can be used to express
- certain policies about how the device is to be used. This
- information can be used by either programs querying hal
- directly or by hal callouts. Default policy (e.g. always
- mount a file system with the option 'exec') can also be
- merged on the root computer device object.
- </para>
- <sect2 id="device-properties-storage-policy-default">
- <title>
- <literal>storage.policy.default</literal> namespace
- </title>
- <para>
- This namespace specifies the default policy for storage
- devices - these properties should be merged on the root computer
- device object.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Key (type)</entry>
- <entry>Values</entry>
- <entry>Mandatory</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>storage.policy.default.use_managed_keyword</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- Whether to use a <emphasis>managed no
- operation
- </emphasis>
- keyword when adding entries to
- the File Systems file (<literal>/etc/fstab</literal>) -
- this is used to identify entries added by a program
- that modifies this file.
- </entry>
- </row>
- <row>
- <entry>
- <literal>storage.policy.default.managed_keyword.primary</literal> (string)
- </entry>
- <entry>Example: 'managed'</entry>
- <entry>No</entry>
- <entry>No-op keyword to use when adding entries to the file systems file</entry>
- </row>
- <row>
- <entry>
- <literal>storage.policy.default.managed_keyword.secondary</literal> (string)
- </entry>
- <entry>Example: 'kudzu'</entry>
- <entry>No</entry>
- <entry>
- Secondary no-op keyword that identifies entries added
- to the file systems file. The secondary keyword is never
- written; only read. This is useful when making a transition
- from one managed keyword to another.
- </entry>
- </row>
- <row>
- <entry>
- <literal>storage.policy.default.mount_option.*</literal> (bool)
- </entry>
- <entry>Examples:
- <literal>.noauto</literal>,
- <literal>.exec</literal>,
- <literal>.console</literal>,
- <literal>.fscontext=system_u:object_r:removable_t</literal>
- </entry>
- <entry>No</entry>
- <entry>
- This is actually an entire namespace that specifies
- what options a storage device should be mounted with,
- e.g. the example <literal>.exec</literal> should be read as
- <literal>storage.policy.default.mount_option.exec</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>storage.policy.default.mount_root</literal> (string)
- </entry>
- <entry>
- Example: <literal>/media</literal>
- </entry>
- <entry>No</entry>
- <entry>
- The default mount root to use when computing what
- mount point to use for a storage device
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- <sect2 id="device-properties-storage-policy">
- <title>
- <literal>storage.policy</literal> namespace
- </title>
- <para>
- This namespace contains properties that can be merged on
- individual storage devices to specify how and if the storage
- device should be mounted.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Key (type)</entry>
- <entry>Values</entry>
- <entry>Mandatory</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>storage.policy.should_mount</literal> (bool)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>Whether any volumes from this storage device
- should be mounted
- </entry>
- </row>
- <row>
- <entry>
- <literal>storage.policy.desired_mount_point</literal> (string)
- </entry>
- <entry></entry>
- <entry>
- No (only applicable if the
- property <literal>storage.no_partitions_hint</literal>
- is set to TRUE)
- </entry>
- <entry>
- The desired mount point for this storage device. The
- path must not be fully qualified and there is no
- guarantee that and storage policy agents, such as
- policy mount wrappers or programs modifying the file
- systems file will use this mount point.
- </entry>
- </row>
- <row>
- <entry>
- <literal>storage.policy.mount_option.*</literal> (bool)
- </entry>
- <entry></entry>
- <entry>
- No (only applicable if the
- property <literal>storage.no_partitions_hint</literal>
- is set to TRUE)
- </entry>
- <entry>
- Mount options to use, see property
- <literal>storage.policy.default.mount_option.*</literal>
- for details.
- </entry>
- </row>
- <row>
- <entry>
- <literal>storage.policy.mount_filesystem</literal> (string)
- </entry>
- <entry></entry>
- <entry>
- No (only applicable if the
- property <literal>storage.no_partitions_hint</literal>
- is set to TRUE)
- </entry>
- <entry>File system to use when mounting the storage device.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- <sect2 id="device-properties-volume-policy">
- <title>
- <literal>volume.policy</literal> namespace
- </title>
- <para>
- This namespace contains properties that can be merged on
- individual volumes to specify how and if the volume
- should be mounted.
- </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Key (type)</entry>
- <entry>Values</entry>
- <entry>Mandatory</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>volume.policy.should_mount</literal> (bool)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>Whether this volume should be mounted at all</entry>
- </row>
- <row>
- <entry>
- <literal>volume.policy.mount_filesystem</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>File system to use when mounting the volume.</entry>
- </row>
- <row>
- <entry>
- <literal>volume.policy.desired_mount_point</literal> (string)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- The desired mount point for this volume. The
- path must not be fully qualified and there is no
- guarantee that and storage policy agents, such as
- policy mount wrappers or programs modifying the file
- systems file will use this mount point.
- </entry>
- </row>
- <row>
- <entry>
- <literal>volume.policy.mount_option.*</literal> (bool)
- </entry>
- <entry></entry>
- <entry>No</entry>
- <entry>
- Mount options to use, see property
- <literal>storage.policy.default.mount_option.*</literal>
- for details.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
- </sect1>
<sect1 id="properties-deprecated">
<title>Deprecated Properties</title>
<para>
diff --git a/doc/spec/hal-spec.xml.in b/doc/spec/hal-spec.xml.in
index 822cc95..dc94ad0 100644
--- a/doc/spec/hal-spec.xml.in
+++ b/doc/spec/hal-spec.xml.in
@@ -5,7 +5,7 @@
<bookinfo>
<title>HAL @VERSION@ Specification</title>
<releaseinfo>Version @VERSION@</releaseinfo>
- <date>May 9th, 2006</date> <!-- Update this manually -->
+ <date>March 24th, 2007</date> <!-- Update this manually -->
<authorgroup>
<author>
<firstname>David</firstname>
@@ -22,6 +22,6 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-introduction.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-properties.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-fdi-files.xml" />
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-examples.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-interfaces.xml" />
</book>
More information about the hal-commit
mailing list