1 | /* |
2 | * Copyright © 2007, 2008 Ryan Lortie |
3 | * Copyright © 2009, 2010 Codethink Limited |
4 | * |
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.1 of the License, or (at your option) any later version. |
9 | * |
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. |
14 | * |
15 | * You should have received a copy of the GNU Lesser General Public |
16 | * License along with this library; if not, see <http://www.gnu.org/licenses/>. |
17 | * |
18 | * Author: Ryan Lortie <desrt@desrt.ca> |
19 | */ |
20 | |
21 | #include "config.h" |
22 | |
23 | #include "gvarianttype.h" |
24 | |
25 | #include <glib/gtestutils.h> |
26 | #include <glib/gstrfuncs.h> |
27 | #include <glib/gvariant-internal.h> |
28 | |
29 | #include <string.h> |
30 | |
31 | |
32 | /** |
33 | * SECTION:gvarianttype |
34 | * @title: GVariantType |
35 | * @short_description: introduction to the GVariant type system |
36 | * @see_also: #GVariantType, #GVariant |
37 | * |
38 | * This section introduces the GVariant type system. It is based, in |
39 | * large part, on the D-Bus type system, with two major changes and |
40 | * some minor lifting of restrictions. The |
41 | * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), |
42 | * therefore, provides a significant amount of |
43 | * information that is useful when working with GVariant. |
44 | * |
45 | * The first major change with respect to the D-Bus type system is the |
46 | * introduction of maybe (or "nullable") types. Any type in GVariant can be |
47 | * converted to a maybe type, in which case, "nothing" (or "null") becomes a |
48 | * valid value. Maybe types have been added by introducing the |
49 | * character "m" to type strings. |
50 | * |
51 | * The second major change is that the GVariant type system supports the |
52 | * concept of "indefinite types" -- types that are less specific than |
53 | * the normal types found in D-Bus. For example, it is possible to speak |
54 | * of "an array of any type" in GVariant, where the D-Bus type system |
55 | * would require you to speak of "an array of integers" or "an array of |
56 | * strings". Indefinite types have been added by introducing the |
57 | * characters "*", "?" and "r" to type strings. |
58 | * |
59 | * Finally, all arbitrary restrictions relating to the complexity of |
60 | * types are lifted along with the restriction that dictionary entries |
61 | * may only appear nested inside of arrays. |
62 | * |
63 | * Just as in D-Bus, GVariant types are described with strings ("type |
64 | * strings"). Subject to the differences mentioned above, these strings |
65 | * are of the same form as those found in D-Bus. Note, however: D-Bus |
66 | * always works in terms of messages and therefore individual type |
67 | * strings appear nowhere in its interface. Instead, "signatures" |
68 | * are a concatenation of the strings of the type of each argument in a |
69 | * message. GVariant deals with single values directly so GVariant type |
70 | * strings always describe the type of exactly one value. This means |
71 | * that a D-Bus signature string is generally not a valid GVariant type |
72 | * string -- except in the case that it is the signature of a message |
73 | * containing exactly one argument. |
74 | * |
75 | * An indefinite type is similar in spirit to what may be called an |
76 | * abstract type in other type systems. No value can exist that has an |
77 | * indefinite type as its type, but values can exist that have types |
78 | * that are subtypes of indefinite types. That is to say, |
79 | * g_variant_get_type() will never return an indefinite type, but |
80 | * calling g_variant_is_of_type() with an indefinite type may return |
81 | * %TRUE. For example, you cannot have a value that represents "an |
82 | * array of no particular type", but you can have an "array of integers" |
83 | * which certainly matches the type of "an array of no particular type", |
84 | * since "array of integers" is a subtype of "array of no particular |
85 | * type". |
86 | * |
87 | * This is similar to how instances of abstract classes may not |
88 | * directly exist in other type systems, but instances of their |
89 | * non-abstract subtypes may. For example, in GTK, no object that has |
90 | * the type of #GtkBin can exist (since #GtkBin is an abstract class), |
91 | * but a #GtkWindow can certainly be instantiated, and you would say |
92 | * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of |
93 | * #GtkBin). |
94 | * |
95 | * ## GVariant Type Strings |
96 | * |
97 | * A GVariant type string can be any of the following: |
98 | * |
99 | * - any basic type string (listed below) |
100 | * |
101 | * - "v", "r" or "*" |
102 | * |
103 | * - one of the characters 'a' or 'm', followed by another type string |
104 | * |
105 | * - the character '(', followed by a concatenation of zero or more other |
106 | * type strings, followed by the character ')' |
107 | * |
108 | * - the character '{', followed by a basic type string (see below), |
109 | * followed by another type string, followed by the character '}' |
110 | * |
111 | * A basic type string describes a basic type (as per |
112 | * g_variant_type_is_basic()) and is always a single character in length. |
113 | * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", |
114 | * "h", "d", "s", "o", "g" and "?". |
115 | * |
116 | * The above definition is recursive to arbitrary depth. "aaaaai" and |
117 | * "(ui(nq((y)))s)" are both valid type strings, as is |
118 | * "a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant |
119 | * imposes a limit on recursion depth of 65 nested containers. This is the |
120 | * limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to |
121 | * be nested in a top-level tuple. |
122 | * |
123 | * The meaning of each of the characters is as follows: |
124 | * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. |
125 | * - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte. |
126 | * - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer. |
127 | * - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer. |
128 | * - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer. |
129 | * - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer. |
130 | * - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer. |
131 | * - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer. |
132 | * - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value |
133 | * that, by convention, is used as an index into an array of file |
134 | * descriptors that are sent alongside a D-Bus message. |
135 | * - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision |
136 | * floating point value. |
137 | * - `s`: the type string of %G_VARIANT_TYPE_STRING; a string. |
138 | * - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form |
139 | * of a D-Bus object path. |
140 | * - `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of |
141 | * a D-Bus type signature. |
142 | * - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that |
143 | * is a supertype of any of the basic types. |
144 | * - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that |
145 | * contain any other type of value. |
146 | * - `a`: used as a prefix on another type string to mean an array of that |
147 | * type; the type string "ai", for example, is the type of an array of |
148 | * signed 32-bit integers. |
149 | * - `m`: used as a prefix on another type string to mean a "maybe", or |
150 | * "nullable", version of that type; the type string "ms", for example, |
151 | * is the type of a value that maybe contains a string, or maybe contains |
152 | * nothing. |
153 | * - `()`: used to enclose zero or more other concatenated type strings to |
154 | * create a tuple type; the type string "(is)", for example, is the type of |
155 | * a pair of an integer and a string. |
156 | * - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is |
157 | * a supertype of any tuple type, regardless of the number of items. |
158 | * - `{}`: used to enclose a basic type string concatenated with another type |
159 | * string to create a dictionary entry type, which usually appears inside of |
160 | * an array to form a dictionary; the type string "a{sd}", for example, is |
161 | * the type of a dictionary that maps strings to double precision floating |
162 | * point values. |
163 | * |
164 | * The first type (the basic type) is the key type and the second type is |
165 | * the value type. The reason that the first type is restricted to being a |
166 | * basic type is so that it can easily be hashed. |
167 | * - `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is |
168 | * a supertype of all types. Note that, as with all type strings, this |
169 | * character represents exactly one type. It cannot be used inside of tuples |
170 | * to mean "any number of items". |
171 | * |
172 | * Any type string of a container that contains an indefinite type is, |
173 | * itself, an indefinite type. For example, the type string "a*" |
174 | * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type |
175 | * that is a supertype of every array type. "(*s)" is a supertype |
176 | * of all tuples that contain exactly two items where the second |
177 | * item is a string. |
178 | * |
179 | * "a{?*}" is an indefinite type that is a supertype of all arrays |
180 | * containing dictionary entries where the key is any basic type and |
181 | * the value is any type at all. This is, by definition, a dictionary, |
182 | * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note |
183 | * that, due to the restriction that the key of a dictionary entry must |
184 | * be a basic type, "{**}" is not a valid type string. |
185 | */ |
186 | |
187 | |
188 | static gboolean |
189 | g_variant_type_check (const GVariantType *type) |
190 | { |
191 | if (type == NULL) |
192 | return FALSE; |
193 | |
194 | #if 0 |
195 | return g_variant_type_string_scan ((const gchar *) type, NULL, NULL); |
196 | #else |
197 | return TRUE; |
198 | #endif |
199 | } |
200 | |
201 | static gboolean |
202 | variant_type_string_scan_internal (const gchar *string, |
203 | const gchar *limit, |
204 | const gchar **endptr, |
205 | gsize *depth, |
206 | gsize depth_limit) |
207 | { |
208 | gsize max_depth = 0, child_depth; |
209 | |
210 | g_return_val_if_fail (string != NULL, FALSE); |
211 | |
212 | if (string == limit || *string == '\0') |
213 | return FALSE; |
214 | |
215 | switch (*string++) |
216 | { |
217 | case '(': |
218 | while (string == limit || *string != ')') |
219 | { |
220 | if (depth_limit == 0 || |
221 | !variant_type_string_scan_internal (string, limit, endptr: &string, |
222 | depth: &child_depth, |
223 | depth_limit: depth_limit - 1)) |
224 | return FALSE; |
225 | |
226 | max_depth = MAX (max_depth, child_depth + 1); |
227 | } |
228 | |
229 | string++; |
230 | break; |
231 | |
232 | case '{': |
233 | if (depth_limit == 0 || |
234 | string == limit || *string == '\0' || /* { */ |
235 | !strchr (s: "bynqihuxtdsog?" , c: *string++) || /* key */ |
236 | !variant_type_string_scan_internal (string, limit, endptr: &string, |
237 | depth: &child_depth, depth_limit: depth_limit - 1) || /* value */ |
238 | string == limit || *string++ != '}') /* } */ |
239 | return FALSE; |
240 | |
241 | max_depth = MAX (max_depth, child_depth + 1); |
242 | break; |
243 | |
244 | case 'm': case 'a': |
245 | if (depth_limit == 0 || |
246 | !variant_type_string_scan_internal (string, limit, endptr: &string, |
247 | depth: &child_depth, depth_limit: depth_limit - 1)) |
248 | return FALSE; |
249 | |
250 | max_depth = MAX (max_depth, child_depth + 1); |
251 | break; |
252 | |
253 | case 'b': case 'y': case 'n': case 'q': case 'i': case 'u': |
254 | case 'x': case 't': case 'd': case 's': case 'o': case 'g': |
255 | case 'v': case 'r': case '*': case '?': case 'h': |
256 | max_depth = MAX (max_depth, 1); |
257 | break; |
258 | |
259 | default: |
260 | return FALSE; |
261 | } |
262 | |
263 | if (endptr != NULL) |
264 | *endptr = string; |
265 | if (depth != NULL) |
266 | *depth = max_depth; |
267 | |
268 | return TRUE; |
269 | } |
270 | |
271 | /** |
272 | * g_variant_type_string_scan: |
273 | * @string: a pointer to any string |
274 | * @limit: (nullable): the end of @string, or %NULL |
275 | * @endptr: (out) (optional): location to store the end pointer, or %NULL |
276 | * |
277 | * Scan for a single complete and valid GVariant type string in @string. |
278 | * The memory pointed to by @limit (or bytes beyond it) is never |
279 | * accessed. |
280 | * |
281 | * If a valid type string is found, @endptr is updated to point to the |
282 | * first character past the end of the string that was found and %TRUE |
283 | * is returned. |
284 | * |
285 | * If there is no valid type string starting at @string, or if the type |
286 | * string does not end before @limit then %FALSE is returned. |
287 | * |
288 | * For the simple case of checking if a string is a valid type string, |
289 | * see g_variant_type_string_is_valid(). |
290 | * |
291 | * Returns: %TRUE if a valid type string was found |
292 | * |
293 | * Since: 2.24 |
294 | **/ |
295 | gboolean |
296 | g_variant_type_string_scan (const gchar *string, |
297 | const gchar *limit, |
298 | const gchar **endptr) |
299 | { |
300 | return variant_type_string_scan_internal (string, limit, endptr, NULL, |
301 | G_VARIANT_MAX_RECURSION_DEPTH); |
302 | } |
303 | |
304 | /* < private > |
305 | * g_variant_type_string_get_depth_: |
306 | * @type_string: a pointer to any string |
307 | * |
308 | * Get the maximum depth of the nested types in @type_string. A basic type will |
309 | * return depth 1, and a container type will return a greater value. The depth |
310 | * of a tuple is 1 plus the depth of its deepest child type. |
311 | * |
312 | * If @type_string is not a valid #GVariant type string, 0 will be returned. |
313 | * |
314 | * Returns: depth of @type_string, or 0 on error |
315 | * Since: 2.60 |
316 | */ |
317 | gsize |
318 | g_variant_type_string_get_depth_ (const gchar *type_string) |
319 | { |
320 | const gchar *endptr; |
321 | gsize depth = 0; |
322 | |
323 | g_return_val_if_fail (type_string != NULL, 0); |
324 | |
325 | if (!variant_type_string_scan_internal (string: type_string, NULL, endptr: &endptr, depth: &depth, |
326 | G_VARIANT_MAX_RECURSION_DEPTH) || |
327 | *endptr != '\0') |
328 | return 0; |
329 | |
330 | return depth; |
331 | } |
332 | |
333 | /** |
334 | * g_variant_type_string_is_valid: |
335 | * @type_string: a pointer to any string |
336 | * |
337 | * Checks if @type_string is a valid GVariant type string. This call is |
338 | * equivalent to calling g_variant_type_string_scan() and confirming |
339 | * that the following character is a nul terminator. |
340 | * |
341 | * Returns: %TRUE if @type_string is exactly one valid type string |
342 | * |
343 | * Since 2.24 |
344 | **/ |
345 | gboolean |
346 | g_variant_type_string_is_valid (const gchar *type_string) |
347 | { |
348 | const gchar *endptr; |
349 | |
350 | g_return_val_if_fail (type_string != NULL, FALSE); |
351 | |
352 | if (!g_variant_type_string_scan (string: type_string, NULL, endptr: &endptr)) |
353 | return FALSE; |
354 | |
355 | return *endptr == '\0'; |
356 | } |
357 | |
358 | /** |
359 | * g_variant_type_free: |
360 | * @type: (nullable): a #GVariantType, or %NULL |
361 | * |
362 | * Frees a #GVariantType that was allocated with |
363 | * g_variant_type_copy(), g_variant_type_new() or one of the container |
364 | * type constructor functions. |
365 | * |
366 | * In the case that @type is %NULL, this function does nothing. |
367 | * |
368 | * Since 2.24 |
369 | **/ |
370 | void |
371 | g_variant_type_free (GVariantType *type) |
372 | { |
373 | g_return_if_fail (type == NULL || g_variant_type_check (type)); |
374 | |
375 | g_free (mem: type); |
376 | } |
377 | |
378 | /** |
379 | * g_variant_type_copy: |
380 | * @type: a #GVariantType |
381 | * |
382 | * Makes a copy of a #GVariantType. It is appropriate to call |
383 | * g_variant_type_free() on the return value. @type may not be %NULL. |
384 | * |
385 | * Returns: (transfer full): a new #GVariantType |
386 | * |
387 | * Since 2.24 |
388 | **/ |
389 | GVariantType * |
390 | g_variant_type_copy (const GVariantType *type) |
391 | { |
392 | gsize length; |
393 | gchar *new; |
394 | |
395 | g_return_val_if_fail (g_variant_type_check (type), NULL); |
396 | |
397 | length = g_variant_type_get_string_length (type); |
398 | new = g_malloc (n_bytes: length + 1); |
399 | |
400 | memcpy (dest: new, src: type, n: length); |
401 | new[length] = '\0'; |
402 | |
403 | return (GVariantType *) new; |
404 | } |
405 | |
406 | /** |
407 | * g_variant_type_new: |
408 | * @type_string: a valid GVariant type string |
409 | * |
410 | * Creates a new #GVariantType corresponding to the type string given |
411 | * by @type_string. It is appropriate to call g_variant_type_free() on |
412 | * the return value. |
413 | * |
414 | * It is a programmer error to call this function with an invalid type |
415 | * string. Use g_variant_type_string_is_valid() if you are unsure. |
416 | * |
417 | * Returns: (transfer full): a new #GVariantType |
418 | * |
419 | * Since: 2.24 |
420 | */ |
421 | GVariantType * |
422 | g_variant_type_new (const gchar *type_string) |
423 | { |
424 | g_return_val_if_fail (type_string != NULL, NULL); |
425 | |
426 | return g_variant_type_copy (G_VARIANT_TYPE (type_string)); |
427 | } |
428 | |
429 | /** |
430 | * g_variant_type_get_string_length: |
431 | * @type: a #GVariantType |
432 | * |
433 | * Returns the length of the type string corresponding to the given |
434 | * @type. This function must be used to determine the valid extent of |
435 | * the memory region returned by g_variant_type_peek_string(). |
436 | * |
437 | * Returns: the length of the corresponding type string |
438 | * |
439 | * Since 2.24 |
440 | **/ |
441 | gsize |
442 | g_variant_type_get_string_length (const GVariantType *type) |
443 | { |
444 | const gchar *type_string = (const gchar *) type; |
445 | gint brackets = 0; |
446 | gsize index = 0; |
447 | |
448 | g_return_val_if_fail (g_variant_type_check (type), 0); |
449 | |
450 | do |
451 | { |
452 | while (type_string[index] == 'a' || type_string[index] == 'm') |
453 | index++; |
454 | |
455 | if (type_string[index] == '(' || type_string[index] == '{') |
456 | brackets++; |
457 | |
458 | else if (type_string[index] == ')' || type_string[index] == '}') |
459 | brackets--; |
460 | |
461 | index++; |
462 | } |
463 | while (brackets); |
464 | |
465 | return index; |
466 | } |
467 | |
468 | /* |
469 | This function is not introspectable, it returns something that |
470 | is not an array and neither a string |
471 | */ |
472 | /** |
473 | * g_variant_type_peek_string: (skip) |
474 | * @type: a #GVariantType |
475 | * |
476 | * Returns the type string corresponding to the given @type. The |
477 | * result is not nul-terminated; in order to determine its length you |
478 | * must call g_variant_type_get_string_length(). |
479 | * |
480 | * To get a nul-terminated string, see g_variant_type_dup_string(). |
481 | * |
482 | * Returns: the corresponding type string (not nul-terminated) |
483 | * |
484 | * Since 2.24 |
485 | **/ |
486 | const gchar * |
487 | g_variant_type_peek_string (const GVariantType *type) |
488 | { |
489 | g_return_val_if_fail (g_variant_type_check (type), NULL); |
490 | |
491 | return (const gchar *) type; |
492 | } |
493 | |
494 | /** |
495 | * g_variant_type_dup_string: |
496 | * @type: a #GVariantType |
497 | * |
498 | * Returns a newly-allocated copy of the type string corresponding to |
499 | * @type. The returned string is nul-terminated. It is appropriate to |
500 | * call g_free() on the return value. |
501 | * |
502 | * Returns: (transfer full): the corresponding type string |
503 | * |
504 | * Since 2.24 |
505 | **/ |
506 | gchar * |
507 | g_variant_type_dup_string (const GVariantType *type) |
508 | { |
509 | g_return_val_if_fail (g_variant_type_check (type), NULL); |
510 | |
511 | return g_strndup (str: g_variant_type_peek_string (type), |
512 | n: g_variant_type_get_string_length (type)); |
513 | } |
514 | |
515 | /** |
516 | * g_variant_type_is_definite: |
517 | * @type: a #GVariantType |
518 | * |
519 | * Determines if the given @type is definite (ie: not indefinite). |
520 | * |
521 | * A type is definite if its type string does not contain any indefinite |
522 | * type characters ('*', '?', or 'r'). |
523 | * |
524 | * A #GVariant instance may not have an indefinite type, so calling |
525 | * this function on the result of g_variant_get_type() will always |
526 | * result in %TRUE being returned. Calling this function on an |
527 | * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in |
528 | * %FALSE being returned. |
529 | * |
530 | * Returns: %TRUE if @type is definite |
531 | * |
532 | * Since 2.24 |
533 | **/ |
534 | gboolean |
535 | g_variant_type_is_definite (const GVariantType *type) |
536 | { |
537 | const gchar *type_string; |
538 | gsize type_length; |
539 | gsize i; |
540 | |
541 | g_return_val_if_fail (g_variant_type_check (type), FALSE); |
542 | |
543 | type_length = g_variant_type_get_string_length (type); |
544 | type_string = g_variant_type_peek_string (type); |
545 | |
546 | for (i = 0; i < type_length; i++) |
547 | if (type_string[i] == '*' || |
548 | type_string[i] == '?' || |
549 | type_string[i] == 'r') |
550 | return FALSE; |
551 | |
552 | return TRUE; |
553 | } |
554 | |
555 | /** |
556 | * g_variant_type_is_container: |
557 | * @type: a #GVariantType |
558 | * |
559 | * Determines if the given @type is a container type. |
560 | * |
561 | * Container types are any array, maybe, tuple, or dictionary |
562 | * entry types plus the variant type. |
563 | * |
564 | * This function returns %TRUE for any indefinite type for which every |
565 | * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for |
566 | * example. |
567 | * |
568 | * Returns: %TRUE if @type is a container type |
569 | * |
570 | * Since 2.24 |
571 | **/ |
572 | gboolean |
573 | g_variant_type_is_container (const GVariantType *type) |
574 | { |
575 | gchar first_char; |
576 | |
577 | g_return_val_if_fail (g_variant_type_check (type), FALSE); |
578 | |
579 | first_char = g_variant_type_peek_string (type)[0]; |
580 | switch (first_char) |
581 | { |
582 | case 'a': |
583 | case 'm': |
584 | case 'r': |
585 | case '(': |
586 | case '{': |
587 | case 'v': |
588 | return TRUE; |
589 | |
590 | default: |
591 | return FALSE; |
592 | } |
593 | } |
594 | |
595 | /** |
596 | * g_variant_type_is_basic: |
597 | * @type: a #GVariantType |
598 | * |
599 | * Determines if the given @type is a basic type. |
600 | * |
601 | * Basic types are booleans, bytes, integers, doubles, strings, object |
602 | * paths and signatures. |
603 | * |
604 | * Only a basic type may be used as the key of a dictionary entry. |
605 | * |
606 | * This function returns %FALSE for all indefinite types except |
607 | * %G_VARIANT_TYPE_BASIC. |
608 | * |
609 | * Returns: %TRUE if @type is a basic type |
610 | * |
611 | * Since 2.24 |
612 | **/ |
613 | gboolean |
614 | g_variant_type_is_basic (const GVariantType *type) |
615 | { |
616 | gchar first_char; |
617 | |
618 | g_return_val_if_fail (g_variant_type_check (type), FALSE); |
619 | |
620 | first_char = g_variant_type_peek_string (type)[0]; |
621 | switch (first_char) |
622 | { |
623 | case 'b': |
624 | case 'y': |
625 | case 'n': |
626 | case 'q': |
627 | case 'i': |
628 | case 'h': |
629 | case 'u': |
630 | case 't': |
631 | case 'x': |
632 | case 'd': |
633 | case 's': |
634 | case 'o': |
635 | case 'g': |
636 | case '?': |
637 | return TRUE; |
638 | |
639 | default: |
640 | return FALSE; |
641 | } |
642 | } |
643 | |
644 | /** |
645 | * g_variant_type_is_maybe: |
646 | * @type: a #GVariantType |
647 | * |
648 | * Determines if the given @type is a maybe type. This is true if the |
649 | * type string for @type starts with an 'm'. |
650 | * |
651 | * This function returns %TRUE for any indefinite type for which every |
652 | * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for |
653 | * example. |
654 | * |
655 | * Returns: %TRUE if @type is a maybe type |
656 | * |
657 | * Since 2.24 |
658 | **/ |
659 | gboolean |
660 | g_variant_type_is_maybe (const GVariantType *type) |
661 | { |
662 | g_return_val_if_fail (g_variant_type_check (type), FALSE); |
663 | |
664 | return g_variant_type_peek_string (type)[0] == 'm'; |
665 | } |
666 | |
667 | /** |
668 | * g_variant_type_is_array: |
669 | * @type: a #GVariantType |
670 | * |
671 | * Determines if the given @type is an array type. This is true if the |
672 | * type string for @type starts with an 'a'. |
673 | * |
674 | * This function returns %TRUE for any indefinite type for which every |
675 | * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for |
676 | * example. |
677 | * |
678 | * Returns: %TRUE if @type is an array type |
679 | * |
680 | * Since 2.24 |
681 | **/ |
682 | gboolean |
683 | g_variant_type_is_array (const GVariantType *type) |
684 | { |
685 | g_return_val_if_fail (g_variant_type_check (type), FALSE); |
686 | |
687 | return g_variant_type_peek_string (type)[0] == 'a'; |
688 | } |
689 | |
690 | /** |
691 | * g_variant_type_is_tuple: |
692 | * @type: a #GVariantType |
693 | * |
694 | * Determines if the given @type is a tuple type. This is true if the |
695 | * type string for @type starts with a '(' or if @type is |
696 | * %G_VARIANT_TYPE_TUPLE. |
697 | * |
698 | * This function returns %TRUE for any indefinite type for which every |
699 | * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for |
700 | * example. |
701 | * |
702 | * Returns: %TRUE if @type is a tuple type |
703 | * |
704 | * Since 2.24 |
705 | **/ |
706 | gboolean |
707 | g_variant_type_is_tuple (const GVariantType *type) |
708 | { |
709 | gchar type_char; |
710 | |
711 | g_return_val_if_fail (g_variant_type_check (type), FALSE); |
712 | |
713 | type_char = g_variant_type_peek_string (type)[0]; |
714 | return type_char == 'r' || type_char == '('; |
715 | } |
716 | |
717 | /** |
718 | * g_variant_type_is_dict_entry: |
719 | * @type: a #GVariantType |
720 | * |
721 | * Determines if the given @type is a dictionary entry type. This is |
722 | * true if the type string for @type starts with a '{'. |
723 | * |
724 | * This function returns %TRUE for any indefinite type for which every |
725 | * definite subtype is a dictionary entry type -- |
726 | * %G_VARIANT_TYPE_DICT_ENTRY, for example. |
727 | * |
728 | * Returns: %TRUE if @type is a dictionary entry type |
729 | * |
730 | * Since 2.24 |
731 | **/ |
732 | gboolean |
733 | g_variant_type_is_dict_entry (const GVariantType *type) |
734 | { |
735 | g_return_val_if_fail (g_variant_type_check (type), FALSE); |
736 | |
737 | return g_variant_type_peek_string (type)[0] == '{'; |
738 | } |
739 | |
740 | /** |
741 | * g_variant_type_is_variant: |
742 | * @type: a #GVariantType |
743 | * |
744 | * Determines if the given @type is the variant type. |
745 | * |
746 | * Returns: %TRUE if @type is the variant type |
747 | * |
748 | * Since 2.24 |
749 | **/ |
750 | gboolean |
751 | g_variant_type_is_variant (const GVariantType *type) |
752 | { |
753 | g_return_val_if_fail (g_variant_type_check (type), FALSE); |
754 | |
755 | return g_variant_type_peek_string (type)[0] == 'v'; |
756 | } |
757 | |
758 | /** |
759 | * g_variant_type_hash: |
760 | * @type: (type GVariantType): a #GVariantType |
761 | * |
762 | * Hashes @type. |
763 | * |
764 | * The argument type of @type is only #gconstpointer to allow use with |
765 | * #GHashTable without function pointer casting. A valid |
766 | * #GVariantType must be provided. |
767 | * |
768 | * Returns: the hash value |
769 | * |
770 | * Since 2.24 |
771 | **/ |
772 | guint |
773 | g_variant_type_hash (gconstpointer type) |
774 | { |
775 | const gchar *type_string; |
776 | guint value = 0; |
777 | gsize length; |
778 | gsize i; |
779 | |
780 | g_return_val_if_fail (g_variant_type_check (type), 0); |
781 | |
782 | type_string = g_variant_type_peek_string (type); |
783 | length = g_variant_type_get_string_length (type); |
784 | |
785 | for (i = 0; i < length; i++) |
786 | value = (value << 5) - value + type_string[i]; |
787 | |
788 | return value; |
789 | } |
790 | |
791 | /** |
792 | * g_variant_type_equal: |
793 | * @type1: (type GVariantType): a #GVariantType |
794 | * @type2: (type GVariantType): a #GVariantType |
795 | * |
796 | * Compares @type1 and @type2 for equality. |
797 | * |
798 | * Only returns %TRUE if the types are exactly equal. Even if one type |
799 | * is an indefinite type and the other is a subtype of it, %FALSE will |
800 | * be returned if they are not exactly equal. If you want to check for |
801 | * subtypes, use g_variant_type_is_subtype_of(). |
802 | * |
803 | * The argument types of @type1 and @type2 are only #gconstpointer to |
804 | * allow use with #GHashTable without function pointer casting. For |
805 | * both arguments, a valid #GVariantType must be provided. |
806 | * |
807 | * Returns: %TRUE if @type1 and @type2 are exactly equal |
808 | * |
809 | * Since 2.24 |
810 | **/ |
811 | gboolean |
812 | g_variant_type_equal (gconstpointer type1, |
813 | gconstpointer type2) |
814 | { |
815 | const gchar *string1, *string2; |
816 | gsize size1, size2; |
817 | |
818 | g_return_val_if_fail (g_variant_type_check (type1), FALSE); |
819 | g_return_val_if_fail (g_variant_type_check (type2), FALSE); |
820 | |
821 | if (type1 == type2) |
822 | return TRUE; |
823 | |
824 | size1 = g_variant_type_get_string_length (type: type1); |
825 | size2 = g_variant_type_get_string_length (type: type2); |
826 | |
827 | if (size1 != size2) |
828 | return FALSE; |
829 | |
830 | string1 = g_variant_type_peek_string (type: type1); |
831 | string2 = g_variant_type_peek_string (type: type2); |
832 | |
833 | return memcmp (s1: string1, s2: string2, n: size1) == 0; |
834 | } |
835 | |
836 | /** |
837 | * g_variant_type_is_subtype_of: |
838 | * @type: a #GVariantType |
839 | * @supertype: a #GVariantType |
840 | * |
841 | * Checks if @type is a subtype of @supertype. |
842 | * |
843 | * This function returns %TRUE if @type is a subtype of @supertype. All |
844 | * types are considered to be subtypes of themselves. Aside from that, |
845 | * only indefinite types can have subtypes. |
846 | * |
847 | * Returns: %TRUE if @type is a subtype of @supertype |
848 | * |
849 | * Since 2.24 |
850 | **/ |
851 | gboolean |
852 | g_variant_type_is_subtype_of (const GVariantType *type, |
853 | const GVariantType *supertype) |
854 | { |
855 | const gchar *supertype_string; |
856 | const gchar *supertype_end; |
857 | const gchar *type_string; |
858 | |
859 | g_return_val_if_fail (g_variant_type_check (type), FALSE); |
860 | g_return_val_if_fail (g_variant_type_check (supertype), FALSE); |
861 | |
862 | supertype_string = g_variant_type_peek_string (type: supertype); |
863 | type_string = g_variant_type_peek_string (type); |
864 | |
865 | supertype_end = supertype_string + |
866 | g_variant_type_get_string_length (type: supertype); |
867 | |
868 | /* we know that type and supertype are both well-formed, so it's |
869 | * safe to treat this merely as a text processing problem. |
870 | */ |
871 | while (supertype_string < supertype_end) |
872 | { |
873 | char supertype_char = *supertype_string++; |
874 | |
875 | if (supertype_char == *type_string) |
876 | type_string++; |
877 | |
878 | else if (*type_string == ')') |
879 | return FALSE; |
880 | |
881 | else |
882 | { |
883 | const GVariantType *target_type = (GVariantType *) type_string; |
884 | |
885 | switch (supertype_char) |
886 | { |
887 | case 'r': |
888 | if (!g_variant_type_is_tuple (type: target_type)) |
889 | return FALSE; |
890 | break; |
891 | |
892 | case '*': |
893 | break; |
894 | |
895 | case '?': |
896 | if (!g_variant_type_is_basic (type: target_type)) |
897 | return FALSE; |
898 | break; |
899 | |
900 | default: |
901 | return FALSE; |
902 | } |
903 | |
904 | type_string += g_variant_type_get_string_length (type: target_type); |
905 | } |
906 | } |
907 | |
908 | return TRUE; |
909 | } |
910 | |
911 | /** |
912 | * g_variant_type_element: |
913 | * @type: an array or maybe #GVariantType |
914 | * |
915 | * Determines the element type of an array or maybe type. |
916 | * |
917 | * This function may only be used with array or maybe types. |
918 | * |
919 | * Returns: (transfer none): the element type of @type |
920 | * |
921 | * Since 2.24 |
922 | **/ |
923 | const GVariantType * |
924 | g_variant_type_element (const GVariantType *type) |
925 | { |
926 | const gchar *type_string; |
927 | |
928 | g_return_val_if_fail (g_variant_type_check (type), NULL); |
929 | |
930 | type_string = g_variant_type_peek_string (type); |
931 | |
932 | g_assert (type_string[0] == 'a' || type_string[0] == 'm'); |
933 | |
934 | return (const GVariantType *) &type_string[1]; |
935 | } |
936 | |
937 | /** |
938 | * g_variant_type_first: |
939 | * @type: a tuple or dictionary entry #GVariantType |
940 | * |
941 | * Determines the first item type of a tuple or dictionary entry |
942 | * type. |
943 | * |
944 | * This function may only be used with tuple or dictionary entry types, |
945 | * but must not be used with the generic tuple type |
946 | * %G_VARIANT_TYPE_TUPLE. |
947 | * |
948 | * In the case of a dictionary entry type, this returns the type of |
949 | * the key. |
950 | * |
951 | * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT. |
952 | * |
953 | * This call, together with g_variant_type_next() provides an iterator |
954 | * interface over tuple and dictionary entry types. |
955 | * |
956 | * Returns: (transfer none): the first item type of @type, or %NULL |
957 | * |
958 | * Since 2.24 |
959 | **/ |
960 | const GVariantType * |
961 | g_variant_type_first (const GVariantType *type) |
962 | { |
963 | const gchar *type_string; |
964 | |
965 | g_return_val_if_fail (g_variant_type_check (type), NULL); |
966 | |
967 | type_string = g_variant_type_peek_string (type); |
968 | g_assert (type_string[0] == '(' || type_string[0] == '{'); |
969 | |
970 | if (type_string[1] == ')') |
971 | return NULL; |
972 | |
973 | return (const GVariantType *) &type_string[1]; |
974 | } |
975 | |
976 | /** |
977 | * g_variant_type_next: |
978 | * @type: a #GVariantType from a previous call |
979 | * |
980 | * Determines the next item type of a tuple or dictionary entry |
981 | * type. |
982 | * |
983 | * @type must be the result of a previous call to |
984 | * g_variant_type_first() or g_variant_type_next(). |
985 | * |
986 | * If called on the key type of a dictionary entry then this call |
987 | * returns the value type. If called on the value type of a dictionary |
988 | * entry then this call returns %NULL. |
989 | * |
990 | * For tuples, %NULL is returned when @type is the last item in a tuple. |
991 | * |
992 | * Returns: (transfer none): the next #GVariantType after @type, or %NULL |
993 | * |
994 | * Since 2.24 |
995 | **/ |
996 | const GVariantType * |
997 | g_variant_type_next (const GVariantType *type) |
998 | { |
999 | const gchar *type_string; |
1000 | |
1001 | g_return_val_if_fail (g_variant_type_check (type), NULL); |
1002 | |
1003 | type_string = g_variant_type_peek_string (type); |
1004 | type_string += g_variant_type_get_string_length (type); |
1005 | |
1006 | if (*type_string == ')' || *type_string == '}') |
1007 | return NULL; |
1008 | |
1009 | return (const GVariantType *) type_string; |
1010 | } |
1011 | |
1012 | /** |
1013 | * g_variant_type_n_items: |
1014 | * @type: a tuple or dictionary entry #GVariantType |
1015 | * |
1016 | * Determines the number of items contained in a tuple or |
1017 | * dictionary entry type. |
1018 | * |
1019 | * This function may only be used with tuple or dictionary entry types, |
1020 | * but must not be used with the generic tuple type |
1021 | * %G_VARIANT_TYPE_TUPLE. |
1022 | * |
1023 | * In the case of a dictionary entry type, this function will always |
1024 | * return 2. |
1025 | * |
1026 | * Returns: the number of items in @type |
1027 | * |
1028 | * Since 2.24 |
1029 | **/ |
1030 | gsize |
1031 | g_variant_type_n_items (const GVariantType *type) |
1032 | { |
1033 | gsize count = 0; |
1034 | |
1035 | g_return_val_if_fail (g_variant_type_check (type), 0); |
1036 | |
1037 | for (type = g_variant_type_first (type); |
1038 | type; |
1039 | type = g_variant_type_next (type)) |
1040 | count++; |
1041 | |
1042 | return count; |
1043 | } |
1044 | |
1045 | /** |
1046 | * g_variant_type_key: |
1047 | * @type: a dictionary entry #GVariantType |
1048 | * |
1049 | * Determines the key type of a dictionary entry type. |
1050 | * |
1051 | * This function may only be used with a dictionary entry type. Other |
1052 | * than the additional restriction, this call is equivalent to |
1053 | * g_variant_type_first(). |
1054 | * |
1055 | * Returns: (transfer none): the key type of the dictionary entry |
1056 | * |
1057 | * Since 2.24 |
1058 | **/ |
1059 | const GVariantType * |
1060 | g_variant_type_key (const GVariantType *type) |
1061 | { |
1062 | const gchar *type_string; |
1063 | |
1064 | g_return_val_if_fail (g_variant_type_check (type), NULL); |
1065 | |
1066 | type_string = g_variant_type_peek_string (type); |
1067 | g_assert (type_string[0] == '{'); |
1068 | |
1069 | return (const GVariantType *) &type_string[1]; |
1070 | } |
1071 | |
1072 | /** |
1073 | * g_variant_type_value: |
1074 | * @type: a dictionary entry #GVariantType |
1075 | * |
1076 | * Determines the value type of a dictionary entry type. |
1077 | * |
1078 | * This function may only be used with a dictionary entry type. |
1079 | * |
1080 | * Returns: (transfer none): the value type of the dictionary entry |
1081 | * |
1082 | * Since 2.24 |
1083 | **/ |
1084 | const GVariantType * |
1085 | g_variant_type_value (const GVariantType *type) |
1086 | { |
1087 | #ifndef G_DISABLE_ASSERT |
1088 | const gchar *type_string; |
1089 | #endif |
1090 | |
1091 | g_return_val_if_fail (g_variant_type_check (type), NULL); |
1092 | |
1093 | #ifndef G_DISABLE_ASSERT |
1094 | type_string = g_variant_type_peek_string (type); |
1095 | g_assert (type_string[0] == '{'); |
1096 | #endif |
1097 | |
1098 | return g_variant_type_next (type: g_variant_type_key (type)); |
1099 | } |
1100 | |
1101 | /** |
1102 | * g_variant_type_new_tuple: |
1103 | * @items: (array length=length): an array of #GVariantTypes, one for each item |
1104 | * @length: the length of @items, or -1 |
1105 | * |
1106 | * Constructs a new tuple type, from @items. |
1107 | * |
1108 | * @length is the number of items in @items, or -1 to indicate that |
1109 | * @items is %NULL-terminated. |
1110 | * |
1111 | * It is appropriate to call g_variant_type_free() on the return value. |
1112 | * |
1113 | * Returns: (transfer full): a new tuple #GVariantType |
1114 | * |
1115 | * Since 2.24 |
1116 | **/ |
1117 | static GVariantType * |
1118 | g_variant_type_new_tuple_slow (const GVariantType * const *items, |
1119 | gint length) |
1120 | { |
1121 | /* the "slow" version is needed in case the static buffer of 1024 |
1122 | * bytes is exceeded when running the normal version. this will |
1123 | * happen only with very unusually large types, so it can be slow. |
1124 | */ |
1125 | GString *string; |
1126 | gint i; |
1127 | |
1128 | string = g_string_new (init: "(" ); |
1129 | for (i = 0; i < length; i++) |
1130 | { |
1131 | const GVariantType *type; |
1132 | gsize size; |
1133 | |
1134 | g_return_val_if_fail (g_variant_type_check (items[i]), NULL); |
1135 | |
1136 | type = items[i]; |
1137 | size = g_variant_type_get_string_length (type); |
1138 | g_string_append_len (string, val: (const gchar *) type, len: size); |
1139 | } |
1140 | g_string_append_c (string, ')'); |
1141 | |
1142 | return (GVariantType *) g_string_free (string, FALSE); |
1143 | } |
1144 | |
1145 | GVariantType * |
1146 | g_variant_type_new_tuple (const GVariantType * const *items, |
1147 | gint length) |
1148 | { |
1149 | char buffer[1024]; |
1150 | gsize offset; |
1151 | gsize i; |
1152 | gsize length_unsigned; |
1153 | |
1154 | g_return_val_if_fail (length == 0 || items != NULL, NULL); |
1155 | |
1156 | if (length < 0) |
1157 | for (length_unsigned = 0; items[length_unsigned] != NULL; length_unsigned++); |
1158 | else |
1159 | length_unsigned = (gsize) length; |
1160 | |
1161 | offset = 0; |
1162 | buffer[offset++] = '('; |
1163 | |
1164 | for (i = 0; i < length_unsigned; i++) |
1165 | { |
1166 | const GVariantType *type; |
1167 | gsize size; |
1168 | |
1169 | g_return_val_if_fail (g_variant_type_check (items[i]), NULL); |
1170 | |
1171 | type = items[i]; |
1172 | size = g_variant_type_get_string_length (type); |
1173 | |
1174 | if (offset + size >= sizeof buffer) /* leave room for ')' */ |
1175 | return g_variant_type_new_tuple_slow (items, length: length_unsigned); |
1176 | |
1177 | memcpy (dest: &buffer[offset], src: type, n: size); |
1178 | offset += size; |
1179 | } |
1180 | |
1181 | g_assert (offset < sizeof buffer); |
1182 | buffer[offset++] = ')'; |
1183 | |
1184 | return (GVariantType *) g_memdup2 (mem: buffer, byte_size: offset); |
1185 | } |
1186 | |
1187 | /** |
1188 | * g_variant_type_new_array: (constructor) |
1189 | * @element: a #GVariantType |
1190 | * |
1191 | * Constructs the type corresponding to an array of elements of the |
1192 | * type @type. |
1193 | * |
1194 | * It is appropriate to call g_variant_type_free() on the return value. |
1195 | * |
1196 | * Returns: (transfer full): a new array #GVariantType |
1197 | * |
1198 | * Since 2.24 |
1199 | **/ |
1200 | GVariantType * |
1201 | g_variant_type_new_array (const GVariantType *element) |
1202 | { |
1203 | gsize size; |
1204 | gchar *new; |
1205 | |
1206 | g_return_val_if_fail (g_variant_type_check (element), NULL); |
1207 | |
1208 | size = g_variant_type_get_string_length (type: element); |
1209 | new = g_malloc (n_bytes: size + 1); |
1210 | |
1211 | new[0] = 'a'; |
1212 | memcpy (dest: new + 1, src: element, n: size); |
1213 | |
1214 | return (GVariantType *) new; |
1215 | } |
1216 | |
1217 | /** |
1218 | * g_variant_type_new_maybe: (constructor) |
1219 | * @element: a #GVariantType |
1220 | * |
1221 | * Constructs the type corresponding to a maybe instance containing |
1222 | * type @type or Nothing. |
1223 | * |
1224 | * It is appropriate to call g_variant_type_free() on the return value. |
1225 | * |
1226 | * Returns: (transfer full): a new maybe #GVariantType |
1227 | * |
1228 | * Since 2.24 |
1229 | **/ |
1230 | GVariantType * |
1231 | g_variant_type_new_maybe (const GVariantType *element) |
1232 | { |
1233 | gsize size; |
1234 | gchar *new; |
1235 | |
1236 | g_return_val_if_fail (g_variant_type_check (element), NULL); |
1237 | |
1238 | size = g_variant_type_get_string_length (type: element); |
1239 | new = g_malloc (n_bytes: size + 1); |
1240 | |
1241 | new[0] = 'm'; |
1242 | memcpy (dest: new + 1, src: element, n: size); |
1243 | |
1244 | return (GVariantType *) new; |
1245 | } |
1246 | |
1247 | /** |
1248 | * g_variant_type_new_dict_entry: (constructor) |
1249 | * @key: a basic #GVariantType |
1250 | * @value: a #GVariantType |
1251 | * |
1252 | * Constructs the type corresponding to a dictionary entry with a key |
1253 | * of type @key and a value of type @value. |
1254 | * |
1255 | * It is appropriate to call g_variant_type_free() on the return value. |
1256 | * |
1257 | * Returns: (transfer full): a new dictionary entry #GVariantType |
1258 | * |
1259 | * Since 2.24 |
1260 | **/ |
1261 | GVariantType * |
1262 | g_variant_type_new_dict_entry (const GVariantType *key, |
1263 | const GVariantType *value) |
1264 | { |
1265 | gsize keysize, valsize; |
1266 | gchar *new; |
1267 | |
1268 | g_return_val_if_fail (g_variant_type_check (key), NULL); |
1269 | g_return_val_if_fail (g_variant_type_check (value), NULL); |
1270 | |
1271 | keysize = g_variant_type_get_string_length (type: key); |
1272 | valsize = g_variant_type_get_string_length (type: value); |
1273 | |
1274 | new = g_malloc (n_bytes: 1 + keysize + valsize + 1); |
1275 | |
1276 | new[0] = '{'; |
1277 | memcpy (dest: new + 1, src: key, n: keysize); |
1278 | memcpy (dest: new + 1 + keysize, src: value, n: valsize); |
1279 | new[1 + keysize + valsize] = '}'; |
1280 | |
1281 | return (GVariantType *) new; |
1282 | } |
1283 | |
1284 | /* private */ |
1285 | const GVariantType * |
1286 | g_variant_type_checked_ (const gchar *type_string) |
1287 | { |
1288 | g_return_val_if_fail (g_variant_type_string_is_valid (type_string), NULL); |
1289 | return (const GVariantType *) type_string; |
1290 | } |
1291 | |