luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-09 04:15:49 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'serializ' into 'master'

Browse Source 
docs: Standardize spelling of serializ*

Closes #2399

See merge request GNOME/glib!2096
This commit is contained in:
Philip Withnall 2021-05-13 11:37:11 +00:00
commit 56ddba7c34
8 changed files with 193 additions and 193 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
gio/gemblemedicon.c
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...
*/ */

154
glib/gvariant-core.c
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.
* *

112
glib/gvariant-serialiser.c
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.

4
glib/gvariant-serialiser.h
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);

60
glib/gvariant.c
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

4
glib/gvarianttypeinfo.c
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.
*/ */

8
glib/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

42
glib/tests/gvariant.c
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);