src/libelogind/sd-bus/GVARIANT-SERIALIZATION

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