dbus.texi 71.2 KB
Newer Older
Michael Albinus's avatar
Michael Albinus committed
1 2 3 4 5 6 7
\input texinfo   @c -*-texinfo-*-
@setfilename ../../info/dbus
@c %**start of header
@settitle Using of D-Bus
@c @setchapternewpage odd
@c %**end of header

8 9 10
@syncodeindex vr cp
@syncodeindex fn cp

Michael Albinus's avatar
Michael Albinus committed
11
@copying
Paul Eggert's avatar
Paul Eggert committed
12
Copyright @copyright{} 2007--2014 Free Software Foundation, Inc.
Michael Albinus's avatar
Michael Albinus committed
13 14 15

@quotation
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
Michael Albinus's avatar
Michael Albinus committed
17
any later version published by the Free Software Foundation; with no
18 19 20
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
Michael Albinus's avatar
Michael Albinus committed
21

22
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
23
modify this GNU manual.''
Michael Albinus's avatar
Michael Albinus committed
24 25 26
@end quotation
@end copying

27
@dircategory Emacs lisp libraries
Michael Albinus's avatar
Michael Albinus committed
28 29 30 31
@direntry
* D-Bus: (dbus).                Using D-Bus in Emacs.
@end direntry

32 33 34 35 36 37 38 39
@titlepage
@title Using D-Bus in Emacs
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage


40
@contents
41

42

Michael Albinus's avatar
Michael Albinus committed
43 44 45
@node Top, Overview, (dir), (dir)
@top D-Bus integration in Emacs

46 47 48 49
This manual documents an API for usage of D-Bus in Emacs.  D-Bus is a
message bus system, a simple way for applications to talk to one
another.  An overview of D-Bus can be found at
@uref{http://dbus.freedesktop.org/}.
Michael Albinus's avatar
Michael Albinus committed
50

51
@ifnottex
Michael Albinus's avatar
Michael Albinus committed
52
@insertcopying
53
@end ifnottex
Michael Albinus's avatar
Michael Albinus committed
54 55 56

@menu
* Overview::                    An overview of D-Bus.
57
* Inspection::                  Inspection of D-Bus services.
Michael Albinus's avatar
Michael Albinus committed
58 59
* Type Conversion::             Mapping Lisp types and D-Bus types.
* Synchronous Methods::         Calling methods in a blocking way.
60
* Asynchronous Methods::        Calling methods non-blocking.
61
* Receiving Method Calls::      Offering own methods.
Michael Albinus's avatar
Michael Albinus committed
62
* Signals::                     Sending and receiving signals.
63
* Alternative Buses::           Alternative buses and environments.
Michael Albinus's avatar
Michael Albinus committed
64
* Errors and Events::           Errors and events.
65 66
* Index::                       Index including concepts, functions, variables.

Michael Albinus's avatar
Michael Albinus committed
67 68 69
* GNU Free Documentation License:: The license for this documentation.
@end menu

70

Michael Albinus's avatar
Michael Albinus committed
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
@node Overview
@chapter An overview of D-Bus
@cindex overview

D-Bus is an inter-process communication mechanism for applications
residing on the same host.  The communication is based on
@dfn{messages}.  Data in the messages is carried in a structured way,
it is not just a byte stream.

The communication is connection oriented to two kinds of message
buses: a so called @dfn{system bus}, and a @dfn{session bus}.  On a
given machine, there is always one single system bus for miscellaneous
system-wide communication, like changing of hardware configuration.
On the other hand, the session bus is always related to a single
user's session.

Every client application, which is connected to a bus, registers under
a @dfn{unique name} at the bus.  This name is used for identifying the
client application.  Such a unique name starts always with a colon,
and looks like @samp{:1.42}.

Additionally, a client application can register itself to a so called
@dfn{known name}, which is a series of identifiers separated by dots,
94
as in @samp{org.gnu.Emacs}.  If several applications register to the
Michael Albinus's avatar
Michael Albinus committed
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
same known name, these registrations are queued, and only the first
application which has registered for the known name is reachable via
this name.  If this application disconnects from the bus, the next
queued unique name becomes the owner of this known name.

An application can install one or several objects under its name.
Such objects are identified by an @dfn{object path}, which looks
similar to paths in a filesystem.  An example of such an object path
could be @samp{/org/gnu/Emacs/}.

Applications might send a request to an object, that means sending a
message with some data as input parameters, and receiving a message
from that object with the result of this message, the output
parameters.  Such a request is called @dfn{method} in D-Bus.

The other form of communication are @dfn{signals}.  The underlying
message is emitted from an object and will be received by all other
applications which have registered for such a signal.

All methods and signals an object supports are called @dfn{interface}
of the object.  Interfaces are specified under a hierarchical name in
D-Bus; an object can support several interfaces.  Such an interface
name could be @samp{org.gnu.Emacs.TextEditor} or
@samp{org.gnu.Emacs.FileManager}.


@node Inspection
122
@chapter Inspection of D-Bus services.
Michael Albinus's avatar
Michael Albinus committed
123 124
@cindex inspection

125
@menu
126
* Version::                     Determining the D-Bus version.
127 128 129 130 131 132 133 134 135
* Bus names::                   Discovering D-Bus names.
* Introspection::               Knowing the details of D-Bus services.
* Nodes and Interfaces::        Detecting object paths and interfaces.
* Methods and Signal::          Applying the functionality.
* Properties and Annotations::  What else to know about interfaces.
* Arguments and Signatures::    The final details.
@end menu


136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
@node Version
@section D-Bus version.

D-Bus has evolved over the years.  New features have been added with
new D-Bus versions.  There are two variables, which allow to determine
the used D-Bus version.

@defvar dbus-compiled-version
This variable, a string, determines the version of D-Bus Emacs is
compiled against.  If it cannot be determined the value is @code{nil}.
@end defvar

@defvar dbus-runtime-version
The other D-Bus version to be checked is the version of D-Bus Emacs
runs with.  This string can be different from @code{dbus-compiled-version}.
It is also @code{nil}, if it cannot be determined at runtime.
@end defvar


155 156 157
@node Bus names
@section Bus names.

Michael Albinus's avatar
Michael Albinus committed
158 159 160 161
There are several basic functions which inspect the buses for
registered names.  Internally they use the basic interface
@samp{org.freedesktop.DBus}, which is supported by all objects of a bus.

162 163 164 165 166 167 168 169
@defun dbus-list-activatable-names &optional bus
This function returns the D-Bus service names, which can be activated
for @var{bus}.  It must be either the symbol @code{:system} (the
default) or the symbol @code{:session}.  An activatable service is
described in a service registration file.  Under GNU/Linux, such files
are located at @file{/usr/share/dbus-1/system-services/} (for the
@code{:system} bus) or @file{/usr/share/dbus-1/services/}.  An
activatable service is not necessarily registered at @var{bus} at already.
Michael Albinus's avatar
Michael Albinus committed
170 171

The result is a list of strings, which is @code{nil} when there are no
172 173 174 175 176 177 178
activatable service names at all.  Example:

@lisp
;; Check, whether the document viewer can be accessed via D-Bus.
(member "org.gnome.evince.Daemon"
        (dbus-list-activatable-names :session))
@end lisp
Michael Albinus's avatar
Michael Albinus committed
179 180 181 182 183 184 185 186 187 188 189 190 191 192
@end defun

@defun dbus-list-names bus
All service names, which are registered at D-Bus @var{bus}, are
returned.  The result is a list of strings, which is @code{nil} when
there are no registered service names at all.  Well known names are
strings like @samp{org.freedesktop.DBus}.  Names starting with
@samp{:} are unique names for services.

@var{bus} must be either the symbol @code{:system} or the symbol
@code{:session}.
@end defun

@defun dbus-list-known-names bus
193
Retrieves all registered services which correspond to a known name in @var{bus}.
Michael Albinus's avatar
Michael Albinus committed
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
A service has a known name if it doesn't start with @samp{:}.  The
result is a list of strings, which is @code{nil} when there are no
known names at all.

@var{bus} must be either the symbol @code{:system} or the symbol
@code{:session}.
@end defun

@defun dbus-list-queued-owners bus service
For a given service, registered at D-Bus @var{bus} under the name
@var{service}, all queued unique names are returned.  The result is a
list of strings, or @code{nil} when there are no queued names for
@var{service} at all.

@var{bus} must be either the symbol @code{:system} or the symbol
@code{:session}.  @var{service} must be a known service name as
string.
@end defun

@defun dbus-get-name-owner bus service
For a given service, registered at D-Bus @var{bus} under the name
215 216 217
@var{service}, the unique name of the name owner is returned.  The
result is a string, or @code{nil} when there exist no name owner of
@var{service}.
Michael Albinus's avatar
Michael Albinus committed
218 219 220 221 222 223

@var{bus} must be either the symbol @code{:system} or the symbol
@code{:session}.  @var{service} must be a known service name as
string.
@end defun

224
@defun dbus-ping bus service &optional timeout
225
Check whether the service name @var{service} is registered at D-Bus
226 227
@var{bus}.  @var{service} might not have been started yet, it is
autostarted if possible.  The result is either @code{t} or @code{nil}.
228 229

@var{bus} must be either the symbol @code{:system} or the symbol
230 231 232
@code{:session}.  @var{service} must be a string.  @var{timeout}, a
nonnegative integer, specifies the maximum number of milliseconds
@code{dbus-ping} must return.  The default value is 25,000.  Example:
233 234 235 236 237

@lisp
(message
   "%s screensaver on board."
   (cond
238 239
     ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome")
     ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE")
240 241
     (t "No")))
@end lisp
242 243 244 245 246 247 248

If it shall be checked whether @var{service} is already running
without autostarting it, one shall apply

@lisp
(member service (dbus-list-known-names bus))
@end lisp
249 250
@end defun

Michael Albinus's avatar
Michael Albinus committed
251 252 253 254 255 256 257 258
@defun dbus-get-unique-name bus
The unique name, under which Emacs is registered at D-Bus @var{bus},
is returned as string.

@var{bus} must be either the symbol @code{:system} or the symbol
@code{:session}.
@end defun

259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360

@node Introspection
@section Knowing the details of D-Bus services.

D-Bus services publish their interfaces.  This can be retrieved and
analyzed during runtime, in order to understand the used
implementation.

The resulting introspection data are in XML format.  The root
introspection element is always a @code{node} element.  It might have
a @code{name} attribute, which denotes the (absolute) object path an
interface is introspected.

The root @code{node} element may have @code{node} and @code{interface}
children.  A child @code{node} element must have a @code{name}
attribute, this case it is the relative object path to the root
@code{node} element.

An @code{interface} element has just one attribute, @code{name}, which
is the full name of that interface.  The default interface
@samp{org.freedesktop.DBus.Introspectable} is always present.  Example:

@example
<node name="/org/bluez">
  <interface name="org.freedesktop.DBus.Introspectable">
    @dots{}
  </interface>
  <interface name="org.bluez.Manager">
    @dots{}
  </interface>
  <interface name="org.bluez.Database">
    @dots{}
  </interface>
  <interface name="org.bluez.Security">
    @dots{}
  </interface>
  <node name="service_audio"/>
  <node name="service_input"/>
  <node name="service_network"/>
  <node name="service_serial"/>
</node>
@end example

Children of an @code{interface} element can be @code{method},
@code{signal} and @code{property} elements.  A @code{method} element
stands for a D-Bus method of the surrounding interface.  The element
itself has a @code{name} attribute, showing the method name.  Children
elements @code{arg} stand for the arguments of a method.  Example:

@example
<method name="ResolveHostName">
  <arg name="interface" type="i" direction="in"/>
  <arg name="protocol" type="i" direction="in"/>
  <arg name="name" type="s" direction="in"/>
  <arg name="aprotocol" type="i" direction="in"/>
  <arg name="flags" type="u" direction="in"/>
  <arg name="interface" type="i" direction="out"/>
  <arg name="protocol" type="i" direction="out"/>
  <arg name="name" type="s" direction="out"/>
  <arg name="aprotocol" type="i" direction="out"/>
  <arg name="address" type="s" direction="out"/>
  <arg name="flags" type="u" direction="out"/>
</method>
@end example

@code{arg} elements can have the attributes @code{name}, @code{type}
and @code{direction}.  The @code{name} attribute is optional.  The
@code{type} attribute stands for the @dfn{signature} of the argument
in D-Bus.  For a discussion of D-Bus types and their Lisp
representation see @ref{Type Conversion}.@footnote{D-Bus signatures
are explained in the D-Bus specification
@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.}
The @code{direction} attribute of an @code{arg} element can be only
@samp{in} or @samp{out}; in case it is omitted, it defaults to
@samp{in}.

A @code{signal} element of an @code{interface} has a similar
structure.  The @code{direction} attribute of an @code{arg} child
element can be only @samp{out} here; which is also the default value.
Example:

@example
<signal name="StateChanged">
  <arg name="state" type="i"/>
  <arg name="error" type="s"/>
</signal>
@end example

A @code{property} element has no @code{arg} child
element.  It just has the attributes @code{name}, @code{type} and
@code{access}, which are all mandatory.  The @code{access} attribute
allows the values @samp{readwrite}, @samp{read}, and @samp{write}.
Example:

@example
<property name="Status" type="u" direction="read"/>
@end example

@code{annotation} elements can be children of @code{interface},
@code{method}, @code{signal}, and @code{property} elements.  Unlike
properties, which can change their values during lifetime of a D-Bus
object, annotations are static.  Often they are used for code
Paul Eggert's avatar
Paul Eggert committed
361
generators of D-Bus language bindings.  Example:
362 363 364 365 366 367 368 369

@example
<annotation name="de.berlios.Pinot.GetStatistics" value="pinotDBus"/>
@end example

Annotations have just @code{name} and @code{value} attributes, both
must be strings.

Michael Albinus's avatar
Michael Albinus committed
370
@defun dbus-introspect bus service path
371 372
This function returns all interfaces and sub-nodes of @var{service},
registered at object path @var{path} at bus @var{bus}.
Michael Albinus's avatar
Michael Albinus committed
373 374 375 376 377

@var{bus} must be either the symbol @code{:system} or the symbol
@code{:session}.  @var{service} must be a known service name, and
@var{path} must be a valid object path.  The last two parameters are
strings.  The result, the introspection data, is a string in XML
378
format.  Example:
Michael Albinus's avatar
Michael Albinus committed
379

380
@lisp
Michael Albinus's avatar
Michael Albinus committed
381 382 383 384
(dbus-introspect
  :system "org.freedesktop.Hal"
  "/org/freedesktop/Hal/devices/computer")

385
@result{} "<!DOCTYPE node PUBLIC
386 387
    "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
    "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
388
    <node>
389 390 391
      <interface name="org.freedesktop.Hal.Device">
        <method name="GetAllProperties">
          <arg name="properties" direction="out" type="a@{sv@}"/>
392
        </method>
393
        @dots{}
394 395 396
        <signal name="PropertyModified">
          <arg name="num_updates" type="i"/>
          <arg name="updates" type="a(sbb)"/>
397 398
        </signal>
      </interface>
399
      @dots{}
400
    </node>"
401
@end lisp
Michael Albinus's avatar
Michael Albinus committed
402

403 404 405
This example informs us, that the service @samp{org.freedesktop.Hal}
at object path @samp{/org/freedesktop/Hal/devices/computer} offers the
interface @samp{org.freedesktop.Hal.Device} (and 2 other interfaces
Michael Albinus's avatar
Michael Albinus committed
406
not documented here).  This interface contains the method
407
@samp{GetAllProperties}, which needs no input parameters, but returns
Michael Albinus's avatar
Michael Albinus committed
408 409 410 411 412
as output parameter an array of dictionary entries (key-value pairs).
Every dictionary entry has a string as key, and a variant as value.

The interface offers also a signal, which returns 2 parameters: an
integer, and an array consisting of elements which are a struct of a
413
string and 2 boolean values.@footnote{ The interfaces of the service
414
@samp{org.freedesktop.Hal} are described in
415 416
@c Previous link is gone.  Since HAL is now obsolete, this URL
@c (unchanged in ~ 4 years) feels like it might go too...
417 418
@uref{http://people.freedesktop.org/~dkukawka/hal-spec-git/hal-spec.html#interfaces,
the HAL specification}.}
Michael Albinus's avatar
Michael Albinus committed
419 420
@end defun

421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465
@defun dbus-introspect-xml bus service path
This function has the same intention as function
@code{dbus-introspect}.  The returned value is a parsed XML tree,
which can be used for further analysis.  Example:

@lisp
(dbus-introspect-xml
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main")

@result{} (node ((name . "/org/freedesktop/xesam/searcher/main"))
     (interface ((name . "org.freedesktop.xesam.Search"))
       (method ((name . "GetHitData"))
         (arg ((name . "search") (type . "s") (direction . "in")))
         (arg ((name . "hit_ids") (type . "au") (direction . "in")))
         (arg ((name . "fields") (type . "as") (direction . "in")))
         (arg ((name . "hit_data") (type . "aav") (direction . "out")))
       )
       @dots{}
       (signal ((name . "HitsAdded"))
         (arg ((name . "search") (type . "s")))
         (arg ((name . "count") (type . "u")))
       )
     )
     @dots{}
   )
@end lisp
@end defun

@defun dbus-introspect-get-attribute object attribute
It returns the @var{attribute} value of a D-Bus introspection
@var{object}.  @var{object} can be every subtree of a parsed XML tree
as retrieved with @code{dbus-introspect-xml}.  @var{attribute} must be
a string according to the attribute names in the D-Bus specification.
Example:

@lisp
(dbus-introspect-get-attribute
  (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends"
    "/org/freedesktop/SystemToolsBackends/UsersConfig")
  "name")

@result{} "/org/freedesktop/SystemToolsBackends/UsersConfig"
@end lisp

466 467
If @var{object} has no @var{attribute}, the function returns
@code{nil}.
468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584
@end defun


@node Nodes and Interfaces
@section Detecting object paths and interfaces.

The first elements, to be introspected for a D-Bus object, are further
object paths and interfaces.

@defun dbus-introspect-get-node-names bus service path
All node names of @var{service} in D-Bus @var{bus} at object path
@var{path} are returned as list of strings.  Example:

@lisp
(dbus-introspect-get-node-names
  :session "org.gnome.seahorse" "/org/gnome/seahorse")

@result{} ("crypto" "keys")
@end lisp

The node names stand for further object paths of the D-Bus
@var{service}, relative to @var{path}.  In the example,
@samp{/org/gnome/seahorse/crypto} and @samp{/org/gnome/seahorse/keys}
are also object paths of the D-Bus service @samp{org.gnome.seahorse}.
@end defun

@defun dbus-introspect-get-all-nodes bus service path
This function returns all node names of @var{service} in D-Bus
@var{bus} at object path @var{path}.  It returns a list of strings
with all object paths of @var{service}, starting at @var{path}.
Example:

@lisp
(dbus-introspect-get-all-nodes :session "org.gnome.seahorse" "/")

@result{} ("/" "/org" "/org/gnome" "/org/gnome/seahorse"
    "/org/gnome/seahorse/crypto"
    "/org/gnome/seahorse/keys"
    "/org/gnome/seahorse/keys/openpgp"
    "/org/gnome/seahorse/keys/openpgp/local"
    "/org/gnome/seahorse/keys/openssh"
    "/org/gnome/seahorse/keys/openssh/local")
@end lisp
@end defun

@defun dbus-introspect-get-interface-names bus service path
There will be returned a list strings of all interface names of
@var{service} in D-Bus @var{bus} at object path @var{path}.  This list
will contain the default interface @samp{org.freedesktop.DBus.Introspectable}.

Another default interface is @samp{org.freedesktop.DBus.Properties}.
If present, @code{interface} elements can also have @code{property}
children.  Example:

@lisp
(dbus-introspect-get-interface-names
  :system "org.freedesktop.Hal"
  "/org/freedesktop/Hal/devices/computer")

@result{} ("org.freedesktop.DBus.Introspectable"
    "org.freedesktop.Hal.Device"
    "org.freedesktop.Hal.Device.SystemPowerManagement"
    "org.freedesktop.Hal.Device.CPUFreq")
@end lisp
@end defun

@defun dbus-introspect-get-interface bus service path interface
Return @var{interface} of @var{service} in D-Bus @var{bus} at object
path @var{path}.  The return value is an XML element.  @var{interface}
must be a string, element of the list returned by
@code{dbus-introspect-get-interface-names}.  Example:

@lisp
(dbus-introspect-get-interface
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main"
  "org.freedesktop.xesam.Search")

@result{} (interface ((name . "org.freedesktop.xesam.Search"))
     (method ((name . "GetHitData"))
       (arg ((name . "search") (type . "s") (direction . "in")))
       (arg ((name . "hit_ids") (type . "au") (direction . "in")))
       (arg ((name . "fields") (type . "as") (direction . "in")))
       (arg ((name . "hit_data") (type . "aav") (direction . "out")))
     )
     @dots{}
     (signal ((name . "HitsAdded"))
       (arg ((name . "search") (type . "s")))
       (arg ((name . "count") (type . "u")))
     )
   )
@end lisp
@end defun

@noindent
With these functions, it is possible to retrieve all introspection
data from a running system:

@lisp
(with-current-buffer (switch-to-buffer "*introspect*")
  (erase-buffer)
  (dolist (service (dbus-list-known-names :session))
    (dolist (path (dbus-introspect-get-all-nodes :session service "/"))
      ;; We want to introspect only elements, which have more than
      ;; the default interface "org.freedesktop.DBus.Introspectable".
      (when (delete
             "org.freedesktop.DBus.Introspectable"
             (dbus-introspect-get-interface-names :session service path))
        (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path)
                (dbus-introspect :session service path))
        (redisplay t)))))
@end lisp


@node Methods and Signal
@section Applying the functionality.

Paul Eggert's avatar
Paul Eggert committed
585
Methods and signals are the communication means to D-Bus.  The
586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668
following functions return their specifications.

@defun dbus-introspect-get-method-names bus service path interface
Return a list of strings of all method names of @var{interface} of
@var{service} in D-Bus @var{bus} at object path @var{path}.  Example:

@lisp
(dbus-introspect-get-method-names
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main"
  "org.freedesktop.xesam.Search")

@result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession"
    "CloseSession" "GetHitData" "SetProperty" "NewSearch"
    "GetProperty" "CloseSearch")
@end lisp
@end defun

@defun dbus-introspect-get-method bus service path interface method
This function returns @var{method} of @var{interface} as XML element.
It must be located at @var{service} in D-Bus @var{bus} at object path
@var{path}.  @var{method} must be a string, element of the list
returned by @code{dbus-introspect-get-method-names}.  Example:

@lisp
(dbus-introspect-get-method
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main"
  "org.freedesktop.xesam.Search" "GetHitData")

@result{} (method ((name . "GetHitData"))
     (arg ((name . "search") (type . "s") (direction . "in")))
     (arg ((name . "hit_ids") (type . "au") (direction . "in")))
     (arg ((name . "fields") (type . "as") (direction . "in")))
     (arg ((name . "hit_data") (type . "aav") (direction . "out")))
   )
@end lisp
@end defun

@defun dbus-introspect-get-signal-names bus service path interface
Return a list of strings of all signal names of @var{interface} of
@var{service} in D-Bus @var{bus} at object path @var{path}.  Example:

@lisp
(dbus-introspect-get-signal-names
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main"
  "org.freedesktop.xesam.Search")

@result{} ("StateChanged" "SearchDone" "HitsModified"
    "HitsRemoved" "HitsAdded")
@end lisp
@end defun

@defun dbus-introspect-get-signal bus service path interface signal
This function returns @var{signal} of @var{interface} as XML element.
It must be located at @var{service} in D-Bus @var{bus} at object path
@var{path}.  @var{signal} must be a string, element of the list
returned by @code{dbus-introspect-get-signal-names}.  Example:

@lisp
(dbus-introspect-get-signal
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main"
  "org.freedesktop.xesam.Search" "HitsAdded")

@result{} (signal ((name . "HitsAdded"))
     (arg ((name . "search") (type . "s")))
     (arg ((name . "count") (type . "u")))
   )
@end lisp
@end defun


@node Properties and Annotations
@section What else to know about interfaces.

Interfaces can have properties.  These can be exposed via the
@samp{org.freedesktop.DBus.Properties} interface@footnote{See
@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}.
That is, properties can be retrieved and changed during lifetime of an
element.

669 670 671 672 673 674
A generalized interface is
@samp{org.freedesktop.DBus.Objectmanager}@footnote{See
@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager}},
which returns objects, their interfaces and properties for a given
service in just one call.

675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723
Annotations, on the other hand, are static values for an element.
Often, they are used to instruct generators, how to generate code from
the interface for a given language binding.

@defun dbus-introspect-get-property-names bus service path interface
Return a list of strings with all property names of @var{interface} of
@var{service} in D-Bus @var{bus} at object path @var{path}.  Example:

@lisp
(dbus-introspect-get-property-names
  :session "org.kde.kded" "/modules/networkstatus"
  "org.kde.Solid.Networking.Client")

@result{} ("Status")
@end lisp

If an interface declares properties, the corresponding element supports
also the @samp{org.freedesktop.DBus.Properties} interface.
@end defun

@defun dbus-introspect-get-property bus service path interface property
This function returns @var{property} of @var{interface} as XML element.
It must be located at @var{service} in D-Bus @var{bus} at object path
@var{path}.  @var{property} must be a string, element of the list
returned by @code{dbus-introspect-get-property-names}.

A @var{property} value can be retrieved by the function
@code{dbus-introspect-get-attribute}.  Example:

@lisp
(dbus-introspect-get-property
  :session "org.kde.kded" "/modules/networkstatus"
  "org.kde.Solid.Networking.Client" "Status")

@result{} (property ((access . "read") (type . "u") (name . "Status")))

(dbus-introspect-get-attribute
  (dbus-introspect-get-property
    :session "org.kde.kded" "/modules/networkstatus"
    "org.kde.Solid.Networking.Client" "Status")
  "access")

@result{} "read"
@end lisp
@end defun

@defun dbus-get-property bus service path interface property
This function returns the value of @var{property} of @var{interface}.
It will be checked at @var{bus}, @var{service}, @var{path}.  The
724
result can be any valid D-Bus value, or @code{nil} if there is no
725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769
@var{property}.  Example:

@lisp
(dbus-get-property
  :session "org.kde.kded" "/modules/networkstatus"
  "org.kde.Solid.Networking.Client" "Status")

@result{} 4
@end lisp
@end defun

@defun dbus-set-property bus service path interface property value
Set value of @var{property} of @var{interface} to @var{value}.  It
will be checked at @var{bus}, @var{service}, @var{path}.  When the
value has been set successful, the result is @var{value}.  Otherwise,
@code{nil} is returned.  Example:

@lisp
(dbus-set-property
  :session "org.kde.kaccess" "/MainApplication"
  "com.trolltech.Qt.QApplication" "doubleClickInterval" 500)

@result{} 500
@end lisp
@end defun

@defun dbus-get-all-properties bus service path interface
This function returns all properties of @var{interface}.  It will be
checked at @var{bus}, @var{service}, @var{path}.  The result is a list
of cons.  Every cons contains the name of the property, and its value.
If there are no properties, @code{nil} is returned.  Example:

@lisp
(dbus-get-all-properties
  :session "org.kde.kaccess" "/MainApplication"
  "com.trolltech.Qt.QApplication")

@result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500)
    ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3)
    ("globalStrut" 0 0) ("startDragTime" . 500)
    ("startDragDistance" . 4) ("quitOnLastWindowClosed" . t)
    ("styleSheet" . ""))
@end lisp
@end defun

770
@defun dbus-get-all-managed-objects bus service path
771
This function returns all objects at @var{bus}, @var{service},
772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824
@var{path}, and the children of @var{path}.  The result is a list of
objects.  Every object is a cons of an existing path name, and the
list of available interface objects.  An interface object is another
cons, which car is the interface name, and the cdr is the list of
properties as returned by @code{dbus-get-all-properties} for that path
and interface. Example:

@lisp
(dbus-get-all-managed-objects
  :session "org.gnome.SettingsDaemon" "/")

@result{} (("/org/gnome/SettingsDaemon/MediaKeys"
     ("org.gnome.SettingsDaemon.MediaKeys")
     ("org.freedesktop.DBus.Peer")
     ("org.freedesktop.DBus.Introspectable")
     ("org.freedesktop.DBus.Properties")
     ("org.freedesktop.DBus.ObjectManager"))
    ("/org/gnome/SettingsDaemon/Power"
     ("org.gnome.SettingsDaemon.Power.Keyboard")
     ("org.gnome.SettingsDaemon.Power.Screen")
     ("org.gnome.SettingsDaemon.Power"
      ("Icon" . ". GThemedIcon battery-full-charged-symbolic ")
      ("Tooltip" . "Laptop battery is charged"))
     ("org.freedesktop.DBus.Peer")
     ("org.freedesktop.DBus.Introspectable")
     ("org.freedesktop.DBus.Properties")
     ("org.freedesktop.DBus.ObjectManager"))
    @dots{})
@end lisp

If possible, @samp{org.freedesktop.DBus.ObjectManager.GetManagedObjects}
is used for retrieving the information.  Otherwise, the information
is collected via @samp{org.freedesktop.DBus.Introspectable.Introspect}
and @samp{org.freedesktop.DBus.Properties.GetAll}, which is slow.

An overview of all existing object paths, their interfaces and
properties could be retrieved by the following code:

@lisp
(with-current-buffer (switch-to-buffer "*objectmanager*")
  (erase-buffer)
  (let (result)
    (dolist (service (dbus-list-known-names :session) result)
      (message "%s" service)
      (add-to-list
       'result
       (cons service
             (dbus-get-all-managed-objects :session service "/"))))
    (insert (message "%s" (pp result)))
    (redisplay t)))
@end lisp
@end defun

825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946
@defun dbus-introspect-get-annotation-names bus service path interface &optional name
Return a list of all annotation names as list of strings.  If
@var{name} is @code{nil}, the annotations are children of
@var{interface}, otherwise @var{name} must be a @code{method},
@code{signal}, or @code{property} XML element, where the annotations
belong to.  Example:

@lisp
(dbus-introspect-get-annotation-names
  :session "de.berlios.Pinot" "/de/berlios/Pinot"
  "de.berlios.Pinot" "GetStatistics")

@result{} ("de.berlios.Pinot.GetStatistics")
@end lisp

Default annotation names@footnote{See
@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format}}
are

@table @samp
@item org.freedesktop.DBus.Deprecated
Whether or not the entity is deprecated; defaults to @code{nil}

@item org.freedesktop.DBus.GLib.CSymbol
The C symbol; may be used for @code{methods} and @code{interfaces}

@item org.freedesktop.DBus.Method.NoReply
If set, don't expect a reply to the @code{method} call; defaults to @code{nil}
@end table
@end defun

@defun dbus-introspect-get-annotation bus service path interface name annotation
Return annotation @var{ANNOTATION} as XML object.  If @var{name} is
@code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise
@var{name} must be the name of a @code{method}, @code{signal}, or
@code{property} XML element, where the @var{ANNOTATION} belongs to.

An attribute value can be retrieved by
@code{dbus-introspect-get-attribute}.  Example:

@lisp
(dbus-introspect-get-annotation
  :session "de.berlios.Pinot" "/de/berlios/Pinot"
  "de.berlios.Pinot" "GetStatistics"
  "de.berlios.Pinot.GetStatistics")

@result{} (annotation ((name . "de.berlios.Pinot.GetStatistics")
                (value . "pinotDBus")))

(dbus-introspect-get-attribute
  (dbus-introspect-get-annotation
    :session "de.berlios.Pinot" "/de/berlios/Pinot"
    "de.berlios.Pinot" "GetStatistics"
    "de.berlios.Pinot.GetStatistics")
  "value")

@result{} "pinotDBus"
@end lisp
@end defun


@node Arguments and Signatures
@section The final details.

Methods and signals have arguments.  They are described in the
@code{arg} XML elements.

@defun dbus-introspect-get-argument-names bus service path interface name
Return a list of all argument names as list of strings.  @var{name}
must be a @code{method} or @code{signal} XML element.  Example:

@lisp
(dbus-introspect-get-argument-names
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main"
  "org.freedesktop.xesam.Search" "GetHitData")

@result{} ("search" "hit_ids" "fields" "hit_data")
@end lisp

Argument names are optional; the function can return @code{nil}
therefore, even if the method or signal has arguments.
@end defun

@defun dbus-introspect-get-argument bus service path interface name arg
Return argument @var{ARG} as XML object.  @var{name}
must be a @code{method} or @code{signal} XML element.  Example:

@lisp
(dbus-introspect-get-argument
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main"
  "org.freedesktop.xesam.Search" "GetHitData" "search")

@result{} (arg ((name . "search") (type . "s") (direction . "in")))
@end lisp
@end defun

@defun dbus-introspect-get-signature bus service path interface name &optional direction
Return signature of a @code{method} or @code{signal}, represented by
@var{name}, as string.

If @var{name} is a @code{method}, @var{direction} can be either
@samp{in} or @samp{out}.  If @var{direction} is @code{nil}, @samp{in}
is assumed.

If @var{name} is a @code{signal}, and @var{direction} is
non-@code{nil}, @var{direction} must be @samp{out}.  Example:

@lisp
(dbus-introspect-get-signature
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main"
  "org.freedesktop.xesam.Search" "GetHitData" "in")

@result{} "sauas"

(dbus-introspect-get-signature
  :session "org.freedesktop.xesam.searcher"
  "/org/freedesktop/xesam/searcher/main"
  "org.freedesktop.xesam.Search" "HitsAdded")

947
@result{} "su"
948 949 950
@end lisp
@end defun

Michael Albinus's avatar
Michael Albinus committed
951 952 953 954 955 956 957 958 959

@node Type Conversion
@chapter Mapping Lisp types and D-Bus types.
@cindex type conversion

D-Bus method calls and signals accept usually several arguments as
parameters, either as input parameter, or as output parameter.  Every
argument belongs to a D-Bus type.

960
Such arguments must be mapped between the value encoded as a D-Bus
Michael Albinus's avatar
Michael Albinus committed
961 962 963 964 965 966 967 968
type, and the corresponding type of Lisp objects.  The mapping is
applied Lisp object @expansion{} D-Bus type for input parameters, and
D-Bus type @expansion{} Lisp object for output parameters.


@section Input parameters.

Input parameters for D-Bus methods and signals occur as arguments of a
969
Lisp function call.  The following mapping to D-Bus types is
Michael Albinus's avatar
Michael Albinus committed
970 971 972
applied, when the corresponding D-Bus message is created:

@example
973
@multitable {negative integer} {@expansion{}} {DBUS_TYPE_BOOLEAN}
Michael Albinus's avatar
Michael Albinus committed
974 975 976
@item Lisp type               @tab              @tab D-Bus type
@item
@item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN
977 978
@item natural number          @tab @expansion{} @tab DBUS_TYPE_UINT32
@item negative integer        @tab @expansion{} @tab DBUS_TYPE_INT32
Michael Albinus's avatar
Michael Albinus committed
979 980
@item float                   @tab @expansion{} @tab DBUS_TYPE_DOUBLE
@item string                  @tab @expansion{} @tab DBUS_TYPE_STRING
981
@item list                    @tab @expansion{} @tab DBUS_TYPE_ARRAY
Michael Albinus's avatar
Michael Albinus committed
982 983 984
@end multitable
@end example

985
Other Lisp objects, like symbols or hash tables, are not accepted as
986
input parameters.
987 988

If it is necessary to use another D-Bus type, a corresponding type
989
symbol can be prepended to the corresponding Lisp object.  Basic D-Bus
990 991 992
types are represented by the type symbols @code{:byte},
@code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32},
@code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double},
993 994
@code{:string}, @code{:object-path}, @code{:signature} and
@code{:unix-fd}.
995

Michael Albinus's avatar
Michael Albinus committed
996
@noindent
997 998 999
Example:

@lisp
1000
(dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING})
1001 1002 1003 1004 1005
@end lisp

is equivalent to

@lisp
1006
(dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING})
1007 1008 1009 1010 1011
@end lisp

but different to

@lisp
1012
(dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING})
1013 1014
@end lisp

1015 1016 1017 1018 1019
The value for a byte D-Bus type can be any integer in the range 0
through 255.  If a character is used as argument, modifiers
represented outside this range are stripped of.  For example,
@code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to
@code{:byte ?\C-x} or @code{:byte ?\M-\C-x}.
1020

1021 1022 1023 1024
Signed and unsigned integer D-Bus types expect a corresponding integer
value.  If the value does not fit Emacs's integer range, it is also
possible to use an equivalent floating point number.

1025 1026
A D-Bus compound type is always represented as a list.  The @sc{car}
of this list can be the type symbol @code{:array}, @code{:variant},
1027 1028
@code{:struct} or @code{:dict-entry}, which would result in a
corresponding D-Bus container.  @code{:array} is optional, because
1029
this is the default compound D-Bus type for a list.
1030 1031 1032 1033 1034

The objects being elements of the list are checked according to the
D-Bus compound type rules.

@itemize
1035 1036 1037
@item An array must contain only elements of the same D-Bus type.  It
can be empty.

1038
@item A variant must contain only one single element.
1039

1040
@item A dictionary entry must be element of an array, and it must
1041 1042 1043
contain only a key-value pair of two elements, with a basic D-Bus type
key.

1044 1045 1046
@item There is no restriction for structs.
@end itemize

1047 1048 1049 1050
If an empty array needs an element D-Bus type other than string, it
can contain exactly one element of D-Bus type @code{:signature}.  The
value of this element (a string) is used as the signature of the
elements of this array.  Example:
1051 1052

@lisp
1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065
(dbus-call-method
  :session "org.freedesktop.Notifications"
  "/org/freedesktop/Notifications"
  "org.freedesktop.Notifications" "Notify"
  "GNU Emacs"                 ;; Application name.
  0                           ;; No replacement of other notifications.
  ""                          ;; No icon.
  "Notification summary"      ;; Summary.
  (format                     ;; Body.
    "This is a test notification, raised from %s" (emacs-version))
  '(:array)                   ;; No actions (empty array of strings).
  '(:array :signature "@{sv@}") ;; No hints
                              ;; (empty array of dictionary entries).
1066
  :int32 -1)                 ;; Default timeout.
1067 1068

@result{} 3
1069
@end lisp
Michael Albinus's avatar
Michael Albinus committed
1070

1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101
@defun dbus-string-to-byte-array string
Sometimes, D-Bus methods require as input parameter an array of bytes,
instead of a string.  If it is guaranteed, that @var{string} is an
UTF8 string, this function performs the conversion.  Example:

@lisp
(dbus-string-to-byte-array "/etc/hosts")

@result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47
           :byte 104 :byte 111 :byte 115 :byte 116 :byte 115)
@end lisp
@end defun

@defun dbus-escape-as-identifier string
Escape an arbitrary @var{string} so it follows the rules for a C
identifier.  The escaped string can be used as object path component,
interface element component, bus name component or member name in
D-Bus.

The escaping consists of replacing all non-alphanumerics, and the
first character if it's a digit, with an underscore and two
lower-case hex digits.  As a special case, "" is escaped to
"_".  Example:

@lisp
(dbus-escape-as-identifier "0123abc_xyz\x01\xff")

@result{} "_30123abc_5fxyz_01_ff"
@end lisp
@end defun

Michael Albinus's avatar
Michael Albinus committed
1102 1103 1104 1105

@section Output parameters.

Output parameters of D-Bus methods and signals are mapped to Lisp
1106
objects.
Michael Albinus's avatar
Michael Albinus committed
1107 1108

@example
1109
@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float}
Michael Albinus's avatar
Michael Albinus committed
1110 1111 1112
@item D-Bus type            @tab              @tab Lisp type
@item
@item DBUS_TYPE_BOOLEAN     @tab @expansion{} @tab @code{t} or @code{nil}
1113 1114 1115 1116
@item DBUS_TYPE_BYTE        @tab @expansion{} @tab natural number
@item DBUS_TYPE_UINT16      @tab @expansion{} @tab natural number
@item DBUS_TYPE_INT16       @tab @expansion{} @tab integer
@item DBUS_TYPE_UINT32      @tab @expansion{} @tab natural number or float
1117
@item DBUS_TYPE_UNIX_FD     @tab @expansion{} @tab natural number or float
1118 1119 1120
@item DBUS_TYPE_INT32       @tab @expansion{} @tab integer or float
@item DBUS_TYPE_UINT64      @tab @expansion{} @tab natural number or float
@item DBUS_TYPE_INT64       @tab @expansion{} @tab integer or float
Michael Albinus's avatar
Michael Albinus committed
1121 1122 1123
@item DBUS_TYPE_DOUBLE      @tab @expansion{} @tab float
@item DBUS_TYPE_STRING      @tab @expansion{} @tab string
@item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
1124
@item DBUS_TYPE_SIGNATURE   @tab @expansion{} @tab string
Michael Albinus's avatar
Michael Albinus committed
1125 1126 1127 1128 1129 1130 1131
@item DBUS_TYPE_ARRAY       @tab @expansion{} @tab list
@item DBUS_TYPE_VARIANT     @tab @expansion{} @tab list
@item DBUS_TYPE_STRUCT      @tab @expansion{} @tab list
@item DBUS_TYPE_DICT_ENTRY  @tab @expansion{} @tab list
@end multitable
@end example

1132
A float object in case of @code{DBUS_TYPE_UINT32},
1133 1134 1135
@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64},
@code{DBUS_TYPE_INT64} and @code{DBUS_TYPE_UNIX_FD} is returned, when
the C value exceeds the Emacs number size range.
1136

Michael Albinus's avatar
Michael Albinus committed
1137 1138 1139 1140 1141 1142 1143 1144 1145
The resulting list of the last 4 D-Bus compound types contains as
elements the elements of the D-Bus container, mapped according to the
same rules.

The signal @code{PropertyModified}, discussed as example in
@ref{Inspection}, would offer as Lisp data the following object
(@var{BOOL} stands here for either @code{nil} or @code{t}):

@lisp
1146
(@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
Michael Albinus's avatar
Michael Albinus committed
1147 1148
@end lisp

1149
@defun dbus-byte-array-to-string byte-array &optional multibyte
1150 1151
If a D-Bus method or signal returns an array of bytes, which are known
to represent an UTF8 string, this function converts @var{byte-array}
1152 1153
to the corresponding string.  The string is unibyte encoded, unless
@var{multibyte} is non-@code{nil}.  Example:
1154 1155 1156 1157 1158 1159 1160 1161 1162

@lisp
(dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115))

@result{} "/etc/hosts"
@end lisp
@end defun

@defun dbus-unescape-from-identifier string
1163 1164
Retrieve the original string from the encoded @var{string} as unibyte
string.  @var{string} must have been encoded with
1165 1166 1167 1168 1169
@code{dbus-escape-as-identifier}.  Example:

@lisp
(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")

1170
@result{} "0123abc_xyz\x01\xff"
1171
@end lisp
1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186

If the original string used in @code{dbus-escape-as-identifier} is a
multibyte string, it cannot be expected that this function returns
that string:

@lisp
(string-equal
  (dbus-unescape-from-identifier
    (dbus-escape-as-identifier "Grüß Göttin"))
  "Grüß Göttin")

@result{} nil
@end lisp


1187 1188
@end defun

Michael Albinus's avatar
Michael Albinus committed
1189 1190 1191 1192 1193 1194 1195

@node Synchronous Methods
@chapter Calling methods in a blocking way.
@cindex method calls, synchronous
@cindex synchronous method calls

Methods can be called synchronously (@dfn{blocking}) or asynchronously
1196
(@dfn{non-blocking}).
Michael Albinus's avatar
Michael Albinus committed
1197 1198 1199 1200 1201 1202

At D-Bus level, a method call consist of two messages: one message
which carries the input parameters to the object owning the method to
be called, and a reply message returning the resulting output
parameters from the object.

1203
@defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args
Michael Albinus's avatar
Michael Albinus committed
1204 1205 1206 1207 1208 1209 1210
This function calls @var{method} on the D-Bus @var{bus}.  @var{bus} is
either the symbol @code{:system} or the symbol @code{:session}.

@var{service} is the D-Bus service name to be used.  @var{path} is the
D-Bus object path, @var{service} is registered at.  @var{interface} is
an interface offered by @var{service}.  It must provide @var{method}.

1211
If the parameter @code{:timeout} is given, the following integer
1212
@var{timeout} specifies the maximum number of milliseconds the method
1213
call must return.  The default value is 25,000.  If the method call
1214 1215 1216
doesn't return in time, a D-Bus error is raised (@pxref{Errors and
Events}).

Michael Albinus's avatar
Michael Albinus committed
1217 1218 1219 1220 1221 1222 1223 1224
All other arguments args are passed to @var{method} as arguments.
They are converted into D-Bus types as described in @ref{Type
Conversion}.

The function returns the resulting values of @var{method} as a list of
Lisp objects, according to the type conversion rules described in
@ref{Type Conversion}.  Example:

1225
@lisp
Michael Albinus's avatar
Michael Albinus committed
1226
(dbus-call-method
1227 1228
  :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
  "org.gnome.seahorse.Keys" "GetKeyField"
Michael Albinus's avatar
Michael Albinus committed
1229 1230 1231
  "openpgp:657984B8C7A966DD" "simple-name")

@result{} (t ("Philip R. Zimmermann"))
1232
@end lisp
Michael Albinus's avatar
Michael Albinus committed
1233 1234 1235 1236 1237

If the result of the method call is just one value, the converted Lisp
object is returned instead of a list containing this single Lisp
object.  Example:

1238
@lisp
Michael Albinus's avatar
Michael Albinus committed
1239
(dbus-call-method
1240 1241 1242
  :system "org.freedesktop.Hal"
  "/org/freedesktop/Hal/devices/computer"
  "org.freedesktop.Hal.Device" "GetPropertyString"
Michael Albinus's avatar
Michael Albinus committed
1243 1244 1245
  "system.kernel.machine")

@result{} "i686"
1246
@end lisp
Michael Albinus's avatar
Michael Albinus committed
1247 1248 1249 1250 1251 1252 1253 1254 1255 1256

With the @code{dbus-introspect} function it is possible to explore the
interfaces of @samp{org.freedesktop.Hal} service. It offers the
interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
path @samp{/org/freedesktop/Hal/Manager} as well as the interface
@samp{org.freedesktop.Hal.Device} for all objects prefixed with the
path @samp{/org/freedesktop/Hal/devices}.  With the methods
@samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
emulate the @code{lshal} command on GNU/Linux systems:

1257
@lisp
Michael Albinus's avatar
Michael Albinus committed
1258 1259
(dolist (device
          (dbus-call-method
1260
            :system "org.freedesktop.Hal"
Michael Albinus's avatar
Michael Albinus committed
1261
            "/org/freedesktop/Hal/Manager"
1262
            "org.freedesktop.Hal.Manager" "GetAllDevices"))
Michael Albinus's avatar
Michael Albinus committed
1263 1264 1265
  (message "\nudi = %s" device)
  (dolist (properties
            (dbus-call-method
1266 1267
              :system "org.freedesktop.Hal" device
              "org.freedesktop.Hal.Device" "GetAllProperties"))
Michael Albinus's avatar
Michael Albinus committed
1268 1269 1270
    (message "  %s = %S"
             (car properties) (or (caar (cdr properties)) ""))))

1271
@print{} "udi = /org/freedesktop/Hal/devices/computer
1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285
      info.addons = (\"hald-addon-acpi\")
      info.bus = \"unknown\"
      info.product = \"Computer\"
      info.subsystem = \"unknown\"
      info.udi = \"/org/freedesktop/Hal/devices/computer\"
      linux.sysfs_path_device = \"(none)\"
      power_management.acpi.linux.version = \"20051216\"
      power_management.can_suspend_to_disk = t
      power_management.can_suspend_to_ram = \"\"
      power_management.type = \"acpi\"
      smbios.bios.release_date = \"11/07/2001\"
      system.chassis.manufacturer = \"COMPAL\"
      system.chassis.type = \"Notebook\"
      system.firmware.release_date = \"03/19/2005\"
1286
      @dots{}"
1287
@end lisp
Michael Albinus's avatar
Michael Albinus committed
1288 1289
@end defun

1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305

@node Asynchronous Methods
@chapter Calling methods non-blocking.
@cindex method calls, asynchronous
@cindex asynchronous method calls

@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args
This function calls @var{method} on the D-Bus @var{bus}
asynchronously.  @var{bus} is either the symbol @code{:system} or the
symbol @code{:session}.

@var{service} is the D-Bus service name to be used.  @var{path} is the
D-Bus object path, @var{service} is registered at.  @var{interface} is
an interface offered by @var{service}.  It must provide @var{method}.

@var{handler} is a Lisp function, which is called when the
1306 1307
corresponding return message has arrived.  If @var{handler} is
@code{nil}, no return message will be expected.
1308 1309 1310

If the parameter @code{:timeout} is given, the following integer
@var{timeout} specifies the maximum number of milliseconds a reply
1311
message must arrive.  The default value is 25,000.  If there is no
1312 1313 1314 1315 1316 1317 1318
reply message in time, a D-Bus error is raised (@pxref{Errors and
Events}).

All other arguments args are passed to @var{method} as arguments.
They are converted into D-Bus types as described in @ref{Type
Conversion}.

1319
If @var{handler} is a Lisp function, the function returns a key into
1320
the hash table @code{dbus-registered-objects-table}.  The
1321 1322
corresponding entry in the hash table is removed, when the return
message has been arrived, and @var{handler} is called.  Example:
1323 1324 1325 1326 1327 1328 1329 1330

@lisp
(dbus-call-method-asynchronously
  :system "org.freedesktop.Hal"
  "/org/freedesktop/Hal/devices/computer"
  "org.freedesktop.Hal.Device" "GetPropertyString" 'message
  "system.kernel.machine")

1331
@result{} (:serial :system 2)
1332 1333 1334 1335 1336

@print{} i686
@end lisp
@end defun

Michael Albinus's avatar
Michael Albinus committed
1337

1338 1339 1340 1341 1342
@node Receiving Method Calls
@chapter Offering own methods.
@cindex method calls, returning
@cindex returning method calls

1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409
In order to register methods on the D-Bus, Emacs has to request a well
known name on the D-Bus under which it will be available for other
clients.  Names on the D-Bus can be registered and unregistered using
the following functions:

@defun dbus-register-service bus service &rest flags
Register the known name @var{service} on D-Bus @var{bus}.

@var{bus} is either the symbol @code{:system} or the symbol
@code{:session}.

@var{service} is the service name to be registered on the D-Bus.  It
must be a known name.

@var{flags} is a subset of the following keywords:

@itemize
@item @code{:allow-replacement}: Allow another service to become the primary
owner if requested.

@item @code{:replace-existing}: Request to replace the current primary owner.

@item @code{:do-not-queue}: If we can not become the primary owner do not
place us in the queue.
@end itemize

One of the following keywords is returned:

@itemize

@item @code{:primary-owner}: We have become the primary owner of the name
@var{service}.

@item @code{:in-queue}: We could not become the primary owner and
have been placed in the queue.

@item @code{:exists}: We already are in the queue.

@item @code{:already-owner}: We already are the primary
owner.
@end itemize
@end defun

@defun dbus-unregister-service bus service
Unregister all objects from D-Bus @var{bus}, registered by Emacs for
@var{service}.

@var{bus} is either the symbol @code{:system} or the symbol
@code{:session}.

@var{service} is the D-Bus service name of the D-Bus.  It must be a
known name.  Emacs releases its association to @var{service} from
D-Bus.

One of the following keywords is returned:

@itemize
@item @code{:released}: We successfully released the name @var{service}.
@item @code{:non-existent}: The name @var{service} does not exist on the bus.
@item @code{:not-owner}: We are not an owner of the name @var{service}.
@end itemize
@end defun

When a name has been chosen, Emacs can offer own methods, which can be
called by other applications.  These methods could be an
implementation of an interface of a well known service, like
@samp{org.freedesktop.TextEditor}.
1410 1411

It could be also an implementation of an own interface.  In this case,
1412
the service name must be @samp{org.gnu.Emacs}.  The object path shall
1413
begin with @samp{/org/gnu/Emacs/@strong{Application}}, and the
1414
interface name shall be @code{org.gnu.Emacs.@strong{Application}}.
1415
@samp{@strong{Application}} is the name of the application which
1416 1417
provides the interface.

1418
@deffn Constant dbus-service-emacs
1419
The well known service name @samp{org.gnu.Emacs} of Emacs.
1420 1421 1422
@end deffn

@deffn Constant dbus-path-emacs
1423 1424 1425 1426 1427
The object path namespace @samp{/org/gnu/Emacs} used by Emacs.
@end deffn

@deffn Constant dbus-interface-emacs
The interface namespace @code{org.gnu.Emacs} used by Emacs.
1428 1429
@end deffn

1430
@defun dbus-register-method bus service path interface method handler dont-register-service
1431 1432 1433 1434 1435 1436 1437
With this function, an application registers @var{method} on the D-Bus
@var{bus}.

@var{bus} is either the symbol @code{:system} or the symbol
@code{:session}.

@var{service} is the D-Bus service name of the D-Bus object
1438 1439
@var{method} is registered for.  It must be a known name (See
discussion of @var{dont-register-service} below).
1440

1441 1442
@var{path} is the D-Bus object path @var{service} is registered (See
discussion of @var{dont-register-service} below).
1443 1444 1445 1446

@var{interface} is the interface offered by @var{service}.  It must
provide @var{method}.

1447 1448 1449 1450 1451 1452 1453 1454 1455 1456
@var{handler} is a Lisp function to be called when a @var{method} call
is received.  It must accept as arguments the input arguments of
@var{method}.  @var{handler} should return a list, whose elements are
to be used as arguments for the reply message of @var{method}.  This
list can be composed like the input parameters in @ref{Type
Conversion}.

If @var{handler} wants to return just one Lisp object and it is not a
cons cell, @var{handler} can return this object directly, instead of
returning a list containing the object.
1457

1458 1459 1460
In case @var{handler} shall return a reply message with an empty
argument list, @var{handler} must return the symbol @code{:ignore}.

1461 1462 1463 1464
When @var{dont-register-service} is non-@code{nil}, the known name
@var{service} is not registered.  This means that other D-Bus clients
have no way of noticing the newly registered method.  When interfaces
are constructed incrementally by adding single methods or properties
1465
at a time, @var{dont-register-service} can be used to prevent other
1466 1467
clients from discovering the still incomplete interface.

1468
The default D-Bus timeout when waiting for a message reply is 25
1469 1470
seconds.  This value could be even smaller, depending on the calling
client.  Therefore, @var{handler} shall not last longer than
1471 1472
absolutely necessary.

1473
@code{dbus-register-method} returns a Lisp object, which can be used
1474 1475 1476
as argument in @code{dbus-unregister-object} for removing the
registration for @var{method}.  Example:

1477
@lisp
1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491
(defun my-dbus-method-handler (filename)
  (let (result)
    (if (find-file filename)
        (setq result '(:boolean t))
      (setq result '(:boolean nil)))
    result))

@result{} my-dbus-method-handler

(dbus-register-method
  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
  "org.freedesktop.TextEditor" "OpenFile"
  'my-dbus-method-handler)

1492
@result{} ((:method :session "org.freedesktop.TextEditor" "OpenFile")
1493
    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
1494
     my-dbus-method-handler))
1495
@end lisp