1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/dbus
4 @settitle Using of D-Bus
5 @c @setchapternewpage odd
9 Copyright @copyright{} 2007 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.2 or
14 any later version published by the Free Software Foundation; with no
15 Invariant Sections, with the Front-Cover texts being ``A GNU
16 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
17 license is included in the section entitled ``GNU Free Documentation
18 License'' in the Emacs manual.
20 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
21 this GNU Manual, like GNU software. Copies published by the Free
22 Software Foundation raise funds for GNU development.''
24 This document is part of a collection distributed under the GNU Free
25 Documentation License. If you want to distribute this document
26 separately from the collection, you can do so by adding a copy of the
27 license to the document, as described in section 6 of the license.
33 * 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
40 Emacs.@footnote{D-Bus is not enabled by default. You must run
41 @command{./configure --with-dbus} in Emacs' top level directory,
42 before you compile Emacs.} D-Bus is a message bus system, a simple
43 way for applications to talk to one another. An overview of D-Bus can
44 be found at @uref{http://dbus.freedesktop.org/}.
49 * Overview:: An overview of D-Bus.
50 * Inspection:: Inspection of the bus names.
51 * Type Conversion:: Mapping Lisp types and D-Bus types.
52 * Synchronous Methods:: Calling methods in a blocking way.
53 * Signals:: Sending and receiving signals.
54 * Errors and Events:: Errors and events.
55 * 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 the bus names.
112 There are several basic functions which inspect the buses for
113 registered names. Internally they use the basic interface
114 @samp{org.freedesktop.DBus}, which is supported by all objects of a bus.
116 @defun dbus-list-activatable-names
117 This function returns the D-Bus service names, which can be activated.
118 An activatable service is described in a service registration file.
119 Under GNU/Linux, such files are located at
120 @file{/usr/share/dbus-1/services/}.
122 The result is a list of strings, which is @code{nil} when there are no
123 activatable service names at all.
126 @defun dbus-list-names bus
127 All service names, which are registered at D-Bus @var{bus}, are
128 returned. The result is a list of strings, which is @code{nil} when
129 there are no registered service names at all. Well known names are
130 strings like @samp{org.freedesktop.DBus}. Names starting with
131 @samp{:} are unique names for services.
133 @var{bus} must be either the symbol @code{:system} or the symbol
137 @defun dbus-list-known-names bus
138 Retrieves all services which correspond to a known name in @var{bus}.
139 A service has a known name if it doesn't start with @samp{:}. The
140 result is a list of strings, which is @code{nil} when there are no
143 @var{bus} must be either the symbol @code{:system} or the symbol
147 @defun dbus-list-queued-owners bus service
148 For a given service, registered at D-Bus @var{bus} under the name
149 @var{service}, all queued unique names are returned. The result is a
150 list of strings, or @code{nil} when there are no queued names for
151 @var{service} at all.
153 @var{bus} must be either the symbol @code{:system} or the symbol
154 @code{:session}. @var{service} must be a known service name as
158 @defun dbus-get-name-owner bus service
159 For a given service, registered at D-Bus @var{bus} under the name
160 @var{service}, the unique name of the name owner is returned. The result is a
161 string, or @code{nil} when there exist no name owner of @var{service}.
163 @var{bus} must be either the symbol @code{:system} or the symbol
164 @code{:session}. @var{service} must be a known service name as
168 @defun dbus-get-unique-name bus
169 The unique name, under which Emacs is registered at D-Bus @var{bus},
170 is returned as string.
172 @var{bus} must be either the symbol @code{:system} or the symbol
176 @defun dbus-introspect bus service path
177 Objects can publish there interfaces to the D-Bus. This function
178 returns all interfaces of @var{service}, registered at object path
179 @var{path} at bus @var{bus}.
181 @var{bus} must be either the symbol @code{:system} or the symbol
182 @code{:session}. @var{service} must be a known service name, and
183 @var{path} must be a valid object path. The last two parameters are
184 strings. The result, the introspection data, is a string in XML
189 :system "org.freedesktop.Hal"
190 "/org/freedesktop/Hal/devices/computer")
192 @result{} "<!DOCTYPE node PUBLIC
193 \"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN\"
194 \"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd\">
196 <interface name=\"org.freedesktop.Hal.Device\">
197 <method name=\"GetAllProperties\">
198 <arg name=\"properties\" direction=\"out\" type=\"a@{sv@}\"/>
201 <signal name=\"PropertyModified\">
202 <arg name=\"num_updates\" type=\"i\"/>
203 <arg name=\"updates\" type=\"a(sbb)\"/>
210 This example informs us, that the service @code{org.freedesktop.Hal}
211 at object path @code{/org/freedesktop/Hal/devices/computer} offers the
212 interface @code{org.freedesktop.Hal.Device} (and 2 other interfaces
213 not documented here). This interface contains the method
214 @code{GetAllProperties}, which needs no input parameters, but returns
215 as output parameter an array of dictionary entries (key-value pairs).
216 Every dictionary entry has a string as key, and a variant as value.
218 The interface offers also a signal, which returns 2 parameters: an
219 integer, and an array consisting of elements which are a struct of a
220 string and 2 boolean values.
222 Such type descriptions are called @dfn{signature} in D-Bus. For a
223 discussion of D-Bus types and their Lisp representation see @ref{Type
224 Conversion}.@footnote{D-Bus signatures are explained in the D-Bus
226 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.
227 The interfaces of the service @code{org.freedesktop.Hal} are described
229 @uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.}
233 @node Type Conversion
234 @chapter Mapping Lisp types and D-Bus types.
235 @cindex type conversion
237 D-Bus method calls and signals accept usually several arguments as
238 parameters, either as input parameter, or as output parameter. Every
239 argument belongs to a D-Bus type.
241 Such arguments must be mapped between the value encoded as a D-Bus
242 type, and the corresponding type of Lisp objects. The mapping is
243 applied Lisp object @expansion{} D-Bus type for input parameters, and
244 D-Bus type @expansion{} Lisp object for output parameters.
247 @section Input parameters.
249 Input parameters for D-Bus methods and signals occur as arguments of a
250 Lisp function call. The following mapping to D-Bus types is
251 applied, when the corresponding D-Bus message is created:
254 @multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN}
255 @item Lisp type @tab @tab D-Bus type
257 @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN
258 @item number @tab @expansion{} @tab DBUS_TYPE_UINT32
259 @item integer @tab @expansion{} @tab DBUS_TYPE_INT32
260 @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE
261 @item string @tab @expansion{} @tab DBUS_TYPE_STRING
262 @item list @tab @expansion{} @tab DBUS_TYPE_ARRAY
266 Other Lisp objects, like symbols or hash tables, are not accepted as
269 If it is necessary to use another D-Bus type, a corresponding type
270 symbol can be preceeded to the corresponding Lisp object. Basic D-Bus
271 types are represented by the type symbols @code{:byte},
272 @code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32},
273 @code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double},
274 @code{:string}, @code{:object-path} and @code{:signature}.
280 (dbus-call-method ... @var{NUMBER} @var{STRING})
286 (dbus-call-method ... :uint32 @var{NUMBER} :string @var{STRING})
292 (dbus-call-method ... :int32 @var{NUMBER} :signature @var{STRING})
295 A D-Bus compound type is always represented as list. The car of this
296 list can be the type symbol @code{:array}, @code{:variant},
297 @code{:struct} or @code{:dict-entry}, which would result in a
298 corresponding D-Bus container. @code{:array} is optional, because
299 this is the default compoud type for a list.
301 The objects being elements of the list are checked according to the
302 D-Bus compound type rules.
305 @item An array must contain only elements of the same D-Bus type.
306 @item A variant must contain only one single element.
307 @item A dictionary entry must be element of an array, and it must
308 contain only a key-value pair of two element, with a basic type key.
309 @item There is no restriction for structs.
316 (dbus-send-signal ...
317 :object-path STRING '(:variant :boolean BOOL)
318 '(:array NUMBER NUMBER) '(:array BOOL :boolean BOOL)
319 '(:struct BOOL :boolean BOOL BOOL
320 (:array NUMBER NUMBER) (:array BOOL BOOL))
321 '(:struct NUMBER NUMBER) '((:dict-entry NUMBER (NUMBER)))
322 '(:array (:dict-entry NUMBER :int32 NUMBER)))
326 @section Output parameters.
328 Output parameters of D-Bus methods and signals are mapped to Lisp
332 @multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}}
333 @item D-Bus type @tab @tab Lisp type
335 @item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil}
336 @item DBUS_TYPE_BYTE @tab @expansion{} @tab number
337 @item DBUS_TYPE_UINT16 @tab @expansion{} @tab number
338 @item DBUS_TYPE_INT16 @tab @expansion{} @tab number
339 @item DBUS_TYPE_UINT32 @tab @expansion{} @tab number or float
340 @item DBUS_TYPE_INT32 @tab @expansion{} @tab number or float
341 @item DBUS_TYPE_UINT64 @tab @expansion{} @tab number or float
342 @item DBUS_TYPE_INT64 @tab @expansion{} @tab number or float
343 @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float
344 @item DBUS_TYPE_STRING @tab @expansion{} @tab string
345 @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
346 @item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string
347 @item DBUS_TYPE_ARRAY @tab @expansion{} @tab list
348 @item DBUS_TYPE_VARIANT @tab @expansion{} @tab list
349 @item DBUS_TYPE_STRUCT @tab @expansion{} @tab list
350 @item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list
354 A float object in case of @code{DBUS_TYPE_UINT32},
355 @code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and
356 @code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the
357 Emacs number size range.
359 The resulting list of the last 4 D-Bus compound types contains as
360 elements the elements of the D-Bus container, mapped according to the
363 The signal @code{PropertyModified}, discussed as example in
364 @ref{Inspection}, would offer as Lisp data the following object
365 (@var{BOOL} stands here for either @code{nil} or @code{t}):
368 (@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) ...))
372 @node Synchronous Methods
373 @chapter Calling methods in a blocking way.
374 @cindex method calls, synchronous
375 @cindex synchronous method calls
377 Methods can be called synchronously (@dfn{blocking}) or asynchronously
378 (@dfn{non-blocking}). Currently, just synchronous methods are
381 At D-Bus level, a method call consist of two messages: one message
382 which carries the input parameters to the object owning the method to
383 be called, and a reply message returning the resulting output
384 parameters from the object.
386 @defun dbus-call-method bus service path interface method &rest args
387 This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is
388 either the symbol @code{:system} or the symbol @code{:session}.
390 @var{service} is the D-Bus service name to be used. @var{path} is the
391 D-Bus object path, @var{service} is registered at. @var{interface} is
392 an interface offered by @var{service}. It must provide @var{method}.
394 All other arguments args are passed to @var{method} as arguments.
395 They are converted into D-Bus types as described in @ref{Type
398 The function returns the resulting values of @var{method} as a list of
399 Lisp objects, according to the type conversion rules described in
400 @ref{Type Conversion}. Example:
404 :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
405 "org.gnome.seahorse.Keys" "GetKeyField"
406 "openpgp:657984B8C7A966DD" "simple-name")
408 @result{} (t ("Philip R. Zimmermann"))
411 If the result of the method call is just one value, the converted Lisp
412 object is returned instead of a list containing this single Lisp
417 :system "org.freedesktop.Hal"
418 "/org/freedesktop/Hal/devices/computer"
419 "org.freedesktop.Hal.Device" "GetPropertyString"
420 "system.kernel.machine")
425 With the @code{dbus-introspect} function it is possible to explore the
426 interfaces of @samp{org.freedesktop.Hal} service. It offers the
427 interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
428 path @samp{/org/freedesktop/Hal/Manager} as well as the interface
429 @samp{org.freedesktop.Hal.Device} for all objects prefixed with the
430 path @samp{/org/freedesktop/Hal/devices}. With the methods
431 @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
432 emulate the @code{lshal} command on GNU/Linux systems:
437 :system "org.freedesktop.Hal"
438 "/org/freedesktop/Hal/Manager"
439 "org.freedesktop.Hal.Manager" "GetAllDevices"))
440 (message "\nudi = %s" device)
443 :system "org.freedesktop.Hal" device
444 "org.freedesktop.Hal.Device" "GetAllProperties"))
446 (car properties) (or (caar (cdr properties)) ""))))
448 @print{} "udi = /org/freedesktop/Hal/devices/computer
449 info.addons = (\"hald-addon-acpi\")
450 info.bus = \"unknown\"
451 info.product = \"Computer\"
452 info.subsystem = \"unknown\"
453 info.udi = \"/org/freedesktop/Hal/devices/computer\"
454 linux.sysfs_path_device = \"(none)\"
455 power_management.acpi.linux.version = \"20051216\"
456 power_management.can_suspend_to_disk = t
457 power_management.can_suspend_to_ram = \"\"
458 power_management.type = \"acpi\"
459 smbios.bios.release_date = \"11/07/2001\"
460 system.chassis.manufacturer = \"COMPAL\"
461 system.chassis.type = \"Notebook\"
462 system.firmware.release_date = \"03/19/2005\"
469 @chapter Sending and receiving signals.
472 Signals are broadcast messages. They carry input parameters, which
473 are received by all objects which have registered for such a signal.
475 @defun dbus-send-signal bus service path interface signal &rest args
476 This function is similar to @code{dbus-call-method}. The difference
477 is, that there are no returning output parameters.
479 The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is
480 either the symbol @code{:system} or the symbol @code{:session}. It
481 doesn't matter whether another object has registered for @var{signal}.
483 @var{service} is the D-Bus service name of the object the signal is
484 emitted from. @var{path} is the corresponding D-Bus object path,
485 @var{service} is registered at. @var{interface} is an interface
486 offered by @var{service}. It must provide @var{signal}.
488 All other arguments args are passed to @var{signal} as arguments.
489 They are converted into D-Bus types as described in @ref{Type
490 Conversion}. Example:
494 :session "org.gnu.Emacs" "/org/gnu/Emacs"
495 "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
499 @defun dbus-register-signal bus service path interface signal handler
500 With this function, an application registers for @var{signal} on the
503 @var{bus} is either the symbol @code{:system} or the symbol
506 @var{service} is the D-Bus service name used by the sending D-Bus
507 object. It can be either a known name or the unique name of the D-Bus
508 object sending the signal. In case of a unique name, signals won't be
509 received any longer once the object owning this unique name has
510 disappeared, and a new queued object has replaced it.
512 When @var{service} is @code{nil}, related signals from all D-Bus
513 objects shall be accepted.
515 @var{path} is the corresponding D-Bus object path, @var{service} is
516 registered at. It can also be @code{nil} if the path name of incoming
517 signals shall not be checked.
519 @var{interface} is an interface offered by @var{service}. It must
520 provide @var{signal}.
522 @var{handler} is a Lisp function to be called when the @var{signal} is
523 received. It must accept as arguments the output parameters
524 @var{signal} is sending. Example:
527 (defun my-dbus-signal-handler (device)
528 (message "Device %s added" device))
530 @result{} my-dbus-signal-handler
532 (dbus-register-signal
533 :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
534 "org.freedesktop.Hal.Manager" "DeviceAdded"
535 'my-dbus-signal-handler)
537 @result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded")
538 ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
542 As we know from the inspection data of interface
543 @code{org.freedesktop.Hal.Manager}, the signal @code{DeviceAdded}
544 provides one single parameter, which is mapped into a Lisp string.
545 The callback function @code{my-dbus-signal-handler} must define one
546 single string argument therefore. Plugging an USB device to your
547 machine, when registered for signal @code{DeviceAdded}, will show you
548 which objects the GNU/Linux @code{hal} daemon adds.
550 @code{dbus-register-signal} returns a Lisp symbol, which can be used
551 as argument in @code{dbus-unregister-signal} for removing the
552 registration for @var{signal}.
555 @defun dbus-unregister-signal object
556 Unregister @var{object} from the the D-Bus. @var{object} must be the
557 result of a preceding @code{dbus-register-signal} call.
561 @node Errors and Events
562 @chapter Errors and events.
566 Input parameters of @code{dbus-call-method} and
567 @code{dbus-register-signal} are checked for correct D-Bus types. If
568 there is a type mismatch, the Lisp error @code{wrong-type-argument}
569 @code{D-Bus ARG} is raised.
571 All errors raised by D-Bus are signaled with the error symbol
572 @code{dbus-error}. As usual, such an error can be trapped with a
573 @code{condition-case} form. If possible, error messages from D-Bus
574 are appended to the @code{dbus-error}.
576 Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc
577 Events, , , elisp}). The generated event has this form:
580 (dbus-event @var{bus} @var{service} @var{path} @var{interface} @var{member} @var{handler} &rest @var{args})
583 @var{bus} identifies the D-Bus the signal is coming from. It is
584 either the symbol @code{:system} or the symbol @code{:session}.
586 @var{service} and @var{path} are the unique name and the object path
587 of the D-Bus object emitting the signal. @var{interface} and
588 @var{member} denote the signal which has been sent.
590 @var{handler} is the callback function which has been registered for
591 this signal (see @pxref{Signals}). When a @code{dbus-event} event
592 arrives, @var{handler} is called with @var{args} as arguments.
594 In order to inspect the @code{dbus-event} data, you could extend the
595 definition of the callback function in @ref{Signals}:
598 (defun my-dbus-signal-handler (&rest args)
599 (message "my-dbus-signal-handler: %S" last-input-event))
602 There exist convenience functions which could be called inside a
603 callback function in order to retrieve the information from the event.
605 @defun dbus-event-bus-name event
606 Returns the bus name @var{event} is coming from.
607 The result is either the symbol @code{:system} or the symbol @code{:session}.
610 @defun dbus-event-service-name event
611 Returns the unique name of the D-Bus object @var{event} is coming from.
614 @defun dbus-event-path-name event
615 Returns the object path of the D-Bus object @var{event} is coming from.
618 @defun dbus-event-interface-name event
619 Returns the interface name of of the D-Bus object @var{event} is coming from.
622 @defun dbus-event-member-name event
623 Returns the member name of of the D-Bus object @var{event} is coming
624 from. It is either a signal name or a method name.
628 @node GNU Free Documentation License
629 @appendix GNU Free Documentation License
630 @include doclicense.texi
637 arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8