Next: Calling methods in a blocking way., Previous: Inspection of D-Bus services., Up: D-Bus integration in Emacs [Contents][Index]
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
Next: Calling methods in a blocking way., Previous: Inspection of D-Bus services., Up: D-Bus integration in Emacs [Contents][Index]