mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-10 03:16:17 +01:00
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
parent
730cc864ef
commit
6b867cd474
@ -136,7 +136,7 @@ the dconf database.
|
||||
<term><option>get</option></term>
|
||||
<listitem><para>
|
||||
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>.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
@ -175,7 +175,7 @@ Queries the description of valid values for <replaceable>KEY</replaceable>.
|
||||
<term><option>set</option></term>
|
||||
<listitem><para>
|
||||
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>.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
@ -263,7 +263,7 @@
|
||||
<para>
|
||||
Used as a prefix for a GVariant type string (not a prefix for a format string, so <literal>&s</literal> is
|
||||
a valid format string but <literal>&@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
|
||||
<link linkend='gvariant-format-strings-pointers'>Pointers</link> below.
|
||||
</para>
|
||||
@ -946,7 +946,7 @@ data = g_variant_new_parsed ("(%o, {'brightness': {'value': <%i>, 'max': <%i>}})
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The '<code>&</code>' character is used to indicate that serialised data should be directly exchanged via a
|
||||
The '<code>&</code>' character is used to indicate that serialized data should be directly exchanged via a
|
||||
pointer.
|
||||
</para>
|
||||
<para>
|
||||
@ -954,7 +954,7 @@ data = g_variant_new_parsed ("(%o, {'brightness': {'value': <%i>, 'max': <%i>}})
|
||||
'<literal>&o</literal>' or '<code>&g</code>'). For
|
||||
<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>
|
||||
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
|
||||
always be properly nul-terminated.
|
||||
</para>
|
||||
|
||||
@ -431,7 +431,7 @@ g_emblemed_icon_serialize (GIcon *icon)
|
||||
icon_data = g_icon_serialize (node->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
|
||||
* of 'emblem' over and again...
|
||||
*/
|
||||
|
||||
@ -81,22 +81,22 @@ 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".
|
||||
*
|
||||
* "serialised form": A serialised GVariant instance stores its value in
|
||||
* the GVariant serialisation format. All
|
||||
* "serialized form": A serialized GVariant instance stores its value in
|
||||
* the GVariant serialization format. All
|
||||
* 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,
|
||||
* 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
|
||||
* the child values of the container (thus forming a tree).
|
||||
*
|
||||
* It is possible for an instance to transition from tree form to
|
||||
* serialised form. This happens, implicitly, if the serialised data is
|
||||
* requested (eg: via g_variant_get_data()). Serialised form instances
|
||||
* serialized form. This happens, implicitly, if the serialized data is
|
||||
* requested (eg: via g_variant_get_data()). Serialized form instances
|
||||
* never transition into tree form.
|
||||
*
|
||||
*
|
||||
@ -109,8 +109,8 @@ struct _GVariant
|
||||
* The type_info field never changes during the life of the
|
||||
* instance, so it can be accessed without a lock.
|
||||
*
|
||||
* size: this is the size of the serialised form for the instance, if it
|
||||
* is known. If the instance is in serialised form then it is, by
|
||||
* size: this is the size of the serialized form for the instance, if it
|
||||
* 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
|
||||
* 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
|
||||
@ -126,33 +126,33 @@ struct _GVariant
|
||||
* that, the size field can be accessed without a lock.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* .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
|
||||
* 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
|
||||
* them without holding a lock.
|
||||
*
|
||||
* .bytes: the #GBytes that contains the memory pointed to by
|
||||
* .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
|
||||
* the instance is freed, this reference must be released
|
||||
* 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.
|
||||
* #GBytes is responsible for memory management.
|
||||
*
|
||||
* 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
|
||||
* 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
|
||||
* entire proper fixed-size of this instance. In this
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
* be held while performing any operations on 'contents.tree'.
|
||||
*
|
||||
* .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()
|
||||
* called on it and the array must be freed using
|
||||
* g_free().
|
||||
@ -183,18 +183,18 @@ struct _GVariant
|
||||
* STATE_LOCKED: the instance lock is held. This is the bit used by
|
||||
* 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
|
||||
* form.
|
||||
*
|
||||
* STATE_TRUSTED: for serialised form instances, this means that the
|
||||
* serialised data is known to be in normal form (ie:
|
||||
* STATE_TRUSTED: for serialized form instances, this means that the
|
||||
* serialized data is known to be in normal form (ie:
|
||||
* not corrupted).
|
||||
*
|
||||
* For tree form instances, this means that all of the
|
||||
* child instances in the contents.tree.children array
|
||||
* 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.
|
||||
*
|
||||
* 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,
|
||||
* increasing with the level of nesting. The top-most GVariant has depth
|
||||
* 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_SERIALISED 2
|
||||
@ -249,7 +249,7 @@ g_variant_unlock (GVariant *value)
|
||||
* @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
|
||||
* serialised form.
|
||||
* serialized form.
|
||||
*
|
||||
* 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);
|
||||
}
|
||||
|
||||
/* 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
|
||||
* public API function, it has its definition elsewhere.
|
||||
*
|
||||
* Note that "serialisation" of an instance does not mean that the
|
||||
* instance is converted to serialised form -- it means that the
|
||||
* serialised form of an instance is written to an external buffer.
|
||||
* Note that "serialization" of an instance does not mean that the
|
||||
* instance is converted to serialized form -- it means that the
|
||||
* serialized form of an instance is written to an external buffer.
|
||||
* g_variant_ensure_serialised() (which is not part of this set of
|
||||
* 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
|
||||
* instances are always in serialised form. For these instances,
|
||||
* storing their serialised form merely involves a memcpy().
|
||||
* instances are always in serialized form. For these instances,
|
||||
* storing their serialized form merely involves a memcpy().
|
||||
*
|
||||
* Serialisation is a two-step process. First, the size of the
|
||||
* serialised data must be calculated so that an appropriately-sized
|
||||
* Serialization is a two-step process. First, the size of the
|
||||
* serialized data must be calculated so that an appropriately-sized
|
||||
* buffer can be allocated. Second, the data is written into the
|
||||
* buffer.
|
||||
*
|
||||
* Determining the size:
|
||||
* The process of determining the size is triggered by a call to
|
||||
* 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() 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
|
||||
* 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.
|
||||
*
|
||||
* Writing the data:
|
||||
* After the buffer has been allocated, g_variant_serialise() is
|
||||
* called on the container. This invokes the serialiser code to write
|
||||
* the bytes to the container. The serialiser is, again, passed
|
||||
* called on the container. This invokes the serializer code to write
|
||||
* the bytes to the container. The serializer is, again, passed
|
||||
* g_variant_fill_gvs() as a callback.
|
||||
*
|
||||
* 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
|
||||
* where it should write its data. This is done by calling
|
||||
* g_variant_store(). In the event that the instance is in serialised
|
||||
* form this means a memcpy() of the serialised data into the
|
||||
* g_variant_store(). In the event that the instance is in serialized
|
||||
* form this means a memcpy() of the serialized data into the
|
||||
* allocated buffer. In the event that the instance is in tree form
|
||||
* 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
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* The current thread must hold the lock on @value.
|
||||
@ -354,7 +354,7 @@ g_variant_ensure_size (GVariant *value)
|
||||
* @value: a #GVariant
|
||||
* @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.
|
||||
*
|
||||
@ -389,15 +389,15 @@ g_variant_serialise (GVariant *value,
|
||||
* @data: a #GVariant 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
|
||||
* actions:
|
||||
*
|
||||
* - 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
|
||||
g_variant_fill_gvs (GVariantSerialised *serialised,
|
||||
@ -425,18 +425,18 @@ g_variant_fill_gvs (GVariantSerialised *serialised,
|
||||
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 >
|
||||
* g_variant_ensure_serialised:
|
||||
* @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
|
||||
* serialised size is known and then allocates a buffer of that size and
|
||||
* serialises the instance into the buffer. The 'children' array is
|
||||
* then released and the instance is set to serialised form based on the
|
||||
* serialized size is known and then allocates a buffer of that size and
|
||||
* serializes the instance into the buffer. The 'children' array is
|
||||
* then released and the instance is set to serialized form based on the
|
||||
* contents of the buffer.
|
||||
*
|
||||
* The current thread must hold the lock on @value.
|
||||
@ -501,8 +501,8 @@ g_variant_alloc (const GVariantType *type,
|
||||
* @bytes: a #GBytes
|
||||
* @trusted: if the contents of @bytes are trusted
|
||||
*
|
||||
* Constructs a new serialised-mode #GVariant instance. This is the
|
||||
* inner interface for creation of new serialised values that gets
|
||||
* Constructs a new serialized-mode #GVariant instance. This is the
|
||||
* inner interface for creation of new serialized values that gets
|
||||
* called from various functions in gvariant.c.
|
||||
*
|
||||
* 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
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* @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
|
||||
* 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)
|
||||
* then this function is O(1). Otherwise, the size is calculated, an
|
||||
* operation which is approximately O(n) in the number of values
|
||||
* involved.
|
||||
*
|
||||
* Returns: the serialised size of @value
|
||||
* Returns: the serialized size of @value
|
||||
*
|
||||
* Since: 2.24
|
||||
**/
|
||||
@ -896,33 +896,33 @@ g_variant_get_size (GVariant *value)
|
||||
* g_variant_get_data:
|
||||
* @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
|
||||
* untrusted source. The returned data must not be freed; it remains
|
||||
* valid for as long as @value exists.
|
||||
*
|
||||
* If @value is a fixed-sized value that was deserialised from a
|
||||
* corrupted serialised container then %NULL may be returned. In this
|
||||
* If @value is a fixed-sized value that was deserialized from a
|
||||
* corrupted serialized container then %NULL may be returned. In this
|
||||
* 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
|
||||
* then %NULL is never returned.
|
||||
*
|
||||
* In the case that @value is already in serialised form, this function
|
||||
* is O(1). If the value is not already in serialised form,
|
||||
* serialisation occurs implicitly and is approximately O(n) in the size
|
||||
* In the case that @value is already in serialized form, this function
|
||||
* is O(1). If the value is not already in serialized form,
|
||||
* serialization 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
|
||||
* To deserialize the data returned by this function, in addition to 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
|
||||
* 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
|
||||
* %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).
|
||||
* 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
|
||||
**/
|
||||
@ -940,7 +940,7 @@ g_variant_get_data (GVariant *value)
|
||||
* g_variant_get_data_as_bytes:
|
||||
* @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
|
||||
* g_variant_get_data(), except that the returned #GBytes holds
|
||||
* 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
|
||||
* 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
|
||||
* g_variant_get_data() and optionally ignoring the return value.
|
||||
*
|
||||
@ -1092,8 +1092,8 @@ g_variant_get_child_value (GVariant *value,
|
||||
GVariantSerialised s_child;
|
||||
GVariant *child;
|
||||
|
||||
/* get the serialiser to extract the serialised data for the child
|
||||
* from the serialised data for the container
|
||||
/* get the serializer to extract the serialized data for the child
|
||||
* from the serialized data for the container
|
||||
*/
|
||||
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);
|
||||
}
|
||||
|
||||
/* create a new serialised instance out of it */
|
||||
/* create a new serialized instance out of it */
|
||||
child = g_slice_new (GVariant);
|
||||
child->type_info = s_child.type_info;
|
||||
child->state = (value->state & STATE_TRUSTED) |
|
||||
@ -1130,17 +1130,17 @@ g_variant_get_child_value (GVariant *value,
|
||||
/**
|
||||
* g_variant_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().
|
||||
*
|
||||
* The stored data is in machine native byte order but may not be in
|
||||
* 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
|
||||
* As with g_variant_get_data(), to be able to deserialize the
|
||||
* serialized 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.
|
||||
@ -1173,7 +1173,7 @@ g_variant_store (GVariant *value,
|
||||
* Checks if @value is in normal form.
|
||||
*
|
||||
* 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
|
||||
* check.
|
||||
*
|
||||
|
||||
@ -44,26 +44,26 @@
|
||||
* container and implements 5 functions for dealing with it:
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
* buffers can be preallocated before serialising.
|
||||
* buffers can be preallocated before serializing.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* is_normal:
|
||||
* - 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
|
||||
* 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
|
||||
* something other than zero bytes as padding) but only one form is
|
||||
* the normal form.
|
||||
@ -72,7 +72,7 @@
|
||||
* functions and logic to dispatch it to the handler for the appropriate
|
||||
* 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()
|
||||
* functions above to do its work so no extra support is needed on a
|
||||
* per-container-type basis.
|
||||
@ -90,17 +90,17 @@
|
||||
/* < private >
|
||||
* GVariantSerialised:
|
||||
* @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
|
||||
*
|
||||
* 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
|
||||
* primary interface to the serialiser. See #GVariantSerialisedFiller
|
||||
* primary interface to the serializer. See #GVariantSerialisedFiller
|
||||
* 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
|
||||
* returned from the serialiser.
|
||||
* returned from the serializer.
|
||||
*
|
||||
* @type_info must be non-%NULL.
|
||||
*
|
||||
@ -117,7 +117,7 @@
|
||||
* combination should be as if @data were a pointer to an
|
||||
* 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.
|
||||
*/
|
||||
|
||||
@ -185,9 +185,9 @@ g_variant_serialised_check (GVariantSerialised serialised)
|
||||
* from a partially-complete #GVariantSerialised.
|
||||
*
|
||||
* 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
|
||||
* serialised. The information filled in to @serialised is the
|
||||
* serialized. The information filled in to @serialised is the
|
||||
* information for this child.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
* the needed size of the child.
|
||||
*
|
||||
* 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
|
||||
* child. The callback must store the serialised form of the child at
|
||||
* aligned for and large enough to store the serialized data of the
|
||||
* child. The callback must store the serialized form of the child at
|
||||
* @data.
|
||||
*
|
||||
* 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_serialise() to write to @data.
|
||||
*/
|
||||
|
||||
/* PART 1: Container types {{{1
|
||||
*
|
||||
* This section contains the serialiser implementation functions for
|
||||
* This section contains the serializer implementation functions for
|
||||
* 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
|
||||
* 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
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
* 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
|
||||
* the "Just" case; in that case, the serialised data of the child value
|
||||
* forms the first part of the serialised data of the maybe value and is
|
||||
* the "Just" case; in that case, the serialized data of the child value
|
||||
* 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,
|
||||
* 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
|
||||
@ -424,8 +424,8 @@ gvs_variable_sized_maybe_is_normal (GVariantSerialised value)
|
||||
|
||||
/* Fixed-sized Array {{{3
|
||||
*
|
||||
* For fixed sized arrays, the serialised data is simply a concatenation
|
||||
* of the serialised data of each element, in order. Since fixed-sized
|
||||
* For fixed sized arrays, the serialized data is simply a concatenation
|
||||
* 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
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
* (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
|
||||
* 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
|
||||
* 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
|
||||
* deserialiser, only the smaller of the two is considered to be in
|
||||
* normal form and that is the one that the serialiser must produce.
|
||||
* deserializer, only the smaller of the two is considered to be in
|
||||
* normal form and that is the one that the serializer must produce.
|
||||
*/
|
||||
|
||||
/* bytes may be NULL if (size == 0). */
|
||||
@ -840,20 +840,20 @@ gvs_variable_sized_array_is_normal (GVariantSerialised value)
|
||||
/* Tuples {{{2
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
* total size of the tuple. For this reason, the last item in the tuple
|
||||
* doesn't need an offset stored.
|
||||
*
|
||||
* 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
|
||||
* for the tuple. See the notes in gvarianttypeinfo.h.
|
||||
@ -1158,7 +1158,7 @@ gvs_tuple_is_normal (GVariantSerialised value)
|
||||
|
||||
/* 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
|
||||
* 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.
|
||||
*/
|
||||
|
||||
@ -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.
|
||||
*/
|
||||
|
||||
@ -1348,7 +1348,7 @@ gvs_variant_is_normal (GVariantSerialised value)
|
||||
* g_variant_serialised_n_children:
|
||||
* @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
|
||||
* that container.
|
||||
*
|
||||
@ -1372,7 +1372,7 @@ g_variant_serialised_n_children (GVariantSerialised serialised)
|
||||
* @serialised: a #GVariantSerialised
|
||||
* @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.
|
||||
*
|
||||
* 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
|
||||
* @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 that we are serialising.
|
||||
* the type that we are serializing.
|
||||
*
|
||||
* The size field of @serialised must be filled in with the value
|
||||
* returned by a previous call to g_variant_serialiser_needed_size().
|
||||
*
|
||||
* 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).
|
||||
*
|
||||
* 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
|
||||
* order for all of the data of that child to be filled in.
|
||||
*/
|
||||
@ -1457,12 +1457,12 @@ g_variant_serialiser_serialise (GVariantSerialised serialised,
|
||||
|
||||
/* < private >
|
||||
* g_variant_serialiser_needed_size:
|
||||
* @type_info: the type to serialise for
|
||||
* @type_info: the type to serialize for
|
||||
* @gvs_filler: the filler function
|
||||
* @children: an array of child items
|
||||
* @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
|
||||
* 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:
|
||||
* @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.
|
||||
*/
|
||||
void
|
||||
@ -1577,9 +1577,9 @@ g_variant_serialised_byteswap (GVariantSerialised serialised)
|
||||
* @serialised: a #GVariantSerialised
|
||||
*
|
||||
* 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
|
||||
* with something other than zeros, but only one form is the normal
|
||||
* form.
|
||||
|
||||
@ -31,14 +31,14 @@ typedef struct
|
||||
gsize depth; /* same semantics as GVariant.depth */
|
||||
} GVariantSerialised;
|
||||
|
||||
/* deserialisation */
|
||||
/* deserialization */
|
||||
GLIB_AVAILABLE_IN_ALL
|
||||
gsize g_variant_serialised_n_children (GVariantSerialised container);
|
||||
GLIB_AVAILABLE_IN_ALL
|
||||
GVariantSerialised g_variant_serialised_get_child (GVariantSerialised container,
|
||||
gsize index);
|
||||
|
||||
/* serialisation */
|
||||
/* serialization */
|
||||
typedef void (*GVariantSerialisedFiller) (GVariantSerialised *serialised,
|
||||
gpointer data);
|
||||
|
||||
|
||||
@ -84,19 +84,19 @@
|
||||
* concurrently accessed in any way from any number of threads without
|
||||
* 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
|
||||
* 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.
|
||||
* 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 instances can be sent over D-Bus. See #GVariantType for
|
||||
* exceptions. (However, #GVariant's serialisation format is not the same
|
||||
* as the serialisation format of a D-Bus message body: use #GDBusMessage,
|
||||
* exceptions. (However, #GVariant's serialization format is not the same
|
||||
* as the serialization format of a D-Bus message body: use #GDBusMessage,
|
||||
* 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,
|
||||
* which must either be implied from context (such as knowledge that a
|
||||
* particular file format always contains a little-endian
|
||||
@ -126,14 +126,14 @@
|
||||
* in the future.
|
||||
*
|
||||
* 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
|
||||
* #GVariant structure itself.
|
||||
*
|
||||
* ## Serialised Data Memory
|
||||
* ## Serialized Data Memory
|
||||
*
|
||||
* 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
|
||||
* 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.
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
* type "a{sv}" then a type information struct will exist for
|
||||
@ -238,14 +238,14 @@
|
||||
* ## Buffer Management Memory
|
||||
*
|
||||
* #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
|
||||
* 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
|
||||
* even g_mapped_file_unref().
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* ## GVariant structure
|
||||
@ -255,7 +255,7 @@
|
||||
*
|
||||
* #GVariant structures only exist if they are explicitly created
|
||||
* 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
|
||||
* entire dictionary (two keys, two values, two variants containing
|
||||
* the values, two dictionary entries, plus the dictionary itself),
|
||||
@ -265,8 +265,8 @@
|
||||
* If calls are made to start accessing the other values then
|
||||
* #GVariant instances will exist for those values only for as long
|
||||
* as they are in use (ie: until you call g_variant_unref()). The
|
||||
* type information is shared. The serialised data and the buffer
|
||||
* management structure for that serialised data is shared by the
|
||||
* type information is shared. The serialized data and the buffer
|
||||
* management structure for that serialized data is shared by the
|
||||
* child.
|
||||
*
|
||||
* ## Summary
|
||||
@ -274,12 +274,12 @@
|
||||
* To put the entire example together, for our dictionary mapping
|
||||
* strings to variants (with two entries, as given above), we are
|
||||
* 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
|
||||
* malloc overhead. If we were to use g_variant_get_child_value() to
|
||||
* access the two dictionary entries, we would use an additional 48
|
||||
* 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
|
||||
* 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
|
||||
* @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.
|
||||
*
|
||||
* @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,
|
||||
* 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
|
||||
* 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,
|
||||
* 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.
|
||||
*
|
||||
* @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.
|
||||
* 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
|
||||
* 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.
|
||||
*
|
||||
* @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))
|
||||
return FALSE;
|
||||
|
||||
/* if both values are trusted to be in their canonical serialised form
|
||||
* then a simple memcmp() of their serialised data will answer the
|
||||
/* if both values are trusted to be in their canonical serialized form
|
||||
* then a simple memcmp() of their serialized data will answer the
|
||||
* question.
|
||||
*
|
||||
* 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;
|
||||
}
|
||||
|
||||
/* Serialised data {{{1 */
|
||||
/* Serialized data {{{1 */
|
||||
static GVariant *
|
||||
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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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:
|
||||
* @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
|
||||
* @trusted: %TRUE if @data is definitely in normal form
|
||||
* @notify: (scope async): function to call when @data is no longer needed
|
||||
* @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.
|
||||
* 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
|
||||
* the result is undefined.
|
||||
*
|
||||
* If @data is trusted to be serialised data in normal form then
|
||||
* @trusted should be %TRUE. This applies to serialised data created
|
||||
* If @data is trusted to be serialized data in normal form then
|
||||
* @trusted should be %TRUE. This applies to serialized data created
|
||||
* within this process or read from a trusted location on the disk (such
|
||||
* as a file installed in /usr/lib alongside your application). You
|
||||
* should set trusted to %FALSE if @data is read from the network, a
|
||||
|
||||
@ -32,7 +32,7 @@
|
||||
* GVariantTypeInfo:
|
||||
*
|
||||
* 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
|
||||
* structures to provide for efficient operation.
|
||||
*
|
||||
@ -93,7 +93,7 @@ typedef struct
|
||||
} ArrayInfo;
|
||||
|
||||
/* 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
|
||||
* comment on GVariantMemberInfo in gvarianttypeinfo.h.
|
||||
*/
|
||||
|
||||
@ -40,18 +40,18 @@ typedef struct _GVariantTypeInfo GVariantTypeInfo;
|
||||
* corresponding to a given child of a tuple or dictionary entry in a
|
||||
* very short constant time. It contains the typeinfo of the child,
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
* refer to tuples and dictionary entries.
|
||||
*
|
||||
* 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
|
||||
* 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
|
||||
* 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
|
||||
|
||||
@ -997,7 +997,7 @@ check_offsets (GVariantTypeInfo *info,
|
||||
position++;
|
||||
|
||||
/* and store the offset, just like it would be in the
|
||||
* serialised data.
|
||||
* serialized data.
|
||||
*/
|
||||
last_offset = position;
|
||||
last_offset_index++;
|
||||
@ -1093,7 +1093,7 @@ test_gvarianttypeinfo (void)
|
||||
#define MAX_TUPLE_CHILDREN 128
|
||||
|
||||
/* 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:
|
||||
* - test different alignments
|
||||
@ -2311,19 +2311,19 @@ test_serialiser_children (void)
|
||||
g_test_summary ("Test that getting a child variant before and after "
|
||||
"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. */
|
||||
child = g_variant_new_maybe (G_VARIANT_TYPE_VARIANT, NULL);
|
||||
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);
|
||||
data1 = g_variant_get_data_as_bytes (child1);
|
||||
|
||||
/* Serialise the parent variant. */
|
||||
/* Serialize the parent 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);
|
||||
data2 = g_variant_get_data_as_bytes (child2);
|
||||
|
||||
@ -2348,7 +2348,7 @@ test_fuzz (gdouble *fuzziness)
|
||||
/* make an instance */
|
||||
tree = tree_instance_new (NULL, 3);
|
||||
|
||||
/* serialise it */
|
||||
/* serialize it */
|
||||
serialise_tree (tree, &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:
|
||||
*
|
||||
* - the serialised data now represents a different value:
|
||||
* - the serialized data now represents a different value:
|
||||
* 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
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
a = g_variant_serialised_is_normal (serialised);
|
||||
@ -3743,9 +3743,9 @@ test_gv_byteswap (void)
|
||||
# define swapped16(x) x, 0
|
||||
#endif
|
||||
/* all kinds of of crazy randomised testing already performed on the
|
||||
* byteswapper in the /gvariant/serialiser/byteswap test and all kinds
|
||||
* of crazy randomised testing performed against the serialiser
|
||||
* normalisation functions in the /gvariant/serialiser/fuzz/ tests.
|
||||
* byteswapper in the /gvariant/serializer/byteswap test and all kinds
|
||||
* of crazy randomised testing performed against the serializer
|
||||
* normalisation functions in the /gvariant/serializer/fuzz/ tests.
|
||||
*
|
||||
* just test a few simple cases here to make sure they each work
|
||||
*/
|
||||
@ -4755,7 +4755,7 @@ test_gbytes (void)
|
||||
g_bytes_unref (bytes2);
|
||||
|
||||
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);
|
||||
bytes2 = g_variant_get_data_as_bytes (a);
|
||||
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
|
||||
* deserialised from untrusted data.*/
|
||||
* deserialized from untrusted data.*/
|
||||
static 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++)
|
||||
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);
|
||||
deserialised_variant = g_variant_new_from_bytes (G_VARIANT_TYPE_VARIANT,
|
||||
bytes, FALSE);
|
||||
@ -4935,7 +4935,7 @@ test_recursion_limits_variant_in_variant (void)
|
||||
|
||||
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,
|
||||
bytes, TRUE);
|
||||
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
|
||||
* 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,
|
||||
* have a static #GVariantType which is too deep — only when nested together do
|
||||
* 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++)
|
||||
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);
|
||||
deserialised_variant = g_variant_new_from_bytes (g_variant_get_type (child_variant),
|
||||
bytes, FALSE);
|
||||
@ -4988,7 +4988,7 @@ test_recursion_limits_array_in_variant (void)
|
||||
|
||||
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,
|
||||
bytes, TRUE);
|
||||
g_assert_nonnull (deserialised_variant);
|
||||
|
||||
Loading…
Reference in New Issue
Block a user