@c %**end of header
@copying
-Copyright @copyright{} 2007, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 2007, 2008, 2009 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
* 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
+@end ifnottex
@menu
* Overview:: An overview of D-Bus.
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
@lisp
(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")
-@result{} "0123abc_xyz\ 1ÿ"
+@ifinfo
+@result{} "0123abc_xyz^Aÿ"
+@end ifinfo
+@ifnotinfo
+@result{} "0123abc_xyz^A@"y"
+@end ifnotinfo
@end lisp
@end defun
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}).
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}).
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-functions-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
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}.
+
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
@end defun
@defun dbus-unregister-object object
-Unregister @var{object} from the the D-Bus. @var{object} must be the
+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.
@end defun
@defun dbus-event-interface-name event
-Returns the interface name of of the D-Bus object @var{event} is coming from.
+Returns the interface name of the D-Bus object @var{event} is coming from.
@end defun
@defun dbus-event-member-name event
-Returns the member name of of the D-Bus object @var{event} is coming
+Returns the member name of the D-Bus object @var{event} is coming
from. It is either a signal name or a method name.
@end defun
D-Bus errors are not propagated during event handling, because it is
usually not desired. D-Bus errors in events can be made visible by
-setting the variable @code{dbus-debug} to @code{t}.
+setting the variable @code{dbus-debug} to @code{t}. They can also be
+handled by a hook function.
+
+@defvar dbus-event-error-hooks
+This hook variable keeps a list of functions, which are called when a
+D-Bus error happens in the event handler. Every function must accept
+two arguments, the event and the error variable catched in
+@code{condition-case} by @code{dbus-error}.
+
+Such functions can be used the adapt the error signal to be raised.
+Example:
+
+@lisp
+(defun my-dbus-event-error-handler (event error)
+ (when (string-equal (concat dbus-service-emacs ".FileManager")
+ (dbus-event-interface-name event))
+ (message "my-dbus-event-error-handler: %S %S" event error)
+ (signal 'file-error (cdr error))))
+
+(add-hook 'dbus-event-error-hooks 'my-dbus-event-error-handler)
+@end lisp
+@end defvar
+
+Hook functions shall take into account, that there might be other
+D-Bus applications running. Therefore, they shall check carefully,
+whether a given D-Bus error is related to them.
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
-@contents
-@c End of dbus.texi
@bye
@ignore
HCoop / bpt / emacs.git / blobdiff