hal/doc/spec hal-spec.html,1.91,1.92

Thu Jun 8 19:19:34 PDT 2006

Update of /cvs/hal/hal/doc/spec
In directory kemper:/tmp/cvs-serv22208/doc/spec

Modified Files:
	hal-spec.html 
Log Message:
2006-06-08  David Zeuthen  <davidz at redhat.com>

	Adds code so addons can claim interfaces and handle the methods on
	them in the addon daemon code. The example here is setting the LCD
	backlight on a Macbook Pro. Actual code for setting the backlight
	is based on code from Nicolas Boichat found on the mactel-linux
	mailing list.

	* hald/linux2/addons/addon-macbookpro-backlight.c: New file.

	* tools/hal-system-power-set-power-save: Bugfix so the right
	backend script is invoked.

	* libhal/libhal.h: Add prototype for libhal_device_claim_interface().

	* libhal/libhal.c (libhal_device_claim_interface): New function.

	* hald/linux2/addons/Makefile.am: Add rules for
	hald-addon-macbookpro-backlight. 

	* hald/hald_dbus.c (device_emit_condition): Only allow helpers,
	e.g.  only messages from direct connections.
	(device_claim_interface): New function to handle the
	ClaimInterface() method
	(do_introspect): Include introspection XML for ClaimInterface()
	and the introspection XML returned by ClaimInterface()
	invocations.
	(reply_from_fwd_message): New function
	(hald_dbus_filter_handle_methods): Handle ClaimInterface() and
	forward messages to the claimed interfaces on the appropriate
	objects.
	(local_server_message_handler): Forward signals from helpers onto
	the system message bus and DTRT when a helper disconnects.

	* hald/device_info.c (handle_spawn): New function. One can now do
	a <spawn udi="foo"> to spawn a child device. See the fdi file below
	for usage.
	(start, spawned_device_callouts_add_done, end):  Handle spawning
	device objects in response to <spawn>.

	* fdi/policy/10osvendor/10-laptop-panel-mgmt-policy.fdi: Add rules
	for matching the Macbook Pro in order to spawn a new device object
	with an addon for handing methods on the org.fd.H.D.LaptopPanel
	interface.

	* hal.conf.in: Allow some interfaces to also emit signals.

	* configure.in: Check for libpci so we can use it as an optional
	dependency. 



Index: hal-spec.html
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.html,v
retrieving revision 1.91
retrieving revision 1.92
diff -u -d -r1.91 -r1.92

--- hal-spec.html	6 Jun 2006 16:03:45 -0000	1.91
+++ hal-spec.html	9 Jun 2006 02:19:32 -0000	1.92
@@ -1,6 +1,6 @@
 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>HAL 0.5.8 Specification</title><link rel="stylesheet" href="docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.69.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.8 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">&lt;<a href="mailto:david at fubar.dk">david at fubar.dk</a>&gt;</code><br>
-          </p></div></div></div></div></div><div><p class="releaseinfo">Version 0.5.8</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="#id2741027">About</a></span></dt><dt><span class="sect1"><a href="#id2685434">Acknowledgements</a></span></dt><dt><span class="sect1"><a href="#ov_halarch">Architecture of HAL</a></span></dt><dt><span class="sect1"><a href="#ov_hal_linux26">HAL on Linux 2.6</a></span></dt><dt><span class="sect1"><a href="#id2753877">Device Objects</a></span></dt><dt><span class="sect1"><a href="#device-capabilities">Device Capabilities</a></span></dt><dt><span class="sect1"><a href="#using-devices">Using devices</a></span></dt></dl></dd><dt><span class="chapter"><a href="#device-properties">2. Device Properties</a></span></dt><dd><dl><dt><span class="sect1"><a href="#properties-metadata">Metadata Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-info">
+          </p></div></div></div></div></div><div><p class="releaseinfo">Version 0.5.8</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="#id2947616">About</a></span></dt><dt><span class="sect1"><a href="#id2909516">Acknowledgements</a></span></dt><dt><span class="sect1"><a href="#ov_halarch">Architecture of HAL</a></span></dt><dt><span class="sect1"><a href="#ov_hal_linux26">HAL on Linux 2.6</a></span></dt><dt><span class="sect1"><a href="#id2964011">Device Objects</a></span></dt><dt><span class="sect1"><a href="#device-capabilities">Device Capabilities</a></span></dt><dt><span class="sect1"><a href="#using-devices">Using devices</a></span></dt></dl></dd><dt><span class="chapter"><a href="#device-properties">2. Device Properties</a></span></dt><dd><dl><dt><span class="sect1"><a href="#properties-metadata">Metadata Properties</a></span></dt><dd><dl><dt><span class="sect2"><a href="#device-properties-info">
         <code class="literal">info</code> namespace
       </a></span></dt><dt><span class="sect2"><a href="#device-properties-linux">
         <code class="literal">linux</code> namespace
@@ -96,7 +96,7 @@
         <code class="literal">storage.policy</code> namespace
       </a></span></dt><dt><span class="sect2"><a href="#device-properties-volume-policy">
         <code class="literal">volume.policy</code> namespace
-      </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#spec-device-info">3. Device Information Files</a></span></dt><dd><dl><dt><span class="sect1"><a href="#fdi-facts">Facts about devices</a></span></dt><dd><dl><dt><span class="sect2"><a href="#fdi-example-mp3player">Example: MP3 player</a></span></dt><dt><span class="sect2"><a href="#fdi-example-camera">Example: Digital Still Camera</a></span></dt><dt><span class="sect2"><a href="#fdi-example-6in1">Example: Card Reader</a></span></dt></dl></dd><dt><span class="sect1"><a href="#fdi-policy">Policy settings for devices</a></span></dt><dd><dl><dt><span class="sect2"><a href="#fdi-example-mountsetting">Storage Devices</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#examples">4. Examples and other stuff</a></span></dt><dd><dl><dt><span class="sect1"><a href="#callouts">Callouts</a></span></dt><dt><span class="sect1"><a href="#dbus-api">D-BUS Network API</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2767694">Interface org.freedesktop.Hal.Manager</a></span></dt><dt><span class="sect2"><a href="#id2757869">Interface org.freedesktop.Hal.Device</a></span></dt></dl></dd><dt><span class="sect1"><a href="#enforcing-policy">Enforcing Policy</a></span></dt><dd><dl><dt><span class="sect2"><a href="#enforcing-stor-vol">Storage Devices</a></span></dt></dl></dd></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="#id2741027">About</a></span></dt><dt><span class="sect1"><a href="#id2685434">Acknowledgements</a></span></dt><dt><span class="sect1"><a href="#ov_halarch">Architecture of HAL</a></span></dt><dt><span class="sect1"><a href="#ov_hal_linux26">HAL on Linux 2.6</a></span></dt><dt><span class="sect1"><a href="#id2753877">Device Objects</a></span></dt><dt><span class="sect1"><a href="#device-capabilities">Device Capabilities</a></span></dt><dt><span class="sect1"><a href="#using-devices">Using devices</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2741027"></a>About</h2></div></div></div><p>
+      </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#spec-device-info">3. Device Information Files</a></span></dt><dd><dl><dt><span class="sect1"><a href="#fdi-facts">Facts about devices</a></span></dt><dd><dl><dt><span class="sect2"><a href="#fdi-example-mp3player">Example: MP3 player</a></span></dt><dt><span class="sect2"><a href="#fdi-example-camera">Example: Digital Still Camera</a></span></dt><dt><span class="sect2"><a href="#fdi-example-6in1">Example: Card Reader</a></span></dt></dl></dd><dt><span class="sect1"><a href="#fdi-policy">Policy settings for devices</a></span></dt><dd><dl><dt><span class="sect2"><a href="#fdi-example-mountsetting">Storage Devices</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#examples">4. Examples and other stuff</a></span></dt><dd><dl><dt><span class="sect1"><a href="#callouts">Callouts</a></span></dt><dt><span class="sect1"><a href="#dbus-api">D-BUS Network API</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2942932">Interface org.freedesktop.Hal.Manager</a></span></dt><dt><span class="sect2"><a href="#id2968014">Interface org.freedesktop.Hal.Device</a></span></dt></dl></dd><dt><span class="sect1"><a href="#enforcing-policy">Enforcing Policy</a></span></dt><dd><dl><dt><span class="sect2"><a href="#enforcing-stor-vol">Storage Devices</a></span></dt></dl></dd></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="#id2947616">About</a></span></dt><dt><span class="sect1"><a href="#id2909516">Acknowledgements</a></span></dt><dt><span class="sect1"><a href="#ov_halarch">Architecture of HAL</a></span></dt><dt><span class="sect1"><a href="#ov_hal_linux26">HAL on Linux 2.6</a></span></dt><dt><span class="sect1"><a href="#id2964011">Device Objects</a></span></dt><dt><span class="sect1"><a href="#device-capabilities">Device Capabilities</a></span></dt><dt><span class="sect1"><a href="#using-devices">Using devices</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2947616"></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
@@ -132,7 +132,7 @@
       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="id2685434"></a>Acknowledgements</h2></div></div></div><p>
+    </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2909516"></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>
@@ -249,7 +249,7 @@
             See <a href="#enforcing-policy" title="Enforcing Policy">the section called &#8220;Enforcing Policy&#8221;</a>
             for more details.
           </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="id2753877"></a>Device Objects</h2></div></div></div><p>
+    </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2964011"></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
@@ -2675,7 +2675,7 @@
          for details.
       </p><pre class="programlisting">
         <a xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" href="../conf/storage-policy-examples.fdi"></a>
-      </pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="examples"></a>Chapter 4. Examples and other stuff</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#callouts">Callouts</a></span></dt><dt><span class="sect1"><a href="#dbus-api">D-BUS Network API</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2767694">Interface org.freedesktop.Hal.Manager</a></span></dt><dt><span class="sect2"><a href="#id2757869">Interface org.freedesktop.Hal.Device</a></span></dt></dl></dd><dt><span class="sect1"><a href="#enforcing-policy">Enforcing Policy</a></span></dt><dd><dl><dt><span class="sect2"><a href="#enforcing-stor-vol">Storage Devices</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="callouts"></a>Callouts</h2></div></div></div><p>
+      </pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="examples"></a>Chapter 4. Examples and other stuff</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#callouts">Callouts</a></span></dt><dt><span class="sect1"><a href="#dbus-api">D-BUS Network API</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id2942932">Interface org.freedesktop.Hal.Manager</a></span></dt><dt><span class="sect2"><a href="#id2968014">Interface org.freedesktop.Hal.Device</a></span></dt></dl></dd><dt><span class="sect1"><a href="#enforcing-policy">Enforcing Policy</a></span></dt><dd><dl><dt><span class="sect2"><a href="#enforcing-stor-vol">Storage Devices</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="callouts"></a>Callouts</h2></div></div></div><p>
       Callouts are programs invoked when the device object list is
       modified. As such, callouts can be used to maintain system-wide
       policy (that may be specific to the particular OS) such as
@@ -2742,7 +2742,7 @@
       and possibly callouts. Eventually, the device transitions to the
       GDL (global device list) and first then it becomes ''visible'' for
       desktop applications.
-    </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2767694"></a>Interface org.freedesktop.Hal.Manager</h3></div></div></div><p>
+    </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2942932"></a>Interface org.freedesktop.Hal.Manager</h3></div></div></div><p>
         Using D-BUS terminology, the HAL daemon provides the D-BUS
         service <code class="literal">org.freedesktop.Hal</code>. This service
         offers a D-BUS object at a well-known
@@ -2799,7 +2799,7 @@
 # @param  udi                   Unique Device Id
 #
 void NewCapability(string udi, string capability)
-      </pre><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2757793"></a>Example</h4></div></div></div><p>
+      </pre><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2967973"></a>Example</h4></div></div></div><p>
           The following brief Python program demonstrates some of the API
         </p><pre class="programlisting">
           <a xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" href="example-manager.py"></a>
@@ -2840,7 +2840,7 @@
 Device /org/freedesktop/Hal/devices/usb_46d_c001_410_-1_noserial was removed
 Device /org/freedesktop/Hal/devices/usbif_usb_46d_c001_410_-1_noserial_0 was removed
         </pre><p>
-        </p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2757869"></a>Interface org.freedesktop.Hal.Device</h3></div></div></div><p>
+        </p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2968014"></a>Interface org.freedesktop.Hal.Device</h3></div></div></div><p>
         Applications use
         the <code class="literal">org.freedesktop.Hal.Manager</code> interface to
         locate the device objects they are interested in. When a device


