+
+Some of the match rules have been added to a later version of D-Bus.
+In order to test the availability of such features, you could register
+for a dummy signal, and check the result:
+
+@lisp
+(dbus-ignore-errors
+ (dbus-register-signal
+ :system nil nil nil nil 'ignore :path-namespace "/invalid/path"))
+
+@result{} nil
+@end lisp
+@end defun
+
+
+@node Alternative Buses
+@chapter Alternative buses and environments.
+@cindex bus names
+@cindex UNIX domain socket
+@cindex TCP/IP 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 or TCP/IP 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 &optional private
+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 buses, this function
+is called when loading @file{dbus.el}, there is no need to call it
+again.
+
+The function returns a number, which counts the connections this Emacs
+session has established to the @var{bus} under the same unique name
+(see @code{dbus-get-unique-name}). It depends on the libraries Emacs
+is linked with, and on the environment Emacs is running. For example,
+if Emacs is linked with the gtk toolkit, and it runs in a GTK-aware
+environment like Gnome, another connection might already be
+established.
+
+When @var{private} is non-@code{nil}, a new connection is established
+instead of reusing an existing one. It results in a new unique name
+at the bus. This can be used, if it is necessary to distinguish from
+another connection used in the same Emacs process, like the one
+established by GTK+. It should be used with care for at least the
+@code{:system} and @code{:session} buses, because other Emacs Lisp
+packages might already use this connection to those buses.
+
+Example: You initialize a connection to the AT-SPI bus on your host:
+
+@lisp
+(setq my-bus
+ (dbus-call-method
+ :session "org.a11y.Bus" "/org/a11y/bus"
+ "org.a11y.Bus" "GetAddress"))
+
+@result{} "unix:abstract=/tmp/dbus-2yzWHOCdSD,guid=a490dd26625870ca1298b6e10000fd7f"
+
+;; If Emacs is built with gtk support, and you run in a GTK enabled
+;; environment (like a GNOME session), the initialization reuses the
+;; connection established by GTK's atk bindings.
+(dbus-init-bus my-bus)
+
+@result{} 2
+
+(dbus-get-unique-name my-bus)
+
+@result{} ":1.19"
+
+;; Open a new connection to the same bus. This obsoletes the
+;; previous one.
+(dbus-init-bus my-bus 'private)
+
+@result{} 1
+
+(dbus-get-unique-name my-bus)
+
+@result{} ":1.20"
+@end lisp
+
+D-Bus addresses can specify different transport. A possible address
+could be based on TCP/IP sockets, see next example. However, it
+depends on the bus daemon configuration, which transport is supported.
+@end defun
+
+@defun dbus-setenv bus variable value
+Set the value of the @var{bus} environment variable @var{variable} to
+@var{value}.
+
+@var{bus} is either a Lisp symbol, @code{:system} or @code{:session},
+or a string denoting the bus address. Both @var{variable} and
+@var{value} should be strings.
+
+Normally, services inherit the environment of the bus daemon. This
+function adds to or modifies that environment when activating services.
+
+Some bus instances, such as @code{:system}, may disable setting the
+environment. In such cases, or if this feature is not available in
+older D-Bus versions, a @code{dbus-error} error is raised.
+
+As an example, it might be desirable to start X11 enabled services on
+a remote host's bus on the same X11 server the local Emacs is
+running. This could be achieved by
+
+@lisp
+(setq my-bus "unix:host=example.gnu.org,port=4711")
+
+@result{} "unix:host=example.gnu.org,port=4711"
+
+(dbus-init-bus my-bus)
+
+@result{} 1
+
+(dbus-setenv my-bus "DISPLAY" (getenv "DISPLAY"))
+
+@result{} nil
+@end lisp
HCoop / bpt / emacs.git / blobdiff