2 * Copyright © 2007, 2008 Ryan Lortie
3 * Copyright © 2010 Codethink Limited
5 * SPDX-License-Identifier: LGPL-2.1-or-later
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
20 * Author: Ryan Lortie <desrt@desrt.ca>
26 #include "gvariant-serialiser.h"
28 #include <glib/gvariant-internal.h>
29 #include <glib/gtestutils.h>
30 #include <glib/gstrfuncs.h>
31 #include <glib/gtypes.h>
38 * After this prologue section, this file has roughly 2 parts.
40 * The first part is split up into sections according to various
41 * container types. Maybe, Array, Tuple, Variant. The Maybe and Array
42 * sections are subdivided for element types being fixed or
43 * variable-sized types.
45 * Each section documents the format of that particular type of
46 * container and implements 5 functions for dealing with it:
49 * - determines (according to serialized data) how many child values
50 * are inside a particular container value.
53 * - gets the type of and the serialized data corresponding to a
54 * given child value within the container value.
57 * - determines how much space would be required to serialize a
58 * container of this type, containing the given children so that
59 * buffers can be preallocated before serializing.
62 * - write the serialized data for a container of this type,
63 * containing the given children, to a buffer.
66 * - check the given data to ensure that it is in normal form. For a
67 * given set of child values, there is exactly one normal form for
68 * the serialized data of a container. Other forms are possible
69 * while maintaining the same children (for example, by inserting
70 * something other than zero bytes as padding) but only one form is
73 * The second part contains the main entry point for each of the above 5
74 * functions and logic to dispatch it to the handler for the appropriate
75 * container type code.
77 * The second part also contains a routine to byteswap serialized
78 * values. This code makes use of the n_children() and get_child()
79 * functions above to do its work so no extra support is needed on a
80 * per-container-type basis.
82 * There is also additional code for checking for normal form. All
83 * numeric types are always in normal form since the full range of
84 * values is permitted (eg: 0 to 255 is a valid byte). Special checks
85 * need to be performed for booleans (only 0 or 1 allowed), strings
86 * (properly nul-terminated) and object paths and signature strings
87 * (meeting the D-Bus specification requirements). Depth checks need to be
88 * performed for nested types (arrays, tuples, and variants), to avoid massive
89 * recursion which could exhaust our stack when handling untrusted input.
94 * @type_info: the #GVariantTypeInfo of this value
95 * @data: (nullable): the serialized data of this value, or %NULL
96 * @size: the size of this value
98 * A structure representing a GVariant in serialized form. This
99 * structure is used with #GVariantSerialisedFiller functions and as the
100 * primary interface to the serializer. See #GVariantSerialisedFiller
101 * for a description of its use there.
103 * When used with the serializer API functions, the following invariants
104 * apply to all #GVariantTypeSerialised structures passed to and
105 * returned from the serializer.
107 * @type_info must be non-%NULL.
109 * @data must be properly aligned for the type described by @type_info.
111 * If @type_info describes a fixed-sized type then @size must always be
112 * equal to the fixed size of that type.
114 * For fixed-sized types (and only fixed-sized types), @data may be
115 * %NULL even if @size is non-zero. This happens when a framing error
116 * occurs while attempting to extract a fixed-sized value out of a
117 * variable-sized container. There is no data to return for the
118 * fixed-sized type, yet @size must be non-zero. The effect of this
119 * combination should be as if @data were a pointer to an
120 * appropriately-sized zero-filled region.
122 * @depth has no restrictions; the depth of a top-level serialized #GVariant is
123 * zero, and it increases for each level of nested child.
127 * g_variant_serialised_check:
128 * @serialised: a #GVariantSerialised struct
130 * Checks @serialised for validity according to the invariants described
133 * Returns: %TRUE if @serialised is valid; %FALSE otherwise
136 g_variant_serialised_check (GVariantSerialised serialised)
141 if (serialised.type_info == NULL)
143 g_variant_type_info_query (serialised.type_info, &alignment, &fixed_size);
145 if (fixed_size != 0 && serialised.size != fixed_size)
147 else if (fixed_size == 0 &&
148 !(serialised.size == 0 || serialised.data != NULL))
151 /* Depending on the native alignment requirements of the machine, the
152 * compiler will insert either 3 or 7 padding bytes after the char.
153 * This will result in the sizeof() the struct being 12 or 16.
154 * Subtract 9 to get 3 or 7 which is a nice bitmask to apply to get
155 * the alignment bits that we "care about" being zero: in the
156 * 4-aligned case, we care about 2 bits, and in the 8-aligned case, we
159 alignment &= sizeof (struct {
169 /* Some OSes (FreeBSD is a known example) have a malloc() that returns
170 * unaligned memory if you request small sizes. 'malloc (1);', for
171 * example, has been seen to return pointers aligned to 6 mod 16.
173 * Check if this is a small allocation and return without enforcing
174 * the alignment assertion if this is the case.
176 return (serialised.size <= alignment ||
177 (alignment & (gsize) serialised.data) == 0);
181 * GVariantSerialisedFiller:
182 * @serialised: a #GVariantSerialised instance to fill
183 * @data: data from the children array
185 * This function is called back from g_variant_serialiser_needed_size()
186 * and g_variant_serialiser_serialise(). It fills in missing details
187 * from a partially-complete #GVariantSerialised.
189 * The @data parameter passed back to the function is one of the items
190 * that was passed to the serializer in the @children array. It
191 * represents a single child item of the container that is being
192 * serialized. The information filled in to @serialised is the
193 * information for this child.
195 * If the @type_info field of @serialised is %NULL then the callback
196 * function must set it to the type information corresponding to the
197 * type of the child. No reference should be added. If it is non-%NULL
198 * then the callback should assert that it is equal to the actual type
201 * If the @size field is zero then the callback must fill it in with the
202 * required amount of space to store the serialized form of the child.
203 * If it is non-zero then the callback should assert that it is equal to
204 * the needed size of the child.
206 * If @data is non-%NULL then it points to a space that is properly
207 * aligned for and large enough to store the serialized data of the
208 * child. The callback must store the serialized form of the child at
211 * If the child value is another container then the callback will likely
212 * recurse back into the serializer by calling
213 * g_variant_serialiser_needed_size() to determine @size and
214 * g_variant_serialiser_serialise() to write to @data.
217 /* PART 1: Container types {{{1
219 * This section contains the serializer implementation functions for
220 * each container type.
225 * Maybe types are handled depending on if the element type of the maybe
226 * type is a fixed-sized or variable-sized type. Although all maybe
227 * types themselves are variable-sized types, herein, a maybe value with
228 * a fixed-sized element type is called a "fixed-sized maybe" for
229 * convenience and a maybe value with a variable-sized element type is
230 * called a "variable-sized maybe".
233 /* Fixed-sized Maybe {{{3
235 * The size of a maybe value with a fixed-sized element type is either 0
236 * or equal to the fixed size of its element type. The case where the
237 * size of the maybe value is zero corresponds to the "Nothing" case and
238 * the case where the size of the maybe value is equal to the fixed size
239 * of the element type corresponds to the "Just" case; in that case, the
240 * serialized data of the child value forms the entire serialized data
241 * of the maybe value.
243 * In the event that a fixed-sized maybe value is presented with a size
244 * that is not equal to the fixed size of the element type then the
245 * value must be taken to be "Nothing".
249 gvs_fixed_sized_maybe_n_children (GVariantSerialised value)
251 gsize element_fixed_size;
253 g_variant_type_info_query_element (value.type_info, NULL,
254 &element_fixed_size);
256 return (element_fixed_size == value.size) ? 1 : 0;
259 static GVariantSerialised
260 gvs_fixed_sized_maybe_get_child (GVariantSerialised value,
263 /* the child has the same bounds as the
264 * container, so just update the type.
266 value.type_info = g_variant_type_info_element (value.type_info);
267 g_variant_type_info_ref (value.type_info);
274 gvs_fixed_sized_maybe_needed_size (GVariantTypeInfo *type_info,
275 GVariantSerialisedFiller gvs_filler,
276 const gpointer *children,
281 gsize element_fixed_size;
283 g_variant_type_info_query_element (type_info, NULL,
284 &element_fixed_size);
286 return element_fixed_size;
293 gvs_fixed_sized_maybe_serialise (GVariantSerialised value,
294 GVariantSerialisedFiller gvs_filler,
295 const gpointer *children,
300 GVariantSerialised child = { NULL, value.data, value.size, value.depth + 1 };
302 gvs_filler (&child, children[0]);
307 gvs_fixed_sized_maybe_is_normal (GVariantSerialised value)
311 gsize element_fixed_size;
313 g_variant_type_info_query_element (value.type_info,
314 NULL, &element_fixed_size);
316 if (value.size != element_fixed_size)
319 /* proper element size: "Just". recurse to the child. */
320 value.type_info = g_variant_type_info_element (value.type_info);
323 return g_variant_serialised_is_normal (value);
326 /* size of 0: "Nothing" */
330 /* Variable-sized Maybe
332 * The size of a maybe value with a variable-sized element type is
333 * either 0 or strictly greater than 0. The case where the size of the
334 * maybe value is zero corresponds to the "Nothing" case and the case
335 * where the size of the maybe value is greater than zero corresponds to
336 * the "Just" case; in that case, the serialized data of the child value
337 * forms the first part of the serialized data of the maybe value and is
338 * followed by a single zero byte. This zero byte is always appended,
339 * regardless of any zero bytes that may already be at the end of the
340 * serialized ata of the child value.
344 gvs_variable_sized_maybe_n_children (GVariantSerialised value)
346 return (value.size > 0) ? 1 : 0;
349 static GVariantSerialised
350 gvs_variable_sized_maybe_get_child (GVariantSerialised value,
353 /* remove the padding byte and update the type. */
354 value.type_info = g_variant_type_info_element (value.type_info);
355 g_variant_type_info_ref (value.type_info);
358 /* if it's zero-sized then it may as well be NULL */
368 gvs_variable_sized_maybe_needed_size (GVariantTypeInfo *type_info,
369 GVariantSerialisedFiller gvs_filler,
370 const gpointer *children,
375 GVariantSerialised child = { 0, };
377 gvs_filler (&child, children[0]);
379 return child.size + 1;
386 gvs_variable_sized_maybe_serialise (GVariantSerialised value,
387 GVariantSerialisedFiller gvs_filler,
388 const gpointer *children,
393 GVariantSerialised child = { NULL, value.data, value.size - 1, value.depth + 1 };
395 /* write the data for the child. */
396 gvs_filler (&child, children[0]);
397 value.data[child.size] = '\0';
402 gvs_variable_sized_maybe_is_normal (GVariantSerialised value)
407 if (value.data[value.size - 1] != '\0')
410 value.type_info = g_variant_type_info_element (value.type_info);
414 return g_variant_serialised_is_normal (value);
419 * Just as with maybe types, array types are handled depending on if the
420 * element type of the array type is a fixed-sized or variable-sized
421 * type. Similar to maybe types, for convenience, an array value with a
422 * fixed-sized element type is called a "fixed-sized array" and an array
423 * value with a variable-sized element type is called a "variable sized
427 /* Fixed-sized Array {{{3
429 * For fixed sized arrays, the serialized data is simply a concatenation
430 * of the serialized data of each element, in order. Since fixed-sized
431 * values always have a fixed size that is a multiple of their alignment
432 * requirement no extra padding is required.
434 * In the event that a fixed-sized array is presented with a size that
435 * is not an integer multiple of the element size then the value of the
436 * array must be taken as being empty.
440 gvs_fixed_sized_array_n_children (GVariantSerialised value)
442 gsize element_fixed_size;
444 g_variant_type_info_query_element (value.type_info, NULL,
445 &element_fixed_size);
447 if (value.size % element_fixed_size == 0)
448 return value.size / element_fixed_size;
453 static GVariantSerialised
454 gvs_fixed_sized_array_get_child (GVariantSerialised value,
457 GVariantSerialised child = { 0, };
459 child.type_info = g_variant_type_info_element (value.type_info);
460 g_variant_type_info_query (child.type_info, NULL, &child.size);
461 child.data = value.data + (child.size * index_);
462 g_variant_type_info_ref (child.type_info);
463 child.depth = value.depth + 1;
469 gvs_fixed_sized_array_needed_size (GVariantTypeInfo *type_info,
470 GVariantSerialisedFiller gvs_filler,
471 const gpointer *children,
474 gsize element_fixed_size;
476 g_variant_type_info_query_element (type_info, NULL, &element_fixed_size);
478 return element_fixed_size * n_children;
482 gvs_fixed_sized_array_serialise (GVariantSerialised value,
483 GVariantSerialisedFiller gvs_filler,
484 const gpointer *children,
487 GVariantSerialised child = { 0, };
490 child.type_info = g_variant_type_info_element (value.type_info);
491 g_variant_type_info_query (child.type_info, NULL, &child.size);
492 child.data = value.data;
493 child.depth = value.depth + 1;
495 for (i = 0; i < n_children; i++)
497 gvs_filler (&child, children[i]);
498 child.data += child.size;
503 gvs_fixed_sized_array_is_normal (GVariantSerialised value)
505 GVariantSerialised child = { 0, };
507 child.type_info = g_variant_type_info_element (value.type_info);
508 g_variant_type_info_query (child.type_info, NULL, &child.size);
509 child.depth = value.depth + 1;
511 if (value.size % child.size != 0)
514 for (child.data = value.data;
515 child.data < value.data + value.size;
516 child.data += child.size)
518 if (!g_variant_serialised_is_normal (child))
525 /* Variable-sized Array {{{3
527 * Variable sized arrays, containing variable-sized elements, must be
528 * able to determine the boundaries between the elements. The items
529 * cannot simply be concatenated. Additionally, we are faced with the
530 * fact that non-fixed-sized values do not necessarily have a size that
531 * is a multiple of their alignment requirement, so we may need to
532 * insert zero-filled padding.
534 * While it is possible to find the start of an item by starting from
535 * the end of the item before it and padding for alignment, it is not
536 * generally possible to do the reverse operation. For this reason, we
537 * record the end point of each element in the array.
539 * GVariant works in terms of "offsets". An offset is a pointer to a
540 * boundary between two bytes. In 4 bytes of serialized data, there
541 * would be 5 possible offsets: one at the start ('0'), one between each
542 * pair of adjacent bytes ('1', '2', '3') and one at the end ('4').
544 * The numeric value of an offset is an unsigned integer given relative
545 * to the start of the serialized data of the array. Offsets are always
546 * stored in little endian byte order and are always only as big as they
547 * need to be. For example, in 255 bytes of serialized data, there are
548 * 256 offsets. All possibilities can be stored in an 8 bit unsigned
549 * integer. In 256 bytes of serialized data, however, there are 257
550 * possible offsets so 16 bit integers must be used. The size of an
551 * offset is always a power of 2.
553 * The offsets are stored at the end of the serialized data of the
554 * array. They are simply concatenated on without any particular
555 * alignment. The size of the offsets is included in the size of the
556 * serialized data for purposes of determining the size of the offsets.
557 * This presents a possibly ambiguity; in certain cases, a particular
558 * value of array could have two different serialized forms.
560 * Imagine an array containing a single string of 253 bytes in length
561 * (so, 254 bytes including the nul terminator). Now the offset must be
562 * written. If an 8 bit offset is written, it will bring the size of
563 * the array's serialized data to 255 -- which means that the use of an
564 * 8 bit offset was valid. If a 16 bit offset is used then the total
565 * size of the array will be 256 -- which means that the use of a 16 bit
566 * offset was valid. Although both of these will be accepted by the
567 * deserializer, only the smaller of the two is considered to be in
568 * normal form and that is the one that the serializer must produce.
571 /* bytes may be NULL if (size == 0). */
573 gvs_read_unaligned_le (guchar *bytes,
578 guchar bytes[GLIB_SIZEOF_SIZE_T];
582 tmpvalue.integer = 0;
584 memcpy (&tmpvalue.bytes, bytes, size);
586 return GSIZE_FROM_LE (tmpvalue.integer);
590 gvs_write_unaligned_le (guchar *bytes,
596 guchar bytes[GLIB_SIZEOF_SIZE_T];
600 tmpvalue.integer = GSIZE_TO_LE (value);
601 memcpy (bytes, &tmpvalue.bytes, size);
605 gvs_get_offset_size (gsize size)
607 if (size > G_MAXUINT32)
610 else if (size > G_MAXUINT16)
613 else if (size > G_MAXUINT8)
623 gvs_calculate_total_size (gsize body_size,
626 if (body_size + 1 * offsets <= G_MAXUINT8)
627 return body_size + 1 * offsets;
629 if (body_size + 2 * offsets <= G_MAXUINT16)
630 return body_size + 2 * offsets;
632 if (body_size + 4 * offsets <= G_MAXUINT32)
633 return body_size + 4 * offsets;
635 return body_size + 8 * offsets;
639 gvs_variable_sized_array_n_children (GVariantSerialised value)
641 gsize offsets_array_size;
648 offset_size = gvs_get_offset_size (value.size);
650 last_end = gvs_read_unaligned_le (value.data + value.size -
651 offset_size, offset_size);
653 if (last_end > value.size)
656 offsets_array_size = value.size - last_end;
658 if (offsets_array_size % offset_size)
661 return offsets_array_size / offset_size;
664 static GVariantSerialised
665 gvs_variable_sized_array_get_child (GVariantSerialised value,
668 GVariantSerialised child = { 0, };
674 child.type_info = g_variant_type_info_element (value.type_info);
675 g_variant_type_info_ref (child.type_info);
676 child.depth = value.depth + 1;
678 offset_size = gvs_get_offset_size (value.size);
680 last_end = gvs_read_unaligned_le (value.data + value.size -
681 offset_size, offset_size);
687 start = gvs_read_unaligned_le (value.data + last_end +
688 (offset_size * (index_ - 1)),
691 g_variant_type_info_query (child.type_info, &alignment, NULL);
692 start += (-start) & alignment;
697 end = gvs_read_unaligned_le (value.data + last_end +
698 (offset_size * index_),
701 if (start < end && end <= value.size && end <= last_end)
703 child.data = value.data + start;
704 child.size = end - start;
711 gvs_variable_sized_array_needed_size (GVariantTypeInfo *type_info,
712 GVariantSerialisedFiller gvs_filler,
713 const gpointer *children,
720 g_variant_type_info_query (type_info, &alignment, NULL);
723 for (i = 0; i < n_children; i++)
725 GVariantSerialised child = { 0, };
727 offset += (-offset) & alignment;
728 gvs_filler (&child, children[i]);
729 offset += child.size;
732 return gvs_calculate_total_size (offset, n_children);
736 gvs_variable_sized_array_serialise (GVariantSerialised value,
737 GVariantSerialisedFiller gvs_filler,
738 const gpointer *children,
747 g_variant_type_info_query (value.type_info, &alignment, NULL);
748 offset_size = gvs_get_offset_size (value.size);
751 offset_ptr = value.data + value.size - offset_size * n_children;
753 for (i = 0; i < n_children; i++)
755 GVariantSerialised child = { 0, };
757 while (offset & alignment)
758 value.data[offset++] = '\0';
760 child.data = value.data + offset;
761 gvs_filler (&child, children[i]);
762 offset += child.size;
764 gvs_write_unaligned_le (offset_ptr, offset, offset_size);
765 offset_ptr += offset_size;
770 gvs_variable_sized_array_is_normal (GVariantSerialised value)
772 GVariantSerialised child = { 0, };
773 gsize offsets_array_size;
774 guchar *offsets_array;
785 offset_size = gvs_get_offset_size (value.size);
786 last_end = gvs_read_unaligned_le (value.data + value.size -
787 offset_size, offset_size);
789 if (last_end > value.size)
792 offsets_array_size = value.size - last_end;
794 if (offsets_array_size % offset_size)
797 offsets_array = value.data + value.size - offsets_array_size;
798 length = offsets_array_size / offset_size;
803 child.type_info = g_variant_type_info_element (value.type_info);
804 g_variant_type_info_query (child.type_info, &alignment, NULL);
805 child.depth = value.depth + 1;
808 for (i = 0; i < length; i++)
812 this_end = gvs_read_unaligned_le (offsets_array + offset_size * i,
815 if (this_end < offset || this_end > last_end)
818 while (offset & alignment)
820 if (!(offset < this_end && value.data[offset] == '\0'))
825 child.data = value.data + offset;
826 child.size = this_end - offset;
831 if (!g_variant_serialised_is_normal (child))
837 g_assert (offset == last_end);
844 * Since tuples can contain a mix of variable- and fixed-sized items,
845 * they are, in terms of serialization, a hybrid of variable-sized and
846 * fixed-sized arrays.
848 * Offsets are only stored for variable-sized items. Also, since the
849 * number of items in a tuple is known from its type, we are able to
850 * know exactly how many offsets to expect in the serialized data (and
851 * therefore how much space is taken up by the offset array). This
852 * means that we know where the end of the serialized data for the last
853 * item is -- we can just subtract the size of the offset array from the
854 * total size of the tuple. For this reason, the last item in the tuple
855 * doesn't need an offset stored.
857 * Tuple offsets are stored in reverse. This design choice allows
858 * iterator-based deserializers to be more efficient.
860 * Most of the "heavy lifting" here is handled by the GVariantTypeInfo
861 * for the tuple. See the notes in gvarianttypeinfo.h.
865 gvs_tuple_n_children (GVariantSerialised value)
867 return g_variant_type_info_n_members (value.type_info);
870 static GVariantSerialised
871 gvs_tuple_get_child (GVariantSerialised value,
874 const GVariantMemberInfo *member_info;
875 GVariantSerialised child = { 0, };
877 gsize start, end, last_end;
879 member_info = g_variant_type_info_member_info (value.type_info, index_);
880 child.type_info = g_variant_type_info_ref (member_info->type_info);
881 child.depth = value.depth + 1;
882 offset_size = gvs_get_offset_size (value.size);
884 /* tuples are the only (potentially) fixed-sized containers, so the
885 * only ones that have to deal with the possibility of having %NULL
886 * data with a non-zero %size if errors occurred elsewhere.
888 if G_UNLIKELY (value.data == NULL && value.size != 0)
890 g_variant_type_info_query (child.type_info, NULL, &child.size);
892 /* this can only happen in fixed-sized tuples,
893 * so the child must also be fixed sized.
895 g_assert (child.size != 0);
901 if (member_info->ending_type == G_VARIANT_MEMBER_ENDING_OFFSET)
903 if (offset_size * (member_info->i + 2) > value.size)
908 if (offset_size * (member_info->i + 1) > value.size)
910 /* if the child is fixed size, return its size.
911 * if child is not fixed-sized, return size = 0.
913 g_variant_type_info_query (child.type_info, NULL, &child.size);
919 if (member_info->i + 1)
920 start = gvs_read_unaligned_le (value.data + value.size -
921 offset_size * (member_info->i + 1),
926 start += member_info->a;
927 start &= member_info->b;
928 start |= member_info->c;
930 if (member_info->ending_type == G_VARIANT_MEMBER_ENDING_LAST)
931 end = value.size - offset_size * (member_info->i + 1);
933 else if (member_info->ending_type == G_VARIANT_MEMBER_ENDING_FIXED)
937 g_variant_type_info_query (child.type_info, NULL, &fixed_size);
938 end = start + fixed_size;
939 child.size = fixed_size;
942 else /* G_VARIANT_MEMBER_ENDING_OFFSET */
943 end = gvs_read_unaligned_le (value.data + value.size -
944 offset_size * (member_info->i + 2),
947 /* The child should not extend into the offset table. */
948 if (index_ != g_variant_type_info_n_members (value.type_info) - 1)
950 GVariantSerialised last_child;
951 last_child = gvs_tuple_get_child (value,
952 g_variant_type_info_n_members (value.type_info) - 1);
953 last_end = last_child.data + last_child.size - value.data;
954 g_variant_type_info_unref (last_child.type_info);
959 if (start < end && end <= value.size && end <= last_end)
961 child.data = value.data + start;
962 child.size = end - start;
969 gvs_tuple_needed_size (GVariantTypeInfo *type_info,
970 GVariantSerialisedFiller gvs_filler,
971 const gpointer *children,
974 const GVariantMemberInfo *member_info = NULL;
979 g_variant_type_info_query (type_info, NULL, &fixed_size);
986 for (i = 0; i < n_children; i++)
990 member_info = g_variant_type_info_member_info (type_info, i);
991 g_variant_type_info_query (member_info->type_info,
992 &alignment, &fixed_size);
993 offset += (-offset) & alignment;
996 offset += fixed_size;
999 GVariantSerialised child = { 0, };
1001 gvs_filler (&child, children[i]);
1002 offset += child.size;
1006 return gvs_calculate_total_size (offset, member_info->i + 1);
1010 gvs_tuple_serialise (GVariantSerialised value,
1011 GVariantSerialisedFiller gvs_filler,
1012 const gpointer *children,
1019 offset_size = gvs_get_offset_size (value.size);
1022 for (i = 0; i < n_children; i++)
1024 const GVariantMemberInfo *member_info;
1025 GVariantSerialised child = { 0, };
1028 member_info = g_variant_type_info_member_info (value.type_info, i);
1029 g_variant_type_info_query (member_info->type_info, &alignment, NULL);
1031 while (offset & alignment)
1032 value.data[offset++] = '\0';
1034 child.data = value.data + offset;
1035 gvs_filler (&child, children[i]);
1036 offset += child.size;
1038 if (member_info->ending_type == G_VARIANT_MEMBER_ENDING_OFFSET)
1040 value.size -= offset_size;
1041 gvs_write_unaligned_le (value.data + value.size,
1042 offset, offset_size);
1046 while (offset < value.size)
1047 value.data[offset++] = '\0';
1051 gvs_tuple_is_normal (GVariantSerialised value)
1059 /* as per the comment in gvs_tuple_get_child() */
1060 if G_UNLIKELY (value.data == NULL && value.size != 0)
1063 offset_size = gvs_get_offset_size (value.size);
1064 length = g_variant_type_info_n_members (value.type_info);
1065 offset_ptr = value.size;
1068 for (i = 0; i < length; i++)
1070 const GVariantMemberInfo *member_info;
1071 GVariantSerialised child;
1076 member_info = g_variant_type_info_member_info (value.type_info, i);
1077 child.type_info = member_info->type_info;
1078 child.depth = value.depth + 1;
1080 g_variant_type_info_query (child.type_info, &alignment, &fixed_size);
1082 while (offset & alignment)
1084 if (offset > value.size || value.data[offset] != '\0')
1089 child.data = value.data + offset;
1091 switch (member_info->ending_type)
1093 case G_VARIANT_MEMBER_ENDING_FIXED:
1094 end = offset + fixed_size;
1097 case G_VARIANT_MEMBER_ENDING_LAST:
1101 case G_VARIANT_MEMBER_ENDING_OFFSET:
1102 if (offset_ptr < offset_size)
1105 offset_ptr -= offset_size;
1107 if (offset_ptr < offset)
1110 end = gvs_read_unaligned_le (value.data + offset_ptr, offset_size);
1114 g_assert_not_reached ();
1117 if (end < offset || end > offset_ptr)
1120 child.size = end - offset;
1122 if (child.size == 0)
1125 if (!g_variant_serialised_is_normal (child))
1135 g_variant_type_info_query (value.type_info, &alignment, &fixed_size);
1139 g_assert (fixed_size == value.size);
1140 g_assert (offset_ptr == value.size);
1144 if (value.data[offset++] != '\0')
1149 while (offset & alignment)
1150 if (value.data[offset++] != '\0')
1154 g_assert (offset == value.size);
1158 return offset_ptr == offset;
1163 * Variants are stored by storing the serialized data of the child,
1164 * followed by a '\0' character, followed by the type string of the
1167 * In the case that a value is presented that contains no '\0'
1168 * character, or doesn't have a single well-formed definite type string
1169 * following that character, the variant must be taken as containing the
1174 gvs_variant_n_children (GVariantSerialised value)
1179 static inline GVariantSerialised
1180 gvs_variant_get_child (GVariantSerialised value,
1183 GVariantSerialised child = { 0, };
1185 /* NOTE: not O(1) and impossible for it to be... */
1188 /* find '\0' character */
1189 for (child.size = value.size - 1; child.size; child.size--)
1190 if (value.data[child.size] == '\0')
1193 /* ensure we didn't just hit the start of the string */
1194 if (value.data[child.size] == '\0')
1196 const gchar *type_string = (gchar *) &value.data[child.size + 1];
1197 const gchar *limit = (gchar *) &value.data[value.size];
1200 if (g_variant_type_string_scan (type_string, limit, &end) &&
1203 const GVariantType *type = (GVariantType *) type_string;
1205 if (g_variant_type_is_definite (type))
1208 gsize child_type_depth;
1210 child.type_info = g_variant_type_info_get (type);
1211 child.depth = value.depth + 1;
1213 if (child.size != 0)
1214 /* only set to non-%NULL if size > 0 */
1215 child.data = value.data;
1217 g_variant_type_info_query (child.type_info,
1219 child_type_depth = g_variant_type_info_query_depth (child.type_info);
1221 if ((!fixed_size || fixed_size == child.size) &&
1222 value.depth < G_VARIANT_MAX_RECURSION_DEPTH - child_type_depth)
1225 g_variant_type_info_unref (child.type_info);
1231 child.type_info = g_variant_type_info_get (G_VARIANT_TYPE_UNIT);
1234 child.depth = value.depth + 1;
1240 gvs_variant_needed_size (GVariantTypeInfo *type_info,
1241 GVariantSerialisedFiller gvs_filler,
1242 const gpointer *children,
1245 GVariantSerialised child = { 0, };
1246 const gchar *type_string;
1248 gvs_filler (&child, children[0]);
1249 type_string = g_variant_type_info_get_type_string (child.type_info);
1251 return child.size + 1 + strlen (type_string);
1255 gvs_variant_serialise (GVariantSerialised value,
1256 GVariantSerialisedFiller gvs_filler,
1257 const gpointer *children,
1260 GVariantSerialised child = { 0, };
1261 const gchar *type_string;
1263 child.data = value.data;
1265 gvs_filler (&child, children[0]);
1266 type_string = g_variant_type_info_get_type_string (child.type_info);
1267 value.data[child.size] = '\0';
1268 memcpy (value.data + child.size + 1, type_string, strlen (type_string));
1271 static inline gboolean
1272 gvs_variant_is_normal (GVariantSerialised value)
1274 GVariantSerialised child;
1276 gsize child_type_depth;
1278 child = gvs_variant_get_child (value, 0);
1279 child_type_depth = g_variant_type_info_query_depth (child.type_info);
1281 normal = (value.depth < G_VARIANT_MAX_RECURSION_DEPTH - child_type_depth) &&
1282 (child.data != NULL || child.size == 0) &&
1283 g_variant_serialised_is_normal (child);
1285 g_variant_type_info_unref (child.type_info);
1292 /* PART 2: Serializer API {{{1
1294 * This is the implementation of the API of the serializer as advertised
1295 * in gvariant-serialiser.h.
1298 /* Dispatch Utilities {{{2
1300 * These macros allow a given function (for example,
1301 * g_variant_serialiser_serialise) to be dispatched to the appropriate
1302 * type-specific function above (fixed/variable-sized maybe,
1303 * fixed/variable-sized array, tuple or variant).
1305 #define DISPATCH_FIXED(type_info, before, after) \
1309 g_variant_type_info_query_element (type_info, NULL, \
1314 before ## fixed_sized ## after \
1318 before ## variable_sized ## after \
1322 #define DISPATCH_CASES(type_info, before, after) \
1323 switch (g_variant_type_info_get_type_char (type_info)) \
1325 case G_VARIANT_TYPE_INFO_CHAR_MAYBE: \
1326 DISPATCH_FIXED (type_info, before, _maybe ## after) \
1328 case G_VARIANT_TYPE_INFO_CHAR_ARRAY: \
1329 DISPATCH_FIXED (type_info, before, _array ## after) \
1331 case G_VARIANT_TYPE_INFO_CHAR_DICT_ENTRY: \
1332 case G_VARIANT_TYPE_INFO_CHAR_TUPLE: \
1334 before ## tuple ## after \
1337 case G_VARIANT_TYPE_INFO_CHAR_VARIANT: \
1339 before ## variant ## after \
1343 /* Serializer entry points {{{2
1345 * These are the functions that are called in order for the serializer
1350 * g_variant_serialised_n_children:
1351 * @serialised: a #GVariantSerialised
1353 * For serialized data that represents a container value (maybes,
1354 * tuples, arrays, variants), determine how many child items are inside
1357 * Returns: the number of children
1360 g_variant_serialised_n_children (GVariantSerialised serialised)
1362 g_assert (g_variant_serialised_check (serialised));
1364 DISPATCH_CASES (serialised.type_info,
1366 return gvs_/**/,/**/_n_children (serialised);
1369 g_assert_not_reached ();
1373 * g_variant_serialised_get_child:
1374 * @serialised: a #GVariantSerialised
1375 * @index_: the index of the child to fetch
1377 * Extracts a child from a serialized data representing a container
1380 * It is an error to call this function with an index out of bounds.
1382 * If the result .data == %NULL and .size > 0 then there has been an
1383 * error extracting the requested fixed-sized value. This number of
1384 * zero bytes needs to be allocated instead.
1386 * In the case that .data == %NULL and .size == 0 then a zero-sized
1387 * item of a variable-sized type is being returned.
1389 * .data is never non-%NULL if size is 0.
1391 * Returns: a #GVariantSerialised for the child
1394 g_variant_serialised_get_child (GVariantSerialised serialised,
1397 GVariantSerialised child;
1399 g_assert (g_variant_serialised_check (serialised));
1401 if G_LIKELY (index_ < g_variant_serialised_n_children (serialised))
1403 DISPATCH_CASES (serialised.type_info,
1405 child = gvs_/**/,/**/_get_child (serialised, index_);
1406 g_assert (child.size || child.data == NULL);
1407 g_assert (g_variant_serialised_check (child));
1411 g_assert_not_reached ();
1414 g_error ("Attempt to access item %"G_GSIZE_FORMAT
1415 " in a container with only %"G_GSIZE_FORMAT" items",
1416 index_, g_variant_serialised_n_children (serialised));
1420 * g_variant_serialiser_serialise:
1421 * @serialised: a #GVariantSerialised, properly set up
1422 * @gvs_filler: the filler function
1423 * @children: an array of child items
1424 * @n_children: the size of @children
1426 * Writes data in serialized form.
1428 * The type_info field of @serialised must be filled in to type info for
1429 * the type that we are serializing.
1431 * The size field of @serialised must be filled in with the value
1432 * returned by a previous call to g_variant_serialiser_needed_size().
1434 * The data field of @serialised must be a pointer to a properly-aligned
1435 * memory region large enough to serialize into (ie: at least as big as
1438 * This function is only resonsible for serializing the top-level
1439 * container. @gvs_filler is called on each child of the container in
1440 * order for all of the data of that child to be filled in.
1443 g_variant_serialiser_serialise (GVariantSerialised serialised,
1444 GVariantSerialisedFiller gvs_filler,
1445 const gpointer *children,
1448 g_assert (g_variant_serialised_check (serialised));
1450 DISPATCH_CASES (serialised.type_info,
1452 gvs_/**/,/**/_serialise (serialised, gvs_filler,
1453 children, n_children);
1457 g_assert_not_reached ();
1461 * g_variant_serialiser_needed_size:
1462 * @type_info: the type to serialize for
1463 * @gvs_filler: the filler function
1464 * @children: an array of child items
1465 * @n_children: the size of @children
1467 * Determines how much memory would be needed to serialize this value.
1469 * This function is only resonsible for performing calculations for the
1470 * top-level container. @gvs_filler is called on each child of the
1471 * container in order to determine its size.
1474 g_variant_serialiser_needed_size (GVariantTypeInfo *type_info,
1475 GVariantSerialisedFiller gvs_filler,
1476 const gpointer *children,
1479 DISPATCH_CASES (type_info,
1481 return gvs_/**/,/**/_needed_size (type_info, gvs_filler,
1482 children, n_children);
1485 g_assert_not_reached ();
1488 /* Byteswapping {{{2 */
1491 * g_variant_serialised_byteswap:
1492 * @value: a #GVariantSerialised
1494 * Byte-swap serialized data. The result of this function is only
1495 * well-defined if the data is in normal form.
1498 g_variant_serialised_byteswap (GVariantSerialised serialised)
1503 g_assert (g_variant_serialised_check (serialised));
1505 if (!serialised.data)
1508 /* the types we potentially need to byteswap are
1509 * exactly those with alignment requirements.
1511 g_variant_type_info_query (serialised.type_info, &alignment, &fixed_size);
1515 /* if fixed size and alignment are equal then we are down
1516 * to the base integer type and we should swap it. the
1517 * only exception to this is if we have a tuple with a
1518 * single item, and then swapping it will be OK anyway.
1520 if (alignment + 1 == fixed_size)
1526 guint16 *ptr = (guint16 *) serialised.data;
1528 g_assert_cmpint (serialised.size, ==, 2);
1529 *ptr = GUINT16_SWAP_LE_BE (*ptr);
1535 guint32 *ptr = (guint32 *) serialised.data;
1537 g_assert_cmpint (serialised.size, ==, 4);
1538 *ptr = GUINT32_SWAP_LE_BE (*ptr);
1544 guint64 *ptr = (guint64 *) serialised.data;
1546 g_assert_cmpint (serialised.size, ==, 8);
1547 *ptr = GUINT64_SWAP_LE_BE (*ptr);
1552 g_assert_not_reached ();
1556 /* else, we have a container that potentially contains
1557 * some children that need to be byteswapped.
1563 children = g_variant_serialised_n_children (serialised);
1564 for (i = 0; i < children; i++)
1566 GVariantSerialised child;
1568 child = g_variant_serialised_get_child (serialised, i);
1569 g_variant_serialised_byteswap (child);
1570 g_variant_type_info_unref (child.type_info);
1575 /* Normal form checking {{{2 */
1578 * g_variant_serialised_is_normal:
1579 * @serialised: a #GVariantSerialised
1581 * Determines, recursively if @serialised is in normal form. There is
1582 * precisely one normal form of serialized data for each possible value.
1584 * It is possible that multiple byte sequences form the serialized data
1585 * for a given value if, for example, the padding bytes are filled in
1586 * with something other than zeros, but only one form is the normal
1590 g_variant_serialised_is_normal (GVariantSerialised serialised)
1592 if (serialised.depth >= G_VARIANT_MAX_RECURSION_DEPTH)
1595 DISPATCH_CASES (serialised.type_info,
1597 return gvs_/**/,/**/_is_normal (serialised);
1601 if (serialised.data == NULL)
1604 /* some hard-coded terminal cases */
1605 switch (g_variant_type_info_get_type_char (serialised.type_info))
1607 case 'b': /* boolean */
1608 return serialised.data[0] < 2;
1610 case 's': /* string */
1611 return g_variant_serialiser_is_string (serialised.data,
1615 return g_variant_serialiser_is_object_path (serialised.data,
1619 return g_variant_serialiser_is_signature (serialised.data,
1623 /* all of the other types are fixed-sized numerical types for
1624 * which all possible values are valid (including various NaN
1625 * representations for floating point values).
1631 /* Validity-checking functions {{{2
1633 * Checks if strings, object paths and signature strings are valid.
1637 * g_variant_serialiser_is_string:
1638 * @data: a possible string
1639 * @size: the size of @data
1641 * Ensures that @data is a valid string with a nul terminator at the end
1642 * and no nul bytes embedded.
1645 g_variant_serialiser_is_string (gconstpointer data,
1648 const gchar *expected_end;
1651 /* Strings must end with a nul terminator. */
1655 expected_end = ((gchar *) data) + size - 1;
1657 if (*expected_end != '\0')
1660 g_utf8_validate_len (data, size, &end);
1662 return end == expected_end;
1666 * g_variant_serialiser_is_object_path:
1667 * @data: a possible D-Bus object path
1668 * @size: the size of @data
1670 * Performs the checks for being a valid string.
1672 * Also, ensures that @data is a valid D-Bus object path, as per the D-Bus
1676 g_variant_serialiser_is_object_path (gconstpointer data,
1679 const gchar *string = data;
1682 if (!g_variant_serialiser_is_string (data, size))
1685 /* The path must begin with an ASCII '/' (integer 47) character */
1686 if (string[0] != '/')
1689 for (i = 1; string[i]; i++)
1690 /* Each element must only contain the ASCII characters
1691 * "[A-Z][a-z][0-9]_"
1693 if (g_ascii_isalnum (string[i]) || string[i] == '_')
1696 /* must consist of elements separated by slash characters. */
1697 else if (string[i] == '/')
1699 /* No element may be the empty string. */
1700 /* Multiple '/' characters cannot occur in sequence. */
1701 if (string[i - 1] == '/')
1708 /* A trailing '/' character is not allowed unless the path is the
1709 * root path (a single '/' character).
1711 if (i > 1 && string[i - 1] == '/')
1718 * g_variant_serialiser_is_signature:
1719 * @data: a possible D-Bus signature
1720 * @size: the size of @data
1722 * Performs the checks for being a valid string.
1724 * Also, ensures that @data is a valid D-Bus type signature, as per the
1725 * D-Bus specification. Note that this means the empty string is valid, as the
1726 * D-Bus specification defines a signature as “zero or more single complete
1730 g_variant_serialiser_is_signature (gconstpointer data,
1733 const gchar *string = data;
1734 gsize first_invalid;
1736 if (!g_variant_serialiser_is_string (data, size))
1739 /* make sure no non-definite characters appear */
1740 first_invalid = strspn (string, "ybnqiuxthdvasog(){}");
1741 if (string[first_invalid])
1744 /* make sure each type string is well-formed */
1746 if (!g_variant_type_string_scan (string, NULL, &string))
1753 /* vim:set foldmethod=marker: */