[glib/glib-2-30] g_variant_get_data: mention what you need to know to deserialise

[Simon McVittie <smcv src gnome org>]

commit ad8457c82f1cf0715ae4040b9014285b70397aac
Author: Simon McVittie <simon mcvittie collabora co uk>
Date:   Mon Oct 3 14:20:51 2011 +0100

    g_variant_get_data: mention what you need to know to deserialise
    
    Also include a shorter version in the docs for g_variant_store, with a
    pointer to g_variant_get_data.
    
    Bug: https://bugzilla.gnome.org/show_bug.cgi?id=632049
    Signed-off-by: Simon McVittie <simon mcvittie collabora co uk>
    Reviewed-by: Ryan Lortie <desrt desrt ca>

 glib/gvariant-core.c |   14 ++++++++++++++
 1 files changed, 14 insertions(+), 0 deletions(-)
---
diff --git a/glib/gvariant-core.c b/glib/gvariant-core.c
index d37f135..a6a23b3 100644
--- a/glib/gvariant-core.c
+++ b/glib/gvariant-core.c
@@ -821,6 +821,16 @@ g_variant_get_size (GVariant *value)
  * serialisation occurs implicitly and is approximately O(n) in the size
  * of the result.
  *
+ * To deserialise the data returned by this function, in addition to the
+ * serialised data, you must know the type of the #GVariant, and (if the
+ * machine might be different) the endianness of the machine that stored
+ * it. As a result, file formats or network messages that incorporate
+ * serialised #GVariant<!---->s must include this information either
+ * implicitly (for instance "the file always contains a
+ * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or
+ * explicitly (by storing the type and/or endianness in addition to the
+ * serialised data).
+ *
  * Since: 2.24
  **/
 gconstpointer
@@ -959,6 +969,10 @@ g_variant_get_child_value (GVariant *value,
  * fully-normalised form if read from an untrusted source.  See
  * g_variant_get_normal_form() for a solution.
  *
+ * As with g_variant_get_data(), to be able to deserialise the
+ * serialised variant successfully, its type and (if the destination
+ * machine might be different) its endianness must also be available.
+ *
  * This function is approximately O(n) in the size of @data.
  *
  * Since: 2.24