2 * Copyright © 2007, 2008 Ryan Lortie
3 * Copyright © 2010 Codethink Limited
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Ryan Lortie <desrt@desrt.ca>
26 #include "gvariant-serialiser.h"
28 #include <glib/gtestutils.h>
29 #include <glib/gstrfuncs.h>
30 #include <glib/gtypes.h>
37 * After this prologue section, this file has roughly 2 parts.
39 * The first part is split up into sections according to various
40 * container types. Maybe, Array, Tuple, Variant. The Maybe and Array
41 * sections are subdivided for element types being fixed or
42 * variable-sized types.
44 * Each section documents the format of that particular type of
45 * container and implements 5 functions for dealing with it:
48 * - determines (according to serialised data) how many child values
49 * are inside a particular container value.
52 * - gets the type of and the serialised data corresponding to a
53 * given child value within the container value.
56 * - determines how much space would be required to serialise a
57 * container of this type, containing the given children so that
58 * buffers can be preallocated before serialising.
61 * - write the serialised data for a container of this type,
62 * containing the given children, to a buffer.
65 * - check the given data to ensure that it is in normal form. For a
66 * given set of child values, there is exactly one normal form for
67 * the serialised data of a container. Other forms are possible
68 * while maintaining the same children (for example, by inserting
69 * something other than zero bytes as padding) but only one form is
72 * The second part contains the main entry point for each of the above 5
73 * functions and logic to dispatch it to the handler for the appropriate
74 * container type code.
76 * The second part also contains a routine to byteswap serialised
77 * values. This code makes use of the n_children() and get_child()
78 * functions above to do its work so no extra support is needed on a
79 * per-container-type basis.
81 * There is also additional code for checking for normal form. All
82 * numeric types are always in normal form since the full range of
83 * values is permitted (eg: 0 to 255 is a valid byte). Special checks
84 * need to be performed for booleans (only 0 or 1 allowed), strings
85 * (properly nul-terminated) and object paths and signature strings
86 * (meeting the D-Bus specification requirements).
91 * @type_info: the #GVariantTypeInfo of this value
92 * @data: (allow-none): the serialised data of this value, or %NULL
93 * @size: the size of this value
95 * A structure representing a GVariant in serialised form. This
96 * structure is used with #GVariantSerialisedFiller functions and as the
97 * primary interface to the serialiser. See #GVariantSerialisedFiller
98 * for a description of its use there.
100 * When used with the serialiser API functions, the following invariants
101 * apply to all #GVariantTypeSerialised structures passed to and
102 * returned from the serialiser.
104 * @type_info must be non-%NULL.
106 * @data must be properly aligned for the type described by @type_info.
108 * If @type_info describes a fixed-sized type then @size must always be
109 * equal to the fixed size of that type.
111 * For fixed-sized types (and only fixed-sized types), @data may be
112 * %NULL even if @size is non-zero. This happens when a framing error
113 * occurs while attempting to extract a fixed-sized value out of a
114 * variable-sized container. There is no data to return for the
115 * fixed-sized type, yet @size must be non-zero. The effect of this
116 * combination should be as if @data were a pointer to an
117 * appropriately-sized zero-filled region.
121 * g_variant_serialised_check:
122 * @serialised: a #GVariantSerialised struct
124 * Checks @serialised for validity according to the invariants described
128 g_variant_serialised_check (GVariantSerialised serialised
)
133 g_assert (serialised
.type_info
!= NULL
);
134 g_variant_type_info_query (serialised
.type_info
, &alignment
, &fixed_size
);
137 g_assert_cmpint (serialised
.size
, ==, fixed_size
);
139 g_assert (serialised
.size
== 0 || serialised
.data
!= NULL
);
141 /* Depending on the native alignment requirements of the machine, the
142 * compiler will insert either 3 or 7 padding bytes after the char.
143 * This will result in the sizeof() the struct being 12 or 16.
144 * Subtract 9 to get 3 or 7 which is a nice bitmask to apply to get
145 * the alignment bits that we "care about" being zero: in the
146 * 4-aligned case, we care about 2 bits, and in the 8-aligned case, we
149 alignment
&= sizeof (struct {
159 /* Some OSes (FreeBSD is a known example) have a malloc() that returns
160 * unaligned memory if you request small sizes. 'malloc (1);', for
161 * example, has been seen to return pointers aligned to 6 mod 16.
163 * Check if this is a small allocation and return without enforcing
164 * the alignment assertion if this is the case.
166 if (serialised
.size
<= alignment
)
169 g_assert_cmpint (alignment
& (gsize
) serialised
.data
, ==, 0);
173 * GVariantSerialisedFiller:
174 * @serialised: a #GVariantSerialised instance to fill
175 * @data: data from the children array
177 * This function is called back from g_variant_serialiser_needed_size()
178 * and g_variant_serialiser_serialise(). It fills in missing details
179 * from a partially-complete #GVariantSerialised.
181 * The @data parameter passed back to the function is one of the items
182 * that was passed to the serialiser in the @children array. It
183 * represents a single child item of the container that is being
184 * serialised. The information filled in to @serialised is the
185 * information for this child.
187 * If the @type_info field of @serialised is %NULL then the callback
188 * function must set it to the type information corresponding to the
189 * type of the child. No reference should be added. If it is non-%NULL
190 * then the callback should assert that it is equal to the actual type
193 * If the @size field is zero then the callback must fill it in with the
194 * required amount of space to store the serialised form of the child.
195 * If it is non-zero then the callback should assert that it is equal to
196 * the needed size of the child.
198 * If @data is non-%NULL then it points to a space that is properly
199 * aligned for and large enough to store the serialised data of the
200 * child. The callback must store the serialised form of the child at
203 * If the child value is another container then the callback will likely
204 * recurse back into the serialiser by calling
205 * g_variant_serialiser_needed_size() to determine @size and
206 * g_variant_serialiser_serialise() to write to @data.
209 /* PART 1: Container types {{{1
211 * This section contains the serialiser implementation functions for
212 * each container type.
217 * Maybe types are handled depending on if the element type of the maybe
218 * type is a fixed-sized or variable-sized type. Although all maybe
219 * types themselves are variable-sized types, herein, a maybe value with
220 * a fixed-sized element type is called a "fixed-sized maybe" for
221 * convenience and a maybe value with a variable-sized element type is
222 * called a "variable-sized maybe".
225 /* Fixed-sized Maybe {{{3
227 * The size of a maybe value with a fixed-sized element type is either 0
228 * or equal to the fixed size of its element type. The case where the
229 * size of the maybe value is zero corresponds to the "Nothing" case and
230 * the case where the size of the maybe value is equal to the fixed size
231 * of the element type corresponds to the "Just" case; in that case, the
232 * serialised data of the child value forms the entire serialised data
233 * of the maybe value.
235 * In the event that a fixed-sized maybe value is presented with a size
236 * that is not equal to the fixed size of the element type then the
237 * value must be taken to be "Nothing".
241 gvs_fixed_sized_maybe_n_children (GVariantSerialised value
)
243 gsize element_fixed_size
;
245 g_variant_type_info_query_element (value
.type_info
, NULL
,
246 &element_fixed_size
);
248 return (element_fixed_size
== value
.size
) ? 1 : 0;
251 static GVariantSerialised
252 gvs_fixed_sized_maybe_get_child (GVariantSerialised value
,
255 /* the child has the same bounds as the
256 * container, so just update the type.
258 value
.type_info
= g_variant_type_info_element (value
.type_info
);
259 g_variant_type_info_ref (value
.type_info
);
265 gvs_fixed_sized_maybe_needed_size (GVariantTypeInfo
*type_info
,
266 GVariantSerialisedFiller gvs_filler
,
267 const gpointer
*children
,
272 gsize element_fixed_size
;
274 g_variant_type_info_query_element (type_info
, NULL
,
275 &element_fixed_size
);
277 return element_fixed_size
;
284 gvs_fixed_sized_maybe_serialise (GVariantSerialised value
,
285 GVariantSerialisedFiller gvs_filler
,
286 const gpointer
*children
,
291 GVariantSerialised child
= { NULL
, value
.data
, value
.size
};
293 gvs_filler (&child
, children
[0]);
298 gvs_fixed_sized_maybe_is_normal (GVariantSerialised value
)
302 gsize element_fixed_size
;
304 g_variant_type_info_query_element (value
.type_info
,
305 NULL
, &element_fixed_size
);
307 if (value
.size
!= element_fixed_size
)
310 /* proper element size: "Just". recurse to the child. */
311 value
.type_info
= g_variant_type_info_element (value
.type_info
);
313 return g_variant_serialised_is_normal (value
);
316 /* size of 0: "Nothing" */
320 /* Variable-sized Maybe
322 * The size of a maybe value with a variable-sized element type is
323 * either 0 or strictly greater than 0. The case where the size of the
324 * maybe value is zero corresponds to the "Nothing" case and the case
325 * where the size of the maybe value is greater than zero corresponds to
326 * the "Just" case; in that case, the serialised data of the child value
327 * forms the first part of the serialised data of the maybe value and is
328 * followed by a single zero byte. This zero byte is always appended,
329 * regardless of any zero bytes that may already be at the end of the
330 * serialised ata of the child value.
334 gvs_variable_sized_maybe_n_children (GVariantSerialised value
)
336 return (value
.size
> 0) ? 1 : 0;
339 static GVariantSerialised
340 gvs_variable_sized_maybe_get_child (GVariantSerialised value
,
343 /* remove the padding byte and update the type. */
344 value
.type_info
= g_variant_type_info_element (value
.type_info
);
345 g_variant_type_info_ref (value
.type_info
);
348 /* if it's zero-sized then it may as well be NULL */
356 gvs_variable_sized_maybe_needed_size (GVariantTypeInfo
*type_info
,
357 GVariantSerialisedFiller gvs_filler
,
358 const gpointer
*children
,
363 GVariantSerialised child
= { 0, };
365 gvs_filler (&child
, children
[0]);
367 return child
.size
+ 1;
374 gvs_variable_sized_maybe_serialise (GVariantSerialised value
,
375 GVariantSerialisedFiller gvs_filler
,
376 const gpointer
*children
,
381 GVariantSerialised child
= { NULL
, value
.data
, value
.size
- 1 };
383 /* write the data for the child. */
384 gvs_filler (&child
, children
[0]);
385 value
.data
[child
.size
] = '\0';
390 gvs_variable_sized_maybe_is_normal (GVariantSerialised value
)
395 if (value
.data
[value
.size
- 1] != '\0')
398 value
.type_info
= g_variant_type_info_element (value
.type_info
);
401 return g_variant_serialised_is_normal (value
);
406 * Just as with maybe types, array types are handled depending on if the
407 * element type of the array type is a fixed-sized or variable-sized
408 * type. Similar to maybe types, for convenience, an array value with a
409 * fixed-sized element type is called a "fixed-sized array" and an array
410 * value with a variable-sized element type is called a "variable sized
414 /* Fixed-sized Array {{{3
416 * For fixed sized arrays, the serialised data is simply a concatenation
417 * of the serialised data of each element, in order. Since fixed-sized
418 * values always have a fixed size that is a multiple of their alignment
419 * requirement no extra padding is required.
421 * In the event that a fixed-sized array is presented with a size that
422 * is not an integer multiple of the element size then the value of the
423 * array must be taken as being empty.
427 gvs_fixed_sized_array_n_children (GVariantSerialised value
)
429 gsize element_fixed_size
;
431 g_variant_type_info_query_element (value
.type_info
, NULL
,
432 &element_fixed_size
);
434 if (value
.size
% element_fixed_size
== 0)
435 return value
.size
/ element_fixed_size
;
440 static GVariantSerialised
441 gvs_fixed_sized_array_get_child (GVariantSerialised value
,
444 GVariantSerialised child
= { 0, };
446 child
.type_info
= g_variant_type_info_element (value
.type_info
);
447 g_variant_type_info_query (child
.type_info
, NULL
, &child
.size
);
448 child
.data
= value
.data
+ (child
.size
* index_
);
449 g_variant_type_info_ref (child
.type_info
);
455 gvs_fixed_sized_array_needed_size (GVariantTypeInfo
*type_info
,
456 GVariantSerialisedFiller gvs_filler
,
457 const gpointer
*children
,
460 gsize element_fixed_size
;
462 g_variant_type_info_query_element (type_info
, NULL
, &element_fixed_size
);
464 return element_fixed_size
* n_children
;
468 gvs_fixed_sized_array_serialise (GVariantSerialised value
,
469 GVariantSerialisedFiller gvs_filler
,
470 const gpointer
*children
,
473 GVariantSerialised child
= { 0, };
476 child
.type_info
= g_variant_type_info_element (value
.type_info
);
477 g_variant_type_info_query (child
.type_info
, NULL
, &child
.size
);
478 child
.data
= value
.data
;
480 for (i
= 0; i
< n_children
; i
++)
482 gvs_filler (&child
, children
[i
]);
483 child
.data
+= child
.size
;
488 gvs_fixed_sized_array_is_normal (GVariantSerialised value
)
490 GVariantSerialised child
= { 0, };
492 child
.type_info
= g_variant_type_info_element (value
.type_info
);
493 g_variant_type_info_query (child
.type_info
, NULL
, &child
.size
);
495 if (value
.size
% child
.size
!= 0)
498 for (child
.data
= value
.data
;
499 child
.data
< value
.data
+ value
.size
;
500 child
.data
+= child
.size
)
502 if (!g_variant_serialised_is_normal (child
))
509 /* Variable-sized Array {{{3
511 * Variable sized arrays, containing variable-sized elements, must be
512 * able to determine the boundaries between the elements. The items
513 * cannot simply be concatenated. Additionally, we are faced with the
514 * fact that non-fixed-sized values do not necessarily have a size that
515 * is a multiple of their alignment requirement, so we may need to
516 * insert zero-filled padding.
518 * While it is possible to find the start of an item by starting from
519 * the end of the item before it and padding for alignment, it is not
520 * generally possible to do the reverse operation. For this reason, we
521 * record the end point of each element in the array.
523 * GVariant works in terms of "offsets". An offset is a pointer to a
524 * boundary between two bytes. In 4 bytes of serialised data, there
525 * would be 5 possible offsets: one at the start ('0'), one between each
526 * pair of adjacent bytes ('1', '2', '3') and one at the end ('4').
528 * The numeric value of an offset is an unsigned integer given relative
529 * to the start of the serialised data of the array. Offsets are always
530 * stored in little endian byte order and are always only as big as they
531 * need to be. For example, in 255 bytes of serialised data, there are
532 * 256 offsets. All possibilities can be stored in an 8 bit unsigned
533 * integer. In 256 bytes of serialised data, however, there are 257
534 * possible offsets so 16 bit integers must be used. The size of an
535 * offset is always a power of 2.
537 * The offsets are stored at the end of the serialised data of the
538 * array. They are simply concatenated on without any particular
539 * alignment. The size of the offsets is included in the size of the
540 * serialised data for purposes of determining the size of the offsets.
541 * This presents a possibly ambiguity; in certain cases, a particular
542 * value of array could have two different serialised forms.
544 * Imagine an array containing a single string of 253 bytes in length
545 * (so, 254 bytes including the nul terminator). Now the offset must be
546 * written. If an 8 bit offset is written, it will bring the size of
547 * the array's serialised data to 255 -- which means that the use of an
548 * 8 bit offset was valid. If a 16 bit offset is used then the total
549 * size of the array will be 256 -- which means that the use of a 16 bit
550 * offset was valid. Although both of these will be accepted by the
551 * deserialiser, only the smaller of the two is considered to be in
552 * normal form and that is the one that the serialiser must produce.
556 gvs_read_unaligned_le (guchar
*bytes
,
561 guchar bytes
[GLIB_SIZEOF_SIZE_T
];
565 tmpvalue
.integer
= 0;
566 memcpy (&tmpvalue
.bytes
, bytes
, size
);
568 return GSIZE_FROM_LE (tmpvalue
.integer
);
572 gvs_write_unaligned_le (guchar
*bytes
,
578 guchar bytes
[GLIB_SIZEOF_SIZE_T
];
582 tmpvalue
.integer
= GSIZE_TO_LE (value
);
583 memcpy (bytes
, &tmpvalue
.bytes
, size
);
587 gvs_get_offset_size (gsize size
)
589 if (size
> G_MAXUINT32
)
592 else if (size
> G_MAXUINT16
)
595 else if (size
> G_MAXUINT8
)
605 gvs_calculate_total_size (gsize body_size
,
608 if (body_size
+ 1 * offsets
<= G_MAXUINT8
)
609 return body_size
+ 1 * offsets
;
611 if (body_size
+ 2 * offsets
<= G_MAXUINT16
)
612 return body_size
+ 2 * offsets
;
614 if (body_size
+ 4 * offsets
<= G_MAXUINT32
)
615 return body_size
+ 4 * offsets
;
617 return body_size
+ 8 * offsets
;
621 gvs_variable_sized_array_n_children (GVariantSerialised value
)
623 gsize offsets_array_size
;
630 offset_size
= gvs_get_offset_size (value
.size
);
632 last_end
= gvs_read_unaligned_le (value
.data
+ value
.size
-
633 offset_size
, offset_size
);
635 if (last_end
> value
.size
)
638 offsets_array_size
= value
.size
- last_end
;
640 if (offsets_array_size
% offset_size
)
643 return offsets_array_size
/ offset_size
;
646 static GVariantSerialised
647 gvs_variable_sized_array_get_child (GVariantSerialised value
,
650 GVariantSerialised child
= { 0, };
656 child
.type_info
= g_variant_type_info_element (value
.type_info
);
657 g_variant_type_info_ref (child
.type_info
);
659 offset_size
= gvs_get_offset_size (value
.size
);
661 last_end
= gvs_read_unaligned_le (value
.data
+ value
.size
-
662 offset_size
, offset_size
);
668 start
= gvs_read_unaligned_le (value
.data
+ last_end
+
669 (offset_size
* (index_
- 1)),
672 g_variant_type_info_query (child
.type_info
, &alignment
, NULL
);
673 start
+= (-start
) & alignment
;
678 end
= gvs_read_unaligned_le (value
.data
+ last_end
+
679 (offset_size
* index_
),
682 if (start
< end
&& end
<= value
.size
)
684 child
.data
= value
.data
+ start
;
685 child
.size
= end
- start
;
692 gvs_variable_sized_array_needed_size (GVariantTypeInfo
*type_info
,
693 GVariantSerialisedFiller gvs_filler
,
694 const gpointer
*children
,
701 g_variant_type_info_query (type_info
, &alignment
, NULL
);
704 for (i
= 0; i
< n_children
; i
++)
706 GVariantSerialised child
= { 0, };
708 offset
+= (-offset
) & alignment
;
709 gvs_filler (&child
, children
[i
]);
710 offset
+= child
.size
;
713 return gvs_calculate_total_size (offset
, n_children
);
717 gvs_variable_sized_array_serialise (GVariantSerialised value
,
718 GVariantSerialisedFiller gvs_filler
,
719 const gpointer
*children
,
728 g_variant_type_info_query (value
.type_info
, &alignment
, NULL
);
729 offset_size
= gvs_get_offset_size (value
.size
);
732 offset_ptr
= value
.data
+ value
.size
- offset_size
* n_children
;
734 for (i
= 0; i
< n_children
; i
++)
736 GVariantSerialised child
= { 0, };
738 while (offset
& alignment
)
739 value
.data
[offset
++] = '\0';
741 child
.data
= value
.data
+ offset
;
742 gvs_filler (&child
, children
[i
]);
743 offset
+= child
.size
;
745 gvs_write_unaligned_le (offset_ptr
, offset
, offset_size
);
746 offset_ptr
+= offset_size
;
751 gvs_variable_sized_array_is_normal (GVariantSerialised value
)
753 GVariantSerialised child
= { 0, };
754 gsize offsets_array_size
;
755 guchar
*offsets_array
;
766 offset_size
= gvs_get_offset_size (value
.size
);
767 last_end
= gvs_read_unaligned_le (value
.data
+ value
.size
-
768 offset_size
, offset_size
);
770 if (last_end
> value
.size
)
773 offsets_array_size
= value
.size
- last_end
;
775 if (offsets_array_size
% offset_size
)
778 offsets_array
= value
.data
+ value
.size
- offsets_array_size
;
779 length
= offsets_array_size
/ offset_size
;
784 child
.type_info
= g_variant_type_info_element (value
.type_info
);
785 g_variant_type_info_query (child
.type_info
, &alignment
, NULL
);
788 for (i
= 0; i
< length
; i
++)
792 this_end
= gvs_read_unaligned_le (offsets_array
+ offset_size
* i
,
795 if (this_end
< offset
|| this_end
> last_end
)
798 while (offset
& alignment
)
800 if (!(offset
< this_end
&& value
.data
[offset
] == '\0'))
805 child
.data
= value
.data
+ offset
;
806 child
.size
= this_end
- offset
;
811 if (!g_variant_serialised_is_normal (child
))
817 g_assert (offset
== last_end
);
824 * Since tuples can contain a mix of variable- and fixed-sized items,
825 * they are, in terms of serialisation, a hybrid of variable-sized and
826 * fixed-sized arrays.
828 * Offsets are only stored for variable-sized items. Also, since the
829 * number of items in a tuple is known from its type, we are able to
830 * know exactly how many offsets to expect in the serialised data (and
831 * therefore how much space is taken up by the offset array). This
832 * means that we know where the end of the serialised data for the last
833 * item is -- we can just subtract the size of the offset array from the
834 * total size of the tuple. For this reason, the last item in the tuple
835 * doesn't need an offset stored.
837 * Tuple offsets are stored in reverse. This design choice allows
838 * iterator-based deserialisers to be more efficient.
840 * Most of the "heavy lifting" here is handled by the GVariantTypeInfo
841 * for the tuple. See the notes in gvarianttypeinfo.h.
845 gvs_tuple_n_children (GVariantSerialised value
)
847 return g_variant_type_info_n_members (value
.type_info
);
850 static GVariantSerialised
851 gvs_tuple_get_child (GVariantSerialised value
,
854 const GVariantMemberInfo
*member_info
;
855 GVariantSerialised child
= { 0, };
859 member_info
= g_variant_type_info_member_info (value
.type_info
, index_
);
860 child
.type_info
= g_variant_type_info_ref (member_info
->type_info
);
861 offset_size
= gvs_get_offset_size (value
.size
);
863 /* tuples are the only (potentially) fixed-sized containers, so the
864 * only ones that have to deal with the possibility of having %NULL
865 * data with a non-zero %size if errors occurred elsewhere.
867 if G_UNLIKELY (value
.data
== NULL
&& value
.size
!= 0)
869 g_variant_type_info_query (child
.type_info
, NULL
, &child
.size
);
871 /* this can only happen in fixed-sized tuples,
872 * so the child must also be fixed sized.
874 g_assert (child
.size
!= 0);
880 if (member_info
->ending_type
== G_VARIANT_MEMBER_ENDING_OFFSET
)
882 if (offset_size
* (member_info
->i
+ 2) > value
.size
)
887 if (offset_size
* (member_info
->i
+ 1) > value
.size
)
889 /* if the child is fixed size, return its size.
890 * if child is not fixed-sized, return size = 0.
892 g_variant_type_info_query (child
.type_info
, NULL
, &child
.size
);
898 if (member_info
->i
+ 1)
899 start
= gvs_read_unaligned_le (value
.data
+ value
.size
-
900 offset_size
* (member_info
->i
+ 1),
905 start
+= member_info
->a
;
906 start
&= member_info
->b
;
907 start
|= member_info
->c
;
909 if (member_info
->ending_type
== G_VARIANT_MEMBER_ENDING_LAST
)
910 end
= value
.size
- offset_size
* (member_info
->i
+ 1);
912 else if (member_info
->ending_type
== G_VARIANT_MEMBER_ENDING_FIXED
)
916 g_variant_type_info_query (child
.type_info
, NULL
, &fixed_size
);
917 end
= start
+ fixed_size
;
918 child
.size
= fixed_size
;
921 else /* G_VARIANT_MEMEBER_ENDING_OFFSET */
922 end
= gvs_read_unaligned_le (value
.data
+ value
.size
-
923 offset_size
* (member_info
->i
+ 2),
926 if (start
< end
&& end
<= value
.size
)
928 child
.data
= value
.data
+ start
;
929 child
.size
= end
- start
;
936 gvs_tuple_needed_size (GVariantTypeInfo
*type_info
,
937 GVariantSerialisedFiller gvs_filler
,
938 const gpointer
*children
,
941 const GVariantMemberInfo
*member_info
= NULL
;
946 g_variant_type_info_query (type_info
, NULL
, &fixed_size
);
953 for (i
= 0; i
< n_children
; i
++)
957 member_info
= g_variant_type_info_member_info (type_info
, i
);
958 g_variant_type_info_query (member_info
->type_info
,
959 &alignment
, &fixed_size
);
960 offset
+= (-offset
) & alignment
;
963 offset
+= fixed_size
;
966 GVariantSerialised child
= { 0, };
968 gvs_filler (&child
, children
[i
]);
969 offset
+= child
.size
;
973 return gvs_calculate_total_size (offset
, member_info
->i
+ 1);
977 gvs_tuple_serialise (GVariantSerialised value
,
978 GVariantSerialisedFiller gvs_filler
,
979 const gpointer
*children
,
986 offset_size
= gvs_get_offset_size (value
.size
);
989 for (i
= 0; i
< n_children
; i
++)
991 const GVariantMemberInfo
*member_info
;
992 GVariantSerialised child
= { 0, };
995 member_info
= g_variant_type_info_member_info (value
.type_info
, i
);
996 g_variant_type_info_query (member_info
->type_info
, &alignment
, NULL
);
998 while (offset
& alignment
)
999 value
.data
[offset
++] = '\0';
1001 child
.data
= value
.data
+ offset
;
1002 gvs_filler (&child
, children
[i
]);
1003 offset
+= child
.size
;
1005 if (member_info
->ending_type
== G_VARIANT_MEMBER_ENDING_OFFSET
)
1007 value
.size
-= offset_size
;
1008 gvs_write_unaligned_le (value
.data
+ value
.size
,
1009 offset
, offset_size
);
1013 while (offset
< value
.size
)
1014 value
.data
[offset
++] = '\0';
1018 gvs_tuple_is_normal (GVariantSerialised value
)
1026 /* as per the comment in gvs_tuple_get_child() */
1027 if G_UNLIKELY (value
.data
== NULL
&& value
.size
!= 0)
1030 offset_size
= gvs_get_offset_size (value
.size
);
1031 length
= g_variant_type_info_n_members (value
.type_info
);
1032 offset_ptr
= value
.size
;
1035 for (i
= 0; i
< length
; i
++)
1037 const GVariantMemberInfo
*member_info
;
1038 GVariantSerialised child
;
1043 member_info
= g_variant_type_info_member_info (value
.type_info
, i
);
1044 child
.type_info
= member_info
->type_info
;
1046 g_variant_type_info_query (child
.type_info
, &alignment
, &fixed_size
);
1048 while (offset
& alignment
)
1050 if (offset
> value
.size
|| value
.data
[offset
] != '\0')
1055 child
.data
= value
.data
+ offset
;
1057 switch (member_info
->ending_type
)
1059 case G_VARIANT_MEMBER_ENDING_FIXED
:
1060 end
= offset
+ fixed_size
;
1063 case G_VARIANT_MEMBER_ENDING_LAST
:
1067 case G_VARIANT_MEMBER_ENDING_OFFSET
:
1068 offset_ptr
-= offset_size
;
1070 if (offset_ptr
< offset
)
1073 end
= gvs_read_unaligned_le (value
.data
+ offset_ptr
, offset_size
);
1077 g_assert_not_reached ();
1080 if (end
< offset
|| end
> offset_ptr
)
1083 child
.size
= end
- offset
;
1085 if (child
.size
== 0)
1088 if (!g_variant_serialised_is_normal (child
))
1098 g_variant_type_info_query (value
.type_info
, &alignment
, &fixed_size
);
1102 g_assert (fixed_size
== value
.size
);
1103 g_assert (offset_ptr
== value
.size
);
1107 if (value
.data
[offset
++] != '\0')
1112 while (offset
& alignment
)
1113 if (value
.data
[offset
++] != '\0')
1117 g_assert (offset
== value
.size
);
1121 return offset_ptr
== offset
;
1126 * Variants are stored by storing the serialised data of the child,
1127 * followed by a '\0' character, followed by the type string of the
1130 * In the case that a value is presented that contains no '\0'
1131 * character, or doesn't have a single well-formed definite type string
1132 * following that character, the variant must be taken as containing the
1137 gvs_variant_n_children (GVariantSerialised value
)
1142 static inline GVariantSerialised
1143 gvs_variant_get_child (GVariantSerialised value
,
1146 GVariantSerialised child
= { 0, };
1148 /* NOTE: not O(1) and impossible for it to be... */
1151 /* find '\0' character */
1152 for (child
.size
= value
.size
- 1; child
.size
; child
.size
--)
1153 if (value
.data
[child
.size
] == '\0')
1156 /* ensure we didn't just hit the start of the string */
1157 if (value
.data
[child
.size
] == '\0')
1159 const gchar
*type_string
= (gchar
*) &value
.data
[child
.size
+ 1];
1160 const gchar
*limit
= (gchar
*) &value
.data
[value
.size
];
1163 if (g_variant_type_string_scan (type_string
, limit
, &end
) &&
1166 const GVariantType
*type
= (GVariantType
*) type_string
;
1168 if (g_variant_type_is_definite (type
))
1172 child
.type_info
= g_variant_type_info_get (type
);
1174 if (child
.size
!= 0)
1175 /* only set to non-%NULL if size > 0 */
1176 child
.data
= value
.data
;
1178 g_variant_type_info_query (child
.type_info
,
1181 if (!fixed_size
|| fixed_size
== child
.size
)
1184 g_variant_type_info_unref (child
.type_info
);
1190 child
.type_info
= g_variant_type_info_get (G_VARIANT_TYPE_UNIT
);
1198 gvs_variant_needed_size (GVariantTypeInfo
*type_info
,
1199 GVariantSerialisedFiller gvs_filler
,
1200 const gpointer
*children
,
1203 GVariantSerialised child
= { 0, };
1204 const gchar
*type_string
;
1206 gvs_filler (&child
, children
[0]);
1207 type_string
= g_variant_type_info_get_type_string (child
.type_info
);
1209 return child
.size
+ 1 + strlen (type_string
);
1213 gvs_variant_serialise (GVariantSerialised value
,
1214 GVariantSerialisedFiller gvs_filler
,
1215 const gpointer
*children
,
1218 GVariantSerialised child
= { 0, };
1219 const gchar
*type_string
;
1221 child
.data
= value
.data
;
1223 gvs_filler (&child
, children
[0]);
1224 type_string
= g_variant_type_info_get_type_string (child
.type_info
);
1225 value
.data
[child
.size
] = '\0';
1226 memcpy (value
.data
+ child
.size
+ 1, type_string
, strlen (type_string
));
1229 static inline gboolean
1230 gvs_variant_is_normal (GVariantSerialised value
)
1232 GVariantSerialised child
;
1235 child
= gvs_variant_get_child (value
, 0);
1237 normal
= (child
.data
!= NULL
|| child
.size
== 0) &&
1238 g_variant_serialised_is_normal (child
);
1240 g_variant_type_info_unref (child
.type_info
);
1247 /* PART 2: Serialiser API {{{1
1249 * This is the implementation of the API of the serialiser as advertised
1250 * in gvariant-serialiser.h.
1253 /* Dispatch Utilities {{{2
1255 * These macros allow a given function (for example,
1256 * g_variant_serialiser_serialise) to be dispatched to the appropriate
1257 * type-specific function above (fixed/variable-sized maybe,
1258 * fixed/variable-sized array, tuple or variant).
1260 #define DISPATCH_FIXED(type_info, before, after) \
1264 g_variant_type_info_query_element (type_info, NULL, \
1269 before ## fixed_sized ## after \
1273 before ## variable_sized ## after \
1277 #define DISPATCH_CASES(type_info, before, after) \
1278 switch (g_variant_type_info_get_type_char (type_info)) \
1280 case G_VARIANT_TYPE_INFO_CHAR_MAYBE: \
1281 DISPATCH_FIXED (type_info, before, _maybe ## after) \
1283 case G_VARIANT_TYPE_INFO_CHAR_ARRAY: \
1284 DISPATCH_FIXED (type_info, before, _array ## after) \
1286 case G_VARIANT_TYPE_INFO_CHAR_DICT_ENTRY: \
1287 case G_VARIANT_TYPE_INFO_CHAR_TUPLE: \
1289 before ## tuple ## after \
1292 case G_VARIANT_TYPE_INFO_CHAR_VARIANT: \
1294 before ## variant ## after \
1298 /* Serialiser entry points {{{2
1300 * These are the functions that are called in order for the serialiser
1305 * g_variant_serialised_n_children:
1306 * @serialised: a #GVariantSerialised
1308 * For serialised data that represents a container value (maybes,
1309 * tuples, arrays, variants), determine how many child items are inside
1312 * Returns: the number of children
1315 g_variant_serialised_n_children (GVariantSerialised serialised
)
1317 g_variant_serialised_check (serialised
);
1319 DISPATCH_CASES (serialised
.type_info
,
1321 return gvs_
/**/,/**/_n_children (serialised
);
1324 g_assert_not_reached ();
1328 * g_variant_serialised_get_child:
1329 * @serialised: a #GVariantSerialised
1330 * @index_: the index of the child to fetch
1332 * Extracts a child from a serialised data representing a container
1335 * It is an error to call this function with an index out of bounds.
1337 * If the result .data == %NULL and .size > 0 then there has been an
1338 * error extracting the requested fixed-sized value. This number of
1339 * zero bytes needs to be allocated instead.
1341 * In the case that .data == %NULL and .size == 0 then a zero-sized
1342 * item of a variable-sized type is being returned.
1344 * .data is never non-%NULL if size is 0.
1346 * Returns: a #GVariantSerialised for the child
1349 g_variant_serialised_get_child (GVariantSerialised serialised
,
1352 GVariantSerialised child
;
1354 g_variant_serialised_check (serialised
);
1356 if G_LIKELY (index_
< g_variant_serialised_n_children (serialised
))
1358 DISPATCH_CASES (serialised
.type_info
,
1360 child
= gvs_
/**/,/**/_get_child (serialised
, index_
);
1361 g_assert (child
.size
|| child
.data
== NULL
);
1362 g_variant_serialised_check (child
);
1366 g_assert_not_reached ();
1369 g_error ("Attempt to access item %"G_GSIZE_FORMAT
1370 " in a container with only %"G_GSIZE_FORMAT
" items",
1371 index_
, g_variant_serialised_n_children (serialised
));
1375 * g_variant_serialiser_serialise:
1376 * @serialised: a #GVariantSerialised, properly set up
1377 * @gvs_filler: the filler function
1378 * @children: an array of child items
1379 * @n_children: the size of @children
1381 * Writes data in serialised form.
1383 * The type_info field of @serialised must be filled in to type info for
1384 * the type that we are serialising.
1386 * The size field of @serialised must be filled in with the value
1387 * returned by a previous call to g_variant_serialiser_needed_size().
1389 * The data field of @serialised must be a pointer to a properly-aligned
1390 * memory region large enough to serialise into (ie: at least as big as
1393 * This function is only resonsible for serialising the top-level
1394 * container. @gvs_filler is called on each child of the container in
1395 * order for all of the data of that child to be filled in.
1398 g_variant_serialiser_serialise (GVariantSerialised serialised
,
1399 GVariantSerialisedFiller gvs_filler
,
1400 const gpointer
*children
,
1403 g_variant_serialised_check (serialised
);
1405 DISPATCH_CASES (serialised
.type_info
,
1407 gvs_
/**/,/**/_serialise (serialised
, gvs_filler
,
1408 children
, n_children
);
1412 g_assert_not_reached ();
1416 * g_variant_serialiser_needed_size:
1417 * @type_info: the type to serialise for
1418 * @gvs_filler: the filler function
1419 * @children: an array of child items
1420 * @n_children: the size of @children
1422 * Determines how much memory would be needed to serialise this value.
1424 * This function is only resonsible for performing calculations for the
1425 * top-level container. @gvs_filler is called on each child of the
1426 * container in order to determine its size.
1429 g_variant_serialiser_needed_size (GVariantTypeInfo
*type_info
,
1430 GVariantSerialisedFiller gvs_filler
,
1431 const gpointer
*children
,
1434 DISPATCH_CASES (type_info
,
1436 return gvs_
/**/,/**/_needed_size (type_info
, gvs_filler
,
1437 children
, n_children
);
1440 g_assert_not_reached ();
1443 /* Byteswapping {{{2 */
1446 * g_variant_serialised_byteswap:
1447 * @value: a #GVariantSerialised
1449 * Byte-swap serialised data. The result of this function is only
1450 * well-defined if the data is in normal form.
1453 g_variant_serialised_byteswap (GVariantSerialised serialised
)
1458 g_variant_serialised_check (serialised
);
1460 if (!serialised
.data
)
1463 /* the types we potentially need to byteswap are
1464 * exactly those with alignment requirements.
1466 g_variant_type_info_query (serialised
.type_info
, &alignment
, &fixed_size
);
1470 /* if fixed size and alignment are equal then we are down
1471 * to the base integer type and we should swap it. the
1472 * only exception to this is if we have a tuple with a
1473 * single item, and then swapping it will be OK anyway.
1475 if (alignment
+ 1 == fixed_size
)
1481 guint16
*ptr
= (guint16
*) serialised
.data
;
1483 g_assert_cmpint (serialised
.size
, ==, 2);
1484 *ptr
= GUINT16_SWAP_LE_BE (*ptr
);
1490 guint32
*ptr
= (guint32
*) serialised
.data
;
1492 g_assert_cmpint (serialised
.size
, ==, 4);
1493 *ptr
= GUINT32_SWAP_LE_BE (*ptr
);
1499 guint64
*ptr
= (guint64
*) serialised
.data
;
1501 g_assert_cmpint (serialised
.size
, ==, 8);
1502 *ptr
= GUINT64_SWAP_LE_BE (*ptr
);
1507 g_assert_not_reached ();
1511 /* else, we have a container that potentially contains
1512 * some children that need to be byteswapped.
1518 children
= g_variant_serialised_n_children (serialised
);
1519 for (i
= 0; i
< children
; i
++)
1521 GVariantSerialised child
;
1523 child
= g_variant_serialised_get_child (serialised
, i
);
1524 g_variant_serialised_byteswap (child
);
1525 g_variant_type_info_unref (child
.type_info
);
1530 /* Normal form checking {{{2 */
1533 * g_variant_serialised_is_normal:
1534 * @serialised: a #GVariantSerialised
1536 * Determines, recursively if @serialised is in normal form. There is
1537 * precisely one normal form of serialised data for each possible value.
1539 * It is possible that multiple byte sequences form the serialised data
1540 * for a given value if, for example, the padding bytes are filled in
1541 * with something other than zeros, but only one form is the normal
1545 g_variant_serialised_is_normal (GVariantSerialised serialised
)
1547 DISPATCH_CASES (serialised
.type_info
,
1549 return gvs_
/**/,/**/_is_normal (serialised
);
1553 if (serialised
.data
== NULL
)
1556 /* some hard-coded terminal cases */
1557 switch (g_variant_type_info_get_type_char (serialised
.type_info
))
1559 case 'b': /* boolean */
1560 return serialised
.data
[0] < 2;
1562 case 's': /* string */
1563 return g_variant_serialiser_is_string (serialised
.data
,
1567 return g_variant_serialiser_is_object_path (serialised
.data
,
1571 return g_variant_serialiser_is_signature (serialised
.data
,
1575 /* all of the other types are fixed-sized numerical types for
1576 * which all possible values are valid (including various NaN
1577 * representations for floating point values).
1583 /* Validity-checking functions {{{2
1585 * Checks if strings, object paths and signature strings are valid.
1589 * g_variant_serialiser_is_string:
1590 * @data: a possible string
1591 * @size: the size of @data
1593 * Ensures that @data is a valid string with a nul terminator at the end
1594 * and no nul bytes embedded.
1597 g_variant_serialiser_is_string (gconstpointer data
,
1600 const gchar
*expected_end
;
1606 expected_end
= ((gchar
*) data
) + size
- 1;
1608 if (*expected_end
!= '\0')
1611 g_utf8_validate (data
, size
, &end
);
1613 return end
== expected_end
;
1617 * g_variant_serialiser_is_object_path:
1618 * @data: a possible D-Bus object path
1619 * @size: the size of @data
1621 * Performs the checks for being a valid string.
1623 * Also, ensures that @data is a valid DBus object path, as per the D-Bus
1627 g_variant_serialiser_is_object_path (gconstpointer data
,
1630 const gchar
*string
= data
;
1633 if (!g_variant_serialiser_is_string (data
, size
))
1636 /* The path must begin with an ASCII '/' (integer 47) character */
1637 if (string
[0] != '/')
1640 for (i
= 1; string
[i
]; i
++)
1641 /* Each element must only contain the ASCII characters
1642 * "[A-Z][a-z][0-9]_"
1644 if (g_ascii_isalnum (string
[i
]) || string
[i
] == '_')
1647 /* must consist of elements separated by slash characters. */
1648 else if (string
[i
] == '/')
1650 /* No element may be the empty string. */
1651 /* Multiple '/' characters cannot occur in sequence. */
1652 if (string
[i
- 1] == '/')
1659 /* A trailing '/' character is not allowed unless the path is the
1660 * root path (a single '/' character).
1662 if (i
> 1 && string
[i
- 1] == '/')
1669 * g_variant_serialiser_is_signature:
1670 * @data: a possible D-Bus signature
1671 * @size: the size of @data
1673 * Performs the checks for being a valid string.
1675 * Also, ensures that @data is a valid D-Bus type signature, as per the
1676 * D-Bus specification.
1679 g_variant_serialiser_is_signature (gconstpointer data
,
1682 const gchar
*string
= data
;
1683 gsize first_invalid
;
1685 if (!g_variant_serialiser_is_string (data
, size
))
1688 /* make sure no non-definite characters appear */
1689 first_invalid
= strspn (string
, "ybnqiuxthdvasog(){}");
1690 if (string
[first_invalid
])
1693 /* make sure each type string is well-formed */
1695 if (!g_variant_type_string_scan (string
, NULL
, &string
))
1702 /* vim:set foldmethod=marker: */