D-Bus integration in Emacs

1 An overview of D-Bus

D-Bus is an inter-process communication mechanism for applications residing on the same host. The communication is based on 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 system bus, and a 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 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 ‘:1.42’.

Additionally, a client application can register itself to a so called known name, which is a series of identifiers separated by dots, as in ‘org.gnu.Emacs’. If several applications register to the 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 object path, which looks similar to paths in a filesystem. An example of such an object path could be ‘/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 method in D-Bus.

The other form of communication are 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 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 ‘org.gnu.Emacs.TextEditor’ or ‘org.gnu.Emacs.FileManager’.

2 Inspection of D-Bus services.

• D-Bus version.
• Bus names.
• Knowing the details of D-Bus services.
• Detecting object paths and interfaces.
• Applying the functionality.
• What else to know about interfaces.
• The final details.

<node name="/org/bluez">
  <interface name="org.freedesktop.DBus.Introspectable">
    …
  </interface>
  <interface name="org.bluez.Manager">
    …
  </interface>
  <interface name="org.bluez.Database">
    …
  </interface>
  <interface name="org.bluez.Security">
    …
  </interface>
  <node name="service_audio"/>
  <node name="service_input"/>
  <node name="service_network"/>
  <node name="service_serial"/>
</node>

<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>

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

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

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

(progn
  (pop-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 (format "\nservice: \"%s\" path: \"%s\"\n" service path)
                (dbus-introspect :session service path))
        (redisplay t)))))

3 Mapping Lisp types and D-Bus types.

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.

Such arguments must be mapped between the value encoded as a D-Bus type, and the corresponding type of Lisp objects. The mapping is applied Lisp object → D-Bus type for input parameters, and D-Bus type → Lisp object for output parameters.

• Input parameters.
• Output parameters.

Lisp type

D-Bus type

t and nil

→

DBUS_TYPE_BOOLEAN

natural number

→

DBUS_TYPE_UINT32

negative integer

→

DBUS_TYPE_INT32

float

→

DBUS_TYPE_DOUBLE

string

→

DBUS_TYPE_STRING

list

→

DBUS_TYPE_ARRAY

(dbus-call-method … nat-number string)

(dbus-call-method … :uint32 nat-number :string string)

(dbus-call-method … :int32 nat-number :signature string)

(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\n%S" (emacs-version))
 '(:array)                     ; No actions (empty array of strings).
 '(:array :signature "{sv}")   ; No hints
                               ; (empty array of dictionary entries).
 :int32 -1)                    ; Default timeout.

⇒ 3

D-Bus type

Lisp type

DBUS_TYPE_BOOLEAN

→

t or nil

DBUS_TYPE_BYTE

→

natural number

DBUS_TYPE_UINT16

→

natural number

DBUS_TYPE_INT16

→

integer

DBUS_TYPE_UINT32

→

natural number

DBUS_TYPE_UNIX_FD

→

natural number

DBUS_TYPE_INT32

→

integer

DBUS_TYPE_UINT64

→

natural number

DBUS_TYPE_INT64

→

integer

DBUS_TYPE_DOUBLE

→

float

DBUS_TYPE_STRING

→

string

DBUS_TYPE_OBJECT_PATH

→

string

DBUS_TYPE_SIGNATURE

→

string

DBUS_TYPE_ARRAY

→

list

DBUS_TYPE_VARIANT

→

list

DBUS_TYPE_STRUCT

→

list

DBUS_TYPE_DICT_ENTRY

→

list

(integer ((string bool bool) (string bool bool) …))

4 Calling methods in a blocking way.

Methods can be called synchronously (blocking) or asynchronously (non-blocking).

At the 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.

Function: dbus-call-method bus service path interface method &optional :timeout timeout &rest args ¶

This function calls method on the D-Bus bus. bus is either the keyword :system or the keyword :session.

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

If the parameter :timeout is given, the following integer timeout specifies the maximum number of milliseconds before the method call must return. The default value is 25,000. If the method call doesn’t return in time, a D-Bus error is raised (see Errors and events.).

The remaining arguments args are passed to method as arguments. They are converted into D-Bus types as described in Mapping Lisp types and D-Bus types..

The function returns the resulting values of method as a list of Lisp objects, according to the type conversion rules described in Mapping Lisp types and D-Bus types.. Example:

(dbus-call-method
 :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
 "org.gnome.seahorse.Keys" "GetKeyField"
 "openpgp:657984B8C7A966DD" "simple-name")

⇒ (t ("Philip R. Zimmermann"))

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:

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

⇒ "i686"

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

(dolist (device
         (dbus-call-method
          :system "org.freedesktop.Hal"
          "/org/freedesktop/Hal/Manager"
          "org.freedesktop.Hal.Manager" "GetAllDevices"))
  (message "\nudi = %s" device)
  (dolist (properties
           (dbus-call-method
            :system "org.freedesktop.Hal" device
            "org.freedesktop.Hal.Device" "GetAllProperties"))
    (message "  %s = %S"
             (car properties) (or (caadr properties) ""))))

-| "udi = /org/freedesktop/Hal/devices/computer
      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\"
      …"

5 Calling methods non-blocking.

Function: dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args ¶

This function calls method on the D-Bus bus asynchronously. bus is either the keyword :system or the keyword :session.

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

handler is a Lisp function, which is called when the corresponding return message arrives. If handler is nil, no return message will be expected.

If the parameter :timeout is given, the following integer timeout specifies the maximum number of milliseconds before a reply message must arrive. The default value is 25,000. If there is no reply message in time, a D-Bus error is raised (see Errors and events.).

The remaining arguments args are passed to method as arguments. They are converted into D-Bus types as described in Mapping Lisp types and D-Bus types..

If handler is a Lisp function, the function returns a key into the hash table dbus-registered-objects-table. The corresponding entry in the hash table is removed, when the return message arrives, and handler is called. Example:

(dbus-call-method-asynchronously
 :system "org.freedesktop.Hal"
 "/org/freedesktop/Hal/devices/computer"
 "org.freedesktop.Hal.Device" "GetPropertyString"
 (lambda (msg) (message "%s" msg))
 "system.kernel.machine")

-| i686

⇒ (:serial :system 2)

6 Offering own services.

You can offer an own service in D-Bus, which will be visible by other D-Bus clients. See https://dbus.freedesktop.org/doc/dbus-api-design.html for a discussion of the design.

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:

Function: dbus-register-service bus service &rest flags ¶

This function registers the known name service on D-Bus bus.

bus is either the keyword :system or the keyword :session.

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

flags is a subset of the following keywords:

:allow-replacement

Allow another service to become the primary owner if requested.

:replace-existing

Request to replace the current primary owner.

:do-not-queue

If we can not become the primary owner do not place us in the queue.

One of the following keywords is returned:

:primary-owner

We have become the primary owner of the name service.

:in-queue

We could not become the primary owner and have been placed in the queue.

:exists

We already are in the queue.

:already-owner

We already are the primary owner.

Function: dbus-unregister-service bus service ¶

This function unregisters all objects from D-Bus bus, that were registered by Emacs for service.

bus is either the keyword :system or the keyword :session.

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

One of the following keywords is returned:

:released

We successfully released the name service.

:non-existent

The name service does not exist on the bus.

:not-owner

We are not an owner of the name service.

When service is not a known name but a unique name, the function returns nil.

When a name has been chosen, Emacs can offer its own methods, which can be called by other applications. These methods could be an implementation of an interface of a well known service, like ‘org.freedesktop.TextEditor’.

They could also be an implementation of its own interface. In this case, the service name must be ‘org.gnu.Emacs’. The object path shall begin with ‘/org/gnu/Emacs/application’, and the interface name shall be org.gnu.Emacs.application, where application is the name of the application which provides the interface.

Constant: dbus-service-emacs ¶

The well known service name ‘org.gnu.Emacs’ of Emacs.

Constant: dbus-path-emacs ¶

The object path namespace ‘/org/gnu/Emacs’ used by Emacs.

Constant: dbus-interface-emacs ¶

The interface namespace org.gnu.Emacs used by Emacs.

Function: dbus-register-method bus service path interface method handler dont-register-service ¶

With this function, an application registers method on the D-Bus bus.

bus is either the keyword :system or the keyword :session.

service is the D-Bus service name of the D-Bus object method is registered for. It must be a known name (see discussion of dont-register-service below).

path is the D-Bus object path service is registered (see discussion of dont-register-service below).

interface is the interface offered by service. It must provide method.

handler is a Lisp function to be called when a method call is received. It must accept as arguments the input arguments of method. handler should return a list, whose elements are to be used as arguments for the reply message of method. This list can be composed like the input parameters in Mapping Lisp types and D-Bus types..

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

If handler returns a reply message with an empty argument list, handler must return the keyword :ignore in order to distinguish it from nil (the boolean false).

If handler detects an error, it shall return the list (:error error-name error-message). error-name is a namespaced string which characterizes the error type, and error-message is a free text string. Alternatively, any Emacs signal dbus-error in handler raises a D-Bus error message with the error name ‘org.freedesktop.DBus.Error.Failed’.

When dont-register-service is non-nil, the known name 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 at a time, dont-register-service can be used to prevent other clients from discovering the still incomplete interface.

The default D-Bus timeout when waiting for a message reply is 25 seconds. This value could be even smaller, depending on the calling client. Therefore, handler should not last longer than absolutely necessary.

dbus-register-method returns a Lisp object, which can be used as argument in dbus-unregister-object for removing the registration for method. Example:

(defun my-dbus-method-handler (filename)
  (if (find-file filename)
      '(:boolean t)
    '(:boolean nil)))

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

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

If you invoke the method ‘org.freedesktop.TextEditor.OpenFile’ from another D-Bus application with a file name as parameter, the file is opened in Emacs, and the method returns either true or false, indicating the success of the method. As a test tool one could use the command line tool dbus-send in a shell:

# dbus-send --session --print-reply \
    --dest="org.freedesktop.TextEditor" \
    "/org/freedesktop/TextEditor" \
    "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts"

-| method return sender=:1.22 -> dest=:1.23 reply_serial=2
      boolean true

You can indicate an error by returning an :error list reply, or by raising the Emacs signal dbus-error. The handler above could be changed like this:

(defun my-dbus-method-handler (&rest args)
  (if (not (and (= (length args) 1) (stringp (car args))))
      (list :error
            "org.freedesktop.TextEditor.Error.InvalidArgs"
            (format "Wrong argument list: %S" args))
    (condition-case err
        (find-file (car args))
      (error (signal 'dbus-error (cdr err))))
    t))

The test then runs

# dbus-send --session --print-reply \
    --dest="org.freedesktop.TextEditor" \
    "/org/freedesktop/TextEditor" \
    "org.freedesktop.TextEditor.OpenFile" \
    string:"/etc/hosts" string:"/etc/passwd"

-| Error org.freedesktop.TextEditor.Error.InvalidArgs:
   Wrong argument list: ("/etc/hosts" "/etc/passwd")

# dbus-send --session --print-reply \
    --dest="org.freedesktop.TextEditor" \
    "/org/freedesktop/TextEditor" \
    "org.freedesktop.TextEditor.OpenFile" \
    string:"/etc/crypttab"

-| Error org.freedesktop.DBus.Error.Failed:
   D-Bus error: "File is not readable", "/etc/crypttab"

Function: dbus-register-property bus service path interface property access [type] value &optional emits-signal dont-register-service ¶

With this function, an application declares a property on the D-Bus bus.

bus is either the keyword :system or the keyword :session.

service is the D-Bus service name of the D-Bus. It must be a known name.

path is the D-Bus object path service is registered (see discussion of dont-register-service below).

interface is the name of the interface used at path, property is the name of the property of interface.

access indicates, whether the property can be changed by other services via D-Bus. It must be either the keyword :read, :write or :readwrite.

value is the initial value of the property, it can be of any valid type (See dbus-call-method, for details). value can be preceded by a type keyword.

If property already exists on path, it will be overwritten. For properties with access type :read this is the only way to change their values. Properties with access type :write or :readwrite can be changed by dbus-set-property.

The interface ‘org.freedesktop.DBus.Properties’ is added to path, including a default handler for the ‘Get’, ‘GetAll’ and ‘Set’ methods of this interface. When emits-signal is non-nil, the signal ‘PropertiesChanged’ is sent when the property is changed by dbus-set-property.

When dont-register-service is non-nil, the known name 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 at a time, dont-register-service can be used to prevent other clients from discovering the still incomplete interface.

dbus-register-property returns a Lisp object, which can be used as argument in dbus-unregister-object for removing the registration for property. Example:

(dbus-register-property
 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
 "org.freedesktop.TextEditor" "name" :read "GNU Emacs")

⇒ ((:property :session "org.freedesktop.TextEditor" "name")
    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))

(dbus-register-property
 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
 "org.freedesktop.TextEditor" "version" :readwrite emacs-version t)

⇒ ((:property :session "org.freedesktop.TextEditor" "version")
    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))

Other D-Bus applications can read the property via the default methods ‘org.freedesktop.DBus.Properties.Get’ and ‘org.freedesktop.DBus.Properties.GetAll’. Testing is also possible via the command line tool dbus-send in a shell:

# dbus-send --session --print-reply \
    --dest="org.freedesktop.TextEditor" \
    "/org/freedesktop/TextEditor" \
    "org.freedesktop.DBus.Properties.GetAll" \
    string:"org.freedesktop.TextEditor"

-| method return sender=:1.22 -> dest=:1.23 reply_serial=3
      array [
         dict entry(
            string "name"
            variant             string "GNU Emacs"
         )
         dict entry(
            string "version"
            variant             string "23.1.50.5"
         )
      ]

It is also possible to apply the dbus-get-property, dbus-get-all-properties and dbus-set-property functions (see What else to know about interfaces.).

(dbus-set-property
 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
 "org.freedesktop.TextEditor" "version" "23.1.50")

⇒ "23.1.50"

(dbus-get-property
 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
 "org.freedesktop.TextEditor" "version")

⇒ "23.1.50"

Function: dbus-unregister-object object ¶

This function unregisters object from the D-Bus. object must be the result of a preceding dbus-register-method, dbus-register-property, dbus-register-signal (see Sending and receiving signals.) or dbus-register-monitor call. It returns t if object has been unregistered, nil otherwise.

When object identifies the last method or property, which is registered for the respective service, Emacs releases its association to the service from D-Bus.

7 Sending and receiving signals.

Signals are one way messages. They carry input parameters, which are received by all objects which have registered for such a signal.

Function: dbus-send-signal bus service path interface signal &rest args ¶

This function is similar to dbus-call-method. The difference is, that there are no returning output parameters.

The function emits signal on the D-Bus bus. bus is either the keyword :system or the keyword :session. It doesn’t matter whether another object has registered for signal.

Signals can be unicast or broadcast messages. For broadcast messages, service must be nil. Otherwise, service is the D-Bus service name the signal is sent to as a unicast message.⁶ path is the D-Bus object path signal is sent from. interface is an interface available at path. It must provide signal.

The remaining arguments args are passed to signal as arguments. They are converted into D-Bus types as described in Mapping Lisp types and D-Bus types.. Example:

(dbus-send-signal
 :session nil dbus-path-emacs
 (concat dbus-interface-emacs ".FileManager") "FileModified"
 "/home/albinus/.emacs")

Function: dbus-register-signal bus service path interface signal handler &rest args ¶

With this function, an application registers for a signal on the D-Bus bus.

bus is either the keyword :system or the keyword :session.

service is the D-Bus service name used by the sending D-Bus object. It can be either a known name or the unique name of the D-Bus object sending the signal. A known name will be mapped onto the unique name of the object, owning service at registration time. When the corresponding D-Bus object disappears, signals will no longer be received.

path is the corresponding D-Bus object path that service is registered at. interface is an interface offered by service. It must provide signal.

service, path, interface and signal can be nil. This is interpreted as a wildcard for the respective argument.

handler is a Lisp function to be called when the signal is received. It must accept as arguments the output parameters signal is sending.

The remaining arguments args can be keywords or keyword string pairs.⁷ Their meaning is as follows:

:argn string

:pathn string

This stands for the nth argument of the signal. :pathn arguments can be used for object path wildcard matches as specified by D-Bus, while an :argN argument requires an exact match.

:arg-namespace string

Register for those signals, whose first argument names a service or interface within the namespace string.

:path-namespace string

Register for the object path namespace string. All signals sent from an object path, which has string as the preceding string, are matched. This requires path to be nil.

:eavesdrop

Register for unicast signals which are not directed to the D-Bus object Emacs is registered at D-Bus BUS, if the security policy of BUS allows this. Otherwise, this argument is ignored.

dbus-register-signal returns a Lisp object, which can be used as argument in dbus-unregister-object for removing the registration for signal. Example:

(defun my-dbus-signal-handler (device)
  (message "Device %s added" device))

(dbus-register-signal
 :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
 "org.freedesktop.Hal.Manager" "DeviceAdded"
 #'my-dbus-signal-handler)

⇒ ((:signal :system "org.freedesktop.Hal.Manager" "DeviceAdded")
    ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
     my-signal-handler))

As we know from the introspection data of interface ‘org.freedesktop.Hal.Manager’, the signal ‘DeviceAdded’ provides one single parameter, which is mapped into a Lisp string. The callback function my-dbus-signal-handler must therefore define a single string argument. Plugging a USB device into your machine, when registered for signal ‘DeviceAdded’, will show you which objects the GNU/Linux hal daemon adds.

Some of the match rules have been added to a later version of D-Bus. In order to test the availability of such features, you could register for a dummy signal, and check the result:

(dbus-ignore-errors
  (dbus-register-signal
   :system nil nil nil nil #'ignore :path-namespace "/invalid/path"))

⇒ nil

8 Alternative buses and environments.

Until now, we have spoken about the system and the session buses, which are the default buses to be connected to. However, it is possible to connect to any bus with a known address. This is a UNIX domain or TCP/IP socket. Everywhere, where a bus is mentioned as argument of a function (the keyword :system or the keyword :session), this address can be used instead. The connection to this bus must be initialized first.

Function: dbus-init-bus bus &optional private ¶

This function establishes the connection to D-Bus bus.

bus can be either the keyword :system or the keyword :session, or it can be a string denoting the address of the corresponding bus. For the system and session buses, this function is called when loading dbus.el, there is no need to call it again.

If Emacs was invoked when there was no D-Bus session bus available yet, you can set the environment variable DBUS_SESSION_BUS_ADDRESS once the session bus daemon is running and offering the address. Calling dbus-init-bus initializes the connection to the session bus.

(setenv "DBUS_SESSION_BUS_ADDRESS" "unix:path=/run/user/1000/bus")

⇒ "unix:path=/run/user/1000/bus"

(dbus-init-bus :session)

⇒ 2

dbus-init-bus returns the number of connections this Emacs session has established to the bus under the same unique name (see dbus-get-unique-name). It depends on the libraries Emacs is linked with, and on the environment Emacs is running. For example, if Emacs is linked with the GTK+ toolkit, and it runs in a GTK+-aware environment like GNOME, another connection might already be established.

When private is non-nil, a new connection is established instead of reusing an existing one. It results in a new unique name at the bus. This can be used, if it is necessary to distinguish from another connection used in the same Emacs process, like the one established by GTK+. If bus is the keyword :system or the keyword :session, the new private connection is identified by the keywords :system-private or :session-private, respectively.

Example: You initialize a connection to the AT-SPI bus on your host:

(setq my-bus
      (dbus-call-method
       :session "org.a11y.Bus" "/org/a11y/bus"
       "org.a11y.Bus" "GetAddress"))

⇒ "unix:abstract=/tmp/dbus-2yzWHOCdSD,guid=a490dd26625870ca1298b6e10000fd7f"

;; If Emacs is built with GTK+ support, and you run in a GTK+-enabled
;; environment (like a GNOME session), the initialization reuses the
;; connection established by GTK+'s atk bindings.
(dbus-init-bus my-bus)

⇒ 2

(dbus-get-unique-name my-bus)

⇒ ":1.19"

;; Open a new connection to the same bus.  This supersedes the
;; previous one.
(dbus-init-bus my-bus 'private)

⇒ 1

(dbus-get-unique-name my-bus)

⇒ ":1.20"

D-Bus addresses can specify a different transport. A possible address could be based on TCP/IP sockets, see next example. Which transport is supported depends on the bus daemon configuration, however.

Function: dbus-setenv bus variable value ¶

This function sets the value of the bus environment variable to value.

bus is either a Lisp keyword, :system or :session, or a string denoting the bus address. Both variable and value should be strings.

Normally, services inherit the environment of the bus daemon. This function adds to or modifies that environment when activating services.

Some bus instances, such as :system, may disable setting the environment. In such cases, or if this feature is not available in older D-Bus versions, this function signals a dbus-error.

As an example, it might be desirable to start X11 enabled services on a remote host’s bus on the same X11 server the local Emacs is running. This could be achieved by

(setq my-bus "unix:host=example.gnu.org,port=4711")

⇒ "unix:host=example.gnu.org,port=4711"

(dbus-init-bus my-bus)

⇒ 1

(dbus-setenv my-bus "DISPLAY" (getenv "DISPLAY"))

⇒ nil

9 Errors and events.

The internal actions can be traced by running in a debug mode.

Variable: dbus-debug ¶

If this variable is non-nil, D-Bus specific debug messages are raised.

Input parameters of dbus-call-method, dbus-call-method-asynchronously, dbus-send-signal, dbus-register-method, dbus-register-property and dbus-register-signal are checked for correct D-Bus types. If there is a type mismatch, the Lisp error wrong-type-argument D-Bus arg is raised.

All errors raised by D-Bus are signaled with the error symbol dbus-error. If possible, error messages from D-Bus are appended to the dbus-error.

Special Form: dbus-ignore-errors forms… ¶

This executes forms exactly like a progn, except that dbus-error errors are ignored during the forms (the macro returns nil then). These errors can be made visible when dbus-debug is set to non-nil.

Incoming D-Bus messages are handled as Emacs events, see (elisp)Misc Events. They are retrieved only, when Emacs runs in interactive mode. The generated event has this form:

(dbus-event bus type serial service destination path interface member
            handler &rest args)

bus identifies the D-Bus the message is coming from. It is either a Lisp keyword, :system, :session, :system-private or :session-private, or a string denoting the bus address.

type is the D-Bus message type which has caused the event. It can be dbus-message-type-invalid, dbus-message-type-method-call, dbus-message-type-method-return, dbus-message-type-error, or dbus-message-type-signal. serial is the serial number of the received D-Bus message, unless type is equal dbus-message-type-error.

service and path are the unique name and the object path of the D-Bus object emitting the message. destination is the D-Bus name the message is dedicated to, or nil in case the message is a broadcast signal.

interface and member denote the message which has been sent. When type is dbus-message-type-error, member is the error name.

handler is the callback function which has been registered for this message (see Sending and receiving signals.). args are the typed arguments as returned from the message. They are passed to handler without type information, when it is called during event handling in dbus-handle-event.

In order to inspect the dbus-event data, you could extend the definition of the callback function in Sending and receiving signals.:

(defun my-dbus-signal-handler (&rest args)
  (message "my-dbus-signal-handler: %S" last-input-event))

There exist convenience functions which could be called inside a callback function in order to retrieve the information from the event.

Function: dbus-event-bus-name event ¶

This function returns the bus name event is coming from. The result is either the keyword :system or the keyword :session.

Function: dbus-event-message-type event ¶

This function returns the message type of the corresponding D-Bus message. The result is a natural number.

Function: dbus-event-serial-number event ¶

This function returns the serial number of the corresponding D-Bus message. The result is a natural number.

Function: dbus-event-service-name event ¶

This function returns the unique name of the D-Bus object event is coming from.

Function: dbus-event-destination-name event ¶

This function returns the unique name of the D-Bus object event is dedicated to.

Function: dbus-event-path-name event ¶

This function returns the object path of the D-Bus object event is coming from.

Function: dbus-event-interface-name event ¶

This function returns the interface name of the D-Bus object event is coming from.

Function: dbus-event-member-name event ¶

This function returns the member name of the D-Bus object event is coming from. It is either a signal name or a method name.

Function: dbus-event-handler event ¶

This function returns the handler the D-Bus object event is applied with.

Function: dbus-event-arguments event ¶

This function returns the arguments the D-Bus object event is carrying on.

D-Bus errors are not propagated during event handling, because it is usually not desired. D-Bus errors in events can be made visible by setting the variable dbus-debug to non-nil. They can also be handled by a hook function.

Variable: dbus-event-error-functions ¶

This hook variable keeps a list of functions, which are called when a D-Bus error happens in the event handler. Every function must accept two arguments, the event and the error variable caught in condition-case by dbus-error.

Such functions can be used to adapt the error signal to be raised. Example:

(defun my-dbus-event-error-handler (event error)
  (when (string-equal (concat dbus-interface-emacs ".FileManager")
                      (dbus-event-interface-name event))
    (message "my-dbus-event-error-handler: %S %S" event error)
    (signal 'file-error (cdr error))))

(add-hook 'dbus-event-error-functions #'my-dbus-event-error-handler)

Hook functions should take into account that there might be other D-Bus applications running. They should therefore check carefully, whether a given D-Bus error is related to them.

10 Monitoring messages.

Function: dbus-register-monitor bus &optional handler &key type sender destination path interface member ¶

This function registers handler for monitoring messages on the D-Bus bus.

bus is either a Lisp keyword, :system or :session, or a string denoting the bus address.

handler is the function to be called when a D-Bus event to be monitored arrives. It is called with the args slot of the D-Bus event (see Errors and events.), which are stripped off the type keywords. If handler is nil, the default handler dbus-monitor-handler is applied. This default handler behaves similar to the dbus-monitor program.

The other arguments are keyword-value pairs. :type type defines the message type to be monitored. If given, it must be equal one of the strings ‘method_call’, ‘method_return’, ‘error’ or ‘signal’.

:sender sender and :destination destination are D-Bus names. They can be unique names, or well-known service names.

:path path is the D-Bus object to be monitored. :interface interface is the name of an interface, and :member member is either a method name, a signal name, or an error name.

dbus-register-monitor returns a Lisp object, which can be used as argument in dbus-unregister-object for removing the monitor.

The following form shows all D-Bus events on the session bus in buffer ‘*D-Bus Monitor*’:

(dbus-register-monitor :session)

And this form restricts the monitoring on D-Bus errors:

(dbus-register-monitor :session nil :type "error")

Command: dbus-monitor &optional bus ¶

This command invokes dbus-register-monitor interactively, and switches to the monitor buffer.