1 /* 2 * Copyright © 2007, 2008 Ryan Lortie 3 * Copyright © 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 of the licence, 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, write to the 17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330, 18 * Boston, MA 02111-1307, USA. 19 * 20 * Author: Ryan Lortie <desrt@desrt.ca> 21 */ 22 23 /* Prologue {{{1 */ 24 25 #include "config.h" 26 27 #include <glib/gvariant-serialiser.h> 28 #include "gvariant-internal.h" 29 #include <glib/gvariant-core.h> 30 #include <glib/gtestutils.h> 31 #include <glib/gstrfuncs.h> 32 #include <glib/ghash.h> 33 #include <glib/gmem.h> 34 35 #include <string.h> 36 37 38 /** 39 * SECTION:gvariant 40 * @title: GVariant 41 * @short_description: strongly typed value datatype 42 * @see_also: GVariantType 43 * 44 * #GVariant is a variant datatype; it stores a value along with 45 * information about the type of that value. The range of possible 46 * values is determined by the type. The type system used by #GVariant 47 * is #GVariantType. 48 * 49 * #GVariant instances always have a type and a value (which are given 50 * at construction time). The type and value of a #GVariant instance 51 * can never change other than by the #GVariant itself being 52 * destroyed. A #GVariant can not contain a pointer. 53 * 54 * #GVariant is reference counted using g_variant_ref() and 55 * g_variant_unref(). #GVariant also has floating reference counts -- 56 * see g_variant_ref_sink(). 57 * 58 * #GVariant is completely threadsafe. A #GVariant instance can be 59 * concurrently accessed in any way from any number of threads without 60 * problems. 61 * 62 * #GVariant is heavily optimised for dealing with data in serialised 63 * form. It works particularly well with data located in memory-mapped 64 * files. It can perform nearly all deserialisation operations in a 65 * small constant time, usually touching only a single memory page. 66 * Serialised #GVariant data can also be sent over the network. 67 * 68 * #GVariant is largely compatible with D-Bus. Almost all types of 69 * #GVariant instances can be sent over D-Bus. See #GVariantType for 70 * exceptions. 71 * 72 * For convenience to C programmers, #GVariant features powerful 73 * varargs-based value construction and destruction. This feature is 74 * designed to be embedded in other libraries. 75 * 76 * There is a Python-inspired text language for describing #GVariant 77 * values. #GVariant includes a printer for this language and a parser 78 * with type inferencing. 79 * 80 * <refsect2> 81 * <title>Memory Use</title> 82 * <para> 83 * #GVariant tries to be quite efficient with respect to memory use. 84 * This section gives a rough idea of how much memory is used by the 85 * current implementation. The information here is subject to change 86 * in the future. 87 * </para> 88 * <para> 89 * The memory allocated by #GVariant can be grouped into 4 broad 90 * purposes: memory for serialised data, memory for the type 91 * information cache, buffer management memory and memory for the 92 * #GVariant structure itself. 93 * </para> 94 * <refsect3> 95 * <title>Serialised Data Memory</title> 96 * <para> 97 * This is the memory that is used for storing GVariant data in 98 * serialised form. This is what would be sent over the network or 99 * what would end up on disk. 100 * </para> 101 * <para> 102 * The amount of memory required to store a boolean is 1 byte. 16, 103 * 32 and 64 bit integers and double precision floating point numbers 104 * use their "natural" size. Strings (including object path and 105 * signature strings) are stored with a nul terminator, and as such 106 * use the length of the string plus 1 byte. 107 * </para> 108 * <para> 109 * Maybe types use no space at all to represent the null value and 110 * use the same amount of space (sometimes plus one byte) as the 111 * equivalent non-maybe-typed value to represent the non-null case. 112 * </para> 113 * <para> 114 * Arrays use the amount of space required to store each of their 115 * members, concatenated. Additionally, if the items stored in an 116 * array are not of a fixed-size (ie: strings, other arrays, etc) 117 * then an additional framing offset is stored for each item. The 118 * size of this offset is either 1, 2 or 4 bytes depending on the 119 * overall size of the container. Additionally, extra padding bytes 120 * are added as required for alignment of child values. 121 * </para> 122 * <para> 123 * Tuples (including dictionary entries) use the amount of space 124 * required to store each of their members, concatenated, plus one 125 * framing offset (as per arrays) for each non-fixed-sized item in 126 * the tuple, except for the last one. Additionally, extra padding 127 * bytes are added as required for alignment of child values. 128 * </para> 129 * <para> 130 * Variants use the same amount of space as the item inside of the 131 * variant, plus 1 byte, plus the length of the type string for the 132 * item inside the variant. 133 * </para> 134 * <para> 135 * As an example, consider a dictionary mapping strings to variants. 136 * In the case that the dictionary is empty, 0 bytes are required for 137 * the serialisation. 138 * </para> 139 * <para> 140 * If we add an item "width" that maps to the int32 value of 500 then 141 * we will use 4 byte to store the int32 (so 6 for the variant 142 * containing it) and 6 bytes for the string. The variant must be 143 * aligned to 8 after the 6 bytes of the string, so that's 2 extra 144 * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used 145 * for the dictionary entry. An additional 1 byte is added to the 146 * array as a framing offset making a total of 15 bytes. 147 * </para> 148 * <para> 149 * If we add another entry, "title" that maps to a nullable string 150 * that happens to have a value of null, then we use 0 bytes for the 151 * null value (and 3 bytes for the variant to contain it along with 152 * its type string) plus 6 bytes for the string. Again, we need 2 153 * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. 154 * </para> 155 * <para> 156 * We now require extra padding between the two items in the array. 157 * After the 14 bytes of the first item, that's 2 bytes required. We 158 * now require 2 framing offsets for an extra two bytes. 14 + 2 + 11 159 * + 2 = 29 bytes to encode the entire two-item dictionary. 160 * </para> 161 * </refsect3> 162 * <refsect3> 163 * <title>Type Information Cache</title> 164 * <para> 165 * For each GVariant type that currently exists in the program a type 166 * information structure is kept in the type information cache. The 167 * type information structure is required for rapid deserialisation. 168 * </para> 169 * <para> 170 * Continuing with the above example, if a #GVariant exists with the 171 * type "a{sv}" then a type information struct will exist for 172 * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type 173 * will share the same type information. Additionally, all 174 * single-digit types are stored in read-only static memory and do 175 * not contribute to the writable memory footprint of a program using 176 * #GVariant. 177 * </para> 178 * <para> 179 * Aside from the type information structures stored in read-only 180 * memory, there are two forms of type information. One is used for 181 * container types where there is a single element type: arrays and 182 * maybe types. The other is used for container types where there 183 * are multiple element types: tuples and dictionary entries. 184 * </para> 185 * <para> 186 * Array type info structures are 6 * sizeof (void *), plus the 187 * memory required to store the type string itself. This means that 188 * on 32bit systems, the cache entry for "a{sv}" would require 30 189 * bytes of memory (plus malloc overhead). 190 * </para> 191 * <para> 192 * Tuple type info structures are 6 * sizeof (void *), plus 4 * 193 * sizeof (void *) for each item in the tuple, plus the memory 194 * required to store the type string itself. A 2-item tuple, for 195 * example, would have a type information structure that consumed 196 * writable memory in the size of 14 * sizeof (void *) (plus type 197 * string) This means that on 32bit systems, the cache entry for 198 * "{sv}" would require 61 bytes of memory (plus malloc overhead). 199 * </para> 200 * <para> 201 * This means that in total, for our "a{sv}" example, 91 bytes of 202 * type information would be allocated. 203 * </para> 204 * <para> 205 * The type information cache, additionally, uses a #GHashTable to 206 * store and lookup the cached items and stores a pointer to this 207 * hash table in static storage. The hash table is freed when there 208 * are zero items in the type cache. 209 * </para> 210 * <para> 211 * Although these sizes may seem large it is important to remember 212 * that a program will probably only have a very small number of 213 * different types of values in it and that only one type information 214 * structure is required for many different values of the same type. 215 * </para> 216 * </refsect3> 217 * <refsect3> 218 * <title>Buffer Management Memory</title> 219 * <para> 220 * #GVariant uses an internal buffer management structure to deal 221 * with the various different possible sources of serialised data 222 * that it uses. The buffer is responsible for ensuring that the 223 * correct call is made when the data is no longer in use by 224 * #GVariant. This may involve a g_free() or a g_slice_free() or 225 * even g_mapped_file_unref(). 226 * </para> 227 * <para> 228 * One buffer management structure is used for each chunk of 229 * serialised data. The size of the buffer management structure is 4 230 * * (void *). On 32bit systems, that's 16 bytes. 231 * </para> 232 * </refsect3> 233 * <refsect3> 234 * <title>GVariant structure</title> 235 * <para> 236 * The size of a #GVariant structure is 6 * (void *). On 32 bit 237 * systems, that's 24 bytes. 238 * </para> 239 * <para> 240 * #GVariant structures only exist if they are explicitly created 241 * with API calls. For example, if a #GVariant is constructed out of 242 * serialised data for the example given above (with the dictionary) 243 * then although there are 9 individual values that comprise the 244 * entire dictionary (two keys, two values, two variants containing 245 * the values, two dictionary entries, plus the dictionary itself), 246 * only 1 #GVariant instance exists -- the one refering to the 247 * dictionary. 248 * </para> 249 * <para> 250 * If calls are made to start accessing the other values then 251 * #GVariant instances will exist for those values only for as long 252 * as they are in use (ie: until you call g_variant_unref()). The 253 * type information is shared. The serialised data and the buffer 254 * management structure for that serialised data is shared by the 255 * child. 256 * </para> 257 * </refsect3> 258 * <refsect3> 259 * <title>Summary</title> 260 * <para> 261 * To put the entire example together, for our dictionary mapping 262 * strings to variants (with two entries, as given above), we are 263 * using 91 bytes of memory for type information, 29 byes of memory 264 * for the serialised data, 16 bytes for buffer management and 24 265 * bytes for the #GVariant instance, or a total of 160 bytes, plus 266 * malloc overhead. If we were to use g_variant_get_child_value() to 267 * access the two dictionary entries, we would use an additional 48 268 * bytes. If we were to have other dictionaries of the same type, we 269 * would use more memory for the serialised data and buffer 270 * management for those dictionaries, but the type information would 271 * be shared. 272 * </para> 273 * </refsect3> 274 * </refsect2> 275 */ 276 277 /* definition of GVariant structure is in gvariant-core.c */ 278 279 /* this is a g_return_val_if_fail() for making 280 * sure a (GVariant *) has the required type. 281 */ 282 #define TYPE_CHECK(value, TYPE, val) \ 283 if G_UNLIKELY (!g_variant_is_of_type (value, TYPE)) { \ 284 g_return_if_fail_warning (G_LOG_DOMAIN, G_STRFUNC, \ 285 "g_variant_is_of_type (" #value \ 286 ", " #TYPE ")"); \ 287 return val; \ 288 } 289 290 /* Numeric Type Constructor/Getters {{{1 */ 291 /* < private > 292 * g_variant_new_from_trusted: 293 * @type: the #GVariantType 294 * @data: the data to use 295 * @size: the size of @data 296 * @returns: a new floating #GVariant 297 * 298 * Constructs a new trusted #GVariant instance from the provided data. 299 * This is used to implement g_variant_new_* for all the basic types. 300 */ 301 static GVariant * 302 g_variant_new_from_trusted (const GVariantType *type, 303 gconstpointer data, 304 gsize size) 305 { 306 GVariant *value; 307 GBuffer *buffer; 308 309 buffer = g_buffer_new_from_data (data, size); 310 value = g_variant_new_from_buffer (type, buffer, TRUE); 311 g_buffer_unref (buffer); 312 313 return value; 314 } 315 316 /** 317 * g_variant_new_boolean: 318 * @value: a #gboolean value 319 * @returns: (transfer none): a floating reference to a new boolean #GVariant instance 320 * 321 * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. 322 * 323 * Since: 2.24 324 **/ 325 GVariant * 326 g_variant_new_boolean (gboolean value) 327 { 328 guchar v = value; 329 330 return g_variant_new_from_trusted (G_VARIANT_TYPE_BOOLEAN, &v, 1); 331 } 332 333 /** 334 * g_variant_get_boolean: 335 * @value: a boolean #GVariant instance 336 * @returns: %TRUE or %FALSE 337 * 338 * Returns the boolean value of @value. 339 * 340 * It is an error to call this function with a @value of any type 341 * other than %G_VARIANT_TYPE_BOOLEAN. 342 * 343 * Since: 2.24 344 **/ 345 gboolean 346 g_variant_get_boolean (GVariant *value) 347 { 348 const guchar *data; 349 350 TYPE_CHECK (value, G_VARIANT_TYPE_BOOLEAN, FALSE); 351 352 data = g_variant_get_data (value); 353 354 return data != NULL ? *data != 0 : FALSE; 355 } 356 357 /* the constructors and accessors for byte, int{16,32,64}, handles and 358 * doubles all look pretty much exactly the same, so we reduce 359 * copy/pasting here. 360 */ 361 #define NUMERIC_TYPE(TYPE, type, ctype) \ 362 GVariant *g_variant_new_##type (ctype value) { \ 363 return g_variant_new_from_trusted (G_VARIANT_TYPE_##TYPE, \ 364 &value, sizeof value); \ 365 } \ 366 ctype g_variant_get_##type (GVariant *value) { \ 367 const ctype *data; \ 368 TYPE_CHECK (value, G_VARIANT_TYPE_ ## TYPE, 0); \ 369 data = g_variant_get_data (value); \ 370 return data != NULL ? *data : 0; \ 371 } 372 373 374 /** 375 * g_variant_new_byte: 376 * @value: a #guint8 value 377 * @returns: (transfer none): a floating reference to a new byte #GVariant instance 378 * 379 * Creates a new byte #GVariant instance. 380 * 381 * Since: 2.24 382 **/ 383 /** 384 * g_variant_get_byte: 385 * @value: a byte #GVariant instance 386 * @returns: a #guchar 387 * 388 * Returns the byte value of @value. 389 * 390 * It is an error to call this function with a @value of any type 391 * other than %G_VARIANT_TYPE_BYTE. 392 * 393 * Since: 2.24 394 **/ 395 NUMERIC_TYPE (BYTE, byte, guchar) 396 397 /** 398 * g_variant_new_int16: 399 * @value: a #gint16 value 400 * @returns: (transfer none): a floating reference to a new int16 #GVariant instance 401 * 402 * Creates a new int16 #GVariant instance. 403 * 404 * Since: 2.24 405 **/ 406 /** 407 * g_variant_get_int16: 408 * @value: a int16 #GVariant instance 409 * @returns: a #gint16 410 * 411 * Returns the 16-bit signed integer value of @value. 412 * 413 * It is an error to call this function with a @value of any type 414 * other than %G_VARIANT_TYPE_INT16. 415 * 416 * Since: 2.24 417 **/ 418 NUMERIC_TYPE (INT16, int16, gint16) 419 420 /** 421 * g_variant_new_uint16: 422 * @value: a #guint16 value 423 * @returns: (transfer none): a floating reference to a new uint16 #GVariant instance 424 * 425 * Creates a new uint16 #GVariant instance. 426 * 427 * Since: 2.24 428 **/ 429 /** 430 * g_variant_get_uint16: 431 * @value: a uint16 #GVariant instance 432 * @returns: a #guint16 433 * 434 * Returns the 16-bit unsigned integer value of @value. 435 * 436 * It is an error to call this function with a @value of any type 437 * other than %G_VARIANT_TYPE_UINT16. 438 * 439 * Since: 2.24 440 **/ 441 NUMERIC_TYPE (UINT16, uint16, guint16) 442 443 /** 444 * g_variant_new_int32: 445 * @value: a #gint32 value 446 * @returns: (transfer none): a floating reference to a new int32 #GVariant instance 447 * 448 * Creates a new int32 #GVariant instance. 449 * 450 * Since: 2.24 451 **/ 452 /** 453 * g_variant_get_int32: 454 * @value: a int32 #GVariant instance 455 * @returns: a #gint32 456 * 457 * Returns the 32-bit signed integer value of @value. 458 * 459 * It is an error to call this function with a @value of any type 460 * other than %G_VARIANT_TYPE_INT32. 461 * 462 * Since: 2.24 463 **/ 464 NUMERIC_TYPE (INT32, int32, gint32) 465 466 /** 467 * g_variant_new_uint32: 468 * @value: a #guint32 value 469 * @returns: (transfer none): a floating reference to a new uint32 #GVariant instance 470 * 471 * Creates a new uint32 #GVariant instance. 472 * 473 * Since: 2.24 474 **/ 475 /** 476 * g_variant_get_uint32: 477 * @value: a uint32 #GVariant instance 478 * @returns: a #guint32 479 * 480 * Returns the 32-bit unsigned integer value of @value. 481 * 482 * It is an error to call this function with a @value of any type 483 * other than %G_VARIANT_TYPE_UINT32. 484 * 485 * Since: 2.24 486 **/ 487 NUMERIC_TYPE (UINT32, uint32, guint32) 488 489 /** 490 * g_variant_new_int64: 491 * @value: a #gint64 value 492 * @returns: (transfer none): a floating reference to a new int64 #GVariant instance 493 * 494 * Creates a new int64 #GVariant instance. 495 * 496 * Since: 2.24 497 **/ 498 /** 499 * g_variant_get_int64: 500 * @value: a int64 #GVariant instance 501 * @returns: a #gint64 502 * 503 * Returns the 64-bit signed integer value of @value. 504 * 505 * It is an error to call this function with a @value of any type 506 * other than %G_VARIANT_TYPE_INT64. 507 * 508 * Since: 2.24 509 **/ 510 NUMERIC_TYPE (INT64, int64, gint64) 511 512 /** 513 * g_variant_new_uint64: 514 * @value: a #guint64 value 515 * @returns: (transfer none): a floating reference to a new uint64 #GVariant instance 516 * 517 * Creates a new uint64 #GVariant instance. 518 * 519 * Since: 2.24 520 **/ 521 /** 522 * g_variant_get_uint64: 523 * @value: a uint64 #GVariant instance 524 * @returns: a #guint64 525 * 526 * Returns the 64-bit unsigned integer value of @value. 527 * 528 * It is an error to call this function with a @value of any type 529 * other than %G_VARIANT_TYPE_UINT64. 530 * 531 * Since: 2.24 532 **/ 533 NUMERIC_TYPE (UINT64, uint64, guint64) 534 535 /** 536 * g_variant_new_handle: 537 * @value: a #gint32 value 538 * @returns: (transfer none): a floating reference to a new handle #GVariant instance 539 * 540 * Creates a new handle #GVariant instance. 541 * 542 * By convention, handles are indexes into an array of file descriptors 543 * that are sent alongside a D-Bus message. If you're not interacting 544 * with D-Bus, you probably don't need them. 545 * 546 * Since: 2.24 547 **/ 548 /** 549 * g_variant_get_handle: 550 * @value: a handle #GVariant instance 551 * @returns: a #gint32 552 * 553 * Returns the 32-bit signed integer value of @value. 554 * 555 * It is an error to call this function with a @value of any type other 556 * than %G_VARIANT_TYPE_HANDLE. 557 * 558 * By convention, handles are indexes into an array of file descriptors 559 * that are sent alongside a D-Bus message. If you're not interacting 560 * with D-Bus, you probably don't need them. 561 * 562 * Since: 2.24 563 **/ 564 NUMERIC_TYPE (HANDLE, handle, gint32) 565 566 /** 567 * g_variant_new_double: 568 * @value: a #gdouble floating point value 569 * @returns: (transfer none): a floating reference to a new double #GVariant instance 570 * 571 * Creates a new double #GVariant instance. 572 * 573 * Since: 2.24 574 **/ 575 /** 576 * g_variant_get_double: 577 * @value: a double #GVariant instance 578 * @returns: a #gdouble 579 * 580 * Returns the double precision floating point value of @value. 581 * 582 * It is an error to call this function with a @value of any type 583 * other than %G_VARIANT_TYPE_DOUBLE. 584 * 585 * Since: 2.24 586 **/ 587 NUMERIC_TYPE (DOUBLE, double, gdouble) 588 589 /* Container type Constructor / Deconstructors {{{1 */ 590 /** 591 * g_variant_new_maybe: 592 * @child_type: (allow-none): the #GVariantType of the child, or %NULL 593 * @child: (allow-none): the child value, or %NULL 594 * @returns: (transfer none): a floating reference to a new #GVariant maybe instance 595 * 596 * Depending on if @child is %NULL, either wraps @child inside of a 597 * maybe container or creates a Nothing instance for the given @type. 598 * 599 * At least one of @child_type and @child must be non-%NULL. 600 * If @child_type is non-%NULL then it must be a definite type. 601 * If they are both non-%NULL then @child_type must be the type 602 * of @child. 603 * 604 * If @child is a floating reference (see g_variant_ref_sink()), the new 605 * instance takes ownership of @child. 606 * 607 * Since: 2.24 608 **/ 609 GVariant * 610 g_variant_new_maybe (const GVariantType *child_type, 611 GVariant *child) 612 { 613 GVariantType *maybe_type; 614 GVariant *value; 615 616 g_return_val_if_fail (child_type == NULL || g_variant_type_is_definite 617 (child_type), 0); 618 g_return_val_if_fail (child_type != NULL || child != NULL, NULL); 619 g_return_val_if_fail (child_type == NULL || child == NULL || 620 g_variant_is_of_type (child, child_type), 621 NULL); 622 623 if (child_type == NULL) 624 child_type = g_variant_get_type (child); 625 626 maybe_type = g_variant_type_new_maybe (child_type); 627 628 if (child != NULL) 629 { 630 GVariant **children; 631 gboolean trusted; 632 633 children = g_new (GVariant *, 1); 634 children[0] = g_variant_ref_sink (child); 635 trusted = g_variant_is_trusted (children[0]); 636 637 value = g_variant_new_from_children (maybe_type, children, 1, trusted); 638 } 639 else 640 value = g_variant_new_from_children (maybe_type, NULL, 0, TRUE); 641 642 g_variant_type_free (maybe_type); 643 644 return value; 645 } 646 647 /** 648 * g_variant_get_maybe: 649 * @value: a maybe-typed value 650 * @returns: (allow-none) (transfer full): the contents of @value, or %NULL 651 * 652 * Given a maybe-typed #GVariant instance, extract its value. If the 653 * value is Nothing, then this function returns %NULL. 654 * 655 * Since: 2.24 656 **/ 657 GVariant * 658 g_variant_get_maybe (GVariant *value) 659 { 660 TYPE_CHECK (value, G_VARIANT_TYPE_MAYBE, NULL); 661 662 if (g_variant_n_children (value)) 663 return g_variant_get_child_value (value, 0); 664 665 return NULL; 666 } 667 668 /** 669 * g_variant_new_variant: 670 * @value: a #GVariant instance 671 * @returns: (transfer none): a floating reference to a new variant #GVariant instance 672 * 673 * Boxes @value. The result is a #GVariant instance representing a 674 * variant containing the original value. 675 * 676 * If @child is a floating reference (see g_variant_ref_sink()), the new 677 * instance takes ownership of @child. 678 * 679 * Since: 2.24 680 **/ 681 GVariant * 682 g_variant_new_variant (GVariant *value) 683 { 684 g_return_val_if_fail (value != NULL, NULL); 685 686 g_variant_ref_sink (value); 687 688 return g_variant_new_from_children (G_VARIANT_TYPE_VARIANT, 689 g_memdup (&value, sizeof value), 690 1, g_variant_is_trusted (value)); 691 } 692 693 /** 694 * g_variant_get_variant: 695 * @value: a variant #GVariant instance 696 * @returns: (transfer full): the item contained in the variant 697 * 698 * Unboxes @value. The result is the #GVariant instance that was 699 * contained in @value. 700 * 701 * Since: 2.24 702 **/ 703 GVariant * 704 g_variant_get_variant (GVariant *value) 705 { 706 TYPE_CHECK (value, G_VARIANT_TYPE_VARIANT, NULL); 707 708 return g_variant_get_child_value (value, 0); 709 } 710 711 /** 712 * g_variant_new_array: 713 * @child_type: (allow-none): the element type of the new array 714 * @children: (allow-none) (array length=n_children): an array of 715 * #GVariant pointers, the children 716 * @n_children: the length of @children 717 * @returns: (transfer none): a floating reference to a new #GVariant array 718 * 719 * Creates a new #GVariant array from @children. 720 * 721 * @child_type must be non-%NULL if @n_children is zero. Otherwise, the 722 * child type is determined by inspecting the first element of the 723 * @children array. If @child_type is non-%NULL then it must be a 724 * definite type. 725 * 726 * The items of the array are taken from the @children array. No entry 727 * in the @children array may be %NULL. 728 * 729 * All items in the array must have the same type, which must be the 730 * same as @child_type, if given. 731 * 732 * If the @children are floating references (see g_variant_ref_sink()), the 733 * new instance takes ownership of them as if via g_variant_ref_sink(). 734 * 735 * Since: 2.24 736 **/ 737 GVariant * 738 g_variant_new_array (const GVariantType *child_type, 739 GVariant * const *children, 740 gsize n_children) 741 { 742 GVariantType *array_type; 743 GVariant **my_children; 744 gboolean trusted; 745 GVariant *value; 746 gsize i; 747 748 g_return_val_if_fail (n_children > 0 || child_type != NULL, NULL); 749 g_return_val_if_fail (n_children == 0 || children != NULL, NULL); 750 g_return_val_if_fail (child_type == NULL || 751 g_variant_type_is_definite (child_type), NULL); 752 753 my_children = g_new (GVariant *, n_children); 754 trusted = TRUE; 755 756 if (child_type == NULL) 757 child_type = g_variant_get_type (children[0]); 758 array_type = g_variant_type_new_array (child_type); 759 760 for (i = 0; i < n_children; i++) 761 { 762 TYPE_CHECK (children[i], child_type, NULL); 763 my_children[i] = g_variant_ref_sink (children[i]); 764 trusted &= g_variant_is_trusted (children[i]); 765 } 766 767 value = g_variant_new_from_children (array_type, my_children, 768 n_children, trusted); 769 g_variant_type_free (array_type); 770 771 return value; 772 } 773 774 /*< private > 775 * g_variant_make_tuple_type: 776 * @children: (array length=n_children): an array of GVariant * 777 * @n_children: the length of @children 778 * 779 * Return the type of a tuple containing @children as its items. 780 **/ 781 static GVariantType * 782 g_variant_make_tuple_type (GVariant * const *children, 783 gsize n_children) 784 { 785 const GVariantType **types; 786 GVariantType *type; 787 gsize i; 788 789 types = g_new (const GVariantType *, n_children); 790 791 for (i = 0; i < n_children; i++) 792 types[i] = g_variant_get_type (children[i]); 793 794 type = g_variant_type_new_tuple (types, n_children); 795 g_free (types); 796 797 return type; 798 } 799 800 /** 801 * g_variant_new_tuple: 802 * @children: (array length=n_children): the items to make the tuple out of 803 * @n_children: the length of @children 804 * @returns: (transfer none): a floating reference to a new #GVariant tuple 805 * 806 * Creates a new tuple #GVariant out of the items in @children. The 807 * type is determined from the types of @children. No entry in the 808 * @children array may be %NULL. 809 * 810 * If @n_children is 0 then the unit tuple is constructed. 811 * 812 * If the @children are floating references (see g_variant_ref_sink()), the 813 * new instance takes ownership of them as if via g_variant_ref_sink(). 814 * 815 * Since: 2.24 816 **/ 817 GVariant * 818 g_variant_new_tuple (GVariant * const *children, 819 gsize n_children) 820 { 821 GVariantType *tuple_type; 822 GVariant **my_children; 823 gboolean trusted; 824 GVariant *value; 825 gsize i; 826 827 g_return_val_if_fail (n_children == 0 || children != NULL, NULL); 828 829 my_children = g_new (GVariant *, n_children); 830 trusted = TRUE; 831 832 for (i = 0; i < n_children; i++) 833 { 834 my_children[i] = g_variant_ref_sink (children[i]); 835 trusted &= g_variant_is_trusted (children[i]); 836 } 837 838 tuple_type = g_variant_make_tuple_type (children, n_children); 839 value = g_variant_new_from_children (tuple_type, my_children, 840 n_children, trusted); 841 g_variant_type_free (tuple_type); 842 843 return value; 844 } 845 846 /*< private > 847 * g_variant_make_dict_entry_type: 848 * @key: a #GVariant, the key 849 * @val: a #GVariant, the value 850 * 851 * Return the type of a dictionary entry containing @key and @val as its 852 * children. 853 **/ 854 static GVariantType * 855 g_variant_make_dict_entry_type (GVariant *key, 856 GVariant *val) 857 { 858 return g_variant_type_new_dict_entry (g_variant_get_type (key), 859 g_variant_get_type (val)); 860 } 861 862 /** 863 * g_variant_new_dict_entry: (constructor) 864 * @key: a basic #GVariant, the key 865 * @value: a #GVariant, the value 866 * @returns: (transfer none): a floating reference to a new dictionary entry #GVariant 867 * 868 * Creates a new dictionary entry #GVariant. @key and @value must be 869 * non-%NULL. @key must be a value of a basic type (ie: not a container). 870 * 871 * If the @key or @value are floating references (see g_variant_ref_sink()), 872 * the new instance takes ownership of them as if via g_variant_ref_sink(). 873 * 874 * Since: 2.24 875 **/ 876 GVariant * 877 g_variant_new_dict_entry (GVariant *key, 878 GVariant *value) 879 { 880 GVariantType *dict_type; 881 GVariant **children; 882 gboolean trusted; 883 884 g_return_val_if_fail (key != NULL && value != NULL, NULL); 885 g_return_val_if_fail (!g_variant_is_container (key), NULL); 886 887 children = g_new (GVariant *, 2); 888 children[0] = g_variant_ref_sink (key); 889 children[1] = g_variant_ref_sink (value); 890 trusted = g_variant_is_trusted (key) && g_variant_is_trusted (value); 891 892 dict_type = g_variant_make_dict_entry_type (key, value); 893 value = g_variant_new_from_children (dict_type, children, 2, trusted); 894 g_variant_type_free (dict_type); 895 896 return value; 897 } 898 899 /** 900 * g_variant_lookup: (skip) 901 * @dictionary: a dictionary #GVariant 902 * @key: the key to lookup in the dictionary 903 * @format_string: a GVariant format string 904 * @...: the arguments to unpack the value into 905 * 906 * Looks up a value in a dictionary #GVariant. 907 * 908 * This function is a wrapper around g_variant_lookup_value() and 909 * g_variant_get(). In the case that %NULL would have been returned, 910 * this function returns %FALSE. Otherwise, it unpacks the returned 911 * value and returns %TRUE. 912 * 913 * See g_variant_get() for information about @format_string. 914 * 915 * Returns: %TRUE if a value was unpacked 916 * 917 * Since: 2.28 918 */ 919 gboolean 920 g_variant_lookup (GVariant *dictionary, 921 const gchar *key, 922 const gchar *format_string, 923 ...) 924 { 925 GVariantType *type; 926 GVariant *value; 927 928 /* flatten */ 929 g_variant_get_data (dictionary); 930 931 type = g_variant_format_string_scan_type (format_string, NULL, NULL); 932 value = g_variant_lookup_value (dictionary, key, type); 933 g_variant_type_free (type); 934 935 if (value) 936 { 937 va_list ap; 938 939 va_start (ap, format_string); 940 g_variant_get_va (value, format_string, NULL, &ap); 941 g_variant_unref (value); 942 va_end (ap); 943 944 return TRUE; 945 } 946 947 else 948 return FALSE; 949 } 950 951 /** 952 * g_variant_lookup_value: 953 * @dictionary: a dictionary #GVariant 954 * @key: the key to lookup in the dictionary 955 * @expected_type: (allow-none): a #GVariantType, or %NULL 956 * 957 * Looks up a value in a dictionary #GVariant. 958 * 959 * This function works with dictionaries of the type 960 * <literal>a{s*}</literal> (and equally well with type 961 * <literal>a{o*}</literal>, but we only further discuss the string case 962 * for sake of clarity). 963 * 964 * In the event that @dictionary has the type <literal>a{sv}</literal>, 965 * the @expected_type string specifies what type of value is expected to 966 * be inside of the variant. If the value inside the variant has a 967 * different type then %NULL is returned. In the event that @dictionary 968 * has a value type other than <literal>v</literal> then @expected_type 969 * must directly match the key type and it is used to unpack the value 970 * directly or an error occurs. 971 * 972 * In either case, if @key is not found in @dictionary, %NULL is 973 * returned. 974 * 975 * If the key is found and the value has the correct type, it is 976 * returned. If @expected_type was specified then any non-%NULL return 977 * value will have this type. 978 * 979 * Returns: (transfer full): the value of the dictionary key, or %NULL 980 * 981 * Since: 2.28 982 */ 983 GVariant * 984 g_variant_lookup_value (GVariant *dictionary, 985 const gchar *key, 986 const GVariantType *expected_type) 987 { 988 GVariantIter iter; 989 GVariant *entry; 990 GVariant *value; 991 992 g_return_val_if_fail (g_variant_is_of_type (dictionary, 993 G_VARIANT_TYPE ("a{s*}")) || 994 g_variant_is_of_type (dictionary, 995 G_VARIANT_TYPE ("a{o*}")), 996 NULL); 997 998 g_variant_iter_init (&iter, dictionary); 999 1000 while ((entry = g_variant_iter_next_value (&iter))) 1001 { 1002 GVariant *entry_key; 1003 gboolean matches; 1004 1005 entry_key = g_variant_get_child_value (entry, 0); 1006 matches = strcmp (g_variant_get_string (entry_key, NULL), key) == 0; 1007 g_variant_unref (entry_key); 1008 1009 if (matches) 1010 break; 1011 1012 g_variant_unref (entry); 1013 } 1014 1015 if (entry == NULL) 1016 return NULL; 1017 1018 value = g_variant_get_child_value (entry, 1); 1019 g_variant_unref (entry); 1020 1021 if (g_variant_is_of_type (value, G_VARIANT_TYPE_VARIANT)) 1022 { 1023 GVariant *tmp; 1024 1025 tmp = g_variant_get_variant (value); 1026 g_variant_unref (value); 1027 1028 if (expected_type && !g_variant_is_of_type (tmp, expected_type)) 1029 { 1030 g_variant_unref (tmp); 1031 tmp = NULL; 1032 } 1033 1034 value = tmp; 1035 } 1036 1037 g_return_val_if_fail (expected_type == NULL || value == NULL || 1038 g_variant_is_of_type (value, expected_type), NULL); 1039 1040 return value; 1041 } 1042 1043 /** 1044 * g_variant_get_fixed_array: 1045 * @value: a #GVariant array with fixed-sized elements 1046 * @n_elements: (out): a pointer to the location to store the number of items 1047 * @element_size: the size of each element 1048 * @returns: (array length=n_elements): a pointer to the fixed array 1049 * 1050 * Provides access to the serialised data for an array of fixed-sized 1051 * items. 1052 * 1053 * @value must be an array with fixed-sized elements. Numeric types are 1054 * fixed-size as are tuples containing only other fixed-sized types. 1055 * 1056 * @element_size must be the size of a single element in the array. For 1057 * example, if calling this function for an array of 32 bit integers, 1058 * you might say <code>sizeof (gint32)</code>. This value isn't used 1059 * except for the purpose of a double-check that the form of the 1060 * seralised data matches the caller's expectation. 1061 * 1062 * @n_elements, which must be non-%NULL is set equal to the number of 1063 * items in the array. 1064 * 1065 * Since: 2.24 1066 **/ 1067 gconstpointer 1068 g_variant_get_fixed_array (GVariant *value, 1069 gsize *n_elements, 1070 gsize element_size) 1071 { 1072 GVariantTypeInfo *array_info; 1073 gsize array_element_size; 1074 gconstpointer data; 1075 gsize size; 1076 1077 TYPE_CHECK (value, G_VARIANT_TYPE_ARRAY, NULL); 1078 1079 g_return_val_if_fail (n_elements != NULL, NULL); 1080 g_return_val_if_fail (element_size > 0, NULL); 1081 1082 array_info = g_variant_get_type_info (value); 1083 g_variant_type_info_query_element (array_info, NULL, &array_element_size); 1084 1085 g_return_val_if_fail (array_element_size, NULL); 1086 1087 if G_UNLIKELY (array_element_size != element_size) 1088 { 1089 if (array_element_size) 1090 g_critical ("g_variant_get_fixed_array: assertion " 1091 "`g_variant_array_has_fixed_size (value, element_size)' " 1092 "failed: array size %"G_GSIZE_FORMAT" does not match " 1093 "given element_size %"G_GSIZE_FORMAT".", 1094 array_element_size, element_size); 1095 else 1096 g_critical ("g_variant_get_fixed_array: assertion " 1097 "`g_variant_array_has_fixed_size (value, element_size)' " 1098 "failed: array does not have fixed size."); 1099 } 1100 1101 data = g_variant_get_data (value); 1102 size = g_variant_get_size (value); 1103 1104 if (size % element_size) 1105 *n_elements = 0; 1106 else 1107 *n_elements = size / element_size; 1108 1109 if (*n_elements) 1110 return data; 1111 1112 return NULL; 1113 } 1114 1115 /* String type constructor/getters/validation {{{1 */ 1116 /** 1117 * g_variant_new_string: 1118 * @string: a normal utf8 nul-terminated string 1119 * @returns: (transfer none): a floating reference to a new string #GVariant instance 1120 * 1121 * Creates a string #GVariant with the contents of @string. 1122 * 1123 * @string must be valid utf8. 1124 * 1125 * Since: 2.24 1126 **/ 1127 GVariant * 1128 g_variant_new_string (const gchar *string) 1129 { 1130 g_return_val_if_fail (string != NULL, NULL); 1131 g_return_val_if_fail (g_utf8_validate (string, -1, NULL), NULL); 1132 1133 return g_variant_new_from_trusted (G_VARIANT_TYPE_STRING, 1134 string, strlen (string) + 1); 1135 } 1136 1137 /** 1138 * g_variant_new_object_path: 1139 * @object_path: a normal C nul-terminated string 1140 * @returns: (transfer none): a floating reference to a new object path #GVariant instance 1141 * 1142 * Creates a D-Bus object path #GVariant with the contents of @string. 1143 * @string must be a valid D-Bus object path. Use 1144 * g_variant_is_object_path() if you're not sure. 1145 * 1146 * Since: 2.24 1147 **/ 1148 GVariant * 1149 g_variant_new_object_path (const gchar *object_path) 1150 { 1151 g_return_val_if_fail (g_variant_is_object_path (object_path), NULL); 1152 1153 return g_variant_new_from_trusted (G_VARIANT_TYPE_OBJECT_PATH, 1154 object_path, strlen (object_path) + 1); 1155 } 1156 1157 /** 1158 * g_variant_is_object_path: 1159 * @string: a normal C nul-terminated string 1160 * @returns: %TRUE if @string is a D-Bus object path 1161 * 1162 * Determines if a given string is a valid D-Bus object path. You 1163 * should ensure that a string is a valid D-Bus object path before 1164 * passing it to g_variant_new_object_path(). 1165 * 1166 * A valid object path starts with '/' followed by zero or more 1167 * sequences of characters separated by '/' characters. Each sequence 1168 * must contain only the characters "[A-Z][a-z][0-9]_". No sequence 1169 * (including the one following the final '/' character) may be empty. 1170 * 1171 * Since: 2.24 1172 **/ 1173 gboolean 1174 g_variant_is_object_path (const gchar *string) 1175 { 1176 g_return_val_if_fail (string != NULL, FALSE); 1177 1178 return g_variant_serialiser_is_object_path (string, strlen (string) + 1); 1179 } 1180 1181 /** 1182 * g_variant_new_signature: 1183 * @signature: a normal C nul-terminated string 1184 * @returns: (transfer none): a floating reference to a new signature #GVariant instance 1185 * 1186 * Creates a D-Bus type signature #GVariant with the contents of 1187 * @string. @string must be a valid D-Bus type signature. Use 1188 * g_variant_is_signature() if you're not sure. 1189 * 1190 * Since: 2.24 1191 **/ 1192 GVariant * 1193 g_variant_new_signature (const gchar *signature) 1194 { 1195 g_return_val_if_fail (g_variant_is_signature (signature), NULL); 1196 1197 return g_variant_new_from_trusted (G_VARIANT_TYPE_SIGNATURE, 1198 signature, strlen (signature) + 1); 1199 } 1200 1201 /** 1202 * g_variant_is_signature: 1203 * @string: a normal C nul-terminated string 1204 * @returns: %TRUE if @string is a D-Bus type signature 1205 * 1206 * Determines if a given string is a valid D-Bus type signature. You 1207 * should ensure that a string is a valid D-Bus type signature before 1208 * passing it to g_variant_new_signature(). 1209 * 1210 * D-Bus type signatures consist of zero or more definite #GVariantType 1211 * strings in sequence. 1212 * 1213 * Since: 2.24 1214 **/ 1215 gboolean 1216 g_variant_is_signature (const gchar *string) 1217 { 1218 g_return_val_if_fail (string != NULL, FALSE); 1219 1220 return g_variant_serialiser_is_signature (string, strlen (string) + 1); 1221 } 1222 1223 /** 1224 * g_variant_get_string: 1225 * @value: a string #GVariant instance 1226 * @length: (allow-none) (default 0) (out): a pointer to a #gsize, 1227 * to store the length 1228 * @returns: (transfer none): the constant string, utf8 encoded 1229 * 1230 * Returns the string value of a #GVariant instance with a string 1231 * type. This includes the types %G_VARIANT_TYPE_STRING, 1232 * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. 1233 * 1234 * The string will always be utf8 encoded. 1235 * 1236 * If @length is non-%NULL then the length of the string (in bytes) is 1237 * returned there. For trusted values, this information is already 1238 * known. For untrusted values, a strlen() will be performed. 1239 * 1240 * It is an error to call this function with a @value of any type 1241 * other than those three. 1242 * 1243 * The return value remains valid as long as @value exists. 1244 * 1245 * Since: 2.24 1246 **/ 1247 const gchar * 1248 g_variant_get_string (GVariant *value, 1249 gsize *length) 1250 { 1251 gconstpointer data; 1252 gsize size; 1253 1254 g_return_val_if_fail (value != NULL, NULL); 1255 g_return_val_if_fail ( 1256 g_variant_is_of_type (value, G_VARIANT_TYPE_STRING) || 1257 g_variant_is_of_type (value, G_VARIANT_TYPE_OBJECT_PATH) || 1258 g_variant_is_of_type (value, G_VARIANT_TYPE_SIGNATURE), NULL); 1259 1260 data = g_variant_get_data (value); 1261 size = g_variant_get_size (value); 1262 1263 if (!g_variant_is_trusted (value)) 1264 { 1265 switch (g_variant_classify (value)) 1266 { 1267 case G_VARIANT_CLASS_STRING: 1268 if (g_variant_serialiser_is_string (data, size)) 1269 break; 1270 1271 data = ""; 1272 size = 1; 1273 break; 1274 1275 case G_VARIANT_CLASS_OBJECT_PATH: 1276 if (g_variant_serialiser_is_object_path (data, size)) 1277 break; 1278 1279 data = "/"; 1280 size = 2; 1281 break; 1282 1283 case G_VARIANT_CLASS_SIGNATURE: 1284 if (g_variant_serialiser_is_signature (data, size)) 1285 break; 1286 1287 data = ""; 1288 size = 1; 1289 break; 1290 1291 default: 1292 g_assert_not_reached (); 1293 } 1294 } 1295 1296 if (length) 1297 *length = size - 1; 1298 1299 return data; 1300 } 1301 1302 /** 1303 * g_variant_dup_string: 1304 * @value: a string #GVariant instance 1305 * @length: (out): a pointer to a #gsize, to store the length 1306 * @returns: (transfer full): a newly allocated string, utf8 encoded 1307 * 1308 * Similar to g_variant_get_string() except that instead of returning 1309 * a constant string, the string is duplicated. 1310 * 1311 * The string will always be utf8 encoded. 1312 * 1313 * The return value must be freed using g_free(). 1314 * 1315 * Since: 2.24 1316 **/ 1317 gchar * 1318 g_variant_dup_string (GVariant *value, 1319 gsize *length) 1320 { 1321 return g_strdup (g_variant_get_string (value, length)); 1322 } 1323 1324 /** 1325 * g_variant_new_strv: 1326 * @strv: (array length=length) (element-type utf8): an array of strings 1327 * @length: the length of @strv, or -1 1328 * @returns: (transfer none): a new floating #GVariant instance 1329 * 1330 * Constructs an array of strings #GVariant from the given array of 1331 * strings. 1332 * 1333 * If @length is -1 then @strv is %NULL-terminated. 1334 * 1335 * Since: 2.24 1336 **/ 1337 GVariant * 1338 g_variant_new_strv (const gchar * const *strv, 1339 gssize length) 1340 { 1341 GVariant **strings; 1342 gsize i; 1343 1344 g_return_val_if_fail (length == 0 || strv != NULL, NULL); 1345 1346 if (length < 0) 1347 length = g_strv_length ((gchar **) strv); 1348 1349 strings = g_new (GVariant *, length); 1350 for (i = 0; i < length; i++) 1351 strings[i] = g_variant_ref_sink (g_variant_new_string (strv[i])); 1352 1353 return g_variant_new_from_children (G_VARIANT_TYPE_STRING_ARRAY, 1354 strings, length, TRUE); 1355 } 1356 1357 /** 1358 * g_variant_get_strv: 1359 * @value: an array of strings #GVariant 1360 * @length: (out) (allow-none): the length of the result, or %NULL 1361 * @returns: (array length=length zero-terminated=1) (transfer container): an array of constant 1362 * strings 1363 * 1364 * Gets the contents of an array of strings #GVariant. This call 1365 * makes a shallow copy; the return result should be released with 1366 * g_free(), but the individual strings must not be modified. 1367 * 1368 * If @length is non-%NULL then the number of elements in the result 1369 * is stored there. In any case, the resulting array will be 1370 * %NULL-terminated. 1371 * 1372 * For an empty array, @length will be set to 0 and a pointer to a 1373 * %NULL pointer will be returned. 1374 * 1375 * Since: 2.24 1376 **/ 1377 const gchar ** 1378 g_variant_get_strv (GVariant *value, 1379 gsize *length) 1380 { 1381 const gchar **strv; 1382 gsize n; 1383 gsize i; 1384 1385 TYPE_CHECK (value, G_VARIANT_TYPE_STRING_ARRAY, NULL); 1386 1387 g_variant_get_data (value); 1388 n = g_variant_n_children (value); 1389 strv = g_new (const gchar *, n + 1); 1390 1391 for (i = 0; i < n; i++) 1392 { 1393 GVariant *string; 1394 1395 string = g_variant_get_child_value (value, i); 1396 strv[i] = g_variant_get_string (string, NULL); 1397 g_variant_unref (string); 1398 } 1399 strv[i] = NULL; 1400 1401 if (length) 1402 *length = n; 1403 1404 return strv; 1405 } 1406 1407 /** 1408 * g_variant_dup_strv: 1409 * @value: an array of strings #GVariant 1410 * @length: (out) (allow-none): the length of the result, or %NULL 1411 * @returns: (array length=length zero-terminated=1) (transfer full): an array of strings 1412 * 1413 * Gets the contents of an array of strings #GVariant. This call 1414 * makes a deep copy; the return result should be released with 1415 * g_strfreev(). 1416 * 1417 * If @length is non-%NULL then the number of elements in the result 1418 * is stored there. In any case, the resulting array will be 1419 * %NULL-terminated. 1420 * 1421 * For an empty array, @length will be set to 0 and a pointer to a 1422 * %NULL pointer will be returned. 1423 * 1424 * Since: 2.24 1425 **/ 1426 gchar ** 1427 g_variant_dup_strv (GVariant *value, 1428 gsize *length) 1429 { 1430 gchar **strv; 1431 gsize n; 1432 gsize i; 1433 1434 TYPE_CHECK (value, G_VARIANT_TYPE_STRING_ARRAY, NULL); 1435 1436 n = g_variant_n_children (value); 1437 strv = g_new (gchar *, n + 1); 1438 1439 for (i = 0; i < n; i++) 1440 { 1441 GVariant *string; 1442 1443 string = g_variant_get_child_value (value, i); 1444 strv[i] = g_variant_dup_string (string, NULL); 1445 g_variant_unref (string); 1446 } 1447 strv[i] = NULL; 1448 1449 if (length) 1450 *length = n; 1451 1452 return strv; 1453 } 1454 1455 /** 1456 * g_variant_new_bytestring: 1457 * @string: (array zero-terminated=1): a normal nul-terminated string in no particular encoding 1458 * @returns: (transfer none): a floating reference to a new bytestring #GVariant instance 1459 * 1460 * Creates an array-of-bytes #GVariant with the contents of @string. 1461 * This function is just like g_variant_new_string() except that the 1462 * string need not be valid utf8. 1463 * 1464 * The nul terminator character at the end of the string is stored in 1465 * the array. 1466 * 1467 * Since: 2.26 1468 **/ 1469 GVariant * 1470 g_variant_new_bytestring (const gchar *string) 1471 { 1472 g_return_val_if_fail (string != NULL, NULL); 1473 1474 return g_variant_new_from_trusted (G_VARIANT_TYPE_BYTESTRING, 1475 string, strlen (string) + 1); 1476 } 1477 1478 /** 1479 * g_variant_get_bytestring: 1480 * @value: an array-of-bytes #GVariant instance 1481 * @returns: (transfer none) (array zero-terminated=1): the constant string 1482 * 1483 * Returns the string value of a #GVariant instance with an 1484 * array-of-bytes type. The string has no particular encoding. 1485 * 1486 * If the array does not end with a nul terminator character, the empty 1487 * string is returned. For this reason, you can always trust that a 1488 * non-%NULL nul-terminated string will be returned by this function. 1489 * 1490 * If the array contains a nul terminator character somewhere other than 1491 * the last byte then the returned string is the string, up to the first 1492 * such nul character. 1493 * 1494 * It is an error to call this function with a @value that is not an 1495 * array of bytes. 1496 * 1497 * The return value remains valid as long as @value exists. 1498 * 1499 * Since: 2.26 1500 **/ 1501 const gchar * 1502 g_variant_get_bytestring (GVariant *value) 1503 { 1504 const gchar *string; 1505 gsize size; 1506 1507 TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING, NULL); 1508 1509 /* Won't be NULL since this is an array type */ 1510 string = g_variant_get_data (value); 1511 size = g_variant_get_size (value); 1512 1513 if (size && string[size - 1] == '\0') 1514 return string; 1515 else 1516 return ""; 1517 } 1518 1519 /** 1520 * g_variant_dup_bytestring: 1521 * @value: an array-of-bytes #GVariant instance 1522 * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store 1523 * the length (not including the nul terminator) 1524 * @returns: (transfer full) (array zero-terminated=1): a newly allocated string 1525 * 1526 * Similar to g_variant_get_bytestring() except that instead of 1527 * returning a constant string, the string is duplicated. 1528 * 1529 * The return value must be freed using g_free(). 1530 * 1531 * Since: 2.26 1532 **/ 1533 gchar * 1534 g_variant_dup_bytestring (GVariant *value, 1535 gsize *length) 1536 { 1537 const gchar *original = g_variant_get_bytestring (value); 1538 gsize size; 1539 1540 /* don't crash in case get_bytestring() had an assert failure */ 1541 if (original == NULL) 1542 return NULL; 1543 1544 size = strlen (original); 1545 1546 if (length) 1547 *length = size; 1548 1549 return g_memdup (original, size + 1); 1550 } 1551 1552 /** 1553 * g_variant_new_bytestring_array: 1554 * @strv: (array length=length): an array of strings 1555 * @length: the length of @strv, or -1 1556 * @returns: (transfer none): a new floating #GVariant instance 1557 * 1558 * Constructs an array of bytestring #GVariant from the given array of 1559 * strings. 1560 * 1561 * If @length is -1 then @strv is %NULL-terminated. 1562 * 1563 * Since: 2.26 1564 **/ 1565 GVariant * 1566 g_variant_new_bytestring_array (const gchar * const *strv, 1567 gssize length) 1568 { 1569 GVariant **strings; 1570 gsize i; 1571 1572 g_return_val_if_fail (length == 0 || strv != NULL, NULL); 1573 1574 if (length < 0) 1575 length = g_strv_length ((gchar **) strv); 1576 1577 strings = g_new (GVariant *, length); 1578 for (i = 0; i < length; i++) 1579 strings[i] = g_variant_ref_sink (g_variant_new_bytestring (strv[i])); 1580 1581 return g_variant_new_from_children (G_VARIANT_TYPE_BYTESTRING_ARRAY, 1582 strings, length, TRUE); 1583 } 1584 1585 /** 1586 * g_variant_get_bytestring_array: 1587 * @value: an array of array of bytes #GVariant ('aay') 1588 * @length: (out) (allow-none): the length of the result, or %NULL 1589 * @returns: (array length=length) (transfer container): an array of constant strings 1590 * 1591 * Gets the contents of an array of array of bytes #GVariant. This call 1592 * makes a shallow copy; the return result should be released with 1593 * g_free(), but the individual strings must not be modified. 1594 * 1595 * If @length is non-%NULL then the number of elements in the result is 1596 * stored there. In any case, the resulting array will be 1597 * %NULL-terminated. 1598 * 1599 * For an empty array, @length will be set to 0 and a pointer to a 1600 * %NULL pointer will be returned. 1601 * 1602 * Since: 2.26 1603 **/ 1604 const gchar ** 1605 g_variant_get_bytestring_array (GVariant *value, 1606 gsize *length) 1607 { 1608 const gchar **strv; 1609 gsize n; 1610 gsize i; 1611 1612 TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL); 1613 1614 g_variant_get_data (value); 1615 n = g_variant_n_children (value); 1616 strv = g_new (const gchar *, n + 1); 1617 1618 for (i = 0; i < n; i++) 1619 { 1620 GVariant *string; 1621 1622 string = g_variant_get_child_value (value, i); 1623 strv[i] = g_variant_get_bytestring (string); 1624 g_variant_unref (string); 1625 } 1626 strv[i] = NULL; 1627 1628 if (length) 1629 *length = n; 1630 1631 return strv; 1632 } 1633 1634 /** 1635 * g_variant_dup_bytestring_array: 1636 * @value: an array of array of bytes #GVariant ('aay') 1637 * @length: (out) (allow-none): the length of the result, or %NULL 1638 * @returns: (array length=length) (transfer full): an array of strings 1639 * 1640 * Gets the contents of an array of array of bytes #GVariant. This call 1641 * makes a deep copy; the return result should be released with 1642 * g_strfreev(). 1643 * 1644 * If @length is non-%NULL then the number of elements in the result is 1645 * stored there. In any case, the resulting array will be 1646 * %NULL-terminated. 1647 * 1648 * For an empty array, @length will be set to 0 and a pointer to a 1649 * %NULL pointer will be returned. 1650 * 1651 * Since: 2.26 1652 **/ 1653 gchar ** 1654 g_variant_dup_bytestring_array (GVariant *value, 1655 gsize *length) 1656 { 1657 gchar **strv; 1658 gsize n; 1659 gsize i; 1660 1661 TYPE_CHECK (value, G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL); 1662 1663 g_variant_get_data (value); 1664 n = g_variant_n_children (value); 1665 strv = g_new (gchar *, n + 1); 1666 1667 for (i = 0; i < n; i++) 1668 { 1669 GVariant *string; 1670 1671 string = g_variant_get_child_value (value, i); 1672 strv[i] = g_variant_dup_bytestring (string, NULL); 1673 g_variant_unref (string); 1674 } 1675 strv[i] = NULL; 1676 1677 if (length) 1678 *length = n; 1679 1680 return strv; 1681 } 1682 1683 /* Type checking and querying {{{1 */ 1684 /** 1685 * g_variant_get_type: 1686 * @value: a #GVariant 1687 * @returns: a #GVariantType 1688 * 1689 * Determines the type of @value. 1690 * 1691 * The return value is valid for the lifetime of @value and must not 1692 * be freed. 1693 * 1694 * Since: 2.24 1695 **/ 1696 const GVariantType * 1697 g_variant_get_type (GVariant *value) 1698 { 1699 GVariantTypeInfo *type_info; 1700 1701 g_return_val_if_fail (value != NULL, NULL); 1702 1703 type_info = g_variant_get_type_info (value); 1704 1705 return (GVariantType *) g_variant_type_info_get_type_string (type_info); 1706 } 1707 1708 /** 1709 * g_variant_get_type_string: 1710 * @value: a #GVariant 1711 * @returns: the type string for the type of @value 1712 * 1713 * Returns the type string of @value. Unlike the result of calling 1714 * g_variant_type_peek_string(), this string is nul-terminated. This 1715 * string belongs to #GVariant and must not be freed. 1716 * 1717 * Since: 2.24 1718 **/ 1719 const gchar * 1720 g_variant_get_type_string (GVariant *value) 1721 { 1722 GVariantTypeInfo *type_info; 1723 1724 g_return_val_if_fail (value != NULL, NULL); 1725 1726 type_info = g_variant_get_type_info (value); 1727 1728 return g_variant_type_info_get_type_string (type_info); 1729 } 1730 1731 /** 1732 * g_variant_is_of_type: 1733 * @value: a #GVariant instance 1734 * @type: a #GVariantType 1735 * @returns: %TRUE if the type of @value matches @type 1736 * 1737 * Checks if a value has a type matching the provided type. 1738 * 1739 * Since: 2.24 1740 **/ 1741 gboolean 1742 g_variant_is_of_type (GVariant *value, 1743 const GVariantType *type) 1744 { 1745 return g_variant_type_is_subtype_of (g_variant_get_type (value), type); 1746 } 1747 1748 /** 1749 * g_variant_is_container: 1750 * @value: a #GVariant instance 1751 * @returns: %TRUE if @value is a container 1752 * 1753 * Checks if @value is a container. 1754 */ 1755 gboolean 1756 g_variant_is_container (GVariant *value) 1757 { 1758 return g_variant_type_is_container (g_variant_get_type (value)); 1759 } 1760 1761 1762 /** 1763 * g_variant_classify: 1764 * @value: a #GVariant 1765 * @returns: the #GVariantClass of @value 1766 * 1767 * Classifies @value according to its top-level type. 1768 * 1769 * Since: 2.24 1770 **/ 1771 /** 1772 * GVariantClass: 1773 * @G_VARIANT_CLASS_BOOLEAN: The #GVariant is a boolean. 1774 * @G_VARIANT_CLASS_BYTE: The #GVariant is a byte. 1775 * @G_VARIANT_CLASS_INT16: The #GVariant is a signed 16 bit integer. 1776 * @G_VARIANT_CLASS_UINT16: The #GVariant is an unsigned 16 bit integer. 1777 * @G_VARIANT_CLASS_INT32: The #GVariant is a signed 32 bit integer. 1778 * @G_VARIANT_CLASS_UINT32: The #GVariant is an unsigned 32 bit integer. 1779 * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer. 1780 * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer. 1781 * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index. 1782 * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating 1783 * point value. 1784 * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string. 1785 * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path 1786 * string. 1787 * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string. 1788 * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant. 1789 * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value. 1790 * @G_VARIANT_CLASS_ARRAY: The #GVariant is an array. 1791 * @G_VARIANT_CLASS_TUPLE: The #GVariant is a tuple. 1792 * @G_VARIANT_CLASS_DICT_ENTRY: The #GVariant is a dictionary entry. 1793 * 1794 * The range of possible top-level types of #GVariant instances. 1795 * 1796 * Since: 2.24 1797 **/ 1798 GVariantClass 1799 g_variant_classify (GVariant *value) 1800 { 1801 g_return_val_if_fail (value != NULL, 0); 1802 1803 return *g_variant_get_type_string (value); 1804 } 1805 1806 /* Pretty printer {{{1 */ 1807 /* This function is not introspectable because if @string is NULL, 1808 @returns is (transfer full), otherwise it is (transfer none), which 1809 is not supported by GObjectIntrospection */ 1810 /** 1811 * g_variant_print_string: (skip) 1812 * @value: a #GVariant 1813 * @string: (allow-none) (default NULL): a #GString, or %NULL 1814 * @type_annotate: %TRUE if type information should be included in 1815 * the output 1816 * @returns: a #GString containing the string 1817 * 1818 * Behaves as g_variant_print(), but operates on a #GString. 1819 * 1820 * If @string is non-%NULL then it is appended to and returned. Else, 1821 * a new empty #GString is allocated and it is returned. 1822 * 1823 * Since: 2.24 1824 **/ 1825 GString * 1826 g_variant_print_string (GVariant *value, 1827 GString *string, 1828 gboolean type_annotate) 1829 { 1830 if G_UNLIKELY (string == NULL) 1831 string = g_string_new (NULL); 1832 1833 switch (g_variant_classify (value)) 1834 { 1835 case G_VARIANT_CLASS_MAYBE: 1836 if (type_annotate) 1837 g_string_append_printf (string, "@%s ", 1838 g_variant_get_type_string (value)); 1839 1840 if (g_variant_n_children (value)) 1841 { 1842 gchar *printed_child; 1843 GVariant *element; 1844 1845 /* Nested maybes: 1846 * 1847 * Consider the case of the type "mmi". In this case we could 1848 * write "just just 4", but "4" alone is totally unambiguous, 1849 * so we try to drop "just" where possible. 1850 * 1851 * We have to be careful not to always drop "just", though, 1852 * since "nothing" needs to be distinguishable from "just 1853 * nothing". The case where we need to ensure we keep the 1854 * "just" is actually exactly the case where we have a nested 1855 * Nothing. 1856 * 1857 * Instead of searching for that nested Nothing, we just print 1858 * the contained value into a separate string and see if we 1859 * end up with "nothing" at the end of it. If so, we need to 1860 * add "just" at our level. 1861 */ 1862 element = g_variant_get_child_value (value, 0); 1863 printed_child = g_variant_print (element, FALSE); 1864 g_variant_unref (element); 1865 1866 if (g_str_has_suffix (printed_child, "nothing")) 1867 g_string_append (string, "just "); 1868 g_string_append (string, printed_child); 1869 g_free (printed_child); 1870 } 1871 else 1872 g_string_append (string, "nothing"); 1873 1874 break; 1875 1876 case G_VARIANT_CLASS_ARRAY: 1877 /* it's an array so the first character of the type string is 'a' 1878 * 1879 * if the first two characters are 'ay' then it's a bytestring. 1880 * under certain conditions we print those as strings. 1881 */ 1882 if (g_variant_get_type_string (value)[1] == 'y') 1883 { 1884 const gchar *str; 1885 gsize size; 1886 gsize i; 1887 1888 /* first determine if it is a byte string. 1889 * that's when there's a single nul character: at the end. 1890 */ 1891 str = g_variant_get_data (value); 1892 size = g_variant_get_size (value); 1893 1894 for (i = 0; i < size; i++) 1895 if (str[i] == '\0') 1896 break; 1897 1898 /* first nul byte is the last byte -> it's a byte string. */ 1899 if (i == size - 1) 1900 { 1901 gchar *escaped = g_strescape (str, NULL); 1902 1903 /* use double quotes only if a ' is in the string */ 1904 if (strchr (str, '\'')) 1905 g_string_append_printf (string, "b\"%s\"", escaped); 1906 else 1907 g_string_append_printf (string, "b'%s'", escaped); 1908 1909 g_free (escaped); 1910 break; 1911 } 1912 1913 else 1914 /* fall through and handle normally... */; 1915 } 1916 1917 /* 1918 * if the first two characters are 'a{' then it's an array of 1919 * dictionary entries (ie: a dictionary) so we print that 1920 * differently. 1921 */ 1922 if (g_variant_get_type_string (value)[1] == '{') 1923 /* dictionary */ 1924 { 1925 const gchar *comma = ""; 1926 gsize n, i; 1927 1928 if ((n = g_variant_n_children (value)) == 0) 1929 { 1930 if (type_annotate) 1931 g_string_append_printf (string, "@%s ", 1932 g_variant_get_type_string (value)); 1933 g_string_append (string, "{}"); 1934 break; 1935 } 1936 1937 g_string_append_c (string, '{'); 1938 for (i = 0; i < n; i++) 1939 { 1940 GVariant *entry, *key, *val; 1941 1942 g_string_append (string, comma); 1943 comma = ", "; 1944 1945 entry = g_variant_get_child_value (value, i); 1946 key = g_variant_get_child_value (entry, 0); 1947 val = g_variant_get_child_value (entry, 1); 1948 g_variant_unref (entry); 1949 1950 g_variant_print_string (key, string, type_annotate); 1951 g_variant_unref (key); 1952 g_string_append (string, ": "); 1953 g_variant_print_string (val, string, type_annotate); 1954 g_variant_unref (val); 1955 type_annotate = FALSE; 1956 } 1957 g_string_append_c (string, '}'); 1958 } 1959 else 1960 /* normal (non-dictionary) array */ 1961 { 1962 const gchar *comma = ""; 1963 gsize n, i; 1964 1965 if ((n = g_variant_n_children (value)) == 0) 1966 { 1967 if (type_annotate) 1968 g_string_append_printf (string, "@%s ", 1969 g_variant_get_type_string (value)); 1970 g_string_append (string, "[]"); 1971 break; 1972 } 1973 1974 g_string_append_c (string, '['); 1975 for (i = 0; i < n; i++) 1976 { 1977 GVariant *element; 1978 1979 g_string_append (string, comma); 1980 comma = ", "; 1981 1982 element = g_variant_get_child_value (value, i); 1983 1984 g_variant_print_string (element, string, type_annotate); 1985 g_variant_unref (element); 1986 type_annotate = FALSE; 1987 } 1988 g_string_append_c (string, ']'); 1989 } 1990 1991 break; 1992 1993 case G_VARIANT_CLASS_TUPLE: 1994 { 1995 gsize n, i; 1996 1997 n = g_variant_n_children (value); 1998 1999 g_string_append_c (string, '('); 2000 for (i = 0; i < n; i++) 2001 { 2002 GVariant *element; 2003 2004 element = g_variant_get_child_value (value, i); 2005 g_variant_print_string (element, string, type_annotate); 2006 g_string_append (string, ", "); 2007 g_variant_unref (element); 2008 } 2009 2010 /* for >1 item: remove final ", " 2011 * for 1 item: remove final " ", but leave the "," 2012 * for 0 items: there is only "(", so remove nothing 2013 */ 2014 g_string_truncate (string, string->len - (n > 0) - (n > 1)); 2015 g_string_append_c (string, ')'); 2016 } 2017 break; 2018 2019 case G_VARIANT_CLASS_DICT_ENTRY: 2020 { 2021 GVariant *element; 2022 2023 g_string_append_c (string, '{'); 2024 2025 element = g_variant_get_child_value (value, 0); 2026 g_variant_print_string (element, string, type_annotate); 2027 g_variant_unref (element); 2028 2029 g_string_append (string, ", "); 2030 2031 element = g_variant_get_child_value (value, 1); 2032 g_variant_print_string (element, string, type_annotate); 2033 g_variant_unref (element); 2034 2035 g_string_append_c (string, '}'); 2036 } 2037 break; 2038 2039 case G_VARIANT_CLASS_VARIANT: 2040 { 2041 GVariant *child = g_variant_get_variant (value); 2042 2043 /* Always annotate types in nested variants, because they are 2044 * (by nature) of variable type. 2045 */ 2046 g_string_append_c (string, '<'); 2047 g_variant_print_string (child, string, TRUE); 2048 g_string_append_c (string, '>'); 2049 2050 g_variant_unref (child); 2051 } 2052 break; 2053 2054 case G_VARIANT_CLASS_BOOLEAN: 2055 if (g_variant_get_boolean (value)) 2056 g_string_append (string, "true"); 2057 else 2058 g_string_append (string, "false"); 2059 break; 2060 2061 case G_VARIANT_CLASS_STRING: 2062 { 2063 const gchar *str = g_variant_get_string (value, NULL); 2064 gunichar quote = strchr (str, '\'') ? '"' : '\''; 2065 2066 g_string_append_c (string, quote); 2067 2068 while (*str) 2069 { 2070 gunichar c = g_utf8_get_char (str); 2071 2072 if (c == quote || c == '\\') 2073 g_string_append_c (string, '\\'); 2074 2075 if (g_unichar_isprint (c)) 2076 g_string_append_unichar (string, c); 2077 2078 else 2079 { 2080 g_string_append_c (string, '\\'); 2081 if (c < 0x10000) 2082 switch (c) 2083 { 2084 case '\a': 2085 g_string_append_c (string, 'a'); 2086 break; 2087 2088 case '\b': 2089 g_string_append_c (string, 'b'); 2090 break; 2091 2092 case '\f': 2093 g_string_append_c (string, 'f'); 2094 break; 2095 2096 case '\n': 2097 g_string_append_c (string, 'n'); 2098 break; 2099 2100 case '\r': 2101 g_string_append_c (string, 'r'); 2102 break; 2103 2104 case '\t': 2105 g_string_append_c (string, 't'); 2106 break; 2107 2108 case '\v': 2109 g_string_append_c (string, 'v'); 2110 break; 2111 2112 default: 2113 g_string_append_printf (string, "u%04x", c); 2114 break; 2115 } 2116 else 2117 g_string_append_printf (string, "U%08x", c); 2118 } 2119 2120 str = g_utf8_next_char (str); 2121 } 2122 2123 g_string_append_c (string, quote); 2124 } 2125 break; 2126 2127 case G_VARIANT_CLASS_BYTE: 2128 if (type_annotate) 2129 g_string_append (string, "byte "); 2130 g_string_append_printf (string, "0x%02x", 2131 g_variant_get_byte (value)); 2132 break; 2133 2134 case G_VARIANT_CLASS_INT16: 2135 if (type_annotate) 2136 g_string_append (string, "int16 "); 2137 g_string_append_printf (string, "%"G_GINT16_FORMAT, 2138 g_variant_get_int16 (value)); 2139 break; 2140 2141 case G_VARIANT_CLASS_UINT16: 2142 if (type_annotate) 2143 g_string_append (string, "uint16 "); 2144 g_string_append_printf (string, "%"G_GUINT16_FORMAT, 2145 g_variant_get_uint16 (value)); 2146 break; 2147 2148 case G_VARIANT_CLASS_INT32: 2149 /* Never annotate this type because it is the default for numbers 2150 * (and this is a *pretty* printer) 2151 */ 2152 g_string_append_printf (string, "%"G_GINT32_FORMAT, 2153 g_variant_get_int32 (value)); 2154 break; 2155 2156 case G_VARIANT_CLASS_HANDLE: 2157 if (type_annotate) 2158 g_string_append (string, "handle "); 2159 g_string_append_printf (string, "%"G_GINT32_FORMAT, 2160 g_variant_get_handle (value)); 2161 break; 2162 2163 case G_VARIANT_CLASS_UINT32: 2164 if (type_annotate) 2165 g_string_append (string, "uint32 "); 2166 g_string_append_printf (string, "%"G_GUINT32_FORMAT, 2167 g_variant_get_uint32 (value)); 2168 break; 2169 2170 case G_VARIANT_CLASS_INT64: 2171 if (type_annotate) 2172 g_string_append (string, "int64 "); 2173 g_string_append_printf (string, "%"G_GINT64_FORMAT, 2174 g_variant_get_int64 (value)); 2175 break; 2176 2177 case G_VARIANT_CLASS_UINT64: 2178 if (type_annotate) 2179 g_string_append (string, "uint64 "); 2180 g_string_append_printf (string, "%"G_GUINT64_FORMAT, 2181 g_variant_get_uint64 (value)); 2182 break; 2183 2184 case G_VARIANT_CLASS_DOUBLE: 2185 { 2186 gchar buffer[100]; 2187 gint i; 2188 2189 g_ascii_dtostr (buffer, sizeof buffer, g_variant_get_double (value)); 2190 2191 for (i = 0; buffer[i]; i++) 2192 if (buffer[i] == '.' || buffer[i] == 'e' || 2193 buffer[i] == 'n' || buffer[i] == 'N') 2194 break; 2195 2196 /* if there is no '.' or 'e' in the float then add one */ 2197 if (buffer[i] == '\0') 2198 { 2199 buffer[i++] = '.'; 2200 buffer[i++] = '0'; 2201 buffer[i++] = '\0'; 2202 } 2203 2204 g_string_append (string, buffer); 2205 } 2206 break; 2207 2208 case G_VARIANT_CLASS_OBJECT_PATH: 2209 if (type_annotate) 2210 g_string_append (string, "objectpath "); 2211 g_string_append_printf (string, "\'%s\'", 2212 g_variant_get_string (value, NULL)); 2213 break; 2214 2215 case G_VARIANT_CLASS_SIGNATURE: 2216 if (type_annotate) 2217 g_string_append (string, "signature "); 2218 g_string_append_printf (string, "\'%s\'", 2219 g_variant_get_string (value, NULL)); 2220 break; 2221 2222 default: 2223 g_assert_not_reached (); 2224 } 2225 2226 return string; 2227 } 2228 2229 /** 2230 * g_variant_print: 2231 * @value: a #GVariant 2232 * @type_annotate: %TRUE if type information should be included in 2233 * the output 2234 * @returns: (transfer full): a newly-allocated string holding the result. 2235 * 2236 * Pretty-prints @value in the format understood by g_variant_parse(). 2237 * 2238 * The format is described <link linkend='gvariant-text'>here</link>. 2239 * 2240 * If @type_annotate is %TRUE, then type information is included in 2241 * the output. 2242 */ 2243 gchar * 2244 g_variant_print (GVariant *value, 2245 gboolean type_annotate) 2246 { 2247 return g_string_free (g_variant_print_string (value, NULL, type_annotate), 2248 FALSE); 2249 }; 2250 2251 /* Hash, Equal, Compare {{{1 */ 2252 /** 2253 * g_variant_hash: 2254 * @value: (type GVariant): a basic #GVariant value as a #gconstpointer 2255 * @returns: a hash value corresponding to @value 2256 * 2257 * Generates a hash value for a #GVariant instance. 2258 * 2259 * The output of this function is guaranteed to be the same for a given 2260 * value only per-process. It may change between different processor 2261 * architectures or even different versions of GLib. Do not use this 2262 * function as a basis for building protocols or file formats. 2263 * 2264 * The type of @value is #gconstpointer only to allow use of this 2265 * function with #GHashTable. @value must be a #GVariant. 2266 * 2267 * Since: 2.24 2268 **/ 2269 guint 2270 g_variant_hash (gconstpointer value_) 2271 { 2272 GVariant *value = (GVariant *) value_; 2273 2274 switch (g_variant_classify (value)) 2275 { 2276 case G_VARIANT_CLASS_STRING: 2277 case G_VARIANT_CLASS_OBJECT_PATH: 2278 case G_VARIANT_CLASS_SIGNATURE: 2279 return g_str_hash (g_variant_get_string (value, NULL)); 2280 2281 case G_VARIANT_CLASS_BOOLEAN: 2282 /* this is a very odd thing to hash... */ 2283 return g_variant_get_boolean (value); 2284 2285 case G_VARIANT_CLASS_BYTE: 2286 return g_variant_get_byte (value); 2287 2288 case G_VARIANT_CLASS_INT16: 2289 case G_VARIANT_CLASS_UINT16: 2290 { 2291 const guint16 *ptr; 2292 2293 ptr = g_variant_get_data (value); 2294 2295 if (ptr) 2296 return *ptr; 2297 else 2298 return 0; 2299 } 2300 2301 case G_VARIANT_CLASS_INT32: 2302 case G_VARIANT_CLASS_UINT32: 2303 case G_VARIANT_CLASS_HANDLE: 2304 { 2305 const guint *ptr; 2306 2307 ptr = g_variant_get_data (value); 2308 2309 if (ptr) 2310 return *ptr; 2311 else 2312 return 0; 2313 } 2314 2315 case G_VARIANT_CLASS_INT64: 2316 case G_VARIANT_CLASS_UINT64: 2317 case G_VARIANT_CLASS_DOUBLE: 2318 /* need a separate case for these guys because otherwise 2319 * performance could be quite bad on big endian systems 2320 */ 2321 { 2322 const guint *ptr; 2323 2324 ptr = g_variant_get_data (value); 2325 2326 if (ptr) 2327 return ptr[0] + ptr[1]; 2328 else 2329 return 0; 2330 } 2331 2332 default: 2333 g_return_val_if_fail (!g_variant_is_container (value), 0); 2334 g_assert_not_reached (); 2335 } 2336 } 2337 2338 /** 2339 * g_variant_equal: 2340 * @one: (type GVariant): a #GVariant instance 2341 * @two: (type GVariant): a #GVariant instance 2342 * @returns: %TRUE if @one and @two are equal 2343 * 2344 * Checks if @one and @two have the same type and value. 2345 * 2346 * The types of @one and @two are #gconstpointer only to allow use of 2347 * this function with #GHashTable. They must each be a #GVariant. 2348 * 2349 * Since: 2.24 2350 **/ 2351 gboolean 2352 g_variant_equal (gconstpointer one, 2353 gconstpointer two) 2354 { 2355 gboolean equal; 2356 2357 g_return_val_if_fail (one != NULL && two != NULL, FALSE); 2358 2359 if (g_variant_get_type_info ((GVariant *) one) != 2360 g_variant_get_type_info ((GVariant *) two)) 2361 return FALSE; 2362 2363 /* if both values are trusted to be in their canonical serialised form 2364 * then a simple memcmp() of their serialised data will answer the 2365 * question. 2366 * 2367 * if not, then this might generate a false negative (since it is 2368 * possible for two different byte sequences to represent the same 2369 * value). for now we solve this by pretty-printing both values and 2370 * comparing the result. 2371 */ 2372 if (g_variant_is_trusted ((GVariant *) one) && 2373 g_variant_is_trusted ((GVariant *) two)) 2374 { 2375 gconstpointer data_one, data_two; 2376 gsize size_one, size_two; 2377 2378 size_one = g_variant_get_size ((GVariant *) one); 2379 size_two = g_variant_get_size ((GVariant *) two); 2380 2381 if (size_one != size_two) 2382 return FALSE; 2383 2384 data_one = g_variant_get_data ((GVariant *) one); 2385 data_two = g_variant_get_data ((GVariant *) two); 2386 2387 equal = memcmp (data_one, data_two, size_one) == 0; 2388 } 2389 else 2390 { 2391 gchar *strone, *strtwo; 2392 2393 strone = g_variant_print ((GVariant *) one, FALSE); 2394 strtwo = g_variant_print ((GVariant *) two, FALSE); 2395 equal = strcmp (strone, strtwo) == 0; 2396 g_free (strone); 2397 g_free (strtwo); 2398 } 2399 2400 return equal; 2401 } 2402 2403 /** 2404 * g_variant_compare: 2405 * @one: (type GVariant): a basic-typed #GVariant instance 2406 * @two: (type GVariant): a #GVariant instance of the same type 2407 * @returns: negative value if a < b; 2408 * zero if a = b; 2409 * positive value if a > b. 2410 * 2411 * Compares @one and @two. 2412 * 2413 * The types of @one and @two are #gconstpointer only to allow use of 2414 * this function with #GTree, #GPtrArray, etc. They must each be a 2415 * #GVariant. 2416 * 2417 * Comparison is only defined for basic types (ie: booleans, numbers, 2418 * strings). For booleans, %FALSE is less than %TRUE. Numbers are 2419 * ordered in the usual way. Strings are in ASCII lexographical order. 2420 * 2421 * It is a programmer error to attempt to compare container values or 2422 * two values that have types that are not exactly equal. For example, 2423 * you can not compare a 32-bit signed integer with a 32-bit unsigned 2424 * integer. Also note that this function is not particularly 2425 * well-behaved when it comes to comparison of doubles; in particular, 2426 * the handling of incomparable values (ie: NaN) is undefined. 2427 * 2428 * If you only require an equality comparison, g_variant_equal() is more 2429 * general. 2430 * 2431 * Since: 2.26 2432 **/ 2433 gint 2434 g_variant_compare (gconstpointer one, 2435 gconstpointer two) 2436 { 2437 GVariant *a = (GVariant *) one; 2438 GVariant *b = (GVariant *) two; 2439 2440 g_return_val_if_fail (g_variant_classify (a) == g_variant_classify (b), 0); 2441 2442 switch (g_variant_classify (a)) 2443 { 2444 case G_VARIANT_CLASS_BYTE: 2445 return ((gint) g_variant_get_byte (a)) - 2446 ((gint) g_variant_get_byte (b)); 2447 2448 case G_VARIANT_CLASS_INT16: 2449 return ((gint) g_variant_get_int16 (a)) - 2450 ((gint) g_variant_get_int16 (b)); 2451 2452 case G_VARIANT_CLASS_UINT16: 2453 return ((gint) g_variant_get_uint16 (a)) - 2454 ((gint) g_variant_get_uint16 (b)); 2455 2456 case G_VARIANT_CLASS_INT32: 2457 { 2458 gint32 a_val = g_variant_get_int32 (a); 2459 gint32 b_val = g_variant_get_int32 (b); 2460 2461 return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1; 2462 } 2463 2464 case G_VARIANT_CLASS_UINT32: 2465 { 2466 guint32 a_val = g_variant_get_uint32 (a); 2467 guint32 b_val = g_variant_get_uint32 (b); 2468 2469 return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1; 2470 } 2471 2472 case G_VARIANT_CLASS_INT64: 2473 { 2474 gint64 a_val = g_variant_get_int64 (a); 2475 gint64 b_val = g_variant_get_int64 (b); 2476 2477 return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1; 2478 } 2479 2480 case G_VARIANT_CLASS_UINT64: 2481 { 2482 guint64 a_val = g_variant_get_int32 (a); 2483 guint64 b_val = g_variant_get_int32 (b); 2484 2485 return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1; 2486 } 2487 2488 case G_VARIANT_CLASS_DOUBLE: 2489 { 2490 gdouble a_val = g_variant_get_double (a); 2491 gdouble b_val = g_variant_get_double (b); 2492 2493 return (a_val == b_val) ? 0 : (a_val > b_val) ? 1 : -1; 2494 } 2495 2496 case G_VARIANT_CLASS_STRING: 2497 case G_VARIANT_CLASS_OBJECT_PATH: 2498 case G_VARIANT_CLASS_SIGNATURE: 2499 return strcmp (g_variant_get_string (a, NULL), 2500 g_variant_get_string (b, NULL)); 2501 2502 default: 2503 g_return_val_if_fail (!g_variant_is_container (a), 0); 2504 g_assert_not_reached (); 2505 } 2506 } 2507 2508 /* GVariantIter {{{1 */ 2509 /** 2510 * GVariantIter: 2511 * 2512 * #GVariantIter is an opaque data structure and can only be accessed 2513 * using the following functions. 2514 **/ 2515 struct stack_iter 2516 { 2517 GVariant *value; 2518 gssize n, i; 2519 2520 const gchar *loop_format; 2521 2522 gsize padding[3]; 2523 gsize magic; 2524 }; 2525 2526 G_STATIC_ASSERT (sizeof (struct stack_iter) <= sizeof (GVariantIter)); 2527 2528 struct heap_iter 2529 { 2530 struct stack_iter iter; 2531 2532 GVariant *value_ref; 2533 gsize magic; 2534 }; 2535 2536 #define GVSI(i) ((struct stack_iter *) (i)) 2537 #define GVHI(i) ((struct heap_iter *) (i)) 2538 #define GVSI_MAGIC ((gsize) 3579507750u) 2539 #define GVHI_MAGIC ((gsize) 1450270775u) 2540 #define is_valid_iter(i) (i != NULL && \ 2541 GVSI(i)->magic == GVSI_MAGIC) 2542 #define is_valid_heap_iter(i) (GVHI(i)->magic == GVHI_MAGIC && \ 2543 is_valid_iter(i)) 2544 2545 /** 2546 * g_variant_iter_new: 2547 * @value: a container #GVariant 2548 * @returns: (transfer full): a new heap-allocated #GVariantIter 2549 * 2550 * Creates a heap-allocated #GVariantIter for iterating over the items 2551 * in @value. 2552 * 2553 * Use g_variant_iter_free() to free the return value when you no longer 2554 * need it. 2555 * 2556 * A reference is taken to @value and will be released only when 2557 * g_variant_iter_free() is called. 2558 * 2559 * Since: 2.24 2560 **/ 2561 GVariantIter * 2562 g_variant_iter_new (GVariant *value) 2563 { 2564 GVariantIter *iter; 2565 2566 iter = (GVariantIter *) g_slice_new (struct heap_iter); 2567 #ifdef GSTREAMER_LITE 2568 if (iter == NULL) { 2569 return NULL; 2570 } 2571 #endif // GSTREAMER_LITE 2572 GVHI(iter)->value_ref = g_variant_ref (value); 2573 GVHI(iter)->magic = GVHI_MAGIC; 2574 2575 g_variant_iter_init (iter, value); 2576 2577 return iter; 2578 } 2579 2580 /** 2581 * g_variant_iter_init: (skip) 2582 * @iter: a pointer to a #GVariantIter 2583 * @value: a container #GVariant 2584 * @returns: the number of items in @value 2585 * 2586 * Initialises (without allocating) a #GVariantIter. @iter may be 2587 * completely uninitialised prior to this call; its old value is 2588 * ignored. 2589 * 2590 * The iterator remains valid for as long as @value exists, and need not 2591 * be freed in any way. 2592 * 2593 * Since: 2.24 2594 **/ 2595 gsize 2596 g_variant_iter_init (GVariantIter *iter, 2597 GVariant *value) 2598 { 2599 GVSI(iter)->magic = GVSI_MAGIC; 2600 GVSI(iter)->value = value; 2601 GVSI(iter)->n = g_variant_n_children (value); 2602 GVSI(iter)->i = -1; 2603 GVSI(iter)->loop_format = NULL; 2604 2605 return GVSI(iter)->n; 2606 } 2607 2608 /** 2609 * g_variant_iter_copy: 2610 * @iter: a #GVariantIter 2611 * @returns: (transfer full): a new heap-allocated #GVariantIter 2612 * 2613 * Creates a new heap-allocated #GVariantIter to iterate over the 2614 * container that was being iterated over by @iter. Iteration begins on 2615 * the new iterator from the current position of the old iterator but 2616 * the two copies are independent past that point. 2617 * 2618 * Use g_variant_iter_free() to free the return value when you no longer 2619 * need it. 2620 * 2621 * A reference is taken to the container that @iter is iterating over 2622 * and will be releated only when g_variant_iter_free() is called. 2623 * 2624 * Since: 2.24 2625 **/ 2626 GVariantIter * 2627 g_variant_iter_copy (GVariantIter *iter) 2628 { 2629 GVariantIter *copy; 2630 2631 #ifdef GSTREAMER_LITE 2632 if (iter == NULL) { 2633 return NULL; 2634 } 2635 #endif // GSTREAMER_LITE 2636 2637 g_return_val_if_fail (is_valid_iter (iter), 0); 2638 2639 copy = g_variant_iter_new (GVSI(iter)->value); 2640 GVSI(copy)->i = GVSI(iter)->i; 2641 2642 return copy; 2643 } 2644 2645 /** 2646 * g_variant_iter_n_children: 2647 * @iter: a #GVariantIter 2648 * @returns: the number of children in the container 2649 * 2650 * Queries the number of child items in the container that we are 2651 * iterating over. This is the total number of items -- not the number 2652 * of items remaining. 2653 * 2654 * This function might be useful for preallocation of arrays. 2655 * 2656 * Since: 2.24 2657 **/ 2658 gsize 2659 g_variant_iter_n_children (GVariantIter *iter) 2660 { 2661 g_return_val_if_fail (is_valid_iter (iter), 0); 2662 2663 return GVSI(iter)->n; 2664 } 2665 2666 /** 2667 * g_variant_iter_free: 2668 * @iter: (transfer full): a heap-allocated #GVariantIter 2669 * 2670 * Frees a heap-allocated #GVariantIter. Only call this function on 2671 * iterators that were returned by g_variant_iter_new() or 2672 * g_variant_iter_copy(). 2673 * 2674 * Since: 2.24 2675 **/ 2676 void 2677 g_variant_iter_free (GVariantIter *iter) 2678 { 2679 g_return_if_fail (is_valid_heap_iter (iter)); 2680 2681 g_variant_unref (GVHI(iter)->value_ref); 2682 GVHI(iter)->magic = 0; 2683 2684 g_slice_free (struct heap_iter, GVHI(iter)); 2685 } 2686 2687 /** 2688 * g_variant_iter_next_value: 2689 * @iter: a #GVariantIter 2690 * @returns: (allow-none) (transfer full): a #GVariant, or %NULL 2691 * 2692 * Gets the next item in the container. If no more items remain then 2693 * %NULL is returned. 2694 * 2695 * Use g_variant_unref() to drop your reference on the return value when 2696 * you no longer need it. 2697 * 2698 * <example> 2699 * <title>Iterating with g_variant_iter_next_value()</title> 2700 * <programlisting> 2701 * /<!-- -->* recursively iterate a container *<!-- -->/ 2702 * void 2703 * iterate_container_recursive (GVariant *container) 2704 * { 2705 * GVariantIter iter; 2706 * GVariant *child; 2707 * 2708 * g_variant_iter_init (&iter, dictionary); 2709 * while ((child = g_variant_iter_next_value (&iter))) 2710 * { 2711 * g_print ("type '%s'\n", g_variant_get_type_string (child)); 2712 * 2713 * if (g_variant_is_container (child)) 2714 * iterate_container_recursive (child); 2715 * 2716 * g_variant_unref (child); 2717 * } 2718 * } 2719 * </programlisting> 2720 * </example> 2721 * 2722 * Since: 2.24 2723 **/ 2724 GVariant * 2725 g_variant_iter_next_value (GVariantIter *iter) 2726 { 2727 g_return_val_if_fail (is_valid_iter (iter), FALSE); 2728 2729 if G_UNLIKELY (GVSI(iter)->i >= GVSI(iter)->n) 2730 { 2731 g_critical ("g_variant_iter_next_value: must not be called again " 2732 "after NULL has already been returned."); 2733 return NULL; 2734 } 2735 2736 GVSI(iter)->i++; 2737 2738 if (GVSI(iter)->i < GVSI(iter)->n) 2739 return g_variant_get_child_value (GVSI(iter)->value, GVSI(iter)->i); 2740 2741 return NULL; 2742 } 2743 2744 /* GVariantBuilder {{{1 */ 2745 /** 2746 * GVariantBuilder: 2747 * 2748 * A utility type for constructing container-type #GVariant instances. 2749 * 2750 * This is an opaque structure and may only be accessed using the 2751 * following functions. 2752 * 2753 * #GVariantBuilder is not threadsafe in any way. Do not attempt to 2754 * access it from more than one thread. 2755 **/ 2756 2757 struct stack_builder 2758 { 2759 GVariantBuilder *parent; 2760 GVariantType *type; 2761 2762 /* type constraint explicitly specified by 'type'. 2763 * for tuple types, this moves along as we add more items. 2764 */ 2765 const GVariantType *expected_type; 2766 2767 /* type constraint implied by previous array item. 2768 */ 2769 const GVariantType *prev_item_type; 2770 2771 /* constraints on the number of children. max = -1 for unlimited. */ 2772 gsize min_items; 2773 gsize max_items; 2774 2775 /* dynamically-growing pointer array */ 2776 GVariant **children; 2777 gsize allocated_children; 2778 gsize offset; 2779 2780 /* set to '1' if all items in the container will have the same type 2781 * (ie: maybe, array, variant) '0' if not (ie: tuple, dict entry) 2782 */ 2783 guint uniform_item_types : 1; 2784 2785 /* set to '1' initially and changed to '0' if an untrusted value is 2786 * added 2787 */ 2788 guint trusted : 1; 2789 2790 gsize magic; 2791 }; 2792 2793 G_STATIC_ASSERT (sizeof (struct stack_builder) <= sizeof (GVariantBuilder)); 2794 2795 struct heap_builder 2796 { 2797 GVariantBuilder builder; 2798 gsize magic; 2799 2800 gint ref_count; 2801 }; 2802 2803 #define GVSB(b) ((struct stack_builder *) (b)) 2804 #define GVHB(b) ((struct heap_builder *) (b)) 2805 #define GVSB_MAGIC ((gsize) 1033660112u) 2806 #define GVHB_MAGIC ((gsize) 3087242682u) 2807 #define is_valid_builder(b) (b != NULL && \ 2808 GVSB(b)->magic == GVSB_MAGIC) 2809 #define is_valid_heap_builder(b) (GVHB(b)->magic == GVHB_MAGIC) 2810 2811 /** 2812 * g_variant_builder_new: 2813 * @type: a container type 2814 * @returns: (transfer full): a #GVariantBuilder 2815 * 2816 * Allocates and initialises a new #GVariantBuilder. 2817 * 2818 * You should call g_variant_builder_unref() on the return value when it 2819 * is no longer needed. The memory will not be automatically freed by 2820 * any other call. 2821 * 2822 * In most cases it is easier to place a #GVariantBuilder directly on 2823 * the stack of the calling function and initialise it with 2824 * g_variant_builder_init(). 2825 * 2826 * Since: 2.24 2827 **/ 2828 GVariantBuilder * 2829 g_variant_builder_new (const GVariantType *type) 2830 { 2831 GVariantBuilder *builder; 2832 2833 builder = (GVariantBuilder *) g_slice_new (struct heap_builder); 2834 #ifdef GSTREAMER_LITE 2835 if (builder == NULL) { 2836 return NULL; 2837 } 2838 #endif // GSTREAMER_LITE 2839 g_variant_builder_init (builder, type); 2840 GVHB(builder)->magic = GVHB_MAGIC; 2841 GVHB(builder)->ref_count = 1; 2842 2843 return builder; 2844 } 2845 2846 /** 2847 * g_variant_builder_unref: 2848 * @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new() 2849 * 2850 * Decreases the reference count on @builder. 2851 * 2852 * In the event that there are no more references, releases all memory 2853 * associated with the #GVariantBuilder. 2854 * 2855 * Don't call this on stack-allocated #GVariantBuilder instances or bad 2856 * things will happen. 2857 * 2858 * Since: 2.24 2859 **/ 2860 void 2861 g_variant_builder_unref (GVariantBuilder *builder) 2862 { 2863 g_return_if_fail (is_valid_heap_builder (builder)); 2864 2865 if (--GVHB(builder)->ref_count) 2866 return; 2867 2868 g_variant_builder_clear (builder); 2869 GVHB(builder)->magic = 0; 2870 2871 g_slice_free (struct heap_builder, GVHB(builder)); 2872 } 2873 2874 /** 2875 * g_variant_builder_ref: 2876 * @builder: a #GVariantBuilder allocated by g_variant_builder_new() 2877 * @returns: (transfer full): a new reference to @builder 2878 * 2879 * Increases the reference count on @builder. 2880 * 2881 * Don't call this on stack-allocated #GVariantBuilder instances or bad 2882 * things will happen. 2883 * 2884 * Since: 2.24 2885 **/ 2886 GVariantBuilder * 2887 g_variant_builder_ref (GVariantBuilder *builder) 2888 { 2889 g_return_val_if_fail (is_valid_heap_builder (builder), NULL); 2890 2891 GVHB(builder)->ref_count++; 2892 2893 return builder; 2894 } 2895 2896 /** 2897 * g_variant_builder_clear: (skip) 2898 * @builder: a #GVariantBuilder 2899 * 2900 * Releases all memory associated with a #GVariantBuilder without 2901 * freeing the #GVariantBuilder structure itself. 2902 * 2903 * It typically only makes sense to do this on a stack-allocated 2904 * #GVariantBuilder if you want to abort building the value part-way 2905 * through. This function need not be called if you call 2906 * g_variant_builder_end() and it also doesn't need to be called on 2907 * builders allocated with g_variant_builder_new (see 2908 * g_variant_builder_unref() for that). 2909 * 2910 * This function leaves the #GVariantBuilder structure set to all-zeros. 2911 * It is valid to call this function on either an initialised 2912 * #GVariantBuilder or one that is set to all-zeros but it is not valid 2913 * to call this function on uninitialised memory. 2914 * 2915 * Since: 2.24 2916 **/ 2917 void 2918 g_variant_builder_clear (GVariantBuilder *builder) 2919 { 2920 gsize i; 2921 2922 if (GVSB(builder)->magic == 0) 2923 /* all-zeros case */ 2924 return; 2925 2926 g_return_if_fail (is_valid_builder (builder)); 2927 2928 g_variant_type_free (GVSB(builder)->type); 2929 2930 for (i = 0; i < GVSB(builder)->offset; i++) 2931 g_variant_unref (GVSB(builder)->children[i]); 2932 2933 g_free (GVSB(builder)->children); 2934 2935 if (GVSB(builder)->parent) 2936 { 2937 g_variant_builder_clear (GVSB(builder)->parent); 2938 g_slice_free (GVariantBuilder, GVSB(builder)->parent); 2939 } 2940 2941 memset (builder, 0, sizeof (GVariantBuilder)); 2942 } 2943 2944 /** 2945 * g_variant_builder_init: (skip) 2946 * @builder: a #GVariantBuilder 2947 * @type: a container type 2948 * 2949 * Initialises a #GVariantBuilder structure. 2950 * 2951 * @type must be non-%NULL. It specifies the type of container to 2952 * construct. It can be an indefinite type such as 2953 * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)". 2954 * Maybe, array, tuple, dictionary entry and variant-typed values may be 2955 * constructed. 2956 * 2957 * After the builder is initialised, values are added using 2958 * g_variant_builder_add_value() or g_variant_builder_add(). 2959 * 2960 * After all the child values are added, g_variant_builder_end() frees 2961 * the memory associated with the builder and returns the #GVariant that 2962 * was created. 2963 * 2964 * This function completely ignores the previous contents of @builder. 2965 * On one hand this means that it is valid to pass in completely 2966 * uninitialised memory. On the other hand, this means that if you are 2967 * initialising over top of an existing #GVariantBuilder you need to 2968 * first call g_variant_builder_clear() in order to avoid leaking 2969 * memory. 2970 * 2971 * You must not call g_variant_builder_ref() or 2972 * g_variant_builder_unref() on a #GVariantBuilder that was initialised 2973 * with this function. If you ever pass a reference to a 2974 * #GVariantBuilder outside of the control of your own code then you 2975 * should assume that the person receiving that reference may try to use 2976 * reference counting; you should use g_variant_builder_new() instead of 2977 * this function. 2978 * 2979 * Since: 2.24 2980 **/ 2981 void 2982 g_variant_builder_init (GVariantBuilder *builder, 2983 const GVariantType *type) 2984 { 2985 g_return_if_fail (type != NULL); 2986 g_return_if_fail (g_variant_type_is_container (type)); 2987 2988 memset (builder, 0, sizeof (GVariantBuilder)); 2989 2990 GVSB(builder)->type = g_variant_type_copy (type); 2991 GVSB(builder)->magic = GVSB_MAGIC; 2992 GVSB(builder)->trusted = TRUE; 2993 2994 switch (*(const gchar *) type) 2995 { 2996 case G_VARIANT_CLASS_VARIANT: 2997 GVSB(builder)->uniform_item_types = TRUE; 2998 GVSB(builder)->allocated_children = 1; 2999 GVSB(builder)->expected_type = NULL; 3000 GVSB(builder)->min_items = 1; 3001 GVSB(builder)->max_items = 1; 3002 break; 3003 3004 case G_VARIANT_CLASS_ARRAY: 3005 GVSB(builder)->uniform_item_types = TRUE; 3006 GVSB(builder)->allocated_children = 8; 3007 GVSB(builder)->expected_type = 3008 g_variant_type_element (GVSB(builder)->type); 3009 GVSB(builder)->min_items = 0; 3010 GVSB(builder)->max_items = -1; 3011 break; 3012 3013 case G_VARIANT_CLASS_MAYBE: 3014 GVSB(builder)->uniform_item_types = TRUE; 3015 GVSB(builder)->allocated_children = 1; 3016 GVSB(builder)->expected_type = 3017 g_variant_type_element (GVSB(builder)->type); 3018 GVSB(builder)->min_items = 0; 3019 GVSB(builder)->max_items = 1; 3020 break; 3021 3022 case G_VARIANT_CLASS_DICT_ENTRY: 3023 GVSB(builder)->uniform_item_types = FALSE; 3024 GVSB(builder)->allocated_children = 2; 3025 GVSB(builder)->expected_type = 3026 g_variant_type_key (GVSB(builder)->type); 3027 GVSB(builder)->min_items = 2; 3028 GVSB(builder)->max_items = 2; 3029 break; 3030 3031 case 'r': /* G_VARIANT_TYPE_TUPLE was given */ 3032 GVSB(builder)->uniform_item_types = FALSE; 3033 GVSB(builder)->allocated_children = 8; 3034 GVSB(builder)->expected_type = NULL; 3035 GVSB(builder)->min_items = 0; 3036 GVSB(builder)->max_items = -1; 3037 break; 3038 3039 case G_VARIANT_CLASS_TUPLE: /* a definite tuple type was given */ 3040 GVSB(builder)->allocated_children = g_variant_type_n_items (type); 3041 GVSB(builder)->expected_type = 3042 g_variant_type_first (GVSB(builder)->type); 3043 GVSB(builder)->min_items = GVSB(builder)->allocated_children; 3044 GVSB(builder)->max_items = GVSB(builder)->allocated_children; 3045 GVSB(builder)->uniform_item_types = FALSE; 3046 break; 3047 3048 default: 3049 g_assert_not_reached (); 3050 } 3051 3052 GVSB(builder)->children = g_new (GVariant *, 3053 GVSB(builder)->allocated_children); 3054 } 3055 3056 static void 3057 g_variant_builder_make_room (struct stack_builder *builder) 3058 { 3059 if (builder->offset == builder->allocated_children) 3060 { 3061 builder->allocated_children *= 2; 3062 builder->children = g_renew (GVariant *, builder->children, 3063 builder->allocated_children); 3064 } 3065 } 3066 3067 /** 3068 * g_variant_builder_add_value: 3069 * @builder: a #GVariantBuilder 3070 * @value: a #GVariant 3071 * 3072 * Adds @value to @builder. 3073 * 3074 * It is an error to call this function in any way that would create an 3075 * inconsistent value to be constructed. Some examples of this are 3076 * putting different types of items into an array, putting the wrong 3077 * types or number of items in a tuple, putting more than one value into 3078 * a variant, etc. 3079 * 3080 * If @value is a floating reference (see g_variant_ref_sink()), 3081 * the @builder instance takes ownership of @value. 3082 * 3083 * Since: 2.24 3084 **/ 3085 void 3086 g_variant_builder_add_value (GVariantBuilder *builder, 3087 GVariant *value) 3088 { 3089 g_return_if_fail (is_valid_builder (builder)); 3090 g_return_if_fail (GVSB(builder)->offset < GVSB(builder)->max_items); 3091 g_return_if_fail (!GVSB(builder)->expected_type || 3092 g_variant_is_of_type (value, 3093 GVSB(builder)->expected_type)); 3094 g_return_if_fail (!GVSB(builder)->prev_item_type || 3095 g_variant_is_of_type (value, 3096 GVSB(builder)->prev_item_type)); 3097 3098 GVSB(builder)->trusted &= g_variant_is_trusted (value); 3099 3100 if (!GVSB(builder)->uniform_item_types) 3101 { 3102 /* advance our expected type pointers */ 3103 if (GVSB(builder)->expected_type) 3104 GVSB(builder)->expected_type = 3105 g_variant_type_next (GVSB(builder)->expected_type); 3106 3107 if (GVSB(builder)->prev_item_type) 3108 GVSB(builder)->prev_item_type = 3109 g_variant_type_next (GVSB(builder)->prev_item_type); 3110 } 3111 else 3112 GVSB(builder)->prev_item_type = g_variant_get_type (value); 3113 3114 g_variant_builder_make_room (GVSB(builder)); 3115 3116 GVSB(builder)->children[GVSB(builder)->offset++] = 3117 g_variant_ref_sink (value); 3118 } 3119 3120 /** 3121 * g_variant_builder_open: 3122 * @builder: a #GVariantBuilder 3123 * @type: a #GVariantType 3124 * 3125 * Opens a subcontainer inside the given @builder. When done adding 3126 * items to the subcontainer, g_variant_builder_close() must be called. 3127 * 3128 * It is an error to call this function in any way that would cause an 3129 * inconsistent value to be constructed (ie: adding too many values or 3130 * a value of an incorrect type). 3131 * 3132 * Since: 2.24 3133 **/ 3134 void 3135 g_variant_builder_open (GVariantBuilder *builder, 3136 const GVariantType *type) 3137 { 3138 GVariantBuilder *parent; 3139 3140 g_return_if_fail (is_valid_builder (builder)); 3141 g_return_if_fail (GVSB(builder)->offset < GVSB(builder)->max_items); 3142 g_return_if_fail (!GVSB(builder)->expected_type || 3143 g_variant_type_is_subtype_of (type, 3144 GVSB(builder)->expected_type)); 3145 g_return_if_fail (!GVSB(builder)->prev_item_type || 3146 g_variant_type_is_subtype_of (GVSB(builder)->prev_item_type, 3147 type)); 3148 3149 parent = g_slice_dup (GVariantBuilder, builder); 3150 g_variant_builder_init (builder, type); 3151 GVSB(builder)->parent = parent; 3152 3153 /* push the prev_item_type down into the subcontainer */ 3154 if (GVSB(parent)->prev_item_type) 3155 { 3156 if (!GVSB(builder)->uniform_item_types) 3157 /* tuples and dict entries */ 3158 GVSB(builder)->prev_item_type = 3159 g_variant_type_first (GVSB(parent)->prev_item_type); 3160 3161 else if (!g_variant_type_is_variant (GVSB(builder)->type)) 3162 /* maybes and arrays */ 3163 GVSB(builder)->prev_item_type = 3164 g_variant_type_element (GVSB(parent)->prev_item_type); 3165 } 3166 } 3167 3168 /** 3169 * g_variant_builder_close: 3170 * @builder: a #GVariantBuilder 3171 * 3172 * Closes the subcontainer inside the given @builder that was opened by 3173 * the most recent call to g_variant_builder_open(). 3174 * 3175 * It is an error to call this function in any way that would create an 3176 * inconsistent value to be constructed (ie: too few values added to the 3177 * subcontainer). 3178 * 3179 * Since: 2.24 3180 **/ 3181 void 3182 g_variant_builder_close (GVariantBuilder *builder) 3183 { 3184 GVariantBuilder *parent; 3185 3186 g_return_if_fail (is_valid_builder (builder)); 3187 g_return_if_fail (GVSB(builder)->parent != NULL); 3188 3189 parent = GVSB(builder)->parent; 3190 GVSB(builder)->parent = NULL; 3191 3192 g_variant_builder_add_value (parent, g_variant_builder_end (builder)); 3193 *builder = *parent; 3194 3195 g_slice_free (GVariantBuilder, parent); 3196 } 3197 3198 /*< private > 3199 * g_variant_make_maybe_type: 3200 * @element: a #GVariant 3201 * 3202 * Return the type of a maybe containing @element. 3203 */ 3204 static GVariantType * 3205 g_variant_make_maybe_type (GVariant *element) 3206 { 3207 return g_variant_type_new_maybe (g_variant_get_type (element)); 3208 } 3209 3210 /*< private > 3211 * g_variant_make_array_type: 3212 * @element: a #GVariant 3213 * 3214 * Return the type of an array containing @element. 3215 */ 3216 static GVariantType * 3217 g_variant_make_array_type (GVariant *element) 3218 { 3219 return g_variant_type_new_array (g_variant_get_type (element)); 3220 } 3221 3222 /** 3223 * g_variant_builder_end: 3224 * @builder: a #GVariantBuilder 3225 * @returns: (transfer none): a new, floating, #GVariant 3226 * 3227 * Ends the builder process and returns the constructed value. 3228 * 3229 * It is not permissible to use @builder in any way after this call 3230 * except for reference counting operations (in the case of a 3231 * heap-allocated #GVariantBuilder) or by reinitialising it with 3232 * g_variant_builder_init() (in the case of stack-allocated). 3233 * 3234 * It is an error to call this function in any way that would create an 3235 * inconsistent value to be constructed (ie: insufficient number of 3236 * items added to a container with a specific number of children 3237 * required). It is also an error to call this function if the builder 3238 * was created with an indefinite array or maybe type and no children 3239 * have been added; in this case it is impossible to infer the type of 3240 * the empty array. 3241 * 3242 * Since: 2.24 3243 **/ 3244 GVariant * 3245 g_variant_builder_end (GVariantBuilder *builder) 3246 { 3247 GVariantType *my_type; 3248 GVariant *value; 3249 3250 g_return_val_if_fail (is_valid_builder (builder), NULL); 3251 g_return_val_if_fail (GVSB(builder)->offset >= GVSB(builder)->min_items, 3252 NULL); 3253 g_return_val_if_fail (!GVSB(builder)->uniform_item_types || 3254 GVSB(builder)->prev_item_type != NULL || 3255 g_variant_type_is_definite (GVSB(builder)->type), 3256 NULL); 3257 3258 if (g_variant_type_is_definite (GVSB(builder)->type)) 3259 my_type = g_variant_type_copy (GVSB(builder)->type); 3260 3261 else if (g_variant_type_is_maybe (GVSB(builder)->type)) 3262 my_type = g_variant_make_maybe_type (GVSB(builder)->children[0]); 3263 3264 else if (g_variant_type_is_array (GVSB(builder)->type)) 3265 my_type = g_variant_make_array_type (GVSB(builder)->children[0]); 3266 3267 else if (g_variant_type_is_tuple (GVSB(builder)->type)) 3268 my_type = g_variant_make_tuple_type (GVSB(builder)->children, 3269 GVSB(builder)->offset); 3270 3271 else if (g_variant_type_is_dict_entry (GVSB(builder)->type)) 3272 my_type = g_variant_make_dict_entry_type (GVSB(builder)->children[0], 3273 GVSB(builder)->children[1]); 3274 else 3275 g_assert_not_reached (); 3276 3277 value = g_variant_new_from_children (my_type, 3278 g_renew (GVariant *, 3279 GVSB(builder)->children, 3280 GVSB(builder)->offset), 3281 GVSB(builder)->offset, 3282 GVSB(builder)->trusted); 3283 GVSB(builder)->children = NULL; 3284 GVSB(builder)->offset = 0; 3285 3286 g_variant_builder_clear (builder); 3287 g_variant_type_free (my_type); 3288 3289 return value; 3290 } 3291 3292 /* Format strings {{{1 */ 3293 /*< private > 3294 * g_variant_format_string_scan: 3295 * @string: a string that may be prefixed with a format string 3296 * @limit: (allow-none) (default NULL): a pointer to the end of @string, 3297 * or %NULL 3298 * @endptr: (allow-none) (default NULL): location to store the end pointer, 3299 * or %NULL 3300 * @returns: %TRUE if there was a valid format string 3301 * 3302 * Checks the string pointed to by @string for starting with a properly 3303 * formed #GVariant varargs format string. If no valid format string is 3304 * found then %FALSE is returned. 3305 * 3306 * If @string does start with a valid format string then %TRUE is 3307 * returned. If @endptr is non-%NULL then it is updated to point to the 3308 * first character after the format string. 3309 * 3310 * If @limit is non-%NULL then @limit (and any charater after it) will 3311 * not be accessed and the effect is otherwise equivalent to if the 3312 * character at @limit were nul. 3313 * 3314 * See the section on <link linkend='gvariant-format-strings'>GVariant 3315 * Format Strings</link>. 3316 * 3317 * Since: 2.24 3318 */ 3319 gboolean 3320 g_variant_format_string_scan (const gchar *string, 3321 const gchar *limit, 3322 const gchar **endptr) 3323 { 3324 #define next_char() (string == limit ? '\0' : *string++) 3325 #define peek_char() (string == limit ? '\0' : *string) 3326 char c; 3327 3328 switch (next_char()) 3329 { 3330 case 'b': case 'y': case 'n': case 'q': case 'i': case 'u': 3331 case 'x': case 't': case 'h': case 'd': case 's': case 'o': 3332 case 'g': case 'v': case '*': case '?': case 'r': 3333 break; 3334 3335 case 'm': 3336 return g_variant_format_string_scan (string, limit, endptr); 3337 3338 case 'a': 3339 case '@': 3340 return g_variant_type_string_scan (string, limit, endptr); 3341 3342 case '(': 3343 while (peek_char() != ')') 3344 if (!g_variant_format_string_scan (string, limit, &string)) 3345 return FALSE; 3346 3347 next_char(); /* consume ')' */ 3348 break; 3349 3350 case '{': 3351 c = next_char(); 3352 3353 if (c == '&') 3354 { 3355 c = next_char (); 3356 3357 if (c != 's' && c != 'o' && c != 'g') 3358 return FALSE; 3359 } 3360 else 3361 { 3362 if (c == '@') 3363 c = next_char (); 3364 3365 /* ISO/IEC 9899:1999 (C99) §7.21.5.2: 3366 * The terminating null character is considered to be 3367 * part of the string. 3368 */ 3369 if (c != '\0' && strchr ("bynqiuxthdsog?", c) == NULL) 3370 return FALSE; 3371 } 3372 3373 if (!g_variant_format_string_scan (string, limit, &string)) 3374 return FALSE; 3375 3376 if (next_char() != '}') 3377 return FALSE; 3378 3379 break; 3380 3381 case '^': 3382 if ((c = next_char()) == 'a') 3383 { 3384 if ((c = next_char()) == '&') 3385 { 3386 if ((c = next_char()) == 'a') 3387 { 3388 if ((c = next_char()) == 'y') 3389 break; /* '^a&ay' */ 3390 } 3391 3392 else if (c == 's') 3393 break; /* '^a&s' */ 3394 } 3395 3396 else if (c == 'a') 3397 { 3398 if ((c = next_char()) == 'y') 3399 break; /* '^aay' */ 3400 } 3401 3402 else if (c == 's') 3403 break; /* '^as' */ 3404 3405 else if (c == 'y') 3406 break; /* '^ay' */ 3407 } 3408 else if (c == '&') 3409 { 3410 if ((c = next_char()) == 'a') 3411 { 3412 if ((c = next_char()) == 'y') 3413 break; /* '^&ay' */ 3414 } 3415 } 3416 3417 return FALSE; 3418 3419 case '&': 3420 c = next_char(); 3421 3422 if (c != 's' && c != 'o' && c != 'g') 3423 return FALSE; 3424 3425 break; 3426 3427 default: 3428 return FALSE; 3429 } 3430 3431 if (endptr != NULL) 3432 *endptr = string; 3433 3434 #undef next_char 3435 #undef peek_char 3436 3437 return TRUE; 3438 } 3439 3440 /*< private > 3441 * g_variant_format_string_scan_type: 3442 * @string: a string that may be prefixed with a format string 3443 * @limit: (allow-none) (default NULL): a pointer to the end of @string, 3444 * or %NULL 3445 * @endptr: (allow-none) (default NULL): location to store the end pointer, 3446 * or %NULL 3447 * @returns: (allow-none): a #GVariantType if there was a valid format string 3448 * 3449 * If @string starts with a valid format string then this function will 3450 * return the type that the format string corresponds to. Otherwise 3451 * this function returns %NULL. 3452 * 3453 * Use g_variant_type_free() to free the return value when you no longer 3454 * need it. 3455 * 3456 * This function is otherwise exactly like 3457 * g_variant_format_string_scan(). 3458 * 3459 * Since: 2.24 3460 */ 3461 GVariantType * 3462 g_variant_format_string_scan_type (const gchar *string, 3463 const gchar *limit, 3464 const gchar **endptr) 3465 { 3466 const gchar *my_end; 3467 gchar *dest; 3468 gchar *new; 3469 3470 if (endptr == NULL) 3471 endptr = &my_end; 3472 3473 if (!g_variant_format_string_scan (string, limit, endptr)) 3474 return NULL; 3475 3476 dest = new = g_malloc (*endptr - string + 1); 3477 while (string != *endptr) 3478 { 3479 if (*string != '@' && *string != '&' && *string != '^') 3480 *dest++ = *string; 3481 string++; 3482 } 3483 *dest = '\0'; 3484 3485 return (GVariantType *) G_VARIANT_TYPE (new); 3486 } 3487 3488 static gboolean 3489 valid_format_string (const gchar *format_string, 3490 gboolean single, 3491 GVariant *value) 3492 { 3493 const gchar *endptr; 3494 GVariantType *type; 3495 3496 type = g_variant_format_string_scan_type (format_string, NULL, &endptr); 3497 3498 if G_UNLIKELY (type == NULL || (single && *endptr != '\0')) 3499 { 3500 if (single) 3501 g_critical ("`%s' is not a valid GVariant format string", 3502 format_string); 3503 else 3504 g_critical ("`%s' does not have a valid GVariant format " 3505 "string as a prefix", format_string); 3506 3507 if (type != NULL) 3508 g_variant_type_free (type); 3509 3510 return FALSE; 3511 } 3512 3513 if G_UNLIKELY (value && !g_variant_is_of_type (value, type)) 3514 { 3515 gchar *fragment; 3516 gchar *typestr; 3517 3518 fragment = g_strndup (format_string, endptr - format_string); 3519 typestr = g_variant_type_dup_string (type); 3520 3521 g_critical ("the GVariant format string `%s' has a type of " 3522 "`%s' but the given value has a type of `%s'", 3523 fragment, typestr, g_variant_get_type_string (value)); 3524 3525 g_variant_type_free (type); 3526 3527 return FALSE; 3528 } 3529 3530 g_variant_type_free (type); 3531 3532 return TRUE; 3533 } 3534 3535 /* Variable Arguments {{{1 */ 3536 /* We consider 2 main classes of format strings: 3537 * 3538 * - recursive format strings 3539 * these are ones that result in recursion and the collection of 3540 * possibly more than one argument. Maybe types, tuples, 3541 * dictionary entries. 3542 * 3543 * - leaf format string 3544 * these result in the collection of a single argument. 3545 * 3546 * Leaf format strings are further subdivided into two categories: 3547 * 3548 * - single non-null pointer ("nnp") 3549 * these either collect or return a single non-null pointer. 3550 * 3551 * - other 3552 * these collect or return something else (bool, number, etc). 3553 * 3554 * Based on the above, the varargs handling code is split into 4 main parts: 3555 * 3556 * - nnp handling code 3557 * - leaf handling code (which may invoke nnp code) 3558 * - generic handling code (may be recursive, may invoke leaf code) 3559 * - user-facing API (which invokes the generic code) 3560 * 3561 * Each section implements some of the following functions: 3562 * 3563 * - skip: 3564 * collect the arguments for the format string as if 3565 * g_variant_new() had been called, but do nothing with them. used 3566 * for skipping over arguments when constructing a Nothing maybe 3567 * type. 3568 * 3569 * - new: 3570 * create a GVariant * 3571 * 3572 * - get: 3573 * unpack a GVariant * 3574 * 3575 * - free (nnp only): 3576 * free a previously allocated item 3577 */ 3578 3579 static gboolean 3580 g_variant_format_string_is_leaf (const gchar *str) 3581 { 3582 return str[0] != 'm' && str[0] != '(' && str[0] != '{'; 3583 } 3584 3585 static gboolean 3586 g_variant_format_string_is_nnp (const gchar *str) 3587 { 3588 return str[0] == 'a' || str[0] == 's' || str[0] == 'o' || str[0] == 'g' || 3589 str[0] == '^' || str[0] == '@' || str[0] == '*' || str[0] == '?' || 3590 str[0] == 'r' || str[0] == 'v' || str[0] == '&'; 3591 } 3592 3593 /* Single non-null pointer ("nnp") {{{2 */ 3594 static void 3595 g_variant_valist_free_nnp (const gchar *str, 3596 gpointer ptr) 3597 { 3598 switch (*str) 3599 { 3600 case 'a': 3601 g_variant_iter_free (ptr); 3602 break; 3603 3604 case '^': 3605 if (str[2] != '&') /* '^as' */ 3606 g_strfreev (ptr); 3607 else /* '^a&s' */ 3608 g_free (ptr); 3609 break; 3610 3611 case 's': 3612 case 'o': 3613 case 'g': 3614 g_free (ptr); 3615 break; 3616 3617 case '@': 3618 case '*': 3619 case '?': 3620 case 'v': 3621 g_variant_unref (ptr); 3622 break; 3623 3624 case '&': 3625 break; 3626 3627 default: 3628 g_assert_not_reached (); 3629 } 3630 } 3631 3632 static gchar 3633 g_variant_scan_convenience (const gchar **str, 3634 gboolean *constant, 3635 guint *arrays) 3636 { 3637 *constant = FALSE; 3638 *arrays = 0; 3639 3640 for (;;) 3641 { 3642 char c = *(*str)++; 3643 3644 if (c == '&') 3645 *constant = TRUE; 3646 3647 else if (c == 'a') 3648 (*arrays)++; 3649 3650 else 3651 return c; 3652 } 3653 } 3654 3655 static GVariant * 3656 g_variant_valist_new_nnp (const gchar **str, 3657 gpointer ptr) 3658 { 3659 if (**str == '&') 3660 (*str)++; 3661 3662 switch (*(*str)++) 3663 { 3664 case 'a': 3665 if (ptr != NULL) 3666 { 3667 const GVariantType *type; 3668 GVariant *value; 3669 3670 value = g_variant_builder_end (ptr); 3671 type = g_variant_get_type (value); 3672 3673 if G_UNLIKELY (!g_variant_type_is_array (type)) 3674 g_error ("g_variant_new: expected array GVariantBuilder but " 3675 "the built value has type `%s'", 3676 g_variant_get_type_string (value)); 3677 3678 type = g_variant_type_element (type); 3679 3680 if G_UNLIKELY (!g_variant_type_is_subtype_of (type, (GVariantType *) *str)) 3681 g_error ("g_variant_new: expected GVariantBuilder array element " 3682 "type `%s' but the built value has element type `%s'", 3683 g_variant_type_dup_string ((GVariantType *) *str), 3684 g_variant_get_type_string (value) + 1); 3685 3686 g_variant_type_string_scan (*str, NULL, str); 3687 3688 return value; 3689 } 3690 else 3691 3692 /* special case: NULL pointer for empty array */ 3693 { 3694 const GVariantType *type = (GVariantType *) *str; 3695 3696 g_variant_type_string_scan (*str, NULL, str); 3697 3698 if G_UNLIKELY (!g_variant_type_is_definite (type)) 3699 g_error ("g_variant_new: NULL pointer given with indefinite " 3700 "array type; unable to determine which type of empty " 3701 "array to construct."); 3702 3703 return g_variant_new_array (type, NULL, 0); 3704 } 3705 3706 case 's': 3707 { 3708 GVariant *value; 3709 3710 value = g_variant_new_string (ptr); 3711 3712 if (value == NULL) 3713 value = g_variant_new_string ("[Invalid UTF-8]"); 3714 3715 return value; 3716 } 3717 3718 case 'o': 3719 return g_variant_new_object_path (ptr); 3720 3721 case 'g': 3722 return g_variant_new_signature (ptr); 3723 3724 case '^': 3725 { 3726 gboolean constant; 3727 guint arrays; 3728 3729 if (g_variant_scan_convenience (str, &constant, &arrays) == 's') 3730 return g_variant_new_strv (ptr, -1); 3731 3732 if (arrays > 1) 3733 return g_variant_new_bytestring_array (ptr, -1); 3734 3735 return g_variant_new_bytestring (ptr); 3736 } 3737 3738 case '@': 3739 if G_UNLIKELY (!g_variant_is_of_type (ptr, (GVariantType *) *str)) 3740 g_error ("g_variant_new: expected GVariant of type `%s' but " 3741 "received value has type `%s'", 3742 g_variant_type_dup_string ((GVariantType *) *str), 3743 g_variant_get_type_string (ptr)); 3744 3745 g_variant_type_string_scan (*str, NULL, str); 3746 3747 return ptr; 3748 3749 case '*': 3750 return ptr; 3751 3752 case '?': 3753 if G_UNLIKELY (!g_variant_type_is_basic (g_variant_get_type (ptr))) 3754 g_error ("g_variant_new: format string `?' expects basic-typed " 3755 "GVariant, but received value has type `%s'", 3756 g_variant_get_type_string (ptr)); 3757 3758 return ptr; 3759 3760 case 'r': 3761 if G_UNLIKELY (!g_variant_type_is_tuple (g_variant_get_type (ptr))) 3762 g_error ("g_variant_new: format string `r` expects tuple-typed " 3763 "GVariant, but received value has type `%s'", 3764 g_variant_get_type_string (ptr)); 3765 3766 return ptr; 3767 3768 case 'v': 3769 return g_variant_new_variant (ptr); 3770 3771 default: 3772 g_assert_not_reached (); 3773 } 3774 } 3775 3776 static gpointer 3777 g_variant_valist_get_nnp (const gchar **str, 3778 GVariant *value) 3779 { 3780 switch (*(*str)++) 3781 { 3782 case 'a': 3783 g_variant_type_string_scan (*str, NULL, str); 3784 return g_variant_iter_new (value); 3785 3786 case '&': 3787 (*str)++; 3788 return (gchar *) g_variant_get_string (value, NULL); 3789 3790 case 's': 3791 case 'o': 3792 case 'g': 3793 return g_variant_dup_string (value, NULL); 3794 3795 case '^': 3796 { 3797 gboolean constant; 3798 guint arrays; 3799 3800 if (g_variant_scan_convenience (str, &constant, &arrays) == 's') 3801 { 3802 if (constant) 3803 return g_variant_get_strv (value, NULL); 3804 else 3805 return g_variant_dup_strv (value, NULL); 3806 } 3807 3808 else if (arrays > 1) 3809 { 3810 if (constant) 3811 return g_variant_get_bytestring_array (value, NULL); 3812 else 3813 return g_variant_dup_bytestring_array (value, NULL); 3814 } 3815 3816 else 3817 { 3818 if (constant) 3819 return (gchar *) g_variant_get_bytestring (value); 3820 else 3821 return g_variant_dup_bytestring (value, NULL); 3822 } 3823 } 3824 3825 case '@': 3826 g_variant_type_string_scan (*str, NULL, str); 3827 /* fall through */ 3828 3829 case '*': 3830 case '?': 3831 case 'r': 3832 return g_variant_ref (value); 3833 3834 case 'v': 3835 return g_variant_get_variant (value); 3836 3837 default: 3838 g_assert_not_reached (); 3839 } 3840 } 3841 3842 /* Leaves {{{2 */ 3843 static void 3844 g_variant_valist_skip_leaf (const gchar **str, 3845 va_list *app) 3846 { 3847 if (g_variant_format_string_is_nnp (*str)) 3848 { 3849 g_variant_format_string_scan (*str, NULL, str); 3850 va_arg (*app, gpointer); 3851 return; 3852 } 3853 3854 switch (*(*str)++) 3855 { 3856 case 'b': 3857 case 'y': 3858 case 'n': 3859 case 'q': 3860 case 'i': 3861 case 'u': 3862 case 'h': 3863 va_arg (*app, int); 3864 return; 3865 3866 case 'x': 3867 case 't': 3868 va_arg (*app, guint64); 3869 return; 3870 3871 case 'd': 3872 va_arg (*app, gdouble); 3873 return; 3874 3875 default: 3876 g_assert_not_reached (); 3877 } 3878 } 3879 3880 static GVariant * 3881 g_variant_valist_new_leaf (const gchar **str, 3882 va_list *app) 3883 { 3884 if (g_variant_format_string_is_nnp (*str)) 3885 return g_variant_valist_new_nnp (str, va_arg (*app, gpointer)); 3886 3887 switch (*(*str)++) 3888 { 3889 case 'b': 3890 return g_variant_new_boolean (va_arg (*app, gboolean)); 3891 3892 case 'y': 3893 return g_variant_new_byte (va_arg (*app, guint)); 3894 3895 case 'n': 3896 return g_variant_new_int16 (va_arg (*app, gint)); 3897 3898 case 'q': 3899 return g_variant_new_uint16 (va_arg (*app, guint)); 3900 3901 case 'i': 3902 return g_variant_new_int32 (va_arg (*app, gint)); 3903 3904 case 'u': 3905 return g_variant_new_uint32 (va_arg (*app, guint)); 3906 3907 case 'x': 3908 return g_variant_new_int64 (va_arg (*app, gint64)); 3909 3910 case 't': 3911 return g_variant_new_uint64 (va_arg (*app, guint64)); 3912 3913 case 'h': 3914 return g_variant_new_handle (va_arg (*app, gint)); 3915 3916 case 'd': 3917 return g_variant_new_double (va_arg (*app, gdouble)); 3918 3919 default: 3920 g_assert_not_reached (); 3921 } 3922 } 3923 3924 /* The code below assumes this */ 3925 G_STATIC_ASSERT (sizeof (gboolean) == sizeof (guint32)); 3926 G_STATIC_ASSERT (sizeof (gdouble) == sizeof (guint64)); 3927 3928 static void 3929 g_variant_valist_get_leaf (const gchar **str, 3930 GVariant *value, 3931 gboolean free, 3932 va_list *app) 3933 { 3934 gpointer ptr = va_arg (*app, gpointer); 3935 3936 if (ptr == NULL) 3937 { 3938 g_variant_format_string_scan (*str, NULL, str); 3939 return; 3940 } 3941 3942 if (g_variant_format_string_is_nnp (*str)) 3943 { 3944 gpointer *nnp = (gpointer *) ptr; 3945 3946 if (free && *nnp != NULL) 3947 g_variant_valist_free_nnp (*str, *nnp); 3948 3949 *nnp = NULL; 3950 3951 if (value != NULL) 3952 *nnp = g_variant_valist_get_nnp (str, value); 3953 else 3954 g_variant_format_string_scan (*str, NULL, str); 3955 3956 return; 3957 } 3958 3959 if (value != NULL) 3960 { 3961 switch (*(*str)++) 3962 { 3963 case 'b': 3964 *(gboolean *) ptr = g_variant_get_boolean (value); 3965 return; 3966 3967 case 'y': 3968 *(guchar *) ptr = g_variant_get_byte (value); 3969 return; 3970 3971 case 'n': 3972 *(gint16 *) ptr = g_variant_get_int16 (value); 3973 return; 3974 3975 case 'q': 3976 *(guint16 *) ptr = g_variant_get_uint16 (value); 3977 return; 3978 3979 case 'i': 3980 *(gint32 *) ptr = g_variant_get_int32 (value); 3981 return; 3982 3983 case 'u': 3984 *(guint32 *) ptr = g_variant_get_uint32 (value); 3985 return; 3986 3987 case 'x': 3988 *(gint64 *) ptr = g_variant_get_int64 (value); 3989 return; 3990 3991 case 't': 3992 *(guint64 *) ptr = g_variant_get_uint64 (value); 3993 return; 3994 3995 case 'h': 3996 *(gint32 *) ptr = g_variant_get_handle (value); 3997 return; 3998 3999 case 'd': 4000 *(gdouble *) ptr = g_variant_get_double (value); 4001 return; 4002 } 4003 } 4004 else 4005 { 4006 switch (*(*str)++) 4007 { 4008 case 'y': 4009 *(guchar *) ptr = 0; 4010 return; 4011 4012 case 'n': 4013 case 'q': 4014 *(guint16 *) ptr = 0; 4015 return; 4016 4017 case 'i': 4018 case 'u': 4019 case 'h': 4020 case 'b': 4021 *(guint32 *) ptr = 0; 4022 return; 4023 4024 case 'x': 4025 case 't': 4026 case 'd': 4027 *(guint64 *) ptr = 0; 4028 return; 4029 } 4030 } 4031 4032 g_assert_not_reached (); 4033 } 4034 4035 /* Generic (recursive) {{{2 */ 4036 static void 4037 g_variant_valist_skip (const gchar **str, 4038 va_list *app) 4039 { 4040 if (g_variant_format_string_is_leaf (*str)) 4041 g_variant_valist_skip_leaf (str, app); 4042 4043 else if (**str == 'm') /* maybe */ 4044 { 4045 (*str)++; 4046 4047 if (!g_variant_format_string_is_nnp (*str)) 4048 va_arg (*app, gboolean); 4049 4050 g_variant_valist_skip (str, app); 4051 } 4052 else /* tuple, dictionary entry */ 4053 { 4054 g_assert (**str == '(' || **str == '{'); 4055 (*str)++; 4056 while (**str != ')' && **str != '}') 4057 g_variant_valist_skip (str, app); 4058 (*str)++; 4059 } 4060 } 4061 4062 static GVariant * 4063 g_variant_valist_new (const gchar **str, 4064 va_list *app) 4065 { 4066 if (g_variant_format_string_is_leaf (*str)) 4067 return g_variant_valist_new_leaf (str, app); 4068 4069 if (**str == 'm') /* maybe */ 4070 { 4071 GVariantType *type = NULL; 4072 GVariant *value = NULL; 4073 4074 (*str)++; 4075 4076 if (g_variant_format_string_is_nnp (*str)) 4077 { 4078 gpointer nnp = va_arg (*app, gpointer); 4079 4080 if (nnp != NULL) 4081 value = g_variant_valist_new_nnp (str, nnp); 4082 else 4083 type = g_variant_format_string_scan_type (*str, NULL, str); 4084 } 4085 else 4086 { 4087 gboolean just = va_arg (*app, gboolean); 4088 4089 if (just) 4090 value = g_variant_valist_new (str, app); 4091 else 4092 { 4093 type = g_variant_format_string_scan_type (*str, NULL, NULL); 4094 g_variant_valist_skip (str, app); 4095 } 4096 } 4097 4098 value = g_variant_new_maybe (type, value); 4099 4100 if (type != NULL) 4101 g_variant_type_free (type); 4102 4103 return value; 4104 } 4105 else /* tuple, dictionary entry */ 4106 { 4107 GVariantBuilder b; 4108 4109 if (**str == '(') 4110 g_variant_builder_init (&b, G_VARIANT_TYPE_TUPLE); 4111 else 4112 { 4113 g_assert (**str == '{'); 4114 g_variant_builder_init (&b, G_VARIANT_TYPE_DICT_ENTRY); 4115 } 4116 4117 (*str)++; /* '(' */ 4118 while (**str != ')' && **str != '}') 4119 g_variant_builder_add_value (&b, g_variant_valist_new (str, app)); 4120 (*str)++; /* ')' */ 4121 4122 return g_variant_builder_end (&b); 4123 } 4124 } 4125 4126 static void 4127 g_variant_valist_get (const gchar **str, 4128 GVariant *value, 4129 gboolean free, 4130 va_list *app) 4131 { 4132 if (g_variant_format_string_is_leaf (*str)) 4133 g_variant_valist_get_leaf (str, value, free, app); 4134 4135 else if (**str == 'm') 4136 { 4137 (*str)++; 4138 4139 if (value != NULL) 4140 value = g_variant_get_maybe (value); 4141 4142 if (!g_variant_format_string_is_nnp (*str)) 4143 { 4144 gboolean *ptr = va_arg (*app, gboolean *); 4145 4146 if (ptr != NULL) 4147 *ptr = value != NULL; 4148 } 4149 4150 g_variant_valist_get (str, value, free, app); 4151 4152 if (value != NULL) 4153 g_variant_unref (value); 4154 } 4155 4156 else /* tuple, dictionary entry */ 4157 { 4158 gint index = 0; 4159 4160 g_assert (**str == '(' || **str == '{'); 4161 4162 (*str)++; 4163 while (**str != ')' && **str != '}') 4164 { 4165 if (value != NULL) 4166 { 4167 GVariant *child = g_variant_get_child_value (value, index++); 4168 g_variant_valist_get (str, child, free, app); 4169 g_variant_unref (child); 4170 } 4171 else 4172 g_variant_valist_get (str, NULL, free, app); 4173 } 4174 (*str)++; 4175 } 4176 } 4177 4178 /* User-facing API {{{2 */ 4179 /** 4180 * g_variant_new: (skip) 4181 * @format_string: a #GVariant format string 4182 * @...: arguments, as per @format_string 4183 * @returns: a new floating #GVariant instance 4184 * 4185 * Creates a new #GVariant instance. 4186 * 4187 * Think of this function as an analogue to g_strdup_printf(). 4188 * 4189 * The type of the created instance and the arguments that are 4190 * expected by this function are determined by @format_string. See the 4191 * section on <link linkend='gvariant-format-strings'>GVariant Format 4192 * Strings</link>. Please note that the syntax of the format string is 4193 * very likely to be extended in the future. 4194 * 4195 * The first character of the format string must not be '*' '?' '@' or 4196 * 'r'; in essence, a new #GVariant must always be constructed by this 4197 * function (and not merely passed through it unmodified). 4198 * 4199 * Since: 2.24 4200 **/ 4201 GVariant * 4202 g_variant_new (const gchar *format_string, 4203 ...) 4204 { 4205 GVariant *value; 4206 va_list ap; 4207 4208 g_return_val_if_fail (valid_format_string (format_string, TRUE, NULL) && 4209 format_string[0] != '?' && format_string[0] != '@' && 4210 format_string[0] != '*' && format_string[0] != 'r', 4211 NULL); 4212 4213 va_start (ap, format_string); 4214 value = g_variant_new_va (format_string, NULL, &ap); 4215 va_end (ap); 4216 4217 return value; 4218 } 4219 4220 /** 4221 * g_variant_new_va: (skip) 4222 * @format_string: a string that is prefixed with a format string 4223 * @endptr: (allow-none) (default NULL): location to store the end pointer, 4224 * or %NULL 4225 * @app: a pointer to a #va_list 4226 * @returns: a new, usually floating, #GVariant 4227 * 4228 * This function is intended to be used by libraries based on 4229 * #GVariant that want to provide g_variant_new()-like functionality 4230 * to their users. 4231 * 4232 * The API is more general than g_variant_new() to allow a wider range 4233 * of possible uses. 4234 * 4235 * @format_string must still point to a valid format string, but it only 4236 * needs to be nul-terminated if @endptr is %NULL. If @endptr is 4237 * non-%NULL then it is updated to point to the first character past the 4238 * end of the format string. 4239 * 4240 * @app is a pointer to a #va_list. The arguments, according to 4241 * @format_string, are collected from this #va_list and the list is left 4242 * pointing to the argument following the last. 4243 * 4244 * These two generalisations allow mixing of multiple calls to 4245 * g_variant_new_va() and g_variant_get_va() within a single actual 4246 * varargs call by the user. 4247 * 4248 * The return value will be floating if it was a newly created GVariant 4249 * instance (for example, if the format string was "(ii)"). In the case 4250 * that the format_string was '*', '?', 'r', or a format starting with 4251 * '@' then the collected #GVariant pointer will be returned unmodified, 4252 * without adding any additional references. 4253 * 4254 * In order to behave correctly in all cases it is necessary for the 4255 * calling function to g_variant_ref_sink() the return result before 4256 * returning control to the user that originally provided the pointer. 4257 * At this point, the caller will have their own full reference to the 4258 * result. This can also be done by adding the result to a container, 4259 * or by passing it to another g_variant_new() call. 4260 * 4261 * Since: 2.24 4262 **/ 4263 GVariant * 4264 g_variant_new_va (const gchar *format_string, 4265 const gchar **endptr, 4266 va_list *app) 4267 { 4268 GVariant *value; 4269 4270 g_return_val_if_fail (valid_format_string (format_string, !endptr, NULL), 4271 NULL); 4272 g_return_val_if_fail (app != NULL, NULL); 4273 4274 value = g_variant_valist_new (&format_string, app); 4275 4276 if (endptr != NULL) 4277 *endptr = format_string; 4278 4279 return value; 4280 } 4281 4282 /** 4283 * g_variant_get: (skip) 4284 * @value: a #GVariant instance 4285 * @format_string: a #GVariant format string 4286 * @...: arguments, as per @format_string 4287 * 4288 * Deconstructs a #GVariant instance. 4289 * 4290 * Think of this function as an analogue to scanf(). 4291 * 4292 * The arguments that are expected by this function are entirely 4293 * determined by @format_string. @format_string also restricts the 4294 * permissible types of @value. It is an error to give a value with 4295 * an incompatible type. See the section on <link 4296 * linkend='gvariant-format-strings'>GVariant Format Strings</link>. 4297 * Please note that the syntax of the format string is very likely to be 4298 * extended in the future. 4299 * 4300 * Since: 2.24 4301 **/ 4302 void 4303 g_variant_get (GVariant *value, 4304 const gchar *format_string, 4305 ...) 4306 { 4307 va_list ap; 4308 4309 g_return_if_fail (valid_format_string (format_string, TRUE, value)); 4310 4311 /* if any direct-pointer-access formats are in use, flatten first */ 4312 if (strchr (format_string, '&')) 4313 g_variant_get_data (value); 4314 4315 va_start (ap, format_string); 4316 g_variant_get_va (value, format_string, NULL, &ap); 4317 va_end (ap); 4318 } 4319 4320 /** 4321 * g_variant_get_va: (skip) 4322 * @value: a #GVariant 4323 * @format_string: a string that is prefixed with a format string 4324 * @endptr: (allow-none) (default NULL): location to store the end pointer, 4325 * or %NULL 4326 * @app: a pointer to a #va_list 4327 * 4328 * This function is intended to be used by libraries based on #GVariant 4329 * that want to provide g_variant_get()-like functionality to their 4330 * users. 4331 * 4332 * The API is more general than g_variant_get() to allow a wider range 4333 * of possible uses. 4334 * 4335 * @format_string must still point to a valid format string, but it only 4336 * need to be nul-terminated if @endptr is %NULL. If @endptr is 4337 * non-%NULL then it is updated to point to the first character past the 4338 * end of the format string. 4339 * 4340 * @app is a pointer to a #va_list. The arguments, according to 4341 * @format_string, are collected from this #va_list and the list is left 4342 * pointing to the argument following the last. 4343 * 4344 * These two generalisations allow mixing of multiple calls to 4345 * g_variant_new_va() and g_variant_get_va() within a single actual 4346 * varargs call by the user. 4347 * 4348 * Since: 2.24 4349 **/ 4350 void 4351 g_variant_get_va (GVariant *value, 4352 const gchar *format_string, 4353 const gchar **endptr, 4354 va_list *app) 4355 { 4356 g_return_if_fail (valid_format_string (format_string, !endptr, value)); 4357 g_return_if_fail (value != NULL); 4358 g_return_if_fail (app != NULL); 4359 4360 /* if any direct-pointer-access formats are in use, flatten first */ 4361 if (strchr (format_string, '&')) 4362 g_variant_get_data (value); 4363 4364 g_variant_valist_get (&format_string, value, FALSE, app); 4365 4366 if (endptr != NULL) 4367 *endptr = format_string; 4368 } 4369 4370 /* Varargs-enabled Utility Functions {{{1 */ 4371 4372 /** 4373 * g_variant_builder_add: (skp) 4374 * @builder: a #GVariantBuilder 4375 * @format_string: a #GVariant varargs format string 4376 * @...: arguments, as per @format_string 4377 * 4378 * Adds to a #GVariantBuilder. 4379 * 4380 * This call is a convenience wrapper that is exactly equivalent to 4381 * calling g_variant_new() followed by g_variant_builder_add_value(). 4382 * 4383 * This function might be used as follows: 4384 * 4385 * <programlisting> 4386 * GVariant * 4387 * make_pointless_dictionary (void) 4388 * { 4389 * GVariantBuilder *builder; 4390 * int i; 4391 * 4392 * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY); 4393 * for (i = 0; i < 16; i++) 4394 * { 4395 * gchar buf[3]; 4396 * 4397 * sprintf (buf, "%d", i); 4398 * g_variant_builder_add (builder, "{is}", i, buf); 4399 * } 4400 * 4401 * return g_variant_builder_end (builder); 4402 * } 4403 * </programlisting> 4404 * 4405 * Since: 2.24 4406 **/ 4407 void 4408 g_variant_builder_add (GVariantBuilder *builder, 4409 const gchar *format_string, 4410 ...) 4411 { 4412 GVariant *variant; 4413 va_list ap; 4414 4415 va_start (ap, format_string); 4416 variant = g_variant_new_va (format_string, NULL, &ap); 4417 va_end (ap); 4418 4419 g_variant_builder_add_value (builder, variant); 4420 } 4421 4422 /** 4423 * g_variant_get_child: (skip) 4424 * @value: a container #GVariant 4425 * @index_: the index of the child to deconstruct 4426 * @format_string: a #GVariant format string 4427 * @...: arguments, as per @format_string 4428 * 4429 * Reads a child item out of a container #GVariant instance and 4430 * deconstructs it according to @format_string. This call is 4431 * essentially a combination of g_variant_get_child_value() and 4432 * g_variant_get(). 4433 * 4434 * Since: 2.24 4435 **/ 4436 void 4437 g_variant_get_child (GVariant *value, 4438 gsize index_, 4439 const gchar *format_string, 4440 ...) 4441 { 4442 GVariant *child; 4443 va_list ap; 4444 4445 child = g_variant_get_child_value (value, index_); 4446 g_return_if_fail (valid_format_string (format_string, TRUE, child)); 4447 4448 va_start (ap, format_string); 4449 g_variant_get_va (child, format_string, NULL, &ap); 4450 va_end (ap); 4451 4452 g_variant_unref (child); 4453 } 4454 4455 /** 4456 * g_variant_iter_next: (skip) 4457 * @iter: a #GVariantIter 4458 * @format_string: a GVariant format string 4459 * @...: the arguments to unpack the value into 4460 * @returns: %TRUE if a value was unpacked, or %FALSE if there as no 4461 * value 4462 * 4463 * Gets the next item in the container and unpacks it into the variable 4464 * argument list according to @format_string, returning %TRUE. 4465 * 4466 * If no more items remain then %FALSE is returned. 4467 * 4468 * All of the pointers given on the variable arguments list of this 4469 * function are assumed to point at uninitialised memory. It is the 4470 * responsibility of the caller to free all of the values returned by 4471 * the unpacking process. 4472 * 4473 * See the section on <link linkend='gvariant-format-strings'>GVariant 4474 * Format Strings</link>. 4475 * 4476 * <example> 4477 * <title>Memory management with g_variant_iter_next()</title> 4478 * <programlisting> 4479 * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/ 4480 * void 4481 * iterate_dictionary (GVariant *dictionary) 4482 * { 4483 * GVariantIter iter; 4484 * GVariant *value; 4485 * gchar *key; 4486 * 4487 * g_variant_iter_init (&iter, dictionary); 4488 * while (g_variant_iter_next (&iter, "{sv}", &key, &value)) 4489 * { 4490 * g_print ("Item '%s' has type '%s'\n", key, 4491 * g_variant_get_type_string (value)); 4492 * 4493 * /<!-- -->* must free data for ourselves *<!-- -->/ 4494 * g_variant_unref (value); 4495 * g_free (key); 4496 * } 4497 * } 4498 * </programlisting> 4499 * </example> 4500 * 4501 * For a solution that is likely to be more convenient to C programmers 4502 * when dealing with loops, see g_variant_iter_loop(). 4503 * 4504 * Since: 2.24 4505 **/ 4506 gboolean 4507 g_variant_iter_next (GVariantIter *iter, 4508 const gchar *format_string, 4509 ...) 4510 { 4511 GVariant *value; 4512 4513 value = g_variant_iter_next_value (iter); 4514 4515 g_return_val_if_fail (valid_format_string (format_string, TRUE, value), 4516 FALSE); 4517 4518 if (value != NULL) 4519 { 4520 va_list ap; 4521 4522 va_start (ap, format_string); 4523 g_variant_valist_get (&format_string, value, FALSE, &ap); 4524 va_end (ap); 4525 4526 g_variant_unref (value); 4527 } 4528 4529 return value != NULL; 4530 } 4531 4532 /** 4533 * g_variant_iter_loop: (skip) 4534 * @iter: a #GVariantIter 4535 * @format_string: a GVariant format string 4536 * @...: the arguments to unpack the value into 4537 * @returns: %TRUE if a value was unpacked, or %FALSE if there as no 4538 * value 4539 * 4540 * Gets the next item in the container and unpacks it into the variable 4541 * argument list according to @format_string, returning %TRUE. 4542 * 4543 * If no more items remain then %FALSE is returned. 4544 * 4545 * On the first call to this function, the pointers appearing on the 4546 * variable argument list are assumed to point at uninitialised memory. 4547 * On the second and later calls, it is assumed that the same pointers 4548 * will be given and that they will point to the memory as set by the 4549 * previous call to this function. This allows the previous values to 4550 * be freed, as appropriate. 4551 * 4552 * This function is intended to be used with a while loop as 4553 * demonstrated in the following example. This function can only be 4554 * used when iterating over an array. It is only valid to call this 4555 * function with a string constant for the format string and the same 4556 * string constant must be used each time. Mixing calls to this 4557 * function and g_variant_iter_next() or g_variant_iter_next_value() on 4558 * the same iterator is not recommended. 4559 * 4560 * See the section on <link linkend='gvariant-format-strings'>GVariant 4561 * Format Strings</link>. 4562 * 4563 * <example> 4564 * <title>Memory management with g_variant_iter_loop()</title> 4565 * <programlisting> 4566 * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/ 4567 * void 4568 * iterate_dictionary (GVariant *dictionary) 4569 * { 4570 * GVariantIter iter; 4571 * GVariant *value; 4572 * gchar *key; 4573 * 4574 * g_variant_iter_init (&iter, dictionary); 4575 * while (g_variant_iter_loop (&iter, "{sv}", &key, &value)) 4576 * { 4577 * g_print ("Item '%s' has type '%s'\n", key, 4578 * g_variant_get_type_string (value)); 4579 * 4580 * /<!-- -->* no need to free 'key' and 'value' here *<!-- -->/ 4581 * } 4582 * } 4583 * </programlisting> 4584 * </example> 4585 * 4586 * If you want a slightly less magical alternative that requires more 4587 * typing, see g_variant_iter_next(). 4588 * 4589 * Since: 2.24 4590 **/ 4591 gboolean 4592 g_variant_iter_loop (GVariantIter *iter, 4593 const gchar *format_string, 4594 ...) 4595 { 4596 gboolean first_time = GVSI(iter)->loop_format == NULL; 4597 GVariant *value; 4598 va_list ap; 4599 4600 g_return_val_if_fail (first_time || 4601 format_string == GVSI(iter)->loop_format, 4602 FALSE); 4603 4604 if (first_time) 4605 { 4606 TYPE_CHECK (GVSI(iter)->value, G_VARIANT_TYPE_ARRAY, FALSE); 4607 GVSI(iter)->loop_format = format_string; 4608 4609 if (strchr (format_string, '&')) 4610 g_variant_get_data (GVSI(iter)->value); 4611 } 4612 4613 value = g_variant_iter_next_value (iter); 4614 4615 g_return_val_if_fail (!first_time || 4616 valid_format_string (format_string, TRUE, value), 4617 FALSE); 4618 4619 va_start (ap, format_string); 4620 g_variant_valist_get (&format_string, value, !first_time, &ap); 4621 va_end (ap); 4622 4623 if (value != NULL) 4624 g_variant_unref (value); 4625 4626 return value != NULL; 4627 } 4628 4629 /* Serialised data {{{1 */ 4630 static GVariant * 4631 g_variant_deep_copy (GVariant *value) 4632 { 4633 switch (g_variant_classify (value)) 4634 { 4635 case G_VARIANT_CLASS_MAYBE: 4636 case G_VARIANT_CLASS_ARRAY: 4637 case G_VARIANT_CLASS_TUPLE: 4638 case G_VARIANT_CLASS_DICT_ENTRY: 4639 case G_VARIANT_CLASS_VARIANT: 4640 { 4641 GVariantBuilder builder; 4642 GVariantIter iter; 4643 GVariant *child; 4644 4645 g_variant_builder_init (&builder, g_variant_get_type (value)); 4646 g_variant_iter_init (&iter, value); 4647 4648 while ((child = g_variant_iter_next_value (&iter))) 4649 { 4650 g_variant_builder_add_value (&builder, g_variant_deep_copy (child)); 4651 g_variant_unref (child); 4652 } 4653 4654 return g_variant_builder_end (&builder); 4655 } 4656 4657 case G_VARIANT_CLASS_BOOLEAN: 4658 return g_variant_new_boolean (g_variant_get_boolean (value)); 4659 4660 case G_VARIANT_CLASS_BYTE: 4661 return g_variant_new_byte (g_variant_get_byte (value)); 4662 4663 case G_VARIANT_CLASS_INT16: 4664 return g_variant_new_int16 (g_variant_get_int16 (value)); 4665 4666 case G_VARIANT_CLASS_UINT16: 4667 return g_variant_new_uint16 (g_variant_get_uint16 (value)); 4668 4669 case G_VARIANT_CLASS_INT32: 4670 return g_variant_new_int32 (g_variant_get_int32 (value)); 4671 4672 case G_VARIANT_CLASS_UINT32: 4673 return g_variant_new_uint32 (g_variant_get_uint32 (value)); 4674 4675 case G_VARIANT_CLASS_INT64: 4676 return g_variant_new_int64 (g_variant_get_int64 (value)); 4677 4678 case G_VARIANT_CLASS_UINT64: 4679 return g_variant_new_uint64 (g_variant_get_uint64 (value)); 4680 4681 case G_VARIANT_CLASS_HANDLE: 4682 return g_variant_new_handle (g_variant_get_handle (value)); 4683 4684 case G_VARIANT_CLASS_DOUBLE: 4685 return g_variant_new_double (g_variant_get_double (value)); 4686 4687 case G_VARIANT_CLASS_STRING: 4688 return g_variant_new_string (g_variant_get_string (value, NULL)); 4689 4690 case G_VARIANT_CLASS_OBJECT_PATH: 4691 return g_variant_new_object_path (g_variant_get_string (value, NULL)); 4692 4693 case G_VARIANT_CLASS_SIGNATURE: 4694 return g_variant_new_signature (g_variant_get_string (value, NULL)); 4695 } 4696 4697 g_assert_not_reached (); 4698 } 4699 4700 /** 4701 * g_variant_get_normal_form: 4702 * @value: a #GVariant 4703 * @returns: (transfer full): a trusted #GVariant 4704 * 4705 * Gets a #GVariant instance that has the same value as @value and is 4706 * trusted to be in normal form. 4707 * 4708 * If @value is already trusted to be in normal form then a new 4709 * reference to @value is returned. 4710 * 4711 * If @value is not already trusted, then it is scanned to check if it 4712 * is in normal form. If it is found to be in normal form then it is 4713 * marked as trusted and a new reference to it is returned. 4714 * 4715 * If @value is found not to be in normal form then a new trusted 4716 * #GVariant is created with the same value as @value. 4717 * 4718 * It makes sense to call this function if you've received #GVariant 4719 * data from untrusted sources and you want to ensure your serialised 4720 * output is definitely in normal form. 4721 * 4722 * Since: 2.24 4723 **/ 4724 GVariant * 4725 g_variant_get_normal_form (GVariant *value) 4726 { 4727 GVariant *trusted; 4728 4729 if (g_variant_is_normal_form (value)) 4730 return g_variant_ref (value); 4731 4732 trusted = g_variant_deep_copy (value); 4733 g_assert (g_variant_is_trusted (trusted)); 4734 4735 return g_variant_ref_sink (trusted); 4736 } 4737 4738 /** 4739 * g_variant_byteswap: 4740 * @value: a #GVariant 4741 * @returns: (transfer full): the byteswapped form of @value 4742 * 4743 * Performs a byteswapping operation on the contents of @value. The 4744 * result is that all multi-byte numeric data contained in @value is 4745 * byteswapped. That includes 16, 32, and 64bit signed and unsigned 4746 * integers as well as file handles and double precision floating point 4747 * values. 4748 * 4749 * This function is an identity mapping on any value that does not 4750 * contain multi-byte numeric data. That include strings, booleans, 4751 * bytes and containers containing only these things (recursively). 4752 * 4753 * The returned value is always in normal form and is marked as trusted. 4754 * 4755 * Since: 2.24 4756 **/ 4757 GVariant * 4758 g_variant_byteswap (GVariant *value) 4759 { 4760 GVariantTypeInfo *type_info; 4761 guint alignment; 4762 GVariant *new; 4763 4764 type_info = g_variant_get_type_info (value); 4765 4766 g_variant_type_info_query (type_info, &alignment, NULL); 4767 4768 if (alignment) 4769 /* (potentially) contains multi-byte numeric data */ 4770 { 4771 GVariantSerialised serialised; 4772 GVariant *trusted; 4773 GBuffer *buffer; 4774 4775 trusted = g_variant_get_normal_form (value); 4776 serialised.type_info = g_variant_get_type_info (trusted); 4777 serialised.size = g_variant_get_size (trusted); 4778 serialised.data = g_malloc (serialised.size); 4779 g_variant_store (trusted, serialised.data); 4780 g_variant_unref (trusted); 4781 4782 g_variant_serialised_byteswap (serialised); 4783 4784 buffer = g_buffer_new_take_data (serialised.data, serialised.size); 4785 #ifdef GSTREAMER_LITE 4786 if (buffer == NULL) { 4787 return NULL; 4788 } 4789 #endif // GSTREAMER_LITE 4790 new = g_variant_new_from_buffer (g_variant_get_type (value), buffer, TRUE); 4791 g_buffer_unref (buffer); 4792 } 4793 else 4794 /* contains no multi-byte data */ 4795 new = value; 4796 4797 return g_variant_ref_sink (new); 4798 } 4799 4800 /** 4801 * g_variant_new_from_data: 4802 * @type: a definite #GVariantType 4803 * @data: (array length=size) (element-type guint8): the serialised data 4804 * @size: the size of @data 4805 * @trusted: %TRUE if @data is definitely in normal form 4806 * @notify: (scope async): function to call when @data is no longer needed 4807 * @user_data: data for @notify 4808 * @returns: (transfer none): a new floating #GVariant of type @type 4809 * 4810 * Creates a new #GVariant instance from serialised data. 4811 * 4812 * @type is the type of #GVariant instance that will be constructed. 4813 * The interpretation of @data depends on knowing the type. 4814 * 4815 * @data is not modified by this function and must remain valid with an 4816 * unchanging value until such a time as @notify is called with 4817 * @user_data. If the contents of @data change before that time then 4818 * the result is undefined. 4819 * 4820 * If @data is trusted to be serialised data in normal form then 4821 * @trusted should be %TRUE. This applies to serialised data created 4822 * within this process or read from a trusted location on the disk (such 4823 * as a file installed in /usr/lib alongside your application). You 4824 * should set trusted to %FALSE if @data is read from the network, a 4825 * file in the user's home directory, etc. 4826 * 4827 * @notify will be called with @user_data when @data is no longer 4828 * needed. The exact time of this call is unspecified and might even be 4829 * before this function returns. 4830 * 4831 * Since: 2.24 4832 **/ 4833 GVariant * 4834 g_variant_new_from_data (const GVariantType *type, 4835 gconstpointer data, 4836 gsize size, 4837 gboolean trusted, 4838 GDestroyNotify notify, 4839 gpointer user_data) 4840 { 4841 GVariant *value; 4842 GBuffer *buffer; 4843 4844 g_return_val_if_fail (g_variant_type_is_definite (type), NULL); 4845 g_return_val_if_fail (data != NULL || size == 0, NULL); 4846 4847 if (notify) 4848 buffer = g_buffer_new_from_pointer (data, size, notify, user_data); 4849 else 4850 buffer = g_buffer_new_from_static_data (data, size); 4851 4852 value = g_variant_new_from_buffer (type, buffer, trusted); 4853 g_buffer_unref (buffer); 4854 4855 return value; 4856 } 4857 4858 /* Epilogue {{{1 */ 4859 /* vim:set foldmethod=marker: */