* dbus.texi (Type Conversion): Introduce `:unix-fd' type mapping.

[bpt/emacs.git] / doc / misc / dbus.texi

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 2488845..6f6a897 100644 (file)
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -53,6 +53,7 @@ another.  An overview of D-Bus can be found at
 * 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.
 
@@ -889,7 +890,8 @@ symbol can be preceeded to the corresponding Lisp object. Basic D-Bus
 types are represented by the type symbols @code{:byte},
 @code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32},
 @code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double},
-@code{:string}, @code{:object-path} and @code{:signature}.
+@code{:string}, @code{:object-path}, @code{:signature} and
+@code{:unix-fd}.
 
 @noindent
 Example:
@@ -1008,6 +1010,7 @@ objects.
 @item DBUS_TYPE_UINT16      @tab @expansion{} @tab natural number
 @item DBUS_TYPE_INT16       @tab @expansion{} @tab integer
 @item DBUS_TYPE_UINT32      @tab @expansion{} @tab natural number or float
+@item DBUS_TYPE_UNIX_FD     @tab @expansion{} @tab natural number or float
 @item DBUS_TYPE_INT32       @tab @expansion{} @tab integer or float
 @item DBUS_TYPE_UINT64      @tab @expansion{} @tab natural number or float
 @item DBUS_TYPE_INT64       @tab @expansion{} @tab integer or float
@@ -1023,9 +1026,9 @@ objects.
 @end example
 
 A float object in case of @code{DBUS_TYPE_UINT32},
-@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and
-@code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the
-Emacs number size range.
+@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64},
+@code{DBUS_TYPE_INT64} and @code{DBUS_TYPE_UNIX_FD} is returned, when
+the C value exceeds the Emacs number size range.
 
 The resulting list of the last 4 D-Bus compound types contains as
 elements the elements of the D-Bus container, mapped according to the
@@ -1579,6 +1582,56 @@ which objects the GNU/Linux @code{hal} daemon adds.
 @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