hal/doc/spec Makefile.am, 1.3, 1.4 examply-manager.py, NONE,
1.1 hal-spec.html, 1.6, 1.7 hal-spec.xml.in, 1.5, 1.6
David Zeuthen
david at freedesktop.org
Tue Aug 3 09:09:21 PDT 2004
Update of /cvs/hal/hal/doc/spec
In directory pdx:/tmp/cvs-serv13940/doc/spec
Modified Files:
Makefile.am hal-spec.html hal-spec.xml.in
Added Files:
examply-manager.py
Log Message:
2004-08-03 David Zeuthen <david at fubar.dk>
* doc/spec/examply-manager.py: New file
* doc/spec/hal-spec.xml.in: Work in progress
Index: Makefile.am
===================================================================
RCS file: /cvs/hal/hal/doc/spec/Makefile.am,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- Makefile.am 2 Aug 2004 15:10:03 -0000 1.3
+++ Makefile.am 3 Aug 2004 16:09:19 -0000 1.4
@@ -1,7 +1,7 @@
if DOCBOOK_DOCS_ENABLED
-EXTRA_DIST = \
+EXTRA_DIST = \
hal-spec.xml
FIGURE_FILES = \
@@ -21,7 +21,7 @@
clean-local:
rm -f *~
- rm -f hal-spec.html
+ rm -f hal-spec.html hal-spec.xml
endif # DOCBOOK_DOCS_ENABLED
--- NEW FILE: examply-manager.py ---
#!/usr/bin/python
import gtk
import dbus
def device_added(interface, signal_name, service, path, message):
[udi] = message.get_args_list ()
print 'Device %s was added'%udi
def device_removed(interface, signal_name, service, path, message):
[udi] = message.get_args_list ()
print 'Device %s was removed'%udi
bus = dbus.Bus (dbus.Bus.TYPE_SYSTEM)
hal_service = bus.get_service ('org.freedesktop.Hal')
hal_manager = hal_service.get_object ('/org/freedesktop/Hal/Manager',
'org.freedesktop.Hal.Manager')
devices = hal_manager.GetAllDevices ()
for d in devices:
print 'Found device %s'%d
bus.add_signal_receiver(device_added,
'DeviceAdded',
'org.freedesktop.Hal.Manager',
'org.freedesktop.Hal',
'/org/freedesktop/Hal/Manager')
bus.add_signal_receiver(device_removed,
'DeviceRemoved',
'org.freedesktop.Hal.Manager',
'org.freedesktop.Hal',
'/org/freedesktop/Hal/Manager')
gtk.main()
Index: hal-spec.html
===================================================================
RCS file: /cvs/hal/hal/doc/spec/hal-spec.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- hal-spec.html 2 Aug 2004 21:56:24 -0000 1.6
+++ hal-spec.html 3 Aug 2004 16:09:19 -0000 1.7
@@ -845,14 +845,14 @@
#
# @param key Key, for example 'block.fstype'
# @param value Value, for example 'ext3'
-# @return List of UDI's
+# @return Array of UDI's, may be empty
#
array{string} FindDeviceStringMatch(string key, string value)
# Find the set of devices in the GDL that has a given capability
#
# @param capability Capability, for example 'volume'
-# @return List of UDI's
+# @return Array of UDI's, may be empty
#
array{string} FindDeviceByCapability(string capability)
@@ -863,10 +863,18 @@
><P
>
This object also emits the following signals on the
- org.freedesktop.Hal.Manager interface that applications can
- subscribe to using D-BUS:
+ <TT
+CLASS="literal"
+>/org/freedesktop/Hal/Manager</TT
+> object on the
+ <TT
+CLASS="literal"
+>org.freedesktop.Hal.Manager</TT
+> interface that
+ applications can subscribe to using D-BUS:
-<TABLE
+ </P
+><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
@@ -899,25 +907,153 @@
></TD
></TR
></TABLE
->
+><DIV
+CLASS="sect3"
+><HR><H4
+CLASS="sect3"
+><A
+NAME="AEN162"
+>Example</A
+></H4
+><P
+>
+ The following brief Python program demonstrates some of the API
+
+ </P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="programlisting"
+> #!/usr/bin/python
+
+import gtk
+import dbus
+
+def device_added(interface, signal_name, service, path, message):
+ [udi] = message.get_args_list ()
+ print 'Device %s was added'%udi
+
+def device_removed(interface, signal_name, service, path, message):
+ [udi] = message.get_args_list ()
+ print 'Device %s was removed'%udi
+
+
+bus = dbus.Bus (dbus.Bus.TYPE_SYSTEM)
+hal_service = bus.get_service ('org.freedesktop.Hal')
+hal_manager = hal_service.get_object ('/org/freedesktop/Hal/Manager',
+ 'org.freedesktop.Hal.Manager')
+
+devices = hal_manager.GetAllDevices ()
+for d in devices:
+ print 'Found device %s'%d
+
+bus.add_signal_receiver(device_added,
+ 'DeviceAdded',
+ 'org.freedesktop.Hal.Manager',
+ 'org.freedesktop.Hal',
+ '/org/freedesktop/Hal/Manager')
+bus.add_signal_receiver(device_removed,
+ 'DeviceRemoved',
+ 'org.freedesktop.Hal.Manager',
+ 'org.freedesktop.Hal',
+ '/org/freedesktop/Hal/Manager')
+gtk.main()
+
+
+
+
+
+</PRE
+></TD
+></TR
+></TABLE
+><P
+>
+ which gives the following output
+
+ </P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="programlisting"
+> Found device /org/freedesktop/Hal/devices/block_TORiSAN DVD-ROM DRD-U624-00000000000000000001-disc
+Found device /org/freedesktop/Hal/devices/block_TORiSAN DVD-ROM DRD-U624-00000000000000000001
+Found device /org/freedesktop/Hal/devices/block_37332a77-105e-4e76-8e99-27d3746e0531
+Found device /org/freedesktop/Hal/devices/block_3_2
+Found device /org/freedesktop/Hal/devices/block_LS-120 SLIM3 00 UHD Floppy-0208MBA00211
+Found device /org/freedesktop/Hal/devices/block_IC25N020ATCS05-0-CLP225F2G3UR4A
+Found device /org/freedesktop/Hal/devices/ide_1_1
+Found device /org/freedesktop/Hal/devices/ide_0_0
+Found device /org/freedesktop/Hal/devices/ide_1_0
+Found device /org/freedesktop/Hal/devices/usbif_usb_0_0_206_-1_0000:00:07.2_0
+Found device /org/freedesktop/Hal/devices/ide_host_0
+Found device /org/freedesktop/Hal/devices/ide_host_1
+Found device /org/freedesktop/Hal/devices/pci_104c_8400
+Found device /org/freedesktop/Hal/devices/usb_0_0_206_-1_0000:00:07.2
+Found device /org/freedesktop/Hal/devices/pci_1002_4c4d
+Found device /org/freedesktop/Hal/devices/pci_125d_1978
+Found device /org/freedesktop/Hal/devices/pci_8086_7111
+Found device /org/freedesktop/Hal/devices/pci_104c_ac1c/0
+Found device /org/freedesktop/Hal/devices/pci_8086_7112
+Found device /org/freedesktop/Hal/devices/pci_8086_7110
+Found device /org/freedesktop/Hal/devices/input_13_65
+Found device /org/freedesktop/Hal/devices/pci_104c_ac1c
+Found device /org/freedesktop/Hal/devices/pci_8086_7190
+Found device /org/freedesktop/Hal/devices/input_13_64
+Found device /org/freedesktop/Hal/devices/pci_8086_7113
+Found device /org/freedesktop/Hal/devices/pci_8086_7191
+Found device /org/freedesktop/Hal/devices/computer
+(insert USB mouse)
+
+Device /org/freedesktop/Hal/devices/usb_46d_c001_410_-1_noserial was added
+Device /org/freedesktop/Hal/devices/usbif_usb_46d_c001_410_-1_noserial_0 was added
+
+(remove USB mouse)
+
+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
+></TD
+></TR
+></TABLE
+><P
+>
</P
></DIV
+></DIV
><DIV
CLASS="sect2"
><HR><H3
CLASS="sect2"
><A
-NAME="AEN160"
+NAME="AEN170"
>Interface org.freedesktop.Hal.Device</A
></H3
><P
>
- Applications use the Manager interface to locate the device
- objects they are interested in. When a device object (which is
- really a D-BUS object, note that the UDI is the objects object_path)
- is obtained, the HAL daemon provides the
- org.freedesktop.Hal.Device interface with the following methods
+ Applications use
+ the <TT
+CLASS="literal"
+>org.freedesktop.Hal.Manager</TT
+> interface to
+ locate the device objects they are interested in. When a device
+ object (which is really a D-BUS object, note that the UDI is the
+ objects object_path) is obtained, the HAL daemon provides the
+ <TT
+CLASS="literal"
+>org.freedesktop.Hal.Device</TT
+> interface on the
+ object denoted by the UDI. This interface has the following
+ methods
</P
><TABLE
@@ -988,14 +1124,14 @@
# signal to all client applications subscribing to signals from the Manager
# interface.
#
-# @param capability Capability, e.g. 'net.ethernet'
+# @param capability Capability, e.g. 'net.80211'
# @raises org.freedesktop.Hal.NoSuchDevice
#
void AddCapability(string capability)
# Determine if a device got a given capability
#
-# @param capability Capability, e.g. 'video.vga'
+# @param capability Capability, e.g. 'storage.cdrom'
# @return TRUE iff the device got the given capability
# @raises org.freedesktop.Hal.NoSuchDevice
#
@@ -1019,23 +1155,23 @@
><TD
><PRE
CLASS="programlisting"
-> # Notification that property have been added
+> # Notification that property have been modified
#
# @param key Property
+# @param added True iff the property have been added
+# @param removed True iff the property have been removed
#
-void PropertyAdded(string key)
+void PropertyModified(string key, bool added, bool removed)
-# Notification that property have been removed
+# Notification that an event happened on the device has occured.
#
-# @param key Property
+# Normally this is used to signal events that aren't or can't be expressed
+# in properties, e.g. 'ProcessorOverheating' etc.
#
-void PropertyRemoved(string key)
+# @param condition Name of condition
+# @param ... Dependent on the condition name
+void Condition(string condition, ...)
-# Notification that property have changed value
-#
-# @param key Property
-#
-void PropertyChanged(string key)
</PRE
></TD
></TR
@@ -1052,7 +1188,7 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN167"
+NAME="AEN179"
>Interface org.freedesktop.Hal.AgentManager</A
></H3
><P
@@ -1153,82 +1289,40 @@
>Using devices</A
></H2
><P
-> One of the goals of the HAL is to provide easy access to devices on
- a system. This includes obtaining device specific information, such
- as CPU frequency, and invoking device specific methods such as
- getting the pictures on a camera or changing the volume on a sound
- device.
+>
+ While the HAL daemon provides generic operations that apply to
+ all devices (though some may be no-ops), HAL is not concerned
+ with providing non-generic device operations.
</P
><P
>
- While the HAL daemon provides generic operations that apply to all
- devices (though some may be no-ops) and provide some level of monitoring
- for well-know class devices (such as networking devices), it is not
- concerned with providing non-generic device operations.
+ Specifically, one goal of HAL is to integrate with existing and
+ future libraries that target a specific class of devices such as
+ cameras or mp3 players.
</P
><P
>
- The architecture of the HAL allows a number of ways of dealing with
- specific device information and operations
-
- <P
-></P
-><UL
-><LI
-><P
-> <I
-CLASS="emphasis"
->Out-of-process D-BUS Service</I
-></P
-><P
->
- For example, one could write a volume manager that manages the
- different storage devices present on the system and mount the
- partitions/volumes available on those into the filesystem
- according to certain rules.
- The volume manager would run as a daemon monitoring the device list
- of the HAL daemon and act appropriately when devices having
- Storage and StorageVolume in the Capabilitites property appear and
- disappear.
+ For instance, libgphoto2 could be patched such that the
+ application programmer can simply pass the UDI of the camera he
+ wishes to interact with and libghoto2 would then, via D-BUS,
+ acquire the bus-specific information required, the address so to
+ speak, from the HAL daemon, and then interact directly with the
+ hardware.
- </P
+ </P
><P
>
- The volume manager could also offer an operation for writing
- ISO images to e.g. CD-R devices through a D-BUS interface
- on HAL device object. In this scenario, a desktop file manager
- would use the HAL daemon to query for the HAL device object
- that is a CD recorder and pass the object reference to the
- D-BUS service offered by the volume manager.
- </P
-></LI
-><LI
-><P
-> <I
-CLASS="emphasis"
->In-process library</I
-></P
-><P
->
-
- Another example is device objects having capability
- camera. One could use an existing library, such as libgphoto2,
- and make wrapper functions such that the application
- programmer simple passes the HAL UDI to the library. The
- library would then, via D-BUS, acquire the bus-specific
- information required from the HAL daemon, and then interact
- with the device.
-
- </P
-></LI
-></UL
->
+ Another option is to use the existing API of the device library
+ to discover devices (the library would be using HAL under the
+ hood) and provide a function to retrieve the HAL UDI of the
+ device. When the library is built without HAL support this
+ function fails, however, when the UDI is available applications
+ using the library can use the UDI both as stable reference to
+ the device and also to extract more information directly from
+ the HAL daemon.
- Note that there are other ways of dealing with device-specific
- operations - this list is not exhaustive.
-
</P
></DIV
><DIV
@@ -1241,77 +1335,101 @@
></H2
><P
>
- As previously mentioned the capabilities of a device specify what
- the device does. For instance, a CompactFlash card reader can be
- thought of as a camera, a handheld music device and removable
- storage.
+ Mainstream devices aren't very good at reporting what they are,
+ they only report, at best, how to interact with them. 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 they are in fact not. 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
>
- 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 (most
- OS'es has a concept of device classes). At this time the category
- is also determined by selecting the most prominent
- capability. However, both capabilities and category can be
- overridden by either device information files or a desktop
- environment policy daemon. This gives maximum flexibility, while
- maintaining a base level of capability detection.
+ 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, <TT
+CLASS="literal"
+>info.category</TT
+> and
+ <TT
+CLASS="literal"
+>info.capabilities</TT
+>. The former describes
+ <I
+CLASS="emphasis"
+>what the device is</I
+> (as a single
+ alphanumeric keyword) and the latter describes
+ <I
+CLASS="emphasis"
+>what the device does</I
+> (as a number of
+ alphanumeric keywords separated by whitespace). The keywords
+ available for use is defined in this document, we'll refer to
+ them simply as <I
+CLASS="emphasis"
+>capabilities</I
+>.
</P
><P
>
- Note that, for instance, a number of USB devices doesn't advertise
- anything in their device class, so a repository of device
- information files coupled with an interactive dialog (provided by a
- desktop environment daemon) asking the user what he just plugged
- in, will probably yield the best experience for users. Incidently,
- this is how certain non-free operating systems appear to handle
- hardware.
+ 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
+ (most OS'es has a concept of device classes). At this time the
+ category is also determined by selecting the most prominent
+ capability. However, both capabilities and category can be
+ overridden by either device information files or callouts. This
+ gives maximum flexibility, while maintaining a base level of
+ capability detection.
</P
><P
>
- Returning to the example of the card reader, this might just
- happen to be a digital camera with the only interface being a
- card reader - HAL, or the base OS, wouldn't be able to tell the
- difference - it's just looks like a storage device. So, to handle
- hardware well to meet the expectation of the users, device
- information files and desktop environment policy daemons need to
- be available on top of HAL (notably, the desktop environment
- daemon might look at the files on the device to infer whether
- it's music, pictures or something else) and adjust the capabilities
- and category of certain devices.
-
+ The idea of HAL is that existing device capability specific
+ libraries (such as libghoto2), would advertise what kind of HAL
+ capabilities they are able to handle. As this happens over
+ time, this specification will grow to precisely define what a
+ device with a given capability is supposed to do and what
+ library, or service, the application programmer can use to
+ access the device.
+
</P
><P
>
- Finally, what a given capability means, needs to be precisely
- defined. The idea of HAL is that existing device capability
- specific libraries (such as libghoto2), would advertise what kind
- of HAL capabilities they are able to handle. As this happens over
- time, this specification will grow to precisely define what a
- device with a given capability is supposed to do and what
- library, or service, the application programmer can use to access
- the device. At some point in time, we may define an uniform
- in-process extension framework akin to e.g. OpenGL extensions for
- accessing said libraries and services.
-
+ Having a capability also means that part of the property
+ namespace, prefixed with the capability name, can 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, whether it
+ support recording of audio, and how to interact with
+ device. For example, the latter may specify ''USB Storage
+ Device'' or ''proprietary protocol, use libfooplayer''.
+
</P
><P
>
- Having a capability also means that part of the property
- namespace, prefixed with the capability name, can (but it's not a
- requirement) be populated with more specific information about
- the capability. Virtual devices will not have any capabilities
- assigned to them.
+ Finally, capabilities have an inheritance scheme, e.g. if a device
+ has a capability <TT
+CLASS="literal"
+>foo.bar</TT
+>, it must also have
+ the capability <TT
+CLASS="literal"
+>foo</TT
+>.
</P
><P
>
- The following table define the capabilities supported in HAL at
- the time of writing.
+ The following table define the capabilities supported in HAL at
+ the time of writing.
</P
><DIV
@@ -1319,7 +1437,7 @@
><P
></P
><A
-NAME="AEN196"
+NAME="AEN206"
></A
><TABLE
BORDER="1"
@@ -1699,7 +1817,7 @@
><P
></P
><A
-NAME="AEN363"
+NAME="AEN373"
></A
><TABLE
BORDER="1"
@@ -1890,7 +2008,7 @@
><P
></P
><A
-NAME="AEN435"
+NAME="AEN445"
></A
><TABLE
BORDER="1"
@@ -1991,7 +2109,7 @@
><P
></P
><A
-NAME="AEN473"
+NAME="AEN483"
></A
><TABLE
BORDER="1"
@@ -2167,7 +2285,7 @@
><P
></P
><A
-NAME="AEN546"
+NAME="AEN556"
></A
><TABLE
BORDER="1"
@@ -2449,7 +2567,7 @@
><P
></P
><A
-NAME="AEN676"
+NAME="AEN686"
></A
><TABLE
BORDER="1"
@@ -2599,7 +2717,7 @@
><P
></P
><A
-NAME="AEN727"
+NAME="AEN737"
></A
><TABLE
BORDER="1"
@@ -2643,7 +2761,7 @@
><P
></P
><A
-NAME="AEN742"
+NAME="AEN752"
></A
><TABLE
BORDER="1"
@@ -2728,7 +2846,7 @@
><P
></P
><A
-NAME="AEN768"
+NAME="AEN778"
></A
><TABLE
BORDER="1"
@@ -3330,7 +3448,7 @@
><P
></P
><A
-NAME="AEN1051"
+NAME="AEN1061"
></A
><TABLE
BORDER="1"
@@ -3485,7 +3603,7 @@
><P
></P
><A
-NAME="AEN1114"
+NAME="AEN1124"
></A
><TABLE
BORDER="1"
@@ -3560,7 +3678,7 @@
><P
></P
><A
-NAME="AEN1144"
+NAME="AEN1154"
></A
><TABLE
BORDER="1"
@@ -3721,7 +3839,7 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN1190"
+NAME="AEN1200"
>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.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- hal-spec.xml.in 2 Aug 2004 21:56:24 -0000 1.5
+++ hal-spec.xml.in 3 Aug 2004 16:09:19 -0000 1.6
@@ -541,14 +541,14 @@
#
# @param key Key, for example 'block.fstype'
# @param value Value, for example 'ext3'
-# @return List of UDI's
+# @return Array of UDI's, may be empty
#
array{string} FindDeviceStringMatch(string key, string value)
# Find the set of devices in the GDL that has a given capability
#
# @param capability Capability, for example 'volume'
-# @return List of UDI's
+# @return Array of UDI's, may be empty
#
array{string} FindDeviceByCapability(string capability)
@@ -557,8 +557,11 @@
<para>
This object also emits the following signals on the
- org.freedesktop.Hal.Manager interface that applications can
- subscribe to using D-BUS:
+ <literal>/org/freedesktop/Hal/Manager</literal> object on the
+ <literal>org.freedesktop.Hal.Manager</literal> interface that
+ applications can subscribe to using D-BUS:
+
+ </para>
<programlisting>
@@ -584,16 +587,83 @@
</programlisting>
+
+ <sect3><title>Example</title>
+
+ <para>
+
+ The following brief Python program demonstrates some of the API
+
+ </para>
+
+<programlisting>
+ <inlinegraphic format="linespecific" fileref="examply-manager.py"/>
+</programlisting>
+
+ <para>
+
+ which gives the following output
+
</para>
+
+<programlisting>
+Found device /org/freedesktop/Hal/devices/block_TORiSAN DVD-ROM DRD-U624-00000000000000000001-disc
+Found device /org/freedesktop/Hal/devices/block_TORiSAN DVD-ROM DRD-U624-00000000000000000001
+Found device /org/freedesktop/Hal/devices/block_37332a77-105e-4e76-8e99-27d3746e0531
+Found device /org/freedesktop/Hal/devices/block_3_2
+Found device /org/freedesktop/Hal/devices/block_LS-120 SLIM3 00 UHD Floppy-0208MBA00211
+Found device /org/freedesktop/Hal/devices/block_IC25N020ATCS05-0-CLP225F2G3UR4A
+Found device /org/freedesktop/Hal/devices/ide_1_1
+Found device /org/freedesktop/Hal/devices/ide_0_0
+Found device /org/freedesktop/Hal/devices/ide_1_0
+Found device /org/freedesktop/Hal/devices/usbif_usb_0_0_206_-1_0000:00:07.2_0
+Found device /org/freedesktop/Hal/devices/ide_host_0
+Found device /org/freedesktop/Hal/devices/ide_host_1
+Found device /org/freedesktop/Hal/devices/pci_104c_8400
+Found device /org/freedesktop/Hal/devices/usb_0_0_206_-1_0000:00:07.2
+Found device /org/freedesktop/Hal/devices/pci_1002_4c4d
+Found device /org/freedesktop/Hal/devices/pci_125d_1978
+Found device /org/freedesktop/Hal/devices/pci_8086_7111
+Found device /org/freedesktop/Hal/devices/pci_104c_ac1c/0
+Found device /org/freedesktop/Hal/devices/pci_8086_7112
+Found device /org/freedesktop/Hal/devices/pci_8086_7110
+Found device /org/freedesktop/Hal/devices/input_13_65
+Found device /org/freedesktop/Hal/devices/pci_104c_ac1c
+Found device /org/freedesktop/Hal/devices/pci_8086_7190
+Found device /org/freedesktop/Hal/devices/input_13_64
+Found device /org/freedesktop/Hal/devices/pci_8086_7113
+Found device /org/freedesktop/Hal/devices/pci_8086_7191
+Found device /org/freedesktop/Hal/devices/computer
+
+(insert USB mouse)
+
+Device /org/freedesktop/Hal/devices/usb_46d_c001_410_-1_noserial was added
+Device /org/freedesktop/Hal/devices/usbif_usb_46d_c001_410_-1_noserial_0 was added
+
+(remove USB mouse)
+
+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
+</programlisting>
+
+ <para>
+
+ </para>
+
+ </sect3>
+
</sect2>
<sect2><title>Interface org.freedesktop.Hal.Device</title><para>
- Applications use the Manager interface to locate the device
- objects they are interested in. When a device object (which is
- really a D-BUS object, note that the UDI is the objects object_path)
- is obtained, the HAL daemon provides the
- org.freedesktop.Hal.Device interface with the following methods
+ Applications use
+ the <literal>org.freedesktop.Hal.Manager</literal> interface to
+ locate the device objects they are interested in. When a device
+ object (which is really a D-BUS object, note that the UDI is the
+ objects object_path) is obtained, the HAL daemon provides the
+ <literal>org.freedesktop.Hal.Device</literal> interface on the
+ object denoted by the UDI. This interface has the following
+ methods
</para>
@@ -658,14 +728,14 @@
# signal to all client applications subscribing to signals from the Manager
# interface.
#
-# @param capability Capability, e.g. 'net.ethernet'
+# @param capability Capability, e.g. 'net.80211'
# @raises org.freedesktop.Hal.NoSuchDevice
#
void AddCapability(string capability)
# Determine if a device got a given capability
#
-# @param capability Capability, e.g. 'video.vga'
+# @param capability Capability, e.g. 'storage.cdrom'
# @return TRUE iff the device got the given capability
# @raises org.freedesktop.Hal.NoSuchDevice
#
@@ -680,23 +750,23 @@
</para>
<programlisting>
-# Notification that property have been added
+# Notification that property have been modified
#
# @param key Property
+# @param added True iff the property have been added
+# @param removed True iff the property have been removed
#
-void PropertyAdded(string key)
+void PropertyModified(string key, bool added, bool removed)
-# Notification that property have been removed
+# Notification that an event happened on the device has occured.
#
-# @param key Property
+# Normally this is used to signal events that aren't or can't be expressed
+# in properties, e.g. 'ProcessorOverheating' etc.
#
-void PropertyRemoved(string key)
+# @param condition Name of condition
+# @param ... Dependent on the condition name
+void Condition(string condition, ...)
-# Notification that property have changed value
-#
-# @param key Property
-#
-void PropertyChanged(string key)
</programlisting>
<para>
@@ -793,62 +863,37 @@
<sect1 id="using-devices">
<title>Using devices</title>
<para>
- One of the goals of the HAL is to provide easy access to devices on
- a system. This includes obtaining device specific information, such
- as CPU frequency, and invoking device specific methods such as
- getting the pictures on a camera or changing the volume on a sound
- device.
- </para><para>
-
- While the HAL daemon provides generic operations that apply to all
- devices (though some may be no-ops) and provide some level of monitoring
- for well-know class devices (such as networking devices), it is not
- concerned with providing non-generic device operations.
+ While the HAL daemon provides generic operations that apply to
+ all devices (though some may be no-ops), HAL is not concerned
+ with providing non-generic device operations.
</para><para>
- The architecture of the HAL allows a number of ways of dealing with
- specific device information and operations
-
- <itemizedlist>
- <listitem><para>
- <emphasis>Out-of-process D-BUS Service</emphasis></para><para>
- For example, one could write a volume manager that manages the
- different storage devices present on the system and mount the
- partitions/volumes available on those into the filesystem
- according to certain rules.
- The volume manager would run as a daemon monitoring the device list
- of the HAL daemon and act appropriately when devices having
- Storage and StorageVolume in the Capabilitites property appear and
- disappear.
+ Specifically, one goal of HAL is to integrate with existing and
+ future libraries that target a specific class of devices such as
+ cameras or mp3 players.
- </para><para>
+ </para><para>
- The volume manager could also offer an operation for writing
- ISO images to e.g. CD-R devices through a D-BUS interface
- on HAL device object. In this scenario, a desktop file manager
- would use the HAL daemon to query for the HAL device object
- that is a CD recorder and pass the object reference to the
- D-BUS service offered by the volume manager.
- </para></listitem>
- <listitem><para>
- <emphasis>In-process library</emphasis></para><para>
+ For instance, libgphoto2 could be patched such that the
+ application programmer can simply pass the UDI of the camera he
+ wishes to interact with and libghoto2 would then, via D-BUS,
+ acquire the bus-specific information required, the address so to
+ speak, from the HAL daemon, and then interact directly with the
+ hardware.
- Another example is device objects having capability
- camera. One could use an existing library, such as libgphoto2,
- and make wrapper functions such that the application
- programmer simple passes the HAL UDI to the library. The
- library would then, via D-BUS, acquire the bus-specific
- information required from the HAL daemon, and then interact
- with the device.
+ </para><para>
- </para></listitem>
- </itemizedlist>
+ Another option is to use the existing API of the device library
+ to discover devices (the library would be using HAL under the
+ hood) and provide a function to retrieve the HAL UDI of the
+ device. When the library is built without HAL support this
+ function fails, however, when the UDI is available applications
+ using the library can use the UDI both as stable reference to
+ the device and also to extract more information directly from
+ the HAL daemon.
- Note that there are other ways of dealing with device-specific
- operations - this list is not exhaustive.
-
</para>
</sect1>
@@ -856,71 +901,74 @@
<title>Capabilities</title>
<para>
- As previously mentioned the capabilities of a device specify what
- the device does. For instance, a CompactFlash card reader can be
- thought of as a camera, a handheld music device and removable
- storage.
+ Mainstream devices aren't very good at reporting what they are,
+ they only report, at best, how to interact with them. 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 they are in fact not. 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.
</para><para>
- 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 (most
- OS'es has a concept of device classes). At this time the category
- is also determined by selecting the most prominent
- capability. However, both capabilities and category can be
- overridden by either device information files or a desktop
- environment policy daemon. This gives maximum flexibility, while
- maintaining a base level of capability detection.
+ 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, <literal>info.category</literal> and
+ <literal>info.capabilities</literal>. The former describes
+ <emphasis>what the device is</emphasis> (as a single
+ alphanumeric keyword) and the latter describes
+ <emphasis>what the device does</emphasis> (as a number of
+ alphanumeric keywords separated by whitespace). The keywords
+ available for use is defined in this document, we'll refer to
+ them simply as <emphasis>capabilities</emphasis>.
</para><para>
- Note that, for instance, a number of USB devices doesn't advertise
- anything in their device class, so a repository of device
- information files coupled with an interactive dialog (provided by a
- desktop environment daemon) asking the user what he just plugged
- in, will probably yield the best experience for users. Incidently,
- this is how certain non-free operating systems appear to handle
- hardware.
+ 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
+ (most OS'es has a concept of device classes). At this time the
+ category is also determined by selecting the most prominent
+ capability. However, both capabilities and category can be
+ overridden by either device information files or callouts. This
+ gives maximum flexibility, while maintaining a base level of
+ capability detection.
</para><para>
- Returning to the example of the card reader, this might just
- happen to be a digital camera with the only interface being a
- card reader - HAL, or the base OS, wouldn't be able to tell the
- difference - it's just looks like a storage device. So, to handle
- hardware well to meet the expectation of the users, device
- information files and desktop environment policy daemons need to
- be available on top of HAL (notably, the desktop environment
- daemon might look at the files on the device to infer whether
- it's music, pictures or something else) and adjust the capabilities
- and category of certain devices.
-
+ The idea of HAL is that existing device capability specific
+ libraries (such as libghoto2), would advertise what kind of HAL
+ capabilities they are able to handle. As this happens over
+ time, this specification will grow to precisely define what a
+ device with a given capability is supposed to do and what
+ library, or service, the application programmer can use to
+ access the device.
+
</para><para>
- Finally, what a given capability means, needs to be precisely
- defined. The idea of HAL is that existing device capability
- specific libraries (such as libghoto2), would advertise what kind
- of HAL capabilities they are able to handle. As this happens over
- time, this specification will grow to precisely define what a
- device with a given capability is supposed to do and what
- library, or service, the application programmer can use to access
- the device. At some point in time, we may define an uniform
- in-process extension framework akin to e.g. OpenGL extensions for
- accessing said libraries and services.
-
+ Having a capability also means that part of the property
+ namespace, prefixed with the capability name, can 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, whether it
+ support recording of audio, and how to interact with
+ device. For example, the latter may specify ''USB Storage
+ Device'' or ''proprietary protocol, use libfooplayer''.
+
</para><para>
- Having a capability also means that part of the property
- namespace, prefixed with the capability name, can (but it's not a
- requirement) be populated with more specific information about
- the capability. Virtual devices will not have any capabilities
- assigned to them.
+ Finally, capabilities have an inheritance scheme, e.g. if a device
+ has a capability <literal>foo.bar</literal>, it must also have
+ the capability <literal>foo</literal>.
</para><para>
- The following table define the capabilities supported in HAL at
- the time of writing.
+ The following table define the capabilities supported in HAL at
+ the time of writing.
</para>
<informaltable>
More information about the hal-commit
mailing list