--- /dev/null
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>HAL 0.5.10 Specification</title><link rel="stylesheet" href="docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="index"></a>HAL 0.5.10 Specification</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">Zeuthen</span></h3><div class="affiliation"><div class="address"><p><br>
+ <code class="email"><<a href="mailto:david@fubar.dk">david@fubar.dk</a>></code><br>
+ </p></div></div></div></div></div><div><p class="releaseinfo">Version 0.5.10</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#introduction">1. Introduction</a></span></dt><dd><dl><dt><span class="sect1"><a href="#introduction-about">About</a></span></dt><dt><span class="sect1"><a href="#introduction-acknowledgements">Acknowledgements</a></span></dt><dt><span class="sect1"><a href="#ov_halarch">Architecture of HAL</a></span></dt><dt><span class="sect1"><a href="#introduction-device-objects">Device Objects</a></span></dt><dt><span class="sect1"><a href="#device-capabilities">Device Capabilities</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spec-device-info">2. Device Information Files</a></span></dt><dd><dl><dt><span class="sect1"><a href="#fdi-matching">Matching</a></span></dt><dt><span class="sect1"><a href="#fdi-merging">Merging</a></span></dt><dt><span class="sect1"><a href="#fdi-search-paths">Search Paths</a></span></dt></dl></dd><dt><span class="chapter"><a href="#access-control">3. Access Control</a></span></dt><dd><dl><dt><span class="sect1"><a href="#access-control-device-file">Device Files</a></span></dt><dt><span class="sect1"><a href="#access-control-ipc">D-Bus Interfaces</a></span></dt></dl></dd><dt><span class="chapter"><a href="#locking">4. Locking</a></span></dt><dd><dl><dt><span class="sect1"><a href="#locking-overview">Overview</a></span></dt><dt><span class="sect1"><a href="#locking-guidelines">Guidelines</a></span></dt></dl></dd><dt><span class="chapter"><a href="#device-properties">5. Device Properties</a></span></dt><dd><dl><dt><span class="sect1"><a href="#properties-general">General Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-info">
+ info namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-info-callouts">Callouts</a></span></dt><dt><span class="sect2"><a href="#device-properties-info-addons">Addons</a></span></dt><dt><span class="sect2"><a href="#device-properties-info-singleton-addons">Singleton Addons</a></span></dt><dt><span class="sect2"><a href="#device-properties-info-method-calls">Method calls</a></span></dt></dl></dd><dt><span class="sect1"><a href="#properties-subsystem">Subsystem-Specific Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-pci">
+ pci namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-serialif">
+ serial namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-usb">
+ usb_device namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-usbif">
+ usb namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-platform">
+ platform namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ide-host">
+ ide_host namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ide">
+ ide namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-scsi_host">
+ scsi_host namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-scsi">
+ scsi namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ieee1394_host">
+ ieee1394_host namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ieee1394_node">
+ ieee1394_node namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ieee1394">
+ ieee1394 namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-mmc_host">
+ mmc_host namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-mmc">
+ mmc namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ccw">
+ ccw namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ccwgroup">
+ ccwgroup namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-iucv">
+ iucv namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-block">
+ block namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-xen">xen namespace</a></span></dt><dt><span class="sect2"><a href="#device-properties-bluetooth_hci">bluetooth_hci namespace</a></span></dt><dt><span class="sect2"><a href="#device-properties-bluetooth_acl">bluetooth_acl namespace</a></span></dt><dt><span class="sect2"><a href="#device-properties-bluetooth_sco">bluetooth_sco namespace</a></span></dt><dt><span class="sect2"><a href="#device-properties-drm">drm namespace</a></span></dt></dl></dd><dt><span class="sect1"><a href="#properties-functional">Functional Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-kernel">
+ system namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-volume">
+ volume namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-volume-disc">
+ volume.disc namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-storage">
+ storage namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-storage-cdrom">
+ storage.cdrom namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-storage-linux-raid">
+ storage.linux_raid namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net">
+ net namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-80203">
+ net.80203 namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-80211">
+ net.80211 namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-bluetooth">
+ net.bluetooth namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-irda">
+ net.irda namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-80211control">
+ net.80211control namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input">
+ input namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-keys">
+ input.keys namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-keypad">
+ input.keypad namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-keyboard">
+ input.keyboard namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-mouse">
+ input.mouse namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-switch">
+ input.switch namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-joystick">
+ input.joystick namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-tablet">
+ input.tablet namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-keymap">
+ input.keymap namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-xkb">
+ input.xkb namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-pcmcia_socket">
+ pcmcia_socket namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-printer">
+ printer namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-portable_audio_player">
+ portable_audio_player namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-alsa">
+ alsa namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-oss">
+ oss namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-camera">
+ camera namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-scanner">
+ scanner namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-laptop-panel">
+ laptop_panel namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ac_adapter">
+ ac_adapter namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-battery">
+ battery namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-button">
+ button namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-processor">
+ processor namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-light-sensor">
+ light_sensor namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-power-management">
+ power_management namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-tape">
+ tape namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-killswitch">
+ killswitch namespace
+ </a></span></dt></dl></dd><dt><span class="sect1"><a href="#properties-misc">Misc. Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-access-control">
+ access_control namespace
+ </a></span></dt></dl></dd><dt><span class="sect1"><a href="#properties-deprecated">Deprecated Properties</a></span></dt></dl></dd><dt><span class="chapter"><a href="#interfaces">6. D-Bus interfaces</a></span></dt><dd><dl><dt><span class="sect1"><a href="#interface-manager">org.freedesktop.Hal.Manager interface</a></span></dt><dt><span class="sect1"><a href="#interface-device">org.freedesktop.Hal.Device interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-systempower">org.freedesktop.Hal.Device.SystemPowerManagement interface</a></span></dt><dt><span class="sect1"><a href="#interface-cpufreq">org.freedesktop.Hal.Device.CPUFreq interface</a></span></dt><dt><span class="sect1"><a href="#interface-wakeonlan">org.freedesktop.Hal.Device.WakeOnLan interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-laptop-panel">org.freedesktop.Hal.Device.LaptopPanel interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-keyboard-backlight">org.freedesktop.Hal.Device.KeyboardBacklight interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-light-sensor">org.freedesktop.Hal.Device.LightSensor interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-storage">org.freedesktop.Hal.Device.Storage interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-volume">org.freedesktop.Hal.Device.Volume interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-volume-crypto">org.freedesktop.Hal.Device.Volume.Crypto interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-killswitch">org.freedesktop.Hal.Device.KillSwitch interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-accesscontrol">org.freedesktop.Hal.Device.AccessControl interface</a></span></dt><dt><span class="sect1"><a href="#interface-singleton-addon"><code class="literal">org.freedesktop.Hal.SingletonAddon</code> interface</a></span></dt></dl></dd></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="introduction"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#introduction-about">About</a></span></dt><dt><span class="sect1"><a href="#introduction-acknowledgements">Acknowledgements</a></span></dt><dt><span class="sect1"><a href="#ov_halarch">Architecture of HAL</a></span></dt><dt><span class="sect1"><a href="#introduction-device-objects">Device Objects</a></span></dt><dt><span class="sect1"><a href="#device-capabilities">Device Capabilities</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction-about"></a>About</h2></div></div></div><p>
+ This document concerns the specification of HAL which is a
+ piece of software that provides a view of the various hardware
+ attached to a system. In addition to this, HAL keeps detailed
+ metadata for each piece of hardware and provide hooks such
+ that system- and desktop-level software can react to changes
+ in the hardware configuration in order to maintain system
+ policy.
+ </p><p>
+ HAL represents a piece of hardware as a <span class="emphasis"><em>device object</em></span>.
+ A device object is identified by a unique identifer and carries a set of
+ key/value paris referred to as <span class="emphasis"><em>device properties</em></span>.
+ Some properties are derived from the actual hardware, some are merged
+ from <span class="emphasis"><em>device information files</em></span>
+ and some are related to the
+ actual device configuration. This document specifies the set
+ of device properties and gives them well-defined meaning. This
+ enable system and desktop level components to distinguish
+ between the different device objects and discover and
+ configure devices based on these properties.
+ </p><p>
+ 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
+ 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.
+ </p><p>
+ 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
+ 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.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction-acknowledgements"></a>Acknowledgements</h2></div></div></div><p>
+ Havoc Pennington's article
+ <a href="http://www.ometer.com/hardware.html" target="_top">''Making Hardware Just Work''
+ </a>
+ motivated this work. The specification and software would not exist
+ without all the useful ideas, suggestions, comments and patches
+ from the
+ <a href="http://freedesktop.org/mailman/listinfo/xdg" target="_top">Free Desktop</a> and
+ <a href="http://freedesktop.org/mailman/listinfo/hal" target="_top">HAL</a>
+ mailing lists.
+ </p><p>
+ All trademarks mentioned belong to their respective owners.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ov_halarch"></a>Architecture of HAL</h2></div></div></div><p>
+ 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 all implementation details.
+ </p><p>
+ <img src="hal-arch.png">
+ </p><p>
+ Details on each component
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <span class="emphasis"><em>HAL daemon</em></span>
+ </p><p>
+ 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.
+ </p></li><li><p>
+ <span class="emphasis"><em>Applications</em></span>
+ </p><p>
+ These are applications consuming services from HAL; this
+ includes desktop-wide session daemons for maintaining
+ policy such as power and disk/volume management.
+ </p></li><li><p>
+ <span class="emphasis"><em>Callouts</em></span>
+ </p><p>
+ 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 <code class="literal">info.callouts.add</code> and
+ <code class="literal">info.callouts.remove</code>. See
+ <a href="#device-properties-info" title="
+ info namespace
+ ">the section called “
+ info namespace
+ ”</a> for details.
+ </p></li><li><p>
+ <span class="emphasis"><em>Methods</em></span>
+ </p><p>
+ It is possible to specify that a given HAL device object
+ implements a specific D-Bus interface,
+ e.g. <code class="literal">org.freedesktop.Hal.Device.Frob</code>
+ with a set of
+ methods <code class="literal">Foo</code>, <code class="literal">Bar</code>
+ and <code class="literal">Baz</code> and have programs run when
+ applications call into this interface. This is defined in
+ the <code class="literal">info.interfaces</code> property, consult
+ <a href="#device-properties-info" title="
+ info namespace
+ ">the section called “
+ info namespace
+ ”</a> for details.
+ </p></li><li><p>
+ <span class="emphasis"><em>Addons</em></span>
+ </p><p>
+ An <span class="emphasis"><em>addon</em></span> can be characterized as a
+ daemon whose life cycle is tied to a device object in
+ HAL. And addon can also <span class="emphasis"><em>claim</em></span> 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 <code class="literal">info.addons</code> property. See
+ <a href="#device-properties-info" title="
+ info namespace
+ ">the section called “
+ info namespace
+ ”</a> for details.
+ </p></li><li><p>
+ <span class="emphasis"><em>Device Information Files</em></span>
+ </p><p>
+ 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.
+ </p></li></ul></div><p>
+ </p><p>
+ 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.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction-device-objects"></a>Device Objects</h2></div></div></div><p>
+ It is important to precisely define the term HAL device
+ object. It's actually a bit blurry to define in general, it
+ includes what most UNIX-like systems consider first class
+ objects when it comes to hardware. In particular, a device
+ object should represent the smallest unit of addressable
+ hardware. This means there can be a one-to-many relationship
+ between a physical device and the device objects exported by
+ HAL. Specifically, a multi-function printer, which appear to
+ users as a single device may show up as several device
+ objects; e.g. one HAL device object for each of the printing,
+ scanning, fax and storage interfaces. Conversely, some devices
+ may be implemented such that the HAL device object represent
+ several functional interfaces. HAL is not concerned with this
+ duality of either one-to-many or many-to-one relationships
+ between device objects and the actual iron constituting what
+ users normally understand as a single piece of hardware;
+ a device object represents the smallest addressable unit.
+ </p><p>
+ 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
+ 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 applications using HAL will not
+ notice this, 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.
+ </p><p>
+ 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
+ <code class="literal">/dev</code>. 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
+ <code class="literal">/dev/input/mouse2</code> 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
+ identifiers. See <a href="#device-capabilities" title="Device Capabilities">the section called “Device Capabilities”</a>
+ and
+ <a href="#device-properties" title="Chapter 5. Device Properties">Chapter 5, <i>Device Properties</i></a>
+ for details.
+ </p><p>
+ Finally, HAL provides one or more <span class="emphasis"><em>D-Bus
+ interfaces</em></span> for applications to configure and/or use
+ the device. These interfaces are discussed in
+ <a href="#interfaces" title="Chapter 6. D-Bus interfaces">Chapter 6, <i>D-Bus interfaces</i></a>.
+ </p><p>
+ Summarizing, a device object is comprised by
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <span class="emphasis"><em>UDI</em></span>
+ </p><p>
+ This is the the <span class="emphasis"><em>Unique Device
+ Identifer</em></span>, 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.
+ </p></li><li><p>
+ <span class="emphasis"><em>Properties</em></span>
+ </p><p>
+ Each device object got a set of properties which are
+ key/value pairs. The key is an ASCII string while the value
+ can be one of several types, see below. Properties are
+ arranged into name spaces using ''.'' as a separator.
+ </p><div class="itemizedlist"><ul type="circle"><li><p>
+ <code class="literal">string</code> - UTF8 string
+ </p></li><li><p>
+ <code class="literal">strlist</code> - ordered list with UTF8 strings
+ </p></li><li><p>
+ <code class="literal">int</code> - 32-bit signed integer
+ </p></li><li><p>
+ <code class="literal">uint64</code> - 64-bit unsigned integer
+ </p></li><li><p>
+ <code class="literal">bool</code> - truth value
+ </p></li><li><p>
+ <code class="literal">double</code> - IEEE754 double precision
+ floating point number
+ </p></li></ul></div><p>
+ </p></li><li><p>
+ <span class="emphasis"><em>Interfaces</em></span>
+ </p><p>
+ Applications can configure and/or use a device using D-Bus
+ interfaces. Typically, there's a one-to-one relationship
+ between capabilities/namespaces and interfaces.
+ </p></li></ul></div><p>
+ Properties of a device object carry all the important
+ information about a device object. For organisational reasons
+ properties are also namespaced using ''.'' as a separator.
+ </p><p>
+ It can be useful to classify properties into four groups
+ </p><div class="itemizedlist"><ul type="disc"><li><p>Metadata - Information about how the devices
+ are connected with respect to each other
+ (parent/child relationships), what kind of
+ device it is, what functionality it provides
+ etc.
+ </p></li><li><p>Facts -
+ vendor ID, product ID, disk serial numbers,
+ number of buttons on a mouse, formats accepted
+ by a mp3 player and so on.
+ </p></li><li><p>Usage specific information -
+ Network link status, special device file name,
+ filesystem mount location etc.
+ </p></li><li><p>Policy -
+ How the device is to be used be users; usually
+ defined by the system administrator.
+ </p></li></ul></div><p>
+ 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
+ <a href="#device-properties" title="Chapter 5. Device Properties">Chapter 5, <i>Device Properties</i></a> and onwards for more
+ information. As a complement to device properties, HAL also
+ provides <span class="emphasis"><em>conditions</em></span> 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''.
+ </p><p>
+ There is a special hal device object referred to as the ''root
+ computer device object''. This device object represent the
+ entire system as a whole and all other devices are either
+ directly or indirectly childs of this device object. It has
+ the
+ UDI <code class="literal">/org/freedesktop/Hal/devices/computer</code>.
+ </p><p>
+ The fundamental idea about HAL is that all ''interesting''
+ information about hardware that a desktop application needs,
+ can be obtained by querying HAL. Below is a screenshot of a
+ simple device manager application shipped with HAL
+ called <code class="literal">hal-device-manager</code>. This
+ application is communicating with the HAL daemon and displays
+ the tree of device objects. The shown properties are for a
+ device object representing a harddisk.
+ </p><p>
+ <img src="hal-devices1.png">
+ </p><p>
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="device-capabilities"></a>Device Capabilities</h2></div></div></div><p>
+ 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 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.
+ </p><p>
+ As HAL is concerned with merging of external metadata, through
+ e.g. device information files, there needs to be some scheme on
+ how to record what the device actually is. This is achieved by
+ two textual properties, <code class="literal">info.category</code> and
+ <code class="literal">info.capabilities</code>. The former describes
+ <span class="emphasis"><em>what the device is</em></span> (as a single
+ alphanumeric keyword) and the latter describes
+ <span class="emphasis"><em>what the device does</em></span> (as a number of
+ alphanumeric keywords separated by whitespace). The keywords
+ available for use is defined in this document; we'll refer to
+ them in following simply as <span class="emphasis"><em>capabilities</em></span>.
+ </p><p>
+ 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
+ and the hardware itself.
+ </p><p>
+ User mode drivers such as <code class="literal">libgphoto2</code>
+ and <code class="literal">sane</code> 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''.
+ </p><p>
+ Having a capability also means that part of the property
+ namespace, prefixed with the capability name, will be populated
+ with more specific information about the capability. Indeed,
+ 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 (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''.
+ </p><p>
+ Finally, capabilities have an inheritance scheme, e.g. if a device
+ has a capability <code class="literal">foo.bar</code>, it must also have
+ the capability <code class="literal">foo</code>.
+ </p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="spec-device-info"></a>Chapter 2. Device Information Files</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#fdi-matching">Matching</a></span></dt><dt><span class="sect1"><a href="#fdi-merging">Merging</a></span></dt><dt><span class="sect1"><a href="#fdi-search-paths">Search Paths</a></span></dt></dl></div><p>
+ Device information files (<code class="literal">.fdi</code> files is a
+ shorthand) are used to merge arbitrary properties onto device
+ objects. The way device information files works is that once all
+ device properties are merged onto a device object it is tried
+ against the set of installed device information files. Device
+ information files are used for both merging facts and policy
+ settings about devices.
+ </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdi-matching"></a>Matching</h2></div></div></div><p>
+ Each device information file got a number of
+ <code class="literal"><match key="some_property"
+ [string|int|bool|..]="required_value" >
+ </code>
+ directives
+ that is tested against the properties of the device object. If
+ all the match directives passes then the device information can
+ include <code class="literal"><[merge|append|prepend|addset] key="some_property"
+ type="[string|int|bool|..]">
+ </code>
+ 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.
+ </p><p>
+ The <code class="literal"><match></code>,
+ <code class="literal"><merge></code>, <code class="literal"><append></code>,
+ <code class="literal"><prepend></code>
+ and <code class="literal"><addset></code> directives always
+ requires the <code class="literal">key</code> 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
+ <code class="literal">/org/freedesktop/Hal/devices/computer:foo.bar</code>
+ or indirect references such as
+ <code class="literal">@info.parent:baz</code> where the latter means that
+ the device object specified by the UDI in the string property
+ <code class="literal">info.parent</code> should be used to query the
+ property <code class="literal">baz</code>. It is also possible to use
+ multiple indirections, e.g. for a volume on a USB memory stick
+ the indirection <code class="literal">@block.storage_device:@storage.originating_device:usb.vendor_id</code>
+ will reference the <code class="literal">usb.vendor_id</code> property
+ on the device object representing the USB interface.
+ </p><p>
+ When the property to match have been determined a number of
+ attributes can be used within the <code class="literal"><match></code>
+ tag:
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <code class="literal">string</code> - match a string property; for example
+ <code class="literal"><match key="foo.bar" string="baz"></code>
+ will match only if 'foo.bar' is a string property assuming the value 'baz'.
+ </p></li><li><p>
+ <code class="literal">string_outof</code> - work like <code class="literal">string</code> but
+ the match is done against a list of strings separated by ';'.
+ For example:
+ <code class="literal"><match key="system.hardware.product" string_outof="Satellite A30;Portable PC"></code>
+ In this example the line matches if <code class="literal">system.hardware.product</code>
+ is exactly 'Satellite A30' or 'Portable PC'.
+ </p></li><li><p>
+ <code class="literal">int</code> - match an integer property
+ </p></li><li><p>
+ <code class="literal">int_outof</code> - work like <code class="literal">int</code> but
+ the match is done against a list of integer separated by ';'.
+ For example:
+ <code class="literal"><match key="usb.product_id" int_outof="0x1007;0x1008;0x1009"></code>
+ In this example the line matches if <code class="literal">usb.product_id</code> is 0x1007, 0x1008 or 0x1009.
+ </p></li><li><p>
+ <code class="literal">uint64</code> - match property with the 64-bit unsigned type
+ </p></li><li><p>
+ <code class="literal">bool</code> - match a boolean property
+ </p></li><li><p>
+ <code class="literal">double</code> - match a property of type double
+ </p></li><li><p>
+ <code class="literal">exists</code> - used as
+ <code class="literal"><match key="foo.bar" exists="true"></code>. Can be used with
+ 'true' and 'false' respectively to match when a property exists and it doesn't.
+ </p></li><li><p>
+ <code class="literal">empty</code> - 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.
+ </p></li><li><p>
+ <code class="literal">is_ascii</code> - matches only when a string property
+ contain only ASCII characters. Can be used with 'true' or 'false'.
+ </p></li><li><p>
+ <code class="literal">is_absolute_path</code> - matches only when a string
+ property represents an absolute path (the path doesn't have to exist).
+ Can be used with 'true' or 'false'.
+ </p></li><li><p>
+ <code class="literal">sibling_contains</code> - can only be used with string and
+ strlist (string list).
+ For a string key this matches when a sibling item contains the
+ (sub-)string in the same property. For a string list, this is if a string
+ matches an item in the list.
+ </p></li><li><p>
+ <code class="literal">contains</code> - 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.
+ </p></li><li><p>
+ <code class="literal">contains_ncase</code> - like <code class="literal">contains</code>
+ but the property and the given key are converted to lowercase before check.
+ </p></li><li><p>
+ <code class="literal">contains_not</code> - can only be used with strlist (string list)
+ and string properties.
+ For a string list this match if the given string not match any of the
+ item of the list (or the property is not set for the device). 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. <code class="literal">contains</code>.
+ </p></li><li><p>
+ <code class="literal">contains_outof</code> - like <code class="literal">contains</code> but can be
+ used only with strings and the match is done against a list of (sub-)strings
+ separated by ';'.
+ For example:
+ <code class="literal"><match key="system.hardware.product" contains_outof="D600;D610;C540"></code>
+ In this example the line matches if <code class="literal">system.hardware.product</code>
+ contains D600, D610 or C540.
+ </p></li><li><p>
+ <code class="literal">prefix</code> - can only be used with string properties.
+ Matches if property begins with the key.
+ </p></li><li><p>
+ <code class="literal">prefix_ncase</code> - like <code class="literal">prefix</code> but the
+ property and the given key are converted to lowercase before the check.
+ </p></li><li><p>
+ <code class="literal">prefix_outof</code> - like <code class="literal">prefix</code> but the
+ match is done against a list of prefixes separated by ';'.
+ For example:
+ <code class="literal"><match key="system.hardware.product" prefix_outof="1860;2366;2371"></code>
+ In this example the line matches if <code class="literal">system.hardware.product</code>
+ starts with 1860, 2366 or 2371.
+ </p></li><li><p>
+ <code class="literal">suffix</code> - can only be used with string properties.
+ Matches if property ends with the key.
+ </p></li><li><p>
+ <code class="literal">suffix_ncase</code> - like <code class="literal">suffix</code> but the
+ property and the given key are converted to lowercase before the check.
+ </p></li><li><p>
+ <code class="literal">compare_lt</code> - 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.
+ </p></li><li><p>
+ <code class="literal">compare_le</code> - like <code class="literal">compare_lt</code>
+ but matches when less than or equal.
+ </p></li><li><p>
+ <code class="literal">compare_gt</code> - like <code class="literal">compare_lt</code>
+ but matches when greater than.
+ </p></li><li><p>
+ <code class="literal">compare_ge</code> - like <code class="literal">compare_lt</code>
+ but matches when greater than or equal.
+ </p></li><li><p>
+ <code class="literal">compare_ne</code> - like <code class="literal">compare_lt</code>
+ but matches when not equal.
+ </p></li></ul></div><p>
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdi-merging"></a>Merging</h2></div></div></div><p>
+
+ The <code class="literal"><merge></code>, <code class="literal"><append></code>,
+ <code class="literal"><prepend></code>
+ and <code class="literal"><addset></code> directives all require
+ the <code class="literal">type</code> attribute which specifies what to
+ merge. The following values are supported
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <code class="literal">string</code> - The value is copied to the property. For example
+ <code class="literal"><merge key="foo.bar" type="string">baz</merge></code>
+ will merge the value 'baz' into the property 'foo.bar'.
+ </p></li><li><p>
+ <code class="literal">strlist</code> - For <code class="literal"><merge></code> the value is
+ copied to the property and the current property will be overwritten. For
+ <code class="literal"><append></code>
+ and <code class="literal"><prepend></code> the value is
+ append or prepend to the list as new
+ item. For <code class="literal"><addset></code> the strlist
+ is treated as a set and the value is appended if, and only
+ if, the value doesn't exist already. Usage of
+ <code class="literal"><copy_property></code> overwrite the complete list with the
+ value of the given property to copy from.
+ </p></li><li><p>
+ <code class="literal">bool</code> - Can merge the values 'true' or 'false'
+ </p></li><li><p>
+ <code class="literal">int</code> - Merges an integer
+ </p></li><li><p>
+ <code class="literal">uint64</code> - Merges an unsigned 64-bit integer
+ </p></li><li><p>
+ <code class="literal">double</code> - Merges a double precision floating point number
+ </p></li><li><p>
+ <code class="literal">copy_property</code> - Copies the value of a given
+ property - supports paths with direct and indirect UDI's. For example
+ <code class="literal"><merge key="foo.bar" type="copy_property">@info.parent:baz.bat</merge></code>
+ will merge the value of the property <code class="literal">baz.bat</code> on the device object with the UDI from
+ the property <code class="literal">info.parent</code> into the property <code class="literal">foo.bar</code> on
+ the device object being processed.
+ </p></li></ul></div><p>
+ The <code class="literal"><remove></code>, directive require only a key and can be used with all keys.
+ For <code class="literal">strlist</code> there is additionally a special syntax to remove a item from the
+ string list. For example to remove item 'bla' from property 'foo.bar':
+ <code class="literal"><remove key="foo.bar" type="strlist">bla</remove></code>
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdi-search-paths"></a>Search Paths</h2></div></div></div><p>
+ Device Information files are read from two directories
+
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <code class="literal">/usr/share/hal/fdi</code> - for files provided by packages
+ </p></li><li><p>
+ <code class="literal">/etc/hal/fdi</code> - for files provided by the system administrator / user
+ </p></li></ul></div><p>
+
+ 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 <code class="literal">/usr/share/hal/fdi</code>
+
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <code class="literal">information</code> - device information files used to merge device information
+ </p><div class="itemizedlist"><ul type="circle"><li><p>
+ <code class="literal">10freedesktop</code> - included with the hal package
+ </p></li><li><p>
+ <code class="literal">20thirdparty</code> - from a 3rd party, not included in hal package
+ </p></li></ul></div><p>
+ </p></li><li><p>
+ <code class="literal">policy</code> - device information files to merge policy properties such as addons or callouts.
+ </p><div class="itemizedlist"><ul type="circle"><li><p>
+ <code class="literal">10osvendor</code> - included with the hal package
+ </p></li><li><p>
+ <code class="literal">20thirdparty</code> - from a 3rd party, not included in hal package
+ </p></li></ul></div><p>
+ </p></li><li><p>
+ <code class="literal">preprobe</code> - device information files read before probing devices
+ </p><div class="itemizedlist"><ul type="circle"><li><p>
+ <code class="literal">10osvendor</code> - included with the hal package
+ </p></li><li><p>
+ <code class="literal">20thirdparty</code> - from a 3rd party, not included in hal package
+ </p></li></ul></div><p>
+ </p></li></ul></div><p>
+
+ As evident, third party packages should drop device information files in
+
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <code class="literal">/usr/share/hal/fdi/information/20thirdparty</code>
+ </p></li><li><p>
+ <code class="literal">/usr/share/hal/fdi/policy/20thirdparty</code>
+ </p></li><li><p>
+ <code class="literal">/usr/share/hal/fdi/preprobe/20thirdparty</code>
+ </p></li></ul></div><p>
+
+ </p><p>
+ The <code class="literal">/etc/hal/fdi</code> tree uses this layout
+
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <code class="literal">information</code> - device information files used to merge device information
+ </p></li><li><p>
+ <code class="literal">policy</code> - device information files to merge policy properties such as addons or callouts.
+ </p></li><li><p>
+ <code class="literal">preprobe</code> - device information files to read before probing devices
+ </p></li></ul></div><p>
+
+ All device information files are matched for every hal device
+ object in the following order.
+
+ </p><div class="orderedlist"><ol type="1"><li><p>
+ When a device is discovered, the <code class="literal">preprobe</code>
+ device information files (e.g. all files
+ from <code class="literal">/usr/share/hal/fdi/preprobe</code>
+ and <code class="literal">/etc/hal/fdi/preprobe</code>) are
+ processed.
+ </p><p>
+ Typically, this class of device information files is used to
+ tell HAL to leave the device alone by setting the bool
+ property <code class="literal">info.ignore</code> to TRUE. It can also
+ be used to run programs, preprobe callouts, prior to normal
+ device investigation.
+ </p></li><li><p>
+ HAL now runs the preprobe callouts.
+ </p></li><li><p>
+ HAL now probes/investigates the device.
+ </p></li><li><p>
+ All the <code class="literal">information</code> device information
+ files (e.g. all files
+ from <code class="literal">/usr/share/hal/fdi/information</code>
+ and <code class="literal">/etc/hal/fdi/information</code>) are
+ processed.
+ </p><p>
+ These device information files are typically used to
+ associate extra information with a device object.
+ </p></li><li><p>
+ All the <code class="literal">policy</code> policy information
+ files (e.g. all files
+ from <code class="literal">/usr/share/hal/fdi/policy</code>
+ and <code class="literal">/etc/hal/fdi/policy</code>) are
+ processed.
+ </p><p>
+ These device information files are typically used to
+ associate callouts and addons with a device object.
+ </p></li><li><p>
+ HAL now runs the callouts, starts addons, and then finally
+ announces the device on the system message bus.
+ </p></li></ol></div><p>
+
+ </p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="access-control"></a>Chapter 3. Access Control</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#access-control-device-file">Device Files</a></span></dt><dt><span class="sect1"><a href="#access-control-ipc">D-Bus Interfaces</a></span></dt></dl></div><p>
+ Access to hardware by unprivileged users is traditionally granted
+ in two ways either by granting access to the <span class="emphasis"><em>special
+ device file</em></span> or allowing access through another process,
+ using IPC acting on behalf of the user. HAL follows the latter
+ model and uses the system-wide message bus (D-Bus) as the IPC
+ mechanism. In addition, HAL has support for modifying the ACL's
+ (access control lists) on a device file to grant/revoke access to
+ users based on several criteria.
+ </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="access-control-device-file"></a>Device Files</h2></div></div></div><p>
+ If HAL is built with <code class="literal">--enable-acl-management</code>
+ (requires both <code class="literal">--enable-console-kit</code>
+ and <code class="literal">--enable-policy-kit</code>) then ACL's on device
+ objects with the capability <code class="literal">access_control</code>
+ are automatically managed according to the properties defined in
+ <a href="#device-properties-access-control" title="
+ access_control namespace
+ ">the section called “
+ access_control namespace
+ ”</a>. In addition,
+ for this configuration, HAL ships with a device information file
+ (normally installed in
+ <code class="literal">/usr/share/hal/fdi/policy/10osvendor/20-acl-management.fdi</code>)
+ that merges this capability on device objects that are normally
+ accessed by unprivileged users through the device file. This
+ includes e.g. sound cards, webcams and other devices but
+ excludes drives and volumes as the latter two are normally
+ accessed by a user through mounting them into the file system.
+ </p><p>
+ HAL uses PolicyKit to decide what users should have access
+ according to PolicyKit configuration; see the PolicyKit
+ privilege definition
+ file <code class="literal">/etc/PolicyKit/privileges/hal-device-file.priv</code>
+ on a system with HAL installed for the default access suggested
+ by the HAL package and/or OS vendor.
+ </p><p>
+ In addition, 3rd party packages can supply device information
+ files to specify (via
+ the <code class="literal">access_control.grant_user</code>
+ and <code class="literal">access_control.grant_group</code> properties)
+ that a given user or group should always have access to a device
+ file. This is useful for system-wide software (such as AV
+ streaming management) that runs as an unprivileged system
+ user. This interface is supposed to be stable so 3rd party
+ packages can depend on it.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="access-control-ipc"></a>D-Bus Interfaces</h2></div></div></div><p>
+ If HAL is built without ConsoleKit support
+ (e.g. without <code class="literal">--enable-console-kit</code>) access to
+ the various D-Bus interfaces that provides mechanisms is only
+ protected by the D-Bus security configuration files
+ (e.g. using <code class="literal">at_console</code> to restrict to console
+ user on Red Hat systems) and, in certain cases, restricted to
+ the super user.
+ </p><p>
+ If ConsoleKit support is enabled, access to D-Bus interfaces is
+ currently hardcoded to only allow active users at the system
+ console. If PolicyKit support is enabled, the PolicyKit library
+ will be in charge of determining access; see the PolicyKit
+ privilege definition files
+ in <code class="literal">/etc/PolicyKit/privileges</code> on a system with
+ HAL installed for the default access suggested by the HAL
+ package and/or OS vendor.
+ </p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="locking"></a>Chapter 4. Locking</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#locking-overview">Overview</a></span></dt><dt><span class="sect1"><a href="#locking-guidelines">Guidelines</a></span></dt></dl></div><p>
+ As HAL is a mechanism that enables programs in a desktop session
+ to enforce the policy of the users choice, unexpected things can
+ happen. For example, if the user is in the middle of partitioning
+ a disk drive, it is desirable to keep the desktop from mounting
+ partitions that have not yet been prepared with a suitable file
+ system. In fact, in such a situation data loss may be the result
+ if a volume have an old file system signature indicating it's
+ mountable and, simultenously, another tool is writing to the raw
+ block device. The mechanism that automounters use, HAL, provides
+ locking primitives to avoid this.
+ </p><p>
+ Further, for multi-user systems, several desktop sessions may run
+ on a system each on their own display. Suppose that one session
+ becomes idle and the power management daemon in that session
+ decides to suspend the system according to user preferences in the
+ idle session. The result is that users at other seats will see the
+ system suspend and this is not desirable. The power management
+ daemons in all sessions need to cooperate to ensure that the
+ system only suspends when e.g. all sessions are idle or not at
+ all. The mechanism that each power management daemon uses, HAL,
+ provides locking primitives that can be used to achieve this.
+ </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="locking-overview"></a>Overview</h2></div></div></div><p>
+ HAL provides a mechanism to lock a specific D-Bus interface
+ either for a specific device or for all the devices the caller
+ have access to.
+ </p><p>
+ The former is achieved by using
+ the <code class="literal">AcquireInterfaceLock()</code>
+ and <code class="literal">ReleaseInterfaceLock()</code> methods on
+ the <code class="literal">org.freedesktop.Hal.Device</code> interface that
+ every device object implements (see
+ <a href="#interface-device" title="org.freedesktop.Hal.Device interface">the section called “org.freedesktop.Hal.Device interface”</a>). By using this API, a caller
+ can prevent any other caller from invoking methods on the given
+ interface for the given device object - other callers will
+ simply see
+ the <code class="literal">org.freedesktop.Hal.Device.InterfaceLocked</code>
+ exception if they attempt to invoke a method on the given
+ interface on the given device. The locker can specify whether
+ the lock is <span class="emphasis"><em>exclusive</em></span> meaning if multiple
+ clients clients can hold the lock or if only one client can hold
+ the lock at one time. If a client don't have access to the
+ interface of the device, attempts to lock will fail with
+ a <code class="literal">org.freedesktop.Hal.PermissionDenied</code>
+ exception. If a client loses access to a device (say, if his
+ session is switched away from using fast user switching) while
+ holding a lock, he will lose the lock; this can be tracked by
+ listening to the <code class="literal">InterfaceLockReleased</code>
+ signal.
+ </p><p>
+ All local clients, whether they are active or not, can always
+ lock interfaces on the root computer device object (this doesn't
+ mean that they are privileged to use the interfaces though) -
+ the rationale is that this device object represents shared
+ infrastructure, e.g. power management, and even inactive
+ sessions needs to participate in managing this.
+ </p><p>
+ If another client already holds a lock exclusively, attempts
+ from other clients to acquire the lock will fail with
+ the <code class="literal">org.freedesktop.Hal.Device.InterfaceAlreadyLocked</code>
+ exception even if they have access to the device.
+ </p><p>
+ In addition, a client may opt to lock all devices that he got
+ access to by using
+ the <code class="literal">AcquireGlobalInterfaceLock()</code>
+ and <code class="literal">ReleaseGlobalInterfaceLock()</code> methods on
+ the <code class="literal">org.freedesktop.Hal.Manager</code> interface on
+ the <code class="literal">/org/freedesktop/Hal/Manager</code> object (see
+ <a href="#interface-manager" title="org.freedesktop.Hal.Manager interface">the section called “org.freedesktop.Hal.Manager interface”</a>). Global interface locks can
+ also be obtained exclusively if the caller so desires. Unlike
+ per-device interface locking, it is not checked at locking time
+ whether the locker have access to a given device; instead
+ checking is done when callers attempt to access the
+ interface.
+ </p><p>
+ The algorithm used for determining if a caller is locked out is
+ shown below. A caller A is locked out of an interface IFACE on a
+ device object DEVICE if, and only if,
+ </p><div class="orderedlist"><ol type="1"><li><p>
+ Another caller B is holding a lock on the interface IFACE on
+ DEVICE and A don't have either a global lock on IFACE or a
+ lock on IFACE on DEVICE; or
+ </p></li><li><p>
+ Another caller B is holding the global lock on the
+ interface IFACE and B has access to DEVICE and and A don't
+ have either a global lock on IFACE or a lock on IFACE on
+ DEVICE.
+ </p></li></ol></div><p>
+ In other words, a caller A can grab a global lock, but that
+ doesn't mean A can lock other clients out of devices that A
+ doesn't have access to. Specifically a caller is never locked
+ out if he has locked an interface either globally or on the
+ device in question. However, if two clients have a lock on a
+ device, then both can access it. To ensure that everyone is
+ locked out, a caller needs to use an exclusive lock.
+ </p><p>
+ Note that certain interfaces will also check whether other locks
+ are being held on other device objects. This is specified on a
+ per-interface basis in <a href="#interfaces" title="Chapter 6. D-Bus interfaces">Chapter 6, <i>D-Bus interfaces</i></a>.
+ </p><p>
+ If a process holding locks disconnects from the system bus, the
+ locks being held by that process will be released.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="locking-guidelines"></a>Guidelines</h2></div></div></div><p>
+ Locking is only useful if applications requiring exclusive
+ access actually use the locking primitives to cooperate with
+ other applications. Here is a list of guidelines.
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <span class="emphasis"><em>Disk Management / Partitioning</em></span>
+ </p><p>
+ In order to prevent HAL-based automounters from mounting
+ partitions that are being prepared, applications that access
+ block devices directly (and pokes the kernel to reload the
+ partitioning table) should lock out automounters by either
+ a) obtaining
+ the <code class="literal">org.freedesktop.Hal.Device.Storage</code>
+ lock on each drive being processed; or b) obtaintaing the
+ global
+ <code class="literal">org.freedesktop.Hal.Device.Storage</code>
+ lock. This includes programs like fdisk, gparted, parted and
+ operating system installers. See also
+ <a href="#interface-device-volume" title="org.freedesktop.Hal.Device.Volume interface">the section called “org.freedesktop.Hal.Device.Volume interface”</a> and
+ the <code class="literal">hal-lock</code>(1) program and manual page.
+ </p></li><li><p>
+ <span class="emphasis"><em>Power Management</em></span>
+ </p><p>
+ Typically, a desktop session includes a session-wide power
+ management daemon that enforces the policy of the users
+ choice, e.g. whether the system should suspend to ram on lid
+ close, whether to hibernate the system after the user being
+ idle for 30 minutes and so on. In a multi-user setup (both
+ fast user switching and multi-seat), this can break in
+ various interesting ways unless the power management daemons
+ cooperate. Also, there may be software running at the system
+ level who will want to inhibit a desktop session power
+ management daemon from suspending / shutting down.
+ </p><div class="itemizedlist"><ul type="circle"><li><p>
+ System-level software that do not wish to be interrupted
+ by the effect of someone calling into the
+ <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface MUST hold the
+ <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ lock non-exclusively on the root computer device
+ object. For example, the YUM software updater should
+ hold the lock when doing an RPM transaction.
+ </p></li></ul></div><p>
+ In addition, any power management session daemon instance
+ </p><div class="itemizedlist"><ul type="circle"><li><p>
+ ... MUST hold the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code> lock
+ non-exclusively on the root computer device object
+ unless it is prepared to call into this interface
+ itself. This typically means that the PM daemon instance
+ simply acquires the lock on start up and releases it
+ just before it calls into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface. In other words, the PM daemon instance needs
+ to hold the lock exactly when it doesn't want other PM
+ daemon instances to call into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code> interface.
+ This means that if the user have configured the PM
+ daemon instance to go to sleep after 30 minutes of
+ inactivity, the lock should be released then.
+ </p></li><li><p>
+ ... MUST not hold the lock when the session is inactive
+ (fast user switching) UNLESS an application in the
+ session have explicitly called Inhibit() on
+ the <code class="literal">org.freedesktop.PowerManagement</code>
+ D-Bus session bus interface of the PM daemon.
+ </p></li><li><p>
+ ... MUST check that no other process is holding the lock (using the <code class="literal">IsLockedByOthers</code> method on the standard <code class="literal">org.freedesktop.Hal.Device</code> interface)
+ before calling into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface. If another process is holding the lock, it
+ means that either 1) another session is not prepared to
+ call into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface; OR 2) some system-level software is holding
+ the lock. The PM daemon instance MUST respect this by
+ not calling into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface itself.
+ </p></li></ul></div><p>
+ However, any Power management daemon instance
+ </p><div class="itemizedlist"><ul type="circle"><li><p>
+ ... MAY prompt the user, if applicable, to ask if she
+ still wants to perform the requested action (e.g. call
+ into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface) despite the fact that another process
+ (possibly from another user) is indicating that it does
+ not want the system to e.g. suspend. Only if the user
+ agrees, the power management instance should call into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface. Typically, it's only useful to prompt the
+ user with such questions if the request to call into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface originates from user input, e.g. either a
+ hotkey, the user clicking a suspend button in the UI or
+ an application invoking the <code class="literal">Suspend()</code> method on the
+ <code class="literal">org.freedesktop.PowerManagement</code> D-Bus
+ session interface of the PM daemon.
+ </p></li><li><p>
+ ... MAY ignore that other processes are holding the lock
+ and call into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface anyway, but ONLY if if the request to call
+ into
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface originated from e.g. lid close, critically low
+ battery or other similar conditions.
+ </p></li><li><p>
+ ... MAY still call <code class="literal">SetPowerSave()</code> on
+ the <code class="literal">org.freedesktop.Hal.Device.SystemPowerManagement</code>
+ interface even if other processes are holding the lock.
+ </p></li></ul></div></li></ul></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="device-properties"></a>Chapter 5. Device Properties</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#properties-general">General Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-info">
+ info namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-info-callouts">Callouts</a></span></dt><dt><span class="sect2"><a href="#device-properties-info-addons">Addons</a></span></dt><dt><span class="sect2"><a href="#device-properties-info-singleton-addons">Singleton Addons</a></span></dt><dt><span class="sect2"><a href="#device-properties-info-method-calls">Method calls</a></span></dt></dl></dd><dt><span class="sect1"><a href="#properties-subsystem">Subsystem-Specific Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-pci">
+ pci namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-serialif">
+ serial namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-usb">
+ usb_device namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-usbif">
+ usb namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-platform">
+ platform namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ide-host">
+ ide_host namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ide">
+ ide namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-scsi_host">
+ scsi_host namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-scsi">
+ scsi namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ieee1394_host">
+ ieee1394_host namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ieee1394_node">
+ ieee1394_node namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ieee1394">
+ ieee1394 namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-mmc_host">
+ mmc_host namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-mmc">
+ mmc namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ccw">
+ ccw namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ccwgroup">
+ ccwgroup namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-iucv">
+ iucv namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-block">
+ block namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-xen">xen namespace</a></span></dt><dt><span class="sect2"><a href="#device-properties-bluetooth_hci">bluetooth_hci namespace</a></span></dt><dt><span class="sect2"><a href="#device-properties-bluetooth_acl">bluetooth_acl namespace</a></span></dt><dt><span class="sect2"><a href="#device-properties-bluetooth_sco">bluetooth_sco namespace</a></span></dt><dt><span class="sect2"><a href="#device-properties-drm">drm namespace</a></span></dt></dl></dd><dt><span class="sect1"><a href="#properties-functional">Functional Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-kernel">
+ system namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-volume">
+ volume namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-volume-disc">
+ volume.disc namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-storage">
+ storage namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-storage-cdrom">
+ storage.cdrom namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-storage-linux-raid">
+ storage.linux_raid namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net">
+ net namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-80203">
+ net.80203 namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-80211">
+ net.80211 namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-bluetooth">
+ net.bluetooth namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-irda">
+ net.irda namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-net-80211control">
+ net.80211control namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input">
+ input namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-keys">
+ input.keys namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-keypad">
+ input.keypad namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-keyboard">
+ input.keyboard namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-mouse">
+ input.mouse namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-switch">
+ input.switch namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-joystick">
+ input.joystick namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-tablet">
+ input.tablet namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-keymap">
+ input.keymap namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-input-xkb">
+ input.xkb namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-pcmcia_socket">
+ pcmcia_socket namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-printer">
+ printer namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-portable_audio_player">
+ portable_audio_player namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-alsa">
+ alsa namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-oss">
+ oss namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-camera">
+ camera namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-scanner">
+ scanner namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-laptop-panel">
+ laptop_panel namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-ac_adapter">
+ ac_adapter namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-battery">
+ battery namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-button">
+ button namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-processor">
+ processor namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-light-sensor">
+ light_sensor namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-power-management">
+ power_management namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-tape">
+ tape namespace
+ </a></span></dt><dt><span class="sect2"><a href="#device-properties-killswitch">
+ killswitch namespace
+ </a></span></dt></dl></dd><dt><span class="sect1"><a href="#properties-misc">Misc. Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-access-control">
+ access_control namespace
+ </a></span></dt></dl></dd><dt><span class="sect1"><a href="#properties-deprecated">Deprecated Properties</a></span></dt></dl></div><p>
+ Properties are arranged in a namespaces using ''.'' as a separator
+ 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.
+ When a property changes, HAL will emit a D-Bus signal that applications
+ can catch.
+ </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="properties-general"></a>General Properties</h2></div></div></div><p>
+ The section represents properties that aren't tied to either
+ physical or functional characteristics of what the device
+ object represents.
+ </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-info"></a>
+ info namespace
+ </h3></div></div></div><p>
+ The <code class="literal">info</code> namespace contain properties that
+ can be considered metadata about device objects. These
+ properties are always available.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">info.subsystem</code> (string)
+ </td><td>pci, usb, ide_host, ide, block, usb, usbif, scsi_host, scsi</td><td>Yes</td><td>Describes what subsystem the device is connected to</td></tr><tr><td>
+ <code class="literal">info.udi</code> (string)
+ </td><td>example: /org/freedesktop/Hal/devices/pci_10ec_8139</td><td>Yes</td><td>The HAL unique device id</td></tr><tr><td>
+ <code class="literal">info.capabilities</code> (strlist)
+ </td><td>example: 'block, storage, storage.cdrom'</td><td>No</td><td>A string list of capabilities describing what the devices does</td></tr><tr><td>
+ <code class="literal">info.category</code> (string)
+ </td><td>example: storage.cdrom</td><td>No</td><td>The prominent capability describing what the device is</td></tr><tr><td>
+ <code class="literal">info.product</code> (string)
+ </td><td>examples: ''SleekKeyboard'', ''MouseMan 2003'', ''Volume'', ''LS-120 SLIM3 00 UHD Floppy''</td><td>No</td><td>The name of the device; should not be used in any UI; use subsystem / capability specific properties instead.</td></tr><tr><td>
+ <code class="literal">info.vendor</code> (string)
+ </td><td>examples: Logitch, Mustek</td><td>No</td><td>The name of the vendor of the device; should not be used in any UI; use subsystem / capability specific properties instead.</td></tr><tr><td>
+ <code class="literal">info.parent</code> (string)
+ </td><td>example: /org/freedesktop/Hal/devices/computer</td><td>Yes, for all non-root device objects</td><td>The UDI of the device object that this device object
+ is connected to.
+ </td></tr><tr><td>
+ <code class="literal">info.locked</code> (bool)
+ </td><td> </td><td>No</td><td>
+ If this property is available and set
+ to <code class="literal">TRUE</code> it means that a process
+ is using the device that the hal device object in
+ question represents and no other process should attempt
+ to use or configure the device. The lock is only
+ advisory.
+ </td></tr><tr><td>
+ <code class="literal">info.locked.reason</code> (string)
+ </td><td>
+ example: ''The optical drive is currently being used to
+ record a CD-RW disc.''
+ </td><td>
+ Only available if <code class="literal">info.locked</code> is set
+ to <code class="literal">TRUE</code>.
+ </td><td>A localized text suitable for UI display</td></tr><tr><td>
+ <code class="literal">info.locked.dbus_service</code> (string)
+ </td><td>example: :1.278</td><td>
+ Only available if <code class="literal">info.locked</code> is set
+ to <code class="literal">TRUE</code>.
+ </td><td>The base D-BUS service of the process holding the lock.</td></tr><tr><td>
+ <code class="literal">info.is_recalled</code> (bool)
+ </td><td> </td><td>No</td><td>
+ This is set if the hardware may be recalled and should
+ be checked for any potential problem.
+ </td></tr><tr><td>
+ <code class="literal">info.recall.vendor</code> (string)
+ </td><td>Dell, Sony, HP, Panasonic, etc.</td><td>Yes, if <code class="literal">info.is_recalled</code> is TRUE</td><td>
+ The vendor responsible for the hardware recall.
+ </td></tr><tr><td>
+ <code class="literal">info.recall.website_url</code> (string)
+ </td><td> </td><td>Yes, if <code class="literal">info.is_recalled</code> is TRUE</td><td>
+ Users should check this website for more details and if their
+ hardware may affected by any possible fault.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-info-callouts"></a>Callouts</h3></div></div></div><p>
+ 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
+ <code class="literal">/etc/fstab</code> file or configuring the networking
+ subsystem.
+ </p><p>
+ There are three different classes of callouts. A callout
+ involves sequentially invoking all executable programs in the
+ string list in listed order.
+ </p><p>
+ All callouts are searched for and execute in a minimal
+ environment. In addition, the UDI of the device object is
+ exported in the environment
+ variable <code class="literal">UDI</code>. All properties of the device
+ object are exported in the environment prefixed
+ with <code class="literal">HAL_PROP_</code>. If a device is added or
+ removed is exported in the environment
+ variable <code class="literal">HALD_ACTION
+ </code>. The search path for the callout includes the
+ following paths:
+ </p><div class="orderedlist"><ol type="1"><li><p>
+ <code class="literal">$libexecdir</code> (typically <code class="literal">/usr/libexec</code> (e.g. Red Hat) or <code class="literal">/usr/lib/hal</code> (e.g. Debian))
+ </p></li><li><p>
+ <code class="literal">$libdir/hal/scripts</code> (typically <code class="literal">/usr/lib/hal/scripts</code> or
+ <code class="literal">/usr/lib64/hal/scripts</code>)
+ </p></li><li><p>
+ <code class="literal">$bindir/</code> (typically <code class="literal">/usr/bin</code>)
+ </p></li></ol></div><p>
+ including $PATH the HAL daemon was started with during system
+ initialization. Depending on the distribution, this typically
+ includes <code class="literal">/sbin</code>,
+ <code class="literal">/usr/sbin</code>,
+ <code class="literal">/bin</code>,
+ <code class="literal">/usr/sbin</code>. If the program to run is not
+ found in any of these paths, the it <span class="emphasis"><em>will
+ not</em></span> run even if the given path is absolute. To be
+ portable across operating systems, third party packages
+ providing callouts must therefore only
+ use <code class="literal">$libdir/hal/scripts</code>.
+ </p><p>
+ If ConsoleKit support is enabled, the variables
+ <code class="literal">CK_NUM_SEATS</code> (number of seats),
+ <code class="literal">CK_NUM_SESSIONS</code> (number of sessions),
+ <code class="literal">CK_SEATS</code> (tab sep. list of seat-id's),
+ <code class="literal">CK_SEAT_seat-id</code> (tab sep. list of session-id's for a seat),
+ <code class="literal">CK_SEAT_NUM_SESSIONS_seat-id</code> (number of sessions on a seat),
+ <code class="literal">CK_SESSION_SEAT_session-id</code> (the seat that a session belongs to) and
+ <code class="literal">CK_SESSION_IS_ACTIVE_session-id</code> (whether a given session is active) and
+ <code class="literal">CK_SESSION_UID_session-id</code> (the user of the session) and
+ <code class="literal">CK_SESSION_IS_LOCAL_session-id</code> (whether a session is local),
+ <code class="literal">CK_SESSION_HOSTNAME_session-id</code> (host name of session's display if it's not local),
+ will be exported as well. Example:
+ </p><pre class="programlisting">
+CK_NUM_SEATS=1
+CK_NUM_SESSIONS=2
+CK_SEATS=Seat1
+CK_SEAT_Seat1=Session1 Session3
+CK_SEAT_NUM_SESSIONS_Seat1=2
+CK_SESSION_IS_ACTIVE_Session1=true
+CK_SESSION_IS_ACTIVE_Session3=false
+CK_SESSION_IS_LOCAL_Session1=true
+CK_SESSION_IS_LOCAL_Session3=true
+CK_SESSION_SEAT_Session1=Seat1
+CK_SESSION_SEAT_Session3=Seat1
+CK_SESSION_UID_Session1=500
+CK_SESSION_UID_Session3=501
+ </pre><p>
+ Note that all ConsoleKit object paths given are just base
+ names; the real D-Bus object path can be reconstructed by
+ appending <code class="literal">/org/freedesktop/ConsoleKit/</code>
+ prepended to the given identifer.
+ </p><p>
+ 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.
+ </p><p>
+ 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 <code class="literal">HALD_DIRECT_ADDR</code> environment
+ variable. There is convience API in libhal to do this.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">info.callouts.add</code> (string list)
+ </td><td> </td><td>No</td><td>
+ A string list with the programs which should be
+ executed (with <code class="literal">HALD_ACTION=add</code>)
+ when the device is added to the GDL (global device
+ list) but just before it is announced through the
+ D-BUS network API.
+ </td></tr><tr><td>
+ <code class="literal">info.callouts.remove</code> (string list)
+ </td><td> </td><td>No</td><td>
+ A string list with the programs that should be
+ executed (with <code class="literal">HALD_ACTION=remove</code>)
+ when the device is removed from the GDL (global device
+ list). The device isn't removed before the last
+ callout has finished.
+ </td></tr><tr><td>
+ <code class="literal">info.callouts.preprobe</code> (string list)
+ </td><td> </td><td>No</td><td>
+ A string list with the programs that should be
+ executed
+ (with <code class="literal">HALD_ACTION=preprobe</code>) before
+ the device is probed (e.g. investigated) and can be
+ used to avoid causing unnecessary I/O.
+ </td></tr><tr><td>
+ <code class="literal">info.callouts.session_add</code> (string list)
+ </td><td> </td><td>No</td><td>
+ A string list with all programs that should be
+ executed
+ (with <code class="literal">HALD_ACTION=session_add</code>) when
+ a session is added. Can only be set on the root
+ computer device object. The environment also contains
+ the variables
+ <code class="literal">HALD_SESSION_ADD_SESSION_ID</code>,
+ <code class="literal">HALD_SESSION_ADD_SESSION_UID</code> and
+ <code class="literal">HALD_SESSION_ADD_SESSION_IS_ACTIVE</code>
+ to identify the session. This is only used when HAL is
+ built with ConsoleKit support.
+ </td></tr><tr><td>
+ <code class="literal">info.callouts.session_remove</code> (string list)
+ </td><td> </td><td>No</td><td>
+ A string list with all programs which should be
+ executed
+ (with <code class="literal">HALD_ACTION=session_remove</code>)
+ when a session is removed. Can only be set on the root
+ computer device object. The environment also contains
+ the variables
+ <code class="literal">HALD_SESSION_REMOVE_SESSION_ID</code>,
+ <code class="literal">HALD_SESSION_REMOVE_SESSION_UID</code> and
+ <code class="literal">HALD_SESSION_REMOVE_SESSION_IS_ACTIVE</code>
+ to identify the session. This is only used when HAL is
+ built with ConsoleKit support.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-info-addons"></a>Addons</h3></div></div></div><p>
+ Addons are programs that run for the life time of the device
+ object. They are searched for and execute in the same
+ environment as callouts
+ (e.g. with <code class="literal">HAL_PROP_*</code> 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 <code class="literal">SIGTERM</code> to the process.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">info.addons</code> (strlist)
+ </td><td> </td><td>No</td><td>
+ List of programs to run when device is added. Each
+ program will need to call
+ the <code class="literal">AddonIsReady()</code> method in order
+ for the device to show up on D-Bus.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-info-singleton-addons"></a>Singleton Addons</h3></div></div></div><p>
+ Singleton Addons are programs that are started by HAL to
+ handle a set of devices. They are identified by the command line
+ used to start them. They MUST implement the
+ <a href="#interface-singleton-addon" title="org.freedesktop.Hal.SingletonAddon interface">
+ <code class="literal">org.freedesktop.Hal.SingletonAddon</code>
+ </a>
+ interface. on the path
+ <code class="literal">/org/freedesktop/Hal/Singleton</code> path on
+ the direct connection to the HAL daemon.
+ </p><p>
+ When a device is added with an <code class="literal">info.addons.singleton</code>
+ string list key, the elements of that key are used as the command line
+ to start the singleton if the singleton is not already running.
+ Once the singleton has called <code class="literal">SingletonAddonIsReady</code> on
+ <a href="#interface-manager" title="org.freedesktop.Hal.Manager interface">
+ <code class="literal">org.freedesktop.Hal.Manager</code>
+ </a> interface, it will receive
+ <code class="literal">DeviceAdded</code> calls on its
+ <a href="#interface-singleton-addon" title="org.freedesktop.Hal.SingletonAddon interface">
+ <code class="literal">org.freedesktop.Hal.SingletonAddon</code>
+ </a>
+ interface for all devices that have
+ its commandline in <code class="literal">info.addons.singletona</code>.
+ </p><p>
+ If a device is added and the singleton specified in
+ <code class="literal">info.addons.singleton</code> is already running, the
+ singleton will recieve <code class="literal">DeviceAdded</code> on its
+ <a href="#interface-singleton-addon" title="org.freedesktop.Hal.SingletonAddon interface">
+ <code class="literal">org.freedesktop.Hal.SingletonAddon</code>
+ </a>
+ interface for that new device. </p><p>
+ When a device is removed that is being handled by a singleton, the
+ singleton will recieve <code class="literal">DeviceRemoved</code> on
+ <a href="#interface-singleton-addon" title="org.freedesktop.Hal.SingletonAddon interface">
+ <code class="literal">org.freedesktop.Hal.SingletonAddon</code>
+ </a>.
+ When it is no longer handling any more devices it should exit cleanly.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">info.addons.singleton</code> (strlist)
+ </td><td> </td><td>No</td><td>
+ A list of commandlines for singleton addons which should
+ service this device.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-info-method-calls"></a>Method calls</h3></div></div></div><p>
+ 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 <code class="literal">ClaimInterface()</code> API since it reduces
+ the overhead of spawning a process and it can handle both
+ complex incoming and return types as well. See <a href="#interface-device" title="org.freedesktop.Hal.Device interface">the section called “org.freedesktop.Hal.Device interface”</a> for
+ details on claiming interfaces via an addon..
+ </p><p>
+ 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.
+ </p><p>
+ As with addons, method calls are searched for and execute in
+ the same minimal environment as callouts
+ (e.g. with <code class="literal">HAL_PROP_*</code> set in the
+ environment to represent the device properties) and in
+ addition the environment variables
+ <code class="literal">HAL_METHOD_INVOKED_BY_UID</code> (the uid of the caller)
+ and
+ <code class="literal">HAL_METHOD_INVOKED_BY_SYSTEMBUS_CONNECTION_NAME</code>
+ (the unique system bus connection name of the caller) are
+ set. Additionally, if HAL is built with ConsoleKit support,
+ <code class="literal">HAL_METHOD_INVOKED_BY_PID</code> and
+ <code class="literal">HAL_METHOD_INVOKED_BY_SELINUX_CONTEXT</code> (but
+ only if the running system have SELinux enabled) will be
+ set. If HAL itself, or a HAL addon, is invoking a method, then
+ these variables will not be present. Here's an example
+ </p><pre class="programlisting">
+HAL_METHOD_INVOKED_BY_UID=500
+HAL_METHOD_INVOKED_BY_PID=22553
+HAL_METHOD_INVOKED_BY_SELINUX_CONTEXT=user_u:system_r:unconfined_t
+HAL_METHOD_INVOKED_BY_SYSTEMBUS_CONNECTION_NAME=:1.138
+ </pre><p>
+ In addition, with ConsoleKit
+ support, <code class="literal">HAL_METHOD_INVOKED_BY_SESSION</code> will
+ be set to (the basename) of the ConsoleKit session object path
+ but only if the caller is in a session. The method handler can
+ then use the previously
+ mentioned <code class="literal">CK_SESSION_*</code> to learn everything
+ about the context of the caller.
+
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">info.interfaces</code> (strlist)
+ </td><td> </td><td>No</td><td>
+ A list of D-Bus interfaces that the device object
+ supports apart from the
+ standard <code class="literal">org.freedesktop.Hal.Device</code>
+ interface.
+ </td></tr><tr><td>
+ <code class="literal"><iface>.method_names</code> (strlist)
+ </td><td>example: <code class="literal">'Foo', 'Bar', 'Baz'</code></td><td>No</td><td>
+ If a D-Bus interface is implemented by executing a
+ program for every method, this property contains an
+ ordered list of the method names.
+ </td></tr><tr><td>
+ <code class="literal"><iface>.method_argnames</code> (strlist)
+ </td><td>example: <code class="literal">'foo_arg1 foo_arg2', '', 'baz_arg1'</code></td><td>No</td><td>
+ This property contains the names of the arguments for
+ each method. Each entry is a white-space separated
+ list for that particular method.
+ </td></tr><tr><td>
+ <code class="literal"><iface>.method_signatures</code> (strlist)
+ </td><td>example: <code class="literal">'si', '', 'as'</code></td><td>No</td><td>
+ 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.
+ </td></tr><tr><td>
+ <code class="literal"><iface>.method_execpaths</code> (strlist)
+ </td><td>example: <code class="literal">'foo-binary', 'bar-binary', 'baz-binary'</code></td><td>No</td><td>
+ 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.
+ </td></tr></tbody></table></div><p>
+ Items in the <code class="literal"><iface>.*</code> clearly must
+ correspond with each other. The whole mechanism is best
+ explained by an example:
+
+ </p><pre class="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'}
+ </pre><p>
+
+ which, for example, shows that the <code class="literal">Mount()</code>
+ method on the
+ interface <code class="literal">org.freedesktop.Hal.Device.Volume</code>
+ takes three arguments: <code class="literal">mount_point</code> (a
+ string), <code class="literal">fstype</code> (a string)
+ and <code class="literal">extra_options</code> (an array of strings).
+
+ </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="properties-subsystem"></a>Subsystem-Specific Properties</h2></div></div></div><p>
+ In this section properties for device objects that represent
+ addressable hardware is described. Availability of
+ these depends on the value of the <code class="literal">info.subsystem</code>
+ property. These properties are not of particular interest to
+ application developers, instead they are useful for libraries
+ and userspace drivers that needs to interact with the device
+ given a UDI. Knowledge of various subsystem-specific
+ technologies is assumed for this section to be useful.
+ </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-pci"></a>
+ pci namespace
+ </h3></div></div></div><p>
+ This namespace contains properties for device objects representing
+ functions on devices on a PCI bus. These properties are available
+ exactly when <code class="literal">info.subsystem</code> equals <code class="literal">pci</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">pci.device_class</code> (int)
+ </td><td>example: 3</td><td>Yes</td><td>Device Class</td></tr><tr><td>
+ <code class="literal">pci.device_subclass</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>PCI Device Sub Class</td></tr><tr><td>
+ <code class="literal">pci.device_protocol</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>Device Protocol</td></tr><tr><td>
+ <code class="literal">pci.product_id</code> (int)
+ </td><td>example: 0x4c4d</td><td>Yes</td><td>Product ID</td></tr><tr><td>
+ <code class="literal">pci.vendor_id</code> (int)
+ </td><td>example: 0x1002</td><td>Yes</td><td>Vendor ID</td></tr><tr><td>
+ <code class="literal">pci.subsys_product_id</code> (int)
+ </td><td>example: 0x009e</td><td>Yes</td><td>Subsystem product id</td></tr><tr><td>
+ <code class="literal">pci.subsys_vendor_id</code> (int)
+ </td><td>example: 0x1028</td><td>Yes</td><td>Subsystem vendor id</td></tr><tr><td>
+ <code class="literal">pci.linux.sysfs_path</code> (string)
+ </td><td>example: /sys/devices/pci0000:00/0000:00:01/0000:01:00.0</td><td>Yes (only on Linux)</td><td>
+ Equals <code class="literal">linux.sysfs_path</code>
+ </td></tr><tr><td>
+ <code class="literal">pci.product</code> (string)
+ </td><td>Rage Mobility P/M AGP 2x</td><td>No</td><td>Name of the product per the PCI database</td></tr><tr><td>
+ <code class="literal">pci.vendor</code> (string)
+ </td><td>ATI Technologies Inc</td><td>No</td><td>Name of the vendor per the PCI database</td></tr><tr><td>
+ <code class="literal">pci.subsys_product</code> (string)
+ </td><td>Inspiron 7500</td><td>No</td><td>Name of the subsystem product per the PCI database</td></tr><tr><td>
+ <code class="literal">pci.subsys_vendor</code> (string)
+ </td><td>Dell Computer Corporation</td><td>No</td><td>Name of the subsystem vendor per the PCI database</td></tr></tbody></table></div><p>
+ (FIXME: Some key PCI information (bus, slot, port, function
+ etc.) is missing here)
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-serialif"></a>
+ serial namespace
+ </h3></div></div></div><p>
+ Device objects that represent serial devices (e.g. /dev/ttyS* or
+ /dev/ttyUSB*).
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">serial.originating_device</code> (string)
+ </td><td>
+ example: <code class="literal">/org/freedesktop/Hal/devices/pnp_PNP0501</code>
+ </td><td>Yes</td><td>UDI of the device the serial device is bound to.</td></tr><tr><td>
+ <code class="literal">serial.device</code> (string)
+ </td><td>example: /dev/ttyS0</td><td>Yes</td><td>The device node to access the OSS device.</td></tr><tr><td>
+ <code class="literal">serial.port</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>
+ The port number of the device, based on the number in
+ <code class="literal">serial.device</code>
+ </td></tr><tr><td>
+ <code class="literal">serial.type</code> (string)
+ </td><td>example: platform, usb, unknown</td><td>Yes</td><td>This property defines the type of the serial device.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-usb"></a>
+ usb_device namespace
+ </h3></div></div></div><p>
+ For device objects representing USB devices the property
+ <code class="literal">info.subsystem</code> will be <code class="literal">usb_device</code>,
+ and the following properties will be available. Note that the
+ corresponding USB interfaces are represented by separate
+ device objects as children.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">usb_device.bus_number</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>The USB bus the device is attached to</td></tr><tr><td>
+ <code class="literal">usb_device.configuration_value</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>The current configuration the USB device is in;
+ starting from 1
+ </td></tr><tr><td>
+ <code class="literal">usb_device.configuration</code> (int)
+ </td><td>example: Bulk transfer configuration</td><td>No</td><td>Human-readable description of the current configuration the USB device is in
+ </td></tr><tr><td>
+ <code class="literal">usb_device.num_configurations</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>Number of configurations this USB device
+ can assume
+ </td></tr><tr><td>
+ <code class="literal">usb_device.device_class</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>USB Device Class</td></tr><tr><td>
+ <code class="literal">usb_device.device_subclass</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>USB Device Sub Class</td></tr><tr><td>
+ <code class="literal">usb_device.device_protocol</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>USB Device Protocol</td></tr><tr><td>
+ <code class="literal">usb_device.is_self_powered</code> (bool)
+ </td><td>example: false</td><td>Yes</td><td>The device, in the current configuration, is self
+ powered
+ </td></tr><tr><td>
+ <code class="literal">usb_device.can_wake_up</code> (bool)
+ </td><td>example: true</td><td>Yes</td><td>The device, in the current configuration, can wake up</td></tr><tr><td>
+ <code class="literal">usb_device.max_power</code> (int)
+ </td><td>example: 98</td><td>Yes</td><td>Max power drain of device, in mA</td></tr><tr><td>
+ <code class="literal">usb_device.num_interfaces</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>Number of USB Interfaces in the current configuration</td></tr><tr><td>
+ <code class="literal">usb_device.num_ports</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>Number of ports on a hub. Zero for non-hubs</td></tr><tr><td>
+ <code class="literal">usb_device.port_number</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>The port number on the parent hub that the device is attached to, starting from 1</td></tr><tr><td>
+ <code class="literal">usb_device.speed</code> (double)
+ </td><td>examples: 1.5, 12.0, 480.0</td><td>Yes</td><td>Speed of device, in Mbit/s</td></tr><tr><td>
+ <code class="literal">usb_device.version</code> (double)
+ </td><td>examples: 1.0, 1.1, 2.0</td><td>Yes</td><td>USB version of device</td></tr><tr><td>
+ <code class="literal">usb_device.level_number</code> (int)
+ </td><td>example: 2</td><td>Yes</td><td>Depth in USB tree, where the virtual root hub
+ is at depth 0
+ </td></tr><tr><td>
+ <code class="literal">usb_device.linux.device_number</code> (string)
+ </td><td>example: 19</td><td>Yes (only on Linux)</td><td>USB Device Number as assigned by the Linux kernel</td></tr><tr><td>
+ <code class="literal">usb_device.linux.parent_number</code> (string)
+ </td><td>example: 19</td><td>Yes (only on Linux)</td><td>Device number of parent device as assigned by the
+ Linux kernel
+ </td></tr><tr><td>
+ <code class="literal">usb_device.linux.sysfs_path</code> (string)
+ </td><td>example: /sys/devices/pci0000:00/0000:00:07.2/usb1/1-1/1-1.1</td><td>Yes (only on Linux)</td><td>
+ Equals <code class="literal">linux.sysfs_path</code>
+ </td></tr><tr><td>
+ <code class="literal">usb_device.product_id</code> (int)
+ </td><td>example: 0x3005</td><td>Yes</td><td>USB Product ID</td></tr><tr><td>
+ <code class="literal">usb_device.vendor_id</code> (int)
+ </td><td>example: 0x04b3</td><td>Yes</td><td>USB Vendor ID</td></tr><tr><td>
+ <code class="literal">usb_device.device_revision_bcd</code> (int)
+ </td><td>example: 0x0100</td><td>Yes</td><td>Device Revision Number encoded in BCD with two decimals</td></tr><tr><td>
+ <code class="literal">usb_device.serial</code> (string)
+ </td><td> </td><td>No</td><td>A string uniquely identifying the instance
+ of the device; ie. it will be different for two devices
+ of the same type. Note that the serial number is broken
+ on some USB devices.
+ </td></tr><tr><td>
+ <code class="literal">usb_device.product</code> (string)
+ </td><td>example: IBM USB HUB KEYBOARD</td><td>No</td><td>Name of the product per the USB ID Database</td></tr><tr><td>
+ <code class="literal">usb_device.vendor</code> (string)
+ </td><td>example: IBM Corp.</td><td>No</td><td>Name of the vendor per the USB ID Database</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-usbif"></a>
+ usb namespace
+ </h3></div></div></div><p>
+ Device objects that represent USB interfaces, ie. when
+ <code class="literal">info.subsystem</code> assumes <code class="literal">usb</code>,
+ are represented by the properties below. In addition all
+ the <code class="literal">usb_device.*</code> properties from the parent
+ USB device is available in this namespace but only with
+ the <code class="literal">usb</code> prefix instead of
+ <code class="literal">usb_device</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">usb.interface.class</code> (int)
+ </td><td>example: 0x03</td><td>Yes</td><td>USB Class for the interface</td></tr><tr><td>
+ <code class="literal">usb.interface.subclass</code> (int)
+ </td><td>example: 0x01</td><td>Yes</td><td>USB Sub Class for this interface</td></tr><tr><td>
+ <code class="literal">usb.interface.protocol</code> (int)
+ </td><td>example: 0x01</td><td>Yes</td><td>USB Protocol for the interface</td></tr><tr><td>
+ <code class="literal">usb.interface.description</code> (int)
+ </td><td>example: SyncML interface</td><td>No</td><td>Human-readable description for the interface provided by the device</td></tr><tr><td>
+ <code class="literal">usb.interface.number</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>Number of this interface, starting from zero</td></tr><tr><td>
+ <code class="literal">usb.linux.sysfs_path</code> (string)
+ </td><td>example: /sys/devices/pci0000:00/0000:00:07.2/usb1/1-1/1-1.1/1-1.1:1.0</td><td>Yes (only on Linux)</td><td>
+ Equals <code class="literal">linux.sysfs_path</code>
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-platform"></a>
+ platform namespace
+ </h3></div></div></div><p>
+ Devices that are built into the platform or present on busses that
+ cannot be properly enumerated (e.g. ISA) are represented by device
+ objects where <code class="literal">info.subsystem</code> equals
+ <code class="literal">platform</code>. These kind of devices are commonly,
+ somewhat incorrectly, called legacy devices.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">platform.id</code> (string)
+ </td><td>example: serial</td><td>Yes</td><td>Device identification</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-ide-host"></a>
+ ide_host namespace
+ </h3></div></div></div><p>
+ The <code class="literal">ide_host</code> namespace is present for
+ device objects where <code class="literal">info.subsystem</code> is set
+ to <code class="literal">ide_host</code>. Such device objects represent
+ IDE and ATA host adaptors for harddisks and optical drives as
+ found in the majority of computer systems.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ide_host.number</code> (int)
+ </td><td> </td><td>Yes</td><td>A unique number identifying the IDE host adaptor</td></tr><tr><td>
+ <code class="literal">ide_host.linux.sysfs_path</code> (string)
+ </td><td>example: /sys/devices/pci0000:00/0000:00:07.1/ide0</td><td>Yes (only on Linux)</td><td>
+ Equals <code class="literal">linux.sysfs_path</code>
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-ide"></a>
+ ide namespace
+ </h3></div></div></div><p>
+ ATA and IDE drives are represented by device objects where
+ <code class="literal">info.subsystem</code> equals <code class="literal">ide</code>. The
+ following properties are available for such device objects.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ide.host</code> (int)
+ </td><td> </td><td>Yes</td><td>Corresponds
+ to <code class="literal">ide_host.host_number</code> of
+ the <code class="literal">ide_host</code> device that is the
+ parent of this device object
+ </td></tr><tr><td>
+ <code class="literal">ide.channel</code> (int)
+ </td><td> </td><td>Yes</td><td>Identifies the IDE channel of the host interface</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-scsi_host"></a>
+ scsi_host namespace
+ </h3></div></div></div><p>
+ The <code class="literal">scsi_host</code> namespace is present for
+ device objects where <code class="literal">info.subsystem</code> is set
+ to <code class="literal">scsi_host</code>. Such device objects represent
+ SCSI host adaptors for SCSI devices as found in some computer
+ systems.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">scsi_host.host</code> (int)
+ </td><td> </td><td>Yes</td><td>A unique number identifying the SCSI host adaptor</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-scsi"></a>
+ scsi namespace
+ </h3></div></div></div><p>
+ SCSI devices are represented by device objects where
+ <code class="literal">info.subsystem</code> equals <code class="literal">scsi</code>.
+ The following properties are available for such device objects.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">scsi.host</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ Corresponds to <code class="literal">scsi_host.host</code>
+ of the <code class="literal">scsi_host</code> device that is the
+ parent of this device object
+ </td></tr><tr><td>
+ <code class="literal">scsi.bus</code> (int)
+ </td><td> </td><td>Yes</td><td>SCSI channel number</td></tr><tr><td>
+ <code class="literal">scsi.target</code> (int)
+ </td><td> </td><td>Yes</td><td>SCSI identifier number</td></tr><tr><td>
+ <code class="literal">scsi.lun</code> (int)
+ </td><td> </td><td>Yes</td><td>SCSI Logical Unit Number</td></tr><tr><td>
+ <code class="literal">scsi.type</code> (string)
+ </td><td>Example: disk</td><td>Yes</td><td>SCSI device type</td></tr><tr><td> </td><td>cdrom</td><td> </td><td>This is a SCSI cdrom device.</td></tr><tr><td> </td><td>comm</td><td> </td><td>This is a SCSI communication device.</td></tr><tr><td> </td><td>disk</td><td> </td><td>This is a SCSI disk device.</td></tr><tr><td> </td><td>medium_changer</td><td> </td><td>This is a SCSI media changer (e.g. for CD/Tape).</td></tr><tr><td> </td><td>printer</td><td> </td><td>This is a SCSI printer.</td></tr><tr><td> </td><td>processor</td><td> </td><td>This is a SCSI processor device.</td></tr><tr><td> </td><td>raid</td><td> </td><td>This is a SCSI raid device.</td></tr><tr><td> </td><td>scanner</td><td> </td><td>This is a SCSI scanner.</td></tr><tr><td> </td><td>tape</td><td> </td><td>This is a SCSI tape device.</td></tr><tr><td> </td><td>unknown</td><td> </td><td>The type of this SCSI device is unknwon.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-ieee1394_host"></a>
+ ieee1394_host namespace
+ </h3></div></div></div><p>
+ Device objects with <code class="literal">info.subsystem</code> set to
+ <code class="literal">ieee1394_host</code> represent IEEE 1394 host
+ adaptors. The following properties are available for such
+ device objects.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ieee1394_host.is_busmgr</code> (bool)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">ieee1394_host.is_irn</code> (bool)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">ieee1394_host.is_root</code> (bool)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">ieee1394_host.node_count</code> (int)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">ieee1394_host.nodes_active</code> (int)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-ieee1394_node"></a>
+ ieee1394_node namespace
+ </h3></div></div></div><p>
+ Device objects with <code class="literal">info.subsystem</code> set to
+ <code class="literal">ieee1394_node</code> represent IEEE 1394 nodes on
+ a IEEE 1394 bus. The following properties are available for
+ such device objects.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ieee1394_node.capabilities</code> (int)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">ieee1394_node.guid</code> (int)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">ieee1394_node.nodeid</code> (int)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">ieee1394_node.vendor</code> (int)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">ieee1394_node.vendor_id</code> (int)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-ieee1394"></a>
+ ieee1394 namespace
+ </h3></div></div></div><p>
+ Device objects with <code class="literal">info.subsystem</code> set to
+ <code class="literal">ieee1394</code> represent IEEE 1394 devices. The
+ following properties are available for such device objects.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ieee1394.specifier_id</code> (int)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-mmc_host"></a>
+ mmc_host namespace
+ </h3></div></div></div><p>
+ Device objects with <code class="literal">info.subsystem</code> set to
+ <code class="literal">mmc_host</code> represent MultiMediaCard or
+ Secure Digital host adaptors. The following properties
+ are available for such device objects.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">mmc_host.host</code> (int)
+ </td><td> </td><td>Yes</td><td>A unique number identifying the MMC/SD host adaptor</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-mmc"></a>
+ mmc namespace
+ </h3></div></div></div><p>
+ Device objects with <code class="literal">info.subsystem</code> set to
+ <code class="literal">mmc</code> represent MultiMediaCard or Secure
+ Digital cards. The following properties are available for
+ such device objects.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">mmc.cid</code> (string)
+ </td><td>example: 0150415330303842413a1a8083003a9d</td><td>Yes</td><td>Card Identification Data register (unique for every card
+ in existence)
+ </td></tr><tr><td>
+ <code class="literal">mmc.csd</code> (string)
+ </td><td>example: 005d013213598067b6d9cfff1640002d</td><td>Yes</td><td>Card Specific Data register</td></tr><tr><td>
+ <code class="literal">mmc.scr</code> (string)
+ </td><td>example: 00a5000000410000</td><td>Only for SD cards</td><td>SD Card Register</td></tr><tr><td>
+ <code class="literal">mmc.rca</code> (int)
+ </td><td>example: 8083</td><td>Yes</td><td>Card bus address</td></tr><tr><td>
+ <code class="literal">mmc.oem</code> (string)
+ </td><td> </td><td>Yes</td><td>Card OEM distributor</td></tr><tr><td>
+ <code class="literal">mmc.date</code> (string)
+ </td><td>example: 10/2003</td><td>Yes</td><td>Manufacturing date</td></tr><tr><td>
+ <code class="literal">mmc.serial</code> (int)
+ </td><td>example: 0x3a1a8083</td><td>Yes</td><td>Card serial number</td></tr><tr><td>
+ <code class="literal">mmc.hwrev</code> (int)
+ </td><td>example: 4</td><td>Yes</td><td>Hardware revision</td></tr><tr><td>
+ <code class="literal">mmc.fwrev</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>Firmware revision</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-ccw"></a>
+ ccw namespace
+ </h3></div></div></div><p>
+ Device objects that represent s390 ccw devices (when <code class="literal">info.subsystem
+ </code>
+ is set to <code class="literal">ccw</code>) are represented by the
+ properties below.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccw.devtype</code> (string)
+ </td><td>example: 1732/01</td><td>Yes</td><td>Device type/model or n/a</td></tr><tr><td>
+ <code class="literal">ccw.cutype</code> (string)
+ </td><td>example: 1731/01</td><td>Yes</td><td>Control unit type/model</td></tr><tr><td>
+ <code class="literal">ccw.cmb_enable</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>If channel measurements are enabled</td></tr><tr><td>
+ <code class="literal">ccw.availability</code> (string)
+ </td><td>example: good</td><td>Yes</td><td>Can be one of 'good', 'boxed', 'no path',
+ or 'no device'
+ </td></tr><tr><td>
+ <code class="literal">ccw.online</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>Online status</td></tr><tr><td>
+ <code class="literal">ccw.bus_id</code> (string)
+ </td><td>example: 0.0.f588</td><td>Yes</td><td>The device's bus id in sysfs</td></tr><tr><td>
+ <code class="literal">ccw.subchannel.pim</code> (int)
+ </td><td>example: 0x80</td><td>No</td><td>path installed mask</td></tr><tr><td>
+ <code class="literal">ccw.subchannel.pam</code> (int)
+ </td><td>example: 0x80</td><td>No</td><td>path available mask</td></tr><tr><td>
+ <code class="literal">ccw.subchannel.pom</code> (int)
+ </td><td>example: 0xff</td><td>No</td><td>path operational mask</td></tr><tr><td>
+ <code class="literal">ccw.subchannel.chpid0..7</code> (int)
+ </td><td>example: 0x40</td><td>No</td><td>channel path ids</td></tr></tbody></table></div><p>
+ The following properties describe <code class="literal">ccw</code> devices where
+ <code class="literal">linux.driver</code> is either <code class="literal">dasd-eckd</code>
+ or <code class="literal">dasd-fba</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccw.dasd.use_diag</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>If the device driver shall use diagnose calls to access
+ the device
+ </td></tr><tr><td>
+ <code class="literal">ccw.dasd.readonly</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>If the device can only be accessed readonly</td></tr><tr><td>
+ <code class="literal">ccw.dasd.discipline</code> (string)
+ </td><td>example: ECKD</td><td>No</td><td>The dasd discipline used to access the device</td></tr></tbody></table></div><p>
+ The following properties describe <code class="literal">ccw</code> devices where
+ <code class="literal">linux.driver</code> is <code class="literal">zfcp</code>. They are
+ only present when <code class="literal">ccw.online = 1</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccw.zfcp.in_recovery</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>Shows whether the adapter is currently in recovery</td></tr><tr><td>
+ <code class="literal">ccw.zfcp.failed</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>Shows whether the adapter is in failed state</td></tr></tbody></table></div><p>
+ The following properties describe <code class="literal">ccw</code> devices where
+ <code class="literal">linux.driver</code> is of the form <code class="literal">tape_3xxx
+ </code>
+ .
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccw.tape.state</code> (string)
+ </td><td>example: IN_USE</td><td>Yes</td><td>The current status of the tape</td></tr><tr><td>
+ <code class="literal">ccw.tape.operation</code> (string)
+ </td><td>example: REW</td><td>Yes</td><td>A three-letter mnemonic of the current tape operation
+ </td></tr><tr><td>
+ <code class="literal">ccw.tape.medium_state</code> (string)
+ </td><td>example: no medium</td><td>No</td><td>
+ If <code class="literal">ccw.online = 1</code>, shows whether a tape
+ is loaded
+ </td></tr><tr><td>
+ <code class="literal">ccw.tape.blocksize</code> (int)
+ </td><td>example: 512</td><td>No</td><td>
+ If <code class="literal">ccw.online = 1</code>, shows the blocksize
+ used for reads and writes to the tape
+ </td></tr></tbody></table></div><p>
+ The following properties describe <code class="literal">ccw</code> devices where
+ <code class="literal">linux.driver</code> is <code class="literal">3270</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccw.3270.model</code> (int)
+ </td><td>example: 3</td><td>Yes</td><td>The model of the device, determining rows and columns
+ </td></tr><tr><td>
+ <code class="literal">ccw.3270.rows</code> (int)
+ </td><td>example: 32</td><td>Yes</td><td>The number of rows</td></tr><tr><td>
+ <code class="literal">ccw.3270.columns</code> (int)
+ </td><td>example: 80</td><td>Yes</td><td>The number of columns</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-ccwgroup"></a>
+ ccwgroup namespace
+ </h3></div></div></div><p>
+ Device objects that represent groups of <code class="literal">ccw</code> devices
+ (when <code class="literal">info.subsystem</code> is set to <code class="literal">ccwgroup</code>
+ have the properties specified below.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccwgroup.online</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>Online status</td></tr><tr><td>
+ <code class="literal">ccwgroup.bus_id</code> (string)
+ </td><td>example: 0.0.f588</td><td>Yes</td><td>The device's bus id in sysfs</td></tr></tbody></table></div><p>
+ The following properties describe <code class="literal">ccwgroup</code> devices
+ where <code class="literal">linux.driver</code> is <code class="literal">qeth</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccwgroup.qeth.large_send</code> (string)
+ </td><td>example: TSO</td><td>No</td><td>Whether large send is provided. Can be "no", "EDDP"
+ (software) or "TSO" (hardware).
+ </td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.card_type</code> (string)
+ </td><td>example: OSD_1000</td><td>Yes</td><td>Type of the card</td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.checksumming</code> (string)
+ </td><td>example: sw checksumming</td><td>No</td><td>The method used to checksum incoming packets</td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.canonical_macaddr</code> (int)
+ </td><td>example: 0</td><td>No</td><td>Specifies the token ring macaddress format. Not valid in
+ layer2 mode and for ethernet devices.
+ </td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.broadcast_mode</code> (string)
+ </td><td>example: broadcast_allrings</td><td>No</td><td>The scope of token ring broadcasts. Not valid in layer2
+ mode and for ethernet devices.
+ </td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.fake_broadcast</code> (int)
+ </td><td>example: 0</td><td>No</td><td>Whether to fake broadcast capability. Not valid in layer2
+ mode.
+ </td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.fake_ll</code> (int)
+ </td><td>example: 0</td><td>No</td><td>Whether to add a faked link level header to packets.
+ Not valid in layer2 mode.
+ </td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.layer2</code> (int)
+ </td><td>example: 0</td><td>No</td><td>Whether the card operates in layer 2 mode</td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.portname</code> (string)
+ </td><td>example: OSAPORT</td><td>No</td><td>The port name which has been specified for the card</td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.portno</code> (int)
+ </td><td>example: 0</td><td>No</td><td>The relative port number on the card</td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.buffer_count</code> (int)
+ </td><td>example: 16</td><td>Yes</td><td>Number of inbound buffers used</td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.add_hhlen</code> (int)
+ </td><td>example: 0</td><td>No</td><td>How much additional space is provided in the hardware
+ header in skbs in front of packets
+ </td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.priority_queueing</code>
+ (string)
+ </td><td>example: always queue 2</td><td>No</td><td>Which priority queueing algorithm is to be used</td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.route4</code> (string)
+ </td><td>example: no</td><td>No</td><td>Whether the card has a routing functionality for ipv4.
+ Not valid in layer2 mode.
+ </td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.route6</code> (string)
+ </td><td>example: no</td><td>No</td><td>Whether the card has a routing functionality for ipv6.
+ Not valid in layer2 mode.
+ </td></tr><tr><td>
+ <code class="literal">ccwgroup.qeth.state</code> (string)
+ </td><td>example: UP (LAN ONLINE)</td><td>Yes</td><td>The device's current state</td></tr></tbody></table></div><p>
+ The following properties describe <code class="literal">ccwgroup</code> devices
+ where <code class="literal">linux.driver</code> is <code class="literal">ctc</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccwgroup.ctc.protocol</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>The protocol/method used by the connection</td></tr><tr><td>
+ <code class="literal">ccwgroup.ctc.type</code> (string)
+ </td><td>example: CTC/A</td><td>Yes</td><td>The device/connection type</td></tr><tr><td>
+ <code class="literal">ccwgroup.ctc.buffer</code> (int)
+ </td><td>example: 32768</td><td>No</td><td>The maximum buffer size of the connection</td></tr></tbody></table></div><p>
+ The following properties describe <code class="literal">ccwgroup</code> devices
+ where <code class="literal">linux.driver</code> is <code class="literal">lcs</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccwgroup.lcs.portnumber</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>The port on the card that is used</td></tr><tr><td>
+ <code class="literal">ccwgroup.lcs.type</code> (string)
+ </td><td>example: OSA LCS card</td><td>Yes</td><td>The type of the card</td></tr><tr><td>
+ <code class="literal">ccwgroup.lcs.lancmd_timeout</code> (int)
+ </td><td>example: 5</td><td>Yes</td><td>The timeout value for LAN commands in seconds</td></tr></tbody></table></div><p>
+ The following properties describe <code class="literal">ccwgroup</code> devices
+ where <code class="literal">linux.driver</code> is <code class="literal">claw</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ccwgroup.claw.api_type</code> (string)
+ </td><td> </td><td>Yes</td><td>Determines the packing algorithm for outgoing pakets
+ (matching the remote peer)
+ </td></tr><tr><td> </td><td>IP</td><td> </td><td>Using the IP protocol</td></tr><tr><td> </td><td>PACKED</td><td> </td><td>Using an enhanced packing algorithm</td></tr><tr><td> </td><td>TCPIP</td><td> </td><td>Using the TCP/IP protocol</td></tr><tr><td>
+ <code class="literal">ccwgroup.claw.adapter_name</code> (string)
+ </td><td>example: RS1</td><td>Yes</td><td>The host name of the remote communication peer.</td></tr><tr><td>
+ <code class="literal">ccwgroup.claw.host_name</code> (string)
+ </td><td>example: LNX1</td><td>Yes</td><td>The host name of the local adapter.</td></tr><tr><td>
+ <code class="literal">ccwgroup.claw.read_buffer</code> (int)
+ </td><td>example: 4</td><td>Yes</td><td>The number of read buffers allocated</td></tr><tr><td>
+ <code class="literal">ccwgroup.claw.write_buffer</code> (int)
+ </td><td>example: 5</td><td>Yes</td><td>The number of write buffers allocated</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-iucv"></a>
+ iucv namespace
+ </h3></div></div></div><p>
+ Device objects with <code class="literal">info.subsystem</code> set to <code class="literal">iucv
+ </code>
+ are using the "Intra-User Comminication Vehicle" and are
+ described by the following properties.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">iucv.bus_id</code> (string)
+ </td><td>example: netiucv0</td><td>Yes</td><td>The device's bus id in sysfs</td></tr></tbody></table></div><p>
+ The following properties describe <code class="literal">iucv</code> devices
+ where <code class="literal">linux.driver</code> is <code class="literal">netiucv</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">iucv.netiucv.user</code> (string)
+ </td><td>example: linux12</td><td>Yes</td><td>The guest name of the connection's target</td></tr><tr><td>
+ <code class="literal">iucv.netiucv.buffer</code> (int)
+ </td><td>example: 32768</td><td>Yes</td><td>The maximum buffer size of the connection</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-block"></a>
+ block namespace
+ </h3></div></div></div><p>
+ Device objects representing addressable block devices, such as
+ drives and partitions, will have <code class="literal">info.subsystem</code>
+ set to <code class="literal">block</code> and will export a number of
+ properties in the <code class="literal">block</code> namespace.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">block.device</code> (string)
+ </td><td>example: /dev/sda </td><td>Yes</td><td>Special device file to interact with the block device</td></tr><tr><td>
+ <code class="literal">block.major</code> (int)
+ </td><td>example: 8</td><td>Yes</td><td>Major number of special file to interact with the
+ device
+ </td></tr><tr><td>
+ <code class="literal">block.minor</code> (int)
+ </td><td>example: 1</td><td>Yes</td><td>Minor number of special file to interact with the
+ device
+ </td></tr><tr><td>
+ <code class="literal">block.is_volume</code> (bool)
+ </td><td> </td><td>Yes</td><td>True only when the block device is a volume that can
+ be mounted into the file system. In this case the
+ <code class="literal">volume</code> capability will be set and
+ thus, properties, in the <code class="literal">volume</code>
+ namespace are available.
+ </td></tr><tr><td>
+ <code class="literal">block.no_partitions</code> (bool)
+ </td><td> </td><td>Yes</td><td>For toplevel block devices, this is TRUE only
+ when no known partition tables have been found on the
+ media (In this case, if the storage device contain a
+ file system it will be accessible using the same
+ special device file as the one for this device object
+ and the device object representing the filesystem will
+ appear as a separate device object as a child). For
+ the child, that is
+ when <code class="literal">block.is_volume</code> is true, this
+ property is TRUE exactly when it was created for a
+ storage device with
+ the <code class="literal">storage.no_partitions_hint</code> set
+ to TRUE.
+ </td></tr><tr><td>
+ <code class="literal">block.have_scanned</code> (bool)
+ </td><td> </td><td>Yes</td><td>
+ An internal property used by HAL to specify whether a top
+ level block device have already been scanned for filesystems.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-xen"></a>xen namespace</h3></div></div></div><p>
+ Device objects representing virtual devices under the Xen
+ Virtual Machine Monitor, such as frontend network or block
+ devices, will have <code class="literal">info.subsystem</code> set to
+ <code class="literal">block</code> and will export a number of
+ properties in then <code class="literal">xen</code> namespace.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">xen.bus_id</code> (string)</td><td>example: vif-0 </td><td>Yes</td><td>The XenBus ID of the device</td></tr><tr><td><code class="literal">xen.path</code> (string)</td><td>example: device/vif/0 </td><td>Yes</td><td>The XenBus path of the device</td></tr><tr><td><code class="literal">xen.type</code> (string)</td><td>example: vif</td><td>Yes</td><td>The type of Xen device</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-bluetooth_hci"></a>bluetooth_hci namespace</h3></div></div></div><p>
+ Device objects representing a Bluetooth Host Controller Interface.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">bluetooth_hci.address</code> (uint64)</td><td> </td><td>Yes</td><td>Address of the host controller interface.</td></tr><tr><td><code class="literal">bluetooth_hci.originating_device</code> (string)</td><td> </td><td>Yes</td><td>The UDI of the physical device (e.g. an USB interface) that provides the HCI hardware.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-bluetooth_acl"></a>bluetooth_acl namespace</h3></div></div></div><p>
+ Device objects representing Asynchronous Connection-oriented Links.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">bluetooth_acl.address</code> (uint64)</td><td> </td><td>Yes</td><td>Address of the device at the other end of the connection.</td></tr><tr><td><code class="literal">bluetooth_acl.originating_device</code> (string)</td><td> </td><td>Yes</td><td>The UDI of the Bluetooth HCI (of
+ capability <code class="literal">bluetooth_hci</code>) that the
+ connection is made through.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-bluetooth_sco"></a>bluetooth_sco namespace</h3></div></div></div><p>
+ Device objects representing Synchronous Connection-Oriented links.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">bluetooth_sco.address</code> (uint64)</td><td> </td><td>Yes</td><td>Address of the device at the other end of the connection.</td></tr><tr><td><code class="literal">bluetooth_sco.originating_device</code> (string)</td><td> </td><td>Yes</td><td>The UDI of the Bluetooth HCI (of
+ capability <code class="literal">bluetooth_hci</code>) that the
+ connection is made through.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-drm"></a>drm namespace</h3></div></div></div><p>
+ The <code class="literal">drm</code> namespace is present for Direct Rendering Manager device objects.
+ They represent a Direct Rendering Interface.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">drm.dri_library</code> (string)</td><td> </td><td>Yes</td><td>Name of the dri (Direct Rendering Interface) library (e.g. i915).</td></tr><tr><td><code class="literal">drm.version</code> (string)</td><td> </td><td>Yes</td><td>The drm version (of the kernel module/diver).</td></tr></tbody></table></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="properties-functional"></a>Functional Properties</h2></div></div></div><p>
+ The section describe functional properties of device objects,
+ that is, properties that are merged onto device objects
+ representing addressable hardware. In most
+ circumstances such properties stem from a kernel level
+ driver attached to the device represented by the device object,
+ however, as HAL can merge properties from anywhere, they
+ may have been merged from device information files or callouts.
+ </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-kernel"></a>
+ system namespace
+ </h3></div></div></div><p>
+ This namespace is found on the toplevel "Computer" device,
+ and represents information about the system and the currently
+ running kernel.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">system.kernel.name</code> (string)
+ </td><td>example: Linux</td><td>No</td><td>
+ The name of the kernel, usually the equivalent of
+ <code class="literal">uname -s</code>.
+ </td></tr><tr><td>
+ <code class="literal">system.kernel.version</code> (string)
+ </td><td>example: 2.6.5-7.104-default</td><td>No</td><td>
+ The version of the currently running kernel. Usually
+ the equivalent of <code class="literal">uname -r</code>.
+ </td></tr><tr><td>
+ <code class="literal">system.kernel.machine</code> (string)
+ </td><td>example: i686</td><td>No</td><td>
+ The "machine hardware name" of the currently running kernel.
+ Usually the equivalent of <code class="literal">uname -m</code>.
+ </td></tr><tr><td>
+ <code class="literal">system.formfactor</code> (string)
+ </td><td>example: laptop, desktop, server, unknown</td><td>Yes</td><td>
+ The formfactor of the system. Usually the equivalent of
+ <code class="literal">system.chassis.type</code> or set from information
+ about ACPI/APM/PMU properties.
+ </td></tr><tr><td>
+ <code class="literal">system.hardware.vendor</code> (string)
+ </td><td> </td><td>No</td><td>
+ The name of the manufacturer of the machine.
+ </td></tr><tr><td>
+ <code class="literal">system.product</code> (string)
+ </td><td> </td><td>No</td><td>
+ The product name of the machine.
+ </td></tr><tr><td>
+ <code class="literal">system.hardware.version</code> (string)
+ </td><td> </td><td>No</td><td>
+ The version of the machine.
+ </td></tr><tr><td>
+ <code class="literal">system.hardware.serial</code> (string)
+ </td><td> </td><td>No</td><td>
+ The serial number of the machine.
+ </td></tr><tr><td>
+ <code class="literal">system.hardware.uuid</code> (string)
+ </td><td> </td><td>No</td><td>
+ The unique ID of the machine.
+ </td></tr><tr><td>
+ <code class="literal">system.hardware.primary_video.vendor</code> (int)
+ </td><td> </td><td>No</td><td>
+ The PCI vendor ID of the primary graphics card in the system.
+ </td></tr><tr><td>
+ <code class="literal">system.hardware.primary_video.product</code> (int)
+ </td><td> </td><td>No</td><td>
+ The PCI device ID of the primary graphics card in the system.
+ </td></tr><tr><td>
+ <code class="literal">system.firmware.vendor</code> (string)
+ </td><td> </td><td>No</td><td>
+ The firmware vendor.
+ </td></tr><tr><td>
+ <code class="literal">system.firmware.version</code> (string)
+ </td><td> </td><td>No</td><td>
+ The firmware version.
+ </td></tr><tr><td>
+ <code class="literal">system.firmware.release_date</code> (string)
+ </td><td> </td><td>No</td><td>
+ The release date of the firmware.
+ </td></tr><tr><td>
+ <code class="literal">system.chassis.manufacturer</code> (string)
+ </td><td> </td><td>No</td><td>
+ The manufacturer of the chassis.
+ </td></tr><tr><td>
+ <code class="literal">system.chassis.type</code> (string)
+ </td><td> </td><td>No</td><td>
+ The chassis type of the machine.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-volume"></a>
+ volume namespace
+ </h3></div></div></div><p>
+ This namespace is for device objects that represent storage
+ devices with a filesystem that can be mounted. Such device
+ objects will have the capability <code class="literal">volume</code> and
+ they will export the properties below. Note that device
+ objects can only have the <code class="literal">volume</code> capability
+ if they already have the capability <code class="literal">block</code>
+ and the property <code class="literal">block.is_volume</code> set to TRUE.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">volume.ignore</code> (bool)
+ </td><td> </td><td>Yes</td><td>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.
+ </td></tr><tr><td>
+ <code class="literal">volume.is_mounted</code> (bool)
+ </td><td> </td><td>Yes</td><td>This property is TRUE if and only if the volume is mounted</td></tr><tr><td>
+ <code class="literal">volume.is_mounted_read_only</code> (bool)
+ </td><td> </td><td>Yes</td><td>This property is TRUE if and only if the volume is mounted and
+ the volume's file-system is read-only.
+ </td></tr><tr><td>
+ <code class="literal">volume.mount_point</code> (string)
+ </td><td>example: /media/compact_flash1 </td><td>Yes (is blank only when volume.is_mounted is FALSE)</td><td>A fully qualified path to the mount point of the volume</td></tr><tr><td>
+ <code class="literal">volume.fsusage</code> (string)
+ </td><td>example: filesystem</td><td>Yes</td><td>
+ This property specifies the expected usage of the volume
+ </td></tr><tr><td> </td><td>filesystem</td><td> </td><td>The volume is a mountable filesystem</td></tr><tr><td> </td><td>partitiontable</td><td> </td><td>
+ The volume contains a partitiontable.
+ </td></tr><tr><td> </td><td>raid</td><td> </td><td>The volume is a member of a raid set and not mountable</td></tr><tr><td> </td><td>other</td><td> </td><td>The volume is not mountable like a swap partition</td></tr><tr><td> </td><td>unused</td><td> </td><td>The volume is marked a unused or free</td></tr><tr><td>
+ <code class="literal">volume.fstype</code> (string)
+ </td><td>examples: ext3, vfat</td><td>Yes (is blank if the type is unknown)</td><td>The specific type of either the file system or what the volume is used for, cf. volume.fsusage</td></tr><tr><td>
+ <code class="literal">volume.fsversion</code> (string)
+ </td><td>example: FAT32</td><td> </td><td>Version number or subtype of the filesystem</td></tr><tr><td>
+ <code class="literal">volume.label</code> (string)
+ </td><td>example: 'Fedora Core 1.90' </td><td>Yes (is blank if no label is found)</td><td>The label of the volume</td></tr><tr><td>
+ <code class="literal">volume.uuid</code> (string)
+ </td><td>example: 4060-6C11</td><td>Yes (is blank if no UUID is found)</td><td>The Universal Unique Identifer for the volume</td></tr><tr><td>
+ <code class="literal">volume.is_disc</code> (bool)
+ </td><td> </td><td>Yes</td><td>If the volume stems from an optical disc, this
+ property is true and the device object will also have
+ the capability <code class="literal">volume.disc</code>
+ </td></tr><tr><td>
+ <code class="literal">volume.block_size</code> (string)
+ </td><td> </td><td>No</td><td>
+ The block size of the volume
+ </td></tr><tr><td>
+ <code class="literal">volume.num_blocks</code> (string)
+ </td><td> </td><td>No</td><td>
+ Number of blocks on the volume
+ </td></tr><tr><td>
+ <code class="literal">volume.size</code> (uint64)
+ </td><td> </td><td>No</td><td>
+ Size of the volume in bytes
+ </td></tr><tr><td>
+ <code class="literal">volume.is_partition</code> (bool)
+ </td><td> </td><td>Yes</td><td>
+ If the volume stems from a partition on e.g. a hard
+ disk, this property is set to <code class="literal">TRUE</code>.
+ </td></tr><tr><td>
+ <code class="literal">volume.linux.is_device_mapper</code> (bool)
+ </td><td> </td><td>Yes, but only on Linux</td><td>
+ If the volume stems from the Linux Device Mapper this property is set to <code class="literal">TRUE</code>.
+ </td></tr><tr><td>
+ <code class="literal">volume.partition.number</code> (int)
+ </td><td> </td><td>
+ If, and only if, <code class="literal">volume.is_partition</code>
+ is set to <code class="literal">TRUE</code>.
+ </td><td>
+ The number of the partition.
+ </td></tr><tr><td>
+ <code class="literal">volume.partition.label</code> (string)
+ </td><td> </td><td>
+ If, and only if, <code class="literal">volume.is_partition</code>
+ is set to <code class="literal">TRUE</code>.
+ </td><td>
+ Label of partition. Only available for "apm" and "gpt"
+ partition tables. Note that this is not the same as the
+ file system label defined in <code class="literal">volume.label</code>.
+ </td></tr><tr><td>
+ <code class="literal">volume.partition.uuid</code> (string)
+ </td><td> </td><td>
+ If, and only if, <code class="literal">volume.is_partition</code>
+ is set to <code class="literal">TRUE</code>.
+ </td><td>
+ The UUID or GUID of the partition table entry. Only available for
+ "gpt" partition tables.
+ </td></tr><tr><td>
+ <code class="literal">volume.partition.scheme</code> (string)
+ </td><td> </td><td>
+ If, and only if, <code class="literal">volume.is_partition</code>
+ is set to <code class="literal">TRUE</code>.
+ </td><td>
+ The scheme of the partition table this entry is part of.
+ Note that this is not necessarily the same as
+ <code class="literal">storage.partitioning_scheme</code> as
+ some partition tables can embed other partition tables.
+ </td></tr><tr><td> </td><td>mbr</td><td> </td><td>
+ Master Boot Record
+ </td></tr><tr><td> </td><td>embr</td><td> </td><td>
+ Extended Master Boot Record
+ </td></tr><tr><td> </td><td>gpt</td><td> </td><td>
+ GUID Partition Table as defined by EFI
+ </td></tr><tr><td> </td><td>apm</td><td> </td><td>
+ Apple Partition Map
+ </td></tr><tr><td>
+ <code class="literal">volume.partition.type</code> (string)
+ </td><td> </td><td>
+ If, and only if, <code class="literal">volume.is_partition</code>
+ is set to <code class="literal">TRUE</code>.
+ </td><td>
+ The type of the partition table entry. Depends on
+ <code class="literal">volume.partition.scheme</code>.
+ </td></tr><tr><td> </td><td><code class="literal">mbr</code> and <code class="literal">embr</code> entries</td><td> </td><td>
+ The hexadecimal encoding of the 8-bit partition type, see
+ http://www.win.tue.nl/~aeb/partitions/partition_types-1.html
+ for a list. For example the Linux partition type is represented
+ as the string "0x83".
+ </td></tr><tr><td> </td><td><code class="literal">gpt</code> entries</td><td> </td><td>
+ The GUID encoded as a string. See http://en.wikipedia.org/wiki/GUID_Partition_Table
+ for a list of well-known GUID's.
+ </td></tr><tr><td> </td><td><code class="literal">apm</code> entries</td><td> </td><td>
+ Defined in http://developer.apple.com/documentation/mac/Devices/Devices-126.html.
+ Also note that for FAT file systems, it appears that "DOS_FAT_32", "DOS_FAT_16"
+ and "DOS_FAT_12" are also recognized under Mac OS X (I've tested this too) cf.
+ http://lists.apple.com/archives/Darwin-drivers/2003/May/msg00021.html
+ </td></tr><tr><td>
+ <code class="literal">volume.partition.flags</code> (strlist)
+ </td><td> </td><td>
+ If, and only if, <code class="literal">volume.is_partition</code>
+ is set to <code class="literal">TRUE</code>.
+ </td><td>
+ Flags conveying specific information about the partition
+ entry. Dependent on the partitioning scheme.
+ </td></tr><tr><td> </td><td><code class="literal">mbr</code> and <code class="literal">embr</code> entries</td><td> </td><td>
+ Only one flag, "boot", is defined. This is used by some BIOS'es and
+ boot loaders to populate a boot menu. It means that a partition is
+ bootable.
+ </td></tr><tr><td> </td><td><code class="literal">gpt</code> entries</td><td> </td><td>
+ Only the flag "required" is recognized. This corresponds to
+ bit 0 of the attibutes (at offset 48), meaning
+ "Required for the platform to function. The system cannot
+ function normally if this partition is removed. This
+ partition should be considered as part of the hardware of the
+ system, and if it is removed the system may not boot. It may
+ contain diagnostics, recovery tools, or other code or data that is
+ critical to the functioning of a system independent of any OS."
+ </td></tr><tr><td> </td><td><code class="literal">apm</code> entries</td><td> </td><td>
+ The following flags are recognized:
+ "allocated" if the partition is already allocated; and
+ "in_use" if the partition is in use; may be cleared after a system reset; and
+ "boot" if partition contains valid boot information; and
+ "allow_read" if partition allows reading; and
+ "allow_write"; if partition allows writing; and
+ "boot_code_is_pic"; if boot code is position independent
+ </td></tr><tr><td>
+ <code class="literal">volume.partition.media_size</code> (uint64)
+ </td><td>example: 500107862016</td><td>
+ If, and only if, <code class="literal">volume.is_partition</code>
+ is set to <code class="literal">TRUE</code>.
+ </td><td>
+ If available, size of the current media or the fixed disk in the storage device.
+ </td></tr><tr><td>
+ <code class="literal">volume.partition.start</code> (uint64)
+ </td><td>example: 32256</td><td>
+ If, and only if, <code class="literal">volume.is_partition</code>
+ is set to <code class="literal">TRUE</code>.
+ </td><td>
+ If available, the offset where the partition starts on the media or the fixed disk in the storage device.
+ </td></tr></tbody></table></div><p>
+ Device objects with this capability may emit the following
+ device conditions
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Condition Name</th><th>Parameters</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">VolumeMount</code>
+ </td><td>
+ <code class="literal">block.device</code> (string),
+ <code class="literal">volume.mount_point</code> (string)
+ </td><td>
+ <code class="literal">/dev/sda1</code>,
+ <code class="literal">/media/compact_flash</code>
+ </td><td>Emitted when a volume is mounted</td></tr><tr><td>
+ <code class="literal">VolumeUnmount</code>
+ </td><td>
+ <code class="literal">block.device</code> (string),
+ <code class="literal">volume.mount_point</code> (string)
+ </td><td>
+ <code class="literal">/dev/sda1</code>,
+ <code class="literal">/media/compact_flash</code>
+ </td><td>Emitted when a volume is unmounted</td></tr><tr><td>
+ <code class="literal">VolumeUnmountForced</code>
+ </td><td>
+ <code class="literal">block.device</code> (string),
+ <code class="literal">volume.mount_point</code> (string)
+ </td><td>
+ <code class="literal">/dev/sda1</code>,
+ <code class="literal">/media/compact_flash</code>
+ </td><td>
+ Emitted when a volume is forcibly unmounted because
+ the media backing the volume was removed.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-volume-disc"></a>
+ volume.disc namespace
+ </h3></div></div></div><p>
+ This namespace is for device objects that represent optical
+ discs, e.g. device objects with the capability
+ <code class="literal">volume.disc</code>. Such device objects will
+ also have the capability <code class="literal">volume</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">volume.disc.has_audio</code> (bool)
+ </td><td> </td><td>Yes</td><td>Is true only if the disc contains audio</td></tr><tr><td>
+ <code class="literal">volume.disc.has_data</code> (bool)
+ </td><td> </td><td>Yes</td><td>Is true only if the disc contains data</td></tr><tr><td>
+ <code class="literal">volume.disc.is_vcd</code> (bool)
+ </td><td> </td><td>Yes</td><td>Is true only if the disc is a Video CD</td></tr><tr><td>
+ <code class="literal">volume.disc.is_svcd</code> (bool)
+ </td><td> </td><td>Yes</td><td>Is true only if the disc is a Super Video CD</td></tr><tr><td>
+ <code class="literal">volume.disc.is_videodvd</code> (bool)
+ </td><td> </td><td>Yes</td><td>Is true only if the disc is a Video DVD</td></tr><tr><td>
+ <code class="literal">volume.disc.is_appendable</code> (bool)
+ </td><td> </td><td>Yes</td><td>Is true only if it's possible to write additional data</td></tr><tr><td>
+ <code class="literal">volume.disc.is_blank</code> (bool)
+ </td><td> </td><td>Yes</td><td>Is true only if the disc is blank</td></tr><tr><td>
+ <code class="literal">volume.disc.is_rewritable</code> (bool)
+ </td><td> </td><td>Yes</td><td>Is true only if the disc is rewritable</td></tr><tr><td>
+ <code class="literal">volume.disc.capacity</code> (uint64)
+ </td><td> </td><td>No</td><td>Capacity of disc, in bytes</td></tr><tr><td>
+ <code class="literal">volume.disc.type</code> (string)
+ </td><td> </td><td>Yes</td><td>This property specifies the physical type of the disc</td></tr><tr><td> </td><td>cd_rom</td><td> </td><td>CD-ROM disc</td></tr><tr><td> </td><td>cd_r</td><td> </td><td>CD-R disc</td></tr><tr><td> </td><td>cd_rw</td><td> </td><td>CD-RW disc</td></tr><tr><td> </td><td>dvd_rom</td><td> </td><td>DVD-ROM disc</td></tr><tr><td> </td><td>dvd_ram</td><td> </td><td>DVD-RAM disc</td></tr><tr><td> </td><td>dvd_r</td><td> </td><td>DVD-R disc</td></tr><tr><td> </td><td>dvd_rw</td><td> </td><td>DVD-RW disc</td></tr><tr><td> </td><td>dvd_plus_r</td><td> </td><td>DVD+R disc</td></tr><tr><td> </td><td>dvd_plus_rw</td><td> </td><td>DVD+RW disc</td></tr><tr><td> </td><td>bd_rom</td><td> </td><td>BD-ROM disc</td></tr><tr><td> </td><td>bd_r</td><td> </td><td>BD-R disc</td></tr><tr><td> </td><td>bd_re</td><td> </td><td>BD-RE disc</td></tr><tr><td> </td><td>hddvd_rom</td><td> </td><td>HD DVD-ROM disc</td></tr><tr><td> </td><td>hddvd_r</td><td> </td><td>HD DVD-R disc</td></tr><tr><td> </td><td>hddvd_rw</td><td> </td><td>HD DVD-Rewritable disc</td></tr><tr><td> </td><td>unknown</td><td> </td><td>Unknown type or lack of support from drive to determine the type</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-storage"></a>
+ storage namespace
+ </h3></div></div></div><p>
+ This namespace is used to describe storage devices
+ and their capabilities. Such device objects will have the
+ capability <code class="literal">storage</code> and
+ they will export the properties below. Note that device
+ objects can only have the <code class="literal">storage</code> capability
+ if they already got capability <code class="literal">block</code> and the
+ property <code class="literal">block.is_volume</code> set to FALSE.
+ One significant between the <code class="literal">storage</code> and
+ <code class="literal">block</code> namespace is that the properties
+ exported in the <code class="literal">storage</code> represents
+ constant vital product information, whereas the properties
+ in the <code class="literal">block</code> namespace represent
+ variable system-dependent information.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">storage.bus</code> (string)
+ </td><td> </td><td>Yes</td><td>Interface the storage device is attached to</td></tr><tr><td> </td><td>ide</td><td> </td><td>IDE or ATA interface</td></tr><tr><td> </td><td>usb</td><td> </td><td>USB interface</td></tr><tr><td> </td><td>ieee1394</td><td> </td><td>IEEE 1394 interface</td></tr><tr><td> </td><td>scsi</td><td> </td><td>SCSI interface</td></tr><tr><td> </td><td>sata</td><td> </td><td>SATA interface</td></tr><tr><td> </td><td>platform</td><td> </td><td>Legacy device that is part of the platform</td></tr><tr><td> </td><td>linux_raid</td><td> </td><td>Linux MD (multi disk) RAID device</td></tr><tr><td> </td><td> </td><td> </td><td> </td></tr><tr><td>
+ <code class="literal">storage.drive_type</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ The type of the drive. Note that it may not be
+ possible to probe for some of these properties so in
+ some cases memory card readers may appear as
+ harddisks. Device information files can be used to
+ override this value.
+ </td></tr><tr><td> </td><td>disk</td><td> </td><td>The device is a harddisk</td></tr><tr><td> </td><td>cdrom</td><td> </td><td>
+ The device is an optical drive. The device object will also have the capability <code class="literal">storage.cdrom</code> in this case.
+ </td></tr><tr><td> </td><td>floppy</td><td> </td><td>The device is a floppy disk drive</td></tr><tr><td> </td><td>tape</td><td> </td><td>The device is a tape drive</td></tr><tr><td> </td><td>compact_flash</td><td> </td><td>The device is a card reader for Compact Flash memory cards</td></tr><tr><td> </td><td>memory_stick</td><td> </td><td>The device is a card reader for MemoryStick memory cards</td></tr><tr><td> </td><td>smart_media</td><td> </td><td>The device is a card reader for SmartMedia memory cards</td></tr><tr><td> </td><td>sd_mmc</td><td> </td><td>The device is a card reader for SecureDigital/MultiMediaCard memory cards</td></tr><tr><td> </td><td> </td><td> </td><td> </td></tr><tr><td>
+ <code class="literal">storage.removable</code> (bool)
+ </td><td> </td><td>Yes</td><td>Media can be removed from the storage device</td></tr><tr><td>
+ <code class="literal">storage.removable.media_available</code> (bool)
+ </td><td> </td><td>Yes</td><td>true, if and only if, media have been detected in storage device</td></tr><tr><td>
+ <code class="literal">storage.removable.media_size</code> (uint64)
+ </td><td> </td><td>Yes</td><td>Size of media in storage device. Available only if media have been detected in storage device.</td></tr><tr><td>
+ <code class="literal">storage.removable.support_async_notification</code> (bool)
+ </td><td> </td><td>Yes</td><td>Whether the drive reports asynchronous notification for media change.</td></tr><tr><td>
+ <code class="literal">storage.partitioning_scheme</code> (string)
+ </td><td> </td><td>Only when media is inserted and is partitioned</td><td>The partitioning scheme of the media.</td></tr><tr><td> </td><td>mbr</td><td> </td><td>Master Boot Record partitioning scheme used in most PC's</td></tr><tr><td> </td><td>gpt</td><td> </td><td>GUID Partitioning Table as defined by UEFI</td></tr><tr><td> </td><td>apm</td><td> </td><td>Apple Partition Map, used in non-Intel Apple computers</td></tr><tr><td>
+ <code class="literal">storage.size</code> (uint64)
+ </td><td> </td><td>No</td><td>size in bytes of the storage device - only meaningful if storage.removable is FALSE</td></tr><tr><td>
+ <code class="literal">storage.requires_eject</code> (bool)
+ </td><td> </td><td>Yes</td><td>The eject ioctl is required to properly eject the media</td></tr><tr><td>
+ <code class="literal">storage.hotpluggable</code> (bool)
+ </td><td> </td><td>Yes</td><td>The storage device can be removed while the system is running</td></tr><tr><td>
+ <code class="literal">storage.media_check_enabled</code> (bool)
+ </td><td> </td><td>Yes</td><td>If this property is set to FALSE then HAL will not continuosly poll for media changes. </td></tr><tr><td>
+ <code class="literal">storage.automount_enabled_hint</code> (bool)
+ </td><td> </td><td>Yes</td><td>This property is a hint to desktop file managers that they shouldn't automount volumes of the storage device when they appear.</td></tr><tr><td>
+ <code class="literal">storage.no_partitions_hint</code> (bool)
+ </td><td> </td><td>Yes</td><td>
+ This property is a hint to programs that maintain the
+ <code class="literal">/etc/fstab</code> file to signal, when
+ TRUE, that the storage drive (such as floppy or
+ optical drives) is used for media with no partition
+ table so an entry can be added ahead of media
+ insertion time. Note that this is only a hint; media
+ may be inserted that has partition tables that the
+ kernel may respect. Conversely, when this is FALSE
+ media without partition tables may be inserted (an
+ example is a Compact Flash card; this media is normally
+ formatted with a PC style partition table and a single
+ FAT partition. However, it may be formatted with just
+ a single FAT partition and no partition table).
+ </td></tr><tr><td>
+ <code class="literal">storage.originating_device</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ This contains the UDI of the device object
+ representing the device or blank if
+ there is no such device.
+ </td></tr><tr><td>
+ <code class="literal">storage.model</code> (string)
+ </td><td> </td><td>Yes</td><td>The name of the drive</td></tr><tr><td>
+ <code class="literal">storage.vendor</code> (string)
+ </td><td> </td><td>Yes</td><td>The vendor of the drive</td></tr><tr><td>
+ <code class="literal">storage.serial</code> (string)
+ </td><td> </td><td>No</td><td>The serial number of the drive</td></tr><tr><td>
+ <code class="literal">storage.firmware_revision</code> (string)
+ </td><td> </td><td>No</td><td>The revision of the firmware of the drive</td></tr><tr><td>
+ <code class="literal">storage.icon.drive</code> (string)
+ </td><td> </td><td>No</td><td>
+ Name of icon to use for displaying the drive. The name
+ must comply with freedesktop.org icon-theme specification
+ and must not be an absolute path.
+ This property exists such that e.g. OEM's can install
+ icons in <code class="literal">/usr/share/icons/hicolor</code>
+ a device information file matching their device.
+ </td></tr><tr><td>
+ <code class="literal">storage.icon.volume</code> (string)
+ </td><td> </td><td>No</td><td>
+ Name of icon to use for displaying volumes from the drive.
+ The name must comply with freedesktop.org icon-theme
+ specification and must not be an absolute path.
+ This property exists such that e.g. OEM's can install
+ icons in <code class="literal">/usr/share/icons/hicolor</code>
+ a device information file matching their device.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-storage-cdrom"></a>
+ storage.cdrom namespace
+ </h3></div></div></div><p>
+ This namespace is used to describe optical storage drives
+ and their capabilities.Such device objects will have the
+ capability <code class="literal">storage.cdrom</code> and
+ they will export the properties below. Note that device
+ objects can only have the <code class="literal">storage.cdrom</code> capability
+ if they already got the capability <code class="literal">storage</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">storage.cdrom.cdr</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write CD-R discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.cdrw</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can blank and write to CD-RW discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.dvd</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can read DVD-ROM discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.dvdr</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write to DVD-R discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.dvdrw</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can blank and write to DVD-RW discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.dvdram</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write to DVD-RAM discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.dvdplusr</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write to DVD+R discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.dvdplusrw</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can blank and write to DVD+RW discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.dvdplusrwdl</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can blank and write to DVD+RW Dual-Layer discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.dvdplusrdl</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write to DVD+R Dual-Layer discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.bd</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can read Blu-ray ROM discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.bdr</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write to Blu-ray Recordable discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.bdre</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write to Blu-ray Rewritable discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.hddvd</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can read Read-only HD DVD discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.hddvdr</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write to Write-once HD DVD discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.hddvdrw</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write to Rewritable HD DVD discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.mrw</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can read MRW (Mount Rainier Rewrite) discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.mrw_w</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE when the optical drive can write MRW (Mount Rainier Rewrite) discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.mo</code> (bool)
+ </td><td> </td><td>No</td><td>TRUE when the optical drive is a MO (Magneto Optical) device.</td></tr><tr><td>
+ <code class="literal">storage.cdrom.support_multisession</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE if the drive can read multisession discs</td></tr><tr><td>
+ <code class="literal">storage.cdrom.support_media_changed</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE if the drive can generate media changed events</td></tr><tr><td>
+ <code class="literal">storage.cdrom.read_speed</code> (int)
+ </td><td> </td><td>Yes</td><td>The maximum reading speed, in kb/s</td></tr><tr><td>
+ <code class="literal">storage.cdrom.write_speed</code> (int)
+ </td><td> </td><td>Yes</td><td>The maximum writing speed, in kb/s</td></tr><tr><td>
+ <code class="literal">storage.cdrom.write_speeds</code> (strlist)
+ </td><td> </td><td>No</td><td>By the device supported write speeds in kb/s</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-storage-linux-raid"></a>
+ storage.linux_raid namespace
+ </h3></div></div></div><p>
+ This namespace is used to describe logical Software RAID
+ devices under Linux using the <code class="literal">md</code> driver. By
+ and large, all the same properties under
+ the <code class="literal">storage</code> name space applies except
+ that <code class="literal">storage.serial</code> is set to the UUID of
+ the RAID set, <code class="literal">storage.firmware_version</code> is
+ set to the version of the <code class="literal">md</code> driver and the
+ value of <code class="literal">storage.hotpluggable</code> is taken from
+ the enclosing drive of the first RAID component
+ encountered. In addition, the following properties are
+ available.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">storage.linux_raid.level</code> (string)
+ </td><td> </td><td>Yes</td><td>the RAID level of the device as reported by the kernel (linear, raid0, raid1, raid4, raid5, raid6, raid10)</td></tr><tr><td>
+ <code class="literal">storage.linux_raid.sysfs_path</code> (string)
+ </td><td> </td><td>Yes</td><td>sysfs path of device, e.g. /sys/block/md0</td></tr><tr><td>
+ <code class="literal">storage.linux_raid.num_components</code> (int)
+ </td><td> </td><td>Yes</td><td>Number of components in the RAID array</td></tr><tr><td>
+ <code class="literal">storage.linux_raid.num_components_active</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ Number of active components in the RAID array. If less
+ than <code class="literal">storage.linux_raid.num_components</code>
+ it means that the RAID array is running in degraded
+ mode.
+ </td></tr><tr><td>
+ <code class="literal">storage.linux_raid.components</code> (strlist)
+ </td><td> </td><td>Yes</td><td>UDI's of the volumes constituting the array.</td></tr><tr><td>
+ <code class="literal">storage.linux_raid.is_syncing</code> (bool)
+ </td><td> </td><td>Yes</td><td>TRUE if, and only if, the array is currently syncing</td></tr><tr><td>
+ <code class="literal">storage.linux_raid.sync.action</code> (string)
+ </td><td> </td><td>only if <code class="literal">.is_syncing</code> is TRUE</td><td>The syncing mechanism as reported by the kernel (idle, resync, check, repair, recover)</td></tr><tr><td>
+ <code class="literal">storage.linux_raid.sync.progress</code> (double)
+ </td><td> </td><td>only if <code class="literal">.is_syncing</code> is TRUE</td><td>Number between 0 and 1 representing progress of the sync operation. This is updated regulary when syncing is happening.</td></tr><tr><td>
+ <code class="literal">storage.linux_raid.sync.speed</code> (uint64)
+ </td><td> </td><td>only if <code class="literal">.is_syncing</code> is TRUE</td><td>Speed of the sync operation, in kB/s. This is updated regulary when syncing is happening.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-net"></a>
+ net namespace
+ </h3></div></div></div><p>
+ This namespace is used to describe networking devices and
+ their capabilities.Such device objects will have the
+ capability <code class="literal">net</code> and they will export the
+ properties below. This namespace only describe the generic
+ aspect of networking devices; specific networking technologies
+ such as IEEE 802.3, IEEE 802.11 and Bluetooth have separate
+ namespaces.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">net.address</code> (string)
+ </td><td> </td><td>Yes</td><td>Hardware address as a string. Is hardware dependant</td></tr><tr><td>
+ <code class="literal">net.arp_proto_hw_id</code> (string)
+ </td><td> </td><td>Yes</td><td>ARP protocol hardware identifier</td></tr><tr><td>
+ <code class="literal">net.interface</code> (string)
+ </td><td> </td><td>Yes</td><td>Name of the interface; may change if an interface is
+ renamed
+ </td></tr><tr><td>
+ <code class="literal">net.interface_up</code> (bool)
+ </td><td> </td><td>No</td><td>Whether the interface is up</td></tr><tr><td>
+ <code class="literal">net.linux.ifindex</code> (string)
+ </td><td> </td><td>Yes (only on Linux)</td><td>Index of the interface</td></tr><tr><td>
+ <code class="literal">net.originating_device</code> (string)
+ </td><td> </td><td>Yes</td><td>UDI of the device the network device is bound to.</td></tr><tr><td>
+ <code class="literal">net.media</code> (string)
+ </td><td>example: Ethernet</td><td>Yes</td><td>Textual description of the networking media</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-net-80203"></a>
+ net.80203 namespace
+ </h3></div></div></div><p>
+ Ethernet networking devices is described in this namespace
+ for device objects with the capability
+ <code class="literal">net.80203</code>.
+ Note that device
+ objects can only have the <code class="literal">net.80203</code> capability
+ if they already have the capability <code class="literal">net</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">net.80203.link</code> (bool)
+ </td><td> </td><td>
+ Only if the <code class="literal">net.80203</code> capability is set
+ and <code class="literal">net.interface_up</code> is
+ <code class="literal">TRUE</code>.
+ </td><td>True if the ethernet adaptor is connected to a
+ another transceiver. NOTE: property not implemented yet.
+ </td></tr><tr><td>
+ <code class="literal">net.80203.rate</code> (uint64)
+ </td><td>example: 100000000</td><td>
+ Only if the <code class="literal">net.80203</code> capability is set
+ and <code class="literal">net.80203.link</code> is
+ <code class="literal">TRUE</code>.
+ </td><td>Bandwidth of connection, in bits/s. NOTE: property not
+ implemented yet.
+ </td></tr><tr><td>
+ <code class="literal">net.80203.mac_address</code> (uint64)
+ </td><td>example: 0x0010605d8ef4</td><td>
+ Only if the <code class="literal">net.80203</code> is set
+ </td><td>48-bit address</td></tr></tbody></table></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-net-80211"></a>
+ net.80211 namespace
+ </h3></div></div></div><p>
+ Wireless ethernet networking devices is described in this namespace
+ for device objects with the capability
+ <code class="literal">net.80211</code>.
+ Note that device
+ objects can only have the <code class="literal">net.80211</code> capability
+ if they already have the capability <code class="literal">net</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">net.80211.mac_address</code> (uint64)
+ </td><td>example: 0x0010605d8ef4</td><td>
+ Only if the <code class="literal">net.80211</code> capability is set
+ </td><td>48-bit address</td></tr></tbody></table></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-net-bluetooth"></a>
+ net.bluetooth namespace
+ </h3></div></div></div><p>
+ Bluetooth ethernet networking devices is described in this namespace
+ for device objects with the capability
+ <code class="literal">net.bluetooth</code>.
+ Note that device
+ objects can only have the <code class="literal">net.bluetooth</code> capability
+ if they already have the capability <code class="literal">net</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">net.bluetooth.mac_address</code> (uint64)
+ </td><td>example: 0x0010605d8ef4</td><td>
+ Only if the <code class="literal">net.bluetooth</code> capability is set
+ </td><td>48-bit address</td></tr><tr><td>
+ <code class="literal">net.bluetooth.name</code> (string)
+ </td><td>example: Network Access Point Service</td><td>
+ Only if the <code class="literal">net.bluetooth</code> capability is set and Bluez is being used.
+ </td><td>Displayable Name for network connection</td></tr><tr><td>
+ <code class="literal">net.bluetooth.uuid</code> (string)
+ </td><td>example: 00001116-0000-1000-8000-00805f9b34fb</td><td>
+ Only if the <code class="literal">net.bluetooth</code> capability is set and Bluez is being used.
+ </td><td>Universal Unique Identifier for network connection</td></tr></tbody></table></div><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-net-irda"></a>
+ net.irda namespace
+ </h3></div></div></div><p>
+ IrDA (Infrared Data Association) Networking devices are described in
+ this namespace for device objects with the capability
+ <code class="literal">net.irda</code>.
+ Note that device objects can only have the <code class="literal">net.irda</code>
+ capability if they already have the capability <code class="literal">net</code>.
+ </p><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-net-80211control"></a>
+ net.80211control namespace
+ </h3></div></div></div><p>
+ Control devices for Wireless ethernet networking devices are described in
+ this namespace for device objects with the capability
+ <code class="literal">net.80211control</code>.
+ Note that device objects can only have the <code class="literal">net.80211control</code>
+ capability if they already have the capability <code class="literal">net</code>.
+ Warning: You should know what you do if you touch this devices. They are
+ not always stable and can cause (kernel) crashes (on linux).
+ </p><p>
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input"></a>
+ input namespace
+ </h3></div></div></div><p>
+ This namespace is concerned with human input devices such as
+ keyboards, mice, pointing devices and game controllers. If a
+ device object has the capability <code class="literal">input</code> then
+ the following properties are available
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">input.device</code> (string)
+ </td><td> </td><td>Yes</td><td>Special device file for recieving input events</td></tr><tr><td>
+ <code class="literal">input.x11_driver</code> (string)
+ </td><td>e.g. "evdev"</td><td>No</td><td>X11 input driver to use</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input-keys"></a>
+ input.keys namespace
+ </h3></div></div></div><p>
+ The input device have keys that can be pressed. No namespace
+ specific properties.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input-keypad"></a>
+ input.keypad namespace
+ </h3></div></div></div><p>
+ The input device have keypad keys. No namespace
+ specific properties.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input-keyboard"></a>
+ input.keyboard namespace
+ </h3></div></div></div><p>
+ The input device is a normal keyboard. No namespace specific
+ properties.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input-mouse"></a>
+ input.mouse namespace
+ </h3></div></div></div><p>
+ The input device is a mouse. No namespace specific
+ properties.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input-switch"></a>
+ input.switch namespace
+ </h3></div></div></div><p>
+ The input device is a switch, e.g. it has buttons with
+ state. No namespace specific properties.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input-joystick"></a>
+ input.joystick namespace
+ </h3></div></div></div><p>
+ The input device is a joystick. No namespace specific
+ properties.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input-tablet"></a>
+ input.tablet namespace
+ </h3></div></div></div><p>
+ The input device is a tablet. No namespace specific
+ properties.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input-keymap"></a>
+ input.keymap namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">input.keymap</code>
+ provide facilities to remap keyboard buttons.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">input.keymap.data</code> (strlist)
+ </td><td>e.g. "e017:brightnessup"</td><td>No</td><td>
+ The scancode is represented in hex and the keycode name as
+ as string. The keycode name is not case sensitive.
+ On Linux, the keycode name should be the same constant as
+ present in /usr/include/linux/input.h with the 'KEY_'
+ prefix removed, e.g. 'KEY_SLEEP' -> 'sleep'.
+ You can append as many <code class="literal">input.keymap.data</code>
+ values as there are keys to remap.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-input-xkb"></a>
+ input.xkb namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">input.keys</code>
+ can provide information about their physical layout.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">input.xkb.rules</code> (string)
+ </td><td>e.g. "base"</td><td>Yes</td><td>
+ XKB rules file to use; 'base' is standard, but 'xorg'
+ or 'xfree86' may be needed for backwards compatibility
+ with very old versions of XKB data.
+ </td></tr><tr><td>
+ <code class="literal">input.xkb.model</code> (string)
+ </td><td>e.g. "logicdp"</td><td>Yes</td><td>
+ Physical keyboard model (e.g. Logitech Cordless Freedom
+ Pro), as given to XKB.
+ </td></tr><tr><td>
+ <code class="literal">input.xkb.layout</code> (string)
+ </td><td>e.g. "us"</td><td>Yes</td><td>
+ Keyboard layout (as engraved on the keys).
+ </td></tr><tr><td>
+ <code class="literal">input.xkb.variant</code> (string)
+ </td><td>e.g. "nodeadkeys"</td><td>No</td><td>
+ Variant of the XKB layout (if any) to use.
+ </td></tr><tr><td>
+ <code class="literal">input.xkb.options</code> (strlist)
+ </td><td>e.g. "ctrl:nocaps"</td><td>No</td><td>
+ Options to be provided to XKB.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-pcmcia_socket"></a>
+ pcmcia_socket namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">pcmcia_socket</code>
+ represent bridge devices (the actual bus of the device may differ)
+ that PCMCIA cards can be attached to. The following properties are
+ available.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">pcmcia_socket.number</code> (int)
+ </td><td> </td><td>Yes</td><td>PCMCIA socket number, starting from zero</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-printer"></a>
+ printer namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">printer</code>
+ represent printers. The following properties are available.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">printer.device</code> (string)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">printer.vendor</code> (string)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">printer.product</code> (string)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">printer.serial</code> (string)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">printer.description</code> (string)
+ </td><td> </td><td>Yes</td><td>TODO</td></tr><tr><td>
+ <code class="literal">printer.commandset</code> (strlist)
+ </td><td> </td><td>No</td><td>List of supported commands / printer languages.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-portable_audio_player"></a>
+ portable_audio_player namespace
+ </h3></div></div></div><p>
+ Device objects with the capability
+ <code class="literal">portable_audio_player</code> represent portable
+ audio players that can be attached to a computer to exchange
+ files. They can also playback audio. Sometimes they can also
+ record audio. This capability can't, in general, be reliably
+ probed from the hardware so the information needs to be merged
+ from either device information files or callouts. Therefore
+ this capability should be merged on the appropriate device
+ object that represents the addressable piece of hardware that
+ is the portable music player; for USB devices this would be
+ the device object representing the appropriate USB
+ interface. The following properties are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">portable_audio_player.access_method.protocols</code> (strlist)
+ </td><td>example: storage ipod mtp pde iriver karma</td><td>No</td><td>
+ Indicates transfer protocols that this device can speak.
+ <code class="literal">storage</code> indicates USB Mass Storage (UMS) is an access
+ protocol. <code class="literal">ipod</code> indicates UMS plus an iTunes-style database.
+ <code class="literal">mtp</code> indicates a device using Microsoft's Media Transfer Protocol.
+ Arbitrary values for newer or obscure protocols are allowed but
+ entities providing this information should try to ensure that
+ they are not duplicating protocols under a different name.
+ </td></tr><tr><td>
+ <code class="literal">portable_audio_player.access_method.drivers</code> (strlist)
+ </td><td>example: libgpod, libmtp, libnjb, libifp, libkarma</td><td>No</td><td>
+ Indicates installed device driver libraries that can
+ handle this device. These drivers can export information
+ in <code class="literal">portable_audio_player.[drivername]</code> sub-namespaces.
+ Can also be used by libraries or programs providing extra device information
+ to indicate the presence of this information in the appropriate sub-namespace.
+ </td></tr><tr><td>
+ <code class="literal">portable_audio_player.[drivername].protocol</code> (strlist)
+ </td><td>example: mtp</td><td>Yes</td><td>
+ This entry is required for drivers listed in
+ <code class="literal">portable_audio_player.access_method.drivers</code>. Indicates which
+ protocol in <code class="literal">portable_audio_player.access_method.protocols</code>
+ a particular driver will use. If the driver is providing information only, this
+ should be set to <code class="literal">information</code>.
+ </td></tr><tr><td>
+ <code class="literal">portable_audio_player.output_formats</code> (strlist)
+ </td><td>example: audio/mpeg audio/x-ms-wma</td><td>Yes</td><td>
+ A string list of MIME-types representing the kind of audio
+ formats that the device can play back.
+ </td></tr><tr><td>
+ <code class="literal">portable_audio_player.input_formats</code> (strlist)
+ </td><td>example: audio/x-wav</td><td>Yes</td><td>
+ A string list of MIME-types representing the kind of audio
+ formats that the device can record. If empty, it means that
+ the device is not capable of recording.
+ </td></tr><tr><td>
+ <code class="literal">portable_audio_player.folder_depth </code> (int)
+ </td><td>example: 1 (If the device only supports one sub-folder)</td><td>No</td><td>
+ If portable_audio_player.access_method.protocols contains "storage",
+ this tells applications exactly how deep of directory hierarchies
+ files should be placed in. If all files are put in a
+ sub-folder (with the audio_folders property), only the depth within
+ that sub-folder should be entered here. If the device does not have
+ a limit, do not set this property.
+ </td></tr><tr><td>
+ <code class="literal">portable_audio_player.audio_folders</code> (strlist)
+ </td><td>example: music/ voice/ linein/</td><td>No</td><td>
+ If portable_audio_player.access_method.protocols contains "storage",
+ this may contain a string list of folders in which music
+ can be found. Paths are relative to the mount point of the
+ device. If there is one or more entry in this property, the
+ first one is where files will be written to by applications.
+ Do not enter a folder and a parent of that folder.
+ If the device places files in its root directory, then do not
+ set this property.
+ </td></tr><tr><td>
+ <code class="literal">portable_audio_player.playlist_format</code> (strlist)
+ </td><td>example: audio/x-mpegurl audio/x-somethingelse</td><td>No</td><td>
+ A string list of the MIME-type of the playlist formats accepted by
+ this device. Leave blank if none.
+ </td></tr><tr><td>
+ <code class="literal">portable_audio_player.playlist_path</code> (string)
+ </td><td>examples: playlists/%File or Playlist.m3u</td><td>No</td><td>
+ Set to the path to which playlists should be written. Leave
+ blank if playlist files are not supported. If the device supports a single playlist with a specific name/path,
+ set this to the path relative to the mount point that it should be saved to. If it supports multiple
+ playlists, use the %File variable as needed. Applications are responsible for substituting %File with the
+ desired playlist file name, noting that it's use in this string is optional.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-alsa"></a>
+ alsa namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">alsa</code>
+ represent all the streams available through ALSA on a soundcard.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">alsa.card</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ Card number in system as registered by ALSA.
+ </td></tr><tr><td>
+ <code class="literal">alsa.card_id</code> (string)
+ </td><td>
+ Examples: <code class="literal">I82801DBICH4</code>, <code class="literal">MP3</code>
+ </td><td>No</td><td>
+ Textual description of the card.
+ </td></tr><tr><td>
+ <code class="literal">alsa.device</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ Device number assigned by ALSA for a current card.
+ </td></tr><tr><td>
+ <code class="literal">alsa.device_file</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ The device node to access the ALSA device.
+ </td></tr><tr><td>
+ <code class="literal">alsa.device_id</code> (string)
+ </td><td>
+ Examples: <code class="literal">Intel 82801DB-ICH4 MIC2 ADC</code>
+ </td><td>No</td><td>
+ Textual description of the specific device for a card
+ </td></tr><tr><td>
+ <code class="literal">alsa.device_pcm_class</code> (string)
+ </td><td> </td><td>No</td><td>
+ The PCM class of the device.
+ </td></tr><tr><td> </td><td>generic</td><td> </td><td>
+ A standard PCM sound device (SND_PCM_CLASS_GENERIC).
+ </td></tr><tr><td> </td><td>multi</td><td> </td><td>
+ A multichannel device PCM sound device (SND_PCM_CLASS_MULTI) which
+ e.g. contains a generic and a modem device.
+ </td></tr><tr><td> </td><td>digitizer</td><td> </td><td>
+ A PCM digitizer device (SND_PCM_CLASS_DIGITIZER).
+ </td></tr><tr><td> </td><td>modem</td><td> </td><td>
+ A PCM modem device (SND_PCM_CLASS_MODEM).
+ </td></tr><tr><td> </td><td>unknown</td><td> </td><td>
+ The value is 'unknown' if the kernel provide no information about the
+ PCM device class of the device (e.g. the file pcm_class is missing).
+ </td></tr><tr><td> </td><td>none</td><td> </td><td>
+ The value is 'none' if this there is no PCM class for this device.
+ </td></tr><tr><td>
+ <code class="literal">alsa.originating_device</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ UDI of the device the ALSA device is bound to.
+ </td></tr><tr><td>
+ <code class="literal">alsa.type</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ The type of the stream.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">control</code>
+ </td><td> </td><td>
+ Stream is control device.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">capture</code>
+ </td><td> </td><td>
+ Stream is capture device.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">midi</code>
+ </td><td> </td><td>
+ Stream is MIDI device.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">playback</code>
+ </td><td> </td><td>
+ Stream is playback device.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">unknown</code>
+ </td><td> </td><td>
+ The type of the device is unknown.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">hw_specific</code>
+ </td><td> </td><td>
+ This is a hardware specific device (as e.g. from snd_fm801 for Fortemedia FM801
+ PCI Audio). The driver can use it freely for purposes that are not covered by
+ standard ALSA API.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">timer</code>
+ </td><td> </td><td>
+ Stream is the global ALSA timer device.
+ This means, the device is for all ALSA devices/cards.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">sequencer</code>
+ </td><td> </td><td>
+ Stream is the global ALSA sequencer device.
+ This means, the device is for all ALSA devices/cards.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">unknown</code>
+ </td><td> </td><td>
+ Stream is unknown device.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-oss"></a>
+ oss namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">oss</code>
+ represent all the streams available through OSS on a soundcard.
+ OSS devices could be emulated by ALSA.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">oss.card</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ Card number in system as registered by OSS (and/or ALSA).
+ </td></tr><tr><td>
+ <code class="literal">oss.card_id</code> (string)
+ </td><td>
+ Examples: <code class="literal">I82801DBICH4</code>, <code class="literal">MP3</code>
+ </td><td>No</td><td>
+ Textual description of the card.
+ </td></tr><tr><td>
+ <code class="literal">oss.device</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ Device number assigned by OSS/ALSA for a current card.
+ </td></tr><tr><td>
+ <code class="literal">oss.device_file</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ The device node to access the OSS device.
+ </td></tr><tr><td>
+ <code class="literal">oss.device_id</code> (string)
+ </td><td>
+ Examples: <code class="literal">Intel 82801DB-ICH4 MIC2 ADC</code>
+ </td><td>No</td><td>
+ Textual description of the specific device for a card
+ </td></tr><tr><td>
+ <code class="literal">oss.originating_device</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ UDI of the device the OSS device is bound to.
+ </td></tr><tr><td>
+ <code class="literal">oss.type</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ The type of the stream.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">mixer</code>
+ </td><td> </td><td>
+ Stream is control/mixer device.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">pcm</code>
+ </td><td> </td><td>
+ Stream is PCM device.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">midi</code>
+ </td><td> </td><td>
+ Stream is MIDI device.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">sequencer</code>
+ </td><td> </td><td>
+ Stream is a global OSS sequencer device.
+ This means, the device is for all OSS devices/cards.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">unknown</code>
+ </td><td> </td><td>
+ Stream is unknown device.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-camera"></a>
+ camera namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">camera</code>
+ represent digital still cameras that can be attached to a
+ computer to exchange files. This does not include card readers
+ for memory cards used for cameras. This capability can't, in
+ general, be reliably probed from the hardware so the
+ information needs to be merged from either device information
+ files or callouts. Therefore this capability should be merged
+ on the appropriate device object that represents the
+ addressable piece of hardware that is the digital still
+ camera; for USB devices this would be the device object
+ representing the appropriate USB interface. The following
+ properties are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">camera.access_method</code> (string)
+ </td><td> </td><td>Yes</td><td>This property defines how the device is accessed </td></tr><tr><td> </td><td>storage</td><td> </td><td>
+ The device is accessed as a Mass Storage device
+ through a kernel driver. Application Developers
+ should descent down the device object tree to find the
+ device object of capability
+ <code class="literal">storage</code> in order to access the
+ device.
+ </td></tr><tr><td> </td><td>user</td><td> </td><td>
+ The device is accessed from userspace through
+ a userspace driver.
+ </td></tr><tr><td> </td><td> </td><td> </td><td> </td></tr><tr><td>
+ <code class="literal">camera.libgphoto2.support</code> (bool)
+ </td><td> </td><td>No</td><td>
+ If true, the device is supported by a userspace driver
+ from the libgphoto2 project.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-scanner"></a>
+ scanner namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">scanner</code>
+ represent image scanners. This capability should be merged
+ on the appropriate device object that represents the
+ addressable piece of hardware that is the digital still
+ camera; for USB devices this would be the device object
+ representing the appropriate USB interface. The following
+ properties are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">scanner.access_method</code> (string)
+ </td><td> </td><td>Yes</td><td>This property defines how the device is accessed </td></tr><tr><td> </td><td>proprietary</td><td> </td><td>
+ The device is accessed from userspace through
+ a userspace driver such as SANE.
+ </td></tr><tr><td> </td><td> </td><td> </td><td> </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-laptop-panel"></a>
+ laptop_panel namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">laptop_panel</code>
+ represent devices capable of changing the brightness of the display.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">laptop_panel.num_levels</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ The brightness levels supported by the adaptor.
+ </td></tr><tr><td>
+ <code class="literal">laptop_panel.access_method</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ The access method to use in scripts, e.g. pmu, toshiba, ibm, sony.
+ </td></tr><tr><td>
+ <code class="literal">laptop_panel.brightness_in_hardware</code> (bool)
+ </td><td> </td><td>No</td><td>
+ On some laptops, the brightness control is all done in hardware
+ but the hardware also synthesizes keypresses when the
+ brightness is changed.
+ If this key is set true, then any power manager software should
+ not attempt to set any new values on brightness keypress, as it
+ may cause the panel to flash uncontrollably.
+ </td></tr></tbody></table></div><p>
+ The following methods exist on the interface
+ <code class="literal">org.freedesktop.Hal.Device.LaptopPanel</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method (parameter types)</th><th>Parameters</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">SetBrightness</code> (integer)
+ </td><td>
+ The hardware brightness state, which should be between 0 and
+ <code class="literal">laptop_panel.num_levels</code> - 1.
+ </td><td>No</td><td>
+ This method adjusts the brightness on an laptop screen.
+ The values are returned as hardware values rather than
+ percentages as we cannot easily to floating point rounding in
+ shell code and therefore use the raw values to prevent integer
+ rounding errors.
+ </td></tr><tr><td>
+ integer <code class="literal">GetBrightness</code> (void)
+ </td><td>
+ Returns the hardware brightness state, which should be
+ between 0 and <code class="literal">laptop_panel.num_levels</code> - 1.
+ </td><td>No</td><td>
+ This method gets the hardware brightness of the laptop screen,
+ which we may need to do fairly regually on hardware that
+ changes the values in hardware without a software event.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-ac_adapter"></a>
+ ac_adapter namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">ac_adapter</code>
+ represent all the devices capable of powering the system from AC power
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ac_adapter.present</code> (bool)
+ </td><td> </td><td>Yes</td><td>
+ The state of the adapter, i.e. whether it is providing power to
+ the unit from mains power.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-battery"></a>
+ battery namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">battery</code>
+ represent all the devices having some battery (in many cases -
+ rechargeable) inside.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">battery.present</code> (bool)
+ </td><td> </td><td>Yes</td><td>
+ This is present as some smart batteries can have acpi/pmu
+ entries, and be physically missing.
+ </td></tr><tr><td>
+ <code class="literal">battery.type</code> (string)
+ </td><td> </td><td>Yes</td><td>
+ This property defines the type of the device holding the
+ battery. This property is defined for the development
+ simplicity - battery indicators can use it to find the
+ proper iconic representation.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">pda</code>
+ </td><td> </td><td>
+ The device containing the battery is a personal digital
+ assistant, e.g. a device that looks like a handheld computer
+ to do specific tasks such as keeping notes or containing
+ a personal database
+ </td></tr><tr><td> </td><td>
+ <code class="literal">ups</code>
+ </td><td> </td><td>
+ A battery powered power supply that is
+ guaranteed to provide power to a computer in the event of
+ interruptions in the incoming electrical power. Most of the
+ time this is an external device.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">primary</code>
+ </td><td> </td><td>
+ The battery is a primary power source for the system - an
+ example are laptop batteries.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">mouse</code>
+ </td><td> </td><td>
+ The device containing the battery is a mouse.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">keyboard</code>
+ </td><td> </td><td>
+ The device containing the battery is a keyboard.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">keyboard_mouse</code>
+ </td><td> </td><td>
+ The device containing the battery is a combined mouse and keyboard.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">camera</code>
+ </td><td> </td><td>
+ The device containing the battery is a camera.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">usb</code>
+ </td><td> </td><td>
+ The device containing the battery is a generic usb device.
+ </td></tr><tr><td> </td><td>
+ <code class="literal">unknown</code>
+ </td><td> </td><td>
+ The device containing the battery is not covered by other types.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.unit</code> (string)
+ </td><td>Examples:
+ <code class="literal">mWh</code>,
+ <code class="literal">percent</code>
+ </td><td>No</td><td>
+ The physical unit used by the charge level properties
+ (maximum and current). In many cases, this property is
+ omitted - which indicates that the charge properties
+ are measured in some unknown units.
+ The units should never be mAh as this is not a measurement
+ of charge.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.design</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ The maximum level of charge the device was designed for.
+ Measured in <code class="literal">"battery.charge_level.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.last_full</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ The maximum level of charge the device could hold the last
+ time it was full.
+ Measured in <code class="literal">"battery.charge_level.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.current</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ The current level of charge which the device can is holding.
+ Measured in <code class="literal">"battery.charge_level.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.rate</code> (int)
+ </td><td> </td><td>No</td><td>
+ The discharge/charge rate measured
+ in <code class="literal">"battery.charge_level.unit"</code>
+ units per second.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.warning</code> (int)
+ </td><td> </td><td>No</td><td>
+ Once the charge level of the battery drops below this value its
+ state changes to 'warning'.
+ Measured in <code class="literal">"battery.charge_level.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.low</code> (int)
+ </td><td> </td><td>No</td><td>
+ Once the charge level of the battery drops below this value its
+ state changes to 'low'.
+ Measured in <code class="literal">"battery.charge_level.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.granularity_1</code> (int)
+ </td><td> </td><td>No</td><td>
+ Granularity value one of the battery measured
+ in <code class="literal">"battery.charge_level.unit"</code>
+ units .
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.granularity_2</code> (int)
+ </td><td> </td><td>No</td><td>
+ Granularity value two of the battery measured
+ in <code class="literal">"battery.charge_level.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.unit</code> (string)
+ </td><td>Examples:
+ <code class="literal">mWh</code>,
+ <code class="literal">mAh</code>,
+ <code class="literal">percent</code>
+ </td><td>No</td><td>
+ The physical unit used by the charge level properties
+ (maximum and current) as reported by the hardware.
+ In many cases, this property is omitted - which indicates
+ that the charge properties are measured in some unknown units.
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.design</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ The maximum level of charge the device was designed for,
+ as reported by the hardware.
+ Measured in <code class="literal">"battery.reporting.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.last_full</code> (int)
+ </td><td> </td><td>No</td><td>
+ The maximum level of charge the device could hold the last
+ time it was full, as reported by the hardware.
+ Measured in <code class="literal">"battery.reporting.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.current</code> (int)
+ </td><td> </td><td>No</td><td>
+ The current level of charge which the device is holding,
+ as reported by the hardware.
+ Measured in <code class="literal">"battery.reporting.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.rate</code> (int)
+ </td><td> </td><td>No</td><td>
+ The discharge/charge rate as reported by the hardware measured
+ in <code class="literal">"battery.reporting.unit"</code>
+ units per second.
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.warning</code> (int)
+ </td><td> </td><td>No</td><td>
+ Once the hardware charge level of the battery drops below
+ this value its state changes to 'warning'.
+ Measured in <code class="literal">"battery.reporting.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.low</code> (int)
+ </td><td> </td><td>No</td><td>
+ Once the hardware charge level of the battery drops below
+ this value its state changes to 'low'.
+ Measured in <code class="literal">"battery.reporting.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.granularity_1</code> (int)
+ </td><td> </td><td>No</td><td>
+ Hardware granularity value one of the battery measured
+ in <code class="literal">"battery.reporting.unit"</code>
+ units .
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.granularity_2</code> (int)
+ </td><td> </td><td>No</td><td>
+ Hardware granularity value two of the battery measured
+ in <code class="literal">"battery.reporting.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.capacity_state</code> (string)
+ </td><td>
+ Examples: <code class="literal">ok</code>, <code class="literal">critical</code>
+ </td><td>No</td><td>
+ The capacity state of the battery.
+ </td></tr><tr><td>
+ <code class="literal">battery.voltage.unit</code> (string)
+ </td><td>
+ Examples: <code class="literal">mV</code>
+ </td><td>No</td><td>
+ The physical measurement unit used by the voltage properties
+ (design and current).
+ </td></tr><tr><td>
+ <code class="literal">battery.voltage.design</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ The voltage level for which the battery is designed for.
+ Measured in <code class="literal">"battery.voltage.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.voltage.current</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ The voltage level currently emitted by the battery.
+ Measured in <code class="literal">"battery.voltage.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.alarm.unit</code> (string)
+ </td><td>
+ Examples: <code class="literal">mWh</code>, <code class="literal">mAh</code>
+ </td><td>No</td><td>
+ The physical measurement unit used by the alarm property.
+ </td></tr><tr><td>
+ <code class="literal">battery.alarm.design</code> (int)
+ </td><td> </td><td>No</td><td>
+ Once the charge level of the battery drops below this value
+ its state changes to 'alarm'.
+ Measured in <code class="literal">"battery.alarm.unit"</code>
+ units.
+ </td></tr><tr><td>
+ <code class="literal">battery.remaining_time</code> (int)
+ </td><td> </td><td>No</td><td>
+ Remaining time, in seconds, that the battery can provide
+ power (if discharging) or the time until charged (if charging).
+ This is an estimate and may be imprecise.
+ This key is not present for invalid data.
+ </td></tr><tr><td>
+ <code class="literal">battery.remaining_time.calculate_per_time</code> (bool)
+ </td><td> </td><td>No</td><td>
+ If this property is <code class="literal">true</code> the
+ <code class="literal">battery.remaining_time</code> becomes guessed from
+ <code class="literal">battery.charge_level.current</code> and time.
+ </td></tr><tr><td>
+ <code class="literal">battery.charge_level.percentage</code> (int)
+ </td><td> </td><td>No</td><td>
+ Charge, normalised to percent. This is useful if an application
+ does not want to process the raw values and do all the extra
+ checks on the result. This key is not present for invalid data.
+ </td></tr><tr><td>
+ <code class="literal">battery.is_rechargeable</code> (bool)
+ </td><td> </td><td>No</td><td>
+ True if the battery unit is rechargeable, false if its is
+ one-time (disposable after one usage).
+ </td></tr><tr><td>
+ <code class="literal">battery.rechargeable.is_charging</code> (bool)
+ </td><td> </td><td>
+ Only if <code class="literal">battery.is_rechargeable</code> is TRUE
+ </td><td>
+ TRUE if, and only if, the battery is charging.
+ </td></tr><tr><td>
+ <code class="literal">battery.rechargeable.is_discharging</code> (bool)
+ </td><td> </td><td>
+ Only if <code class="literal">battery.is_rechargeable</code> is TRUE
+ </td><td>
+ TRUE if, and only if, the battery is discharging.
+ </td></tr><tr><td>
+ <code class="literal">battery.command_interface</code> (string)
+ </td><td> </td><td>No</td><td>
+ The abstract name allowing daemons and/or user-level apps
+ to distinguish some groups of devices having similar
+ programming interface. Introduced mostly for the daemons'
+ coding simplicity.
+ </td></tr><tr><td>
+ <code class="literal">battery.vendor</code> (string)
+ </td><td> </td><td>No</td><td>
+ Vendor of the battery.
+ </td></tr><tr><td>
+ <code class="literal">battery.model</code> (string)
+ </td><td> </td><td>No</td><td>
+ Make of the battery.
+ </td></tr><tr><td>
+ <code class="literal">battery.reporting.technology</code> (string)
+ </td><td>example: LION</td><td>No</td><td>
+ The technology of the battery as reported by the hardware.
+ </td></tr><tr><td>
+ <code class="literal">battery.technology</code> (string)
+ </td><td>
+ lead-acid, lithium-ion, lithium-polymer,
+ nickel-metal-hydride, unknown
+ </td><td>No</td><td>
+ The technology of the battery processed to a few standard types.
+ This key is needed as the hardware often does not specify the
+ description text for a battery, and so we have to calculate it
+ from the output of <code class="literal">battery.reporting.technology</code>.
+ </td></tr><tr><td>
+ <code class="literal">battery.serial</code> (string)
+ </td><td> </td><td>No</td><td>
+ A string uniquely identifying the instance of the battery;
+ it will be different for two (otherwise) identical batteries.
+ </td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-button"></a>
+ button namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">button</code>
+ represent the devices capable of providing a state to the system.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">button.type</code> (string)
+ </td><td> </td><td>No</td><td>The type of button</td></tr><tr><td> </td><td>lid</td><td> </td><td>
+ The switch on a laptop that senses whether the lid is
+ open or closed
+ </td></tr><tr><td> </td><td>power</td><td> </td><td>The main power button on the computer.</td></tr><tr><td> </td><td>sleep</td><td> </td><td>
+ The sleep button on a computer capable of putting the computer
+ into a suspend state
+ </td></tr><tr><td>
+ <code class="literal">button.has_state</code> (bool)
+ </td><td> </td><td>no</td><td>True if the button maintains state, e.g. can toggled on/off</td></tr><tr><td>
+ <code class="literal">button.state.value</code> (bool)
+ </td><td> </td><td>
+ Only when <code class="literal">button.has_state</code> is
+ TRUE
+ </td><td>State of the button, TRUE if it is enabled</td></tr></tbody></table></div><p>
+ Device objects with this capability may emit the following events.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Condition Name</th><th>Parameters</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">ButtonPressed</code>
+ </td><td>
+ <code class="literal">button.type (string)</code>
+ </td><td>sleep</td><td>Emitted when a button is pressed</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-processor"></a>
+ processor namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">processor</code>
+ represent CPU's in the system.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">processor.number</code> (int)
+ </td><td> </td><td>Yes</td><td>
+ The internal processor number in the system, starting from zero
+ </td></tr><tr><td>
+ <code class="literal">processor.can_throttle</code> (bool)
+ </td><td> </td><td>No</td><td>
+ Whether the processor supports throttling to decrease it's
+ own clock speed
+ </td></tr><tr><td>
+ <code class="literal">processor.maximum_speed</code> (long)
+ </td><td>example: 2200</td><td>No</td><td>The maximum speed of the processor in units of MHz</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-light-sensor"></a>
+ light_sensor namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">sensor</code>
+ represent light sensors in the system.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">light_sensor.sensor_locations</code> (strlist)
+ </td><td> </td><td>Yes</td><td>The locations of the sensors</td></tr><tr><td>
+ <code class="literal">light_sensor.num_sensors</code> (int)
+ </td><td> </td><td>Yes</td><td>Number of physical sensors</td></tr><tr><td>
+ <code class="literal">light_sensor.num_levels</code> (int)
+ </td><td> </td><td>Yes</td><td>The number of levels of the sensors</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-power-management"></a>
+ power_management namespace
+ </h3></div></div></div><p>
+ Keys with the prefix <code class="literal">power_management</code>
+ provide information about power management supported by
+ the system.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">power_management.type</code> (string)
+ </td><td>Examples:
+ <code class="literal">apm</code>,
+ <code class="literal">acpi</code>,
+ <code class="literal">pmu</code>
+ </td><td>Yes</td><td>
+ The power management subsystem used on the computer.
+ </td></tr><tr><td>
+ <code class="literal">power_management.can_suspend</code> (bool)
+ </td><td> </td><td>Yes</td><td>
+ If suspend support is compiled into the kernel.
+ NB. This may not mean the machine is able to suspend
+ successfully.
+ </td></tr><tr><td>
+ <code class="literal">power_management.can_suspend_hybrid</code> (bool)
+ </td><td> </td><td>Yes</td><td>
+ If the system is capable of hybrid suspend.
+ </td></tr><tr><td>
+ <code class="literal">power_management.can_hibernate</code> (bool)
+ </td><td> </td><td>Yes</td><td>
+ If hibernation support is compiled into the kernel.
+ NB. This may not mean the machine is able to hibernate
+ successfully.
+ </td></tr><tr><td>
+ <code class="literal">power_management.is_powersave_set</code> (bool)
+ </td><td> </td><td>Yes</td><td>
+ Is the last value passed to the SetPowerSave method.
+ </td></tr><tr><td>
+ <code class="literal">power_management.quirk.s3_bios</code> (bool)
+ </td><td> </td><td>No</td><td>Use the S3_BIOS kernel command for suspend.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.s3_mode</code> (bool)
+ </td><td> </td><td>No</td><td>Use the S3_MODE kernel command for suspend.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.dpms_suspend</code> (bool)
+ </td><td> </td><td>No</td><td>Suspend the video card via DPMS on suspend.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.vga_mode_3</code> (bool)
+ </td><td> </td><td>No</td><td>Reset the VGA text mode to mode 3 on resume.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.dpms_on</code> (bool)
+ </td><td> </td><td>No</td><td>Reactivate the screen with DPMS on resume.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.vbe_post</code> (bool)
+ </td><td> </td><td>No</td><td>Run the VGA BIOS Power On Self Test (POST) on resume.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.vbestate_restore</code> (bool)
+ </td><td> </td><td>No</td><td>Save the VGA BIOS state before suspend, and restore it on resume.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.vbemode_restore</code> (bool)
+ </td><td> </td><td>No</td><td>Save the VGA BIOS mode before suspend, and restore it on resume.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.radeon_off</code> (bool)
+ </td><td> </td><td>No</td><td>Turn off the Radeon DAC off before suspend.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.reset_brightness</code> (bool)
+ </td><td> </td><td>No</td><td>Reset the brightness state after resume.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.no_fb</code> (bool)
+ </td><td> </td><td>No</td><td>True if the machine can only suspend when not using framebuffer.</td></tr><tr><td>
+ <code class="literal">power_management.quirk.none</code> (bool)
+ </td><td> </td><td>No</td><td>No quirks are necessary for suspend or resume.</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-tape"></a>
+ tape namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">tape</code>
+ represent tape devices.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">tape.major</code> (int)
+ </td><td>example: 254</td><td>Yes</td><td>The device's major number</td></tr><tr><td>
+ <code class="literal">tape.minor</code> (int)
+ </td><td>example: 0</td><td>Yes</td><td>The device's minor number</td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-killswitch"></a>
+ killswitch namespace
+ </h3></div></div></div><p>
+ Device objects with the capability <code class="literal">killswitch</code>
+ represent switches to turn a radio on and off. See also <a href="#interface-device-killswitch" title="org.freedesktop.Hal.Device.KillSwitch interface">the section called “org.freedesktop.Hal.Device.KillSwitch interface”</a>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">killswitch.type</code> (string)
+ </td><td> </td><td>Yes</td><td>Type of the kill switch</td></tr><tr><td> </td><td>wlan</td><td> </td><td>Kill switch is for turning Wireless networking on/off</td></tr><tr><td> </td><td>bluetooth</td><td> </td><td>Kill switch is for turning Bluetooth on/off</td></tr><tr><td>
+ <code class="literal">killswitch.access_method</code> (string)
+ </td><td> </td><td>Yes</td><td>How HAL should program the switch</td></tr></tbody></table></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="properties-misc"></a>Misc. Properties</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="device-properties-access-control"></a>
+ access_control namespace
+ </h3></div></div></div><p>
+ Device objects with the
+ capability <code class="literal">access_control</code> represent devices
+ where access to a special device file can be granted/revoked
+ to unprivileged users.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Values</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">access_control.file</code> (string)
+ </td><td>Example: /dev/snd/pcmC0D1p</td><td>Yes</td><td>
+ Name of the special device file that access can be granted to.
+ </td></tr><tr><td>
+ <code class="literal">access_control.type</code> (string)
+ </td><td>Example: cdrom</td><td>Yes</td><td>
+ Type of access - only makes sense when PolicyKit
+ support is enabled; it's used by PolicyKit to compute
+ what privilege to check for by
+ prepending <code class="literal">hal-device-file-</code> to the
+ value.
+ </td></tr><tr><td>
+ <code class="literal">access_control.grant_user</code> (strlist)
+ </td><td>Example: "gdm, flumotion"</td><td>No</td><td>
+ List of UNIX user names to always grant access to the
+ device. This is useful for 3rd party system-wide
+ packages that need access to a device to function
+ properly.
+ </td></tr><tr><td>
+ <code class="literal">access_control.grant_group</code> (strlist)
+ </td><td>Example: "pvr_software, staff"</td><td>No</td><td>
+ List of UNIX group names to always grant access to the
+ device. This is useful for 3rd party system-wide
+ packages that need access to a device to function
+ properly.
+ </td></tr></tbody></table></div><p>
+ See also <a href="#interface-device-accesscontrol" title="org.freedesktop.Hal.Device.AccessControl interface">the section called “org.freedesktop.Hal.Device.AccessControl interface”</a>.
+ </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="properties-deprecated"></a>Deprecated Properties</h2></div></div></div><p>
+ The section represents properties that are deprecated and should be no longer used.
+ The properties/keys will be removed, but not before the date in the following table:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Key (type)</th><th>Replacement</th><th>Remove (date)</th><th>Notes</th></tr></thead><tbody><tr><td><code class="literal">info.bus</code> (string)</td><td><code class="literal">info.subsystem</code></td><td>2008-03-01</td><td>Renamed to something more abstract, available until removed.</td></tr><tr><td><code class="literal">*.physical_device</code> (string)</td><td><code class="literal">*.originating_device</code></td><td>2008-03-01</td><td>Renamed to something more abstract, available until removed.</td></tr><tr><td><code class="literal">portable_audio_player.access_method</code> (string)</td><td><code class="literal">portable_audio_player.access_method.[drivers, protocols]</code> (strlist)</td><td>2008-05-03</td><td>Original entry can only indicate UMS or userspace driver devices, while some devices can be both. New structure doesn't have this limitation.</td></tr><tr><td><code class="literal">portable_audio_player.type</code> (string)</td><td><code class="literal">portable_audio_player.access_method.[drivers, protocols]</code> (strlist)</td><td>2008-05-03</td><td>New structure allows for better definition of access protocols and handlers.</td></tr><tr><td><code class="literal">power_management.can_suspend_to_ram</code> (bool)</td><td><code class="literal">power_management.can_suspend</code></td><td>2007-05-01</td><td> </td></tr><tr><td><code class="literal">power_management.can_suspend_to_disk</code> (bool)</td><td><code class="literal">power_management.can_hibernate</code></td><td>2007-05-01</td><td> </td></tr><tr><td><code class="literal">smbios.system.manufacturer</code> (string)</td><td><code class="literal">system.hardware.vendor</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">smbios.system.product</code> (string)</td><td><code class="literal">system.hardware.product</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">smbios.system.version</code> (string)</td><td><code class="literal">system.hardware.version</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">smbios.system.serial</code> (string)</td><td><code class="literal">system.hardware.serial</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">smbios.system.uuid</code> (string)</td><td><code class="literal">system.hardware.uuid</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">smbios.bios.vendor</code> (string)</td><td><code class="literal">system.firmware.vendor</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">smbios.bios.version</code> (string)</td><td><code class="literal">system.firmware.version</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">smbios.bios.release_date</code> (string)</td><td><code class="literal">system.firmware.release_date</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">smbios.chassis.manufacturer</code> (string)</td><td><code class="literal">system.chassis.manufacturer</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">smbios.chassis.type</code> (string)</td><td><code class="literal">system.chassis.type</code></td><td>2008-02-28</td><td>Renamed to something more abstract.</td></tr><tr><td><code class="literal">system.vendor</code> (string)</td><td><code class="literal">system.hardware.vendor</code></td><td>2008-02-28</td><td>Duplicate of system.hardware.vendor.</td></tr><tr><td><code class="literal">usb_device.speed_bcd</code> (int)</td><td><code class="literal">usb_device.speed</code> (double)</td><td>2008-03-21</td><td>changed from 'BCD with two decimals' to double</td></tr><tr><td><code class="literal">usb_device.version_bcd</code> (int)</td><td><code class="literal">usb_device.version</code> (double)</td><td>2008-03-21</td><td>changed from 'BCD with two decimals' to double</td></tr></tbody></table></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="interfaces"></a>Chapter 6. D-Bus interfaces</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#interface-manager">org.freedesktop.Hal.Manager interface</a></span></dt><dt><span class="sect1"><a href="#interface-device">org.freedesktop.Hal.Device interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-systempower">org.freedesktop.Hal.Device.SystemPowerManagement interface</a></span></dt><dt><span class="sect1"><a href="#interface-cpufreq">org.freedesktop.Hal.Device.CPUFreq interface</a></span></dt><dt><span class="sect1"><a href="#interface-wakeonlan">org.freedesktop.Hal.Device.WakeOnLan interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-laptop-panel">org.freedesktop.Hal.Device.LaptopPanel interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-keyboard-backlight">org.freedesktop.Hal.Device.KeyboardBacklight interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-light-sensor">org.freedesktop.Hal.Device.LightSensor interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-storage">org.freedesktop.Hal.Device.Storage interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-volume">org.freedesktop.Hal.Device.Volume interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-volume-crypto">org.freedesktop.Hal.Device.Volume.Crypto interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-killswitch">org.freedesktop.Hal.Device.KillSwitch interface</a></span></dt><dt><span class="sect1"><a href="#interface-device-accesscontrol">org.freedesktop.Hal.Device.AccessControl interface</a></span></dt><dt><span class="sect1"><a href="#interface-singleton-addon"><code class="literal">org.freedesktop.Hal.SingletonAddon</code> interface</a></span></dt></dl></div><p>
+ All of the HAL D-Bus interfaces are introspectable using the
+ standard D-Bus introspection methods (e.g. they all implement
+ the <code class="literal">org.freedesktop.DBus.Introspectable</code>
+ interface). For example, a command like
+ </p><pre class="programlisting">
+$ dbus-send --system --print-reply --dest=org.freedesktop.Hal \
+ /org/freedesktop/Hal/devices/computer \
+ org.freedesktop.DBus.Introspectable.Introspect
+ </pre><p>
+ will print out the introspection XML for what interfaces
+ (ie. methods and signals) the given hal device object
+ supports. For brevity, the <code class="literal">org.freedesktop.Hal</code>
+ prefix have been stripped from the exceptions listed in the
+ following sections.
+ </p><p>
+ Also note that other exceptions than the ones listed may be
+ thrown; for example
+ the <code class="literal">org.freedesktop.Hal.Device.InterfaceLocked</code>
+ exception may be thrown regardless of how the interface is
+ implemented (depending on if some other process is holding a lock
+ on the device cf. <a href="#locking" title="Chapter 4. Locking">Chapter 4, <i>Locking</i></a>); if PolicyKit support
+ is enabled,
+ the <code class="literal">org.freedesktop.Hal.Device.PermissionDeniedByPolicy</code>
+ exception may be thrown (the two first words in the exception
+ detail is resp. a) the privilege the caller didn't have; b) the
+ textual result code from PolicyKit specifying if the caller can
+ obtain the privilege) if the caller is not privileged and so on.
+ </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-manager"></a>org.freedesktop.Hal.Manager interface</h2></div></div></div><p>
+ Only the <code class="literal">/org/freedesktop/Hal/Manager</code> object
+ implements this interface. It's primarily used to discover
+ devices. The following methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>GetAllDevices</td><td>Objref[]</td><td> </td><td> </td><td>
+ Get all UDI's in the database.
+ </td></tr><tr><td>DeviceExists</td><td>Bool</td><td> </td><td> </td><td>
+ Determines if a given object exists.
+ </td></tr><tr><td>FindDeviceStringMatch</td><td>Objref[]</td><td>String key, String value</td><td> </td><td>
+ Find devices for which the given string property assumes the given value.
+ </td></tr><tr><td>FindDeviceByCapability</td><td>Objref[]</td><td>String capability</td><td> </td><td>
+ Finds devices of the given capability.
+ </td></tr><tr><td>NewDevice</td><td>Objref</td><td> </td><td>PermissionDenied</td><td>
+ Creates a new device object in the temporary device list
+ (TDL) and return the UDI. Caller must be uid 0.
+ </td></tr><tr><td>Remove</td><td> </td><td>Objref tmp_udi</td><td>NoSuchDevice, PermissionDenied</td><td>
+ Removes a device object that was created in the
+ TDL. Caller must be uid 0.
+ </td></tr><tr><td>CommitToGdl</td><td> </td><td>Objref tmp_udi, Objref udi</td><td>NoSuchDevice, PermissionDenied</td><td>
+ Moves a device from the temporary device list (TDL) to
+ the global device list (GDL). Caller must be uid 0.
+ </td></tr><tr><td>AcquireGlobalInterfaceLock</td><td> </td><td>String interface_name, Bool exclusive</td><td>Device.InterfaceAlreadyLocked</td><td>
+ Acquires a global lock on an interface. See
+ <a href="#locking" title="Chapter 4. Locking">Chapter 4, <i>Locking</i></a> for details.
+ </td></tr><tr><td>ReleaseGlobalInterfaceLock</td><td> </td><td>String interface_name</td><td>Device.InterfaceNotLocked</td><td>
+ Releases a global lock on an interface. See
+ <a href="#locking" title="Chapter 4. Locking">Chapter 4, <i>Locking</i></a> for details.
+ </td></tr><tr><td>SingletonAddonIsReady</td><td> </td><td>String command_line</td><td>PermissionDenied, SyntaxError</td><td>
+ Called by singleton addons to signal that they are
+ ready to handle devices. A singleton addon should
+ implement the <a href="#interface-singleton-addon" title="org.freedesktop.Hal.SingletonAddon interface">
+ org.freedesktop.Hal.Singleton</a> interface.
+ </td></tr></tbody></table></div><p>
+ The following signals are emitted:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Signal</th><th>Parameters</th><th>Description</th></tr></thead><tbody><tr><td>DeviceAdded</td><td>Objref obj</td><td>
+ A device was added to the global device list (GDL).
+ </td></tr><tr><td>DeviceRemoved</td><td>Objref obj</td><td>
+ A device was removed from the global device list (GDL).
+ </td></tr><tr><td>NewCapability</td><td>Objref obj, String cap</td><td>
+ A device gained a new capability.
+ </td></tr><tr><td>GlobalInterfaceLockAcquired</td><td>String lock_name, String lock_owner, Int num_holders</td><td>
+ Sent when a process acquires a global interface lock.
+ </td></tr><tr><td>GlobalInterfaceLockReleased</td><td>String lock_name, String lock_owner, Int num_holders</td><td>
+ Sent when a process releases a global interface lock.
+ </td></tr></tbody></table></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device"></a>org.freedesktop.Hal.Device interface</h2></div></div></div><p>
+ Every hal device object (e.g. objects where the object path is
+ prefixed with <code class="literal">/org/freedesktop/Hal/devices/</code>)
+ implements this interface. It provides generic
+ functionality. The following methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>GetProperty</td><td>Variant</td><td>String key</td><td>NoSuchProperty</td><td>
+ Get property.
+ </td></tr><tr><td>GetPropertyString</td><td>String</td><td>String key</td><td>NoSuchProperty, TypeMismatch</td><td>
+ Get property.
+ </td></tr><tr><td>GetPropertyStringList</td><td>String[]</td><td>String key</td><td>NoSuchProperty, TypeMismatch</td><td>
+ Get property.
+ </td></tr><tr><td>GetPropertyInteger</td><td>Int</td><td>String key</td><td>NoSuchProperty, TypeMismatch</td><td>
+ Get property.
+ </td></tr><tr><td>GetPropertyUInt64</td><td>UInt64</td><td>String key</td><td>NoSuchProperty, TypeMismatch</td><td>
+ Get property.
+ </td></tr><tr><td>GetPropertyBoolean</td><td>Bool</td><td>String key</td><td>NoSuchProperty, TypeMismatch</td><td>
+ Get property.
+ </td></tr><tr><td>GetPropertyDouble</td><td>Double</td><td>String key</td><td>NoSuchProperty, TypeMismatch</td><td>
+ Get property.
+ </td></tr><tr><td>SetProperty</td><td>Variant</td><td>String key</td><td>PermissionDenied</td><td>
+ Set property.
+ </td></tr><tr><td>SetPropertyString</td><td>String</td><td>String key</td><td>PermissionDenied, TypeMismatch</td><td>
+ Set property.
+ </td></tr><tr><td>SetPropertyStringList</td><td>String[]</td><td>String key</td><td>PermissionDenied, TypeMismatch</td><td>
+ Set property.
+ </td></tr><tr><td>SetPropertyInteger</td><td>Int</td><td>String key</td><td>PermissionDenied, TypeMismatch</td><td>
+ Set property.
+ </td></tr><tr><td>SetPropertyUInt64</td><td>UInt64</td><td>String key</td><td>PermissionDenied, TypeMismatch</td><td>
+ Set property.
+ </td></tr><tr><td>SetPropertyBoolean</td><td>Bool</td><td>String key</td><td>PermissionDenied, TypeMismatch</td><td>
+ Set property.
+ </td></tr><tr><td>SetPropertyDouble</td><td>Double</td><td>String key</td><td>PermissionDenied, TypeMismatch</td><td>
+ Set property.
+ </td></tr><tr><td>RemoveProperty</td><td> </td><td>String key</td><td>NoSuchProperty, PermissionDenied</td><td>
+ Remove a property.
+ </td></tr><tr><td>GetPropertyType</td><td>Int</td><td>String key</td><td>NoSuchProperty</td><td>
+ Get the type of a property. Returns the D-Bus type as an integer.
+ </td></tr><tr><td>PropertyExists</td><td>Bool</td><td>String key</td><td> </td><td>
+ Determine if a property exists.
+ </td></tr><tr><td>AddCapability</td><td> </td><td>String capability</td><td>PermissionDenied</td><td>
+ Adds a capability to a device.
+ </td></tr><tr><td>QueryCapability</td><td>Bool</td><td>String capability</td><td> </td><td>
+ Determine if a device have a capability.
+ </td></tr><tr><td>Lock</td><td>Bool</td><td>String reason</td><td>DeviceAlreadyLocked</td><td>
+ Acquires an advisory lock on the device. Returns TRUE if the lock was acquired.
+ </td></tr><tr><td>Unlock</td><td>Bool</td><td> </td><td>DeviceNotLocked</td><td>
+ Releases an advisory lock on the device. Returns TRUE if the lock was released.
+ </td></tr><tr><td>AcquireInterfaceLock</td><td> </td><td>String interface_name, Bool exclusive</td><td>PermissionDenied, Device.InterfaceAlreadyLocked</td><td>
+ Acquires a lock on an interface for a specific
+ device. See <a href="#locking" title="Chapter 4. Locking">Chapter 4, <i>Locking</i></a> for details.
+ </td></tr><tr><td>ReleaseInterfaceLock</td><td> </td><td>String interface_name</td><td>PermissionDenied, Device.InterfaceNotLocked</td><td>
+ Releases a lock on an interface for a specific device. See
+ <a href="#locking" title="Chapter 4. Locking">Chapter 4, <i>Locking</i></a> for details.
+ </td></tr><tr><td>IsCallerLockedOut</td><td>Bool</td><td>String interface_name, String caller_unique_name</td><td>PermissionDenied</td><td>
+ Determines whether a given process on the system message
+ bus is locked out from an interface on a specific
+ device. Only HAL helpers are privileged to use this
+ method. See <a href="#locking" title="Chapter 4. Locking">Chapter 4, <i>Locking</i></a> for details.
+ </td></tr><tr><td>IsCallerPrivileged</td><td>String</td><td>String privilege, String caller_unique_name</td><td>PermissionDenied, Error</td><td>
+ <p>
+ Determines whether a given process on the system
+ message bus is authorized according to PolicyKit on a
+ specific device for a specific PolicyKit
+ privilege. Unprivileged callers (e.g. with a non-zero
+ uid) can only ask
+ about <code class="literal">caller_unique_name</code> that
+ matches their own uid; if this is violated
+ <code class="literal">PermissionDenied</code> will be
+ thrown. This can be used ahead of time to see if a
+ given call will succeed or if it requires privilege
+ elevation (TODO: clarify this once PolicyKit can auth
+ over D-Bus).
+ </p>
+ <p>
+ Returns the textual representation of a PolKitResult
+ value on success.
+ </p>
+ <p>
+ If HAL is not built with PolicyKit support, this
+ method always throws
+ the <code class="literal">org.freedesktop.Hal.Device.Error</code>
+ exception.
+ </p>
+ </td></tr><tr><td>IsLockedByOthers</td><td>Bool</td><td>String interface_name</td><td> </td><td>
+ Determines whether a determines other processes than the
+ caller holds a lock on the given device. See
+ <a href="#locking" title="Chapter 4. Locking">Chapter 4, <i>Locking</i></a> for details.
+ </td></tr><tr><td>StringListAppend</td><td> </td><td>String key, String value</td><td>PermissionDenied, TypeMismatch</td><td>
+ Appends an item to a string list.
+ </td></tr><tr><td>StringListPrepend</td><td> </td><td>String key, String value</td><td>PermissionDenied, TypeMismatch</td><td>
+ Prepends an item to a string list.
+ </td></tr><tr><td>StringListRemove</td><td> </td><td>String key, String value</td><td>PermissionDenied, TypeMismatch</td><td>
+ Removes an item from a string list.
+ </td></tr><tr><td>EmitCondition</td><td>Bool</td><td>String name, String details</td><td>PermissionDenied</td><td>
+ Emit a condition on a device object.
+ </td></tr><tr><td>Rescan</td><td>Bool</td><td> </td><td>PermissionDenied</td><td>
+ Force an updates of the properties of a device object by
+ rereading data that is not monitored for changes.
+ </td></tr><tr><td>Reprobe</td><td>Bool</td><td> </td><td>PermissionDenied</td><td>
+ 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.
+ </td></tr><tr><td>ClaimInterface</td><td>Bool</td><td>String name, String introspection_xml</td><td>PermissionDenied</td><td>
+ 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.
+ </td></tr><tr><td>AddonIsReady</td><td>Bool</td><td> </td><td>PermissionDenied</td><td>
+ 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.
+ </td></tr></tbody></table></div><p>
+ The following signals are emitted:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Signal</th><th>Parameters</th><th>Description</th></tr></thead><tbody><tr><td>PropertyModified</td><td>Int num_changes, Array of struct {String property_name, Bool added, Bool removed}</td><td>
+ One or more properties on the device object have changed.
+ </td></tr><tr><td>Condition</td><td>String name, String details</td><td>
+ 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.).
+ </td></tr><tr><td>InterfaceLockAcquired</td><td>String lock_name, String lock_owner, Int num_holders</td><td>
+ Sent when a process acquires an interface lock on the device.
+ </td></tr><tr><td>InterfaceLockReleased</td><td>String lock_name, String lock_owner, Int num_holders</td><td>
+ Sent when a process releases an interface lock on the device.
+ </td></tr></tbody></table></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device-systempower"></a>org.freedesktop.Hal.Device.SystemPowerManagement interface</h2></div></div></div><p>
+ This interface provides a mechanism to affect system-wide power
+ management. Normally only the root computer device object
+ (<code class="literal">/org/freedesktop/Hal/devices/computer</code>)
+ implements this interface. The following methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>Suspend</td><td>Int</td><td>Int num_secs_to_wakeup</td><td>SystemPowerManagement.NotSupported, SystemPowerManagement.AlarmNotSupported</td><td>
+ Puts the system in a suspended state (typically ACPI S3)
+ for <code class="literal">num_secs_to_wakeup</code> 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.
+ </td></tr><tr><td>Hibernate</td><td>Int</td><td> </td><td>SystemPowerManagement.NotSupported</td><td>
+ 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.
+ </td></tr><tr><td>SuspendHybrid</td><td>Int</td><td>Int num_secs_to_wakeup</td><td>SystemPowerManagement.NotSupported, SystemPowerManagement.AlarmNotSupported</td><td>
+ Puts the system in a suspended state (typically ACPI S3)
+ for <code class="literal">num_secs_to_wakeup</code> 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.
+ </td></tr><tr><td>Shutdown</td><td>Int</td><td> </td><td>SystemPowerManagement.NotSupported</td><td>
+ Shut down the system.
+ </td></tr><tr><td>Reboot</td><td>Int</td><td> </td><td>SystemPowerManagement.NotSupported</td><td>
+ Reboot the system.
+ </td></tr><tr><td>SetPowerSave</td><td>Int</td><td>Bool should_save_power</td><td>SystemPowerManagement.NotSupported</td><td>
+ If the boolean passed is TRUE, the system will be
+ configured to save as much power as possible by
+ e.g. enabling <code class="literal">laptop mode</code> to avoid
+ spinning up disks. Typically, power management daemons
+ will call this method when it determines that the system
+ is running on battery power.
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p><p>
+ Implementors of power management daemons should make sure that
+ their software respects the locking guidelines described in
+ <a href="#interfaces" title="Chapter 6. D-Bus interfaces">Chapter 6, <i>D-Bus interfaces</i></a>.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-cpufreq"></a>org.freedesktop.Hal.Device.CPUFreq interface</h2></div></div></div><p>
+ This interface provides a mechanism to configure CPU frequency
+ scaling. The following methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>GetCPUFreqAvailableGovernors</td><td>String[]</td><td> </td><td> </td><td>
+ Retrieves a list of available CPU scaling governors.
+ </td></tr><tr><td>GetCPUFreqGovernor</td><td>String</td><td> </td><td> </td><td>
+ Get currently selected CPU Frequency governor.
+ </td></tr><tr><td>SetCPUFreqGovernor</td><td>Void</td><td>String governor</td><td>CPUFreq.UnknownGovernor</td><td>
+ Selects a CPU frequency scaling governor for all CPUFreq
+ interfaces the kernel provides. If the userspace governor is
+ set, this interface also contains a proper scaling
+ mechanism.
+ </td></tr><tr><td>SetCPUFreqPerformance</td><td>Void</td><td>Int (1 to 100)</td><td>CPUFreq.NoSuitableGovernor</td><td>
+ 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.
+ </td></tr><tr><td>GetCPUFreqPerformance</td><td>Int</td><td> </td><td>CPUFreq.NoSuitableGovernor</td><td>
+ Get the tuning value for the governor.
+ </td></tr><tr><td>SetCPUFreqConsiderNice</td><td>Void</td><td>Bool consider_niced_processes</td><td>CPUFreq.NoSuitableGovernor</td><td>
+ 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'.
+ </td></tr><tr><td>GetCPUFreqConsiderNice</td><td>Bool</td><td> </td><td>CPUFreq.NoSuitableGovernor</td><td>
+ Whether nice'ed processes are considered by the governor.
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-wakeonlan"></a>org.freedesktop.Hal.Device.WakeOnLan interface</h2></div></div></div><p>
+ This interface provides a mechanism to configure Wake On LAN
+ capabilities. The following methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>GetSupported</td><td>Bool</td><td> </td><td>WakeOnLan.NoEthtool</td><td>
+ Get if device supports Wake On LAN
+ </td></tr><tr><td>GetEnabled</td><td>Bool</td><td> </td><td>WakeOnLan.NoEthtool</td><td>
+ Get if Wake On LAN is enabled
+ </td></tr><tr><td>SetEnabled</td><td>Void</td><td>Bool</td><td>WakeOnLan.NoEthtool</td><td>
+ Enable or disable Wake On LAN
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device-laptop-panel"></a>org.freedesktop.Hal.Device.LaptopPanel interface</h2></div></div></div><p>
+ This interface provides a mechanism to get/set the brightness of
+ a laptop panel. The following methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>GetBrightness</td><td>Int</td><td> </td><td> </td><td>
+ Get the current brightness.
+ </td></tr><tr><td>SetBrightness</td><td> </td><td>Int brightness</td><td> </td><td>
+ Set the current brightness.
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device-keyboard-backlight"></a>org.freedesktop.Hal.Device.KeyboardBacklight interface</h2></div></div></div><p>
+ This interface provides a mechanism to get/set the brightness of
+ the keyboard backlight. The following methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>GetBrightness</td><td>Int</td><td> </td><td> </td><td>
+ Get the current brightness.
+ </td></tr><tr><td>SetBrightness</td><td> </td><td>Int brightness</td><td> </td><td>
+ Set the current brightness.
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device-light-sensor"></a>org.freedesktop.Hal.Device.LightSensor interface</h2></div></div></div><p>
+ This interface provides a mechanism to get information from a
+ light sensor. The following methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>GetBrightness</td><td>Int[]</td><td> </td><td> </td><td>
+ The current brightness as measured by the light sensor.
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device-storage"></a>org.freedesktop.Hal.Device.Storage interface</h2></div></div></div><p>
+ This interface provides a mechanism to interact with a storage
+ device. The following methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>Eject</td><td>Int</td><td>String[] options</td><td>Volume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidEjectOption</td><td>
+ Unmounts all volumes and possibly ejects the media. Note
+ that this method is not only restricted to optical
+ drives.
+ </td></tr><tr><td>CloseTray</td><td>Int</td><td>String[] options</td><td>Storage.InvalidCloseTrayOption</td><td>
+ Attempts to close the tray. Only really makes sense for
+ (optical) drives that uses a tray loading mechanism.
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device-volume"></a>org.freedesktop.Hal.Device.Volume interface</h2></div></div></div><p>
+ This interface provides a mechanism to interact with a volume
+ that has a mountable file system. The following methods are
+ available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>Mount</td><td>Int</td><td>String mount_point, String fstype, String[] options</td><td>Volume.PermissionDenied, Volume.AlreadyMounted, Volume.InvalidMountOption, Volume.UnknownFilesystemType, Volume.InvalidMountPoint, Volume.MountPointNotAvailable, Volume.CannotRemount</td><td>
+ Mounts a volume.
+ </td></tr><tr><td>Unmount</td><td>Int</td><td>String[] options</td><td>Volume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidUnmountOption</td><td>
+ Unmount a volume.
+ </td></tr><tr><td>Eject</td><td>Int</td><td>String[] options</td><td>Volume.PermissionDenied, Volume.NotMounted, Volume.NotMountedByHal, Volume.Busy, Volume.InvalidEjectOption</td><td>
+ Unmounts all volumes from the originating drive and
+ possibly ejects the media. Note that this method is not
+ only restricted to optical drives.
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p><p>
+ If a volume originates from a storage device (and all volumes
+ do), it also is checked whether the caller is locked out of the
+ <code class="literal">org.freedesktop.Hal.Device.Storage</code> interface
+ of the originating storage device. As a corollary, it is
+ sufficient to just either a) lock the storage device; or b)
+ globally lock
+ the <code class="literal">org.freedesktop.Hal.Device.Storage</code>
+ interface if one wants to lock out callers from mounting
+ volumes from either a specific drive or all drives.
+
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device-volume-crypto"></a>org.freedesktop.Hal.Device.Volume.Crypto interface</h2></div></div></div><p>
+ This interface provides a mechanism to interact with a volume that
+ is encrypted at the block layer. The following methods are
+ available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>Setup</td><td>Int</td><td>String passphrase</td><td>Volume.Crypto.CryptSetupMissing, Volume.Crypto.SetupError, Volume.Crypto.SetupPasswordError</td><td>
+ Unlocks an encrypted file system. If successful, a cleartext volume will appear.
+ </td></tr><tr><td>Teardown</td><td>Int</td><td> </td><td>Volume.Crypto.TeardownError</td><td>
+ Teardown the cleartext volume.
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p><p>
+ For objects implementing this interface, it will also be checked
+ if the caller is locked out of the Volume interface on the
+ device (and per <a href="#interface-device-volume" title="org.freedesktop.Hal.Device.Volume interface">the section called “org.freedesktop.Hal.Device.Volume interface”</a> this
+ includes checking whether the caller is locked out of
+ the <code class="literal">org.freedesktop.Hal.Device.Storage</code>
+ interface for the storage device that the volume originates
+ from).
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device-killswitch"></a>org.freedesktop.Hal.Device.KillSwitch interface</h2></div></div></div><p>
+ This interface provides a mechanism for both querying whether a
+ radio is on as well as turning it on and off. The following
+ methods are available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>GetPower</td><td>Int</td><td> </td><td> </td><td>
+ Returns 1 if, and only if, the power is on.
+ </td></tr><tr><td>SetPower</td><td> </td><td>Bool</td><td> </td><td>
+ Set the power of the radio.
+ </td></tr></tbody></table></div><p>
+ This interface does not emit any signals.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-device-accesscontrol"></a>org.freedesktop.Hal.Device.AccessControl interface</h2></div></div></div><p>
+ This interface provides a mechanism for discovering when an ACL
+ is added or removed for a device file. The following signals are
+ available:
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Parameters</th><th>Description</th></tr></thead><tbody><tr><td>ACLAdded</td><td>UInt unix_user_id</td><td>
+ Emitted when an ACL have been added for a UNIX user on a
+ device object with the <code class="literal">access_control</code>
+ capability.
+ </td></tr><tr><td>ACLRemoved</td><td>UInt unix_user_id</td><td>
+ Emitted when an ACL have been removed for a UNIX user on
+ a device object with
+ the <code class="literal">access_control</code> capability.
+ </td></tr></tbody></table></div><p>
+ This interface does not export any methods.
+ </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="interface-singleton-addon"></a><code class="literal">org.freedesktop.Hal.SingletonAddon</code> interface</h2></div></div></div><p>
+ This interface is provided by singleton addons to allow the Manager to
+ request handling of new devices and removal of old ones.
+
+ This differs from other HAL interface definitions in that it
+ is provided by addon processes, rather than the HAL daemon itself.
+
+ It should be exported on the path
+ <code class="literal">/org/freedesktop/Hal/Manager</code>.
+ </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Method</th><th>Returns</th><th>Parameters</th><th>Throws</th><th>Description</th></tr></thead><tbody><tr><td>
+ <code class="literal">DeviceAdded</code>
+ </td><td>
+ <p><code class="literal">String udi</code></p>
+ <p><code class="literal">Dict(String,Variant) property_set</code></p>
+ </td><td> </td><td> </td><td>
+ <p>
+ Called by the HAL Manager when a device is added that has
+ this singleton listed in
+ <a href="#device-properties-info-singleton-addons" title="Singleton Addons">
+ <code class="literal">info.addons.singleton</code>
+ </a>
+ </p>
+ <p>
+ An addon implementing this function should start handling the
+ device before returning, and keep track that is is handling this
+ udi.
+ </p>
+ </td></tr><tr><td>
+ <code class="literal">DeviceRemoved</code>
+ </td><td>
+ <p><code class="literal">String udi</code></p>
+ <p><code class="literal">Dict(String,Variant) property_set</code></p>
+ </td><td> </td><td> </td><td>
+ <p>
+ Called by the HAL Manager when a device is added that has
+ this singleton listed in
+ <a href="#device-properties-info-singleton-addons" title="Singleton Addons">
+ <code class="literal">info.addons.singleton</code>
+ </a>
+ </p>
+ <p>
+ The implementer of this function should keep track of
+ which devices it is still handling and exit when no longer
+ handling any devices.
+ </p>
+ </td></tr></tbody></table></div><p>
+ This interface does not export any methods.
+ </p></div></div></div></body></html>
projects / framework / uifw / edbus.git / commitdiff