[PATCH 6/6] document singleton addons
Rob Taylor
rob.taylor at codethink.co.uk
Fri Jun 22 05:21:18 PDT 2007
Adds documentation to the spec for info.addons.singleton and the org.freedesktop.Hal.SingletonAddon interface.
---
doc/spec/hal-spec-interfaces.xml | 100 +++++++++++++++++++++++++++++++++++++-
doc/spec/hal-spec-properties.xml | 75 ++++++++++++++++++++++++++++-
2 files changed, 172 insertions(+), 3 deletions(-)
diff --git a/doc/spec/hal-spec-interfaces.xml b/doc/spec/hal-spec-interfaces.xml
index 2511011..4e5050f 100644
--- a/doc/spec/hal-spec-interfaces.xml
+++ b/doc/spec/hal-spec-interfaces.xml
@@ -142,7 +142,18 @@ $ dbus-send --system --print-reply --dest=org.freedesktop.Hal \
<xref linkend="locking"/> for details.
</entry>
</row>
-
+ <row>
+ <entry>SingletonAddonIsReady</entry>
+ <entry></entry>
+ <entry>String command_line</entry>
+ <entry>PermissionDenied, SyntaxError</entry>
+ <entry>
+ Called by singleton addons to signal that they are
+ ready to handle devices. A singleton addon should
+ implement the <link linkend="interface-singleton-addon">
+ org.freedesktop.Hal.Singleton</link> interface.
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
@@ -643,7 +654,6 @@ $ dbus-send --system --print-reply --dest=org.freedesktop.Hal \
</informaltable>
</sect1>
-
<sect1 id="interface-device-systempower">
<title>org.freedesktop.Hal.Device.SystemPowerManagement interface</title>
<para>
@@ -1281,6 +1291,92 @@ $ dbus-send --system --print-reply --dest=org.freedesktop.Hal \
</sect1>
+ <sect1 id="interface-singleton-addon">
+ <title><literal>org.freedesktop.Hal.SingletonAddon</literal> interface</title>
+ <para>
+ 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
+ <literal>/org/freedesktop/Hal/Manager</literal>.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Returns</entry>
+ <entry>Parameters</entry>
+ <entry>Throws</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>DeviceAdded</literal>
+ </entry>
+ <entry>
+ <para><literal>String udi</literal></para>
+ <para><literal>Dict(String,Variant) property_set</literal></para>
+ </entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ <para>
+ Called by the HAL Manager when a device is added that has
+ this singleton listed in
+ <link linkend="device-properties-info-singleton-addons">
+ <literal>info.addons.singleton</literal>
+ </link>
+ </para>
+ <para>
+ An addon implementing this function should start handling the
+ device before returning, and keep track that is is handling this
+ udi.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>DeviceRemoved</literal>
+ </entry>
+ <entry>
+ <para><literal>String udi</literal></para>
+ <para><literal>Dict(String,Variant) property_set</literal></para>
+ </entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>
+ <para>
+ Called by the HAL Manager when a device is added that has
+ this singleton listed in
+ <link linkend="device-properties-info-singleton-addons">
+ <literal>info.addons.singleton</literal>
+ </link>
+ </para>
+ <para>
+ The implementer of this function should keep track of
+ which devices it is still handling and exit when no longer
+ handling any devices.
+ </para>
+ </entry>
+ </row>
+
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ This interface does not export any methods.
+ </para>
+ </sect1>
+
<!--
<sect1 id="interface-device-foo">
<title>org.freedesktop.Hal.Device.Foo interface</title>
diff --git a/doc/spec/hal-spec-properties.xml b/doc/spec/hal-spec-properties.xml
index 730f826..c94e2a8 100644
--- a/doc/spec/hal-spec-properties.xml
+++ b/doc/spec/hal-spec-properties.xml
@@ -434,7 +434,80 @@ CK_SESSION_UID_Session3=501
</informaltable>
</sect2>
- <sect2 id="device-properties-info-method-calls">
+ <sect2 id="device-properties-info-singleton-addons">
+ <title>Singleton Addons</title>
+
+ <para>
+ 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
+ <link linkend="interface-singleton-addon">
+ <literal>org.freedesktop.Hal.SingletonAddon</literal>
+ </link>
+ interface. on the path
+ <literal>/org/freedesktop/Hal/Singleton</literal> path on
+ the direct connection to the HAL daemon.
+ </para>
+ <para>
+ When a device is added with an <literal>info.addons.singleton</literal>
+ 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 <literal>SingletonAddonIsReady</literal> on
+ <link linkend="interface-manager">
+ <literal>org.freedesktop.Hal.Manager</literal>
+ </link> interface, it will receive
+ <literal>DeviceAdded</literal> calls on its
+ <link linkend="interface-singleton-addon">
+ <literal>org.freedesktop.Hal.SingletonAddon</literal>
+ </link>
+ interface for all devices that have
+ its commandline in <literal>info.addons.singletona</literal>.
+ </para>
+ <para>
+ If a device is added and the singleton specified in
+ <literal>info.addons.singleton</literal> is already running, the
+ singleton will recieve <literal>DeviceAdded</literal> on its
+ <link linkend="interface-singleton-addon">
+ <literal>org.freedesktop.Hal.SingletonAddon</literal>
+ </link>
+ interface for that new device. </para>
+ <para>
+ When a device is removed that is being handled by a singleton, the
+ singleton will recieve <literal>DeviceRemoved</literal> on
+ <link linkend="interface-singleton-addon">
+ <literal>org.freedesktop.Hal.SingletonAddon</literal>
+ </link>.
+ When it is no longer handling any more devices it should exit cleanly.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Key (type)</entry>
+ <entry>Values</entry>
+ <entry>Mandatory</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>info.addons.singleton</literal> (strlist)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ A list of commandlines for singleton addons which should
+ service this device.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ </sect2>
+ <sect2 id="device-properties-info-method-calls">
<title>Method calls</title>
<para>
--
1.5.2-rc3.GIT
--------------010609010103020107060701--
More information about the hal
mailing list