2003-04-03 Havoc Pennington <hp@pobox.com>

	* bus/config-parser.c (bus_config_parser_unref): free
	list of mechanisms, bug discovered by test suite enhancements
	(putting system.conf and session.conf into suite)

	* test/Makefile.am, test/test-service.c: add placeholder for a
	test service that we'll activate as part of test suite. Doesn't
	do anything yet.

	* dbus/dbus-sysdeps.c (_dbus_setenv): support unsetenv by
	setting NULL value, and use system malloc not dbus_malloc()
	when we have unavoidable memleakage.

	* dbus/dbus-bus.c (dbus_bus_get): fix bug where bus type of 0
	didn't work, and support DBUS_BUS_ACTIVATION.

	* bus/activation.c (child_setup): pass our well-known bus type to
	the child

	* bus/config-parser.c: support <type> to specify well-known type

	* doc/dbus-specification.sgml: document the env variables to
	locate well-known buses and find service activator

2 files changed, 50 insertions, 7 deletions

diff --git a/doc/config-file.txt b/doc/config-file.txt
index b8230aab..8c2152b5 100644
--- a/doc/config-file.txt
+++ b/doc/config-file.txt
@@ -27,6 +27,15 @@ Elements:
  
     Root element.
 
+ <type>
+
+    The well-known type of the message bus. Currently known values
+    are "system" and "session"; if other values are set, they should 
+    be either added to the D-BUS specification, or namespaced.
+    The last <type> element "wins"
+
+    Example: <type>session</type>
+
  <include>
   ignore_missing="(yes|no)"   optional attribute, defaults to no
    
diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml
index 5d150e86..7e2fcb35 100644
--- a/doc/dbus-specification.sgml
+++ b/doc/dbus-specification.sgml
@@ -1235,10 +1235,22 @@
       </para>
       <para>
         The executable launched will have the environment variable
-        <literal>DBUS_BUS_ADDRESS</literal> set to the address of the
+        <literal>DBUS_ACTIVATION_ADDRESS</literal> set to the address of the
         message bus so it can connect and register the appropriate services.
       </para>
       <para>
+        The executable being launched may want to know whether the message bus
+        activating it is one of the well-known message buses (see <xref
+        linkend="message-bus-types">). To facilitate this, the bus MUST also set
+        the <literal>DBUS_ACTIVATION_BUS_TYPE</literal> environment variable if it is one
+        of the well-known buses. The currently-defined values for this variable
+        are <literal>system</literal> for the systemwide message bus,
+        and <literal>session</literal> for the per-login-session message
+        bus. The activated executable must still connect to the address given
+        in <literal>DBUS_ACTIVATION_ADDRESS</literal>, but may assume that the
+        resulting connection is to the well-known bus.
+      </para>
+      <para>
         [FIXME there should be a timeout somewhere, either specified
         in the .service file, by the client, or just a global value
         and if the client being activated fails to connect within that
@@ -1247,7 +1259,7 @@
     </sect2>
 
     <sect2 id="message-bus-types">
-      <title>Standard Message Bus Instances</title>
+      <title>Well-known Message Bus Instances</title>
       <para>
         Two standard message bus instances are defined here, along with how 
         to locate them and where their service files live.
@@ -1257,9 +1269,17 @@
         <para>
           Each time a user logs in, a <firstterm>login session message
             bus</firstterm> may be started. All applications in the user's login
-          session may interact with one another using this message bus.  [specify
-          how to find the address of the login session message bus via
-          environment variable and/or X property]
+          session may interact with one another using this message bus.
+        </para>
+        <para>
+          The address of the login session message bus is given 
+          in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment 
+          variable. If that variable is not set, applications may 
+          also try to read the address from the X Window System root 
+          window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
+          The root window property must have type <literal>STRING</literal>.
+          The environment variable should have precedence over the 
+          root window property.
         </para>
         <para>
           [FIXME specify location of .service files, probably using 
@@ -1272,8 +1292,22 @@
         <para>
           A computer may have a <firstterm>system message bus</firstterm>,
           accessible to all applications on the system. This message bus may be
-          used to broadcast system events, such as adding new hardware devices.
-          [specify how to find the address of the system message bus]
+          used to broadcast system events, such as adding new hardware devices, 
+          changes in the printer queue, and so forth.
+        </para>
+        <para>
+          The address of the login session message bus is given 
+          in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment 
+          variable. If that variable is not set, applications should try 
+          to connect to the well-known address
+          <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
+          <footnote>
+            <para>
+              The D-BUS reference implementation actually honors the 
+              <literal>$(localstatedir)</literal> configure option 
+              for this address, on both client and server side.
+            </para>
+          </footnote>
         </para>
         <para>
           [FIXME specify location of system bus .service files]