changeset 109963:8a3f86c30b0c

* dbus.texi (Alternative Buses): New chapter.

--- a/doc/misc/ChangeLog	Mon Aug 23 15:08:54 2010 +0200
+++ b/doc/misc/ChangeLog	Mon Aug 23 15:48:48 2010 +0200
@@ -1,3 +1,7 @@
[phone]  Michael Albinus  <[e-mail]>
+
+	* dbus.texi (Alternative Buses): New chapter.
+
 2010-08-12  Stefan Monnier  <[e-mail]>
 
 	* cl.texi (Mapping over Sequences): Rename mapc => cl-mapc.

--- a/doc/misc/dbus.texi	Mon Aug 23 15:08:54 2010 +0200
+++ b/doc/misc/dbus.texi	Mon Aug 23 15:48:48 2010 +0200
@@ -53,6 +53,7 @@
 * Asynchronous Methods::        Calling methods non-blocking.
 * Receiving Method Calls::      Offering own methods.
 * Signals::                     Sending and receiving signals.
+* Alternative Buses::           Alternative buses.
 * Errors and Events::           Errors and events.
 * Index::                       Index including concepts, functions, variables.
 
@@ -1579,6 +1580,56 @@
 @end defun
 
 
+@node Alternative Buses
+@chapter Alternative buses.
+@cindex bus names
+@cindex UNIX domain socket
+
+Until now, we have spoken about the system and the session buses,
+which are the default buses to be connected to.  However, it is
+possible to connect to any bus, from which the address is known.  This
+is a UNIX domain socket.  Everywhere, where a @var{bus} is mentioned
+as argument of a function (the symbol @code{:system} or the symbol
+@code{:session}), this address can be used instead.  The connection to
+this bus must be initialized first.
+
+@defun dbus-init-bus bus
+Establish the connection to D-Bus @var{bus}.
+
+@var{bus} can be either the symbol @code{:system} or the symbol
+@code{:session}, or it can be a string denoting the address of the
+corresponding bus.  For the system and session busses, this function
+is called when loading @file{dbus.el}, there is no need to call it
+again.
+
+Example: You open another session bus in a terminal window on your host:
+
+@example
+# eval `dbus-launch --auto-syntax`
+# echo $DBUS_SESSION_BUS_ADDRESS
+
+@print{} unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e
+@end example
+
+In Emacs, you can access to this bus via its address:
+
+@lisp
+(setq my-bus
+      "unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e")
+
+@result{} "unix:abstract=/tmp/dbus-JoFtAVG92w,guid=2f320a1ebe50b7ef58e"
+
+(dbus-init-bus my-bus)
+
+@result{} nil
+
+(dbus-get-unique-name my-bus)
+
+@result{} ":1.0"
+@end lisp
+@end defun
+
+
 @node Errors and Events
 @chapter Errors and events.
 @cindex debugging