dbus/doc dbus-specification.xml,1.32,1.33

[Havoc Pennington]

Update of /cvs/dbus/dbus/doc
In directory gabe:/tmp/cvs-serv11412/doc

Modified Files:
	dbus-specification.xml 
Log Message:
2005-02-25  Havoc Pennington  <hp at redhat.com>

	* doc/dbus-specification.xml: document the GUID thing

	* dbus/dbus-server.c (_dbus_server_init_base): initialize a
	globally unique ID for the server, and put a "guid=hexencoded"
	field in the address

	* dbus/dbus-bus.c: fix missing #include of dbus-threads-internal.h

	* dbus/dbus-message.c: ditto

	* dbus/dbus-dataslot.c: ditto

	* dbus/dbus-list.c: ditto

	* dbus/dbus-internals.h: wait, just include
	dbus-threads-internal.h here
	
	* dbus/dbus-string.c (_dbus_string_copy_to_buffer): move back for
	use in main library

	* dbus/dbus-sysdeps.c (_dbus_generate_random_bytes_buffer): new function



Index: dbus-specification.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-specification.xml,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -d -r1.32 -r1.33
--- dbus-specification.xml	24 Feb 2005 16:03:56 -0000	1.32
+++ dbus-specification.xml	25 Feb 2005 22:03:30 -0000	1.33
@@ -2165,6 +2165,28 @@
       The set of optionally-escaped bytes is intended to preserve address 
       readability and convenience.
     </para>
+
+    <para>
+      A server may specify a key-value pair with the key <literal>guid</literal>
+      and the value a hex-encoded 16-byte sequence. This globally unique ID must
+      be created by filling the first 4 bytes with a 32-bit UNIX time since the
+      epoch, and the remaining 12 bytes with random bytes. If present, the GUID
+      may be used to distinguish one server from another. A server should use a
+      different GUID for each address it listens on. For example, if a message
+      bus daemon offers both UNIX domain socket and TCP connections, but treats
+      clients the same regardless of how they connect, those two connections are
+      equivalent post-connection but should have distinct GUIDs to distinguish
+      the kinds of connection.
+    </para>
+    
+    <para>
+      The intent of the GUID feature is to allow a client to avoid opening
+      multiple identical connections to the same server, by allowing the client
+      to check whether an address corresponds to an already-existing connection.
+      Comparing two addresses is insufficient, because addresses can be recycled
+      by distinct servers.
+    </para>
+
     <para>
       [FIXME clarify if attempting to connect to each is a requirement 
       or just a suggestion]