hal/doc/spec hal-arch.dia, 1.2, 1.3 hal-arch.png, 1.2,
1.3 hal-linux26.dia, 1.2, 1.3 hal-linux26.png, 1.2,
1.3 hal-spec.html, 1.21, 1.22 hal-spec.xml.in, 1.19, 1.20
David Zeuthen
david at freedesktop.org
Sun Sep 19 09:32:17 PDT 2004
Update of /cvs/hal/hal/doc/spec
In directory gabe:/tmp/cvs-serv15910/doc/spec
Modified Files:
hal-arch.dia hal-arch.png hal-linux26.dia hal-linux26.png
hal-spec.html hal-spec.xml.in
Log Message:
2004-09-19 David Zeuthen <david at fubar.dk>
* hald/hald_dbus.c (agent_device_matches): Removed
(agent_merge_properties): Removed
(agent_manager_remove): Removed
(agent_manager_commit_to_gdl): Removed
(agent_manager_new_device): Removed
(filter_function): Removed all the AgentManager methods
(raise_udi_in_use): Removed
* doc/spec/hal-spec.xml.in: Add docs for info.locked. Remove section
about HAL agents as they are now gone. Fixed up renaming of scsi_device
to scsi.
* doc/spec/hal-arch.dia: Remove HAL Agents
* doc/spec/hal-linux26.dia: Update diagram since we now use a local
socket from hal.hotplug and hal.dev helpers.
* examples/locking.py: New file; shows how to use locking
Index: hal-arch.dia
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-arch.dia,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
Binary files /tmp/cvs684KzH and /tmp/cvsodR43e differ
Index: hal-arch.png
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-arch.png,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
Binary files /tmp/cvscD1T6H and /tmp/cvsWYr3Di differ
Index: hal-linux26.dia
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-linux26.dia,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
Binary files /tmp/cvspcfdbL and /tmp/cvsgIn1gm differ
Index: hal-linux26.png
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-linux26.png,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
Binary files /tmp/cvsSDdZlJ and /tmp/cvsY91uOi differ
Index: hal-spec.html
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.html,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -d -r1.21 -r1.22
--- hal-spec.html 19 Sep 2004 13:47:52 -0000 1.21
+++ hal-spec.html 19 Sep 2004 16:32:15 -0000 1.22
@@ -105,7 +105,7 @@
></DD
><DT
><A
-HREF="#AEN114"
+HREF="#AEN108"
>Device Objects</A
></DT
><DT
@@ -210,7 +210,7 @@
HREF="#device-properties-scsi"
><TT
CLASS="literal"
->scsi_device</TT
+>scsi</TT
> namespace</A
></DT
><DT
@@ -400,28 +400,23 @@
><DL
><DT
><A
-HREF="#AEN1808"
+HREF="#AEN1825"
>Interface org.freedesktop.Hal.Manager</A
></DT
><DD
><DL
><DT
><A
-HREF="#AEN1819"
+HREF="#AEN1836"
>Example</A
></DT
></DL
></DD
><DT
><A
-HREF="#AEN1827"
+HREF="#AEN1844"
>Interface org.freedesktop.Hal.Device</A
></DT
-><DT
-><A
-HREF="#AEN1836"
->Interface org.freedesktop.Hal.AgentManager</A
-></DT
></DL
></DD
><DT
@@ -674,35 +669,6 @@
><P
> <I
CLASS="emphasis"
->HAL agents</I
-></P
-><P
->
-
- The term <I
-CLASS="emphasis"
->HAL agent</I
-> is used to
- characterize a program that is involved in the detection and
- monitoring of devices not supported directly by the HAL
- daemon.
-
- </P
-><P
->
- Any program can be a HAL agent; all it means is that the
- program communicates with the HAL daemon using a specific
- interface. Examples of use that come to mind are prototypes
- for supporting vendor or OEM specific buses/devices,
- integration of existing device detection/monitoring
- frameworks etc.
-
- </P
-></LI
-><LI
-><P
-> <I
-CLASS="emphasis"
>Applications</I
></P
><P
@@ -767,18 +733,18 @@
</P
><P
>
- The HAL uses D-BUS to provide a ''network API'' to both desktop
- applications and the aforementioned HAL agents. As D-BUS is
- designed to be language independent, potentially many languages
- / runtime systems will be able to easily access the services
- offered by HAL. The D-BUS API is detailed in <A
+ The HAL uses D-BUS to provide a ''network API'' to
+ applications. As D-BUS is designed to be language independent,
+ potentially many languages / runtime systems will be able to
+ easily access the services offered by HAL. The D-BUS API is
+ detailed in <A
HREF="#dbus-api"
>the chapter called <I
>D-BUS Network API</I
></A
->. Note that HAL doesn't enforce any policy
- at all, this is left for desktop environments and operating
- systems vendors to implement. However, to ensure
+>. Note that HAL doesn't
+ enforce any policy at all, this is left for desktop environments
+ and operating systems vendors to implement. However, to ensure
interoperability between operating systems and desktop
environments, recommendations and best practises on how to
enforce policy is discussed in <A
@@ -903,7 +869,7 @@
CLASS="chapter"
><HR><H1
><A
-NAME="AEN114"
+NAME="AEN108"
></A
>Device Objects</H1
><P
@@ -1366,7 +1332,7 @@
><P
></P
><A
-NAME="AEN201"
+NAME="AEN195"
></A
><TABLE
BORDER="1"
@@ -1394,7 +1360,7 @@
>info.bus</TT
> (string)</TD
><TD
->pci, usb, ide_host, ide, block, usb, usbif, scsi_host, scsi_device</TD
+>pci, usb, ide_host, ide, block, usb, usbif, scsi_host, scsi</TD
><TD
>Yes</TD
><TD
@@ -1510,6 +1476,72 @@
>The UDI of the device object that this device object
is connected to.</TD
></TR
+><TR
+><TD
+><TT
+CLASS="literal"
+>info.locked</TT
+> (bool)</TD
+><TD
+> </TD
+><TD
+>No</TD
+><TD
+> If this property is available and set
+ to <TT
+CLASS="literal"
+>TRUE</TT
+> 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
+><TT
+CLASS="literal"
+>info.locked.reason</TT
+> (string)</TD
+><TD
+> example: ''The optical drive is currently being used to
+ record a CD-RW disc.''
+ </TD
+><TD
+> Only available if <TT
+CLASS="literal"
+>info.locked</TT
+> is set
+ to <TT
+CLASS="literal"
+>TRUE</TT
+>.
+ </TD
+><TD
+>A localized text suitable for UI display</TD
+></TR
+><TR
+><TD
+><TT
+CLASS="literal"
+>info.locked.dbus_service</TT
+> (string)</TD
+><TD
+>example: :1.278</TD
+><TD
+> Only available if <TT
+CLASS="literal"
+>info.locked</TT
+> is set
+ to <TT
+CLASS="literal"
+>TRUE</TT
+>.
+ </TD
+><TD
+>The base D-BUS service of the process holding the lock.</TD
+></TR
></TBODY
></TABLE
><P
@@ -1536,7 +1568,7 @@
><P
></P
><A
-NAME="AEN269"
+NAME="AEN286"
></A
><TABLE
BORDER="1"
@@ -1675,7 +1707,7 @@
><P
></P
><A
-NAME="AEN313"
+NAME="AEN330"
></A
><TABLE
BORDER="1"
@@ -1898,7 +1930,7 @@
><P
></P
><A
-NAME="AEN402"
+NAME="AEN419"
></A
><TABLE
BORDER="1"
@@ -2290,7 +2322,7 @@
><P
></P
><A
-NAME="AEN565"
+NAME="AEN582"
></A
><TABLE
BORDER="1"
@@ -2419,7 +2451,7 @@
><P
></P
><A
-NAME="AEN612"
+NAME="AEN629"
></A
><TABLE
BORDER="1"
@@ -2504,7 +2536,7 @@
><P
></P
><A
-NAME="AEN640"
+NAME="AEN657"
></A
><TABLE
BORDER="1"
@@ -2600,7 +2632,7 @@
><P
></P
><A
-NAME="AEN670"
+NAME="AEN687"
></A
><TABLE
BORDER="1"
@@ -2648,7 +2680,7 @@
NAME="device-properties-scsi"
><TT
CLASS="literal"
->scsi_device</TT
+>scsi</TT
> namespace</A
></H3
><P
@@ -2659,7 +2691,7 @@
>info.bus</TT
> equals <TT
CLASS="literal"
->scsi_device</TT
+>scsi</TT
>.
The following properties are available for such device objects.
@@ -2669,7 +2701,7 @@
><P
></P
><A
-NAME="AEN691"
+NAME="AEN708"
></A
><TABLE
BORDER="1"
@@ -2786,7 +2818,7 @@
><P
></P
><A
-NAME="AEN732"
+NAME="AEN749"
></A
><TABLE
BORDER="1"
@@ -2908,7 +2940,7 @@
><P
></P
><A
-NAME="AEN777"
+NAME="AEN794"
></A
><TABLE
BORDER="1"
@@ -3029,7 +3061,7 @@
><P
></P
><A
-NAME="AEN822"
+NAME="AEN839"
></A
><TABLE
BORDER="1"
@@ -3102,7 +3134,7 @@
><P
></P
><A
-NAME="AEN844"
+NAME="AEN861"
></A
><TABLE
BORDER="1"
@@ -3299,7 +3331,7 @@
><P
></P
><A
-NAME="AEN904"
+NAME="AEN921"
></A
><TABLE
BORDER="1"
@@ -3522,7 +3554,7 @@
><P
></P
><A
-NAME="AEN1000"
+NAME="AEN1017"
></A
><TABLE
BORDER="1"
@@ -3660,7 +3692,7 @@
><P
></P
><A
-NAME="AEN1043"
+NAME="AEN1060"
></A
><TABLE
BORDER="1"
@@ -3771,7 +3803,7 @@
><P
></P
><A
-NAME="AEN1079"
+NAME="AEN1096"
></A
><TABLE
BORDER="1"
@@ -4033,7 +4065,7 @@
><P
></P
><A
-NAME="AEN1186"
+NAME="AEN1203"
></A
><TABLE
BORDER="1"
@@ -4452,7 +4484,7 @@
><P
></P
><A
-NAME="AEN1355"
+NAME="AEN1372"
></A
><TABLE
BORDER="1"
@@ -4651,7 +4683,7 @@
><P
></P
><A
-NAME="AEN1435"
+NAME="AEN1452"
></A
><TABLE
BORDER="1"
@@ -4805,7 +4837,7 @@
><P
></P
><A
-NAME="AEN1493"
+NAME="AEN1510"
></A
><TABLE
BORDER="1"
@@ -4936,7 +4968,7 @@
><P
></P
><A
-NAME="AEN1535"
+NAME="AEN1552"
></A
><TABLE
BORDER="1"
@@ -5009,7 +5041,7 @@
><P
></P
><A
-NAME="AEN1557"
+NAME="AEN1574"
></A
><TABLE
BORDER="1"
@@ -5076,7 +5108,7 @@
><P
></P
><A
-NAME="AEN1577"
+NAME="AEN1594"
></A
><TABLE
BORDER="1"
@@ -5141,7 +5173,7 @@
><P
></P
><A
-NAME="AEN1597"
+NAME="AEN1614"
></A
><TABLE
BORDER="1"
@@ -5268,7 +5300,7 @@
><P
></P
><A
-NAME="AEN1641"
+NAME="AEN1658"
></A
><TABLE
BORDER="1"
@@ -5415,7 +5447,7 @@
><P
></P
><A
-NAME="AEN1689"
+NAME="AEN1706"
></A
><TABLE
BORDER="1"
@@ -5769,7 +5801,7 @@
><P
></P
><A
-NAME="AEN1766"
+NAME="AEN1783"
></A
><TABLE
BORDER="1"
@@ -5929,7 +5961,7 @@
><HR><H2
CLASS="sect1"
><A
-NAME="AEN1808"
+NAME="AEN1825"
>Interface org.freedesktop.Hal.Manager</A
></H2
><P
@@ -6045,7 +6077,7 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN1819"
+NAME="AEN1836"
>Example</A
></H3
><P
@@ -6163,7 +6195,7 @@
><HR><H2
CLASS="sect1"
><A
-NAME="AEN1827"
+NAME="AEN1844"
>Interface org.freedesktop.Hal.Device</A
></H2
><P
@@ -6328,102 +6360,6 @@
</P
></DIV
-><DIV
-CLASS="sect1"
-><HR><H2
-CLASS="sect1"
-><A
-NAME="AEN1836"
->Interface org.freedesktop.Hal.AgentManager</A
-></H2
-><P
->
- The API described above is available to all applications. There is
- an additional D-BUS interface on the /org/freedesktop/Hal/Manager
- object called org.freedesktop.Hal.AgentManager which is only available
- for processes running with administrative privileges.
- </P
-><TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="100%"
-><TR
-><TD
-><PRE
-CLASS="programlisting"
->
-# Create a new device object not in the GDL (ie. hidden from
-# applications). This object can be obtained using the given UDI as
-# as the D-BUS object reference.
-#
-# The object implements the org.freedesktop.Hal.Device interface
-#
-# @return Temporary UDI for new device object
-#
-string NewDevice()
-
-# When a device have been built, an application can add it to the GDL.
-#
-# A side-effect of this call, is that the Manager object will emit the
-# signal DeviceAdded.
-#
-# @param tempUdi Temporary UDI as obtained from the NewDevice call
-# @param newUdi New UDI to use.
-# @raises org.freedesktop.Hal.(NoSuchDevice|UdiInUse)
-#
-void CommitToGDL(string tempUdi, string newUdi)
-
-# Remove a device object.
-#
-# Depending on the info.persistent property, the device may not be removed but
-# rather acquire the property info.not_available with value true.
-#
-# @param udi UDI of device
-# @raises org.freedesktop.Hal.NoSuchDevice
-#
-void Remove(string udi)
-
-# Merge all properties from one device to another device.
-#
-# If the source device got any capabilities, then the target device
-# will acquire these capabilities and a NewCapability signal will be
-# emitted for the target device for every capability in the source
-# device.
-#
-# @param targetUdi UDI of device to receive properties
-# @param sourceUdi UDI of device to copy properties from
-# @raises org.freedesktop.Hal.NoSuchDevice
-#
-void MergeProperties(string targetUdi, string sourceUdi)
-
-# Checks that all properties where keys, starting with a given value
-# (namespace), of the first device is present in the second device and that
-# they got the same value and type.
-#
-# Note that the other inclusion isn't tested, so there could be
-# properties (from the given namespace) in the second device not present
-# in the first device.
-#
-# @param udi1 UDI of device 1
-# @param udi2 UDI of device 2
-# @param namespace Namespace used for matching, e.g. 'usb'
-# @return TRUE if, and only if, all properties starting
-# with the namespace parameter from udi1 is
-# in udi2 and assume the same value
-# @raises org.freedesktop.Hal.NoSuchDevice
-#
-bool DeviceMatches(string udi1, string udi2, string namespace)
-
-</PRE
-></TD
-></TR
-></TABLE
-><P
-> HAL Agents uses the org.freedesktop.Hal.AgentManager API when
- discovering devices either through detection, handling hotplug
- events or through some other way.
- </P
-></DIV
></DIV
><DIV
CLASS="chapter"
Index: hal-spec.xml.in
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.xml.in,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -d -r1.19 -r1.20
--- hal-spec.xml.in 17 Sep 2004 17:05:48 -0000 1.19
+++ hal-spec.xml.in 19 Sep 2004 16:32:15 -0000 1.20
@@ -174,27 +174,6 @@
<!-- ####################################################### -->
<listitem><para>
- <emphasis>HAL agents</emphasis></para><para>
-
- The term <emphasis>HAL agent</emphasis> is used to
- characterize a program that is involved in the detection and
- monitoring of devices not supported directly by the HAL
- daemon.
-
- </para><para>
-
- Any program can be a HAL agent; all it means is that the
- program communicates with the HAL daemon using a specific
- interface. Examples of use that come to mind are prototypes
- for supporting vendor or OEM specific buses/devices,
- integration of existing device detection/monitoring
- frameworks etc.
-
- </para></listitem>
-
- <!-- ####################################################### -->
-
- <listitem><para>
<emphasis>Applications</emphasis></para><para>
This represents the end consumers of the HAL and comprises
@@ -246,14 +225,13 @@
</para>
<para>
- The HAL uses D-BUS to provide a ''network API'' to both desktop
- applications and the aforementioned HAL agents. As D-BUS is
- designed to be language independent, potentially many languages
- / runtime systems will be able to easily access the services
- offered by HAL. The D-BUS API is detailed in <xref
- linkend="dbus-api"/>. Note that HAL doesn't enforce any policy
- at all, this is left for desktop environments and operating
- systems vendors to implement. However, to ensure
+ The HAL uses D-BUS to provide a ''network API'' to
+ applications. As D-BUS is designed to be language independent,
+ potentially many languages / runtime systems will be able to
+ easily access the services offered by HAL. The D-BUS API is
+ detailed in <xref linkend="dbus-api"/>. Note that HAL doesn't
+ enforce any policy at all, this is left for desktop environments
+ and operating systems vendors to implement. However, to ensure
interoperability between operating systems and desktop
environments, recommendations and best practises on how to
enforce policy is discussed in <xref
@@ -640,7 +618,7 @@
<row>
<entry><literal>info.bus</literal> (string)</entry>
- <entry>pci, usb, ide_host, ide, block, usb, usbif, scsi_host, scsi_device</entry>
+ <entry>pci, usb, ide_host, ide, block, usb, usbif, scsi_host, scsi</entry>
<entry>Yes</entry>
<entry>Describes what ''physical'' bus the device is connected to</entry>
</row>
@@ -696,6 +674,41 @@
is connected to.</entry>
</row>
+ <row>
+ <entry><literal>info.locked</literal> (bool)</entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ If this property is available and set
+ to <literal>TRUE</literal> 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.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>info.locked.reason</literal> (string)</entry>
+ <entry>
+ example: ''The optical drive is currently being used to
+ record a CD-RW disc.''
+ </entry>
+ <entry>
+ Only available if <literal>info.locked</literal> is set
+ to <literal>TRUE</literal>.
+ </entry>
+ <entry>A localized text suitable for UI display</entry>
+ </row>
+ <row>
+ <entry><literal>info.locked.dbus_service</literal> (string)</entry>
+ <entry>example: :1.278</entry>
+ <entry>
+ Only available if <literal>info.locked</literal> is set
+ to <literal>TRUE</literal>.
+ </entry>
+ <entry>The base D-BUS service of the process holding the lock.</entry>
+ </row>
+
</tbody>
</tgroup>
</informaltable>
@@ -1249,11 +1262,11 @@
<sect2 id="device-properties-scsi">
- <title><literal>scsi_device</literal> namespace</title>
+ <title><literal>scsi</literal> namespace</title>
<para>
SCSI devices are represented by device objects where
- <literal>info.bus</literal> equals <literal>scsi_device</literal>.
+ <literal>info.bus</literal> equals <literal>scsi</literal>.
The following properties are available for such device objects.
</para>
@@ -3277,87 +3290,6 @@
</sect1>
- <sect1><title>Interface org.freedesktop.Hal.AgentManager</title><para>
-
- The API described above is available to all applications. There is
- an additional D-BUS interface on the /org/freedesktop/Hal/Manager
- object called org.freedesktop.Hal.AgentManager which is only available
- for processes running with administrative privileges.
- </para>
-
-<programlisting>
-
-# Create a new device object not in the GDL (ie. hidden from
-# applications). This object can be obtained using the given UDI as
-# as the D-BUS object reference.
-#
-# The object implements the org.freedesktop.Hal.Device interface
-#
-# @return Temporary UDI for new device object
-#
-string NewDevice()
-
-# When a device have been built, an application can add it to the GDL.
-#
-# A side-effect of this call, is that the Manager object will emit the
-# signal DeviceAdded.
-#
-# @param tempUdi Temporary UDI as obtained from the NewDevice call
-# @param newUdi New UDI to use.
-# @raises org.freedesktop.Hal.(NoSuchDevice|UdiInUse)
-#
-void CommitToGDL(string tempUdi, string newUdi)
-
-# Remove a device object.
-#
-# Depending on the info.persistent property, the device may not be removed but
-# rather acquire the property info.not_available with value true.
-#
-# @param udi UDI of device
-# @raises org.freedesktop.Hal.NoSuchDevice
-#
-void Remove(string udi)
-
-# Merge all properties from one device to another device.
-#
-# If the source device got any capabilities, then the target device
-# will acquire these capabilities and a NewCapability signal will be
-# emitted for the target device for every capability in the source
-# device.
-#
-# @param targetUdi UDI of device to receive properties
-# @param sourceUdi UDI of device to copy properties from
-# @raises org.freedesktop.Hal.NoSuchDevice
-#
-void MergeProperties(string targetUdi, string sourceUdi)
-
-# Checks that all properties where keys, starting with a given value
-# (namespace), of the first device is present in the second device and that
-# they got the same value and type.
-#
-# Note that the other inclusion isn't tested, so there could be
-# properties (from the given namespace) in the second device not present
-# in the first device.
-#
-# @param udi1 UDI of device 1
-# @param udi2 UDI of device 2
-# @param namespace Namespace used for matching, e.g. 'usb'
-# @return TRUE if, and only if, all properties starting
-# with the namespace parameter from udi1 is
-# in udi2 and assume the same value
-# @raises org.freedesktop.Hal.NoSuchDevice
-#
-bool DeviceMatches(string udi1, string udi2, string namespace)
-
-</programlisting>
- <para>
- HAL Agents uses the org.freedesktop.Hal.AgentManager API when
- discovering devices either through detection, handling hotplug
- events or through some other way.
- </para>
-
- </sect1>
-
</chapter>
More information about the hal-commit
mailing list