1---
2title: GVariant D-Bus Message Serialization
3category: Interfaces
4layout: default
5SPDX-License-Identifier: LGPL-2.1-or-later
6---
7
8# GVariant D-Bus Message Serialization
9
10We stay as close to the original dbus1 framing as possible, but make
11certain changes to adapt for GVariant. dbus1 has the following
12framing:
13
14    1. A fixed header of "yyyyuu"
15    2. Additional header fields of "a(yv)"
16    3. Padding with NUL bytes to pad up to next 8byte boundary
17    4. The body
18
19Note that the body is not padded at the end, the complete message
20hence might have a non-aligned size. Reading multiple messages at once
21will hence result in possibly unaligned messages in memory.
22
23The header consists of the following:
24
25    y  Endianness, 'l' or 'B'
26    y  Message Type
27    y  Flags
28    y  Protocol version, '1'
29    u  Length of the body, i.e. the length of part 4 above
30    u  32bit Serial number
31
32    = 12 bytes
33
34This header is then followed by the fields array, whose first value is
35a 32bit array size.
36
37When using GVariant we keep the basic structure in place, only
38slightly alter the header, and define protocol version '2'. The new
39header:
40
41    y  Endianness, 'l' or 'B'
42    y  Message Type
43    y  Flags
44    y  Protocol version, '2'
45    u  Reserved, must be 0
46    t  64bit Cookie
47
48    = 16 bytes
49
50This is then followed by the GVariant fields array ("a{tv}"), and
51finally the actual body as variant (v). Putting this altogether a
52packet on dbus2 hence qualifies as a fully compliant GVariant
53structure of (yyyyuta{tv}v).
54
55For details on gvariant, see:
56
57https://people.gnome.org/~desrt/gvariant-serialisation.pdf
58
59Regarding the framing of dbus2, also see:
60
61https://wiki.gnome.org/Projects/GLib/GDBus/Version2
62
63The first four bytes of the header are defined the same way for dbus1
64and dbus2. The first bytes contain the endianness field and the
65protocol version, so that the remainder of the message can be safely
66made sense of just by looking at the first 32bit.
67
68Note that the length of the body is no longer included in the header
69on dbus2! In fact, the message size must be known in advance, from the
70underlying transport in order to parse dbus2 messages, while it is
71directly included in dbus1 message headers. This change of semantics
72is an effect of GVariant's basic design.
73
74The serial number has been renamed cookie and has been extended from
7532bit to 64bit. It is recommended to avoid the higher 32bit of the
76cookie field though, to simplify compatibility with dbus1 peers. Note
77that not only the cookie/serial field in the fixed header, but also
78the reply_cookie/reply_serial additional header field has been
79increased from 32bit to 64bit, too!
80
81The header field identifiers have been extended from 8bit to
8264bit. This has been done to simplify things, and has no effect
83on the serialization size, as due to alignment for each 8bit
84header field identifier 56 bits of padding had to be added.
85
86Note that the header size changed, due to these changes. However,
87consider that on dbus1 the beginning of the fields array contains the
8832bit array size (since that is how arrays are encoded on dbus1),
89thus, if one considers that size part of the header, instead of the
90array, the size of the header on dbus1 and dbus2 stays identical, at
9116 bytes.
92
93              0               4               8               12              16
94      Common: | E | T | F | V | ...
95
96       dbus1: |  (as above)   | Body Length   | Serial        | Fields Length | Fields array ...
97
98    gvariant: |  (as above)   | Reserved      | Cookie                        | Fields array ...
99
100And that's already it.
101
102Note: To simplify parsing, valid dbus2 messages must include the entire
103      fixed header and additional header fields in a single non-memfd
104      message part. Also, the signature string of the body variant all the
105      way to the end of the message must be in a single non-memfd part
106      too. The parts for this extended header and footer can be the same
107      one, and can also continue any amount of additional body bytes.
108
109Note: The GVariant "MAYBE" type is not supported, so that messages can
110      be fully converted forth and back between dbus1 and gvariant
111      representations.
112