X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/867d4bb3718f1fee9191e2c17cd810ef620d4b54..3107d2a58a15e7fe71f3ac56886a4a71a9af36db:/doc/misc/dbus.texi

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 40b652d95a..e6fb00d348 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -5,8 +5,11 @@
 @c @setchapternewpage odd
 @c %**end of header
 
+@syncodeindex vr cp
+@syncodeindex fn cp
+
 @copying
-Copyright @copyright{} 2007, 2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 2007-2011 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -22,22 +25,21 @@ developing GNU and promoting software freedom.''
 @end quotation
 @end copying
 
-@dircategory Emacs
+@dircategory Emacs lisp libraries
 @direntry
 * D-Bus: (dbus).                Using D-Bus in Emacs.
 @end direntry
 
 @contents
 
+
 @node Top, Overview, (dir), (dir)
 @top D-Bus integration in Emacs
 
-This manual documents an API for usage of D-Bus in
-Emacs.@footnote{D-Bus is not enabled by default.  You must run
-@command{./configure --with-dbus} in Emacs' top level directory,
-before you compile Emacs.}  D-Bus is a message bus system, a simple
-way for applications to talk to one another.  An overview of D-Bus can
-be found at @uref{http://dbus.freedesktop.org/}.
+This manual documents an API for usage of D-Bus in Emacs.  D-Bus is a
+message bus system, a simple way for applications to talk to one
+another.  An overview of D-Bus can be found at
+@uref{http://dbus.freedesktop.org/}.
 
 @ifnottex
 @insertcopying
@@ -51,7 +53,10 @@ be found at @uref{http://dbus.freedesktop.org/}.
 * 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.
+
 * GNU Free Documentation License:: The license for this documentation.
 @end menu
 
@@ -127,14 +132,24 @@ There are several basic functions which inspect the buses for
 registered names.  Internally they use the basic interface
 @samp{org.freedesktop.DBus}, which is supported by all objects of a bus.
 
-@defun dbus-list-activatable-names
-This function returns the D-Bus service names, which can be activated.
-An activatable service is described in a service registration file.
-Under GNU/Linux, such files are located at
-@file{/usr/share/dbus-1/services/}.
+@defun dbus-list-activatable-names &optional bus
+This function returns the D-Bus service names, which can be activated
+for @var{bus}.  It must be either the symbol @code{:system} (the
+default) or the symbol @code{:session}.  An activatable service is
+described in a service registration file.  Under GNU/Linux, such files
+are located at @file{/usr/share/dbus-1/system-services/} (for the
+@code{:system} bus) or @file{/usr/share/dbus-1/services/}.  An
+activatable service is not necessarily registered at @var{bus} at already.
 
 The result is a list of strings, which is @code{nil} when there are no
-activatable service names at all.
+activatable service names at all.  Example:
+
+@lisp
+;; Check, whether the document viewer can be accessed via D-Bus.
+(member "org.gnome.evince.Daemon"
+        (dbus-list-activatable-names :session))
+@end lisp
+
 @end defun
 
 @defun dbus-list-names bus
@@ -149,7 +164,7 @@ strings like @samp{org.freedesktop.DBus}.  Names starting with
 @end defun
 
 @defun dbus-list-known-names bus
-Retrieves all services which correspond to a known name in @var{bus}.
+Retrieves all registered services which correspond to a known name in @var{bus}.
 A service has a known name if it doesn't start with @samp{:}.  The
 result is a list of strings, which is @code{nil} when there are no
 known names at all.
@@ -180,22 +195,31 @@ result is a string, or @code{nil} when there exist no name owner of
 string.
 @end defun
 
-@defun dbus-ping bus service
+@defun dbus-ping bus service &optional timeout
 Check whether the service name @var{service} is registered at D-Bus
-@var{bus}.  @var{service} might not have been started yet.  The result
-is either @code{t} or @code{nil}.
+@var{bus}.  @var{service} might not have been started yet, it is
+autostarted if possible.  The result is either @code{t} or @code{nil}.
 
 @var{bus} must be either the symbol @code{:system} or the symbol
-@code{:session}.  @var{service} must be a string.  Example:
+@code{:session}.  @var{service} must be a string.  @var{timeout}, a
+nonnegative integer, specifies the maximum number of milliseconds
+@code{dbus-ping} must return.  The default value is 25,000.  Example:
 
 @lisp
 (message
    "%s screensaver on board."
    (cond
-     ((dbus-ping :session "org.gnome.ScreenSaver") "Gnome")
-     ((dbus-ping :session "org.freedesktop.ScreenSaver") "KDE")
+     ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome")
+     ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE")
      (t "No")))
 @end lisp
+
+If it shall be checked whether @var{service} is already running
+without autostarting it, one shall apply
+
+@lisp
+(member service (dbus-list-known-names bus))
+@end lisp
 @end defun
 
 @defun dbus-get-unique-name bus
@@ -410,7 +434,8 @@ Example:
 @result{} "/org/freedesktop/SystemToolsBackends/UsersConfig"
 @end lisp
 
-If @var{object} has no @var{attribute}, the function returns nil.
+If @var{object} has no @var{attribute}, the function returns
+@code{nil}.
 @end defun
 
 
@@ -661,7 +686,7 @@ A @var{property} value can be retrieved by the function
 @defun dbus-get-property bus service path interface property
 This function returns the value of @var{property} of @var{interface}.
 It will be checked at @var{bus}, @var{service}, @var{path}.  The
-result can be any valid D-Bus value, or nil if there is no
+result can be any valid D-Bus value, or @code{nil} if there is no
 @var{property}.  Example:
 
 @lisp
@@ -855,12 +880,12 @@ Lisp function call.  The following mapping to D-Bus types is
 applied, when the corresponding D-Bus message is created:
 
 @example
-@multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN}
+@multitable {negative integer} {@expansion{}} {DBUS_TYPE_BOOLEAN}
 @item Lisp type               @tab              @tab D-Bus type
 @item
 @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN
-@item number                  @tab @expansion{} @tab DBUS_TYPE_UINT32
-@item integer                 @tab @expansion{} @tab DBUS_TYPE_INT32
+@item natural number          @tab @expansion{} @tab DBUS_TYPE_UINT32
+@item negative integer        @tab @expansion{} @tab DBUS_TYPE_INT32
 @item float                   @tab @expansion{} @tab DBUS_TYPE_DOUBLE
 @item string                  @tab @expansion{} @tab DBUS_TYPE_STRING
 @item list                    @tab @expansion{} @tab DBUS_TYPE_ARRAY
@@ -868,32 +893,33 @@ applied, when the corresponding D-Bus message is created:
 @end example
 
 Other Lisp objects, like symbols or hash tables, are not accepted as
-input parameter.
+input parameters.
 
 If it is necessary to use another D-Bus type, a corresponding type
-symbol can be preceeded to the corresponding Lisp object. Basic D-Bus
+symbol can be prepended 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:
 
 @lisp
-(dbus-call-method @dots{} @var{NUMBER} @var{STRING})
+(dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING})
 @end lisp
 
 is equivalent to
 
 @lisp
-(dbus-call-method @dots{} :uint32 @var{NUMBER} :string @var{STRING})
+(dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING})
 @end lisp
 
 but different to
 
 @lisp
-(dbus-call-method @dots{} :int32 @var{NUMBER} :signature @var{STRING})
+(dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING})
 @end lisp
 
 The value for a byte D-Bus type can be any integer in the range 0
@@ -943,7 +969,7 @@ elements of this array.  Example:
   '(:array)                   ;; No actions (empty array of strings).
   '(:array :signature "@{sv@}") ;; No hints
                               ;; (empty array of dictionary entries).
-  ':int32 -1)                 ;; Default timeout.
+  :int32 -1)                 ;; Default timeout.
 
 @result{} 3
 @end lisp
@@ -986,17 +1012,18 @@ Output parameters of D-Bus methods and signals are mapped to Lisp
 objects.
 
 @example
-@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}}
+@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float}
 @item D-Bus type            @tab              @tab Lisp type
 @item
 @item DBUS_TYPE_BOOLEAN     @tab @expansion{} @tab @code{t} or @code{nil}
-@item DBUS_TYPE_BYTE        @tab @expansion{} @tab number
-@item DBUS_TYPE_UINT16      @tab @expansion{} @tab number
-@item DBUS_TYPE_INT16       @tab @expansion{} @tab number
-@item DBUS_TYPE_UINT32      @tab @expansion{} @tab number or float
-@item DBUS_TYPE_INT32       @tab @expansion{} @tab number or float
-@item DBUS_TYPE_UINT64      @tab @expansion{} @tab number or float
-@item DBUS_TYPE_INT64       @tab @expansion{} @tab number or float
+@item DBUS_TYPE_BYTE        @tab @expansion{} @tab natural number
+@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
 @item DBUS_TYPE_DOUBLE      @tab @expansion{} @tab float
 @item DBUS_TYPE_STRING      @tab @expansion{} @tab string
 @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
@@ -1009,9 +1036,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
@@ -1022,7 +1049,7 @@ The signal @code{PropertyModified}, discussed as example in
 (@var{BOOL} stands here for either @code{nil} or @code{t}):
 
 @lisp
-(@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
+(@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
 @end lisp
 
 @defun dbus-byte-array-to-string byte-array
@@ -1045,7 +1072,12 @@ Retrieve the original string from the encoded @var{string}.
 @lisp
 (dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")
 
-@result{} "0123abc_xyz
ÿ"
+@ifinfo
+@result{} "0123abc_xyz^Aÿ"
+@end ifinfo
+@ifnotinfo
+@result{} "0123abc_xyz^A@"y"
+@end ifnotinfo
 @end lisp
 @end defun
 
@@ -1073,7 +1105,7 @@ an interface offered by @var{service}.  It must provide @var{method}.
 
 If the parameter @code{:timeout} is given, the following integer
 @var{timeout} specifies the maximum number of milliseconds the method
-call must return.  The default value is 25.000.  If the method call
+call must return.  The default value is 25,000.  If the method call
 doesn't return in time, a D-Bus error is raised (@pxref{Errors and
 Events}).
 
@@ -1184,11 +1216,12 @@ D-Bus object path, @var{service} is registered at.  @var{interface} is
 an interface offered by @var{service}.  It must provide @var{method}.
 
 @var{handler} is a Lisp function, which is called when the
-corresponding return message has arrived.
+corresponding return message has arrived.  If @var{handler} is
+@code{nil}, no return message will be expected.
 
 If the parameter @code{:timeout} is given, the following integer
 @var{timeout} specifies the maximum number of milliseconds a reply
-message must arrive.  The default value is 25.000.  If there is no
+message must arrive.  The default value is 25,000.  If there is no
 reply message in time, a D-Bus error is raised (@pxref{Errors and
 Events}).
 
@@ -1196,10 +1229,10 @@ All other arguments args are passed to @var{method} as arguments.
 They are converted into D-Bus types as described in @ref{Type
 Conversion}.
 
-The function returns a key into the hash table
-@code{dbus-registered-functions-table}.  The corresponding entry in
-the hash table is removed, when the return message has been arrived,
-and @var{handler} is called.  Example:
+Unless @var{handler} is @code{nil}, the function returns a key into
+the hash table @code{dbus-registered-objects-table}.  The
+corresponding entry in the hash table is removed, when the return
+message has been arrived, and @var{handler} is called.  Example:
 
 @lisp
 (dbus-call-method-asynchronously
@@ -1220,9 +1253,73 @@ and @var{handler} is called.  Example:
 @cindex method calls, returning
 @cindex returning method calls
 
-Emacs can also offer own methods, which can be called by other
-applications.  These methods could be an implementation of an
-interface of a well known service, like @samp{org.freedesktop.TextEditor}.
+In order to register methods on the D-Bus, Emacs has to request a well
+known name on the D-Bus under which it will be available for other
+clients.  Names on the D-Bus can be registered and unregistered using
+the following functions:
+
+@defun dbus-register-service bus service &rest flags
+Register the known name @var{service} on D-Bus @var{bus}.
+
+@var{bus} is either the symbol @code{:system} or the symbol
+@code{:session}.
+
+@var{service} is the service name to be registered on the D-Bus.  It
+must be a known name.
+
+@var{flags} is a subset of the following keywords:
+
+@itemize
+@item @code{:allow-replacement}: Allow another service to become the primary
+owner if requested.
+
+@item @code{:replace-existing}: Request to replace the current primary owner.
+
+@item @code{:do-not-queue}: If we can not become the primary owner do not
+place us in the queue.
+@end itemize
+
+One of the following keywords is returned:
+
+@itemize
+
+@item @code{:primary-owner}: We have become the primary owner of the name
+@var{service}.
+
+@item @code{:in-queue}: We could not become the primary owner and
+have been placed in the queue.
+
+@item @code{:exists}: We already are in the queue.
+
+@item @code{:already-owner}: We already are the primary
+owner.
+@end itemize
+@end defun
+
+@defun dbus-unregister-service bus service
+Unregister all objects from D-Bus @var{bus}, registered by Emacs for
+@var{service}.
+
+@var{bus} is either the symbol @code{:system} or the symbol
+@code{:session}.
+
+@var{service} is the D-Bus service name of the D-Bus.  It must be a
+known name.  Emacs releases its association to @var{service} from
+D-Bus.
+
+One of the following keywords is returned:
+
+@itemize
+@item @code{:released}: We successfully released the name @var{service}.
+@item @code{:non-existent}: The name @var{service} does not exist on the bus.
+@item @code{:not-owner}: We are not an owner of the name @var{service}.
+@end itemize
+@end defun
+
+When a name has been chosen, Emacs can offer own methods, which can be
+called by other applications.  These methods could be an
+implementation of an interface of a well known service, like
+@samp{org.freedesktop.TextEditor}.
 
 It could be also an implementation of an own interface.  In this case,
 the service name must be @samp{org.gnu.Emacs}.  The object path shall
@@ -1241,7 +1338,7 @@ paths, used by offered methods or signals, shall start with this
 string.
 @end deffn
 
-@defun dbus-register-method bus service path interface method handler
+@defun dbus-register-method bus service path interface method handler dont-register-service
 With this function, an application registers @var{method} on the D-Bus
 @var{bus}.
 
@@ -1249,10 +1346,11 @@ With this function, an application registers @var{method} on the D-Bus
 @code{:session}.
 
 @var{service} is the D-Bus service name of the D-Bus object
-@var{method} is registered for.  It must be a known name.
+@var{method} is registered for.  It must be a known name (See
+discussion of @var{dont-register-service} below).
 
-@var{path} is the D-Bus object path @var{service} is
-registered.
+@var{path} is the D-Bus object path @var{service} is registered (See
+discussion of @var{dont-register-service} below).
 
 @var{interface} is the interface offered by @var{service}.  It must
 provide @var{method}.
@@ -1268,6 +1366,16 @@ If @var{handler} wants to return just one Lisp object and it is not a
 cons cell, @var{handler} can return this object directly, instead of
 returning a list containing the object.
 
+In case @var{handler} shall return a reply message with an empty
+argument list, @var{handler} must return the symbol @code{:ignore}.
+
+When @var{dont-register-service} is non-@code{nil}, the known name
+@var{service} is not registered.  This means that other D-Bus clients
+have no way of noticing the newly registered method.  When interfaces
+are constructed incrementally by adding single methods or properties
+at a time, @var{dont-register-service} can be used to prevent other
+clients from discovering the still incomplete interface.
+
 The default D-Bus timeout when waiting for a message reply is 25
 seconds.  This value could be even smaller, depending on the calling
 client.  Therefore, @var{handler} shall not last longer than
@@ -1300,7 +1408,7 @@ registration for @var{method}.  Example:
 If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile}
 from another D-Bus application with a filename as parameter, the file
 is opened in Emacs, and the method returns either @var{true} or
-@var{false}, indicating the success if the method.  As test tool one
+@var{false}, indicating the success of the method.  As test tool one
 could use the command line tool @code{dbus-send} in a shell:
 
 @example
@@ -1342,6 +1450,120 @@ The test runs then
 @end example
 @end defun
 
+@defun dbus-register-property bus service path interface property access value &optional emits-signal dont-register-service
+With this function, an application declares a @var{property} on the D-Bus
+@var{bus}.
+
+@var{bus} is either the symbol @code{:system} or the symbol
+@code{:session}.
+
+@var{service} is the D-Bus service name of the D-Bus.  It must be a
+known name.
+
+@var{path} is the D-Bus object path @var{service} is registered (See
+discussion of @var{dont-register-service} below).
+
+@var{interface} is the name of the interface used at @var{path},
+@var{property} is the name of the property of @var{interface}.
+
+@var{access} indicates, whether the property can be changed by other
+services via D-Bus.  It must be either the symbol @code{:read} or
+@code{:readwrite}.  @var{value} is the initial value of the property,
+it can be of any valid type (see @code{dbus-call-method} for details).
+
+If @var{property} already exists on @var{path}, it will be
+overwritten.  For properties with access type @code{:read} this is the
+only way to change their values.  Properties with access type
+@code{:readwrite} can be changed by @code{dbus-set-property}.
+
+The interface @samp{org.freedesktop.DBus.Properties} is added to
+@var{path}, including a default handler for the @samp{Get},
+@samp{GetAll} and @samp{Set} methods of this interface.  When
+@var{emits-signal} is non-@code{nil}, the signal
+@samp{PropertiesChanged} is sent when the property is changed by
+@code{dbus-set-property}.
+
+When @var{dont-register-service} is non-@code{nil}, the known name
+@var{service} is not registered.  This means that other D-Bus clients
+have no way of noticing the newly registered method.  When interfaces
+are constructed incrementally by adding single methods or properties
+at a time, @var{dont-register-service} can be used to prevent other
+clients from discovering the still incomplete interface.
+
+@noindent Example:
+
+@lisp
+(dbus-register-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "name" :read "GNU Emacs")
+
+@result{} ((:session "org.freedesktop.TextEditor" "name")
+    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
+
+(dbus-register-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "version" :readwrite emacs-version t)
+
+@result{} ((:session "org.freedesktop.TextEditor" "version")
+    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
+@end lisp
+
+Other D-Bus applications can read the property via the default methods
+@samp{org.freedesktop.DBus.Properties.Get} and
+@samp{org.freedesktop.DBus.Properties.GetAll}.  Testing is also
+possible via the command line tool @code{dbus-send} in a shell:
+
+@example
+# dbus-send --session --print-reply \
+    --dest="org.freedesktop.TextEditor" \
+    "/org/freedesktop/TextEditor" \
+    "org.freedesktop.DBus.Properties.GetAll" \
+    string:"org.freedesktop.TextEditor"
+
+@print{} method return sender=:1.22 -> dest=:1.23 reply_serial=3
+      array [
+         dict entry(
+            string "name"
+            variant             string "GNU Emacs"
+         )
+         dict entry(
+            string "version"
+            variant             string "23.1.50.5"
+         )
+      ]
+@end example
+
+It is also possible, to apply the @code{dbus-get-property},
+@code{dbus-get-all-properties} and @code{dbus-set-property} functions
+(@pxref{Properties and Annotations}).
+
+@lisp
+(dbus-set-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "version" "23.1.50")
+
+@result{} "23.1.50"
+
+(dbus-get-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "version")
+
+@result{} "23.1.50"
+@end lisp
+@end defun
+
+@defun dbus-unregister-object object
+Unregister @var{object} from the D-Bus.  @var{object} must be the
+result of a preceding @code{dbus-register-method},
+@code{dbus-register-property} or @code{dbus-register-signal} call
+(@pxref{Signals}).  It returns @code{t} if @var{object} has been
+unregistered, @code{nil} otherwise.
+
+When @var{object} identifies the last method or property, which is
+registered for the respective service, Emacs releases its association
+to the service from D-Bus.
+@end defun
+
 
 @node Signals
 @chapter Sending and receiving signals.
@@ -1436,19 +1658,69 @@ machine, when registered for signal @samp{DeviceAdded}, will show you
 which objects the GNU/Linux @code{hal} daemon adds.
 @end defun
 
-@defun dbus-unregister-object object
-Unregister @var{object} from the D-Bus.  @var{object} must be the
-result of a preceding @code{dbus-register-signal} or
-@code{dbus-register-method} call.  It returns @code{t} if @var{object}
-has been unregistered, @code{nil} otherwise.
+
+@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
 @cindex errors
 @cindex events
 
+The internal actions can be traced by running in a debug mode.
+
+@defvar dbus-debug
+If this variable is non-@code{nil}, D-Bus specific debug messages are raised.
+@end defvar
+
 Input parameters of @code{dbus-call-method},
 @code{dbus-call-method-non-blocking},
 @code{dbus-call-method-asynchronously}, and
@@ -1463,12 +1735,12 @@ appended to the @code{dbus-error}.
 @defspec dbus-ignore-errors forms@dots{}
 This executes @var{forms} exactly like a @code{progn}, except that
 @code{dbus-error} errors are ignored during the @var{forms}.  These
-errors can be made visible when variable @code{dbus-debug} is set to
-@code{t}.
+errors can be made visible when @code{dbus-debug} is set to @code{t}.
 @end defspec
 
-Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc
-Events, , , elisp}).  The generated event has this form:
+Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc
+Events, , , elisp}.  They are retrieved only, when Emacs runs in
+interactive mode.  The generated event has this form:
 
 @lisp
 (dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler}
@@ -1511,12 +1783,12 @@ The result is either the symbol @code{:system} or the symbol @code{:session}.
 
 @defun dbus-event-message-type event
 Returns the message type of the corresponding D-Bus message.  The
-result is a number.
+result is a natural number.
 @end defun
 
 @defun dbus-event-serial-number event
 Returns the serial number of the corresponding D-Bus message.
-The result is a number.
+The result is a natural number.
 @end defun
 
 @defun dbus-event-service-name event
@@ -1566,12 +1838,14 @@ D-Bus applications running.  Therefore, they shall check carefully,
 whether a given D-Bus error is related to them.
 
 
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
 @bye
-
-@ignore
-   arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8
-@end ignore