[glib] GVariant: say that serialized form needs an out-of-band length

[Simon McVittie <smcv src gnome org>]

commit 7db1baf59078c667ac1ae43f839b2b1866e65a87
Author: Simon McVittie <simon mcvittie collabora co uk>
Date:   Fri Sep 19 15:05:04 2014 +0100

    GVariant: say that serialized form needs an out-of-band length
    
    This confused me for a while, because it isn't the same as D-Bus.
    Like GVariant, the D-Bus serialization needs an out-of-band
    endianness and type indicator, but unlike GVariant, serialized
    D-Bus objects encapsulate their own length (often by starting with
    a byte-count). This does come at some redundancy cost, so I can see
    why the more efficient GVariant format does this the way it does;
    but it's a difference between D-Bus and GVariant that seems worth
    calling out.
    
    It's also relevant for the designers of file or message-framing
    formats: with D-Bus serialization it would be feasible to say "the file
    starts with a little-endian D-Bus variant, followed by...",
    but in GVariant you wouldn't be able to deserialize the variant
    unless you either assume that it extends to end-of-file, or have
    an explicit length.
    
    Bug: https://bugzilla.gnome.org/show_bug.cgi?id=736975
    Reviewed-by: Ryan Lortie

 glib/gvariant.c |   12 +++++++-----
 1 files changed, 7 insertions(+), 5 deletions(-)
---
diff --git a/glib/gvariant.c b/glib/gvariant.c
index aca9579..52b40a7 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -71,10 +71,11 @@
  * in the gio library, for those.)
  *
  * For space-efficiency, the #GVariant serialisation format does not
- * automatically include the variant's type or endianness, which must
- * either be implied from context (such as knowledge that a particular
- * file format always contains a little-endian %G_VARIANT_TYPE_VARIANT)
- * or supplied out-of-band (for instance, a type and/or endianness
+ * automatically include the variant's length, type or endianness,
+ * which must either be implied from context (such as knowledge that a
+ * particular file format always contains a little-endian
+ * %G_VARIANT_TYPE_VARIANT which occupies the whole length of the file)
+ * or supplied out-of-band (for instance, a length, type and/or endianness
  * indicator could be placed at the beginning of a file, network message
  * or network stream).
  *
@@ -107,7 +108,8 @@
  *
  * This is the memory that is used for storing GVariant data in
  * serialised form.  This is what would be sent over the network or
- * what would end up on disk.
+ * what would end up on disk, not counting any indicator of the
+ * endianness, or of the length or type of the top-level variant.
  *
  * The amount of memory required to store a boolean is 1 byte. 16,
  * 32 and 64 bit integers and double precision floating point numbers