1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/dbus
4 @settitle Using of D-Bus
5 @c @setchapternewpage odd
9 Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.3 or
14 any later version published by the Free Software Foundation; with no
15 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
16 and with the Back-Cover Texts as in (a) below. A copy of the license
17 is included in the section entitled ``GNU Free Documentation License''.
19 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
20 modify this GNU manual. Buying copies from the FSF supports it in
21 developing GNU and promoting software freedom.''
27 * D-Bus: (dbus). Using D-Bus in Emacs.
33 @node Top, Overview, (dir), (dir)
34 @top D-Bus integration in Emacs
36 This manual documents an API for usage of D-Bus in Emacs. D-Bus is a
37 message bus system, a simple way for applications to talk to one
38 another. An overview of D-Bus can be found at
39 @uref{http://dbus.freedesktop.org/}.
46 * Overview:: An overview of D-Bus.
47 * Inspection:: Inspection of D-Bus services.
48 * Type Conversion:: Mapping Lisp types and D-Bus types.
49 * Synchronous Methods:: Calling methods in a blocking way.
50 * Asynchronous Methods:: Calling methods non-blocking.
51 * Receiving Method Calls:: Offering own methods.
52 * Signals:: Sending and receiving signals.
53 * Errors and Events:: Errors and events.
54 * GNU Free Documentation License:: The license for this documentation.
59 @chapter An overview of D-Bus
62 D-Bus is an inter-process communication mechanism for applications
63 residing on the same host. The communication is based on
64 @dfn{messages}. Data in the messages is carried in a structured way,
65 it is not just a byte stream.
67 The communication is connection oriented to two kinds of message
68 buses: a so called @dfn{system bus}, and a @dfn{session bus}. On a
69 given machine, there is always one single system bus for miscellaneous
70 system-wide communication, like changing of hardware configuration.
71 On the other hand, the session bus is always related to a single
74 Every client application, which is connected to a bus, registers under
75 a @dfn{unique name} at the bus. This name is used for identifying the
76 client application. Such a unique name starts always with a colon,
77 and looks like @samp{:1.42}.
79 Additionally, a client application can register itself to a so called
80 @dfn{known name}, which is a series of identifiers separated by dots,
81 as in @samp{org.gnu.Emacs}. If several applications register to the
82 same known name, these registrations are queued, and only the first
83 application which has registered for the known name is reachable via
84 this name. If this application disconnects from the bus, the next
85 queued unique name becomes the owner of this known name.
87 An application can install one or several objects under its name.
88 Such objects are identified by an @dfn{object path}, which looks
89 similar to paths in a filesystem. An example of such an object path
90 could be @samp{/org/gnu/Emacs/}.
92 Applications might send a request to an object, that means sending a
93 message with some data as input parameters, and receiving a message
94 from that object with the result of this message, the output
95 parameters. Such a request is called @dfn{method} in D-Bus.
97 The other form of communication are @dfn{signals}. The underlying
98 message is emitted from an object and will be received by all other
99 applications which have registered for such a signal.
101 All methods and signals an object supports are called @dfn{interface}
102 of the object. Interfaces are specified under a hierarchical name in
103 D-Bus; an object can support several interfaces. Such an interface
104 name could be @samp{org.gnu.Emacs.TextEditor} or
105 @samp{org.gnu.Emacs.FileManager}.
109 @chapter Inspection of D-Bus services.
113 * Bus names:: Discovering D-Bus names.
114 * Introspection:: Knowing the details of D-Bus services.
115 * Nodes and Interfaces:: Detecting object paths and interfaces.
116 * Methods and Signal:: Applying the functionality.
117 * Properties and Annotations:: What else to know about interfaces.
118 * Arguments and Signatures:: The final details.
125 There are several basic functions which inspect the buses for
126 registered names. Internally they use the basic interface
127 @samp{org.freedesktop.DBus}, which is supported by all objects of a bus.
129 @defun dbus-list-activatable-names
130 This function returns the D-Bus service names, which can be activated.
131 An activatable service is described in a service registration file.
132 Under GNU/Linux, such files are located at
133 @file{/usr/share/dbus-1/services/}.
135 The result is a list of strings, which is @code{nil} when there are no
136 activatable service names at all.
139 @defun dbus-list-names bus
140 All service names, which are registered at D-Bus @var{bus}, are
141 returned. The result is a list of strings, which is @code{nil} when
142 there are no registered service names at all. Well known names are
143 strings like @samp{org.freedesktop.DBus}. Names starting with
144 @samp{:} are unique names for services.
146 @var{bus} must be either the symbol @code{:system} or the symbol
150 @defun dbus-list-known-names bus
151 Retrieves all services which correspond to a known name in @var{bus}.
152 A service has a known name if it doesn't start with @samp{:}. The
153 result is a list of strings, which is @code{nil} when there are no
156 @var{bus} must be either the symbol @code{:system} or the symbol
160 @defun dbus-list-queued-owners bus service
161 For a given service, registered at D-Bus @var{bus} under the name
162 @var{service}, all queued unique names are returned. The result is a
163 list of strings, or @code{nil} when there are no queued names for
164 @var{service} at all.
166 @var{bus} must be either the symbol @code{:system} or the symbol
167 @code{:session}. @var{service} must be a known service name as
171 @defun dbus-get-name-owner bus service
172 For a given service, registered at D-Bus @var{bus} under the name
173 @var{service}, the unique name of the name owner is returned. The
174 result is a string, or @code{nil} when there exist no name owner of
177 @var{bus} must be either the symbol @code{:system} or the symbol
178 @code{:session}. @var{service} must be a known service name as
182 @defun dbus-ping bus service &optional timeout
183 Check whether the service name @var{service} is registered at D-Bus
184 @var{bus}. @var{service} might not have been started yet, it is
185 autostarted if possible. The result is either @code{t} or @code{nil}.
187 @var{bus} must be either the symbol @code{:system} or the symbol
188 @code{:session}. @var{service} must be a string. @var{timeout}, a
189 nonnegative integer, specifies the maximum number of milliseconds
190 @code{dbus-ping} must return. The default value is 25,000. Example:
194 "%s screensaver on board."
196 ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome")
197 ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE")
201 If it shall be checked whether @var{service} is already running
202 without autostarting it, one shall apply
205 (member service (dbus-list-known-names bus))
209 @defun dbus-get-unique-name bus
210 The unique name, under which Emacs is registered at D-Bus @var{bus},
211 is returned as string.
213 @var{bus} must be either the symbol @code{:system} or the symbol
219 @section Knowing the details of D-Bus services.
221 D-Bus services publish their interfaces. This can be retrieved and
222 analyzed during runtime, in order to understand the used
225 The resulting introspection data are in XML format. The root
226 introspection element is always a @code{node} element. It might have
227 a @code{name} attribute, which denotes the (absolute) object path an
228 interface is introspected.
230 The root @code{node} element may have @code{node} and @code{interface}
231 children. A child @code{node} element must have a @code{name}
232 attribute, this case it is the relative object path to the root
235 An @code{interface} element has just one attribute, @code{name}, which
236 is the full name of that interface. The default interface
237 @samp{org.freedesktop.DBus.Introspectable} is always present. Example:
240 <node name="/org/bluez">
241 <interface name="org.freedesktop.DBus.Introspectable">
244 <interface name="org.bluez.Manager">
247 <interface name="org.bluez.Database">
250 <interface name="org.bluez.Security">
253 <node name="service_audio"/>
254 <node name="service_input"/>
255 <node name="service_network"/>
256 <node name="service_serial"/>
260 Children of an @code{interface} element can be @code{method},
261 @code{signal} and @code{property} elements. A @code{method} element
262 stands for a D-Bus method of the surrounding interface. The element
263 itself has a @code{name} attribute, showing the method name. Children
264 elements @code{arg} stand for the arguments of a method. Example:
267 <method name="ResolveHostName">
268 <arg name="interface" type="i" direction="in"/>
269 <arg name="protocol" type="i" direction="in"/>
270 <arg name="name" type="s" direction="in"/>
271 <arg name="aprotocol" type="i" direction="in"/>
272 <arg name="flags" type="u" direction="in"/>
273 <arg name="interface" type="i" direction="out"/>
274 <arg name="protocol" type="i" direction="out"/>
275 <arg name="name" type="s" direction="out"/>
276 <arg name="aprotocol" type="i" direction="out"/>
277 <arg name="address" type="s" direction="out"/>
278 <arg name="flags" type="u" direction="out"/>
282 @code{arg} elements can have the attributes @code{name}, @code{type}
283 and @code{direction}. The @code{name} attribute is optional. The
284 @code{type} attribute stands for the @dfn{signature} of the argument
285 in D-Bus. For a discussion of D-Bus types and their Lisp
286 representation see @ref{Type Conversion}.@footnote{D-Bus signatures
287 are explained in the D-Bus specification
288 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.}
289 The @code{direction} attribute of an @code{arg} element can be only
290 @samp{in} or @samp{out}; in case it is omitted, it defaults to
293 A @code{signal} element of an @code{interface} has a similar
294 structure. The @code{direction} attribute of an @code{arg} child
295 element can be only @samp{out} here; which is also the default value.
299 <signal name="StateChanged">
300 <arg name="state" type="i"/>
301 <arg name="error" type="s"/>
305 A @code{property} element has no @code{arg} child
306 element. It just has the attributes @code{name}, @code{type} and
307 @code{access}, which are all mandatory. The @code{access} attribute
308 allows the values @samp{readwrite}, @samp{read}, and @samp{write}.
312 <property name="Status" type="u" direction="read"/>
315 @code{annotation} elements can be children of @code{interface},
316 @code{method}, @code{signal}, and @code{property} elements. Unlike
317 properties, which can change their values during lifetime of a D-Bus
318 object, annotations are static. Often they are used for code
319 generators of D-Bus langugae bindings. Example:
322 <annotation name="de.berlios.Pinot.GetStatistics" value="pinotDBus"/>
325 Annotations have just @code{name} and @code{value} attributes, both
328 @defun dbus-introspect bus service path
329 This function returns all interfaces and sub-nodes of @var{service},
330 registered at object path @var{path} at bus @var{bus}.
332 @var{bus} must be either the symbol @code{:system} or the symbol
333 @code{:session}. @var{service} must be a known service name, and
334 @var{path} must be a valid object path. The last two parameters are
335 strings. The result, the introspection data, is a string in XML
340 :system "org.freedesktop.Hal"
341 "/org/freedesktop/Hal/devices/computer")
343 @result{} "<!DOCTYPE node PUBLIC
344 "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
345 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
347 <interface name="org.freedesktop.Hal.Device">
348 <method name="GetAllProperties">
349 <arg name="properties" direction="out" type="a@{sv@}"/>
352 <signal name="PropertyModified">
353 <arg name="num_updates" type="i"/>
354 <arg name="updates" type="a(sbb)"/>
361 This example informs us, that the service @samp{org.freedesktop.Hal}
362 at object path @samp{/org/freedesktop/Hal/devices/computer} offers the
363 interface @samp{org.freedesktop.Hal.Device} (and 2 other interfaces
364 not documented here). This interface contains the method
365 @samp{GetAllProperties}, which needs no input parameters, but returns
366 as output parameter an array of dictionary entries (key-value pairs).
367 Every dictionary entry has a string as key, and a variant as value.
369 The interface offers also a signal, which returns 2 parameters: an
370 integer, and an array consisting of elements which are a struct of a
371 string and 2 boolean values.@footnote{ The interfaces of the service
372 @samp{org.freedesktop.Hal} are described at
373 @uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.}
376 @defun dbus-introspect-xml bus service path
377 This function has the same intention as function
378 @code{dbus-introspect}. The returned value is a parsed XML tree,
379 which can be used for further analysis. Example:
383 :session "org.freedesktop.xesam.searcher"
384 "/org/freedesktop/xesam/searcher/main")
386 @result{} (node ((name . "/org/freedesktop/xesam/searcher/main"))
387 (interface ((name . "org.freedesktop.xesam.Search"))
388 (method ((name . "GetHitData"))
389 (arg ((name . "search") (type . "s") (direction . "in")))
390 (arg ((name . "hit_ids") (type . "au") (direction . "in")))
391 (arg ((name . "fields") (type . "as") (direction . "in")))
392 (arg ((name . "hit_data") (type . "aav") (direction . "out")))
395 (signal ((name . "HitsAdded"))
396 (arg ((name . "search") (type . "s")))
397 (arg ((name . "count") (type . "u")))
405 @defun dbus-introspect-get-attribute object attribute
406 It returns the @var{attribute} value of a D-Bus introspection
407 @var{object}. @var{object} can be every subtree of a parsed XML tree
408 as retrieved with @code{dbus-introspect-xml}. @var{attribute} must be
409 a string according to the attribute names in the D-Bus specification.
413 (dbus-introspect-get-attribute
414 (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends"
415 "/org/freedesktop/SystemToolsBackends/UsersConfig")
418 @result{} "/org/freedesktop/SystemToolsBackends/UsersConfig"
421 If @var{object} has no @var{attribute}, the function returns nil.
425 @node Nodes and Interfaces
426 @section Detecting object paths and interfaces.
428 The first elements, to be introspected for a D-Bus object, are further
429 object paths and interfaces.
431 @defun dbus-introspect-get-node-names bus service path
432 All node names of @var{service} in D-Bus @var{bus} at object path
433 @var{path} are returned as list of strings. Example:
436 (dbus-introspect-get-node-names
437 :session "org.gnome.seahorse" "/org/gnome/seahorse")
439 @result{} ("crypto" "keys")
442 The node names stand for further object paths of the D-Bus
443 @var{service}, relative to @var{path}. In the example,
444 @samp{/org/gnome/seahorse/crypto} and @samp{/org/gnome/seahorse/keys}
445 are also object paths of the D-Bus service @samp{org.gnome.seahorse}.
448 @defun dbus-introspect-get-all-nodes bus service path
449 This function returns all node names of @var{service} in D-Bus
450 @var{bus} at object path @var{path}. It returns a list of strings
451 with all object paths of @var{service}, starting at @var{path}.
455 (dbus-introspect-get-all-nodes :session "org.gnome.seahorse" "/")
457 @result{} ("/" "/org" "/org/gnome" "/org/gnome/seahorse"
458 "/org/gnome/seahorse/crypto"
459 "/org/gnome/seahorse/keys"
460 "/org/gnome/seahorse/keys/openpgp"
461 "/org/gnome/seahorse/keys/openpgp/local"
462 "/org/gnome/seahorse/keys/openssh"
463 "/org/gnome/seahorse/keys/openssh/local")
467 @defun dbus-introspect-get-interface-names bus service path
468 There will be returned a list strings of all interface names of
469 @var{service} in D-Bus @var{bus} at object path @var{path}. This list
470 will contain the default interface @samp{org.freedesktop.DBus.Introspectable}.
472 Another default interface is @samp{org.freedesktop.DBus.Properties}.
473 If present, @code{interface} elements can also have @code{property}
477 (dbus-introspect-get-interface-names
478 :system "org.freedesktop.Hal"
479 "/org/freedesktop/Hal/devices/computer")
481 @result{} ("org.freedesktop.DBus.Introspectable"
482 "org.freedesktop.Hal.Device"
483 "org.freedesktop.Hal.Device.SystemPowerManagement"
484 "org.freedesktop.Hal.Device.CPUFreq")
488 @defun dbus-introspect-get-interface bus service path interface
489 Return @var{interface} of @var{service} in D-Bus @var{bus} at object
490 path @var{path}. The return value is an XML element. @var{interface}
491 must be a string, element of the list returned by
492 @code{dbus-introspect-get-interface-names}. Example:
495 (dbus-introspect-get-interface
496 :session "org.freedesktop.xesam.searcher"
497 "/org/freedesktop/xesam/searcher/main"
498 "org.freedesktop.xesam.Search")
500 @result{} (interface ((name . "org.freedesktop.xesam.Search"))
501 (method ((name . "GetHitData"))
502 (arg ((name . "search") (type . "s") (direction . "in")))
503 (arg ((name . "hit_ids") (type . "au") (direction . "in")))
504 (arg ((name . "fields") (type . "as") (direction . "in")))
505 (arg ((name . "hit_data") (type . "aav") (direction . "out")))
508 (signal ((name . "HitsAdded"))
509 (arg ((name . "search") (type . "s")))
510 (arg ((name . "count") (type . "u")))
517 With these functions, it is possible to retrieve all introspection
518 data from a running system:
521 (with-current-buffer (switch-to-buffer "*introspect*")
523 (dolist (service (dbus-list-known-names :session))
524 (dolist (path (dbus-introspect-get-all-nodes :session service "/"))
525 ;; We want to introspect only elements, which have more than
526 ;; the default interface "org.freedesktop.DBus.Introspectable".
528 "org.freedesktop.DBus.Introspectable"
529 (dbus-introspect-get-interface-names :session service path))
530 (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path)
531 (dbus-introspect :session service path))
536 @node Methods and Signal
537 @section Applying the functionality.
539 Methods and signals are the communicatione means to D-Bus. The
540 following functions return their specifications.
542 @defun dbus-introspect-get-method-names bus service path interface
543 Return a list of strings of all method names of @var{interface} of
544 @var{service} in D-Bus @var{bus} at object path @var{path}. Example:
547 (dbus-introspect-get-method-names
548 :session "org.freedesktop.xesam.searcher"
549 "/org/freedesktop/xesam/searcher/main"
550 "org.freedesktop.xesam.Search")
552 @result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession"
553 "CloseSession" "GetHitData" "SetProperty" "NewSearch"
554 "GetProperty" "CloseSearch")
558 @defun dbus-introspect-get-method bus service path interface method
559 This function returns @var{method} of @var{interface} as XML element.
560 It must be located at @var{service} in D-Bus @var{bus} at object path
561 @var{path}. @var{method} must be a string, element of the list
562 returned by @code{dbus-introspect-get-method-names}. Example:
565 (dbus-introspect-get-method
566 :session "org.freedesktop.xesam.searcher"
567 "/org/freedesktop/xesam/searcher/main"
568 "org.freedesktop.xesam.Search" "GetHitData")
570 @result{} (method ((name . "GetHitData"))
571 (arg ((name . "search") (type . "s") (direction . "in")))
572 (arg ((name . "hit_ids") (type . "au") (direction . "in")))
573 (arg ((name . "fields") (type . "as") (direction . "in")))
574 (arg ((name . "hit_data") (type . "aav") (direction . "out")))
579 @defun dbus-introspect-get-signal-names bus service path interface
580 Return a list of strings of all signal names of @var{interface} of
581 @var{service} in D-Bus @var{bus} at object path @var{path}. Example:
584 (dbus-introspect-get-signal-names
585 :session "org.freedesktop.xesam.searcher"
586 "/org/freedesktop/xesam/searcher/main"
587 "org.freedesktop.xesam.Search")
589 @result{} ("StateChanged" "SearchDone" "HitsModified"
590 "HitsRemoved" "HitsAdded")
594 @defun dbus-introspect-get-signal bus service path interface signal
595 This function returns @var{signal} of @var{interface} as XML element.
596 It must be located at @var{service} in D-Bus @var{bus} at object path
597 @var{path}. @var{signal} must be a string, element of the list
598 returned by @code{dbus-introspect-get-signal-names}. Example:
601 (dbus-introspect-get-signal
602 :session "org.freedesktop.xesam.searcher"
603 "/org/freedesktop/xesam/searcher/main"
604 "org.freedesktop.xesam.Search" "HitsAdded")
606 @result{} (signal ((name . "HitsAdded"))
607 (arg ((name . "search") (type . "s")))
608 (arg ((name . "count") (type . "u")))
614 @node Properties and Annotations
615 @section What else to know about interfaces.
617 Interfaces can have properties. These can be exposed via the
618 @samp{org.freedesktop.DBus.Properties} interface@footnote{See
619 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}.
620 That is, properties can be retrieved and changed during lifetime of an
623 Annotations, on the other hand, are static values for an element.
624 Often, they are used to instruct generators, how to generate code from
625 the interface for a given language binding.
627 @defun dbus-introspect-get-property-names bus service path interface
628 Return a list of strings with all property names of @var{interface} of
629 @var{service} in D-Bus @var{bus} at object path @var{path}. Example:
632 (dbus-introspect-get-property-names
633 :session "org.kde.kded" "/modules/networkstatus"
634 "org.kde.Solid.Networking.Client")
639 If an interface declares properties, the corresponding element supports
640 also the @samp{org.freedesktop.DBus.Properties} interface.
643 @defun dbus-introspect-get-property bus service path interface property
644 This function returns @var{property} of @var{interface} as XML element.
645 It must be located at @var{service} in D-Bus @var{bus} at object path
646 @var{path}. @var{property} must be a string, element of the list
647 returned by @code{dbus-introspect-get-property-names}.
649 A @var{property} value can be retrieved by the function
650 @code{dbus-introspect-get-attribute}. Example:
653 (dbus-introspect-get-property
654 :session "org.kde.kded" "/modules/networkstatus"
655 "org.kde.Solid.Networking.Client" "Status")
657 @result{} (property ((access . "read") (type . "u") (name . "Status")))
659 (dbus-introspect-get-attribute
660 (dbus-introspect-get-property
661 :session "org.kde.kded" "/modules/networkstatus"
662 "org.kde.Solid.Networking.Client" "Status")
669 @defun dbus-get-property bus service path interface property
670 This function returns the value of @var{property} of @var{interface}.
671 It will be checked at @var{bus}, @var{service}, @var{path}. The
672 result can be any valid D-Bus value, or nil if there is no
673 @var{property}. Example:
677 :session "org.kde.kded" "/modules/networkstatus"
678 "org.kde.Solid.Networking.Client" "Status")
684 @defun dbus-set-property bus service path interface property value
685 Set value of @var{property} of @var{interface} to @var{value}. It
686 will be checked at @var{bus}, @var{service}, @var{path}. When the
687 value has been set successful, the result is @var{value}. Otherwise,
688 @code{nil} is returned. Example:
692 :session "org.kde.kaccess" "/MainApplication"
693 "com.trolltech.Qt.QApplication" "doubleClickInterval" 500)
699 @defun dbus-get-all-properties bus service path interface
700 This function returns all properties of @var{interface}. It will be
701 checked at @var{bus}, @var{service}, @var{path}. The result is a list
702 of cons. Every cons contains the name of the property, and its value.
703 If there are no properties, @code{nil} is returned. Example:
706 (dbus-get-all-properties
707 :session "org.kde.kaccess" "/MainApplication"
708 "com.trolltech.Qt.QApplication")
710 @result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500)
711 ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3)
712 ("globalStrut" 0 0) ("startDragTime" . 500)
713 ("startDragDistance" . 4) ("quitOnLastWindowClosed" . t)
718 @defun dbus-introspect-get-annotation-names bus service path interface &optional name
719 Return a list of all annotation names as list of strings. If
720 @var{name} is @code{nil}, the annotations are children of
721 @var{interface}, otherwise @var{name} must be a @code{method},
722 @code{signal}, or @code{property} XML element, where the annotations
726 (dbus-introspect-get-annotation-names
727 :session "de.berlios.Pinot" "/de/berlios/Pinot"
728 "de.berlios.Pinot" "GetStatistics")
730 @result{} ("de.berlios.Pinot.GetStatistics")
733 Default annotation names@footnote{See
734 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format}}
738 @item org.freedesktop.DBus.Deprecated
739 Whether or not the entity is deprecated; defaults to @code{nil}
741 @item org.freedesktop.DBus.GLib.CSymbol
742 The C symbol; may be used for @code{methods} and @code{interfaces}
744 @item org.freedesktop.DBus.Method.NoReply
745 If set, don't expect a reply to the @code{method} call; defaults to @code{nil}
749 @defun dbus-introspect-get-annotation bus service path interface name annotation
750 Return annotation @var{ANNOTATION} as XML object. If @var{name} is
751 @code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise
752 @var{name} must be the name of a @code{method}, @code{signal}, or
753 @code{property} XML element, where the @var{ANNOTATION} belongs to.
755 An attribute value can be retrieved by
756 @code{dbus-introspect-get-attribute}. Example:
759 (dbus-introspect-get-annotation
760 :session "de.berlios.Pinot" "/de/berlios/Pinot"
761 "de.berlios.Pinot" "GetStatistics"
762 "de.berlios.Pinot.GetStatistics")
764 @result{} (annotation ((name . "de.berlios.Pinot.GetStatistics")
765 (value . "pinotDBus")))
767 (dbus-introspect-get-attribute
768 (dbus-introspect-get-annotation
769 :session "de.berlios.Pinot" "/de/berlios/Pinot"
770 "de.berlios.Pinot" "GetStatistics"
771 "de.berlios.Pinot.GetStatistics")
774 @result{} "pinotDBus"
779 @node Arguments and Signatures
780 @section The final details.
782 Methods and signals have arguments. They are described in the
783 @code{arg} XML elements.
785 @defun dbus-introspect-get-argument-names bus service path interface name
786 Return a list of all argument names as list of strings. @var{name}
787 must be a @code{method} or @code{signal} XML element. Example:
790 (dbus-introspect-get-argument-names
791 :session "org.freedesktop.xesam.searcher"
792 "/org/freedesktop/xesam/searcher/main"
793 "org.freedesktop.xesam.Search" "GetHitData")
795 @result{} ("search" "hit_ids" "fields" "hit_data")
798 Argument names are optional; the function can return @code{nil}
799 therefore, even if the method or signal has arguments.
802 @defun dbus-introspect-get-argument bus service path interface name arg
803 Return argument @var{ARG} as XML object. @var{name}
804 must be a @code{method} or @code{signal} XML element. Example:
807 (dbus-introspect-get-argument
808 :session "org.freedesktop.xesam.searcher"
809 "/org/freedesktop/xesam/searcher/main"
810 "org.freedesktop.xesam.Search" "GetHitData" "search")
812 @result{} (arg ((name . "search") (type . "s") (direction . "in")))
816 @defun dbus-introspect-get-signature bus service path interface name &optional direction
817 Return signature of a @code{method} or @code{signal}, represented by
818 @var{name}, as string.
820 If @var{name} is a @code{method}, @var{direction} can be either
821 @samp{in} or @samp{out}. If @var{direction} is @code{nil}, @samp{in}
824 If @var{name} is a @code{signal}, and @var{direction} is
825 non-@code{nil}, @var{direction} must be @samp{out}. Example:
828 (dbus-introspect-get-signature
829 :session "org.freedesktop.xesam.searcher"
830 "/org/freedesktop/xesam/searcher/main"
831 "org.freedesktop.xesam.Search" "GetHitData" "in")
835 (dbus-introspect-get-signature
836 :session "org.freedesktop.xesam.searcher"
837 "/org/freedesktop/xesam/searcher/main"
838 "org.freedesktop.xesam.Search" "HitsAdded")
845 @node Type Conversion
846 @chapter Mapping Lisp types and D-Bus types.
847 @cindex type conversion
849 D-Bus method calls and signals accept usually several arguments as
850 parameters, either as input parameter, or as output parameter. Every
851 argument belongs to a D-Bus type.
853 Such arguments must be mapped between the value encoded as a D-Bus
854 type, and the corresponding type of Lisp objects. The mapping is
855 applied Lisp object @expansion{} D-Bus type for input parameters, and
856 D-Bus type @expansion{} Lisp object for output parameters.
859 @section Input parameters.
861 Input parameters for D-Bus methods and signals occur as arguments of a
862 Lisp function call. The following mapping to D-Bus types is
863 applied, when the corresponding D-Bus message is created:
866 @multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN}
867 @item Lisp type @tab @tab D-Bus type
869 @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN
870 @item number @tab @expansion{} @tab DBUS_TYPE_UINT32
871 @item integer @tab @expansion{} @tab DBUS_TYPE_INT32
872 @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE
873 @item string @tab @expansion{} @tab DBUS_TYPE_STRING
874 @item list @tab @expansion{} @tab DBUS_TYPE_ARRAY
878 Other Lisp objects, like symbols or hash tables, are not accepted as
881 If it is necessary to use another D-Bus type, a corresponding type
882 symbol can be preceeded to the corresponding Lisp object. Basic D-Bus
883 types are represented by the type symbols @code{:byte},
884 @code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32},
885 @code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double},
886 @code{:string}, @code{:object-path} and @code{:signature}.
892 (dbus-call-method @dots{} @var{NUMBER} @var{STRING})
898 (dbus-call-method @dots{} :uint32 @var{NUMBER} :string @var{STRING})
904 (dbus-call-method @dots{} :int32 @var{NUMBER} :signature @var{STRING})
907 The value for a byte D-Bus type can be any integer in the range 0
908 through 255. If a character is used as argument, modifiers
909 represented outside this range are stripped of. For example,
910 @code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to
911 @code{:byte ?\C-x} or @code{:byte ?\M-\C-x}.
913 A D-Bus compound type is always represented as a list. The @sc{car}
914 of this list can be the type symbol @code{:array}, @code{:variant},
915 @code{:struct} or @code{:dict-entry}, which would result in a
916 corresponding D-Bus container. @code{:array} is optional, because
917 this is the default compound D-Bus type for a list.
919 The objects being elements of the list are checked according to the
920 D-Bus compound type rules.
923 @item An array must contain only elements of the same D-Bus type. It
926 @item A variant must contain only one single element.
928 @item A dictionary entry must be element of an array, and it must
929 contain only a key-value pair of two elements, with a basic D-Bus type
932 @item There is no restriction for structs.
935 If an empty array needs an element D-Bus type other than string, it
936 can contain exactly one element of D-Bus type @code{:signature}. The
937 value of this element (a string) is used as the signature of the
938 elements of this array. Example:
942 :session "org.freedesktop.Notifications"
943 "/org/freedesktop/Notifications"
944 "org.freedesktop.Notifications" "Notify"
945 "GNU Emacs" ;; Application name.
946 0 ;; No replacement of other notifications.
948 "Notification summary" ;; Summary.
950 "This is a test notification, raised from %s" (emacs-version))
951 '(:array) ;; No actions (empty array of strings).
952 '(:array :signature "@{sv@}") ;; No hints
953 ;; (empty array of dictionary entries).
954 :int32 -1) ;; Default timeout.
959 @defun dbus-string-to-byte-array string
960 Sometimes, D-Bus methods require as input parameter an array of bytes,
961 instead of a string. If it is guaranteed, that @var{string} is an
962 UTF8 string, this function performs the conversion. Example:
965 (dbus-string-to-byte-array "/etc/hosts")
967 @result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47
968 :byte 104 :byte 111 :byte 115 :byte 116 :byte 115)
972 @defun dbus-escape-as-identifier string
973 Escape an arbitrary @var{string} so it follows the rules for a C
974 identifier. The escaped string can be used as object path component,
975 interface element component, bus name component or member name in
978 The escaping consists of replacing all non-alphanumerics, and the
979 first character if it's a digit, with an underscore and two
980 lower-case hex digits. As a special case, "" is escaped to
984 (dbus-escape-as-identifier "0123abc_xyz\x01\xff")
986 @result{} "_30123abc_5fxyz_01_ff"
991 @section Output parameters.
993 Output parameters of D-Bus methods and signals are mapped to Lisp
997 @multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}}
998 @item D-Bus type @tab @tab Lisp type
1000 @item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil}
1001 @item DBUS_TYPE_BYTE @tab @expansion{} @tab number
1002 @item DBUS_TYPE_UINT16 @tab @expansion{} @tab number
1003 @item DBUS_TYPE_INT16 @tab @expansion{} @tab number
1004 @item DBUS_TYPE_UINT32 @tab @expansion{} @tab number or float
1005 @item DBUS_TYPE_INT32 @tab @expansion{} @tab number or float
1006 @item DBUS_TYPE_UINT64 @tab @expansion{} @tab number or float
1007 @item DBUS_TYPE_INT64 @tab @expansion{} @tab number or float
1008 @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float
1009 @item DBUS_TYPE_STRING @tab @expansion{} @tab string
1010 @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
1011 @item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string
1012 @item DBUS_TYPE_ARRAY @tab @expansion{} @tab list
1013 @item DBUS_TYPE_VARIANT @tab @expansion{} @tab list
1014 @item DBUS_TYPE_STRUCT @tab @expansion{} @tab list
1015 @item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list
1019 A float object in case of @code{DBUS_TYPE_UINT32},
1020 @code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and
1021 @code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the
1022 Emacs number size range.
1024 The resulting list of the last 4 D-Bus compound types contains as
1025 elements the elements of the D-Bus container, mapped according to the
1028 The signal @code{PropertyModified}, discussed as example in
1029 @ref{Inspection}, would offer as Lisp data the following object
1030 (@var{BOOL} stands here for either @code{nil} or @code{t}):
1033 (@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
1036 @defun dbus-byte-array-to-string byte-array
1037 If a D-Bus method or signal returns an array of bytes, which are known
1038 to represent an UTF8 string, this function converts @var{byte-array}
1039 to the corresponding string. Example:
1042 (dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115))
1044 @result{} "/etc/hosts"
1048 @defun dbus-unescape-from-identifier string
1049 Retrieve the original string from the encoded @var{string}.
1050 @var{string} must have been coded with
1051 @code{dbus-escape-as-identifier}. Example:
1054 (dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")
1057 @result{} "0123abc_xyz^Aÿ"
1060 @result{} "0123abc_xyz^A@"y"
1066 @node Synchronous Methods
1067 @chapter Calling methods in a blocking way.
1068 @cindex method calls, synchronous
1069 @cindex synchronous method calls
1071 Methods can be called synchronously (@dfn{blocking}) or asynchronously
1072 (@dfn{non-blocking}).
1074 At D-Bus level, a method call consist of two messages: one message
1075 which carries the input parameters to the object owning the method to
1076 be called, and a reply message returning the resulting output
1077 parameters from the object.
1079 @defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args
1080 This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is
1081 either the symbol @code{:system} or the symbol @code{:session}.
1083 @var{service} is the D-Bus service name to be used. @var{path} is the
1084 D-Bus object path, @var{service} is registered at. @var{interface} is
1085 an interface offered by @var{service}. It must provide @var{method}.
1087 If the parameter @code{:timeout} is given, the following integer
1088 @var{timeout} specifies the maximum number of milliseconds the method
1089 call must return. The default value is 25,000. If the method call
1090 doesn't return in time, a D-Bus error is raised (@pxref{Errors and
1093 All other arguments args are passed to @var{method} as arguments.
1094 They are converted into D-Bus types as described in @ref{Type
1097 The function returns the resulting values of @var{method} as a list of
1098 Lisp objects, according to the type conversion rules described in
1099 @ref{Type Conversion}. Example:
1103 :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
1104 "org.gnome.seahorse.Keys" "GetKeyField"
1105 "openpgp:657984B8C7A966DD" "simple-name")
1107 @result{} (t ("Philip R. Zimmermann"))
1110 If the result of the method call is just one value, the converted Lisp
1111 object is returned instead of a list containing this single Lisp
1116 :system "org.freedesktop.Hal"
1117 "/org/freedesktop/Hal/devices/computer"
1118 "org.freedesktop.Hal.Device" "GetPropertyString"
1119 "system.kernel.machine")
1124 With the @code{dbus-introspect} function it is possible to explore the
1125 interfaces of @samp{org.freedesktop.Hal} service. It offers the
1126 interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
1127 path @samp{/org/freedesktop/Hal/Manager} as well as the interface
1128 @samp{org.freedesktop.Hal.Device} for all objects prefixed with the
1129 path @samp{/org/freedesktop/Hal/devices}. With the methods
1130 @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
1131 emulate the @code{lshal} command on GNU/Linux systems:
1136 :system "org.freedesktop.Hal"
1137 "/org/freedesktop/Hal/Manager"
1138 "org.freedesktop.Hal.Manager" "GetAllDevices"))
1139 (message "\nudi = %s" device)
1142 :system "org.freedesktop.Hal" device
1143 "org.freedesktop.Hal.Device" "GetAllProperties"))
1145 (car properties) (or (caar (cdr properties)) ""))))
1147 @print{} "udi = /org/freedesktop/Hal/devices/computer
1148 info.addons = (\"hald-addon-acpi\")
1149 info.bus = \"unknown\"
1150 info.product = \"Computer\"
1151 info.subsystem = \"unknown\"
1152 info.udi = \"/org/freedesktop/Hal/devices/computer\"
1153 linux.sysfs_path_device = \"(none)\"
1154 power_management.acpi.linux.version = \"20051216\"
1155 power_management.can_suspend_to_disk = t
1156 power_management.can_suspend_to_ram = \"\"
1157 power_management.type = \"acpi\"
1158 smbios.bios.release_date = \"11/07/2001\"
1159 system.chassis.manufacturer = \"COMPAL\"
1160 system.chassis.type = \"Notebook\"
1161 system.firmware.release_date = \"03/19/2005\"
1166 @defun dbus-call-method-non-blocking bus service path interface method &optional :timeout timeout &rest args
1167 Call @var{method} on the D-Bus @var{bus}, but don't block the event queue.
1168 This is necessary for communicating to registered D-Bus methods,
1169 which are running in the same Emacs process.
1171 The arguments are the same as in @code{dbus-call-method}. Example:
1174 (dbus-call-method-non-blocking
1175 :system "org.freedesktop.Hal"
1176 "/org/freedesktop/Hal/devices/computer"
1177 "org.freedesktop.Hal.Device" "GetPropertyString"
1178 "system.kernel.machine")
1185 @node Asynchronous Methods
1186 @chapter Calling methods non-blocking.
1187 @cindex method calls, asynchronous
1188 @cindex asynchronous method calls
1190 @defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args
1191 This function calls @var{method} on the D-Bus @var{bus}
1192 asynchronously. @var{bus} is either the symbol @code{:system} or the
1193 symbol @code{:session}.
1195 @var{service} is the D-Bus service name to be used. @var{path} is the
1196 D-Bus object path, @var{service} is registered at. @var{interface} is
1197 an interface offered by @var{service}. It must provide @var{method}.
1199 @var{handler} is a Lisp function, which is called when the
1200 corresponding return message has arrived. If @var{handler} is
1201 @code{nil}, no return message will be expected.
1203 If the parameter @code{:timeout} is given, the following integer
1204 @var{timeout} specifies the maximum number of milliseconds a reply
1205 message must arrive. The default value is 25,000. If there is no
1206 reply message in time, a D-Bus error is raised (@pxref{Errors and
1209 All other arguments args are passed to @var{method} as arguments.
1210 They are converted into D-Bus types as described in @ref{Type
1213 Unless @var{handler} is @code{nil}, the function returns a key into
1214 the hash table @code{dbus-registered-objects-table}. The
1215 corresponding entry in the hash table is removed, when the return
1216 message has been arrived, and @var{handler} is called. Example:
1219 (dbus-call-method-asynchronously
1220 :system "org.freedesktop.Hal"
1221 "/org/freedesktop/Hal/devices/computer"
1222 "org.freedesktop.Hal.Device" "GetPropertyString" 'message
1223 "system.kernel.machine")
1225 @result{} (:system 2)
1232 @node Receiving Method Calls
1233 @chapter Offering own methods.
1234 @cindex method calls, returning
1235 @cindex returning method calls
1237 Emacs can also offer own methods, which can be called by other
1238 applications. These methods could be an implementation of an
1239 interface of a well known service, like @samp{org.freedesktop.TextEditor}.
1241 It could be also an implementation of an own interface. In this case,
1242 the service name must be @samp{org.gnu.Emacs}. The object path shall
1243 begin with @samp{/org/gnu/Emacs/@strong{Application}/}, and the
1244 interface name shall be @code{org.gnu.Emacs.@strong{Application}}.
1245 @samp{@strong{Application}} is the name of the application which
1246 provides the interface.
1248 @deffn Constant dbus-service-emacs
1249 The well known service name of Emacs.
1252 @deffn Constant dbus-path-emacs
1253 The object path head "/org/gnu/Emacs" used by Emacs. All object
1254 paths, used by offered methods or signals, shall start with this
1258 @defun dbus-register-method bus service path interface method handler
1259 With this function, an application registers @var{method} on the D-Bus
1262 @var{bus} is either the symbol @code{:system} or the symbol
1265 @var{service} is the D-Bus service name of the D-Bus object
1266 @var{method} is registered for. It must be a known name.
1268 @var{path} is the D-Bus object path @var{service} is
1271 @var{interface} is the interface offered by @var{service}. It must
1272 provide @var{method}.
1274 @var{handler} is a Lisp function to be called when a @var{method} call
1275 is received. It must accept as arguments the input arguments of
1276 @var{method}. @var{handler} should return a list, whose elements are
1277 to be used as arguments for the reply message of @var{method}. This
1278 list can be composed like the input parameters in @ref{Type
1281 If @var{handler} wants to return just one Lisp object and it is not a
1282 cons cell, @var{handler} can return this object directly, instead of
1283 returning a list containing the object.
1285 In case @var{handler} shall return a reply message with an empty
1286 argument list, @var{handler} must return the symbol @code{:ignore}.
1288 The default D-Bus timeout when waiting for a message reply is 25
1289 seconds. This value could be even smaller, depending on the calling
1290 client. Therefore, @var{handler} shall not last longer than
1291 absolutely necessary.
1293 @code{dbus-register-method} returns a Lisp object, which can be used
1294 as argument in @code{dbus-unregister-object} for removing the
1295 registration for @var{method}. Example:
1298 (defun my-dbus-method-handler (filename)
1300 (if (find-file filename)
1301 (setq result '(:boolean t))
1302 (setq result '(:boolean nil)))
1305 @result{} my-dbus-method-handler
1307 (dbus-register-method
1308 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1309 "org.freedesktop.TextEditor" "OpenFile"
1310 'my-dbus-method-handler)
1312 @result{} ((:session "org.freedesktop.TextEditor" "OpenFile")
1313 ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1314 my-dbus-method-handler))
1317 If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile}
1318 from another D-Bus application with a filename as parameter, the file
1319 is opened in Emacs, and the method returns either @var{true} or
1320 @var{false}, indicating the success of the method. As test tool one
1321 could use the command line tool @code{dbus-send} in a shell:
1324 # dbus-send --session --print-reply \
1325 --dest="org.freedesktop.TextEditor" \
1326 "/org/freedesktop/TextEditor" \
1327 "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts"
1329 @print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2
1333 You can indicate an error by raising the Emacs signal
1334 @code{dbus-error}. The handler above could be changed like this:
1337 (defun my-dbus-method-handler (&rest args)
1338 (unless (and (= (length args) 1) (stringp (car args)))
1339 (signal 'dbus-error (list (format "Wrong argument list: %S" args))))
1341 (find-file (car args))
1342 (error (signal 'dbus-error (cdr err))))
1345 @result{} my-dbus-method-handler
1351 # dbus-send --session --print-reply \
1352 --dest="org.freedesktop.TextEditor" \
1353 "/org/freedesktop/TextEditor" \
1354 "org.freedesktop.TextEditor.OpenFile" \
1355 string:"/etc/hosts" string:"/etc/passwd"
1357 @print{} Error org.freedesktop.DBus.Error.Failed:
1358 Wrong argument list: ("/etc/hosts" "/etc/passwd")
1362 @defun dbus-register-property bus service path interface property access value
1363 With this function, an application declares a @var{property} on the D-Bus
1366 @var{bus} is either the symbol @code{:system} or the symbol
1369 @var{service} is the D-Bus service name of the D-Bus. It must be a
1372 @var{path} is the D-Bus object path @var{service} is
1375 @var{interface} is the name of the interface used at @var{path},
1376 @var{property} is the name of the property of @var{interface}.
1378 @var{access} indicates, whether the property can be changed by other
1379 services via D-Bus. It must be either the symbol @code{:read} or
1380 @code{:readwrite}. @var{value} is the initial value of the property,
1381 it can be of any valid type (see @code{dbus-call-method} for details).
1383 If @var{property} already exists on @var{path}, it will be
1384 overwritten. For properties with access type @code{:read} this is the
1385 only way to change their values. Properties with access type
1386 @code{:readwrite} can be changed by @code{dbus-set-property}.
1388 The interface @samp{org.freedesktop.DBus.Properties} is added to
1389 @var{path}, including a default handler for the @samp{Get},
1390 @samp{GetAll} and @samp{Set} methods of this interface. Example:
1393 (dbus-register-property
1394 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1395 "org.freedesktop.TextEditor" "name" :read "GNU Emacs")
1397 @result{} ((:session "org.freedesktop.TextEditor" "name")
1398 ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
1400 (dbus-register-property
1401 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1402 "org.freedesktop.TextEditor" "version" :readwrite emacs-version)
1404 @result{} ((:session "org.freedesktop.TextEditor" "version")
1405 ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
1408 Other D-Bus applications can read the property via the default methods
1409 @samp{org.freedesktop.DBus.Properties.Get} and
1410 @samp{org.freedesktop.DBus.Properties.GetAll}. Testing is also
1411 possible via the command line tool @code{dbus-send} in a shell:
1414 # dbus-send --session --print-reply \
1415 --dest="org.freedesktop.TextEditor" \
1416 "/org/freedesktop/TextEditor" \
1417 "org.freedesktop.DBus.Properties.GetAll" \
1418 string:"org.freedesktop.TextEditor"
1420 @print{} method return sender=:1.22 -> dest=:1.23 reply_serial=3
1424 variant string "GNU Emacs"
1428 variant string "23.1.50.5"
1433 It is also possible, to apply the @code{dbus-get-property},
1434 @code{dbus-get-all-properties} and @code{dbus-set-property} functions
1435 (@pxref{Properties and Annotations}).
1439 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1440 "org.freedesktop.TextEditor" "version" "23.1.50")
1445 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1446 "org.freedesktop.TextEditor" "version")
1452 @defun dbus-unregister-object object
1453 Unregister @var{object} from the D-Bus. @var{object} must be the
1454 result of a preceding @code{dbus-register-method},
1455 @code{dbus-register-property} or @code{dbus-register-signal} call
1456 (@pxref{Signals}). It returns @code{t} if @var{object} has been
1457 unregistered, @code{nil} otherwise.
1459 When @var{object} identifies the last method or property, which is
1460 registered for the respective service, Emacs releases its association
1461 to the service from D-Bus.
1464 @defun dbus-unregister-service bus service
1465 Unregister all objects from D-Bus @var{bus}, registered by Emacs for
1468 @var{bus} is either the symbol @code{:system} or the symbol
1471 @var{service} is the D-Bus service name of the D-Bus. It must be a
1472 known name. Emacs releases its association to @var{service} from
1478 @chapter Sending and receiving signals.
1481 Signals are broadcast messages. They carry input parameters, which
1482 are received by all objects which have registered for such a signal.
1484 @defun dbus-send-signal bus service path interface signal &rest args
1485 This function is similar to @code{dbus-call-method}. The difference
1486 is, that there are no returning output parameters.
1488 The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is
1489 either the symbol @code{:system} or the symbol @code{:session}. It
1490 doesn't matter whether another object has registered for @var{signal}.
1492 @var{service} is the D-Bus service name of the object the signal is
1493 emitted from. @var{path} is the corresponding D-Bus object path,
1494 @var{service} is registered at. @var{interface} is an interface
1495 offered by @var{service}. It must provide @var{signal}.
1497 All other arguments args are passed to @var{signal} as arguments.
1498 They are converted into D-Bus types as described in @ref{Type
1499 Conversion}. Example:
1503 :session dbus-service-emacs dbus-path-emacs
1504 (concat dbus-service-emacs ".FileManager") "FileModified"
1505 "/home/albinus/.emacs")
1509 @defun dbus-register-signal bus service path interface signal handler &rest args
1510 With this function, an application registers for @var{signal} on the
1513 @var{bus} is either the symbol @code{:system} or the symbol
1516 @var{service} is the D-Bus service name used by the sending D-Bus
1517 object. It can be either a known name or the unique name of the D-Bus
1518 object sending the signal. In case of a unique name, signals won't be
1519 received any longer once the object owning this unique name has
1520 disappeared, and a new queued object has replaced it.
1522 When @var{service} is @code{nil}, related signals from all D-Bus
1523 objects shall be accepted.
1525 @var{path} is the corresponding D-Bus object path, @var{service} is
1526 registered at. It can also be @code{nil} if the path name of incoming
1527 signals shall not be checked.
1529 @var{interface} is an interface offered by @var{service}. It must
1530 provide @var{signal}.
1532 @var{handler} is a Lisp function to be called when the @var{signal} is
1533 received. It must accept as arguments the output parameters
1534 @var{signal} is sending.
1536 All other arguments @var{args}, if specified, must be strings. They
1537 stand for the respective arguments of @var{signal} in their order, and
1538 are used for filtering as well. A @code{nil} argument might be used
1539 to preserve the order.
1541 @code{dbus-register-signal} returns a Lisp object, which can be used
1542 as argument in @code{dbus-unregister-object} for removing the
1543 registration for @var{signal}. Example:
1546 (defun my-dbus-signal-handler (device)
1547 (message "Device %s added" device))
1549 @result{} my-dbus-signal-handler
1551 (dbus-register-signal
1552 :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
1553 "org.freedesktop.Hal.Manager" "DeviceAdded"
1554 'my-dbus-signal-handler)
1556 @result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded")
1557 ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
1561 As we know from the introspection data of interface
1562 @samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded}
1563 provides one single parameter, which is mapped into a Lisp string.
1564 The callback function @code{my-dbus-signal-handler} must define one
1565 single string argument therefore. Plugging an USB device to your
1566 machine, when registered for signal @samp{DeviceAdded}, will show you
1567 which objects the GNU/Linux @code{hal} daemon adds.
1571 @node Errors and Events
1572 @chapter Errors and events.
1576 Input parameters of @code{dbus-call-method},
1577 @code{dbus-call-method-non-blocking},
1578 @code{dbus-call-method-asynchronously}, and
1579 @code{dbus-register-signal} are checked for correct D-Bus types. If
1580 there is a type mismatch, the Lisp error @code{wrong-type-argument}
1581 @code{D-Bus ARG} is raised.
1583 All errors raised by D-Bus are signaled with the error symbol
1584 @code{dbus-error}. If possible, error messages from D-Bus are
1585 appended to the @code{dbus-error}.
1587 @defspec dbus-ignore-errors forms@dots{}
1588 This executes @var{forms} exactly like a @code{progn}, except that
1589 @code{dbus-error} errors are ignored during the @var{forms}. These
1590 errors can be made visible when variable @code{dbus-debug} is set to
1594 Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc
1595 Events, , , elisp}. They are retrieved only, when Emacs runs in
1596 interactive mode. The generated event has this form:
1599 (dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler}
1603 @var{bus} identifies the D-Bus the message is coming from. It is
1604 either the symbol @code{:system} or the symbol @code{:session}.
1606 @var{type} is the D-Bus message type which has caused the event. It
1607 can be @code{dbus-message-type-invalid},
1608 @code{dbus-message-type-method-call},
1609 @code{dbus-message-type-method-return},
1610 @code{dbus-message-type-error}, or @code{dbus-message-type-signal}.
1611 @var{serial} is the serial number of the received D-Bus message.
1613 @var{service} and @var{path} are the unique name and the object path
1614 of the D-Bus object emitting the message. @var{interface} and
1615 @var{member} denote the message which has been sent.
1617 @var{handler} is the callback function which has been registered for
1618 this message (see @pxref{Signals}). When a @code{dbus-event} event
1619 arrives, @var{handler} is called with @var{args} as arguments.
1621 In order to inspect the @code{dbus-event} data, you could extend the
1622 definition of the callback function in @ref{Signals}:
1625 (defun my-dbus-signal-handler (&rest args)
1626 (message "my-dbus-signal-handler: %S" last-input-event))
1629 There exist convenience functions which could be called inside a
1630 callback function in order to retrieve the information from the event.
1632 @defun dbus-event-bus-name event
1633 Returns the bus name @var{event} is coming from.
1634 The result is either the symbol @code{:system} or the symbol @code{:session}.
1637 @defun dbus-event-message-type event
1638 Returns the message type of the corresponding D-Bus message. The
1642 @defun dbus-event-serial-number event
1643 Returns the serial number of the corresponding D-Bus message.
1644 The result is a number.
1647 @defun dbus-event-service-name event
1648 Returns the unique name of the D-Bus object @var{event} is coming from.
1651 @defun dbus-event-path-name event
1652 Returns the object path of the D-Bus object @var{event} is coming from.
1655 @defun dbus-event-interface-name event
1656 Returns the interface name of the D-Bus object @var{event} is coming from.
1659 @defun dbus-event-member-name event
1660 Returns the member name of the D-Bus object @var{event} is coming
1661 from. It is either a signal name or a method name.
1664 D-Bus errors are not propagated during event handling, because it is
1665 usually not desired. D-Bus errors in events can be made visible by
1666 setting the variable @code{dbus-debug} to @code{t}. They can also be
1667 handled by a hook function.
1669 @defvar dbus-event-error-hooks
1670 This hook variable keeps a list of functions, which are called when a
1671 D-Bus error happens in the event handler. Every function must accept
1672 two arguments, the event and the error variable catched in
1673 @code{condition-case} by @code{dbus-error}.
1675 Such functions can be used the adapt the error signal to be raised.
1679 (defun my-dbus-event-error-handler (event error)
1680 (when (string-equal (concat dbus-service-emacs ".FileManager")
1681 (dbus-event-interface-name event))
1682 (message "my-dbus-event-error-handler: %S %S" event error)
1683 (signal 'file-error (cdr error))))
1685 (add-hook 'dbus-event-error-hooks 'my-dbus-event-error-handler)
1689 Hook functions shall take into account, that there might be other
1690 D-Bus applications running. Therefore, they shall check carefully,
1691 whether a given D-Bus error is related to them.
1694 @node GNU Free Documentation License
1695 @appendix GNU Free Documentation License
1696 @include doclicense.texi
1701 arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8