2009-02-02 Carsten Dominik <dominik@science.uva.nl>

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

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index b93f29a..c012647 100644 (file)
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -6,7 +6,7 @@
 @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
@@ -1254,14 +1254,16 @@ registered.
 @var{interface} is the interface offered by @var{service}.  It must
 provide @var{method}.
 
-@var{handler} is a Lisp function to be called when when a @var{method}
-call is is received.  It must accept as arguments the input arguments
-of @var{method}.  @var{handler} must return a list, which elements are
-used as arguments for the reply message of @var{method}.  This list
-can be composed like the input parameters in @ref{Type Conversion}.
-If only one Lisp object is returned, and this object is not a consp,
-then @var{handler} can return this object directly, instead of of list
-of this object.
+@var{handler} is a Lisp function to be called when a @var{method} call
+is received.  It must accept as arguments the input arguments of
+@var{method}.  @var{handler} should return a list, whose elements are
+to be used as arguments for the reply message of @var{method}.  This
+list can be composed like the input parameters in @ref{Type
+Conversion}.
+
+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.
 
 The default D-Bus timeout when waiting for a message reply is 25
 seconds.  This value could be even smaller, depending on the calling
@@ -1523,17 +1525,42 @@ Returns the object path of the D-Bus object @var{event} is coming from.
 @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