@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
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
@result{} 3
@end lisp
+@defun dbus-string-to-byte-array string
+Sometimes, D-Bus methods require as input parameter an array of bytes,
+instead of a string. If it is guaranteed, that @var{string} is an
+UTF8 string, this function performs the conversion. Example:
+
+@lisp
+(dbus-string-to-byte-array "/etc/hosts")
+
+@result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47
+ :byte 104 :byte 111 :byte 115 :byte 116 :byte 115)
+@end lisp
+@end defun
+
+@defun dbus-escape-as-identifier string
+Escape an arbitrary @var{string} so it follows the rules for a C
+identifier. The escaped string can be used as object path component,
+interface element component, bus name component or member name in
+D-Bus.
+
+The escaping consists of replacing all non-alphanumerics, and the
+first character if it's a digit, with an underscore and two
+lower-case hex digits. As a special case, "" is escaped to
+"_". Example:
+
+@lisp
+(dbus-escape-as-identifier "0123abc_xyz\x01\xff")
+
+@result{} "_30123abc_5fxyz_01_ff"
+@end lisp
+@end defun
+
@section Output parameters.
(@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
@end lisp
+@defun dbus-byte-array-to-string byte-array
+If a D-Bus method or signal returns an array of bytes, which are known
+to represent an UTF8 string, this function converts @var{byte-array}
+to the corresponding string. Example:
+
+@lisp
+(dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115))
+
+@result{} "/etc/hosts"
+@end lisp
+@end defun
+
+@defun dbus-unescape-from-identifier string
+Retrieve the original string from the encoded @var{string}.
+@var{string} must have been coded with
+@code{dbus-escape-as-identifier}. Example:
+
+@lisp
+(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")
+
+@result{} "0123abc_xyz\ 1ΓΏ"
+@end lisp
+@end defun
+
@node Synchronous Methods
@chapter Calling methods in a blocking way.
@samp{@strong{Application}} is the name of the application which
provides the interface.
+@deffn Constant dbus-service-emacs
+The well known service name of Emacs.
+@end deffn
+
+@deffn Constant dbus-path-emacs
+The object path head "/org/gnu/Emacs" used by Emacs. All object
+paths, used by offered methods or signals, shall start with this
+string.
+@end deffn
+
@defun dbus-register-method bus service path interface method handler
With this function, an application registers @var{method} on the D-Bus
@var{bus}.
@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}.
+@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
@lisp
(dbus-send-signal
- :session "org.gnu.Emacs" "/org/gnu/Emacs"
- "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
+ :session dbus-service-emacs dbus-path-emacs
+ (concat dbus-service-emacs ".FileManager") "FileModified"
+ "/home/albinus/.emacs")
@end lisp
@end defun
@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