doc/misc/dbus.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @setfilename ../../info/dbus
   3 @c %**start of header
   4 @settitle Using of D-Bus
   5 @c @setchapternewpage odd
   6 @c %**end of header
   7
   8 @copying
   9 Copyright @copyright{} 2007 Free Software Foundation, Inc.
  10
  11 @quotation
  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.
  19
  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.''
  23
  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.
  28 @end quotation
  29 @end copying
  30
  31 @dircategory Emacs
  32 @direntry
  33 * D-Bus: (dbus).                Using D-Bus in Emacs.
  34 @end direntry
  35
  36 @node Top, Overview, (dir), (dir)
  37 @top D-Bus integration in Emacs
  38
  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/}.
  45
  46 @insertcopying
  47
  48 @menu
  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.
  56 @end menu
  57
  58 @node Overview
  59 @chapter An overview of D-Bus
  60 @cindex overview
  61
  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.
  66
  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
  72 user's session.
  73
  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}.
  78
  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.
  86
  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/}.
  91
  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.
  96
  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.
 100
 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}.
 106
 107
 108 @node Inspection
 109 @chapter Inspection of the bus names.
 110 @cindex inspection
 111
 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.
 115
 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/}.
 121
 122 The result is a list of strings, which is @code{nil} when there are no
 123 activatable service names at all.
 124 @end defun
 125
 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.
 132
 133 @var{bus} must be either the symbol @code{:system} or the symbol
 134 @code{:session}.
 135 @end defun
 136
 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
 141 known names at all.
 142
 143 @var{bus} must be either the symbol @code{:system} or the symbol
 144 @code{:session}.
 145 @end defun
 146
 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.
 152
 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
 155 string.
 156 @end defun
 157
 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
 161 result is a string, or @code{nil} when there exist no name owner of
 162 @var{service}.
 163
 164 @var{bus} must be either the symbol @code{:system} or the symbol
 165 @code{:session}.  @var{service} must be a known service name as
 166 string.
 167 @end defun
 168
 169 @defun dbus-get-unique-name bus
 170 The unique name, under which Emacs is registered at D-Bus @var{bus},
 171 is returned as string.
 172
 173 @var{bus} must be either the symbol @code{:system} or the symbol
 174 @code{:session}.
 175 @end defun
 176
 177 @defun dbus-introspect bus service path
 178 Objects can publish there interfaces to the D-Bus.  This function
 179 returns all interfaces of @var{service}, registered at object path
 180 @var{path} at bus @var{bus}.
 181
 182 @var{bus} must be either the symbol @code{:system} or the symbol
 183 @code{:session}.  @var{service} must be a known service name, and
 184 @var{path} must be a valid object path.  The last two parameters are
 185 strings.  The result, the introspection data, is a string in XML
 186 format. Example:
 187
 188 @example
 189 (dbus-introspect
 190   :system "org.freedesktop.Hal"
 191   "/org/freedesktop/Hal/devices/computer")
 192
 193 @result{} "<!DOCTYPE node PUBLIC
 194     \"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN\"
 195     \"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd\">
 196     <node>
 197       <interface name=\"org.freedesktop.Hal.Device\">
 198         <method name=\"GetAllProperties\">
 199           <arg name=\"properties\" direction=\"out\" type=\"a@{sv@}\"/>
 200         </method>
 201         ...
 202         <signal name=\"PropertyModified\">
 203           <arg name=\"num_updates\" type=\"i\"/>
 204           <arg name=\"updates\" type=\"a(sbb)\"/>
 205         </signal>
 206       </interface>
 207       ...
 208     </node>"
 209 @end example
 210
 211 This example informs us, that the service @code{org.freedesktop.Hal}
 212 at object path @code{/org/freedesktop/Hal/devices/computer} offers the
 213 interface @code{org.freedesktop.Hal.Device} (and 2 other interfaces
 214 not documented here).  This interface contains the method
 215 @code{GetAllProperties}, which needs no input parameters, but returns
 216 as output parameter an array of dictionary entries (key-value pairs).
 217 Every dictionary entry has a string as key, and a variant as value.
 218
 219 The interface offers also a signal, which returns 2 parameters: an
 220 integer, and an array consisting of elements which are a struct of a
 221 string and 2 boolean values.
 222
 223 Such type descriptions are called @dfn{signature} in D-Bus.  For a
 224 discussion of D-Bus types and their Lisp representation see @ref{Type
 225 Conversion}.@footnote{D-Bus signatures are explained in the D-Bus
 226 specification
 227 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.
 228 The interfaces of the service @code{org.freedesktop.Hal} are described
 229 at
 230 @uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.}
 231 @end defun
 232
 233
 234 @node Type Conversion
 235 @chapter Mapping Lisp types and D-Bus types.
 236 @cindex type conversion
 237
 238 D-Bus method calls and signals accept usually several arguments as
 239 parameters, either as input parameter, or as output parameter.  Every
 240 argument belongs to a D-Bus type.
 241
 242 Such arguments must be mapped between the the value encoded as a D-Bus
 243 type, and the corresponding type of Lisp objects.  The mapping is
 244 applied Lisp object @expansion{} D-Bus type for input parameters, and
 245 D-Bus type @expansion{} Lisp object for output parameters.
 246
 247
 248 @section Input parameters.
 249
 250 Input parameters for D-Bus methods and signals occur as arguments of a
 251 Lisp function call.  Only some primitive Lisp types are supported in
 252 the current implementation.  The following mapping to D-Bus types is
 253 applied, when the corresponding D-Bus message is created:
 254
 255 @example
 256 @multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN}
 257 @item Lisp type               @tab              @tab D-Bus type
 258 @item
 259 @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN
 260 @item number                  @tab @expansion{} @tab DBUS_TYPE_UINT32
 261 @item integer                 @tab @expansion{} @tab DBUS_TYPE_INT32
 262 @item float                   @tab @expansion{} @tab DBUS_TYPE_DOUBLE
 263 @item string                  @tab @expansion{} @tab DBUS_TYPE_STRING
 264 @end multitable
 265 @end example
 266
 267 @noindent
 268 Other Lisp types, especially lists, are not supported (yet).
 269
 270
 271 @section Output parameters.
 272
 273 Output parameters of D-Bus methods and signals are mapped to Lisp
 274 objects.  This mapping is more powerful than the one for input
 275 parameters, i.e., more D-Bus types are supported by the current
 276 implementation.
 277
 278 @example
 279 @multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}}
 280 @item D-Bus type            @tab              @tab Lisp type
 281 @item
 282 @item DBUS_TYPE_BOOLEAN     @tab @expansion{} @tab @code{t} or @code{nil}
 283 @item DBUS_TYPE_UINT32      @tab @expansion{} @tab number
 284 @item DBUS_TYPE_INT32       @tab @expansion{} @tab number
 285 @item DBUS_TYPE_DOUBLE      @tab @expansion{} @tab float
 286 @item DBUS_TYPE_STRING      @tab @expansion{} @tab string
 287 @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
 288 @item DBUS_TYPE_ARRAY       @tab @expansion{} @tab list
 289 @item DBUS_TYPE_VARIANT     @tab @expansion{} @tab list
 290 @item DBUS_TYPE_STRUCT      @tab @expansion{} @tab list
 291 @item DBUS_TYPE_DICT_ENTRY  @tab @expansion{} @tab list
 292 @end multitable
 293 @end example
 294
 295 The resulting list of the last 4 D-Bus compound types contains as
 296 elements the elements of the D-Bus container, mapped according to the
 297 same rules.
 298
 299 The signal @code{PropertyModified}, discussed as example in
 300 @ref{Inspection}, would offer as Lisp data the following object
 301 (@var{BOOL} stands here for either @code{nil} or @code{t}):
 302
 303 @lisp
 304 (@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) ...))
 305 @end lisp
 306
 307
 308 @node Synchronous Methods
 309 @chapter Calling methods in a blocking way.
 310 @cindex method calls, synchronous
 311 @cindex synchronous method calls
 312
 313 Methods can be called synchronously (@dfn{blocking}) or asynchronously
 314 (@dfn{non-blocking}).  Currently, just synchronous methods are
 315 implemented.
 316
 317 At D-Bus level, a method call consist of two messages: one message
 318 which carries the input parameters to the object owning the method to
 319 be called, and a reply message returning the resulting output
 320 parameters from the object.
 321
 322 @defun dbus-call-method bus method service path interface &rest args
 323 This function calls @var{method} on the D-Bus @var{bus}.  @var{bus} is
 324 either the symbol @code{:system} or the symbol @code{:session}.
 325
 326 @var{service} is the D-Bus service name to be used.  @var{path} is the
 327 D-Bus object path, @var{service} is registered at.  @var{interface} is
 328 an interface offered by @var{service}.  It must provide @var{method}.
 329
 330 All other arguments args are passed to @var{method} as arguments.
 331 They are converted into D-Bus types as described in @ref{Type
 332 Conversion}.
 333
 334 The function returns the resulting values of @var{method} as a list of
 335 Lisp objects, according to the type conversion rules described in
 336 @ref{Type Conversion}.  Example:
 337
 338 @example
 339 (dbus-call-method
 340   :session "GetKeyField" "org.gnome.seahorse"
 341   "/org/gnome/seahorse/keys/openpgp" "org.gnome.seahorse.Keys"
 342   "openpgp:657984B8C7A966DD" "simple-name")
 343
 344 @result{} (t ("Philip R. Zimmermann"))
 345 @end example
 346
 347 If the result of the method call is just one value, the converted Lisp
 348 object is returned instead of a list containing this single Lisp
 349 object.  Example:
 350
 351 @example
 352 (dbus-call-method
 353   :system "GetPropertyString" "org.freedesktop.Hal"
 354   "/org/freedesktop/Hal/devices/computer" "org.freedesktop.Hal.Device"
 355   "system.kernel.machine")
 356
 357 @result{} "i686"
 358 @end example
 359
 360 With the @code{dbus-introspect} function it is possible to explore the
 361 interfaces of @samp{org.freedesktop.Hal} service. It offers the
 362 interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
 363 path @samp{/org/freedesktop/Hal/Manager} as well as the interface
 364 @samp{org.freedesktop.Hal.Device} for all objects prefixed with the
 365 path @samp{/org/freedesktop/Hal/devices}.  With the methods
 366 @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
 367 emulate the @code{lshal} command on GNU/Linux systems:
 368
 369 @example
 370 (dolist (device
 371           (dbus-call-method
 372             :system "GetAllDevices" "org.freedesktop.Hal"
 373             "/org/freedesktop/Hal/Manager"
 374             "org.freedesktop.Hal.Manager"))
 375   (message "\nudi = %s" device)
 376   (dolist (properties
 377             (dbus-call-method
 378               :system "GetAllProperties" "org.freedesktop.Hal"
 379               device "org.freedesktop.Hal.Device"))
 380     (message "  %s = %S"
 381              (car properties) (or (caar (cdr properties)) ""))))
 382
 383 @print{} "udi = /org/freedesktop/Hal/devices/computer
 384       info.addons = (\"hald-addon-acpi\")
 385       info.bus = \"unknown\"
 386       info.product = \"Computer\"
 387       info.subsystem = \"unknown\"
 388       info.udi = \"/org/freedesktop/Hal/devices/computer\"
 389       linux.sysfs_path_device = \"(none)\"
 390       power_management.acpi.linux.version = \"20051216\"
 391       power_management.can_suspend_to_disk = t
 392       power_management.can_suspend_to_ram = \"\"
 393       power_management.type = \"acpi\"
 394       smbios.bios.release_date = \"11/07/2001\"
 395       system.chassis.manufacturer = \"COMPAL\"
 396       system.chassis.type = \"Notebook\"
 397       system.firmware.release_date = \"03/19/2005\"
 398       ..."
 399 @end example
 400 @end defun
 401
 402
 403 @node Signals
 404 @chapter Sending and receiving signals.
 405 @cindex signals
 406
 407 Signals are broadcast messages.  They carry input parameters, which
 408 are received by all objects which have registered for such a signal.
 409
 410 @defun dbus-send-signal bus signal service path interface &rest args
 411 This function is similar to @code{dbus-call-method}.  The difference
 412 is, that there are no returning output parameters.
 413
 414 The function emits @var{signal} on the D-Bus @var{bus}.  @var{bus} is
 415 either the symbol @code{:system} or the symbol @code{:session}.  It
 416 doesn't matter whether another object has registered for @var{signal}.
 417
 418 @var{service} is the D-Bus service name of the object the signal is
 419 emitted from.  @var{path} is the corresponding D-Bus object path,
 420 @var{service} is registered at.  @var{interface} is an interface
 421 offered by @var{service}.  It must provide @var{signal}.
 422
 423 All other arguments args are passed to @var{signal} as arguments.
 424 They are converted into D-Bus types as described in @ref{Type
 425 Conversion}.  Example:
 426
 427 @example
 428 (dbus-send-signal
 429   :session "FileModified" "org.gnu.Emacs" "/org/gnu/Emacs"
 430   "org.gnu.Emacs.FileManager" "/home/albinus/.emacs")
 431 @end example
 432 @end defun
 433
 434 @defun dbus-register-signal bus signal service path interface handler
 435 With this function, an application registers for @var{signal} on the
 436 D-Bus @var{bus}.
 437
 438 @var{bus} is either the symbol @code{:system} or the symbol
 439 @code{:session}.
 440
 441 @var{service} is the D-Bus service name of the object the signal is
 442 emitted from.  @var{path} is the corresponding D-Bus object path,
 443 @var{service} is registered at.  @var{interface} is an interface
 444 offered by @var{service}.  It must provide @var{signal}.
 445
 446 @var{handler} is a Lisp function to be called when the @var{signal} is
 447 received.  It must accept as arguments the output parameters
 448 @var{signal} is sending.  Example:
 449
 450 @example
 451 (defun my-dbus-signal-handler (device)
 452   (message "Device %s added" device))
 453
 454 (dbus-register-signal
 455   :system "DeviceAdded" "org.freedesktop.Hal"
 456   "/org/freedesktop/Hal/Manager" "org.freedesktop.Hal.Manager"
 457   'my-dbus-signal-handler)
 458
 459 @result{} :system.org.freedesktop.Hal.Manager.DeviceAdded
 460 @end example
 461
 462 As we know from the inspection data of interface
 463 @code{org.freedesktop.Hal.Manager}, the signal @code{DeviceAdded}
 464 provides one single parameter, which is mapped into a Lisp string.
 465 The callback function @code{my-dbus-signal-handler} must define one
 466 single string argument therefore.  Plugging an USB device to your
 467 machine, when registered for signal @code{DeviceAdded}, will show you
 468 which objects the GNU/Linux @code{hal} daemon adds.
 469
 470 @code{dbus-register-signal} returns a Lisp symbol, which can be used
 471 as argument in @code{dbus-unregister-signal} for removing the
 472 registration for @var{signal}.
 473 @end defun
 474
 475 @defun dbus-unregister-signal object
 476 Unregister @var{object} from the the D-Bus.  @var{object} must be the
 477 result of a preceding @code{dbus-register-signal} call.
 478 @end defun
 479
 480
 481 @node Errors and Events
 482 @chapter Errors and events.
 483 @cindex errors
 484 @cindex events
 485
 486 All errors raised by D-Bus are signaled with the error symbol
 487 @code{dbus-error}.  As usual, such an error can be trapped with a
 488 @code{condition-case} form.  If possible, error messages from D-Bus
 489 are appended to the @code{dbus-error}.
 490
 491 Incoming D-Bus messages are handled as Emacs event (see @pxref{Misc
 492 Events, , , elisp}).  The generated event has this form:
 493
 494 @example
 495 (dbus-event @var{symbol} @var{service} @var{path} &rest @var{args})
 496 @end example
 497
 498 @var{symbol} is the interned Lisp symbol which has been generated
 499 during signal registration (see @pxref{Signals}).  Its function cell
 500 is the argument @var{handler}, the callback function which was
 501 provided by @code{dbus-register-signal}.  When a @code{dbus-event}
 502 event arrives, @var{handler} is called with @var{args} as arguments.
 503
 504 @var{service} and @var{path} are the unique name and the object path
 505 of the D-Bus object emitting the signal.
 506
 507 In order to inspect the @code{dbus-event} data, you could extend the
 508 definition of the callback function in @ref{Signals}:
 509
 510 @example
 511 (defun my-dbus-signal-handler (&rest args)
 512   (message "my-dbus-signal-handler: %S" last-input-event))
 513 @end example
 514
 515 There exist convenience functions which could be called inside a
 516 callback function in order to retrieve the information from the event.
 517
 518 @defun dbus-event-bus-name event
 519 Returns the bus name @var{event} is coming from.
 520 The result is either the symbol @code{:system} or the symbol @code{:session}.
 521 @end defun
 522
 523 @defun dbus-event-service-name event
 524 Returns the unique name of the D-Bus object @var{event} is coming from.
 525 @end defun
 526
 527 @defun dbus-event-path-name event
 528 Returns the object path of the D-Bus object @var{event} is coming from.
 529 @end defun
 530
 531 @defun dbus-event-interface-name event
 532 Returns the interface name of of the D-Bus object @var{event} is coming from.
 533 @end defun
 534
 535 @defun dbus-event-member-name event
 536 Returns the member name of of the D-Bus object @var{event} is coming
 537 from.  It is either a signal name or a method name.
 538 @end defun
 539
 540
 541 @node GNU Free Documentation License
 542 @appendix GNU Free Documentation License
 543 @include doclicense.texi
 544
 545 @contents
 546 @c End of dbus.texi
 547 @bye