1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/dbus
4 @settitle Using of D-Bus
5 @c @setchapternewpage odd
12 Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.3 or
17 any later version published by the Free Software Foundation; with no
18 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
19 and with the Back-Cover Texts as in (a) below. A copy of the license
20 is included in the section entitled ``GNU Free Documentation License''.
22 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
23 modify this GNU manual. Buying copies from the FSF supports it in
24 developing GNU and promoting software freedom.''
30 * D-Bus: (dbus). Using D-Bus in Emacs.
36 @node Top, Overview, (dir), (dir)
37 @top D-Bus integration in Emacs
39 This manual documents an API for usage of D-Bus in Emacs. D-Bus is a
40 message bus system, a simple way for applications to talk to one
41 another. An overview of D-Bus can be found at
42 @uref{http://dbus.freedesktop.org/}.
49 * Overview:: An overview of D-Bus.
50 * Inspection:: Inspection of D-Bus services.
51 * Type Conversion:: Mapping Lisp types and D-Bus types.
52 * Synchronous Methods:: Calling methods in a blocking way.
53 * Asynchronous Methods:: Calling methods non-blocking.
54 * Receiving Method Calls:: Offering own methods.
55 * Signals:: Sending and receiving signals.
56 * Errors and Events:: Errors and events.
57 * Index:: Index including concepts, functions, variables.
59 * GNU Free Documentation License:: The license for this documentation.
64 @chapter An overview of D-Bus
67 D-Bus is an inter-process communication mechanism for applications
68 residing on the same host. The communication is based on
69 @dfn{messages}. Data in the messages is carried in a structured way,
70 it is not just a byte stream.
72 The communication is connection oriented to two kinds of message
73 buses: a so called @dfn{system bus}, and a @dfn{session bus}. On a
74 given machine, there is always one single system bus for miscellaneous
75 system-wide communication, like changing of hardware configuration.
76 On the other hand, the session bus is always related to a single
79 Every client application, which is connected to a bus, registers under
80 a @dfn{unique name} at the bus. This name is used for identifying the
81 client application. Such a unique name starts always with a colon,
82 and looks like @samp{:1.42}.
84 Additionally, a client application can register itself to a so called
85 @dfn{known name}, which is a series of identifiers separated by dots,
86 as in @samp{org.gnu.Emacs}. If several applications register to the
87 same known name, these registrations are queued, and only the first
88 application which has registered for the known name is reachable via
89 this name. If this application disconnects from the bus, the next
90 queued unique name becomes the owner of this known name.
92 An application can install one or several objects under its name.
93 Such objects are identified by an @dfn{object path}, which looks
94 similar to paths in a filesystem. An example of such an object path
95 could be @samp{/org/gnu/Emacs/}.
97 Applications might send a request to an object, that means sending a
98 message with some data as input parameters, and receiving a message
99 from that object with the result of this message, the output
100 parameters. Such a request is called @dfn{method} in D-Bus.
102 The other form of communication are @dfn{signals}. The underlying
103 message is emitted from an object and will be received by all other
104 applications which have registered for such a signal.
106 All methods and signals an object supports are called @dfn{interface}
107 of the object. Interfaces are specified under a hierarchical name in
108 D-Bus; an object can support several interfaces. Such an interface
109 name could be @samp{org.gnu.Emacs.TextEditor} or
110 @samp{org.gnu.Emacs.FileManager}.
114 @chapter Inspection of D-Bus services.
118 * Bus names:: Discovering D-Bus names.
119 * Introspection:: Knowing the details of D-Bus services.
120 * Nodes and Interfaces:: Detecting object paths and interfaces.
121 * Methods and Signal:: Applying the functionality.
122 * Properties and Annotations:: What else to know about interfaces.
123 * Arguments and Signatures:: The final details.
130 There are several basic functions which inspect the buses for
131 registered names. Internally they use the basic interface
132 @samp{org.freedesktop.DBus}, which is supported by all objects of a bus.
134 @defun dbus-list-activatable-names
135 This function returns the D-Bus service names, which can be activated.
136 An activatable service is described in a service registration file.
137 Under GNU/Linux, such files are located at
138 @file{/usr/share/dbus-1/services/}.
140 The result is a list of strings, which is @code{nil} when there are no
141 activatable service names at all.
144 @defun dbus-list-names bus
145 All service names, which are registered at D-Bus @var{bus}, are
146 returned. The result is a list of strings, which is @code{nil} when
147 there are no registered service names at all. Well known names are
148 strings like @samp{org.freedesktop.DBus}. Names starting with
149 @samp{:} are unique names for services.
151 @var{bus} must be either the symbol @code{:system} or the symbol
155 @defun dbus-list-known-names bus
156 Retrieves all services which correspond to a known name in @var{bus}.
157 A service has a known name if it doesn't start with @samp{:}. The
158 result is a list of strings, which is @code{nil} when there are no
161 @var{bus} must be either the symbol @code{:system} or the symbol
165 @defun dbus-list-queued-owners bus service
166 For a given service, registered at D-Bus @var{bus} under the name
167 @var{service}, all queued unique names are returned. The result is a
168 list of strings, or @code{nil} when there are no queued names for
169 @var{service} at all.
171 @var{bus} must be either the symbol @code{:system} or the symbol
172 @code{:session}. @var{service} must be a known service name as
176 @defun dbus-get-name-owner bus service
177 For a given service, registered at D-Bus @var{bus} under the name
178 @var{service}, the unique name of the name owner is returned. The
179 result is a string, or @code{nil} when there exist no name owner of
182 @var{bus} must be either the symbol @code{:system} or the symbol
183 @code{:session}. @var{service} must be a known service name as
187 @defun dbus-ping bus service &optional timeout
188 Check whether the service name @var{service} is registered at D-Bus
189 @var{bus}. @var{service} might not have been started yet, it is
190 autostarted if possible. The result is either @code{t} or @code{nil}.
192 @var{bus} must be either the symbol @code{:system} or the symbol
193 @code{:session}. @var{service} must be a string. @var{timeout}, a
194 nonnegative integer, specifies the maximum number of milliseconds
195 @code{dbus-ping} must return. The default value is 25,000. Example:
199 "%s screensaver on board."
201 ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome")
202 ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE")
206 If it shall be checked whether @var{service} is already running
207 without autostarting it, one shall apply
210 (member service (dbus-list-known-names bus))
214 @defun dbus-get-unique-name bus
215 The unique name, under which Emacs is registered at D-Bus @var{bus},
216 is returned as string.
218 @var{bus} must be either the symbol @code{:system} or the symbol
224 @section Knowing the details of D-Bus services.
226 D-Bus services publish their interfaces. This can be retrieved and
227 analyzed during runtime, in order to understand the used
230 The resulting introspection data are in XML format. The root
231 introspection element is always a @code{node} element. It might have
232 a @code{name} attribute, which denotes the (absolute) object path an
233 interface is introspected.
235 The root @code{node} element may have @code{node} and @code{interface}
236 children. A child @code{node} element must have a @code{name}
237 attribute, this case it is the relative object path to the root
240 An @code{interface} element has just one attribute, @code{name}, which
241 is the full name of that interface. The default interface
242 @samp{org.freedesktop.DBus.Introspectable} is always present. Example:
245 <node name="/org/bluez">
246 <interface name="org.freedesktop.DBus.Introspectable">
249 <interface name="org.bluez.Manager">
252 <interface name="org.bluez.Database">
255 <interface name="org.bluez.Security">
258 <node name="service_audio"/>
259 <node name="service_input"/>
260 <node name="service_network"/>
261 <node name="service_serial"/>
265 Children of an @code{interface} element can be @code{method},
266 @code{signal} and @code{property} elements. A @code{method} element
267 stands for a D-Bus method of the surrounding interface. The element
268 itself has a @code{name} attribute, showing the method name. Children
269 elements @code{arg} stand for the arguments of a method. Example:
272 <method name="ResolveHostName">
273 <arg name="interface" type="i" direction="in"/>
274 <arg name="protocol" type="i" direction="in"/>
275 <arg name="name" type="s" direction="in"/>
276 <arg name="aprotocol" type="i" direction="in"/>
277 <arg name="flags" type="u" direction="in"/>
278 <arg name="interface" type="i" direction="out"/>
279 <arg name="protocol" type="i" direction="out"/>
280 <arg name="name" type="s" direction="out"/>
281 <arg name="aprotocol" type="i" direction="out"/>
282 <arg name="address" type="s" direction="out"/>
283 <arg name="flags" type="u" direction="out"/>
287 @code{arg} elements can have the attributes @code{name}, @code{type}
288 and @code{direction}. The @code{name} attribute is optional. The
289 @code{type} attribute stands for the @dfn{signature} of the argument
290 in D-Bus. For a discussion of D-Bus types and their Lisp
291 representation see @ref{Type Conversion}.@footnote{D-Bus signatures
292 are explained in the D-Bus specification
293 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.}
294 The @code{direction} attribute of an @code{arg} element can be only
295 @samp{in} or @samp{out}; in case it is omitted, it defaults to
298 A @code{signal} element of an @code{interface} has a similar
299 structure. The @code{direction} attribute of an @code{arg} child
300 element can be only @samp{out} here; which is also the default value.
304 <signal name="StateChanged">
305 <arg name="state" type="i"/>
306 <arg name="error" type="s"/>
310 A @code{property} element has no @code{arg} child
311 element. It just has the attributes @code{name}, @code{type} and
312 @code{access}, which are all mandatory. The @code{access} attribute
313 allows the values @samp{readwrite}, @samp{read}, and @samp{write}.
317 <property name="Status" type="u" direction="read"/>
320 @code{annotation} elements can be children of @code{interface},
321 @code{method}, @code{signal}, and @code{property} elements. Unlike
322 properties, which can change their values during lifetime of a D-Bus
323 object, annotations are static. Often they are used for code
324 generators of D-Bus langugae bindings. Example:
327 <annotation name="de.berlios.Pinot.GetStatistics" value="pinotDBus"/>
330 Annotations have just @code{name} and @code{value} attributes, both
333 @defun dbus-introspect bus service path
334 This function returns all interfaces and sub-nodes of @var{service},
335 registered at object path @var{path} at bus @var{bus}.
337 @var{bus} must be either the symbol @code{:system} or the symbol
338 @code{:session}. @var{service} must be a known service name, and
339 @var{path} must be a valid object path. The last two parameters are
340 strings. The result, the introspection data, is a string in XML
345 :system "org.freedesktop.Hal"
346 "/org/freedesktop/Hal/devices/computer")
348 @result{} "<!DOCTYPE node PUBLIC
349 "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
350 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
352 <interface name="org.freedesktop.Hal.Device">
353 <method name="GetAllProperties">
354 <arg name="properties" direction="out" type="a@{sv@}"/>
357 <signal name="PropertyModified">
358 <arg name="num_updates" type="i"/>
359 <arg name="updates" type="a(sbb)"/>
366 This example informs us, that the service @samp{org.freedesktop.Hal}
367 at object path @samp{/org/freedesktop/Hal/devices/computer} offers the
368 interface @samp{org.freedesktop.Hal.Device} (and 2 other interfaces
369 not documented here). This interface contains the method
370 @samp{GetAllProperties}, which needs no input parameters, but returns
371 as output parameter an array of dictionary entries (key-value pairs).
372 Every dictionary entry has a string as key, and a variant as value.
374 The interface offers also a signal, which returns 2 parameters: an
375 integer, and an array consisting of elements which are a struct of a
376 string and 2 boolean values.@footnote{ The interfaces of the service
377 @samp{org.freedesktop.Hal} are described at
378 @uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.}
381 @defun dbus-introspect-xml bus service path
382 This function has the same intention as function
383 @code{dbus-introspect}. The returned value is a parsed XML tree,
384 which can be used for further analysis. Example:
388 :session "org.freedesktop.xesam.searcher"
389 "/org/freedesktop/xesam/searcher/main")
391 @result{} (node ((name . "/org/freedesktop/xesam/searcher/main"))
392 (interface ((name . "org.freedesktop.xesam.Search"))
393 (method ((name . "GetHitData"))
394 (arg ((name . "search") (type . "s") (direction . "in")))
395 (arg ((name . "hit_ids") (type . "au") (direction . "in")))
396 (arg ((name . "fields") (type . "as") (direction . "in")))
397 (arg ((name . "hit_data") (type . "aav") (direction . "out")))
400 (signal ((name . "HitsAdded"))
401 (arg ((name . "search") (type . "s")))
402 (arg ((name . "count") (type . "u")))
410 @defun dbus-introspect-get-attribute object attribute
411 It returns the @var{attribute} value of a D-Bus introspection
412 @var{object}. @var{object} can be every subtree of a parsed XML tree
413 as retrieved with @code{dbus-introspect-xml}. @var{attribute} must be
414 a string according to the attribute names in the D-Bus specification.
418 (dbus-introspect-get-attribute
419 (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends"
420 "/org/freedesktop/SystemToolsBackends/UsersConfig")
423 @result{} "/org/freedesktop/SystemToolsBackends/UsersConfig"
426 If @var{object} has no @var{attribute}, the function returns
431 @node Nodes and Interfaces
432 @section Detecting object paths and interfaces.
434 The first elements, to be introspected for a D-Bus object, are further
435 object paths and interfaces.
437 @defun dbus-introspect-get-node-names bus service path
438 All node names of @var{service} in D-Bus @var{bus} at object path
439 @var{path} are returned as list of strings. Example:
442 (dbus-introspect-get-node-names
443 :session "org.gnome.seahorse" "/org/gnome/seahorse")
445 @result{} ("crypto" "keys")
448 The node names stand for further object paths of the D-Bus
449 @var{service}, relative to @var{path}. In the example,
450 @samp{/org/gnome/seahorse/crypto} and @samp{/org/gnome/seahorse/keys}
451 are also object paths of the D-Bus service @samp{org.gnome.seahorse}.
454 @defun dbus-introspect-get-all-nodes bus service path
455 This function returns all node names of @var{service} in D-Bus
456 @var{bus} at object path @var{path}. It returns a list of strings
457 with all object paths of @var{service}, starting at @var{path}.
461 (dbus-introspect-get-all-nodes :session "org.gnome.seahorse" "/")
463 @result{} ("/" "/org" "/org/gnome" "/org/gnome/seahorse"
464 "/org/gnome/seahorse/crypto"
465 "/org/gnome/seahorse/keys"
466 "/org/gnome/seahorse/keys/openpgp"
467 "/org/gnome/seahorse/keys/openpgp/local"
468 "/org/gnome/seahorse/keys/openssh"
469 "/org/gnome/seahorse/keys/openssh/local")
473 @defun dbus-introspect-get-interface-names bus service path
474 There will be returned a list strings of all interface names of
475 @var{service} in D-Bus @var{bus} at object path @var{path}. This list
476 will contain the default interface @samp{org.freedesktop.DBus.Introspectable}.
478 Another default interface is @samp{org.freedesktop.DBus.Properties}.
479 If present, @code{interface} elements can also have @code{property}
483 (dbus-introspect-get-interface-names
484 :system "org.freedesktop.Hal"
485 "/org/freedesktop/Hal/devices/computer")
487 @result{} ("org.freedesktop.DBus.Introspectable"
488 "org.freedesktop.Hal.Device"
489 "org.freedesktop.Hal.Device.SystemPowerManagement"
490 "org.freedesktop.Hal.Device.CPUFreq")
494 @defun dbus-introspect-get-interface bus service path interface
495 Return @var{interface} of @var{service} in D-Bus @var{bus} at object
496 path @var{path}. The return value is an XML element. @var{interface}
497 must be a string, element of the list returned by
498 @code{dbus-introspect-get-interface-names}. Example:
501 (dbus-introspect-get-interface
502 :session "org.freedesktop.xesam.searcher"
503 "/org/freedesktop/xesam/searcher/main"
504 "org.freedesktop.xesam.Search")
506 @result{} (interface ((name . "org.freedesktop.xesam.Search"))
507 (method ((name . "GetHitData"))
508 (arg ((name . "search") (type . "s") (direction . "in")))
509 (arg ((name . "hit_ids") (type . "au") (direction . "in")))
510 (arg ((name . "fields") (type . "as") (direction . "in")))
511 (arg ((name . "hit_data") (type . "aav") (direction . "out")))
514 (signal ((name . "HitsAdded"))
515 (arg ((name . "search") (type . "s")))
516 (arg ((name . "count") (type . "u")))
523 With these functions, it is possible to retrieve all introspection
524 data from a running system:
527 (with-current-buffer (switch-to-buffer "*introspect*")
529 (dolist (service (dbus-list-known-names :session))
530 (dolist (path (dbus-introspect-get-all-nodes :session service "/"))
531 ;; We want to introspect only elements, which have more than
532 ;; the default interface "org.freedesktop.DBus.Introspectable".
534 "org.freedesktop.DBus.Introspectable"
535 (dbus-introspect-get-interface-names :session service path))
536 (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path)
537 (dbus-introspect :session service path))
542 @node Methods and Signal
543 @section Applying the functionality.
545 Methods and signals are the communicatione means to D-Bus. The
546 following functions return their specifications.
548 @defun dbus-introspect-get-method-names bus service path interface
549 Return a list of strings of all method names of @var{interface} of
550 @var{service} in D-Bus @var{bus} at object path @var{path}. Example:
553 (dbus-introspect-get-method-names
554 :session "org.freedesktop.xesam.searcher"
555 "/org/freedesktop/xesam/searcher/main"
556 "org.freedesktop.xesam.Search")
558 @result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession"
559 "CloseSession" "GetHitData" "SetProperty" "NewSearch"
560 "GetProperty" "CloseSearch")
564 @defun dbus-introspect-get-method bus service path interface method
565 This function returns @var{method} of @var{interface} as XML element.
566 It must be located at @var{service} in D-Bus @var{bus} at object path
567 @var{path}. @var{method} must be a string, element of the list
568 returned by @code{dbus-introspect-get-method-names}. Example:
571 (dbus-introspect-get-method
572 :session "org.freedesktop.xesam.searcher"
573 "/org/freedesktop/xesam/searcher/main"
574 "org.freedesktop.xesam.Search" "GetHitData")
576 @result{} (method ((name . "GetHitData"))
577 (arg ((name . "search") (type . "s") (direction . "in")))
578 (arg ((name . "hit_ids") (type . "au") (direction . "in")))
579 (arg ((name . "fields") (type . "as") (direction . "in")))
580 (arg ((name . "hit_data") (type . "aav") (direction . "out")))
585 @defun dbus-introspect-get-signal-names bus service path interface
586 Return a list of strings of all signal names of @var{interface} of
587 @var{service} in D-Bus @var{bus} at object path @var{path}. Example:
590 (dbus-introspect-get-signal-names
591 :session "org.freedesktop.xesam.searcher"
592 "/org/freedesktop/xesam/searcher/main"
593 "org.freedesktop.xesam.Search")
595 @result{} ("StateChanged" "SearchDone" "HitsModified"
596 "HitsRemoved" "HitsAdded")
600 @defun dbus-introspect-get-signal bus service path interface signal
601 This function returns @var{signal} of @var{interface} as XML element.
602 It must be located at @var{service} in D-Bus @var{bus} at object path
603 @var{path}. @var{signal} must be a string, element of the list
604 returned by @code{dbus-introspect-get-signal-names}. Example:
607 (dbus-introspect-get-signal
608 :session "org.freedesktop.xesam.searcher"
609 "/org/freedesktop/xesam/searcher/main"
610 "org.freedesktop.xesam.Search" "HitsAdded")
612 @result{} (signal ((name . "HitsAdded"))
613 (arg ((name . "search") (type . "s")))
614 (arg ((name . "count") (type . "u")))
620 @node Properties and Annotations
621 @section What else to know about interfaces.
623 Interfaces can have properties. These can be exposed via the
624 @samp{org.freedesktop.DBus.Properties} interface@footnote{See
625 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}.
626 That is, properties can be retrieved and changed during lifetime of an
629 Annotations, on the other hand, are static values for an element.
630 Often, they are used to instruct generators, how to generate code from
631 the interface for a given language binding.
633 @defun dbus-introspect-get-property-names bus service path interface
634 Return a list of strings with all property names of @var{interface} of
635 @var{service} in D-Bus @var{bus} at object path @var{path}. Example:
638 (dbus-introspect-get-property-names
639 :session "org.kde.kded" "/modules/networkstatus"
640 "org.kde.Solid.Networking.Client")
645 If an interface declares properties, the corresponding element supports
646 also the @samp{org.freedesktop.DBus.Properties} interface.
649 @defun dbus-introspect-get-property bus service path interface property
650 This function returns @var{property} of @var{interface} as XML element.
651 It must be located at @var{service} in D-Bus @var{bus} at object path
652 @var{path}. @var{property} must be a string, element of the list
653 returned by @code{dbus-introspect-get-property-names}.
655 A @var{property} value can be retrieved by the function
656 @code{dbus-introspect-get-attribute}. Example:
659 (dbus-introspect-get-property
660 :session "org.kde.kded" "/modules/networkstatus"
661 "org.kde.Solid.Networking.Client" "Status")
663 @result{} (property ((access . "read") (type . "u") (name . "Status")))
665 (dbus-introspect-get-attribute
666 (dbus-introspect-get-property
667 :session "org.kde.kded" "/modules/networkstatus"
668 "org.kde.Solid.Networking.Client" "Status")
675 @defun dbus-get-property bus service path interface property
676 This function returns the value of @var{property} of @var{interface}.
677 It will be checked at @var{bus}, @var{service}, @var{path}. The
678 result can be any valid D-Bus value, or @code{nil} if there is no
679 @var{property}. Example:
683 :session "org.kde.kded" "/modules/networkstatus"
684 "org.kde.Solid.Networking.Client" "Status")
690 @defun dbus-set-property bus service path interface property value
691 Set value of @var{property} of @var{interface} to @var{value}. It
692 will be checked at @var{bus}, @var{service}, @var{path}. When the
693 value has been set successful, the result is @var{value}. Otherwise,
694 @code{nil} is returned. Example:
698 :session "org.kde.kaccess" "/MainApplication"
699 "com.trolltech.Qt.QApplication" "doubleClickInterval" 500)
705 @defun dbus-get-all-properties bus service path interface
706 This function returns all properties of @var{interface}. It will be
707 checked at @var{bus}, @var{service}, @var{path}. The result is a list
708 of cons. Every cons contains the name of the property, and its value.
709 If there are no properties, @code{nil} is returned. Example:
712 (dbus-get-all-properties
713 :session "org.kde.kaccess" "/MainApplication"
714 "com.trolltech.Qt.QApplication")
716 @result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500)
717 ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3)
718 ("globalStrut" 0 0) ("startDragTime" . 500)
719 ("startDragDistance" . 4) ("quitOnLastWindowClosed" . t)
724 @defun dbus-introspect-get-annotation-names bus service path interface &optional name
725 Return a list of all annotation names as list of strings. If
726 @var{name} is @code{nil}, the annotations are children of
727 @var{interface}, otherwise @var{name} must be a @code{method},
728 @code{signal}, or @code{property} XML element, where the annotations
732 (dbus-introspect-get-annotation-names
733 :session "de.berlios.Pinot" "/de/berlios/Pinot"
734 "de.berlios.Pinot" "GetStatistics")
736 @result{} ("de.berlios.Pinot.GetStatistics")
739 Default annotation names@footnote{See
740 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format}}
744 @item org.freedesktop.DBus.Deprecated
745 Whether or not the entity is deprecated; defaults to @code{nil}
747 @item org.freedesktop.DBus.GLib.CSymbol
748 The C symbol; may be used for @code{methods} and @code{interfaces}
750 @item org.freedesktop.DBus.Method.NoReply
751 If set, don't expect a reply to the @code{method} call; defaults to @code{nil}
755 @defun dbus-introspect-get-annotation bus service path interface name annotation
756 Return annotation @var{ANNOTATION} as XML object. If @var{name} is
757 @code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise
758 @var{name} must be the name of a @code{method}, @code{signal}, or
759 @code{property} XML element, where the @var{ANNOTATION} belongs to.
761 An attribute value can be retrieved by
762 @code{dbus-introspect-get-attribute}. Example:
765 (dbus-introspect-get-annotation
766 :session "de.berlios.Pinot" "/de/berlios/Pinot"
767 "de.berlios.Pinot" "GetStatistics"
768 "de.berlios.Pinot.GetStatistics")
770 @result{} (annotation ((name . "de.berlios.Pinot.GetStatistics")
771 (value . "pinotDBus")))
773 (dbus-introspect-get-attribute
774 (dbus-introspect-get-annotation
775 :session "de.berlios.Pinot" "/de/berlios/Pinot"
776 "de.berlios.Pinot" "GetStatistics"
777 "de.berlios.Pinot.GetStatistics")
780 @result{} "pinotDBus"
785 @node Arguments and Signatures
786 @section The final details.
788 Methods and signals have arguments. They are described in the
789 @code{arg} XML elements.
791 @defun dbus-introspect-get-argument-names bus service path interface name
792 Return a list of all argument names as list of strings. @var{name}
793 must be a @code{method} or @code{signal} XML element. Example:
796 (dbus-introspect-get-argument-names
797 :session "org.freedesktop.xesam.searcher"
798 "/org/freedesktop/xesam/searcher/main"
799 "org.freedesktop.xesam.Search" "GetHitData")
801 @result{} ("search" "hit_ids" "fields" "hit_data")
804 Argument names are optional; the function can return @code{nil}
805 therefore, even if the method or signal has arguments.
808 @defun dbus-introspect-get-argument bus service path interface name arg
809 Return argument @var{ARG} as XML object. @var{name}
810 must be a @code{method} or @code{signal} XML element. Example:
813 (dbus-introspect-get-argument
814 :session "org.freedesktop.xesam.searcher"
815 "/org/freedesktop/xesam/searcher/main"
816 "org.freedesktop.xesam.Search" "GetHitData" "search")
818 @result{} (arg ((name . "search") (type . "s") (direction . "in")))
822 @defun dbus-introspect-get-signature bus service path interface name &optional direction
823 Return signature of a @code{method} or @code{signal}, represented by
824 @var{name}, as string.
826 If @var{name} is a @code{method}, @var{direction} can be either
827 @samp{in} or @samp{out}. If @var{direction} is @code{nil}, @samp{in}
830 If @var{name} is a @code{signal}, and @var{direction} is
831 non-@code{nil}, @var{direction} must be @samp{out}. Example:
834 (dbus-introspect-get-signature
835 :session "org.freedesktop.xesam.searcher"
836 "/org/freedesktop/xesam/searcher/main"
837 "org.freedesktop.xesam.Search" "GetHitData" "in")
841 (dbus-introspect-get-signature
842 :session "org.freedesktop.xesam.searcher"
843 "/org/freedesktop/xesam/searcher/main"
844 "org.freedesktop.xesam.Search" "HitsAdded")
851 @node Type Conversion
852 @chapter Mapping Lisp types and D-Bus types.
853 @cindex type conversion
855 D-Bus method calls and signals accept usually several arguments as
856 parameters, either as input parameter, or as output parameter. Every
857 argument belongs to a D-Bus type.
859 Such arguments must be mapped between the value encoded as a D-Bus
860 type, and the corresponding type of Lisp objects. The mapping is
861 applied Lisp object @expansion{} D-Bus type for input parameters, and
862 D-Bus type @expansion{} Lisp object for output parameters.
865 @section Input parameters.
867 Input parameters for D-Bus methods and signals occur as arguments of a
868 Lisp function call. The following mapping to D-Bus types is
869 applied, when the corresponding D-Bus message is created:
872 @multitable {negative integer} {@expansion{}} {DBUS_TYPE_BOOLEAN}
873 @item Lisp type @tab @tab D-Bus type
875 @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN
876 @item natural number @tab @expansion{} @tab DBUS_TYPE_UINT32
877 @item negative integer @tab @expansion{} @tab DBUS_TYPE_INT32
878 @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE
879 @item string @tab @expansion{} @tab DBUS_TYPE_STRING
880 @item list @tab @expansion{} @tab DBUS_TYPE_ARRAY
884 Other Lisp objects, like symbols or hash tables, are not accepted as
887 If it is necessary to use another D-Bus type, a corresponding type
888 symbol can be preceeded to the corresponding Lisp object. Basic D-Bus
889 types are represented by the type symbols @code{:byte},
890 @code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32},
891 @code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double},
892 @code{:string}, @code{:object-path} and @code{:signature}.
898 (dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING})
904 (dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING})
910 (dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING})
913 The value for a byte D-Bus type can be any integer in the range 0
914 through 255. If a character is used as argument, modifiers
915 represented outside this range are stripped of. For example,
916 @code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to
917 @code{:byte ?\C-x} or @code{:byte ?\M-\C-x}.
919 A D-Bus compound type is always represented as a list. The @sc{car}
920 of this list can be the type symbol @code{:array}, @code{:variant},
921 @code{:struct} or @code{:dict-entry}, which would result in a
922 corresponding D-Bus container. @code{:array} is optional, because
923 this is the default compound D-Bus type for a list.
925 The objects being elements of the list are checked according to the
926 D-Bus compound type rules.
929 @item An array must contain only elements of the same D-Bus type. It
932 @item A variant must contain only one single element.
934 @item A dictionary entry must be element of an array, and it must
935 contain only a key-value pair of two elements, with a basic D-Bus type
938 @item There is no restriction for structs.
941 If an empty array needs an element D-Bus type other than string, it
942 can contain exactly one element of D-Bus type @code{:signature}. The
943 value of this element (a string) is used as the signature of the
944 elements of this array. Example:
948 :session "org.freedesktop.Notifications"
949 "/org/freedesktop/Notifications"
950 "org.freedesktop.Notifications" "Notify"
951 "GNU Emacs" ;; Application name.
952 0 ;; No replacement of other notifications.
954 "Notification summary" ;; Summary.
956 "This is a test notification, raised from %s" (emacs-version))
957 '(:array) ;; No actions (empty array of strings).
958 '(:array :signature "@{sv@}") ;; No hints
959 ;; (empty array of dictionary entries).
960 :int32 -1) ;; Default timeout.
965 @defun dbus-string-to-byte-array string
966 Sometimes, D-Bus methods require as input parameter an array of bytes,
967 instead of a string. If it is guaranteed, that @var{string} is an
968 UTF8 string, this function performs the conversion. Example:
971 (dbus-string-to-byte-array "/etc/hosts")
973 @result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47
974 :byte 104 :byte 111 :byte 115 :byte 116 :byte 115)
978 @defun dbus-escape-as-identifier string
979 Escape an arbitrary @var{string} so it follows the rules for a C
980 identifier. The escaped string can be used as object path component,
981 interface element component, bus name component or member name in
984 The escaping consists of replacing all non-alphanumerics, and the
985 first character if it's a digit, with an underscore and two
986 lower-case hex digits. As a special case, "" is escaped to
990 (dbus-escape-as-identifier "0123abc_xyz\x01\xff")
992 @result{} "_30123abc_5fxyz_01_ff"
997 @section Output parameters.
999 Output parameters of D-Bus methods and signals are mapped to Lisp
1003 @multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float}
1004 @item D-Bus type @tab @tab Lisp type
1006 @item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil}
1007 @item DBUS_TYPE_BYTE @tab @expansion{} @tab natural number
1008 @item DBUS_TYPE_UINT16 @tab @expansion{} @tab natural number
1009 @item DBUS_TYPE_INT16 @tab @expansion{} @tab integer
1010 @item DBUS_TYPE_UINT32 @tab @expansion{} @tab natural number or float
1011 @item DBUS_TYPE_INT32 @tab @expansion{} @tab integer or float
1012 @item DBUS_TYPE_UINT64 @tab @expansion{} @tab natural number or float
1013 @item DBUS_TYPE_INT64 @tab @expansion{} @tab integer or float
1014 @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float
1015 @item DBUS_TYPE_STRING @tab @expansion{} @tab string
1016 @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
1017 @item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string
1018 @item DBUS_TYPE_ARRAY @tab @expansion{} @tab list
1019 @item DBUS_TYPE_VARIANT @tab @expansion{} @tab list
1020 @item DBUS_TYPE_STRUCT @tab @expansion{} @tab list
1021 @item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list
1025 A float object in case of @code{DBUS_TYPE_UINT32},
1026 @code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and
1027 @code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the
1028 Emacs number size range.
1030 The resulting list of the last 4 D-Bus compound types contains as
1031 elements the elements of the D-Bus container, mapped according to the
1034 The signal @code{PropertyModified}, discussed as example in
1035 @ref{Inspection}, would offer as Lisp data the following object
1036 (@var{BOOL} stands here for either @code{nil} or @code{t}):
1039 (@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
1042 @defun dbus-byte-array-to-string byte-array
1043 If a D-Bus method or signal returns an array of bytes, which are known
1044 to represent an UTF8 string, this function converts @var{byte-array}
1045 to the corresponding string. Example:
1048 (dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115))
1050 @result{} "/etc/hosts"
1054 @defun dbus-unescape-from-identifier string
1055 Retrieve the original string from the encoded @var{string}.
1056 @var{string} must have been coded with
1057 @code{dbus-escape-as-identifier}. Example:
1060 (dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")
1063 @result{} "0123abc_xyz^Aÿ"
1066 @result{} "0123abc_xyz^A@"y"
1072 @node Synchronous Methods
1073 @chapter Calling methods in a blocking way.
1074 @cindex method calls, synchronous
1075 @cindex synchronous method calls
1077 Methods can be called synchronously (@dfn{blocking}) or asynchronously
1078 (@dfn{non-blocking}).
1080 At D-Bus level, a method call consist of two messages: one message
1081 which carries the input parameters to the object owning the method to
1082 be called, and a reply message returning the resulting output
1083 parameters from the object.
1085 @defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args
1086 This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is
1087 either the symbol @code{:system} or the symbol @code{:session}.
1089 @var{service} is the D-Bus service name to be used. @var{path} is the
1090 D-Bus object path, @var{service} is registered at. @var{interface} is
1091 an interface offered by @var{service}. It must provide @var{method}.
1093 If the parameter @code{:timeout} is given, the following integer
1094 @var{timeout} specifies the maximum number of milliseconds the method
1095 call must return. The default value is 25,000. If the method call
1096 doesn't return in time, a D-Bus error is raised (@pxref{Errors and
1099 All other arguments args are passed to @var{method} as arguments.
1100 They are converted into D-Bus types as described in @ref{Type
1103 The function returns the resulting values of @var{method} as a list of
1104 Lisp objects, according to the type conversion rules described in
1105 @ref{Type Conversion}. Example:
1109 :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
1110 "org.gnome.seahorse.Keys" "GetKeyField"
1111 "openpgp:657984B8C7A966DD" "simple-name")
1113 @result{} (t ("Philip R. Zimmermann"))
1116 If the result of the method call is just one value, the converted Lisp
1117 object is returned instead of a list containing this single Lisp
1122 :system "org.freedesktop.Hal"
1123 "/org/freedesktop/Hal/devices/computer"
1124 "org.freedesktop.Hal.Device" "GetPropertyString"
1125 "system.kernel.machine")
1130 With the @code{dbus-introspect} function it is possible to explore the
1131 interfaces of @samp{org.freedesktop.Hal} service. It offers the
1132 interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
1133 path @samp{/org/freedesktop/Hal/Manager} as well as the interface
1134 @samp{org.freedesktop.Hal.Device} for all objects prefixed with the
1135 path @samp{/org/freedesktop/Hal/devices}. With the methods
1136 @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
1137 emulate the @code{lshal} command on GNU/Linux systems:
1142 :system "org.freedesktop.Hal"
1143 "/org/freedesktop/Hal/Manager"
1144 "org.freedesktop.Hal.Manager" "GetAllDevices"))
1145 (message "\nudi = %s" device)
1148 :system "org.freedesktop.Hal" device
1149 "org.freedesktop.Hal.Device" "GetAllProperties"))
1151 (car properties) (or (caar (cdr properties)) ""))))
1153 @print{} "udi = /org/freedesktop/Hal/devices/computer
1154 info.addons = (\"hald-addon-acpi\")
1155 info.bus = \"unknown\"
1156 info.product = \"Computer\"
1157 info.subsystem = \"unknown\"
1158 info.udi = \"/org/freedesktop/Hal/devices/computer\"
1159 linux.sysfs_path_device = \"(none)\"
1160 power_management.acpi.linux.version = \"20051216\"
1161 power_management.can_suspend_to_disk = t
1162 power_management.can_suspend_to_ram = \"\"
1163 power_management.type = \"acpi\"
1164 smbios.bios.release_date = \"11/07/2001\"
1165 system.chassis.manufacturer = \"COMPAL\"
1166 system.chassis.type = \"Notebook\"
1167 system.firmware.release_date = \"03/19/2005\"
1172 @defun dbus-call-method-non-blocking bus service path interface method &optional :timeout timeout &rest args
1173 Call @var{method} on the D-Bus @var{bus}, but don't block the event queue.
1174 This is necessary for communicating to registered D-Bus methods,
1175 which are running in the same Emacs process.
1177 The arguments are the same as in @code{dbus-call-method}. Example:
1180 (dbus-call-method-non-blocking
1181 :system "org.freedesktop.Hal"
1182 "/org/freedesktop/Hal/devices/computer"
1183 "org.freedesktop.Hal.Device" "GetPropertyString"
1184 "system.kernel.machine")
1191 @node Asynchronous Methods
1192 @chapter Calling methods non-blocking.
1193 @cindex method calls, asynchronous
1194 @cindex asynchronous method calls
1196 @defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args
1197 This function calls @var{method} on the D-Bus @var{bus}
1198 asynchronously. @var{bus} is either the symbol @code{:system} or the
1199 symbol @code{:session}.
1201 @var{service} is the D-Bus service name to be used. @var{path} is the
1202 D-Bus object path, @var{service} is registered at. @var{interface} is
1203 an interface offered by @var{service}. It must provide @var{method}.
1205 @var{handler} is a Lisp function, which is called when the
1206 corresponding return message has arrived. If @var{handler} is
1207 @code{nil}, no return message will be expected.
1209 If the parameter @code{:timeout} is given, the following integer
1210 @var{timeout} specifies the maximum number of milliseconds a reply
1211 message must arrive. The default value is 25,000. If there is no
1212 reply message in time, a D-Bus error is raised (@pxref{Errors and
1215 All other arguments args are passed to @var{method} as arguments.
1216 They are converted into D-Bus types as described in @ref{Type
1219 Unless @var{handler} is @code{nil}, the function returns a key into
1220 the hash table @code{dbus-registered-objects-table}. The
1221 corresponding entry in the hash table is removed, when the return
1222 message has been arrived, and @var{handler} is called. Example:
1225 (dbus-call-method-asynchronously
1226 :system "org.freedesktop.Hal"
1227 "/org/freedesktop/Hal/devices/computer"
1228 "org.freedesktop.Hal.Device" "GetPropertyString" 'message
1229 "system.kernel.machine")
1231 @result{} (:system 2)
1238 @node Receiving Method Calls
1239 @chapter Offering own methods.
1240 @cindex method calls, returning
1241 @cindex returning method calls
1243 Emacs can also offer own methods, which can be called by other
1244 applications. These methods could be an implementation of an
1245 interface of a well known service, like @samp{org.freedesktop.TextEditor}.
1247 It could be also an implementation of an own interface. In this case,
1248 the service name must be @samp{org.gnu.Emacs}. The object path shall
1249 begin with @samp{/org/gnu/Emacs/@strong{Application}/}, and the
1250 interface name shall be @code{org.gnu.Emacs.@strong{Application}}.
1251 @samp{@strong{Application}} is the name of the application which
1252 provides the interface.
1254 @deffn Constant dbus-service-emacs
1255 The well known service name of Emacs.
1258 @deffn Constant dbus-path-emacs
1259 The object path head "/org/gnu/Emacs" used by Emacs. All object
1260 paths, used by offered methods or signals, shall start with this
1264 @defun dbus-register-method bus service path interface method handler
1265 With this function, an application registers @var{method} on the D-Bus
1268 @var{bus} is either the symbol @code{:system} or the symbol
1271 @var{service} is the D-Bus service name of the D-Bus object
1272 @var{method} is registered for. It must be a known name.
1274 @var{path} is the D-Bus object path @var{service} is
1277 @var{interface} is the interface offered by @var{service}. It must
1278 provide @var{method}.
1280 @var{handler} is a Lisp function to be called when a @var{method} call
1281 is received. It must accept as arguments the input arguments of
1282 @var{method}. @var{handler} should return a list, whose elements are
1283 to be used as arguments for the reply message of @var{method}. This
1284 list can be composed like the input parameters in @ref{Type
1287 If @var{handler} wants to return just one Lisp object and it is not a
1288 cons cell, @var{handler} can return this object directly, instead of
1289 returning a list containing the object.
1291 In case @var{handler} shall return a reply message with an empty
1292 argument list, @var{handler} must return the symbol @code{:ignore}.
1294 The default D-Bus timeout when waiting for a message reply is 25
1295 seconds. This value could be even smaller, depending on the calling
1296 client. Therefore, @var{handler} shall not last longer than
1297 absolutely necessary.
1299 @code{dbus-register-method} returns a Lisp object, which can be used
1300 as argument in @code{dbus-unregister-object} for removing the
1301 registration for @var{method}. Example:
1304 (defun my-dbus-method-handler (filename)
1306 (if (find-file filename)
1307 (setq result '(:boolean t))
1308 (setq result '(:boolean nil)))
1311 @result{} my-dbus-method-handler
1313 (dbus-register-method
1314 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1315 "org.freedesktop.TextEditor" "OpenFile"
1316 'my-dbus-method-handler)
1318 @result{} ((:session "org.freedesktop.TextEditor" "OpenFile")
1319 ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1320 my-dbus-method-handler))
1323 If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile}
1324 from another D-Bus application with a filename as parameter, the file
1325 is opened in Emacs, and the method returns either @var{true} or
1326 @var{false}, indicating the success of the method. As test tool one
1327 could use the command line tool @code{dbus-send} in a shell:
1330 # dbus-send --session --print-reply \
1331 --dest="org.freedesktop.TextEditor" \
1332 "/org/freedesktop/TextEditor" \
1333 "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts"
1335 @print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2
1339 You can indicate an error by raising the Emacs signal
1340 @code{dbus-error}. The handler above could be changed like this:
1343 (defun my-dbus-method-handler (&rest args)
1344 (unless (and (= (length args) 1) (stringp (car args)))
1345 (signal 'dbus-error (list (format "Wrong argument list: %S" args))))
1347 (find-file (car args))
1348 (error (signal 'dbus-error (cdr err))))
1351 @result{} my-dbus-method-handler
1357 # dbus-send --session --print-reply \
1358 --dest="org.freedesktop.TextEditor" \
1359 "/org/freedesktop/TextEditor" \
1360 "org.freedesktop.TextEditor.OpenFile" \
1361 string:"/etc/hosts" string:"/etc/passwd"
1363 @print{} Error org.freedesktop.DBus.Error.Failed:
1364 Wrong argument list: ("/etc/hosts" "/etc/passwd")
1368 @defun dbus-register-property bus service path interface property access value &optional emits-signal
1369 With this function, an application declares a @var{property} on the D-Bus
1372 @var{bus} is either the symbol @code{:system} or the symbol
1375 @var{service} is the D-Bus service name of the D-Bus. It must be a
1378 @var{path} is the D-Bus object path @var{service} is
1381 @var{interface} is the name of the interface used at @var{path},
1382 @var{property} is the name of the property of @var{interface}.
1384 @var{access} indicates, whether the property can be changed by other
1385 services via D-Bus. It must be either the symbol @code{:read} or
1386 @code{:readwrite}. @var{value} is the initial value of the property,
1387 it can be of any valid type (see @code{dbus-call-method} for details).
1389 If @var{property} already exists on @var{path}, it will be
1390 overwritten. For properties with access type @code{:read} this is the
1391 only way to change their values. Properties with access type
1392 @code{:readwrite} can be changed by @code{dbus-set-property}.
1394 The interface @samp{org.freedesktop.DBus.Properties} is added to
1395 @var{path}, including a default handler for the @samp{Get},
1396 @samp{GetAll} and @samp{Set} methods of this interface. When
1397 @var{emits-signal} is non-@code{nil}, the signal
1398 @samp{PropertiesChanged} is sent when the property is changed by
1399 @code{dbus-set-property}.
1404 (dbus-register-property
1405 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1406 "org.freedesktop.TextEditor" "name" :read "GNU Emacs")
1408 @result{} ((:session "org.freedesktop.TextEditor" "name")
1409 ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
1411 (dbus-register-property
1412 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1413 "org.freedesktop.TextEditor" "version" :readwrite emacs-version t)
1415 @result{} ((:session "org.freedesktop.TextEditor" "version")
1416 ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
1419 Other D-Bus applications can read the property via the default methods
1420 @samp{org.freedesktop.DBus.Properties.Get} and
1421 @samp{org.freedesktop.DBus.Properties.GetAll}. Testing is also
1422 possible via the command line tool @code{dbus-send} in a shell:
1425 # dbus-send --session --print-reply \
1426 --dest="org.freedesktop.TextEditor" \
1427 "/org/freedesktop/TextEditor" \
1428 "org.freedesktop.DBus.Properties.GetAll" \
1429 string:"org.freedesktop.TextEditor"
1431 @print{} method return sender=:1.22 -> dest=:1.23 reply_serial=3
1435 variant string "GNU Emacs"
1439 variant string "23.1.50.5"
1444 It is also possible, to apply the @code{dbus-get-property},
1445 @code{dbus-get-all-properties} and @code{dbus-set-property} functions
1446 (@pxref{Properties and Annotations}).
1450 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1451 "org.freedesktop.TextEditor" "version" "23.1.50")
1456 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1457 "org.freedesktop.TextEditor" "version")
1463 @defun dbus-unregister-object object
1464 Unregister @var{object} from the D-Bus. @var{object} must be the
1465 result of a preceding @code{dbus-register-method},
1466 @code{dbus-register-property} or @code{dbus-register-signal} call
1467 (@pxref{Signals}). It returns @code{t} if @var{object} has been
1468 unregistered, @code{nil} otherwise.
1470 When @var{object} identifies the last method or property, which is
1471 registered for the respective service, Emacs releases its association
1472 to the service from D-Bus.
1475 @defun dbus-unregister-service bus service
1476 Unregister all objects from D-Bus @var{bus}, registered by Emacs for
1479 @var{bus} is either the symbol @code{:system} or the symbol
1482 @var{service} is the D-Bus service name of the D-Bus. It must be a
1483 known name. Emacs releases its association to @var{service} from
1489 @chapter Sending and receiving signals.
1492 Signals are broadcast messages. They carry input parameters, which
1493 are received by all objects which have registered for such a signal.
1495 @defun dbus-send-signal bus service path interface signal &rest args
1496 This function is similar to @code{dbus-call-method}. The difference
1497 is, that there are no returning output parameters.
1499 The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is
1500 either the symbol @code{:system} or the symbol @code{:session}. It
1501 doesn't matter whether another object has registered for @var{signal}.
1503 @var{service} is the D-Bus service name of the object the signal is
1504 emitted from. @var{path} is the corresponding D-Bus object path,
1505 @var{service} is registered at. @var{interface} is an interface
1506 offered by @var{service}. It must provide @var{signal}.
1508 All other arguments args are passed to @var{signal} as arguments.
1509 They are converted into D-Bus types as described in @ref{Type
1510 Conversion}. Example:
1514 :session dbus-service-emacs dbus-path-emacs
1515 (concat dbus-service-emacs ".FileManager") "FileModified"
1516 "/home/albinus/.emacs")
1520 @defun dbus-register-signal bus service path interface signal handler &rest args
1521 With this function, an application registers for @var{signal} on the
1524 @var{bus} is either the symbol @code{:system} or the symbol
1527 @var{service} is the D-Bus service name used by the sending D-Bus
1528 object. It can be either a known name or the unique name of the D-Bus
1529 object sending the signal. In case of a unique name, signals won't be
1530 received any longer once the object owning this unique name has
1531 disappeared, and a new queued object has replaced it.
1533 When @var{service} is @code{nil}, related signals from all D-Bus
1534 objects shall be accepted.
1536 @var{path} is the corresponding D-Bus object path, @var{service} is
1537 registered at. It can also be @code{nil} if the path name of incoming
1538 signals shall not be checked.
1540 @var{interface} is an interface offered by @var{service}. It must
1541 provide @var{signal}.
1543 @var{handler} is a Lisp function to be called when the @var{signal} is
1544 received. It must accept as arguments the output parameters
1545 @var{signal} is sending.
1547 All other arguments @var{args}, if specified, must be strings. They
1548 stand for the respective arguments of @var{signal} in their order, and
1549 are used for filtering as well. A @code{nil} argument might be used
1550 to preserve the order.
1552 @code{dbus-register-signal} returns a Lisp object, which can be used
1553 as argument in @code{dbus-unregister-object} for removing the
1554 registration for @var{signal}. Example:
1557 (defun my-dbus-signal-handler (device)
1558 (message "Device %s added" device))
1560 @result{} my-dbus-signal-handler
1562 (dbus-register-signal
1563 :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
1564 "org.freedesktop.Hal.Manager" "DeviceAdded"
1565 'my-dbus-signal-handler)
1567 @result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded")
1568 ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
1572 As we know from the introspection data of interface
1573 @samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded}
1574 provides one single parameter, which is mapped into a Lisp string.
1575 The callback function @code{my-dbus-signal-handler} must define one
1576 single string argument therefore. Plugging an USB device to your
1577 machine, when registered for signal @samp{DeviceAdded}, will show you
1578 which objects the GNU/Linux @code{hal} daemon adds.
1582 @node Errors and Events
1583 @chapter Errors and events.
1588 The internal actions can be traced by running in a debug mode.
1591 If this variable is non-@code{nil}, D-Bus specific debug messages are raised.
1594 Input parameters of @code{dbus-call-method},
1595 @code{dbus-call-method-non-blocking},
1596 @code{dbus-call-method-asynchronously}, and
1597 @code{dbus-register-signal} are checked for correct D-Bus types. If
1598 there is a type mismatch, the Lisp error @code{wrong-type-argument}
1599 @code{D-Bus ARG} is raised.
1601 All errors raised by D-Bus are signaled with the error symbol
1602 @code{dbus-error}. If possible, error messages from D-Bus are
1603 appended to the @code{dbus-error}.
1605 @defspec dbus-ignore-errors forms@dots{}
1606 This executes @var{forms} exactly like a @code{progn}, except that
1607 @code{dbus-error} errors are ignored during the @var{forms}. These
1608 errors can be made visible when @code{dbus-debug} is set to @code{t}.
1611 Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc
1612 Events, , , elisp}. They are retrieved only, when Emacs runs in
1613 interactive mode. The generated event has this form:
1616 (dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler}
1620 @var{bus} identifies the D-Bus the message is coming from. It is
1621 either the symbol @code{:system} or the symbol @code{:session}.
1623 @var{type} is the D-Bus message type which has caused the event. It
1624 can be @code{dbus-message-type-invalid},
1625 @code{dbus-message-type-method-call},
1626 @code{dbus-message-type-method-return},
1627 @code{dbus-message-type-error}, or @code{dbus-message-type-signal}.
1628 @var{serial} is the serial number of the received D-Bus message.
1630 @var{service} and @var{path} are the unique name and the object path
1631 of the D-Bus object emitting the message. @var{interface} and
1632 @var{member} denote the message which has been sent.
1634 @var{handler} is the callback function which has been registered for
1635 this message (see @pxref{Signals}). When a @code{dbus-event} event
1636 arrives, @var{handler} is called with @var{args} as arguments.
1638 In order to inspect the @code{dbus-event} data, you could extend the
1639 definition of the callback function in @ref{Signals}:
1642 (defun my-dbus-signal-handler (&rest args)
1643 (message "my-dbus-signal-handler: %S" last-input-event))
1646 There exist convenience functions which could be called inside a
1647 callback function in order to retrieve the information from the event.
1649 @defun dbus-event-bus-name event
1650 Returns the bus name @var{event} is coming from.
1651 The result is either the symbol @code{:system} or the symbol @code{:session}.
1654 @defun dbus-event-message-type event
1655 Returns the message type of the corresponding D-Bus message. The
1656 result is a natural number.
1659 @defun dbus-event-serial-number event
1660 Returns the serial number of the corresponding D-Bus message.
1661 The result is a natural number.
1664 @defun dbus-event-service-name event
1665 Returns the unique name of the D-Bus object @var{event} is coming from.
1668 @defun dbus-event-path-name event
1669 Returns the object path of the D-Bus object @var{event} is coming from.
1672 @defun dbus-event-interface-name event
1673 Returns the interface name of the D-Bus object @var{event} is coming from.
1676 @defun dbus-event-member-name event
1677 Returns the member name of the D-Bus object @var{event} is coming
1678 from. It is either a signal name or a method name.
1681 D-Bus errors are not propagated during event handling, because it is
1682 usually not desired. D-Bus errors in events can be made visible by
1683 setting the variable @code{dbus-debug} to @code{t}. They can also be
1684 handled by a hook function.
1686 @defvar dbus-event-error-hooks
1687 This hook variable keeps a list of functions, which are called when a
1688 D-Bus error happens in the event handler. Every function must accept
1689 two arguments, the event and the error variable catched in
1690 @code{condition-case} by @code{dbus-error}.
1692 Such functions can be used the adapt the error signal to be raised.
1696 (defun my-dbus-event-error-handler (event error)
1697 (when (string-equal (concat dbus-service-emacs ".FileManager")
1698 (dbus-event-interface-name event))
1699 (message "my-dbus-event-error-handler: %S %S" event error)
1700 (signal 'file-error (cdr error))))
1702 (add-hook 'dbus-event-error-hooks 'my-dbus-event-error-handler)
1706 Hook functions shall take into account, that there might be other
1707 D-Bus applications running. Therefore, they shall check carefully,
1708 whether a given D-Bus error is related to them.
1717 @node GNU Free Documentation License
1718 @appendix GNU Free Documentation License
1719 @include doclicense.texi
1724 arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8