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 e.g. @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
118 This function returns the D-Bus service names, which can be activated.
119 An activatable service is described in a service registration file.
120 Under GNU/Linux, such files are located at
121 @file{/usr/share/dbus-1/services/}.
123 The result is a list of strings, which is @code{nil} when there are no
124 activatable service names at all.
127 @defun dbus-list-names bus
129 All service names, which are registered at D-Bus @var{bus}, are
130 returned. The result is a list of strings, which is @code{nil} when
131 there are no registered service names at all. Well known names are
132 strings like @samp{org.freedesktop.DBus}. Names starting with
133 @samp{:} are unique names for services.
135 @var{bus} must be either the symbol @code{:system} or the symbol
139 @defun dbus-list-known-names bus
141 Retrieves all services which correspond to a known name in @var{bus}.
142 A service has a known name if it doesn't start with @samp{:}. The
143 result is a list of strings, which is @code{nil} when there are no
146 @var{bus} must be either the symbol @code{:system} or the symbol
150 @defun dbus-list-queued-owners bus service
152 For a given service, registered at D-Bus @var{bus} under the name
153 @var{service}, all queued unique names are returned. The result is a
154 list of strings, or @code{nil} when there are no queued names for
155 @var{service} at all.
157 @var{bus} must be either the symbol @code{:system} or the symbol
158 @code{:session}. @var{service} must be a known service name as
162 @defun dbus-get-name-owner bus service
164 For a given service, registered at D-Bus @var{bus} under the name
165 @var{service}, the unique name of the name owner is returned. The result is a
166 string, or @code{nil} when there exist no name owner of @var{service}.
168 @var{bus} must be either the symbol @code{:system} or the symbol
169 @code{:session}. @var{service} must be a known service name as
173 @defun dbus-get-unique-name bus
175 The unique name, under which Emacs is registered at D-Bus @var{bus},
176 is returned as string.
178 @var{bus} must be either the symbol @code{:system} or the symbol
182 @defun dbus-introspect bus service path
184 Objects can publish there interfaces to the D-Bus. This function
185 returns all interfaces of @var{service}, registered at object path
186 @var{path} at bus @var{bus}.
188 @var{bus} must be either the symbol @code{:system} or the symbol
189 @code{:session}. @var{service} must be a known service name, and
190 @var{path} must be a valid object path. The last two parameters are
191 strings. The result, the introspection data, is a string in XML
196 :system "org.freedesktop.Hal"
197 "/org/freedesktop/Hal/devices/computer")
199 @result{} <!DOCTYPE node PUBLIC
200 "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
201 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
203 <interface name="org.freedesktop.Hal.Device">
204 <method name="GetAllProperties">
205 <arg name="properties" direction="out" type="a@{sv@}"/>
208 <signal name="PropertyModified">
209 <arg name="num_updates" type="i"/>
210 <arg name="updates" type="a(sbb)"/>
217 This example informs us, that the service @code{org.freedesktop.Hal}
218 at object path @code{/org/freedesktop/Hal/devices/computer} offers the
219 interface @code{org.freedesktop.Hal.Device} (and 2 other interfaces
220 not documented here). This interface contains the method
221 @code{GetAllProperties}, which needs no input parameters, but returns
222 as output parameter an array of dictionary entries (key-value pairs).
223 Every dictionary entry has a string as key, and a variant as value.
225 The interface offers also a signal, which returns 2 parameters: an
226 integer, and an array consisting of elements which are a struct of a
227 string and 2 boolean values.
229 Such type descriptions are called @dfn{signature} in D-Bus. For a
230 discussion of D-Bus types and their Lisp representation see @ref{Type
231 Conversion}.@footnote{D-Bus signatures are explained in the D-Bus
233 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.
234 The interfaces of the service @code{org.freedesktop.Hal} are described
236 @uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.}
240 @node Type Conversion
241 @chapter Mapping Lisp types and D-Bus types.
242 @cindex type conversion
244 D-Bus method calls and signals accept usually several arguments as
245 parameters, either as input parameter, or as output parameter. Every
246 argument belongs to a D-Bus type.
248 Such arguments must be mapped between the the value encoded as a D-Bus
249 type, and the corresponding type of Lisp objects. The mapping is
250 applied Lisp object @expansion{} D-Bus type for input parameters, and
251 D-Bus type @expansion{} Lisp object for output parameters.
254 @section Input parameters.
256 Input parameters for D-Bus methods and signals occur as arguments of a
257 Lisp function call. Only some primitive Lisp types are supported in
258 the current implementation. The following mapping to D-Bus types is
259 applied, when the corresponding D-Bus message is created:
262 @multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN}
263 @item Lisp type @tab @tab D-Bus type
265 @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN
266 @item number @tab @expansion{} @tab DBUS_TYPE_UINT32
267 @item integer @tab @expansion{} @tab DBUS_TYPE_INT32
268 @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE
269 @item string @tab @expansion{} @tab DBUS_TYPE_STRING
274 Other Lisp types, especially lists, are not supported (yet).
277 @section Output parameters.
279 Output parameters of D-Bus methods and signals are mapped to Lisp
280 objects. This mapping is more powerful than the one for input
281 parameters, i.e. more types are supported by the current
285 @multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}}
286 @item D-Bus type @tab @tab Lisp type
288 @item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil}
289 @item DBUS_TYPE_UINT32 @tab @expansion{} @tab number
290 @item DBUS_TYPE_INT32 @tab @expansion{} @tab number
291 @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float
292 @item DBUS_TYPE_STRING @tab @expansion{} @tab string
293 @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
294 @item DBUS_TYPE_ARRAY @tab @expansion{} @tab list
295 @item DBUS_TYPE_VARIANT @tab @expansion{} @tab list
296 @item DBUS_TYPE_STRUCT @tab @expansion{} @tab list
297 @item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list
301 The resulting list of the last 4 D-Bus compound types contains as
302 elements the elements of the D-Bus container, mapped according to the
305 The signal @code{PropertyModified}, discussed as example in
306 @ref{Inspection}, would offer as Lisp data the following object
307 (@var{BOOL} stands here for either @code{nil} or @code{t}):
310 (@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) ...))
314 @node Synchronous Methods
315 @chapter Calling methods in a blocking way.
316 @cindex method calls, synchronous
317 @cindex synchronous method calls
319 Methods can be called synchronously (@dfn{blocking}) or asynchronously
320 (@dfn{non-blocking}). Currently, just synchronous methods are
323 At D-Bus level, a method call consist of two messages: one message
324 which carries the input parameters to the object owning the method to
325 be called, and a reply message returning the resulting output
326 parameters from the object.
328 @defun dbus-call-method bus method service path interface &rest args
330 This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is
331 either the symbol @code{:system} or the symbol @code{:session}.
333 @var{service} is the D-Bus service name to be used. @var{path} is the
334 D-Bus object path, @var{service} is registered at. @var{interface} is
335 an interface offered by @var{service}. It must provide @var{method}.
337 All other arguments args are passed to @var{method} as arguments.
338 They are converted into D-Bus types as described in @ref{Type
341 The function returns the resulting values of @var{method} as a list of
342 Lisp objects, according to the type conversion rules described in
343 @ref{Type Conversion}. Example:
347 :session "GetKeyField" "org.gnome.seahorse"
348 "/org/gnome/seahorse/keys/openpgp" "org.gnome.seahorse.Keys"
349 "openpgp:657984B8C7A966DD" "simple-name")
351 @result{} (t ("Philip R. Zimmermann"))
354 If the result of the method call is just one value, the converted Lisp
355 object is returned instead of a list containing this single Lisp
360 :system "GetPropertyString" "org.freedesktop.Hal"
361 "/org/freedesktop/Hal/devices/computer" "org.freedesktop.Hal.Device"
362 "system.kernel.machine")
367 With the @code{dbus-introspect} function it is possible to explore the
368 interfaces of @samp{org.freedesktop.Hal} service. It offers the
369 interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
370 path @samp{/org/freedesktop/Hal/Manager} as well as the interface
371 @samp{org.freedesktop.Hal.Device} for all objects prefixed with the
372 path @samp{/org/freedesktop/Hal/devices}. With the methods
373 @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
374 emulate the @code{lshal} command on GNU/Linux systems:
379 :system "GetAllDevices" "org.freedesktop.Hal"
380 "/org/freedesktop/Hal/Manager"
381 "org.freedesktop.Hal.Manager"))
382 (message "\nudi = %s" device)
385 :system "GetAllProperties" "org.freedesktop.Hal"
386 device "org.freedesktop.Hal.Device"))
388 (car properties) (or (caar (cdr properties)) ""))))
390 @result{} udi = /org/freedesktop/Hal/devices/computer
391 info.addons = ("hald-addon-acpi")
393 info.product = "Computer"
394 info.subsystem = "unknown"
395 info.udi = "/org/freedesktop/Hal/devices/computer"
396 linux.sysfs_path_device = "(none)"
397 power_management.acpi.linux.version = "20051216"
398 power_management.can_suspend_to_disk = t
399 power_management.can_suspend_to_ram = ""
400 power_management.type = "acpi"
401 smbios.bios.release_date = "11/07/2001"
402 system.chassis.manufacturer = "COMPAL"
403 system.chassis.type = "Notebook"
404 system.firmware.release_date = "03/19/2005"
411 @chapter Sending and receiving signals.
414 Signals are broadcast messages. They carry input parameters, which
415 are received by all objects which have registered for such a signal.
417 @defun dbus-send-signal bus signal service path interface &rest args
419 This function is similar to @code{dbus-call-method}. The difference
420 is, that there are no returning output parameters.
422 The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is
423 either the symbol @code{:system} or the symbol @code{:session}. It
424 doesn't matter whether another object has registered for @var{signal}.
426 @var{service} is the D-Bus service name of the object the signal is
427 emitted from. @var{path} is the corresponding D-Bus object path,
428 @var{service} is registered at. @var{interface} is an interface
429 offered by @var{service}. It must provide @var{signal}.
431 All other arguments args are passed to @var{signal} as arguments.
432 They are converted into D-Bus types as described in @ref{Type
433 Conversion}. Example:
437 :session "FileModified" "org.gnu.Emacs" "/org/gnu/Emacs"
438 "org.gnu.Emacs.FileManager" "/home/albinus/.emacs")
442 @defun dbus-register-signal bus signal service path interface handler
444 With this function, an application registers for @var{signal} on the
447 @var{bus} is either the symbol @code{:system} or the symbol
450 @var{service} is the D-Bus service name of the object the signal is
451 emitted from. @var{path} is the corresponding D-Bus object path,
452 @var{service} is registered at. @var{interface} is an interface
453 offered by @var{service}. It must provide @var{signal}.
455 @var{handler} is a Lisp function to be called when the @var{signal} is
456 received. It must accept as arguments the output parameters
457 @var{signal} is sending. Example:
460 (defun my-dbus-signal-handler (device)
461 (message "Device %s added" device))
463 (dbus-register-signal
464 :system "DeviceAdded" "org.freedesktop.Hal"
465 "/org/freedesktop/Hal/Manager" "org.freedesktop.Hal.Manager"
466 'my-dbus-signal-handler)
468 @result{} :system.org.freedesktop.Hal.Manager.DeviceAdded
471 As we know from the inspection data of interface
472 @code{org.freedesktop.Hal.Manager}, the signal @code{DeviceAdded}
473 provides one single parameter, which is mapped into a Lisp string.
474 The callback function @code{my-dbus-signal-handler} must define one
475 single string argument therefore. Plugging an USB device to your
476 machine, when registered for signal @code{DeviceAdded}, will show you
477 which objects the GNU/Linux @code{hal} daemon adds.
479 @code{dbus-register-signal} returns a Lisp symbol, which can be used
480 as argument in @code{dbus-unregister-signal} for removing the
481 registration for @var{signal}.
484 @defun dbus-unregister-signal object
486 Unregister @var{object} from the the D-Bus. @var{object} must be the
487 result of a preceding @code{dbus-register-signal} call.
491 @node Errors and Events
492 @chapter Errors and events.
496 All errors raised by D-Bus are signaled with the error symbol
497 @code{dbus-error}. As usual, such an error can be trapped with a
498 @code{condition-case} form. If possible, error messages from D-Bus
499 are appended to the @code{dbus-error}.
501 Incoming D-Bus messages are handled as Emacs event (see @pxref{Misc
502 Events, , , elisp}). The generated event has this form:
505 (dbus-event @var{symbol} @var{service} @var{path} &rest @var{args})
508 @var{symbol} is the interned Lisp symbol which has been generated
509 during signal registration (see @pxref{Signals}). Its function cell
510 is the argument @var{handler}, the callback function which was
511 provided by @code{dbus-register-signal}. When a @code{dbus-event}
512 event arrives, @var{handler} is called with @var{args} as arguments.
514 @var{service} and @var{path} are the unique name and the object path
515 of the D-Bus object emitting the signal.
517 In order to inspect the @code{dbus-event} data, you could extend the
518 definition of the callback function in @ref{Signals}:
521 (defun my-dbus-signal-handler (&rest args)
522 (message "my-dbus-signal-handler: %S" last-input-event))
525 There exist convenience functions which could be called inside a
526 callback function in order to retrieve the information from the event.
528 @defun dbus-event-bus-name event
530 Returns the bus name @var{event} is coming from.
531 The result is either the symbol @code{:system} or the symbol @code{:session}.
534 @defun dbus-event-service-name event
536 Returns the unique name of the D-Bus object @var{event} is coming from.
539 @defun dbus-event-path-name event
541 Returns the object path of the D-Bus object @var{event} is coming from.
544 @defun dbus-event-interface-name event
546 Returns the interface name of of the D-Bus object @var{event} is coming from.
549 @defun dbus-event-member-name event
551 Returns the member name of of the D-Bus object @var{event} is coming
552 from. It is either a signal name or a method name.
556 @node GNU Free Documentation License
557 @appendix GNU Free Documentation License
558 @include doclicense.texi