hal/doc/spec hal-spec.html,1.5,1.6 hal-spec.xml.in,1.4,1.5
David Zeuthen
david at freedesktop.org
Mon Aug 2 14:56:26 PDT 2004
Update of /cvs/hal/hal/doc/spec
In directory pdx:/tmp/cvs-serv24564/doc/spec
Modified Files:
hal-spec.html hal-spec.xml.in
Log Message:
2004-08-02 David Zeuthen <david at fubar.dk>
* tools/device-manager/DeviceManager.py (DeviceManager.gdl_changed):
Upgrade to latest D-BUS python API
Index: hal-spec.html
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- hal-spec.html 2 Aug 2004 15:10:04 -0000 1.5
+++ hal-spec.html 2 Aug 2004 21:56:24 -0000 1.6
@@ -74,7 +74,7 @@
></DT
><DT
><A
-HREF="#AEN143"
+HREF="#AEN146"
>D-BUS Network API</A
></DT
><DT
@@ -465,7 +465,7 @@
><P
>
Merging class device information (derived from the hardware)
- into a device object. For example, for an USB mouse HAL will
+ into a device object. For example, for a USB mouse HAL will
merge well-defined properties describing the input-related
capabilities of the mouse (e.g. how many buttons), and for
optical discs HAL will merge information about the disc (e.g.
@@ -480,7 +480,8 @@
from device information files. This allows applications to
think in terms of ''capabilities'' rather than relying on
device class information derived from the hardware. For example,
- for MP3 players the set of audio formats can be merged.
+ for an MP3 player, the set of audio formats that the device is
+ capable to playback can be merged.
</P
></LI
@@ -569,8 +570,7 @@
><P
>
A device as recognized by the USB, PCI etc. standards and treated as
- such by the operating system kernel and base OS. Note that a physical
- PCI board may appear as two PCI devices.
+ such by the operating system kernel and base OS.
</P
></LI
@@ -590,12 +590,12 @@
>
Note there is not necessarily a one-to-one relationship between
- physical devices attached to a computer system and ''device objects''.
- A multi-function device, which appears (and is marketed) to users
- as a multi-function printer may show up as several device objects; e.g.
- printer, scanner, fax and storage.
- On the other hand, an USB keyboard with a scroll-wheel may appear as
- a single USB device with multiple USB interfaces.
+ physical devices attached to a computer system and ''device
+ objects''. A multi-function device, which appears (and is
+ marketed) to users as a multi-function printer may show up as
+ several device objects; e.g. printer, scanner, fax and storage.
+ On the other hand, PCI networking equipment with multiple ports
+ may show up as several networking devices and so on.
</P
><P
@@ -704,21 +704,25 @@
></UL
>
- The first category is determined by HAL itself, the next is
- merged from either the hardware itself or device information
- files and the last is intercepted by monitoring the operating
- system.
+ The first category is determined by HAL, the next is merged from
+ either the hardware itself or device information files and the
+ last is intercepted by monitoring the operating system.
- This specification is concerned with precisely defining several
- properties; see
- <A
+ </P
+><P
+>
+ This specification is concerned with precisely defining several
+ properties; see <A
HREF="#device-properties"
>the Section called <I
>Properties of a device</I
></A
-> and onwards for more
- information.
+> and onwards
+ for more information.
+ </P
+><P
+>
As a complement to device properties, HAL also provides
<I
CLASS="emphasis"
@@ -728,8 +732,11 @@
not easily expressed in properties. This includes events such as
''processor is overheating'' or ''block device unmounted''.
+ </P
+><P
+>
The fundamental idea about HAL is that all ''interesting'' information
- that a desktop application would be using can be obtained by HAL.
+ about hardware a desktop application needs can be obtained by HAL.
</P
><P
@@ -752,7 +759,7 @@
><HR><H2
CLASS="sect1"
><A
-NAME="AEN143"
+NAME="AEN146"
>D-BUS Network API</A
></H2
><P
@@ -761,12 +768,12 @@
The HAL daemon is a system-wide process that keeps track of a
number of device objects. It communicates with the operating
system and intercepts hotplug events as devices are plugged in
- and removed.
- The daemon is also responsible for providing services to
- applications that wants to locate devices and perform
- generic operations them such as obtaining exclusive access.
- Non-generic operations, such as obtaining pictures from a camera
- device, is outside the scope of the HAL daemon; see <A
+ and removed. The daemon is also responsible for providing
+ services to applications that wants to locate devices and
+ perform generic operations them such as obtaining exclusive
+ access. Non-generic operations, such as obtaining pictures from
+ a camera device, is outside the scope of the HAL daemon; see
+ <A
HREF="#using-devices"
>the Section called <I
>Using devices</I
@@ -776,13 +783,12 @@
</P
><P
>
- Note that the HAL daemon has the concept of a Global Device List
- (GDL in the following) that contains the devices that the
- clients can search and subscribe on changes to.
-
- When a device have been detected, either from inside the HAL daemon
- or from an HAL agent, devices are not initially in the GDL; instead,
- they are added later when a number of properties have been merged.
+ HAL has the concept of device stores. When a device is detected
+ it is placed in the TDL (temporary device list) and then properties
+ are merged from several sources including device information files
+ and possibly callouts. Eventually, the device transitions to the
+ GDL (global device list) and first then it becomes ''visible'' for
+ desktop applications.
</P
><DIV
@@ -790,16 +796,27 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN148"
+NAME="AEN151"
>Interface org.freedesktop.Hal.Manager</A
></H3
><P
>
- Using D-BUS terminology, the HAL daemon provides the D-BUS service
- org.freedesktop.Hal. This service offers a D-BUS object at a
- well-known location /org/freedesktop/Hal/Manager. This object
- offers a D-BUS interface, org.freedesktop.Hal.Manager, for
+ Using D-BUS terminology, the HAL daemon provides the D-BUS
+ service <TT
+CLASS="literal"
+>org.freedesktop.Hal</TT
+>. This service
+ offers a D-BUS object at a well-known
+ location <TT
+CLASS="literal"
+>/org/freedesktop/Hal/Manager</TT
+>. This
+ object offers a D-BUS
+ interface, <TT
+CLASS="literal"
+>org.freedesktop.Hal.Manager</TT
+>, for
querying device objects with the following methods:
</P
><TABLE
@@ -891,7 +908,7 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN154"
+NAME="AEN160"
>Interface org.freedesktop.Hal.Device</A
></H3
><P
@@ -1035,7 +1052,7 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN161"
+NAME="AEN167"
>Interface org.freedesktop.Hal.AgentManager</A
></H3
><P
@@ -1302,7 +1319,7 @@
><P
></P
><A
-NAME="AEN190"
+NAME="AEN196"
></A
><TABLE
BORDER="1"
@@ -1682,7 +1699,7 @@
><P
></P
><A
-NAME="AEN357"
+NAME="AEN363"
></A
><TABLE
BORDER="1"
@@ -1873,7 +1890,7 @@
><P
></P
><A
-NAME="AEN429"
+NAME="AEN435"
></A
><TABLE
BORDER="1"
@@ -1974,7 +1991,7 @@
><P
></P
><A
-NAME="AEN467"
+NAME="AEN473"
></A
><TABLE
BORDER="1"
@@ -2150,7 +2167,7 @@
><P
></P
><A
-NAME="AEN540"
+NAME="AEN546"
></A
><TABLE
BORDER="1"
@@ -2432,7 +2449,7 @@
><P
></P
><A
-NAME="AEN670"
+NAME="AEN676"
></A
><TABLE
BORDER="1"
@@ -2582,7 +2599,7 @@
><P
></P
><A
-NAME="AEN721"
+NAME="AEN727"
></A
><TABLE
BORDER="1"
@@ -2626,7 +2643,7 @@
><P
></P
><A
-NAME="AEN736"
+NAME="AEN742"
></A
><TABLE
BORDER="1"
@@ -2711,7 +2728,7 @@
><P
></P
><A
-NAME="AEN762"
+NAME="AEN768"
></A
><TABLE
BORDER="1"
@@ -3313,7 +3330,7 @@
><P
></P
><A
-NAME="AEN1045"
+NAME="AEN1051"
></A
><TABLE
BORDER="1"
@@ -3468,7 +3485,7 @@
><P
></P
><A
-NAME="AEN1108"
+NAME="AEN1114"
></A
><TABLE
BORDER="1"
@@ -3543,7 +3560,7 @@
><P
></P
><A
-NAME="AEN1138"
+NAME="AEN1144"
></A
><TABLE
BORDER="1"
@@ -3704,7 +3721,7 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN1184"
+NAME="AEN1190"
>Linux 2.6 and udev</A
></H3
><P
Index: hal-spec.xml.in
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.xml.in,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- hal-spec.xml.in 2 Aug 2004 15:10:04 -0000 1.4
+++ hal-spec.xml.in 2 Aug 2004 21:56:24 -0000 1.5
@@ -1,7 +1,6 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- CVSID: $Id$ -->
-<!-- !DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" -->
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "/usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-22.1/docbookx.dtd">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!-- THIS FILE IS AUTOGENERATED FROM hal-spec.xml.in -->
@@ -282,7 +281,7 @@
<listitem><para>
Merging class device information (derived from the hardware)
- into a device object. For example, for an USB mouse HAL will
+ into a device object. For example, for a USB mouse HAL will
merge well-defined properties describing the input-related
capabilities of the mouse (e.g. how many buttons), and for
optical discs HAL will merge information about the disc (e.g.
@@ -295,7 +294,8 @@
from device information files. This allows applications to
think in terms of ''capabilities'' rather than relying on
device class information derived from the hardware. For example,
- for MP3 players the set of audio formats can be merged.
+ for an MP3 player, the set of audio formats that the device is
+ capable to playback can be merged.
</para></listitem>
<listitem><para>
@@ -362,8 +362,7 @@
<listitem><para>
A device as recognized by the USB, PCI etc. standards and treated as
- such by the operating system kernel and base OS. Note that a physical
- PCI board may appear as two PCI devices.
+ such by the operating system kernel and base OS.
</para></listitem>
<listitem><para>
@@ -379,12 +378,12 @@
</itemizedlist>
Note there is not necessarily a one-to-one relationship between
- physical devices attached to a computer system and ''device objects''.
- A multi-function device, which appears (and is marketed) to users
- as a multi-function printer may show up as several device objects; e.g.
- printer, scanner, fax and storage.
- On the other hand, an USB keyboard with a scroll-wheel may appear as
- a single USB device with multiple USB interfaces.
+ physical devices attached to a computer system and ''device
+ objects''. A multi-function device, which appears (and is
+ marketed) to users as a multi-function printer may show up as
+ several device objects; e.g. printer, scanner, fax and storage.
+ On the other hand, PCI networking equipment with multiple ports
+ may show up as several networking devices and so on.
</para><para>
@@ -450,15 +449,17 @@
mount location etc.</para></listitem>
</itemizedlist>
- The first category is determined by HAL itself, the next is
- merged from either the hardware itself or device information
- files and the last is intercepted by monitoring the operating
- system.
+ The first category is determined by HAL, the next is merged from
+ either the hardware itself or device information files and the
+ last is intercepted by monitoring the operating system.
- This specification is concerned with precisely defining several
- properties; see
- <xref linkend="device-properties"/> and onwards for more
- information.
+ </para><para>
+
+ This specification is concerned with precisely defining several
+ properties; see <xref linkend="device-properties"/> and onwards
+ for more information.
+
+ </para><para>
As a complement to device properties, HAL also provides
<emphasis>conditions</emphasis> on HAL device objects. Conditions
@@ -466,8 +467,10 @@
not easily expressed in properties. This includes events such as
''processor is overheating'' or ''block device unmounted''.
+ </para><para>
+
The fundamental idea about HAL is that all ''interesting'' information
- that a desktop application would be using can be obtained by HAL.
+ about hardware a desktop application needs can be obtained by HAL.
</para><para>
@@ -488,23 +491,21 @@
The HAL daemon is a system-wide process that keeps track of a
number of device objects. It communicates with the operating
system and intercepts hotplug events as devices are plugged in
- and removed.
- The daemon is also responsible for providing services to
- applications that wants to locate devices and perform
- generic operations them such as obtaining exclusive access.
- Non-generic operations, such as obtaining pictures from a camera
- device, is outside the scope of the HAL daemon; see <xref
- linkend="using-devices"/> for more information.
+ and removed. The daemon is also responsible for providing
+ services to applications that wants to locate devices and
+ perform generic operations them such as obtaining exclusive
+ access. Non-generic operations, such as obtaining pictures from
+ a camera device, is outside the scope of the HAL daemon; see
+ <xref linkend="using-devices"/> for more information.
</para><para>
- Note that the HAL daemon has the concept of a Global Device List
- (GDL in the following) that contains the devices that the
- clients can search and subscribe on changes to.
-
- When a device have been detected, either from inside the HAL daemon
- or from an HAL agent, devices are not initially in the GDL; instead,
- they are added later when a number of properties have been merged.
+ HAL has the concept of device stores. When a device is detected
+ it is placed in the TDL (temporary device list) and then properties
+ are merged from several sources including device information files
+ and possibly callouts. Eventually, the device transitions to the
+ GDL (global device list) and first then it becomes ''visible'' for
+ desktop applications.
</para>
@@ -512,10 +513,12 @@
<para>
- Using D-BUS terminology, the HAL daemon provides the D-BUS service
- org.freedesktop.Hal. This service offers a D-BUS object at a
- well-known location /org/freedesktop/Hal/Manager. This object
- offers a D-BUS interface, org.freedesktop.Hal.Manager, for
+ Using D-BUS terminology, the HAL daemon provides the D-BUS
+ service <literal>org.freedesktop.Hal</literal>. This service
+ offers a D-BUS object at a well-known
+ location <literal>/org/freedesktop/Hal/Manager</literal>. This
+ object offers a D-BUS
+ interface, <literal>org.freedesktop.Hal.Manager</literal>, for
querying device objects with the following methods:
</para>
@@ -1723,7 +1726,7 @@
</para>
<programlisting>
- storage_controller.ide -> ide_host -> ide -> block -> block
+ storage_controller.ide -> ide_host -> ide -> block -> block
</programlisting>
<para>
More information about the hal-commit
mailing list