docs: Standardize spelling of serializ*

Changes serialis* to serializ*.

Fixes: #2399

Signed-off-by: Geyslan G. Bem <geyslan@gmail.com>
This commit is contained in:
Geyslan G. Bem
2021-05-07 08:42:44 -03:00
parent 730cc864ef
commit 6b867cd474
10 changed files with 198 additions and 198 deletions

View File

@@ -136,7 +136,7 @@ the dconf database.
<term><option>get</option></term> <term><option>get</option></term>
<listitem><para> <listitem><para>
Gets the value of <replaceable>KEY</replaceable>. Gets the value of <replaceable>KEY</replaceable>.
The value is printed out as a serialised The value is printed out as a serialized
<link linkend="GVariant"><type>GVariant</type></link>. <link linkend="GVariant"><type>GVariant</type></link>.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>
@@ -175,7 +175,7 @@ Queries the description of valid values for <replaceable>KEY</replaceable>.
<term><option>set</option></term> <term><option>set</option></term>
<listitem><para> <listitem><para>
Sets the value of <replaceable>KEY</replaceable> to Sets the value of <replaceable>KEY</replaceable> to
<replaceable>VALUE</replaceable>. The value is specified as a serialised <replaceable>VALUE</replaceable>. The value is specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link>. <link linkend="GVariant"><type>GVariant</type></link>.
</para></listitem> </para></listitem>
</varlistentry> </varlistentry>

View File

@@ -263,7 +263,7 @@
<para> <para>
Used as a prefix for a GVariant type string (not a prefix for a format string, so <literal>&amp;s</literal> is Used as a prefix for a GVariant type string (not a prefix for a format string, so <literal>&amp;s</literal> is
a valid format string but <literal>&amp;@s</literal> is not). a valid format string but <literal>&amp;@s</literal> is not).
Denotes that a C pointer to serialised data Denotes that a C pointer to serialized data
should be used in place of the normal C type. See should be used in place of the normal C type. See
<link linkend='gvariant-format-strings-pointers'>Pointers</link> below. <link linkend='gvariant-format-strings-pointers'>Pointers</link> below.
</para> </para>
@@ -946,7 +946,7 @@ data = g_variant_new_parsed ("(%o, {'brightness': {'value': <%i>, 'max': <%i>}})
</para> </para>
<para> <para>
The '<code>&amp;</code>' character is used to indicate that serialised data should be directly exchanged via a The '<code>&amp;</code>' character is used to indicate that serialized data should be directly exchanged via a
pointer. pointer.
</para> </para>
<para> <para>
@@ -954,7 +954,7 @@ data = g_variant_new_parsed ("(%o, {'brightness': {'value': <%i>, 'max': <%i>}})
'<literal>&amp;o</literal>' or '<code>&amp;g</code>'). For '<literal>&amp;o</literal>' or '<code>&amp;g</code>'). For
<link linkend='g-variant-new'><function>g_variant_new()</function></link> this has absolutely no effect. The string <link linkend='g-variant-new'><function>g_variant_new()</function></link> this has absolutely no effect. The string
is collected and duplicated normally. For <link linkend='g-variant-get'><function>g_variant_get()</function></link> is collected and duplicated normally. For <link linkend='g-variant-get'><function>g_variant_get()</function></link>
it means that instead of creating a newly allocated copy of the string, a pointer to the serialised data is it means that instead of creating a newly allocated copy of the string, a pointer to the serialized data is
returned. This pointer should not be freed. Validity checks are performed to ensure that the string data will returned. This pointer should not be freed. Validity checks are performed to ensure that the string data will
always be properly nul-terminated. always be properly nul-terminated.
</para> </para>

View File

@@ -431,7 +431,7 @@ g_emblemed_icon_serialize (GIcon *icon)
icon_data = g_icon_serialize (node->data); icon_data = g_icon_serialize (node->data);
if (icon_data) if (icon_data)
{ {
/* We know how emblems serialise, so do a tweak here to /* We know how emblems serialize, so do a tweak here to
* reduce some of the variant wrapping and redundant storage * reduce some of the variant wrapping and redundant storage
* of 'emblem' over and again... * of 'emblem' over and again...
*/ */

View File

@@ -81,22 +81,22 @@ struct _GVariant
/* struct GVariant: /* struct GVariant:
* *
* There are two primary forms of GVariant instances: "serialised form" * There are two primary forms of GVariant instances: "serialized form"
* and "tree form". * and "tree form".
* *
* "serialised form": A serialised GVariant instance stores its value in * "serialized form": A serialized GVariant instance stores its value in
* the GVariant serialisation format. All * the GVariant serialization format. All
* basic-typed instances (ie: non-containers) are in * basic-typed instances (ie: non-containers) are in
* serialised format, as are some containers. * serialized format, as are some containers.
* *
* "tree form": Some containers are in "tree form". In this case, * "tree form": Some containers are in "tree form". In this case,
* instead of containing the serialised data for the * instead of containing the serialized data for the
* container, the instance contains an array of pointers to * container, the instance contains an array of pointers to
* the child values of the container (thus forming a tree). * the child values of the container (thus forming a tree).
* *
* It is possible for an instance to transition from tree form to * It is possible for an instance to transition from tree form to
* serialised form. This happens, implicitly, if the serialised data is * serialized form. This happens, implicitly, if the serialized data is
* requested (eg: via g_variant_get_data()). Serialised form instances * requested (eg: via g_variant_get_data()). Serialized form instances
* never transition into tree form. * never transition into tree form.
* *
* *
@@ -109,8 +109,8 @@ struct _GVariant
* The type_info field never changes during the life of the * The type_info field never changes during the life of the
* instance, so it can be accessed without a lock. * instance, so it can be accessed without a lock.
* *
* size: this is the size of the serialised form for the instance, if it * size: this is the size of the serialized form for the instance, if it
* is known. If the instance is in serialised form then it is, by * is known. If the instance is in serialized form then it is, by
* definition, known. If the instance is in tree form then it may * definition, known. If the instance is in tree form then it may
* be unknown (in which case it is -1). It is possible for the * be unknown (in which case it is -1). It is possible for the
* size to be known when in tree form if, for example, the user * size to be known when in tree form if, for example, the user
@@ -126,33 +126,33 @@ struct _GVariant
* that, the size field can be accessed without a lock. * that, the size field can be accessed without a lock.
* *
* contents: a union containing either the information associated with * contents: a union containing either the information associated with
* holding a value in serialised form or holding a value in * holding a value in serialized form or holding a value in
* tree form. * tree form.
* *
* .serialised: Only valid when the instance is in serialised form. * .serialised: Only valid when the instance is in serialized form.
* *
* Since an instance can never transition away from * Since an instance can never transition away from
* serialised form, once these fields are set, they will * serialized form, once these fields are set, they will
* never be changed. It is therefore valid to access * never be changed. It is therefore valid to access
* them without holding a lock. * them without holding a lock.
* *
* .bytes: the #GBytes that contains the memory pointed to by * .bytes: the #GBytes that contains the memory pointed to by
* .data, or %NULL if .data is %NULL. In the event that * .data, or %NULL if .data is %NULL. In the event that
* the instance was deserialised from another instance, * the instance was deserialized from another instance,
* then the bytes will be shared by both of them. When * then the bytes will be shared by both of them. When
* the instance is freed, this reference must be released * the instance is freed, this reference must be released
* with g_bytes_unref(). * with g_bytes_unref().
* *
* .data: the serialised data (of size 'size') of the instance. * .data: the serialized data (of size 'size') of the instance.
* This pointer should not be freed or modified in any way. * This pointer should not be freed or modified in any way.
* #GBytes is responsible for memory management. * #GBytes is responsible for memory management.
* *
* This pointer may be %NULL in two cases: * This pointer may be %NULL in two cases:
* *
* - if the serialised size of the instance is 0 * - if the serialized size of the instance is 0
* *
* - if the instance is of a fixed-sized type and was * - if the instance is of a fixed-sized type and was
* deserialised out of a corrupted container such that * deserialized out of a corrupted container such that
* the container contains too few bytes to point to the * the container contains too few bytes to point to the
* entire proper fixed-size of this instance. In this * entire proper fixed-size of this instance. In this
* case, 'size' will still be equal to the proper fixed * case, 'size' will still be equal to the proper fixed
@@ -165,12 +165,12 @@ struct _GVariant
* .tree: Only valid when the instance is in tree form. * .tree: Only valid when the instance is in tree form.
* *
* Note that accesses from other threads could result in * Note that accesses from other threads could result in
* conversion of the instance from tree form to serialised form * conversion of the instance from tree form to serialized form
* at any time. For this reason, the instance lock must always * at any time. For this reason, the instance lock must always
* be held while performing any operations on 'contents.tree'. * be held while performing any operations on 'contents.tree'.
* *
* .children: the array of the child instances of this instance. * .children: the array of the child instances of this instance.
* When the instance is freed (or converted to serialised * When the instance is freed (or converted to serialized
* form) then each child must have g_variant_unref() * form) then each child must have g_variant_unref()
* called on it and the array must be freed using * called on it and the array must be freed using
* g_free(). * g_free().
@@ -183,18 +183,18 @@ struct _GVariant
* STATE_LOCKED: the instance lock is held. This is the bit used by * STATE_LOCKED: the instance lock is held. This is the bit used by
* g_bit_lock(). * g_bit_lock().
* *
* STATE_SERIALISED: the instance is in serialised form. If this * STATE_SERIALISED: the instance is in serialized form. If this
* flag is not set then the instance is in tree * flag is not set then the instance is in tree
* form. * form.
* *
* STATE_TRUSTED: for serialised form instances, this means that the * STATE_TRUSTED: for serialized form instances, this means that the
* serialised data is known to be in normal form (ie: * serialized data is known to be in normal form (ie:
* not corrupted). * not corrupted).
* *
* For tree form instances, this means that all of the * For tree form instances, this means that all of the
* child instances in the contents.tree.children array * child instances in the contents.tree.children array
* are trusted. This means that if the container is * are trusted. This means that if the container is
* serialised then the resulting data will be in * serialized then the resulting data will be in
* normal form. * normal form.
* *
* If this flag is unset it does not imply that the * If this flag is unset it does not imply that the
@@ -209,7 +209,7 @@ struct _GVariant
* depth: the depth of the GVariant in a hierarchy of nested containers, * depth: the depth of the GVariant in a hierarchy of nested containers,
* increasing with the level of nesting. The top-most GVariant has depth * increasing with the level of nesting. The top-most GVariant has depth
* zero. This is used to avoid recursing too deeply and overflowing the * zero. This is used to avoid recursing too deeply and overflowing the
* stack when handling deeply nested untrusted serialised GVariants. * stack when handling deeply nested untrusted serialized GVariants.
*/ */
#define STATE_LOCKED 1 #define STATE_LOCKED 1
#define STATE_SERIALISED 2 #define STATE_SERIALISED 2
@@ -249,7 +249,7 @@ g_variant_unlock (GVariant *value)
* @value and frees the array itself. @value must be in tree form. * @value and frees the array itself. @value must be in tree form.
* *
* This is done when freeing a tree-form instance or converting it to * This is done when freeing a tree-form instance or converting it to
* serialised form. * serialized form.
* *
* The current thread must hold the lock on @value. * The current thread must hold the lock on @value.
*/ */
@@ -267,52 +267,52 @@ g_variant_release_children (GVariant *value)
g_free (value->contents.tree.children); g_free (value->contents.tree.children);
} }
/* This begins the main body of the recursive serialiser. /* This begins the main body of the recursive serializer.
* *
* There are 3 functions here that work as a team with the serialiser to * There are 3 functions here that work as a team with the serializer to
* get things done. g_variant_store() has a trivial role, but as a * get things done. g_variant_store() has a trivial role, but as a
* public API function, it has its definition elsewhere. * public API function, it has its definition elsewhere.
* *
* Note that "serialisation" of an instance does not mean that the * Note that "serialization" of an instance does not mean that the
* instance is converted to serialised form -- it means that the * instance is converted to serialized form -- it means that the
* serialised form of an instance is written to an external buffer. * serialized form of an instance is written to an external buffer.
* g_variant_ensure_serialised() (which is not part of this set of * g_variant_ensure_serialised() (which is not part of this set of
* functions) is the function that is responsible for converting an * functions) is the function that is responsible for converting an
* instance to serialised form. * instance to serialized form.
* *
* We are only concerned here with container types since non-container * We are only concerned here with container types since non-container
* instances are always in serialised form. For these instances, * instances are always in serialized form. For these instances,
* storing their serialised form merely involves a memcpy(). * storing their serialized form merely involves a memcpy().
* *
* Serialisation is a two-step process. First, the size of the * Serialization is a two-step process. First, the size of the
* serialised data must be calculated so that an appropriately-sized * serialized data must be calculated so that an appropriately-sized
* buffer can be allocated. Second, the data is written into the * buffer can be allocated. Second, the data is written into the
* buffer. * buffer.
* *
* Determining the size: * Determining the size:
* The process of determining the size is triggered by a call to * The process of determining the size is triggered by a call to
* g_variant_ensure_size() on a container. This invokes the * g_variant_ensure_size() on a container. This invokes the
* serialiser code to determine the size. The serialiser is passed * serializer code to determine the size. The serializer is passed
* g_variant_fill_gvs() as a callback. * g_variant_fill_gvs() as a callback.
* *
* g_variant_fill_gvs() is called by the serialiser on each child of * g_variant_fill_gvs() is called by the serializer on each child of
* the container which, in turn, calls g_variant_ensure_size() on * the container which, in turn, calls g_variant_ensure_size() on
* itself and fills in the result of its own size calculation. * itself and fills in the result of its own size calculation.
* *
* The serialiser uses the size information from the children to * The serializer uses the size information from the children to
* calculate the size needed for the entire container. * calculate the size needed for the entire container.
* *
* Writing the data: * Writing the data:
* After the buffer has been allocated, g_variant_serialise() is * After the buffer has been allocated, g_variant_serialise() is
* called on the container. This invokes the serialiser code to write * called on the container. This invokes the serializer code to write
* the bytes to the container. The serialiser is, again, passed * the bytes to the container. The serializer is, again, passed
* g_variant_fill_gvs() as a callback. * g_variant_fill_gvs() as a callback.
* *
* This time, when g_variant_fill_gvs() is called for each child, the * This time, when g_variant_fill_gvs() is called for each child, the
* child is given a pointer to a sub-region of the allocated buffer * child is given a pointer to a sub-region of the allocated buffer
* where it should write its data. This is done by calling * where it should write its data. This is done by calling
* g_variant_store(). In the event that the instance is in serialised * g_variant_store(). In the event that the instance is in serialized
* form this means a memcpy() of the serialised data into the * form this means a memcpy() of the serialized data into the
* allocated buffer. In the event that the instance is in tree form * allocated buffer. In the event that the instance is in tree form
* this means a recursive call back into g_variant_serialise(). * this means a recursive call back into g_variant_serialise().
* *
@@ -326,7 +326,7 @@ static void g_variant_fill_gvs (GVariantSerialised *, gpointer);
* @value: a #GVariant * @value: a #GVariant
* *
* Ensures that the ->size field of @value is filled in properly. This * Ensures that the ->size field of @value is filled in properly. This
* must be done as a precursor to any serialisation of the value in * must be done as a precursor to any serialization of the value in
* order to know how large of a buffer is needed to store the data. * order to know how large of a buffer is needed to store the data.
* *
* The current thread must hold the lock on @value. * The current thread must hold the lock on @value.
@@ -354,7 +354,7 @@ g_variant_ensure_size (GVariant *value)
* @value: a #GVariant * @value: a #GVariant
* @data: an appropriately-sized buffer * @data: an appropriately-sized buffer
* *
* Serialises @value into @data. @value must be in tree form. * Serializes @value into @data. @value must be in tree form.
* *
* No change is made to @value. * No change is made to @value.
* *
@@ -389,15 +389,15 @@ g_variant_serialise (GVariant *value,
* @data: a #GVariant instance * @data: a #GVariant instance
* *
* This is the callback that is passed by a tree-form container instance * This is the callback that is passed by a tree-form container instance
* to the serialiser. This callback gets called on each child of the * to the serializer. This callback gets called on each child of the
* container. Each child is responsible for performing the following * container. Each child is responsible for performing the following
* actions: * actions:
* *
* - reporting its type * - reporting its type
* *
* - reporting its serialised size (requires knowing the size first) * - reporting its serialized size (requires knowing the size first)
* *
* - possibly storing its serialised form into the provided buffer * - possibly storing its serialized form into the provided buffer
*/ */
static void static void
g_variant_fill_gvs (GVariantSerialised *serialised, g_variant_fill_gvs (GVariantSerialised *serialised,
@@ -425,18 +425,18 @@ g_variant_fill_gvs (GVariantSerialised *serialised,
g_variant_store (value, serialised->data); g_variant_store (value, serialised->data);
} }
/* this ends the main body of the recursive serialiser */ /* this ends the main body of the recursive serializer */
/* < private > /* < private >
* g_variant_ensure_serialised: * g_variant_ensure_serialised:
* @value: a #GVariant * @value: a #GVariant
* *
* Ensures that @value is in serialised form. * Ensures that @value is in serialized form.
* *
* If @value is in tree form then this function ensures that the * If @value is in tree form then this function ensures that the
* serialised size is known and then allocates a buffer of that size and * serialized size is known and then allocates a buffer of that size and
* serialises the instance into the buffer. The 'children' array is * serializes the instance into the buffer. The 'children' array is
* then released and the instance is set to serialised form based on the * then released and the instance is set to serialized form based on the
* contents of the buffer. * contents of the buffer.
* *
* The current thread must hold the lock on @value. * The current thread must hold the lock on @value.
@@ -501,8 +501,8 @@ g_variant_alloc (const GVariantType *type,
* @bytes: a #GBytes * @bytes: a #GBytes
* @trusted: if the contents of @bytes are trusted * @trusted: if the contents of @bytes are trusted
* *
* Constructs a new serialised-mode #GVariant instance. This is the * Constructs a new serialized-mode #GVariant instance. This is the
* inner interface for creation of new serialised values that gets * inner interface for creation of new serialized values that gets
* called from various functions in gvariant.c. * called from various functions in gvariant.c.
* *
* A reference is taken on @bytes. * A reference is taken on @bytes.
@@ -605,7 +605,7 @@ g_variant_new_from_bytes (const GVariantType *type,
* @trusted: %TRUE if every child in @children in trusted * @trusted: %TRUE if every child in @children in trusted
* *
* Constructs a new tree-mode #GVariant instance. This is the inner * Constructs a new tree-mode #GVariant instance. This is the inner
* interface for creation of new serialised values that gets called from * interface for creation of new serialized values that gets called from
* various functions in gvariant.c. * various functions in gvariant.c.
* *
* @children is consumed by this function. g_free() will be called on * @children is consumed by this function. g_free() will be called on
@@ -872,13 +872,13 @@ g_variant_is_floating (GVariant *value)
* If @value has a fixed-sized type then this function always returned * If @value has a fixed-sized type then this function always returned
* that fixed size. * that fixed size.
* *
* In the case that @value is already in serialised form or the size has * In the case that @value is already in serialized form or the size has
* already been calculated (ie: this function has been called before) * already been calculated (ie: this function has been called before)
* then this function is O(1). Otherwise, the size is calculated, an * then this function is O(1). Otherwise, the size is calculated, an
* operation which is approximately O(n) in the number of values * operation which is approximately O(n) in the number of values
* involved. * involved.
* *
* Returns: the serialised size of @value * Returns: the serialized size of @value
* *
* Since: 2.24 * Since: 2.24
**/ **/
@@ -896,33 +896,33 @@ g_variant_get_size (GVariant *value)
* g_variant_get_data: * g_variant_get_data:
* @value: a #GVariant instance * @value: a #GVariant instance
* *
* Returns a pointer to the serialised form of a #GVariant instance. * Returns a pointer to the serialized form of a #GVariant instance.
* The returned data may not be in fully-normalised form if read from an * The returned data may not be in fully-normalised form if read from an
* untrusted source. The returned data must not be freed; it remains * untrusted source. The returned data must not be freed; it remains
* valid for as long as @value exists. * valid for as long as @value exists.
* *
* If @value is a fixed-sized value that was deserialised from a * If @value is a fixed-sized value that was deserialized from a
* corrupted serialised container then %NULL may be returned. In this * corrupted serialized container then %NULL may be returned. In this
* case, the proper thing to do is typically to use the appropriate * case, the proper thing to do is typically to use the appropriate
* number of nul bytes in place of @value. If @value is not fixed-sized * number of nul bytes in place of @value. If @value is not fixed-sized
* then %NULL is never returned. * then %NULL is never returned.
* *
* In the case that @value is already in serialised form, this function * In the case that @value is already in serialized form, this function
* is O(1). If the value is not already in serialised form, * is O(1). If the value is not already in serialized form,
* serialisation occurs implicitly and is approximately O(n) in the size * serialization occurs implicitly and is approximately O(n) in the size
* of the result. * of the result.
* *
* To deserialise the data returned by this function, in addition to the * To deserialize the data returned by this function, in addition to the
* serialised data, you must know the type of the #GVariant, and (if the * serialized data, you must know the type of the #GVariant, and (if the
* machine might be different) the endianness of the machine that stored * machine might be different) the endianness of the machine that stored
* it. As a result, file formats or network messages that incorporate * it. As a result, file formats or network messages that incorporate
* serialised #GVariants must include this information either * serialized #GVariants must include this information either
* implicitly (for instance "the file always contains a * implicitly (for instance "the file always contains a
* %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or * %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 * explicitly (by storing the type and/or endianness in addition to the
* serialised data). * serialized data).
* *
* Returns: (transfer none): the serialised form of @value, or %NULL * Returns: (transfer none): the serialized form of @value, or %NULL
* *
* Since: 2.24 * Since: 2.24
**/ **/
@@ -940,7 +940,7 @@ g_variant_get_data (GVariant *value)
* g_variant_get_data_as_bytes: * g_variant_get_data_as_bytes:
* @value: a #GVariant * @value: a #GVariant
* *
* Returns a pointer to the serialised form of a #GVariant instance. * Returns a pointer to the serialized form of a #GVariant instance.
* The semantics of this function are exactly the same as * The semantics of this function are exactly the same as
* g_variant_get_data(), except that the returned #GBytes holds * g_variant_get_data(), except that the returned #GBytes holds
* a reference to the variant data. * a reference to the variant data.
@@ -1043,7 +1043,7 @@ g_variant_n_children (GVariant *value)
* *
* Note that values borrowed from the returned child are not guaranteed to * Note that values borrowed from the returned child are not guaranteed to
* still be valid after the child is freed even if you still hold a reference * still be valid after the child is freed even if you still hold a reference
* to @value, if @value has not been serialised at the time this function is * to @value, if @value has not been serialized at the time this function is
* called. To avoid this, you can serialize @value by calling * called. To avoid this, you can serialize @value by calling
* g_variant_get_data() and optionally ignoring the return value. * g_variant_get_data() and optionally ignoring the return value.
* *
@@ -1092,8 +1092,8 @@ g_variant_get_child_value (GVariant *value,
GVariantSerialised s_child; GVariantSerialised s_child;
GVariant *child; GVariant *child;
/* get the serialiser to extract the serialised data for the child /* get the serializer to extract the serialized data for the child
* from the serialised data for the container * from the serialized data for the container
*/ */
s_child = g_variant_serialised_get_child (serialised, index_); s_child = g_variant_serialised_get_child (serialised, index_);
@@ -1111,7 +1111,7 @@ g_variant_get_child_value (GVariant *value,
return g_variant_new_tuple (NULL, 0); return g_variant_new_tuple (NULL, 0);
} }
/* create a new serialised instance out of it */ /* create a new serialized instance out of it */
child = g_slice_new (GVariant); child = g_slice_new (GVariant);
child->type_info = s_child.type_info; child->type_info = s_child.type_info;
child->state = (value->state & STATE_TRUSTED) | child->state = (value->state & STATE_TRUSTED) |
@@ -1130,17 +1130,17 @@ g_variant_get_child_value (GVariant *value,
/** /**
* g_variant_store: * g_variant_store:
* @value: the #GVariant to store * @value: the #GVariant to store
* @data: (not nullable): the location to store the serialised data at * @data: (not nullable): the location to store the serialized data at
* *
* Stores the serialised form of @value at @data. @data should be * Stores the serialized form of @value at @data. @data should be
* large enough. See g_variant_get_size(). * large enough. See g_variant_get_size().
* *
* The stored data is in machine native byte order but may not be in * The stored data is in machine native byte order but may not be in
* fully-normalised form if read from an untrusted source. See * fully-normalised form if read from an untrusted source. See
* g_variant_get_normal_form() for a solution. * g_variant_get_normal_form() for a solution.
* *
* As with g_variant_get_data(), to be able to deserialise the * As with g_variant_get_data(), to be able to deserialize the
* serialised variant successfully, its type and (if the destination * serialized variant successfully, its type and (if the destination
* machine might be different) its endianness must also be available. * machine might be different) its endianness must also be available.
* *
* This function is approximately O(n) in the size of @data. * This function is approximately O(n) in the size of @data.
@@ -1173,7 +1173,7 @@ g_variant_store (GVariant *value,
* Checks if @value is in normal form. * Checks if @value is in normal form.
* *
* The main reason to do this is to detect if a given chunk of * The main reason to do this is to detect if a given chunk of
* serialised data is in normal form: load the data into a #GVariant * serialized data is in normal form: load the data into a #GVariant
* using g_variant_new_from_data() and then use this function to * using g_variant_new_from_data() and then use this function to
* check. * check.
* *

View File

@@ -44,26 +44,26 @@
* container and implements 5 functions for dealing with it: * container and implements 5 functions for dealing with it:
* *
* n_children: * n_children:
* - determines (according to serialised data) how many child values * - determines (according to serialized data) how many child values
* are inside a particular container value. * are inside a particular container value.
* *
* get_child: * get_child:
* - gets the type of and the serialised data corresponding to a * - gets the type of and the serialized data corresponding to a
* given child value within the container value. * given child value within the container value.
* *
* needed_size: * needed_size:
* - determines how much space would be required to serialise a * - determines how much space would be required to serialize a
* container of this type, containing the given children so that * container of this type, containing the given children so that
* buffers can be preallocated before serialising. * buffers can be preallocated before serializing.
* *
* serialise: * serialise:
* - write the serialised data for a container of this type, * - write the serialized data for a container of this type,
* containing the given children, to a buffer. * containing the given children, to a buffer.
* *
* is_normal: * is_normal:
* - check the given data to ensure that it is in normal form. For a * - check the given data to ensure that it is in normal form. For a
* given set of child values, there is exactly one normal form for * given set of child values, there is exactly one normal form for
* the serialised data of a container. Other forms are possible * the serialized data of a container. Other forms are possible
* while maintaining the same children (for example, by inserting * while maintaining the same children (for example, by inserting
* something other than zero bytes as padding) but only one form is * something other than zero bytes as padding) but only one form is
* the normal form. * the normal form.
@@ -72,7 +72,7 @@
* functions and logic to dispatch it to the handler for the appropriate * functions and logic to dispatch it to the handler for the appropriate
* container type code. * container type code.
* *
* The second part also contains a routine to byteswap serialised * The second part also contains a routine to byteswap serialized
* values. This code makes use of the n_children() and get_child() * values. This code makes use of the n_children() and get_child()
* functions above to do its work so no extra support is needed on a * functions above to do its work so no extra support is needed on a
* per-container-type basis. * per-container-type basis.
@@ -90,17 +90,17 @@
/* < private > /* < private >
* GVariantSerialised: * GVariantSerialised:
* @type_info: the #GVariantTypeInfo of this value * @type_info: the #GVariantTypeInfo of this value
* @data: (nullable): the serialised data of this value, or %NULL * @data: (nullable): the serialized data of this value, or %NULL
* @size: the size of this value * @size: the size of this value
* *
* A structure representing a GVariant in serialised form. This * A structure representing a GVariant in serialized form. This
* structure is used with #GVariantSerialisedFiller functions and as the * structure is used with #GVariantSerialisedFiller functions and as the
* primary interface to the serialiser. See #GVariantSerialisedFiller * primary interface to the serializer. See #GVariantSerialisedFiller
* for a description of its use there. * for a description of its use there.
* *
* When used with the serialiser API functions, the following invariants * When used with the serializer API functions, the following invariants
* apply to all #GVariantTypeSerialised structures passed to and * apply to all #GVariantTypeSerialised structures passed to and
* returned from the serialiser. * returned from the serializer.
* *
* @type_info must be non-%NULL. * @type_info must be non-%NULL.
* *
@@ -117,7 +117,7 @@
* combination should be as if @data were a pointer to an * combination should be as if @data were a pointer to an
* appropriately-sized zero-filled region. * appropriately-sized zero-filled region.
* *
* @depth has no restrictions; the depth of a top-level serialised #GVariant is * @depth has no restrictions; the depth of a top-level serialized #GVariant is
* zero, and it increases for each level of nested child. * zero, and it increases for each level of nested child.
*/ */
@@ -185,9 +185,9 @@ g_variant_serialised_check (GVariantSerialised serialised)
* from a partially-complete #GVariantSerialised. * from a partially-complete #GVariantSerialised.
* *
* The @data parameter passed back to the function is one of the items * The @data parameter passed back to the function is one of the items
* that was passed to the serialiser in the @children array. It * that was passed to the serializer in the @children array. It
* represents a single child item of the container that is being * represents a single child item of the container that is being
* serialised. The information filled in to @serialised is the * serialized. The information filled in to @serialised is the
* information for this child. * information for this child.
* *
* If the @type_info field of @serialised is %NULL then the callback * If the @type_info field of @serialised is %NULL then the callback
@@ -197,24 +197,24 @@ g_variant_serialised_check (GVariantSerialised serialised)
* of the child. * of the child.
* *
* If the @size field is zero then the callback must fill it in with the * If the @size field is zero then the callback must fill it in with the
* required amount of space to store the serialised form of the child. * required amount of space to store the serialized form of the child.
* If it is non-zero then the callback should assert that it is equal to * If it is non-zero then the callback should assert that it is equal to
* the needed size of the child. * the needed size of the child.
* *
* If @data is non-%NULL then it points to a space that is properly * If @data is non-%NULL then it points to a space that is properly
* aligned for and large enough to store the serialised data of the * aligned for and large enough to store the serialized data of the
* child. The callback must store the serialised form of the child at * child. The callback must store the serialized form of the child at
* @data. * @data.
* *
* If the child value is another container then the callback will likely * If the child value is another container then the callback will likely
* recurse back into the serialiser by calling * recurse back into the serializer by calling
* g_variant_serialiser_needed_size() to determine @size and * g_variant_serialiser_needed_size() to determine @size and
* g_variant_serialiser_serialise() to write to @data. * g_variant_serialiser_serialise() to write to @data.
*/ */
/* PART 1: Container types {{{1 /* PART 1: Container types {{{1
* *
* This section contains the serialiser implementation functions for * This section contains the serializer implementation functions for
* each container type. * each container type.
*/ */
@@ -235,7 +235,7 @@ g_variant_serialised_check (GVariantSerialised serialised)
* size of the maybe value is zero corresponds to the "Nothing" case and * size of the maybe value is zero corresponds to the "Nothing" case and
* the case where the size of the maybe value is equal to the fixed size * the case where the size of the maybe value is equal to the fixed size
* of the element type corresponds to the "Just" case; in that case, the * of the element type corresponds to the "Just" case; in that case, the
* serialised data of the child value forms the entire serialised data * serialized data of the child value forms the entire serialized data
* of the maybe value. * of the maybe value.
* *
* In the event that a fixed-sized maybe value is presented with a size * In the event that a fixed-sized maybe value is presented with a size
@@ -331,11 +331,11 @@ gvs_fixed_sized_maybe_is_normal (GVariantSerialised value)
* either 0 or strictly greater than 0. The case where the size of the * either 0 or strictly greater than 0. The case where the size of the
* maybe value is zero corresponds to the "Nothing" case and the case * maybe value is zero corresponds to the "Nothing" case and the case
* where the size of the maybe value is greater than zero corresponds to * where the size of the maybe value is greater than zero corresponds to
* the "Just" case; in that case, the serialised data of the child value * the "Just" case; in that case, the serialized data of the child value
* forms the first part of the serialised data of the maybe value and is * forms the first part of the serialized data of the maybe value and is
* followed by a single zero byte. This zero byte is always appended, * followed by a single zero byte. This zero byte is always appended,
* regardless of any zero bytes that may already be at the end of the * regardless of any zero bytes that may already be at the end of the
* serialised ata of the child value. * serialized ata of the child value.
*/ */
static gsize static gsize
@@ -424,8 +424,8 @@ gvs_variable_sized_maybe_is_normal (GVariantSerialised value)
/* Fixed-sized Array {{{3 /* Fixed-sized Array {{{3
* *
* For fixed sized arrays, the serialised data is simply a concatenation * For fixed sized arrays, the serialized data is simply a concatenation
* of the serialised data of each element, in order. Since fixed-sized * of the serialized data of each element, in order. Since fixed-sized
* values always have a fixed size that is a multiple of their alignment * values always have a fixed size that is a multiple of their alignment
* requirement no extra padding is required. * requirement no extra padding is required.
* *
@@ -535,35 +535,35 @@ gvs_fixed_sized_array_is_normal (GVariantSerialised value)
* record the end point of each element in the array. * record the end point of each element in the array.
* *
* GVariant works in terms of "offsets". An offset is a pointer to a * GVariant works in terms of "offsets". An offset is a pointer to a
* boundary between two bytes. In 4 bytes of serialised data, there * boundary between two bytes. In 4 bytes of serialized data, there
* would be 5 possible offsets: one at the start ('0'), one between each * would be 5 possible offsets: one at the start ('0'), one between each
* pair of adjacent bytes ('1', '2', '3') and one at the end ('4'). * pair of adjacent bytes ('1', '2', '3') and one at the end ('4').
* *
* The numeric value of an offset is an unsigned integer given relative * The numeric value of an offset is an unsigned integer given relative
* to the start of the serialised data of the array. Offsets are always * to the start of the serialized data of the array. Offsets are always
* stored in little endian byte order and are always only as big as they * stored in little endian byte order and are always only as big as they
* need to be. For example, in 255 bytes of serialised data, there are * need to be. For example, in 255 bytes of serialized data, there are
* 256 offsets. All possibilities can be stored in an 8 bit unsigned * 256 offsets. All possibilities can be stored in an 8 bit unsigned
* integer. In 256 bytes of serialised data, however, there are 257 * integer. In 256 bytes of serialized data, however, there are 257
* possible offsets so 16 bit integers must be used. The size of an * possible offsets so 16 bit integers must be used. The size of an
* offset is always a power of 2. * offset is always a power of 2.
* *
* The offsets are stored at the end of the serialised data of the * The offsets are stored at the end of the serialized data of the
* array. They are simply concatenated on without any particular * array. They are simply concatenated on without any particular
* alignment. The size of the offsets is included in the size of the * alignment. The size of the offsets is included in the size of the
* serialised data for purposes of determining the size of the offsets. * serialized data for purposes of determining the size of the offsets.
* This presents a possibly ambiguity; in certain cases, a particular * This presents a possibly ambiguity; in certain cases, a particular
* value of array could have two different serialised forms. * value of array could have two different serialized forms.
* *
* Imagine an array containing a single string of 253 bytes in length * Imagine an array containing a single string of 253 bytes in length
* (so, 254 bytes including the nul terminator). Now the offset must be * (so, 254 bytes including the nul terminator). Now the offset must be
* written. If an 8 bit offset is written, it will bring the size of * written. If an 8 bit offset is written, it will bring the size of
* the array's serialised data to 255 -- which means that the use of an * the array's serialized data to 255 -- which means that the use of an
* 8 bit offset was valid. If a 16 bit offset is used then the total * 8 bit offset was valid. If a 16 bit offset is used then the total
* size of the array will be 256 -- which means that the use of a 16 bit * size of the array will be 256 -- which means that the use of a 16 bit
* offset was valid. Although both of these will be accepted by the * offset was valid. Although both of these will be accepted by the
* deserialiser, only the smaller of the two is considered to be in * deserializer, only the smaller of the two is considered to be in
* normal form and that is the one that the serialiser must produce. * normal form and that is the one that the serializer must produce.
*/ */
/* bytes may be NULL if (size == 0). */ /* bytes may be NULL if (size == 0). */
@@ -840,20 +840,20 @@ gvs_variable_sized_array_is_normal (GVariantSerialised value)
/* Tuples {{{2 /* Tuples {{{2
* *
* Since tuples can contain a mix of variable- and fixed-sized items, * Since tuples can contain a mix of variable- and fixed-sized items,
* they are, in terms of serialisation, a hybrid of variable-sized and * they are, in terms of serialization, a hybrid of variable-sized and
* fixed-sized arrays. * fixed-sized arrays.
* *
* Offsets are only stored for variable-sized items. Also, since the * Offsets are only stored for variable-sized items. Also, since the
* number of items in a tuple is known from its type, we are able to * number of items in a tuple is known from its type, we are able to
* know exactly how many offsets to expect in the serialised data (and * know exactly how many offsets to expect in the serialized data (and
* therefore how much space is taken up by the offset array). This * therefore how much space is taken up by the offset array). This
* means that we know where the end of the serialised data for the last * means that we know where the end of the serialized data for the last
* item is -- we can just subtract the size of the offset array from the * item is -- we can just subtract the size of the offset array from the
* total size of the tuple. For this reason, the last item in the tuple * total size of the tuple. For this reason, the last item in the tuple
* doesn't need an offset stored. * doesn't need an offset stored.
* *
* Tuple offsets are stored in reverse. This design choice allows * Tuple offsets are stored in reverse. This design choice allows
* iterator-based deserialisers to be more efficient. * iterator-based deserializers to be more efficient.
* *
* Most of the "heavy lifting" here is handled by the GVariantTypeInfo * Most of the "heavy lifting" here is handled by the GVariantTypeInfo
* for the tuple. See the notes in gvarianttypeinfo.h. * for the tuple. See the notes in gvarianttypeinfo.h.
@@ -1158,7 +1158,7 @@ gvs_tuple_is_normal (GVariantSerialised value)
/* Variants {{{2 /* Variants {{{2
* *
* Variants are stored by storing the serialised data of the child, * Variants are stored by storing the serialized data of the child,
* followed by a '\0' character, followed by the type string of the * followed by a '\0' character, followed by the type string of the
* child. * child.
* *
@@ -1287,9 +1287,9 @@ gvs_variant_is_normal (GVariantSerialised value)
/* PART 2: Serialiser API {{{1 /* PART 2: Serializer API {{{1
* *
* This is the implementation of the API of the serialiser as advertised * This is the implementation of the API of the serializer as advertised
* in gvariant-serialiser.h. * in gvariant-serialiser.h.
*/ */
@@ -1338,9 +1338,9 @@ gvs_variant_is_normal (GVariantSerialised value)
} \ } \
} }
/* Serialiser entry points {{{2 /* Serializer entry points {{{2
* *
* These are the functions that are called in order for the serialiser * These are the functions that are called in order for the serializer
* to do its thing. * to do its thing.
*/ */
@@ -1348,7 +1348,7 @@ gvs_variant_is_normal (GVariantSerialised value)
* g_variant_serialised_n_children: * g_variant_serialised_n_children:
* @serialised: a #GVariantSerialised * @serialised: a #GVariantSerialised
* *
* For serialised data that represents a container value (maybes, * For serialized data that represents a container value (maybes,
* tuples, arrays, variants), determine how many child items are inside * tuples, arrays, variants), determine how many child items are inside
* that container. * that container.
* *
@@ -1372,7 +1372,7 @@ g_variant_serialised_n_children (GVariantSerialised serialised)
* @serialised: a #GVariantSerialised * @serialised: a #GVariantSerialised
* @index_: the index of the child to fetch * @index_: the index of the child to fetch
* *
* Extracts a child from a serialised data representing a container * Extracts a child from a serialized data representing a container
* value. * value.
* *
* It is an error to call this function with an index out of bounds. * It is an error to call this function with an index out of bounds.
@@ -1421,19 +1421,19 @@ g_variant_serialised_get_child (GVariantSerialised serialised,
* @children: an array of child items * @children: an array of child items
* @n_children: the size of @children * @n_children: the size of @children
* *
* Writes data in serialised form. * Writes data in serialized form.
* *
* The type_info field of @serialised must be filled in to type info for * The type_info field of @serialised must be filled in to type info for
* the type that we are serialising. * the type that we are serializing.
* *
* The size field of @serialised must be filled in with the value * The size field of @serialised must be filled in with the value
* returned by a previous call to g_variant_serialiser_needed_size(). * returned by a previous call to g_variant_serialiser_needed_size().
* *
* The data field of @serialised must be a pointer to a properly-aligned * The data field of @serialised must be a pointer to a properly-aligned
* memory region large enough to serialise into (ie: at least as big as * memory region large enough to serialize into (ie: at least as big as
* the size field). * the size field).
* *
* This function is only resonsible for serialising the top-level * This function is only resonsible for serializing the top-level
* container. @gvs_filler is called on each child of the container in * container. @gvs_filler is called on each child of the container in
* order for all of the data of that child to be filled in. * order for all of the data of that child to be filled in.
*/ */
@@ -1457,12 +1457,12 @@ g_variant_serialiser_serialise (GVariantSerialised serialised,
/* < private > /* < private >
* g_variant_serialiser_needed_size: * g_variant_serialiser_needed_size:
* @type_info: the type to serialise for * @type_info: the type to serialize for
* @gvs_filler: the filler function * @gvs_filler: the filler function
* @children: an array of child items * @children: an array of child items
* @n_children: the size of @children * @n_children: the size of @children
* *
* Determines how much memory would be needed to serialise this value. * Determines how much memory would be needed to serialize this value.
* *
* This function is only resonsible for performing calculations for the * This function is only resonsible for performing calculations for the
* top-level container. @gvs_filler is called on each child of the * top-level container. @gvs_filler is called on each child of the
@@ -1489,7 +1489,7 @@ g_variant_serialiser_needed_size (GVariantTypeInfo *type_info,
* g_variant_serialised_byteswap: * g_variant_serialised_byteswap:
* @value: a #GVariantSerialised * @value: a #GVariantSerialised
* *
* Byte-swap serialised data. The result of this function is only * Byte-swap serialized data. The result of this function is only
* well-defined if the data is in normal form. * well-defined if the data is in normal form.
*/ */
void void
@@ -1577,9 +1577,9 @@ g_variant_serialised_byteswap (GVariantSerialised serialised)
* @serialised: a #GVariantSerialised * @serialised: a #GVariantSerialised
* *
* Determines, recursively if @serialised is in normal form. There is * Determines, recursively if @serialised is in normal form. There is
* precisely one normal form of serialised data for each possible value. * precisely one normal form of serialized data for each possible value.
* *
* It is possible that multiple byte sequences form the serialised data * It is possible that multiple byte sequences form the serialized data
* for a given value if, for example, the padding bytes are filled in * for a given value if, for example, the padding bytes are filled in
* with something other than zeros, but only one form is the normal * with something other than zeros, but only one form is the normal
* form. * form.

View File

@@ -31,14 +31,14 @@ typedef struct
gsize depth; /* same semantics as GVariant.depth */ gsize depth; /* same semantics as GVariant.depth */
} GVariantSerialised; } GVariantSerialised;
/* deserialisation */ /* deserialization */
GLIB_AVAILABLE_IN_ALL GLIB_AVAILABLE_IN_ALL
gsize g_variant_serialised_n_children (GVariantSerialised container); gsize g_variant_serialised_n_children (GVariantSerialised container);
GLIB_AVAILABLE_IN_ALL GLIB_AVAILABLE_IN_ALL
GVariantSerialised g_variant_serialised_get_child (GVariantSerialised container, GVariantSerialised g_variant_serialised_get_child (GVariantSerialised container,
gsize index); gsize index);
/* serialisation */ /* serialization */
typedef void (*GVariantSerialisedFiller) (GVariantSerialised *serialised, typedef void (*GVariantSerialisedFiller) (GVariantSerialised *serialised,
gpointer data); gpointer data);

View File

@@ -84,19 +84,19 @@
* concurrently accessed in any way from any number of threads without * concurrently accessed in any way from any number of threads without
* problems. * problems.
* *
* #GVariant is heavily optimised for dealing with data in serialised * #GVariant is heavily optimised for dealing with data in serialized
* form. It works particularly well with data located in memory-mapped * form. It works particularly well with data located in memory-mapped
* files. It can perform nearly all deserialisation operations in a * files. It can perform nearly all deserialization operations in a
* small constant time, usually touching only a single memory page. * small constant time, usually touching only a single memory page.
* Serialised #GVariant data can also be sent over the network. * Serialized #GVariant data can also be sent over the network.
* *
* #GVariant is largely compatible with D-Bus. Almost all types of * #GVariant is largely compatible with D-Bus. Almost all types of
* #GVariant instances can be sent over D-Bus. See #GVariantType for * #GVariant instances can be sent over D-Bus. See #GVariantType for
* exceptions. (However, #GVariant's serialisation format is not the same * exceptions. (However, #GVariant's serialization format is not the same
* as the serialisation format of a D-Bus message body: use #GDBusMessage, * as the serialization format of a D-Bus message body: use #GDBusMessage,
* in the gio library, for those.) * in the gio library, for those.)
* *
* For space-efficiency, the #GVariant serialisation format does not * For space-efficiency, the #GVariant serialization format does not
* automatically include the variant's length, type or endianness, * automatically include the variant's length, type or endianness,
* which must either be implied from context (such as knowledge that a * which must either be implied from context (such as knowledge that a
* particular file format always contains a little-endian * particular file format always contains a little-endian
@@ -126,14 +126,14 @@
* in the future. * in the future.
* *
* The memory allocated by #GVariant can be grouped into 4 broad * The memory allocated by #GVariant can be grouped into 4 broad
* purposes: memory for serialised data, memory for the type * purposes: memory for serialized data, memory for the type
* information cache, buffer management memory and memory for the * information cache, buffer management memory and memory for the
* #GVariant structure itself. * #GVariant structure itself.
* *
* ## Serialised Data Memory * ## Serialized Data Memory
* *
* This is the memory that is used for storing GVariant data in * This is the memory that is used for storing GVariant data in
* serialised form. This is what would be sent over the network or * serialized form. This is what would be sent over the network or
* what would end up on disk, not counting any indicator of the * what would end up on disk, not counting any indicator of the
* endianness, or of the length or type of the top-level variant. * endianness, or of the length or type of the top-level variant.
* *
@@ -167,7 +167,7 @@
* *
* As an example, consider a dictionary mapping strings to variants. * As an example, consider a dictionary mapping strings to variants.
* In the case that the dictionary is empty, 0 bytes are required for * In the case that the dictionary is empty, 0 bytes are required for
* the serialisation. * the serialization.
* *
* If we add an item "width" that maps to the int32 value of 500 then * If we add an item "width" that maps to the int32 value of 500 then
* we will use 4 byte to store the int32 (so 6 for the variant * we will use 4 byte to store the int32 (so 6 for the variant
@@ -193,7 +193,7 @@
* *
* For each GVariant type that currently exists in the program a type * For each GVariant type that currently exists in the program a type
* information structure is kept in the type information cache. The * information structure is kept in the type information cache. The
* type information structure is required for rapid deserialisation. * type information structure is required for rapid deserialization.
* *
* Continuing with the above example, if a #GVariant exists with the * Continuing with the above example, if a #GVariant exists with the
* type "a{sv}" then a type information struct will exist for * type "a{sv}" then a type information struct will exist for
@@ -238,14 +238,14 @@
* ## Buffer Management Memory * ## Buffer Management Memory
* *
* #GVariant uses an internal buffer management structure to deal * #GVariant uses an internal buffer management structure to deal
* with the various different possible sources of serialised data * with the various different possible sources of serialized data
* that it uses. The buffer is responsible for ensuring that the * that it uses. The buffer is responsible for ensuring that the
* correct call is made when the data is no longer in use by * correct call is made when the data is no longer in use by
* #GVariant. This may involve a g_free() or a g_slice_free() or * #GVariant. This may involve a g_free() or a g_slice_free() or
* even g_mapped_file_unref(). * even g_mapped_file_unref().
* *
* One buffer management structure is used for each chunk of * One buffer management structure is used for each chunk of
* serialised data. The size of the buffer management structure * serialized data. The size of the buffer management structure
* is 4 * (void *). On 32-bit systems, that's 16 bytes. * is 4 * (void *). On 32-bit systems, that's 16 bytes.
* *
* ## GVariant structure * ## GVariant structure
@@ -255,7 +255,7 @@
* *
* #GVariant structures only exist if they are explicitly created * #GVariant structures only exist if they are explicitly created
* with API calls. For example, if a #GVariant is constructed out of * with API calls. For example, if a #GVariant is constructed out of
* serialised data for the example given above (with the dictionary) * serialized data for the example given above (with the dictionary)
* then although there are 9 individual values that comprise the * then although there are 9 individual values that comprise the
* entire dictionary (two keys, two values, two variants containing * entire dictionary (two keys, two values, two variants containing
* the values, two dictionary entries, plus the dictionary itself), * the values, two dictionary entries, plus the dictionary itself),
@@ -265,8 +265,8 @@
* If calls are made to start accessing the other values then * If calls are made to start accessing the other values then
* #GVariant instances will exist for those values only for as long * #GVariant instances will exist for those values only for as long
* as they are in use (ie: until you call g_variant_unref()). The * as they are in use (ie: until you call g_variant_unref()). The
* type information is shared. The serialised data and the buffer * type information is shared. The serialized data and the buffer
* management structure for that serialised data is shared by the * management structure for that serialized data is shared by the
* child. * child.
* *
* ## Summary * ## Summary
@@ -274,12 +274,12 @@
* To put the entire example together, for our dictionary mapping * To put the entire example together, for our dictionary mapping
* strings to variants (with two entries, as given above), we are * strings to variants (with two entries, as given above), we are
* using 91 bytes of memory for type information, 29 bytes of memory * using 91 bytes of memory for type information, 29 bytes of memory
* for the serialised data, 16 bytes for buffer management and 24 * for the serialized data, 16 bytes for buffer management and 24
* bytes for the #GVariant instance, or a total of 160 bytes, plus * bytes for the #GVariant instance, or a total of 160 bytes, plus
* malloc overhead. If we were to use g_variant_get_child_value() to * malloc overhead. If we were to use g_variant_get_child_value() to
* access the two dictionary entries, we would use an additional 48 * access the two dictionary entries, we would use an additional 48
* bytes. If we were to have other dictionaries of the same type, we * bytes. If we were to have other dictionaries of the same type, we
* would use more memory for the serialised data and buffer * would use more memory for the serialized data and buffer
* management for those dictionaries, but the type information would * management for those dictionaries, but the type information would
* be shared. * be shared.
*/ */
@@ -1095,7 +1095,7 @@ g_variant_lookup_value (GVariant *dictionary,
* @n_elements: (out): a pointer to the location to store the number of items * @n_elements: (out): a pointer to the location to store the number of items
* @element_size: the size of each element * @element_size: the size of each element
* *
* Provides access to the serialised data for an array of fixed-sized * Provides access to the serialized data for an array of fixed-sized
* items. * items.
* *
* @value must be an array with fixed-sized elements. Numeric types are * @value must be an array with fixed-sized elements. Numeric types are
@@ -1103,7 +1103,7 @@ g_variant_lookup_value (GVariant *dictionary,
* *
* @element_size must be the size of a single element in the array, * @element_size must be the size of a single element in the array,
* as given by the section on * as given by the section on
* [serialized data memory][gvariant-serialised-data-memory]. * [serialized data memory][gvariant-serialized-data-memory].
* *
* In particular, arrays of these fixed-sized types can be interpreted * In particular, arrays of these fixed-sized types can be interpreted
* as an array of the given C type, with @element_size set to the size * as an array of the given C type, with @element_size set to the size
@@ -1116,7 +1116,7 @@ g_variant_lookup_value (GVariant *dictionary,
* *
* For example, if calling this function for an array of 32-bit integers, * For example, if calling this function for an array of 32-bit integers,
* you might say `sizeof(gint32)`. This value isn't used except for the purpose * you might say `sizeof(gint32)`. This value isn't used except for the purpose
* of a double-check that the form of the serialised data matches the caller's * of a double-check that the form of the serialized data matches the caller's
* expectation. * expectation.
* *
* @n_elements, which must be non-%NULL, is set equal to the number of * @n_elements, which must be non-%NULL, is set equal to the number of
@@ -1191,7 +1191,7 @@ g_variant_get_fixed_array (GVariant *value,
* @element_size must be the size of a single element in the array. * @element_size must be the size of a single element in the array.
* For example, if calling this function for an array of 32-bit integers, * For example, if calling this function for an array of 32-bit integers,
* you might say sizeof(gint32). This value isn't used except for the purpose * you might say sizeof(gint32). This value isn't used except for the purpose
* of a double-check that the form of the serialised data matches the caller's * of a double-check that the form of the serialized data matches the caller's
* expectation. * expectation.
* *
* @n_elements must be the length of the @elements array. * @n_elements must be the length of the @elements array.
@@ -2745,8 +2745,8 @@ g_variant_equal (gconstpointer one,
g_variant_get_type_info ((GVariant *) two)) g_variant_get_type_info ((GVariant *) two))
return FALSE; return FALSE;
/* if both values are trusted to be in their canonical serialised form /* if both values are trusted to be in their canonical serialized form
* then a simple memcmp() of their serialised data will answer the * then a simple memcmp() of their serialized data will answer the
* question. * question.
* *
* if not, then this might generate a false negative (since it is * if not, then this might generate a false negative (since it is
@@ -5793,7 +5793,7 @@ g_variant_iter_loop (GVariantIter *iter,
return value != NULL; return value != NULL;
} }
/* Serialised data {{{1 */ /* Serialized data {{{1 */
static GVariant * static GVariant *
g_variant_deep_copy (GVariant *value) g_variant_deep_copy (GVariant *value)
{ {
@@ -5882,7 +5882,7 @@ g_variant_deep_copy (GVariant *value)
* #GVariant is created with the same value as @value. * #GVariant is created with the same value as @value.
* *
* It makes sense to call this function if you've received #GVariant * It makes sense to call this function if you've received #GVariant
* data from untrusted sources and you want to ensure your serialised * data from untrusted sources and you want to ensure your serialized
* output is definitely in normal form. * output is definitely in normal form.
* *
* If @value is already in normal form, a new reference will be returned * If @value is already in normal form, a new reference will be returned
@@ -5972,13 +5972,13 @@ g_variant_byteswap (GVariant *value)
/** /**
* g_variant_new_from_data: * g_variant_new_from_data:
* @type: a definite #GVariantType * @type: a definite #GVariantType
* @data: (array length=size) (element-type guint8): the serialised data * @data: (array length=size) (element-type guint8): the serialized data
* @size: the size of @data * @size: the size of @data
* @trusted: %TRUE if @data is definitely in normal form * @trusted: %TRUE if @data is definitely in normal form
* @notify: (scope async): function to call when @data is no longer needed * @notify: (scope async): function to call when @data is no longer needed
* @user_data: data for @notify * @user_data: data for @notify
* *
* Creates a new #GVariant instance from serialised data. * Creates a new #GVariant instance from serialized data.
* *
* @type is the type of #GVariant instance that will be constructed. * @type is the type of #GVariant instance that will be constructed.
* The interpretation of @data depends on knowing the type. * The interpretation of @data depends on knowing the type.
@@ -5988,8 +5988,8 @@ g_variant_byteswap (GVariant *value)
* @user_data. If the contents of @data change before that time then * @user_data. If the contents of @data change before that time then
* the result is undefined. * the result is undefined.
* *
* If @data is trusted to be serialised data in normal form then * If @data is trusted to be serialized data in normal form then
* @trusted should be %TRUE. This applies to serialised data created * @trusted should be %TRUE. This applies to serialized data created
* within this process or read from a trusted location on the disk (such * within this process or read from a trusted location on the disk (such
* as a file installed in /usr/lib alongside your application). You * as a file installed in /usr/lib alongside your application). You
* should set trusted to %FALSE if @data is read from the network, a * should set trusted to %FALSE if @data is read from the network, a

View File

@@ -32,7 +32,7 @@
* GVariantTypeInfo: * GVariantTypeInfo:
* *
* This structure contains the necessary information to facilitate the * This structure contains the necessary information to facilitate the
* serialisation and fast deserialisation of a given type of GVariant * serialization and fast deserialization of a given type of GVariant
* value. A GVariant instance holds a pointer to one of these * value. A GVariant instance holds a pointer to one of these
* structures to provide for efficient operation. * structures to provide for efficient operation.
* *
@@ -93,7 +93,7 @@ typedef struct
} ArrayInfo; } ArrayInfo;
/* For 'tuple' and 'dict entry' types, we store extra information for /* For 'tuple' and 'dict entry' types, we store extra information for
* each member -- its type and how to find it inside the serialised data * each member -- its type and how to find it inside the serialized data
* in O(1) time using 4 variables -- 'i', 'a', 'b', and 'c'. See the * in O(1) time using 4 variables -- 'i', 'a', 'b', and 'c'. See the
* comment on GVariantMemberInfo in gvarianttypeinfo.h. * comment on GVariantMemberInfo in gvarianttypeinfo.h.
*/ */

View File

@@ -40,18 +40,18 @@ typedef struct _GVariantTypeInfo GVariantTypeInfo;
* corresponding to a given child of a tuple or dictionary entry in a * corresponding to a given child of a tuple or dictionary entry in a
* very short constant time. It contains the typeinfo of the child, * very short constant time. It contains the typeinfo of the child,
* along with 4 constants that allow the bounds of the child's * along with 4 constants that allow the bounds of the child's
* serialised data within the container's serialised data to be found * serialized data within the container's serialized data to be found
* very efficiently. * very efficiently.
* *
* Since dictionary entries are serialised as if they were tuples of 2 * Since dictionary entries are serialized as if they were tuples of 2
* items, the term "tuple" will be used here in the general sense to * items, the term "tuple" will be used here in the general sense to
* refer to tuples and dictionary entries. * refer to tuples and dictionary entries.
* *
* BACKGROUND: * BACKGROUND:
* The serialised data for a tuple contains an array of "offsets" at * The serialized data for a tuple contains an array of "offsets" at
* the end. There is one "offset" in this array for each * the end. There is one "offset" in this array for each
* variable-sized item in the tuple (except for the last one). The * variable-sized item in the tuple (except for the last one). The
* offset points to the end point of that item's serialised data. The * offset points to the end point of that item's serialized data. The
* procedure for finding the start point is described below. An * procedure for finding the start point is described below. An
* offset is not needed for the last item because the end point of the * offset is not needed for the last item because the end point of the
* last item is merely the end point of the container itself (after * last item is merely the end point of the container itself (after

View File

@@ -997,7 +997,7 @@ check_offsets (GVariantTypeInfo *info,
position++; position++;
/* and store the offset, just like it would be in the /* and store the offset, just like it would be in the
* serialised data. * serialized data.
*/ */
last_offset = position; last_offset = position;
last_offset_index++; last_offset_index++;
@@ -1093,7 +1093,7 @@ test_gvarianttypeinfo (void)
#define MAX_TUPLE_CHILDREN 128 #define MAX_TUPLE_CHILDREN 128
/* this function generates a random type such that all characteristics /* this function generates a random type such that all characteristics
* that are "interesting" to the serialiser are tested. * that are "interesting" to the serializer are tested.
* *
* this basically means: * this basically means:
* - test different alignments * - test different alignments
@@ -2311,19 +2311,19 @@ test_serialiser_children (void)
g_test_summary ("Test that getting a child variant before and after " g_test_summary ("Test that getting a child variant before and after "
"serialisation of the parent works"); "serialisation of the parent works");
/* Construct a variable sized array containing a child which serialises to a /* Construct a variable sized array containing a child which serializes to a
* zero-length bytestring. */ * zero-length bytestring. */
child = g_variant_new_maybe (G_VARIANT_TYPE_VARIANT, NULL); child = g_variant_new_maybe (G_VARIANT_TYPE_VARIANT, NULL);
variant = g_variant_new_array (mv_type, &child, 1); variant = g_variant_new_array (mv_type, &child, 1);
/* Get the child before serialising. */ /* Get the child before serializing. */
child1 = g_variant_get_child_value (variant, 0); child1 = g_variant_get_child_value (variant, 0);
data1 = g_variant_get_data_as_bytes (child1); data1 = g_variant_get_data_as_bytes (child1);
/* Serialise the parent variant. */ /* Serialize the parent variant. */
g_variant_get_data (variant); g_variant_get_data (variant);
/* Get the child again after serialising — this uses a different code path. */ /* Get the child again after serializing — this uses a different code path. */
child2 = g_variant_get_child_value (variant, 0); child2 = g_variant_get_child_value (variant, 0);
data2 = g_variant_get_data_as_bytes (child2); data2 = g_variant_get_data_as_bytes (child2);
@@ -2348,7 +2348,7 @@ test_fuzz (gdouble *fuzziness)
/* make an instance */ /* make an instance */
tree = tree_instance_new (NULL, 3); tree = tree_instance_new (NULL, 3);
/* serialise it */ /* serialize it */
serialise_tree (tree, &serialised); serialise_tree (tree, &serialised);
g_assert_true (g_variant_serialised_is_normal (serialised)); g_assert_true (g_variant_serialised_is_normal (serialised));
@@ -2371,17 +2371,17 @@ test_fuzz (gdouble *fuzziness)
} }
} }
/* at least one byte in the serialised data has changed. /* at least one byte in the serialized data has changed.
* *
* this means that at least one of the following is true: * this means that at least one of the following is true:
* *
* - the serialised data now represents a different value: * - the serialized data now represents a different value:
* check_tree() will return FALSE * check_tree() will return FALSE
* *
* - the serialised data is in non-normal form: * - the serialized data is in non-normal form:
* g_variant_serialiser_is_normal() will return FALSE * g_variant_serialiser_is_normal() will return FALSE
* *
* we always do both checks to increase exposure of the serialiser * we always do both checks to increase exposure of the serializer
* to corrupt data. * to corrupt data.
*/ */
a = g_variant_serialised_is_normal (serialised); a = g_variant_serialised_is_normal (serialised);
@@ -3743,9 +3743,9 @@ test_gv_byteswap (void)
# define swapped16(x) x, 0 # define swapped16(x) x, 0
#endif #endif
/* all kinds of of crazy randomised testing already performed on the /* all kinds of of crazy randomised testing already performed on the
* byteswapper in the /gvariant/serialiser/byteswap test and all kinds * byteswapper in the /gvariant/serializer/byteswap test and all kinds
* of crazy randomised testing performed against the serialiser * of crazy randomised testing performed against the serializer
* normalisation functions in the /gvariant/serialiser/fuzz/ tests. * normalisation functions in the /gvariant/serializer/fuzz/ tests.
* *
* just test a few simple cases here to make sure they each work * just test a few simple cases here to make sure they each work
*/ */
@@ -4755,7 +4755,7 @@ test_gbytes (void)
g_bytes_unref (bytes2); g_bytes_unref (bytes2);
tuple = g_variant_new_parsed ("['foo', 'bar']"); tuple = g_variant_new_parsed ("['foo', 'bar']");
bytes = g_variant_get_data_as_bytes (tuple); /* force serialisation */ bytes = g_variant_get_data_as_bytes (tuple); /* force serialization */
a = g_variant_get_child_value (tuple, 1); a = g_variant_get_child_value (tuple, 1);
bytes2 = g_variant_get_data_as_bytes (a); bytes2 = g_variant_get_data_as_bytes (a);
g_assert_false (g_bytes_equal (bytes, bytes2)); g_assert_false (g_bytes_equal (bytes, bytes2));
@@ -4898,7 +4898,7 @@ test_normal_checking_tuples (void)
} }
/* Check that deeply nested variants are not considered in normal form when /* Check that deeply nested variants are not considered in normal form when
* deserialised from untrusted data.*/ * deserialized from untrusted data.*/
static void static void
test_recursion_limits_variant_in_variant (void) test_recursion_limits_variant_in_variant (void)
{ {
@@ -4914,7 +4914,7 @@ test_recursion_limits_variant_in_variant (void)
for (i = 0; i < G_VARIANT_MAX_RECURSION_DEPTH - 1; i++) for (i = 0; i < G_VARIANT_MAX_RECURSION_DEPTH - 1; i++)
wrapper_variant = g_variant_new_variant (g_steal_pointer (&wrapper_variant)); wrapper_variant = g_variant_new_variant (g_steal_pointer (&wrapper_variant));
/* Serialise and deserialise it as untrusted data, to force normalisation. */ /* Serialize and deserialize it as untrusted data, to force normalisation. */
bytes = g_variant_get_data_as_bytes (wrapper_variant); bytes = g_variant_get_data_as_bytes (wrapper_variant);
deserialised_variant = g_variant_new_from_bytes (G_VARIANT_TYPE_VARIANT, deserialised_variant = g_variant_new_from_bytes (G_VARIANT_TYPE_VARIANT,
bytes, FALSE); bytes, FALSE);
@@ -4935,7 +4935,7 @@ test_recursion_limits_variant_in_variant (void)
g_variant_unref (deserialised_variant); g_variant_unref (deserialised_variant);
/* Deserialise it again, but trusted this time. This should succeed. */ /* Deserialize it again, but trusted this time. This should succeed. */
deserialised_variant = g_variant_new_from_bytes (G_VARIANT_TYPE_VARIANT, deserialised_variant = g_variant_new_from_bytes (G_VARIANT_TYPE_VARIANT,
bytes, TRUE); bytes, TRUE);
g_assert_nonnull (deserialised_variant); g_assert_nonnull (deserialised_variant);
@@ -4947,7 +4947,7 @@ test_recursion_limits_variant_in_variant (void)
} }
/* Check that deeply nested arrays are not considered in normal form when /* Check that deeply nested arrays are not considered in normal form when
* deserialised from untrusted data after being wrapped in a variant. This is * deserialized from untrusted data after being wrapped in a variant. This is
* worth testing, because neither the deeply nested array, nor the variant, * worth testing, because neither the deeply nested array, nor the variant,
* have a static #GVariantType which is too deep — only when nested together do * have a static #GVariantType which is too deep — only when nested together do
* they become too deep. */ * they become too deep. */
@@ -4967,7 +4967,7 @@ test_recursion_limits_array_in_variant (void)
for (i = 0; i < G_VARIANT_MAX_RECURSION_DEPTH - 1; i++) for (i = 0; i < G_VARIANT_MAX_RECURSION_DEPTH - 1; i++)
child_variant = g_variant_new_array (NULL, &child_variant, 1); child_variant = g_variant_new_array (NULL, &child_variant, 1);
/* Serialise and deserialise it as untrusted data, to force normalisation. */ /* Serialize and deserialize it as untrusted data, to force normalisation. */
bytes = g_variant_get_data_as_bytes (child_variant); bytes = g_variant_get_data_as_bytes (child_variant);
deserialised_variant = g_variant_new_from_bytes (g_variant_get_type (child_variant), deserialised_variant = g_variant_new_from_bytes (g_variant_get_type (child_variant),
bytes, FALSE); bytes, FALSE);
@@ -4988,7 +4988,7 @@ test_recursion_limits_array_in_variant (void)
g_variant_unref (deserialised_variant); g_variant_unref (deserialised_variant);
/* Deserialise it again, but trusted this time. This should succeed. */ /* Deserialize it again, but trusted this time. This should succeed. */
deserialised_variant = g_variant_new_from_bytes (G_VARIANT_TYPE_VARIANT, deserialised_variant = g_variant_new_from_bytes (G_VARIANT_TYPE_VARIANT,
bytes, TRUE); bytes, TRUE);
g_assert_nonnull (deserialised_variant); g_assert_nonnull (deserialised_variant);