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 for D-Bus methods and signals occur as arguments of a Lisp function call. The following mapping to D-Bus types is applied, when the corresponding D-Bus message is created:
Lisp type | D-Bus type | |
| → | 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 |
Other Lisp objects, like symbols or hash tables, are not accepted as input parameters.
If it is necessary to use another D-Bus type, a corresponding type
keyword can be prepended to the corresponding Lisp object. Basic
D-Bus types are represented by the type keywords :byte,
:boolean, :int16, :uint16, :int32,
:uint32, :int64, :uint64, :double,
:string, :object-path, :signature and
:unix-fd.
Example:
(dbus-call-method … nat-number string)
is equivalent to
(dbus-call-method … :uint32 nat-number :string string)
but different to
(dbus-call-method … :int32 nat-number :signature string)
The value for a D-Bus byte type can be any natural number. If the
number is larger than 255, it is truncated to the least significant
byte. For example, :byte 1025 is equal to :byte 1. If
a character is used as argument, modifiers represented outside this
range are stripped off. For example, :byte ?x is equal to
:byte ?\M-x, but it is not equal to :byte ?\C-x or
:byte ?\M-\C-x.
Signed and unsigned D-Bus integer types expect a corresponding integer value. A unix file descriptor is restricted to the values 0…9.
If typed explicitly, a non-nil boolean value like
:boolean 'symbol is handled like t or :boolean t.
A D-Bus compound type is always represented as a list. The CAR
of this list can be the type keyword :array, :variant,
:struct or :dict-entry, which would result in a
corresponding D-Bus container. :array is optional, because
this is the default compound D-Bus type for a list.
The objects being elements of the list are checked according to the D-Bus compound type rules.
If an empty array needs an element D-Bus type other than string, it
can contain exactly one element of D-Bus type :signature. The
value of this element (a string) is used as the signature of the
elements of this array. Example:
(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
Sometimes, D-Bus methods require as input parameter an array of bytes, instead of a string. If it is guaranteed, that string is a UTF-8 string, this function performs the conversion. Example:
(dbus-string-to-byte-array "/etc/hosts")
⇒ (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47
:byte 104 :byte 111 :byte 115 :byte 116 :byte 115)
This function escapes an arbitrary 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:
(dbus-escape-as-identifier "0123abc_xyz\x01\xff") ⇒ "_30123abc_5fxyz_01_ff"
Output parameters of D-Bus methods and signals are mapped to Lisp objects.
D-Bus type | Lisp type | |
DBUS_TYPE_BOOLEAN | → |
|
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 |
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 PropertyModified, discussed as an example in
Inspection of D-Bus services., would offer as Lisp data the following object
(bool stands here for either nil or t):
(integer ((string bool bool) (string bool bool) …))
If a D-Bus method or signal returns an array of bytes, which are known
to represent a UTF-8 string, this function converts byte-array
to the corresponding string. The string is unibyte encoded, unless
multibyte is non-nil. Example:
(dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115)) ⇒ "/etc/hosts"
This function retrieves the original string from the encoded
string as a unibyte string. The value of string must have
been encoded with dbus-escape-as-identifier. Example:
(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff") ⇒ "0123abc_xyz\x01\xff"
If the original string used in dbus-escape-as-identifier is a
multibyte string, it cannot be expected that this function returns
that string:
(string-equal (dbus-unescape-from-identifier (dbus-escape-as-identifier "Grüß Göttin")) "Grüß Göttin") ⇒ nil