[thirdparty/systemd.git] / src / libsystemd / sd-bus / GVARIANT-SERIALIZATION

How we use GVariant for serializing D-Bus messages
--------------------------------------------------

We stay as close to the original dbus1 framing as possible. dbus1 has
the following framing:

    1. A fixed header of "yyyyuu"
    2. Additional header fields of "a(yv)"
    3. Padding with NUL bytes to pad up to next 8byte boundary
    4. The body

Note that the body is not padded at the end, the complete message
hence might have a non-aligned size. Reading multiple messages at once
will hence result in possibly unaligned messages in memory.

The header consists of the following:

    y  Endianness, 'l' or 'B'
    y  Message Type
    y  Flags
    y  Protocol version, '1'
    u  Length of the body, i.e. the length of part 4 above
    u  Serial number

    = 12 bytes

When using GVariant we keep the basic structure in place, only
slightly extend the header, and define protocol version '2'. The new
header:

    y  Endianness, 'l' or 'B'
    y  Message Type
    y  Flags
    y  Protocol version, '2'
    u  Length of the body, i.e. the length of part 4 above
    u  Serial number
    u  Length of the additional header fields array

    = 16 bytes

This has the nice benefit that the beginning of the additional header
fields array is aligned to an 8 byte boundary. Also, in dbus1
marshalling arrays start with a length value of 32bit, which means in
both dbus1 and gvariant marshallings the size of the header fields
array will be at the same location between bytes 12 and 16. To
visualize that:

              0               4               8               12              16
      Common: | E | T | F | V | Body Length   | Serial        | Fields Length |

       dbus1: |                            ... (as above) ... | Fields array ...

    gvariant: |                            ... (as above) ... | Fields Length | Fields array ...

And that's already it.

Note: on kdbus only native endian messages marshalled in gvariant may
      be sent. If a client receives a message in non-native endianness
      or in dbus1 marshalling it shall ignore the message.

Note: The GVariant "MAYBE" type is not supported, so that messages can
      be fully converted forth and back between dbus1 and gvariant
      representations.
Commit	Line	Data
c1b9d935 LP	1	How we use GVariant for serializing D-Bus messages
	2	--------------------------------------------------
	3
954871d8 KS	4	We stay as close to the original dbus1 framing as possible. dbus1 has
954871d8 KS	5	the following framing:
c1b9d935 LP	6
	7	1. A fixed header of "yyyyuu"
	8	2. Additional header fields of "a(yv)"
	9	3. Padding with NUL bytes to pad up to next 8byte boundary
	10	4. The body
	11
	12	Note that the body is not padded at the end, the complete message
	13	hence might have a non-aligned size. Reading multiple messages at once
	14	will hence result in possibly unaligned messages in memory.
	15
	16	The header consists of the following:
	17
	18	y Endianness, 'l' or 'B'
	19	y Message Type
	20	y Flags
	21	y Protocol version, '1'
	22	u Length of the body, i.e. the length of part 4 above
954871d8	23	u Serial number
c1b9d935 LP	24
	25	= 12 bytes
	26
	27	When using GVariant we keep the basic structure in place, only
954871d8	28	slightly extend the header, and define protocol version '2'. The new
c1b9d935 LP	29	header:
	30
	31	y Endianness, 'l' or 'B'
	32	y Message Type
	33	y Flags
	34	y Protocol version, '2'
954871d8 KS	35	u Length of the body, i.e. the length of part 4 above
	36	u Serial number
	37	u Length of the additional header fields array
c1b9d935 LP	38
	39	= 16 bytes
	40
954871d8 KS	41	This has the nice benefit that the beginning of the additional header
	42	fields array is aligned to an 8 byte boundary. Also, in dbus1
	43	marshalling arrays start with a length value of 32bit, which means in
	44	both dbus1 and gvariant marshallings the size of the header fields
	45	array will be at the same location between bytes 12 and 16. To
	46	visualize that:
c1b9d935 LP	47
c1b9d935 LP	48	0 4 8 12 16
954871d8	49	Common: \| E \| T \| F \| V \| Body Length \| Serial \| Fields Length \|
c1b9d935	50
954871d8	51	dbus1: \| ... (as above) ... \| Fields array ...
c1b9d935	52
954871d8	53	gvariant: \| ... (as above) ... \| Fields Length \| Fields array ...
c1b9d935 LP	54
	55	And that's already it.
	56
	57	Note: on kdbus only native endian messages marshalled in gvariant may
	58	be sent. If a client receives a message in non-native endianness
	59	or in dbus1 marshalling it shall ignore the message.
6647dc66 LP	60
	61	Note: The GVariant "MAYBE" type is not supported, so that messages can
	62	be fully converted forth and back between dbus1 and gvariant
	63	representations.