9
Copyright @copyright{} 2007, 2008 Free Software Foundation, Inc.
9
Copyright @copyright{} 2007, 2008, 2009 Free Software Foundation, Inc.
12
12
Permission is granted to copy, distribute and/or modify this document
13
under the terms of the GNU Free Documentation License, Version 1.2 or
13
under the terms of the GNU Free Documentation License, Version 1.3 or
14
14
any later version published by the Free Software Foundation; with no
15
15
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
16
16
and with the Back-Cover Texts as in (a) below. A copy of the license
27
27
* D-Bus: (dbus). Using D-Bus in Emacs.
31
32
@node Top, Overview, (dir), (dir)
32
33
@top D-Bus integration in Emacs
951
@defun dbus-string-to-byte-array string
952
Sometimes, D-Bus methods require as input parameter an array of bytes,
953
instead of a string. If it is guaranteed, that @var{string} is an
954
UTF8 string, this function performs the conversion. Example:
957
(dbus-string-to-byte-array "/etc/hosts")
959
@result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47
960
:byte 104 :byte 111 :byte 115 :byte 116 :byte 115)
964
@defun dbus-escape-as-identifier string
965
Escape an arbitrary @var{string} so it follows the rules for a C
966
identifier. The escaped string can be used as object path component,
967
interface element component, bus name component or member name in
970
The escaping consists of replacing all non-alphanumerics, and the
971
first character if it's a digit, with an underscore and two
972
lower-case hex digits. As a special case, "" is escaped to
976
(dbus-escape-as-identifier "0123abc_xyz\x01\xff")
978
@result{} "_30123abc_5fxyz_01_ff"
949
983
@section Output parameters.
991
1025
(@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
1028
@defun dbus-byte-array-to-string byte-array
1029
If a D-Bus method or signal returns an array of bytes, which are known
1030
to represent an UTF8 string, this function converts @var{byte-array}
1031
to the corresponding string. Example:
1034
(dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115))
1036
@result{} "/etc/hosts"
1040
@defun dbus-unescape-from-identifier string
1041
Retrieve the original string from the encoded @var{string}.
1042
@var{string} must have been coded with
1043
@code{dbus-escape-as-identifier}. Example:
1046
(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")
1048
@result{} "0123abc_xyzÿ"
995
1053
@node Synchronous Methods
996
1054
@chapter Calling methods in a blocking way.
1173
1231
@samp{@strong{Application}} is the name of the application which
1174
1232
provides the interface.
1234
@deffn Constant dbus-service-emacs
1235
The well known service name of Emacs.
1238
@deffn Constant dbus-path-emacs
1239
The object path head "/org/gnu/Emacs" used by Emacs. All object
1240
paths, used by offered methods or signals, shall start with this
1176
1244
@defun dbus-register-method bus service path interface method handler
1177
1245
With this function, an application registers @var{method} on the D-Bus
1189
1257
@var{interface} is the interface offered by @var{service}. It must
1190
1258
provide @var{method}.
1192
@var{handler} is a Lisp function to be called when when a @var{method}
1193
call is is received. It must accept as arguments the input arguments
1194
of @var{method}. @var{handler} must return a list, which elements are
1195
used as arguments for the reply message of @var{method}. This list
1196
can be composed like the input parameters in @ref{Type Conversion}.
1260
@var{handler} is a Lisp function to be called when a @var{method} call
1261
is received. It must accept as arguments the input arguments of
1262
@var{method}. @var{handler} should return a list, whose elements are
1263
to be used as arguments for the reply message of @var{method}. This
1264
list can be composed like the input parameters in @ref{Type
1267
If @var{handler} wants to return just one Lisp object and it is not a
1268
cons cell, @var{handler} can return this object directly, instead of
1269
returning a list containing the object.
1198
1271
The default D-Bus timeout when waiting for a message reply is 25
1199
1272
seconds. This value could be even smaller, depending on the calling
1298
1371
(dbus-send-signal
1299
:session "org.gnu.Emacs" "/org/gnu/Emacs"
1300
"org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
1372
:session dbus-service-emacs dbus-path-emacs
1373
(concat dbus-service-emacs ".FileManager") "FileModified"
1374
"/home/albinus/.emacs")
1365
1439
@defun dbus-unregister-object object
1366
Unregister @var{object} from the the D-Bus. @var{object} must be the
1440
Unregister @var{object} from the D-Bus. @var{object} must be the
1367
1441
result of a preceding @code{dbus-register-signal} or
1368
1442
@code{dbus-register-method} call. It returns @code{t} if @var{object}
1369
1443
has been unregistered, @code{nil} otherwise.
1456
1530
@defun dbus-event-interface-name event
1457
Returns the interface name of of the D-Bus object @var{event} is coming from.
1531
Returns the interface name of the D-Bus object @var{event} is coming from.
1460
1534
@defun dbus-event-member-name event
1461
Returns the member name of of the D-Bus object @var{event} is coming
1535
Returns the member name of the D-Bus object @var{event} is coming
1462
1536
from. It is either a signal name or a method name.
1465
1539
D-Bus errors are not propagated during event handling, because it is
1466
1540
usually not desired. D-Bus errors in events can be made visible by
1467
setting the variable @code{dbus-debug} to @code{t}.
1541
setting the variable @code{dbus-debug} to @code{t}. They can also be
1542
handled by a hook function.
1544
@defvar dbus-event-error-hooks
1545
This hook variable keeps a list of functions, which are called when a
1546
D-Bus error happens in the event handler. Every function must accept
1547
two arguments, the event and the error variable catched in
1548
@code{condition-case} by @code{dbus-error}.
1550
Such functions can be used the adapt the error signal to be raised.
1554
(defun my-dbus-event-error-handler (event error)
1555
(when (string-equal (concat dbus-service-emacs ".FileManager")
1556
(dbus-event-interface-name event))
1557
(message "my-dbus-event-error-handler: %S %S" event error)
1558
(signal 'file-error (cdr error))))
1560
(add-hook 'dbus-event-error-hooks 'my-dbus-event-error-handler)
1564
Hook functions shall take into account, that there might be other
1565
D-Bus applications running. Therefore, they shall check carefully,
1566
whether a given D-Bus error is related to them.
1470
1569
@node GNU Free Documentation License
1471
1570
@appendix GNU Free Documentation License
1472
1571
@include doclicense.texi
added
removed
doc/misc/dbus.texi
