dbus/doc dbus-specification.xml,1.42,1.43

[Havoc Pennington]

Update of /cvs/dbus/dbus/doc
In directory kemper:/tmp/cvs-serv15792/doc

Modified Files:
	dbus-specification.xml 
Log Message:
2006-09-30  Havoc Pennington  <hp at redhat.com>

	* configure.in (LT_CURRENT, LT_AGE): increment current and age to
	reflect addition of interfaces.

	* doc/dbus-specification.xml: describe a new
	org.freedesktop.DBus.Peer.GetMachineId method

	* dbus/dbus-string.c (_dbus_string_skip_white_reverse): new function
	(_dbus_string_skip_white, _dbus_string_skip_blank): use new
	DBUS_IS_ASCII_BLANK, DBUS_IS_ASCII_WHITE macros and fix assertion
	at end of skip_white
	(_dbus_string_chop_white): new function

	* bus/connection.c (bus_connections_setup_connection): call
	dbus_connection_set_route_peer_messages.

	* dbus/dbus-connection.c
	(_dbus_connection_peer_filter_unlocked_no_update): modify to
	support a GetMachineId method.

	Also, support a new flag to let the bus pass peer methods through
	to apps on the bus, which can be set with
	dbus_connection_set_route_peer_messages.

	Finally, handle and return an error for anything unknown on the
	Peer interface, which will allow us to extend the Peer interface
	in the future without fear that we're now intercepting something
	apps were wanting to see.
	
	* tools/dbus-uuidgen.c: a thin wrapper around the functions in 
	dbus/dbus-uuidgen.c

	* dbus/dbus-uuidgen.c: implement the bulk of the dbus-uuidgen
	binary here, since most of the code is already in libdbus

	* dbus/dbus-sysdeps.c (_dbus_read_local_machine_uuid): read the
	uuid from the system config file

	* dbus/dbus-internals.c (_dbus_generate_uuid, _dbus_uuid_encode) 
	(_dbus_read_uuid_file_without_creating) 
	(_dbus_create_uuid_file_exclusively, _dbus_read_uuid_file): new
	uuid-related functions, partly factored out from dbus-server.c

	* dbus/dbus-sysdeps.c (_dbus_error_from_errno): convert EEXIST to
	DBUS_ERROR_FILE_EXISTS instead of EEXIST

	* dbus/dbus-protocol.h (DBUS_ERROR_FILE_EXISTS): add file exists error

	* tools/dbus-cleanup-sockets.1: explain what the point of this
	thing is a bit more

	* autogen.sh (run_configure): add --config-cache to default
	configure args

	* dbus/dbus-internals.h (_DBUS_ASSERT_ERROR_IS_SET): disable the
	error set/clear assertions when DBUS_DISABLE_CHECKS is defined

	* tools/dbus-launch.c (main): if xdisplay hasn't been opened,
	don't try to save address, fixes crash in make check



Index: dbus-specification.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-specification.xml,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -d -r1.42 -r1.43
--- dbus-specification.xml	17 Aug 2006 21:20:13 -0000	1.42
+++ dbus-specification.xml	1 Oct 2006 03:18:47 -0000	1.43
@@ -2290,9 +2290,10 @@
       <title><literal>org.freedesktop.DBus.Peer</literal></title>
       <para>
         The <literal>org.freedesktop.DBus.Peer</literal> interface 
-        has one method:
+        has two methods:
         <programlisting>
           org.freedesktop.DBus.Peer.Ping ()
+          org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid)
         </programlisting>
       </para>
       <para>
@@ -2300,9 +2301,33 @@
         <literal>org.freedesktop.DBus.Peer.Ping</literal>, an application should do
         nothing other than reply with a <literal>METHOD_RETURN</literal> as
         usual.  It does not matter which object path a ping is sent to.  The
-        reference implementation should simply handle this method on behalf of
-        all objects, though it doesn't yet. (The point is, you're really pinging
-        the peer process, not a specific object.)
+        reference implementation handles this method automatically.
+      </para>
+      <para>
+        On receipt of the <literal>METHOD_CALL</literal> message
+        <literal>org.freedesktop.DBus.Peer.GetMachineId</literal>, an application should 
+        reply with a <literal>METHOD_RETURN</literal> containing a hex-encoded 
+        UUID representing the identity of the machine the process is running on.
+        This UUID must be the same for all processes on a single system at least
+        until that system next reboots. It should be the same across reboots 
+        if possible, but may change due to reconfiguration or hardware changes.
+        It does not matter which object path a GetMachineId is sent to.  The
+        reference implementation handles this method automatically.
+      </para>
+      <para>
+        The UUID must contain 128 bits of data and be hex-encoded (meaning, the hex 
+        string contains 32 ASCII characters). The hex-encoded string may not contain 
+        hyphens or other non-hex-digit characters, and it must be exactly 32 characters long.
+        To generate a UUID, the recommended algorithm is to put the current time in seconds
+        since the UNIX epoch in the last 32 bits of the UUID, and to put randomly-generated bits
+        in the first 96 bits of the UUID.
+      </para>
+      <para>
+        The UUID is intended to be per-instance-of-the-operating-system, so may represent
+        a virtual machine running on a hypervisor, rather than a physical machine.
+        Basically if two processes see the same UUID, they should also see the same
+        shared memory, UNIX domain sockets, process IDs, and other features that require 
+        a running OS kernel in common between the processes.
       </para>
     </sect2>