dbus/doc dbus-specification.xml,1.26,1.27

[Havoc Pennington]

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

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

	* test/glib/test-dbus-glib.c (main): fix so this test doesn't fail
	(call dbus_g_proxy_add_signal)

	* dbus/dbus-server-unix.c (_dbus_server_new_for_tcp_socket):
	escape the hostname
	(_dbus_server_new_for_domain_socket): escape the path

	* dbus/dbus-address.c (dbus_address_escape_value): new
	(dbus_address_unescape_value): new
	(dbus_parse_address): unescape values

	* dbus/dbus-string.c (_dbus_string_append_byte_as_hex): new function

	* doc/dbus-specification.xml: explain how to escape values in
	addresses



Index: dbus-specification.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-specification.xml,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -d -r1.26 -r1.27
--- dbus-specification.xml	11 Feb 2005 01:13:45 -0000	1.26
+++ dbus-specification.xml	11 Feb 2005 03:37:03 -0000	1.27
@@ -2131,7 +2131,7 @@
     <para>
       Server addresses consist of a transport name followed by a colon, and
       then an optional, comma-separated list of keys and values in the form key=value.
-      [FIXME how do you escape colon, comma, and semicolon in the values of the key=value pairs?]
+      Each value is escaped.
     </para>
     <para>
       For example: 
@@ -2139,6 +2139,33 @@
       Which is the address to a unix socket with the path /tmp/dbus-test.
     </para>
     <para>
+      Value escaping is similar to URI escaping but simpler.
+      <itemizedlist>
+        <listitem>
+          <para>
+            The set of optionally-escaped bytes is:
+            <literal>[0-9A-Za-z_-/.\]</literal>. To escape, each
+            <emphasis>byte</emphasis> (note, not character) which is not in the
+            set of optionally-escaped bytes must be replaced with an ASCII
+            percent (<literal>%</literal>) and the value of the byte in hex.
+            The hex value must always be two digits, even if the first digit is
+            zero. The optionally-escaped bytes may be escaped if desired.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            To unescape, append each byte in the value; if a byte is an ASCII
+            percent (<literal>%</literal>) character then append the following
+            hex value instead. It is an error if a <literal>%</literal> byte
+            does not have two hex digits following. It is an error if a
+            non-optionally-escaped byte is seen unescaped.
+          </para>
+        </listitem>
+      </itemizedlist>
+      The set of optionally-escaped bytes is intended to preserve address 
+      readability and convenience.
+    </para>
+    <para>
       [FIXME clarify if attempting to connect to each is a requirement 
       or just a suggestion]
       When connecting to a server, multiple server addresses can be