From eb932e8a59875d4499def7f94568f56526a461ef Mon Sep 17 00:00:00 2001
From: Michael Albinus <michael.albinus@gmx.de>
Date: Sun, 3 Aug 2008 17:14:34 +0000
Subject: [PATCH] * dbus.texi (Receiving Method Calls): Document error handling
 of own D-Bus methods.

---
 doc/misc/ChangeLog |  5 +++++
 doc/misc/dbus.texi | 34 +++++++++++++++++++++++++++++++---
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 1ce8133fd22..b80aeb1abd0 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2008-08-03  Michael Albinus  <michael.albinus@gmx.de>
+
+	* dbus.texi (Receiving Method Calls): Document error handling of own
+	D-Bus methods.
+
 2008-08-01  Bill Wohler  <wohler@newt.com>
 
 	* mh-e.texi (Reading Mail)
diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 0b761cef6da..c7692e44bbe 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -1219,9 +1219,9 @@ registration for @var{method}.  Example:
   "org.freedesktop.TextEditor" "OpenFile"
   'my-dbus-method-handler)
 
-@result{} ((:system "org.freedesktop.TextEditor" "OpenFile")
+@result{} ((:session "org.freedesktop.TextEditor" "OpenFile")
     ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
-     my-method-handler))
+     my-dbus-method-handler))
 @end lisp
 
 If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile}
@@ -1237,7 +1237,35 @@ could use the command line tool @code{dbus-send} in a shell:
     "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts"
 
 @print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2
-     boolean true
+      boolean true
+@end example
+
+You can indicate an error by raising the Emacs signal
+@code{dbus-error}.  The handler above could be changed like this:
+
+@lisp
+(defun my-dbus-method-handler (&rest args)
+  (unless (and (= (length args) 1) (stringp (car args)))
+    (signal 'dbus-error (list (format "Wrong argument list: %S" args))))
+  (condition-case err
+      (find-file (car args))
+    (error (signal 'dbus-error (cdr err))))
+  t)
+
+@result{} my-dbus-method-handler
+@end lisp
+
+The test runs then
+
+@example
+# dbus-send --session --print-reply \
+    --dest="org.freedesktop.TextEditor" \
+    "/org/freedesktop/TextEditor" \
+    "org.freedesktop.TextEditor.OpenFile" \
+    string:"/etc/hosts" string:"/etc/passwd"
+
+@print{} Error org.freedesktop.DBus.Error.Failed:
+   Wrong argument list: ("/etc/hosts" "/etc/passwd")
 @end example
 @end defun
 
-- 
2.39.2