1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD 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 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module glib.Variant; 26 27 private import glib.Bytes; 28 private import glib.ConstructionException; 29 private import glib.ErrorG; 30 private import glib.GException; 31 private import glib.Str; 32 private import glib.StringG; 33 private import glib.VariantIter; 34 private import glib.VariantType; 35 private import gtkc.glib; 36 public import gtkc.glibtypes; 37 38 39 /** 40 * #GVariant is a variant datatype; it stores a value along with 41 * information about the type of that value. The range of possible 42 * values is determined by the type. The type system used by #GVariant 43 * is #GVariantType. 44 * 45 * #GVariant instances always have a type and a value (which are given 46 * at construction time). The type and value of a #GVariant instance 47 * can never change other than by the #GVariant itself being 48 * destroyed. A #GVariant cannot contain a pointer. 49 * 50 * #GVariant is reference counted using g_variant_ref() and 51 * g_variant_unref(). #GVariant also has floating reference counts -- 52 * see g_variant_ref_sink(). 53 * 54 * #GVariant is completely threadsafe. A #GVariant instance can be 55 * concurrently accessed in any way from any number of threads without 56 * problems. 57 * 58 * #GVariant is heavily optimised for dealing with data in serialised 59 * form. It works particularly well with data located in memory-mapped 60 * files. It can perform nearly all deserialisation operations in a 61 * small constant time, usually touching only a single memory page. 62 * Serialised #GVariant data can also be sent over the network. 63 * 64 * #GVariant is largely compatible with D-Bus. Almost all types of 65 * #GVariant instances can be sent over D-Bus. See #GVariantType for 66 * exceptions. (However, #GVariant's serialisation format is not the same 67 * as the serialisation format of a D-Bus message body: use #GDBusMessage, 68 * in the gio library, for those.) 69 * 70 * For space-efficiency, the #GVariant serialisation format does not 71 * automatically include the variant's length, type or endianness, 72 * which must either be implied from context (such as knowledge that a 73 * particular file format always contains a little-endian 74 * %G_VARIANT_TYPE_VARIANT which occupies the whole length of the file) 75 * or supplied out-of-band (for instance, a length, type and/or endianness 76 * indicator could be placed at the beginning of a file, network message 77 * or network stream). 78 * 79 * A #GVariant's size is limited mainly by any lower level operating 80 * system constraints, such as the number of bits in #gsize. For 81 * example, it is reasonable to have a 2GB file mapped into memory 82 * with #GMappedFile, and call g_variant_new_from_data() on it. 83 * 84 * For convenience to C programmers, #GVariant features powerful 85 * varargs-based value construction and destruction. This feature is 86 * designed to be embedded in other libraries. 87 * 88 * There is a Python-inspired text language for describing #GVariant 89 * values. #GVariant includes a printer for this language and a parser 90 * with type inferencing. 91 * 92 * ## Memory Use 93 * 94 * #GVariant tries to be quite efficient with respect to memory use. 95 * This section gives a rough idea of how much memory is used by the 96 * current implementation. The information here is subject to change 97 * in the future. 98 * 99 * The memory allocated by #GVariant can be grouped into 4 broad 100 * purposes: memory for serialised data, memory for the type 101 * information cache, buffer management memory and memory for the 102 * #GVariant structure itself. 103 * 104 * ## Serialised Data Memory 105 * 106 * This is the memory that is used for storing GVariant data in 107 * serialised form. This is what would be sent over the network or 108 * what would end up on disk, not counting any indicator of the 109 * endianness, or of the length or type of the top-level variant. 110 * 111 * The amount of memory required to store a boolean is 1 byte. 16, 112 * 32 and 64 bit integers and double precision floating point numbers 113 * use their "natural" size. Strings (including object path and 114 * signature strings) are stored with a nul terminator, and as such 115 * use the length of the string plus 1 byte. 116 * 117 * Maybe types use no space at all to represent the null value and 118 * use the same amount of space (sometimes plus one byte) as the 119 * equivalent non-maybe-typed value to represent the non-null case. 120 * 121 * Arrays use the amount of space required to store each of their 122 * members, concatenated. Additionally, if the items stored in an 123 * array are not of a fixed-size (ie: strings, other arrays, etc) 124 * then an additional framing offset is stored for each item. The 125 * size of this offset is either 1, 2 or 4 bytes depending on the 126 * overall size of the container. Additionally, extra padding bytes 127 * are added as required for alignment of child values. 128 * 129 * Tuples (including dictionary entries) use the amount of space 130 * required to store each of their members, concatenated, plus one 131 * framing offset (as per arrays) for each non-fixed-sized item in 132 * the tuple, except for the last one. Additionally, extra padding 133 * bytes are added as required for alignment of child values. 134 * 135 * Variants use the same amount of space as the item inside of the 136 * variant, plus 1 byte, plus the length of the type string for the 137 * item inside the variant. 138 * 139 * As an example, consider a dictionary mapping strings to variants. 140 * In the case that the dictionary is empty, 0 bytes are required for 141 * the serialisation. 142 * 143 * If we add an item "width" that maps to the int32 value of 500 then 144 * we will use 4 byte to store the int32 (so 6 for the variant 145 * containing it) and 6 bytes for the string. The variant must be 146 * aligned to 8 after the 6 bytes of the string, so that's 2 extra 147 * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used 148 * for the dictionary entry. An additional 1 byte is added to the 149 * array as a framing offset making a total of 15 bytes. 150 * 151 * If we add another entry, "title" that maps to a nullable string 152 * that happens to have a value of null, then we use 0 bytes for the 153 * null value (and 3 bytes for the variant to contain it along with 154 * its type string) plus 6 bytes for the string. Again, we need 2 155 * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. 156 * 157 * We now require extra padding between the two items in the array. 158 * After the 14 bytes of the first item, that's 2 bytes required. 159 * We now require 2 framing offsets for an extra two 160 * bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item 161 * dictionary. 162 * 163 * ## Type Information Cache 164 * 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 * 169 * Continuing with the above example, if a #GVariant exists with the 170 * type "a{sv}" then a type information struct will exist for 171 * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type 172 * will share the same type information. Additionally, all 173 * single-digit types are stored in read-only static memory and do 174 * not contribute to the writable memory footprint of a program using 175 * #GVariant. 176 * 177 * Aside from the type information structures stored in read-only 178 * memory, there are two forms of type information. One is used for 179 * container types where there is a single element type: arrays and 180 * maybe types. The other is used for container types where there 181 * are multiple element types: tuples and dictionary entries. 182 * 183 * Array type info structures are 6 * sizeof (void *), plus the 184 * memory required to store the type string itself. This means that 185 * on 32-bit systems, the cache entry for "a{sv}" would require 30 186 * bytes of memory (plus malloc overhead). 187 * 188 * Tuple type info structures are 6 * sizeof (void *), plus 4 * 189 * sizeof (void *) for each item in the tuple, plus the memory 190 * required to store the type string itself. A 2-item tuple, for 191 * example, would have a type information structure that consumed 192 * writable memory in the size of 14 * sizeof (void *) (plus type 193 * string) This means that on 32-bit systems, the cache entry for 194 * "{sv}" would require 61 bytes of memory (plus malloc overhead). 195 * 196 * This means that in total, for our "a{sv}" example, 91 bytes of 197 * type information would be allocated. 198 * 199 * The type information cache, additionally, uses a #GHashTable to 200 * store and lookup the cached items and stores a pointer to this 201 * hash table in static storage. The hash table is freed when there 202 * are zero items in the type cache. 203 * 204 * Although these sizes may seem large it is important to remember 205 * that a program will probably only have a very small number of 206 * different types of values in it and that only one type information 207 * structure is required for many different values of the same type. 208 * 209 * ## Buffer Management Memory 210 * 211 * #GVariant uses an internal buffer management structure to deal 212 * with the various different possible sources of serialised data 213 * that it uses. The buffer is responsible for ensuring that the 214 * correct call is made when the data is no longer in use by 215 * #GVariant. This may involve a g_free() or a g_slice_free() or 216 * even g_mapped_file_unref(). 217 * 218 * One buffer management structure is used for each chunk of 219 * serialised data. The size of the buffer management structure 220 * is 4 * (void *). On 32-bit systems, that's 16 bytes. 221 * 222 * ## GVariant structure 223 * 224 * The size of a #GVariant structure is 6 * (void *). On 32-bit 225 * systems, that's 24 bytes. 226 * 227 * #GVariant structures only exist if they are explicitly created 228 * with API calls. For example, if a #GVariant is constructed out of 229 * serialised data for the example given above (with the dictionary) 230 * then although there are 9 individual values that comprise the 231 * entire dictionary (two keys, two values, two variants containing 232 * the values, two dictionary entries, plus the dictionary itself), 233 * only 1 #GVariant instance exists -- the one referring to the 234 * dictionary. 235 * 236 * If calls are made to start accessing the other values then 237 * #GVariant instances will exist for those values only for as long 238 * as they are in use (ie: until you call g_variant_unref()). The 239 * type information is shared. The serialised data and the buffer 240 * management structure for that serialised data is shared by the 241 * child. 242 * 243 * ## Summary 244 * 245 * To put the entire example together, for our dictionary mapping 246 * strings to variants (with two entries, as given above), we are 247 * using 91 bytes of memory for type information, 29 byes of memory 248 * for the serialised data, 16 bytes for buffer management and 24 249 * bytes for the #GVariant instance, or a total of 160 bytes, plus 250 * malloc overhead. If we were to use g_variant_get_child_value() to 251 * access the two dictionary entries, we would use an additional 48 252 * bytes. If we were to have other dictionaries of the same type, we 253 * would use more memory for the serialised data and buffer 254 * management for those dictionaries, but the type information would 255 * be shared. 256 * 257 * Since: 2.24 258 */ 259 public class Variant 260 { 261 /** the main Gtk struct */ 262 protected GVariant* gVariant; 263 264 /** Get the main Gtk struct */ 265 public GVariant* getVariantStruct() 266 { 267 return gVariant; 268 } 269 270 /** the main Gtk struct as a void* */ 271 protected void* getStruct() 272 { 273 return cast(void*)gVariant; 274 } 275 276 /** 277 * Sets our main struct and passes it to the parent class. 278 */ 279 public this (GVariant* gVariant) 280 { 281 this.gVariant = gVariant; 282 } 283 284 /** 285 * Creates a DBus object path GVariant with the contents of string. 286 * string must be a valid DBus object path. 287 * Use Variant.isObjectPath() if you're not sure. 288 * 289 * Since: 2.24 290 * 291 * Throws: ConstructionException GTK+ fails to create the object. 292 */ 293 public static Variant fromObjectPath(string path) 294 { 295 auto p = g_variant_new_object_path(Str.toStringz(path)); 296 if(p is null) 297 { 298 throw new ConstructionException("null returned by g_variant_new_object_path"); 299 } 300 return new Variant(cast(GVariant*) p); 301 } 302 303 /** 304 * Creates a DBus type signature GVariant with the contents of string. 305 * string must be a valid DBus type signature. 306 * Use Variant.isSignature() if you're not sure. 307 * 308 * Since: 2.24 309 * 310 * Throws: ConstructionException GTK+ fails to create the object. 311 */ 312 public static Variant fromSignature(string signature) 313 { 314 auto p = g_variant_new_signature(Str.toStringz(signature)); 315 if(p is null) 316 { 317 throw new ConstructionException("null returned by g_variant_new_signature"); 318 } 319 return new Variant(cast(GVariant*) p); 320 } 321 322 /** 323 * Creates an array-of-bytes GVariant with the contents of string. 324 * This function is just like new Variant(string) except that the string 325 * need not be valid utf8. 326 * 327 * The nul terminator character at the end of the string is stored in 328 * the array. 329 * 330 * Throws: ConstructionException GTK+ fails to create the object. 331 */ 332 public static Variant fromByteString(string byteString) 333 { 334 auto p = g_variant_new_bytestring(Str.toStringz(byteString)); 335 if(p is null) 336 { 337 throw new ConstructionException("null returned by g_variant_new_bytestring"); 338 } 339 return new Variant(cast(GVariant*) p); 340 } 341 342 /** 343 * Constructs an array of object paths Variant from the given array 344 * of strings. 345 * 346 * Each string must be a valid Variant object path. 347 * 348 * Since: 2.30 349 * 350 * Params: 351 * strv = an array of strings. 352 * 353 * Throws: ConstructionException GTK+ fails to create the object. 354 */ 355 public static Variant fromObjv(string[] strv) 356 { 357 // GVariant * g_variant_new_objv (const gchar * const *strv, gssize length); 358 auto p = g_variant_new_objv(Str.toStringzArray(strv), strv.length); 359 if(p is null) 360 { 361 throw new ConstructionException("null returned by g_variant_new_objv(strv, length)"); 362 } 363 return new Variant(cast(GVariant*) p); 364 } 365 366 /** 367 * Constructs an array of bytestring GVariant from the given array of 368 * strings. If length is -1 then strv is null-terminated. 369 * 370 * Since: 2.26 371 * 372 * Params: 373 * strv = an array of strings. 374 * 375 * Throws: ConstructionException GTK+ fails to create the object. 376 */ 377 public static Variant fromByteStringArray(string[] strv) 378 { 379 auto p = g_variant_new_bytestring_array(Str.toStringzArray(strv), strv.length); 380 if(p is null) 381 { 382 throw new ConstructionException("null returned by g_variant_new_bytestring_array(strv, length)"); 383 } 384 return new Variant(cast(GVariant*) p); 385 } 386 387 /** 388 */ 389 390 /** 391 * Creates a new #GVariant array from @children. 392 * 393 * @child_type must be non-%NULL if @n_children is zero. Otherwise, the 394 * child type is determined by inspecting the first element of the 395 * @children array. If @child_type is non-%NULL then it must be a 396 * definite type. 397 * 398 * The items of the array are taken from the @children array. No entry 399 * in the @children array may be %NULL. 400 * 401 * All items in the array must have the same type, which must be the 402 * same as @child_type, if given. 403 * 404 * If the @children are floating references (see g_variant_ref_sink()), the 405 * new instance takes ownership of them as if via g_variant_ref_sink(). 406 * 407 * Params: 408 * childType = the element type of the new array 409 * children = an array of 410 * #GVariant pointers, the children 411 * nChildren = the length of @children 412 * 413 * Return: a floating reference to a new #GVariant array 414 * 415 * Since: 2.24 416 * 417 * Throws: ConstructionException GTK+ fails to create the object. 418 */ 419 public this(VariantType childType, Variant[] children) 420 { 421 GVariant*[] childrenArray = new GVariant*[children.length]; 422 for ( int i = 0; i < children.length; i++ ) 423 { 424 childrenArray[i] = children[i].getVariantStruct(); 425 } 426 427 auto p = g_variant_new_array((childType is null) ? null : childType.getVariantTypeStruct(), childrenArray.ptr, cast(size_t)children.length); 428 429 if(p is null) 430 { 431 throw new ConstructionException("null returned by new_array"); 432 } 433 434 this(cast(GVariant*) p); 435 } 436 437 /** 438 * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. 439 * 440 * Params: 441 * value = a #gboolean value 442 * 443 * Return: a floating reference to a new boolean #GVariant instance 444 * 445 * Since: 2.24 446 * 447 * Throws: ConstructionException GTK+ fails to create the object. 448 */ 449 public this(bool value) 450 { 451 auto p = g_variant_new_boolean(value); 452 453 if(p is null) 454 { 455 throw new ConstructionException("null returned by new_boolean"); 456 } 457 458 this(cast(GVariant*) p); 459 } 460 461 /** 462 * Creates a new byte #GVariant instance. 463 * 464 * Params: 465 * value = a #guint8 value 466 * 467 * Return: a floating reference to a new byte #GVariant instance 468 * 469 * Since: 2.24 470 * 471 * Throws: ConstructionException GTK+ fails to create the object. 472 */ 473 public this(char value) 474 { 475 auto p = g_variant_new_byte(value); 476 477 if(p is null) 478 { 479 throw new ConstructionException("null returned by new_byte"); 480 } 481 482 this(cast(GVariant*) p); 483 } 484 485 /** 486 * Creates a new dictionary entry #GVariant. @key and @value must be 487 * non-%NULL. @key must be a value of a basic type (ie: not a container). 488 * 489 * If the @key or @value are floating references (see g_variant_ref_sink()), 490 * the new instance takes ownership of them as if via g_variant_ref_sink(). 491 * 492 * Params: 493 * key = a basic #GVariant, the key 494 * value = a #GVariant, the value 495 * 496 * Return: a floating reference to a new dictionary entry #GVariant 497 * 498 * Since: 2.24 499 * 500 * Throws: ConstructionException GTK+ fails to create the object. 501 */ 502 public this(Variant key, Variant value) 503 { 504 auto p = g_variant_new_dict_entry((key is null) ? null : key.getVariantStruct(), (value is null) ? null : value.getVariantStruct()); 505 506 if(p is null) 507 { 508 throw new ConstructionException("null returned by new_dict_entry"); 509 } 510 511 this(cast(GVariant*) p); 512 } 513 514 /** 515 * Creates a new double #GVariant instance. 516 * 517 * Params: 518 * value = a #gdouble floating point value 519 * 520 * Return: a floating reference to a new double #GVariant instance 521 * 522 * Since: 2.24 523 * 524 * Throws: ConstructionException GTK+ fails to create the object. 525 */ 526 public this(double value) 527 { 528 auto p = g_variant_new_double(value); 529 530 if(p is null) 531 { 532 throw new ConstructionException("null returned by new_double"); 533 } 534 535 this(cast(GVariant*) p); 536 } 537 538 /** 539 * Provides access to the serialised data for an array of fixed-sized 540 * items. 541 * 542 * @value must be an array with fixed-sized elements. Numeric types are 543 * fixed-size as are tuples containing only other fixed-sized types. 544 * 545 * @element_size must be the size of a single element in the array. 546 * For example, if calling this function for an array of 32-bit integers, 547 * you might say sizeof(gint32). This value isn't used except for the purpose 548 * of a double-check that the form of the serialised data matches the caller's 549 * expectation. 550 * 551 * @n_elements, which must be non-%NULL is set equal to the number of 552 * items in the array. 553 * 554 * Params: 555 * elementType = the #GVariantType of each element 556 * elements = a pointer to the fixed array of contiguous elements 557 * nElements = the number of elements 558 * elementSize = the size of each element 559 * 560 * Return: a floating reference to a new array #GVariant instance 561 * 562 * Since: 2.32 563 * 564 * Throws: ConstructionException GTK+ fails to create the object. 565 */ 566 public this(VariantType elementType, void* elements, size_t nElements, size_t elementSize) 567 { 568 auto p = g_variant_new_fixed_array((elementType is null) ? null : elementType.getVariantTypeStruct(), elements, nElements, elementSize); 569 570 if(p is null) 571 { 572 throw new ConstructionException("null returned by new_fixed_array"); 573 } 574 575 this(cast(GVariant*) p); 576 } 577 578 /** 579 * Constructs a new serialised-mode #GVariant instance. This is the 580 * inner interface for creation of new serialised values that gets 581 * called from various functions in gvariant.c. 582 * 583 * A reference is taken on @bytes. 584 * 585 * Params: 586 * type = a #GVariantType 587 * bytes = a #GBytes 588 * trusted = if the contents of @bytes are trusted 589 * 590 * Return: a new #GVariant with a floating reference 591 * 592 * Since: 2.36 593 * 594 * Throws: ConstructionException GTK+ fails to create the object. 595 */ 596 public this(VariantType type, Bytes bytes, bool trusted) 597 { 598 auto p = g_variant_new_from_bytes((type is null) ? null : type.getVariantTypeStruct(), (bytes is null) ? null : bytes.getBytesStruct(), trusted); 599 600 if(p is null) 601 { 602 throw new ConstructionException("null returned by new_from_bytes"); 603 } 604 605 this(cast(GVariant*) p); 606 } 607 608 /** 609 * Creates a new #GVariant instance from serialised data. 610 * 611 * @type is the type of #GVariant instance that will be constructed. 612 * The interpretation of @data depends on knowing the type. 613 * 614 * @data is not modified by this function and must remain valid with an 615 * unchanging value until such a time as @notify is called with 616 * @user_data. If the contents of @data change before that time then 617 * the result is undefined. 618 * 619 * If @data is trusted to be serialised data in normal form then 620 * @trusted should be %TRUE. This applies to serialised data created 621 * within this process or read from a trusted location on the disk (such 622 * as a file installed in /usr/lib alongside your application). You 623 * should set trusted to %FALSE if @data is read from the network, a 624 * file in the user's home directory, etc. 625 * 626 * If @data was not stored in this machine's native endianness, any multi-byte 627 * numeric values in the returned variant will also be in non-native 628 * endianness. g_variant_byteswap() can be used to recover the original values. 629 * 630 * @notify will be called with @user_data when @data is no longer 631 * needed. The exact time of this call is unspecified and might even be 632 * before this function returns. 633 * 634 * Params: 635 * type = a definite #GVariantType 636 * data = the serialised data 637 * size = the size of @data 638 * trusted = %TRUE if @data is definitely in normal form 639 * notify = function to call when @data is no longer needed 640 * userData = data for @notify 641 * 642 * Return: a new floating #GVariant of type @type 643 * 644 * Since: 2.24 645 * 646 * Throws: ConstructionException GTK+ fails to create the object. 647 */ 648 public this(VariantType type, ubyte[] data, bool trusted, GDestroyNotify notify, void* userData) 649 { 650 auto p = g_variant_new_from_data((type is null) ? null : type.getVariantTypeStruct(), data.ptr, cast(size_t)data.length, trusted, notify, userData); 651 652 if(p is null) 653 { 654 throw new ConstructionException("null returned by new_from_data"); 655 } 656 657 this(cast(GVariant*) p); 658 } 659 660 /** 661 * Creates a new int16 #GVariant instance. 662 * 663 * Params: 664 * value = a #gint16 value 665 * 666 * Return: a floating reference to a new int16 #GVariant instance 667 * 668 * Since: 2.24 669 * 670 * Throws: ConstructionException GTK+ fails to create the object. 671 */ 672 public this(short value) 673 { 674 auto p = g_variant_new_int16(value); 675 676 if(p is null) 677 { 678 throw new ConstructionException("null returned by new_int16"); 679 } 680 681 this(cast(GVariant*) p); 682 } 683 684 /** 685 * Creates a new int32 #GVariant instance. 686 * 687 * Params: 688 * value = a #gint32 value 689 * 690 * Return: a floating reference to a new int32 #GVariant instance 691 * 692 * Since: 2.24 693 * 694 * Throws: ConstructionException GTK+ fails to create the object. 695 */ 696 public this(int value) 697 { 698 auto p = g_variant_new_int32(value); 699 700 if(p is null) 701 { 702 throw new ConstructionException("null returned by new_int32"); 703 } 704 705 this(cast(GVariant*) p); 706 } 707 708 /** 709 * Creates a new int64 #GVariant instance. 710 * 711 * Params: 712 * value = a #gint64 value 713 * 714 * Return: a floating reference to a new int64 #GVariant instance 715 * 716 * Since: 2.24 717 * 718 * Throws: ConstructionException GTK+ fails to create the object. 719 */ 720 public this(long value) 721 { 722 auto p = g_variant_new_int64(value); 723 724 if(p is null) 725 { 726 throw new ConstructionException("null returned by new_int64"); 727 } 728 729 this(cast(GVariant*) p); 730 } 731 732 /** 733 * Depending on if @child is %NULL, either wraps @child inside of a 734 * maybe container or creates a Nothing instance for the given @type. 735 * 736 * At least one of @child_type and @child must be non-%NULL. 737 * If @child_type is non-%NULL then it must be a definite type. 738 * If they are both non-%NULL then @child_type must be the type 739 * of @child. 740 * 741 * If @child is a floating reference (see g_variant_ref_sink()), the new 742 * instance takes ownership of @child. 743 * 744 * Params: 745 * childType = the #GVariantType of the child, or %NULL 746 * child = the child value, or %NULL 747 * 748 * Return: a floating reference to a new #GVariant maybe instance 749 * 750 * Since: 2.24 751 * 752 * Throws: ConstructionException GTK+ fails to create the object. 753 */ 754 public this(VariantType childType, Variant child) 755 { 756 auto p = g_variant_new_maybe((childType is null) ? null : childType.getVariantTypeStruct(), (child is null) ? null : child.getVariantStruct()); 757 758 if(p is null) 759 { 760 throw new ConstructionException("null returned by new_maybe"); 761 } 762 763 this(cast(GVariant*) p); 764 } 765 766 /** 767 * Parses @format and returns the result. 768 * 769 * This is the version of g_variant_new_parsed() intended to be used 770 * from libraries. 771 * 772 * The return value will be floating if it was a newly created GVariant 773 * instance. In the case that @format simply specified the collection 774 * of a #GVariant pointer (eg: @format was "%*") then the collected 775 * #GVariant pointer will be returned unmodified, without adding any 776 * additional references. 777 * 778 * Note that the arguments in @app must be of the correct width for their types 779 * specified in @format when collected into the #va_list. See 780 * the [GVariant varargs documentation][gvariant-varargs]. 781 * 782 * In order to behave correctly in all cases it is necessary for the 783 * calling function to g_variant_ref_sink() the return result before 784 * returning control to the user that originally provided the pointer. 785 * At this point, the caller will have their own full reference to the 786 * result. This can also be done by adding the result to a container, 787 * or by passing it to another g_variant_new() call. 788 * 789 * Params: 790 * format = a text format #GVariant 791 * app = a pointer to a #va_list 792 * 793 * Return: a new, usually floating, #GVariant 794 * 795 * Throws: ConstructionException GTK+ fails to create the object. 796 */ 797 public this(string format, void** app) 798 { 799 auto p = g_variant_new_parsed_va(Str.toStringz(format), app); 800 801 if(p is null) 802 { 803 throw new ConstructionException("null returned by new_parsed_va"); 804 } 805 806 this(cast(GVariant*) p); 807 } 808 809 /** 810 * Creates a string #GVariant with the contents of @string. 811 * 812 * @string must be valid UTF-8, and must not be %NULL. To encode 813 * potentially-%NULL strings, use g_variant_new() with `ms` as the 814 * [format string][gvariant-format-strings-maybe-types]. 815 * 816 * Params: 817 * str = a normal UTF-8 nul-terminated string 818 * 819 * Return: a floating reference to a new string #GVariant instance 820 * 821 * Since: 2.24 822 * 823 * Throws: ConstructionException GTK+ fails to create the object. 824 */ 825 public this(string str) 826 { 827 auto p = g_variant_new_string(Str.toStringz(str)); 828 829 if(p is null) 830 { 831 throw new ConstructionException("null returned by new_string"); 832 } 833 834 this(cast(GVariant*) p); 835 } 836 837 /** 838 * Constructs an array of strings #GVariant from the given array of 839 * strings. 840 * 841 * If @length is -1 then @strv is %NULL-terminated. 842 * 843 * Params: 844 * strv = an array of strings 845 * length = the length of @strv, or -1 846 * 847 * Return: a new floating #GVariant instance 848 * 849 * Since: 2.24 850 * 851 * Throws: ConstructionException GTK+ fails to create the object. 852 */ 853 public this(string[] strv) 854 { 855 auto p = g_variant_new_strv(Str.toStringzArray(strv), cast(ptrdiff_t)strv.length); 856 857 if(p is null) 858 { 859 throw new ConstructionException("null returned by new_strv"); 860 } 861 862 this(cast(GVariant*) p); 863 } 864 865 /** 866 * Creates a new tuple #GVariant out of the items in @children. The 867 * type is determined from the types of @children. No entry in the 868 * @children array may be %NULL. 869 * 870 * If @n_children is 0 then the unit tuple is constructed. 871 * 872 * If the @children are floating references (see g_variant_ref_sink()), the 873 * new instance takes ownership of them as if via g_variant_ref_sink(). 874 * 875 * Params: 876 * children = the items to make the tuple out of 877 * nChildren = the length of @children 878 * 879 * Return: a floating reference to a new #GVariant tuple 880 * 881 * Since: 2.24 882 * 883 * Throws: ConstructionException GTK+ fails to create the object. 884 */ 885 public this(Variant[] children) 886 { 887 GVariant*[] childrenArray = new GVariant*[children.length]; 888 for ( int i = 0; i < children.length; i++ ) 889 { 890 childrenArray[i] = children[i].getVariantStruct(); 891 } 892 893 auto p = g_variant_new_tuple(childrenArray.ptr, cast(size_t)children.length); 894 895 if(p is null) 896 { 897 throw new ConstructionException("null returned by new_tuple"); 898 } 899 900 this(cast(GVariant*) p); 901 } 902 903 /** 904 * Creates a new uint16 #GVariant instance. 905 * 906 * Params: 907 * value = a #guint16 value 908 * 909 * Return: a floating reference to a new uint16 #GVariant instance 910 * 911 * Since: 2.24 912 * 913 * Throws: ConstructionException GTK+ fails to create the object. 914 */ 915 public this(ushort value) 916 { 917 auto p = g_variant_new_uint16(value); 918 919 if(p is null) 920 { 921 throw new ConstructionException("null returned by new_uint16"); 922 } 923 924 this(cast(GVariant*) p); 925 } 926 927 /** 928 * Creates a new uint32 #GVariant instance. 929 * 930 * Params: 931 * value = a #guint32 value 932 * 933 * Return: a floating reference to a new uint32 #GVariant instance 934 * 935 * Since: 2.24 936 * 937 * Throws: ConstructionException GTK+ fails to create the object. 938 */ 939 public this(uint value) 940 { 941 auto p = g_variant_new_uint32(value); 942 943 if(p is null) 944 { 945 throw new ConstructionException("null returned by new_uint32"); 946 } 947 948 this(cast(GVariant*) p); 949 } 950 951 /** 952 * Creates a new uint64 #GVariant instance. 953 * 954 * Params: 955 * value = a #guint64 value 956 * 957 * Return: a floating reference to a new uint64 #GVariant instance 958 * 959 * Since: 2.24 960 * 961 * Throws: ConstructionException GTK+ fails to create the object. 962 */ 963 public this(ulong value) 964 { 965 auto p = g_variant_new_uint64(value); 966 967 if(p is null) 968 { 969 throw new ConstructionException("null returned by new_uint64"); 970 } 971 972 this(cast(GVariant*) p); 973 } 974 975 /** 976 * This function is intended to be used by libraries based on 977 * #GVariant that want to provide g_variant_new()-like functionality 978 * to their users. 979 * 980 * The API is more general than g_variant_new() to allow a wider range 981 * of possible uses. 982 * 983 * @format_string must still point to a valid format string, but it only 984 * needs to be nul-terminated if @endptr is %NULL. If @endptr is 985 * non-%NULL then it is updated to point to the first character past the 986 * end of the format string. 987 * 988 * @app is a pointer to a #va_list. The arguments, according to 989 * @format_string, are collected from this #va_list and the list is left 990 * pointing to the argument following the last. 991 * 992 * Note that the arguments in @app must be of the correct width for their 993 * types specified in @format_string when collected into the #va_list. 994 * See the [GVariant varargs documentation][gvariant-varargs. 995 * 996 * These two generalisations allow mixing of multiple calls to 997 * g_variant_new_va() and g_variant_get_va() within a single actual 998 * varargs call by the user. 999 * 1000 * The return value will be floating if it was a newly created GVariant 1001 * instance (for example, if the format string was "(ii)"). In the case 1002 * that the format_string was '*', '?', 'r', or a format starting with 1003 * '@' then the collected #GVariant pointer will be returned unmodified, 1004 * without adding any additional references. 1005 * 1006 * In order to behave correctly in all cases it is necessary for the 1007 * calling function to g_variant_ref_sink() the return result before 1008 * returning control to the user that originally provided the pointer. 1009 * At this point, the caller will have their own full reference to the 1010 * result. This can also be done by adding the result to a container, 1011 * or by passing it to another g_variant_new() call. 1012 * 1013 * Params: 1014 * formatString = a string that is prefixed with a format string 1015 * endptr = location to store the end pointer, 1016 * or %NULL 1017 * app = a pointer to a #va_list 1018 * 1019 * Return: a new, usually floating, #GVariant 1020 * 1021 * Since: 2.24 1022 * 1023 * Throws: ConstructionException GTK+ fails to create the object. 1024 */ 1025 public this(string formatString, string[] endptr, void** app) 1026 { 1027 auto p = g_variant_new_va(Str.toStringz(formatString), Str.toStringzArray(endptr), app); 1028 1029 if(p is null) 1030 { 1031 throw new ConstructionException("null returned by new_va"); 1032 } 1033 1034 this(cast(GVariant*) p); 1035 } 1036 1037 /** 1038 * Boxes @value. The result is a #GVariant instance representing a 1039 * variant containing the original value. 1040 * 1041 * If @child is a floating reference (see g_variant_ref_sink()), the new 1042 * instance takes ownership of @child. 1043 * 1044 * Params: 1045 * value = a #GVariant instance 1046 * 1047 * Return: a floating reference to a new variant #GVariant instance 1048 * 1049 * Since: 2.24 1050 * 1051 * Throws: ConstructionException GTK+ fails to create the object. 1052 */ 1053 public this(Variant value) 1054 { 1055 auto p = g_variant_new_variant((value is null) ? null : value.getVariantStruct()); 1056 1057 if(p is null) 1058 { 1059 throw new ConstructionException("null returned by new_variant"); 1060 } 1061 1062 this(cast(GVariant*) p); 1063 } 1064 1065 /** 1066 * Performs a byteswapping operation on the contents of @value. The 1067 * result is that all multi-byte numeric data contained in @value is 1068 * byteswapped. That includes 16, 32, and 64bit signed and unsigned 1069 * integers as well as file handles and double precision floating point 1070 * values. 1071 * 1072 * This function is an identity mapping on any value that does not 1073 * contain multi-byte numeric data. That include strings, booleans, 1074 * bytes and containers containing only these things (recursively). 1075 * 1076 * The returned value is always in normal form and is marked as trusted. 1077 * 1078 * Return: the byteswapped form of @value 1079 * 1080 * Since: 2.24 1081 */ 1082 public Variant byteswap() 1083 { 1084 auto p = g_variant_byteswap(gVariant); 1085 1086 if(p is null) 1087 { 1088 return null; 1089 } 1090 1091 return new Variant(cast(GVariant*) p); 1092 } 1093 1094 /** 1095 * Checks if calling g_variant_get() with @format_string on @value would 1096 * be valid from a type-compatibility standpoint. @format_string is 1097 * assumed to be a valid format string (from a syntactic standpoint). 1098 * 1099 * If @copy_only is %TRUE then this function additionally checks that it 1100 * would be safe to call g_variant_unref() on @value immediately after 1101 * the call to g_variant_get() without invalidating the result. This is 1102 * only possible if deep copies are made (ie: there are no pointers to 1103 * the data inside of the soon-to-be-freed #GVariant instance). If this 1104 * check fails then a g_critical() is printed and %FALSE is returned. 1105 * 1106 * This function is meant to be used by functions that wish to provide 1107 * varargs accessors to #GVariant values of uncertain values (eg: 1108 * g_variant_lookup() or g_menu_model_get_item_attribute()). 1109 * 1110 * Params: 1111 * formatString = a valid #GVariant format string 1112 * copyOnly = %TRUE to ensure the format string makes deep copies 1113 * 1114 * Return: %TRUE if @format_string is safe to use 1115 * 1116 * Since: 2.34 1117 */ 1118 public bool checkFormatString(string formatString, bool copyOnly) 1119 { 1120 return g_variant_check_format_string(gVariant, Str.toStringz(formatString), copyOnly) != 0; 1121 } 1122 1123 /** 1124 * Classifies @value according to its top-level type. 1125 * 1126 * Return: the #GVariantClass of @value 1127 * 1128 * Since: 2.24 1129 */ 1130 public GVariantClass classify() 1131 { 1132 return g_variant_classify(gVariant); 1133 } 1134 1135 /** 1136 * Compares @one and @two. 1137 * 1138 * The types of @one and @two are #gconstpointer only to allow use of 1139 * this function with #GTree, #GPtrArray, etc. They must each be a 1140 * #GVariant. 1141 * 1142 * Comparison is only defined for basic types (ie: booleans, numbers, 1143 * strings). For booleans, %FALSE is less than %TRUE. Numbers are 1144 * ordered in the usual way. Strings are in ASCII lexographical order. 1145 * 1146 * It is a programmer error to attempt to compare container values or 1147 * two values that have types that are not exactly equal. For example, 1148 * you cannot compare a 32-bit signed integer with a 32-bit unsigned 1149 * integer. Also note that this function is not particularly 1150 * well-behaved when it comes to comparison of doubles; in particular, 1151 * the handling of incomparable values (ie: NaN) is undefined. 1152 * 1153 * If you only require an equality comparison, g_variant_equal() is more 1154 * general. 1155 * 1156 * Params: 1157 * two = a #GVariant instance of the same type 1158 * 1159 * Return: negative value if a < b; 1160 * zero if a = b; 1161 * positive value if a > b. 1162 * 1163 * Since: 2.26 1164 */ 1165 public int compare(Variant two) 1166 { 1167 return g_variant_compare(gVariant, (two is null) ? null : two.getVariantStruct()); 1168 } 1169 1170 /** 1171 * Similar to g_variant_get_bytestring() except that instead of 1172 * returning a constant string, the string is duplicated. 1173 * 1174 * The return value must be freed using g_free(). 1175 * 1176 * Return: a newly allocated string 1177 * 1178 * Since: 2.26 1179 */ 1180 public string dupBytestring() 1181 { 1182 size_t length; 1183 1184 return Str.toString(g_variant_dup_bytestring(gVariant, &length)); 1185 } 1186 1187 /** 1188 * Gets the contents of an array of array of bytes #GVariant. This call 1189 * makes a deep copy; the return result should be released with 1190 * g_strfreev(). 1191 * 1192 * If @length is non-%NULL then the number of elements in the result is 1193 * stored there. In any case, the resulting array will be 1194 * %NULL-terminated. 1195 * 1196 * For an empty array, @length will be set to 0 and a pointer to a 1197 * %NULL pointer will be returned. 1198 * 1199 * Return: an array of strings 1200 * 1201 * Since: 2.26 1202 */ 1203 public string[] dupBytestringArray() 1204 { 1205 size_t length; 1206 1207 return Str.toStringArray(g_variant_dup_bytestring_array(gVariant, &length)); 1208 } 1209 1210 /** 1211 * Gets the contents of an array of object paths #GVariant. This call 1212 * makes a deep copy; the return result should be released with 1213 * g_strfreev(). 1214 * 1215 * If @length is non-%NULL then the number of elements in the result 1216 * is stored there. In any case, the resulting array will be 1217 * %NULL-terminated. 1218 * 1219 * For an empty array, @length will be set to 0 and a pointer to a 1220 * %NULL pointer will be returned. 1221 * 1222 * Return: an array of strings 1223 * 1224 * Since: 2.30 1225 */ 1226 public string[] dupObjv() 1227 { 1228 size_t length; 1229 1230 return Str.toStringArray(g_variant_dup_objv(gVariant, &length)); 1231 } 1232 1233 /** 1234 * Similar to g_variant_get_string() except that instead of returning 1235 * a constant string, the string is duplicated. 1236 * 1237 * The string will always be UTF-8 encoded. 1238 * 1239 * The return value must be freed using g_free(). 1240 * 1241 * Params: 1242 * length = a pointer to a #gsize, to store the length 1243 * 1244 * Return: a newly allocated string, UTF-8 encoded 1245 * 1246 * Since: 2.24 1247 */ 1248 public string dupString(out size_t length) 1249 { 1250 return Str.toString(g_variant_dup_string(gVariant, &length)); 1251 } 1252 1253 /** 1254 * Gets the contents of an array of strings #GVariant. This call 1255 * makes a deep copy; the return result should be released with 1256 * g_strfreev(). 1257 * 1258 * If @length is non-%NULL then the number of elements in the result 1259 * is stored there. In any case, the resulting array will be 1260 * %NULL-terminated. 1261 * 1262 * For an empty array, @length will be set to 0 and a pointer to a 1263 * %NULL pointer will be returned. 1264 * 1265 * Return: an array of strings 1266 * 1267 * Since: 2.24 1268 */ 1269 public string[] dupStrv() 1270 { 1271 size_t length; 1272 1273 return Str.toStringArray(g_variant_dup_strv(gVariant, &length)); 1274 } 1275 1276 /** 1277 * Checks if @one and @two have the same type and value. 1278 * 1279 * The types of @one and @two are #gconstpointer only to allow use of 1280 * this function with #GHashTable. They must each be a #GVariant. 1281 * 1282 * Params: 1283 * two = a #GVariant instance 1284 * 1285 * Return: %TRUE if @one and @two are equal 1286 * 1287 * Since: 2.24 1288 */ 1289 public bool equal(Variant two) 1290 { 1291 return g_variant_equal(gVariant, (two is null) ? null : two.getVariantStruct()) != 0; 1292 } 1293 1294 /** 1295 * Returns the boolean value of @value. 1296 * 1297 * It is an error to call this function with a @value of any type 1298 * other than %G_VARIANT_TYPE_BOOLEAN. 1299 * 1300 * Return: %TRUE or %FALSE 1301 * 1302 * Since: 2.24 1303 */ 1304 public bool getBoolean() 1305 { 1306 return g_variant_get_boolean(gVariant) != 0; 1307 } 1308 1309 /** 1310 * Returns the byte value of @value. 1311 * 1312 * It is an error to call this function with a @value of any type 1313 * other than %G_VARIANT_TYPE_BYTE. 1314 * 1315 * Return: a #guchar 1316 * 1317 * Since: 2.24 1318 */ 1319 public char getByte() 1320 { 1321 return g_variant_get_byte(gVariant); 1322 } 1323 1324 /** 1325 * Returns the string value of a #GVariant instance with an 1326 * array-of-bytes type. The string has no particular encoding. 1327 * 1328 * If the array does not end with a nul terminator character, the empty 1329 * string is returned. For this reason, you can always trust that a 1330 * non-%NULL nul-terminated string will be returned by this function. 1331 * 1332 * If the array contains a nul terminator character somewhere other than 1333 * the last byte then the returned string is the string, up to the first 1334 * such nul character. 1335 * 1336 * It is an error to call this function with a @value that is not an 1337 * array of bytes. 1338 * 1339 * The return value remains valid as long as @value exists. 1340 * 1341 * Return: the constant string 1342 * 1343 * Since: 2.26 1344 */ 1345 public string getBytestring() 1346 { 1347 return Str.toString(g_variant_get_bytestring(gVariant)); 1348 } 1349 1350 /** 1351 * Gets the contents of an array of array of bytes #GVariant. This call 1352 * makes a shallow copy; the return result should be released with 1353 * g_free(), but the individual strings must not be modified. 1354 * 1355 * If @length is non-%NULL then the number of elements in the result is 1356 * stored there. In any case, the resulting array will be 1357 * %NULL-terminated. 1358 * 1359 * For an empty array, @length will be set to 0 and a pointer to a 1360 * %NULL pointer will be returned. 1361 * 1362 * Return: an array of constant strings 1363 * 1364 * Since: 2.26 1365 */ 1366 public string[] getBytestringArray() 1367 { 1368 size_t length; 1369 1370 return Str.toStringArray(g_variant_get_bytestring_array(gVariant, &length)); 1371 } 1372 1373 /** 1374 * Reads a child item out of a container #GVariant instance. This 1375 * includes variants, maybes, arrays, tuples and dictionary 1376 * entries. It is an error to call this function on any other type of 1377 * #GVariant. 1378 * 1379 * It is an error if @index_ is greater than the number of child items 1380 * in the container. See g_variant_n_children(). 1381 * 1382 * The returned value is never floating. You should free it with 1383 * g_variant_unref() when you're done with it. 1384 * 1385 * This function is O(1). 1386 * 1387 * Params: 1388 * index = the index of the child to fetch 1389 * 1390 * Return: the child at the specified index 1391 * 1392 * Since: 2.24 1393 */ 1394 public Variant getChildValue(size_t index) 1395 { 1396 auto p = g_variant_get_child_value(gVariant, index); 1397 1398 if(p is null) 1399 { 1400 return null; 1401 } 1402 1403 return new Variant(cast(GVariant*) p); 1404 } 1405 1406 /** 1407 * Returns a pointer to the serialised form of a #GVariant instance. 1408 * The returned data may not be in fully-normalised form if read from an 1409 * untrusted source. The returned data must not be freed; it remains 1410 * valid for as long as @value exists. 1411 * 1412 * If @value is a fixed-sized value that was deserialised from a 1413 * corrupted serialised container then %NULL may be returned. In this 1414 * case, the proper thing to do is typically to use the appropriate 1415 * number of nul bytes in place of @value. If @value is not fixed-sized 1416 * then %NULL is never returned. 1417 * 1418 * In the case that @value is already in serialised form, this function 1419 * is O(1). If the value is not already in serialised form, 1420 * serialisation occurs implicitly and is approximately O(n) in the size 1421 * of the result. 1422 * 1423 * To deserialise the data returned by this function, in addition to the 1424 * serialised data, you must know the type of the #GVariant, and (if the 1425 * machine might be different) the endianness of the machine that stored 1426 * it. As a result, file formats or network messages that incorporate 1427 * serialised #GVariants must include this information either 1428 * implicitly (for instance "the file always contains a 1429 * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or 1430 * explicitly (by storing the type and/or endianness in addition to the 1431 * serialised data). 1432 * 1433 * Return: the serialised form of @value, or %NULL 1434 * 1435 * Since: 2.24 1436 */ 1437 public void* getData() 1438 { 1439 return g_variant_get_data(gVariant); 1440 } 1441 1442 /** 1443 * Returns a pointer to the serialised form of a #GVariant instance. 1444 * The semantics of this function are exactly the same as 1445 * g_variant_get_data(), except that the returned #GBytes holds 1446 * a reference to the variant data. 1447 * 1448 * Return: A new #GBytes representing the variant data 1449 * 1450 * Since: 2.36 1451 */ 1452 public Bytes getDataAsBytes() 1453 { 1454 auto p = g_variant_get_data_as_bytes(gVariant); 1455 1456 if(p is null) 1457 { 1458 return null; 1459 } 1460 1461 return new Bytes(cast(GBytes*) p); 1462 } 1463 1464 /** 1465 * Returns the double precision floating point value of @value. 1466 * 1467 * It is an error to call this function with a @value of any type 1468 * other than %G_VARIANT_TYPE_DOUBLE. 1469 * 1470 * Return: a #gdouble 1471 * 1472 * Since: 2.24 1473 */ 1474 public double getDouble() 1475 { 1476 return g_variant_get_double(gVariant); 1477 } 1478 1479 /** 1480 * Provides access to the serialised data for an array of fixed-sized 1481 * items. 1482 * 1483 * @value must be an array with fixed-sized elements. Numeric types are 1484 * fixed-size, as are tuples containing only other fixed-sized types. 1485 * 1486 * @element_size must be the size of a single element in the array, 1487 * as given by the section on 1488 * [serialized data memory][gvariant-serialised-data-memory]. 1489 * 1490 * In particular, arrays of these fixed-sized types can be interpreted 1491 * as an array of the given C type, with @element_size set to the size 1492 * the appropriate type: 1493 * - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) 1494 * - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) 1495 * - %G_VARIANT_TYPE_BYTE: #guchar 1496 * - %G_VARIANT_TYPE_HANDLE: #guint32 1497 * - %G_VARIANT_TYPE_DOUBLE: #gdouble 1498 * 1499 * For example, if calling this function for an array of 32-bit integers, 1500 * you might say sizeof(gint32). This value isn't used except for the purpose 1501 * of a double-check that the form of the serialised data matches the caller's 1502 * expectation. 1503 * 1504 * @n_elements, which must be non-%NULL is set equal to the number of 1505 * items in the array. 1506 * 1507 * Params: 1508 * elementSize = the size of each element 1509 * 1510 * Return: a pointer to 1511 * the fixed array 1512 * 1513 * Since: 2.24 1514 */ 1515 public void[] getFixedArray(size_t elementSize) 1516 { 1517 size_t nElements; 1518 1519 auto p = g_variant_get_fixed_array(gVariant, &nElements, elementSize); 1520 1521 return p[0 .. nElements]; 1522 } 1523 1524 /** 1525 * Returns the 32-bit signed integer value of @value. 1526 * 1527 * It is an error to call this function with a @value of any type other 1528 * than %G_VARIANT_TYPE_HANDLE. 1529 * 1530 * By convention, handles are indexes into an array of file descriptors 1531 * that are sent alongside a D-Bus message. If you're not interacting 1532 * with D-Bus, you probably don't need them. 1533 * 1534 * Return: a #gint32 1535 * 1536 * Since: 2.24 1537 */ 1538 public int getHandle() 1539 { 1540 return g_variant_get_handle(gVariant); 1541 } 1542 1543 /** 1544 * Returns the 16-bit signed integer value of @value. 1545 * 1546 * It is an error to call this function with a @value of any type 1547 * other than %G_VARIANT_TYPE_INT16. 1548 * 1549 * Return: a #gint16 1550 * 1551 * Since: 2.24 1552 */ 1553 public short getInt16() 1554 { 1555 return g_variant_get_int16(gVariant); 1556 } 1557 1558 /** 1559 * Returns the 32-bit signed integer value of @value. 1560 * 1561 * It is an error to call this function with a @value of any type 1562 * other than %G_VARIANT_TYPE_INT32. 1563 * 1564 * Return: a #gint32 1565 * 1566 * Since: 2.24 1567 */ 1568 public int getInt32() 1569 { 1570 return g_variant_get_int32(gVariant); 1571 } 1572 1573 /** 1574 * Returns the 64-bit signed integer value of @value. 1575 * 1576 * It is an error to call this function with a @value of any type 1577 * other than %G_VARIANT_TYPE_INT64. 1578 * 1579 * Return: a #gint64 1580 * 1581 * Since: 2.24 1582 */ 1583 public long getInt64() 1584 { 1585 return g_variant_get_int64(gVariant); 1586 } 1587 1588 /** 1589 * Given a maybe-typed #GVariant instance, extract its value. If the 1590 * value is Nothing, then this function returns %NULL. 1591 * 1592 * Return: the contents of @value, or %NULL 1593 * 1594 * Since: 2.24 1595 */ 1596 public Variant getMaybe() 1597 { 1598 auto p = g_variant_get_maybe(gVariant); 1599 1600 if(p is null) 1601 { 1602 return null; 1603 } 1604 1605 return new Variant(cast(GVariant*) p); 1606 } 1607 1608 /** 1609 * Gets a #GVariant instance that has the same value as @value and is 1610 * trusted to be in normal form. 1611 * 1612 * If @value is already trusted to be in normal form then a new 1613 * reference to @value is returned. 1614 * 1615 * If @value is not already trusted, then it is scanned to check if it 1616 * is in normal form. If it is found to be in normal form then it is 1617 * marked as trusted and a new reference to it is returned. 1618 * 1619 * If @value is found not to be in normal form then a new trusted 1620 * #GVariant is created with the same value as @value. 1621 * 1622 * It makes sense to call this function if you've received #GVariant 1623 * data from untrusted sources and you want to ensure your serialised 1624 * output is definitely in normal form. 1625 * 1626 * Return: a trusted #GVariant 1627 * 1628 * Since: 2.24 1629 */ 1630 public Variant getNormalForm() 1631 { 1632 auto p = g_variant_get_normal_form(gVariant); 1633 1634 if(p is null) 1635 { 1636 return null; 1637 } 1638 1639 return new Variant(cast(GVariant*) p); 1640 } 1641 1642 /** 1643 * Gets the contents of an array of object paths #GVariant. This call 1644 * makes a shallow copy; the return result should be released with 1645 * g_free(), but the individual strings must not be modified. 1646 * 1647 * If @length is non-%NULL then the number of elements in the result 1648 * is stored there. In any case, the resulting array will be 1649 * %NULL-terminated. 1650 * 1651 * For an empty array, @length will be set to 0 and a pointer to a 1652 * %NULL pointer will be returned. 1653 * 1654 * Return: an array of constant strings 1655 * 1656 * Since: 2.30 1657 */ 1658 public string[] getObjv() 1659 { 1660 size_t length; 1661 1662 return Str.toStringArray(g_variant_get_objv(gVariant, &length)); 1663 } 1664 1665 /** 1666 * Determines the number of bytes that would be required to store @value 1667 * with g_variant_store(). 1668 * 1669 * If @value has a fixed-sized type then this function always returned 1670 * that fixed size. 1671 * 1672 * In the case that @value is already in serialised form or the size has 1673 * already been calculated (ie: this function has been called before) 1674 * then this function is O(1). Otherwise, the size is calculated, an 1675 * operation which is approximately O(n) in the number of values 1676 * involved. 1677 * 1678 * Return: the serialised size of @value 1679 * 1680 * Since: 2.24 1681 */ 1682 public size_t getSize() 1683 { 1684 return g_variant_get_size(gVariant); 1685 } 1686 1687 /** 1688 * Returns the string value of a #GVariant instance with a string 1689 * type. This includes the types %G_VARIANT_TYPE_STRING, 1690 * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. 1691 * 1692 * The string will always be UTF-8 encoded, and will never be %NULL. 1693 * 1694 * If @length is non-%NULL then the length of the string (in bytes) is 1695 * returned there. For trusted values, this information is already 1696 * known. For untrusted values, a strlen() will be performed. 1697 * 1698 * It is an error to call this function with a @value of any type 1699 * other than those three. 1700 * 1701 * The return value remains valid as long as @value exists. 1702 * 1703 * Params: 1704 * length = a pointer to a #gsize, 1705 * to store the length 1706 * 1707 * Return: the constant string, UTF-8 encoded 1708 * 1709 * Since: 2.24 1710 */ 1711 public string getString(out size_t length) 1712 { 1713 return Str.toString(g_variant_get_string(gVariant, &length)); 1714 } 1715 1716 /** 1717 * Gets the contents of an array of strings #GVariant. This call 1718 * makes a shallow copy; the return result should be released with 1719 * g_free(), but the individual strings must not be modified. 1720 * 1721 * If @length is non-%NULL then the number of elements in the result 1722 * is stored there. In any case, the resulting array will be 1723 * %NULL-terminated. 1724 * 1725 * For an empty array, @length will be set to 0 and a pointer to a 1726 * %NULL pointer will be returned. 1727 * 1728 * Return: an array of constant strings 1729 * 1730 * Since: 2.24 1731 */ 1732 public string[] getStrv() 1733 { 1734 size_t length; 1735 1736 return Str.toStringArray(g_variant_get_strv(gVariant, &length)); 1737 } 1738 1739 /** 1740 * Determines the type of @value. 1741 * 1742 * The return value is valid for the lifetime of @value and must not 1743 * be freed. 1744 * 1745 * Return: a #GVariantType 1746 * 1747 * Since: 2.24 1748 */ 1749 public VariantType getType() 1750 { 1751 auto p = g_variant_get_type(gVariant); 1752 1753 if(p is null) 1754 { 1755 return null; 1756 } 1757 1758 return new VariantType(cast(GVariantType*) p); 1759 } 1760 1761 /** 1762 * Returns the type string of @value. Unlike the result of calling 1763 * g_variant_type_peek_string(), this string is nul-terminated. This 1764 * string belongs to #GVariant and must not be freed. 1765 * 1766 * Return: the type string for the type of @value 1767 * 1768 * Since: 2.24 1769 */ 1770 public string getTypeString() 1771 { 1772 return Str.toString(g_variant_get_type_string(gVariant)); 1773 } 1774 1775 /** 1776 * Returns the 16-bit unsigned integer value of @value. 1777 * 1778 * It is an error to call this function with a @value of any type 1779 * other than %G_VARIANT_TYPE_UINT16. 1780 * 1781 * Return: a #guint16 1782 * 1783 * Since: 2.24 1784 */ 1785 public ushort getUint16() 1786 { 1787 return g_variant_get_uint16(gVariant); 1788 } 1789 1790 /** 1791 * Returns the 32-bit unsigned integer value of @value. 1792 * 1793 * It is an error to call this function with a @value of any type 1794 * other than %G_VARIANT_TYPE_UINT32. 1795 * 1796 * Return: a #guint32 1797 * 1798 * Since: 2.24 1799 */ 1800 public uint getUint32() 1801 { 1802 return g_variant_get_uint32(gVariant); 1803 } 1804 1805 /** 1806 * Returns the 64-bit unsigned integer value of @value. 1807 * 1808 * It is an error to call this function with a @value of any type 1809 * other than %G_VARIANT_TYPE_UINT64. 1810 * 1811 * Return: a #guint64 1812 * 1813 * Since: 2.24 1814 */ 1815 public ulong getUint64() 1816 { 1817 return g_variant_get_uint64(gVariant); 1818 } 1819 1820 /** 1821 * This function is intended to be used by libraries based on #GVariant 1822 * that want to provide g_variant_get()-like functionality to their 1823 * users. 1824 * 1825 * The API is more general than g_variant_get() to allow a wider range 1826 * of possible uses. 1827 * 1828 * @format_string must still point to a valid format string, but it only 1829 * need to be nul-terminated if @endptr is %NULL. If @endptr is 1830 * non-%NULL then it is updated to point to the first character past the 1831 * end of the format string. 1832 * 1833 * @app is a pointer to a #va_list. The arguments, according to 1834 * @format_string, are collected from this #va_list and the list is left 1835 * pointing to the argument following the last. 1836 * 1837 * These two generalisations allow mixing of multiple calls to 1838 * g_variant_new_va() and g_variant_get_va() within a single actual 1839 * varargs call by the user. 1840 * 1841 * @format_string determines the C types that are used for unpacking 1842 * the values and also determines if the values are copied or borrowed, 1843 * see the section on 1844 * [GVariant format strings][gvariant-format-strings-pointers]. 1845 * 1846 * Params: 1847 * formatString = a string that is prefixed with a format string 1848 * endptr = location to store the end pointer, 1849 * or %NULL 1850 * app = a pointer to a #va_list 1851 * 1852 * Since: 2.24 1853 */ 1854 public void getVa(string formatString, string[] endptr, void** app) 1855 { 1856 g_variant_get_va(gVariant, Str.toStringz(formatString), Str.toStringzArray(endptr), app); 1857 } 1858 1859 /** 1860 * Unboxes @value. The result is the #GVariant instance that was 1861 * contained in @value. 1862 * 1863 * Return: the item contained in the variant 1864 * 1865 * Since: 2.24 1866 */ 1867 public Variant getVariant() 1868 { 1869 auto p = g_variant_get_variant(gVariant); 1870 1871 if(p is null) 1872 { 1873 return null; 1874 } 1875 1876 return new Variant(cast(GVariant*) p); 1877 } 1878 1879 /** 1880 * Generates a hash value for a #GVariant instance. 1881 * 1882 * The output of this function is guaranteed to be the same for a given 1883 * value only per-process. It may change between different processor 1884 * architectures or even different versions of GLib. Do not use this 1885 * function as a basis for building protocols or file formats. 1886 * 1887 * The type of @value is #gconstpointer only to allow use of this 1888 * function with #GHashTable. @value must be a #GVariant. 1889 * 1890 * Return: a hash value corresponding to @value 1891 * 1892 * Since: 2.24 1893 */ 1894 public uint hash() 1895 { 1896 return g_variant_hash(gVariant); 1897 } 1898 1899 /** 1900 * Checks if @value is a container. 1901 * 1902 * Return: %TRUE if @value is a container 1903 * 1904 * Since: 2.24 1905 */ 1906 public bool isContainer() 1907 { 1908 return g_variant_is_container(gVariant) != 0; 1909 } 1910 1911 /** 1912 * Checks whether @value has a floating reference count. 1913 * 1914 * This function should only ever be used to assert that a given variant 1915 * is or is not floating, or for debug purposes. To acquire a reference 1916 * to a variant that might be floating, always use g_variant_ref_sink() 1917 * or g_variant_take_ref(). 1918 * 1919 * See g_variant_ref_sink() for more information about floating reference 1920 * counts. 1921 * 1922 * Return: whether @value is floating 1923 * 1924 * Since: 2.26 1925 */ 1926 public bool isFloating() 1927 { 1928 return g_variant_is_floating(gVariant) != 0; 1929 } 1930 1931 /** 1932 * Checks if @value is in normal form. 1933 * 1934 * The main reason to do this is to detect if a given chunk of 1935 * serialised data is in normal form: load the data into a #GVariant 1936 * using g_variant_new_from_data() and then use this function to 1937 * check. 1938 * 1939 * If @value is found to be in normal form then it will be marked as 1940 * being trusted. If the value was already marked as being trusted then 1941 * this function will immediately return %TRUE. 1942 * 1943 * Return: %TRUE if @value is in normal form 1944 * 1945 * Since: 2.24 1946 */ 1947 public bool isNormalForm() 1948 { 1949 return g_variant_is_normal_form(gVariant) != 0; 1950 } 1951 1952 /** 1953 * Checks if a value has a type matching the provided type. 1954 * 1955 * Params: 1956 * type = a #GVariantType 1957 * 1958 * Return: %TRUE if the type of @value matches @type 1959 * 1960 * Since: 2.24 1961 */ 1962 public bool isOfType(VariantType type) 1963 { 1964 return g_variant_is_of_type(gVariant, (type is null) ? null : type.getVariantTypeStruct()) != 0; 1965 } 1966 1967 /** 1968 * Creates a heap-allocated #GVariantIter for iterating over the items 1969 * in @value. 1970 * 1971 * Use g_variant_iter_free() to free the return value when you no longer 1972 * need it. 1973 * 1974 * A reference is taken to @value and will be released only when 1975 * g_variant_iter_free() is called. 1976 * 1977 * Return: a new heap-allocated #GVariantIter 1978 * 1979 * Since: 2.24 1980 */ 1981 public VariantIter iterNew() 1982 { 1983 auto p = g_variant_iter_new(gVariant); 1984 1985 if(p is null) 1986 { 1987 return null; 1988 } 1989 1990 return new VariantIter(cast(GVariantIter*) p); 1991 } 1992 1993 /** 1994 * Looks up a value in a dictionary #GVariant. 1995 * 1996 * This function works with dictionaries of the type a{s*} (and equally 1997 * well with type a{o*}, but we only further discuss the string case 1998 * for sake of clarity). 1999 * 2000 * In the event that @dictionary has the type a{sv}, the @expected_type 2001 * string specifies what type of value is expected to be inside of the 2002 * variant. If the value inside the variant has a different type then 2003 * %NULL is returned. In the event that @dictionary has a value type other 2004 * than v then @expected_type must directly match the key type and it is 2005 * used to unpack the value directly or an error occurs. 2006 * 2007 * In either case, if @key is not found in @dictionary, %NULL is returned. 2008 * 2009 * If the key is found and the value has the correct type, it is 2010 * returned. If @expected_type was specified then any non-%NULL return 2011 * value will have this type. 2012 * 2013 * This function is currently implemented with a linear scan. If you 2014 * plan to do many lookups then #GVariantDict may be more efficient. 2015 * 2016 * Params: 2017 * key = the key to lookup in the dictionary 2018 * expectedType = a #GVariantType, or %NULL 2019 * 2020 * Return: the value of the dictionary key, or %NULL 2021 * 2022 * Since: 2.28 2023 */ 2024 public Variant lookupValue(string key, VariantType expectedType) 2025 { 2026 auto p = g_variant_lookup_value(gVariant, Str.toStringz(key), (expectedType is null) ? null : expectedType.getVariantTypeStruct()); 2027 2028 if(p is null) 2029 { 2030 return null; 2031 } 2032 2033 return new Variant(cast(GVariant*) p); 2034 } 2035 2036 /** 2037 * Determines the number of children in a container #GVariant instance. 2038 * This includes variants, maybes, arrays, tuples and dictionary 2039 * entries. It is an error to call this function on any other type of 2040 * #GVariant. 2041 * 2042 * For variants, the return value is always 1. For values with maybe 2043 * types, it is always zero or one. For arrays, it is the length of the 2044 * array. For tuples it is the number of tuple items (which depends 2045 * only on the type). For dictionary entries, it is always 2 2046 * 2047 * This function is O(1). 2048 * 2049 * Return: the number of children in the container 2050 * 2051 * Since: 2.24 2052 */ 2053 public size_t nChildren() 2054 { 2055 return g_variant_n_children(gVariant); 2056 } 2057 2058 /** 2059 * Pretty-prints @value in the format understood by g_variant_parse(). 2060 * 2061 * The format is described [here][gvariant-text]. 2062 * 2063 * If @type_annotate is %TRUE, then type information is included in 2064 * the output. 2065 * 2066 * Params: 2067 * typeAnnotate = %TRUE if type information should be included in 2068 * the output 2069 * 2070 * Return: a newly-allocated string holding the result. 2071 * 2072 * Since: 2.24 2073 */ 2074 public string print(bool typeAnnotate) 2075 { 2076 return Str.toString(g_variant_print(gVariant, typeAnnotate)); 2077 } 2078 2079 /** 2080 * Behaves as g_variant_print(), but operates on a #GString. 2081 * 2082 * If @string is non-%NULL then it is appended to and returned. Else, 2083 * a new empty #GString is allocated and it is returned. 2084 * 2085 * Params: 2086 * str = a #GString, or %NULL 2087 * typeAnnotate = %TRUE if type information should be included in 2088 * the output 2089 * 2090 * Return: a #GString containing the string 2091 * 2092 * Since: 2.24 2093 */ 2094 public StringG printString(StringG str, bool typeAnnotate) 2095 { 2096 auto p = g_variant_print_string(gVariant, (str is null) ? null : str.getStringGStruct(), typeAnnotate); 2097 2098 if(p is null) 2099 { 2100 return null; 2101 } 2102 2103 return new StringG(cast(GString*) p); 2104 } 2105 2106 /** 2107 * Increases the reference count of @value. 2108 * 2109 * Return: the same @value 2110 * 2111 * Since: 2.24 2112 */ 2113 public Variant doref() 2114 { 2115 auto p = g_variant_ref(gVariant); 2116 2117 if(p is null) 2118 { 2119 return null; 2120 } 2121 2122 return new Variant(cast(GVariant*) p); 2123 } 2124 2125 /** 2126 * #GVariant uses a floating reference count system. All functions with 2127 * names starting with `g_variant_new_` return floating 2128 * references. 2129 * 2130 * Calling g_variant_ref_sink() on a #GVariant with a floating reference 2131 * will convert the floating reference into a full reference. Calling 2132 * g_variant_ref_sink() on a non-floating #GVariant results in an 2133 * additional normal reference being added. 2134 * 2135 * In other words, if the @value is floating, then this call "assumes 2136 * ownership" of the floating reference, converting it to a normal 2137 * reference. If the @value is not floating, then this call adds a 2138 * new normal reference increasing the reference count by one. 2139 * 2140 * All calls that result in a #GVariant instance being inserted into a 2141 * container will call g_variant_ref_sink() on the instance. This means 2142 * that if the value was just created (and has only its floating 2143 * reference) then the container will assume sole ownership of the value 2144 * at that point and the caller will not need to unreference it. This 2145 * makes certain common styles of programming much easier while still 2146 * maintaining normal refcounting semantics in situations where values 2147 * are not floating. 2148 * 2149 * Return: the same @value 2150 * 2151 * Since: 2.24 2152 */ 2153 public Variant refSink() 2154 { 2155 auto p = g_variant_ref_sink(gVariant); 2156 2157 if(p is null) 2158 { 2159 return null; 2160 } 2161 2162 return new Variant(cast(GVariant*) p); 2163 } 2164 2165 /** 2166 * Stores the serialised form of @value at @data. @data should be 2167 * large enough. See g_variant_get_size(). 2168 * 2169 * The stored data is in machine native byte order but may not be in 2170 * fully-normalised form if read from an untrusted source. See 2171 * g_variant_get_normal_form() for a solution. 2172 * 2173 * As with g_variant_get_data(), to be able to deserialise the 2174 * serialised variant successfully, its type and (if the destination 2175 * machine might be different) its endianness must also be available. 2176 * 2177 * This function is approximately O(n) in the size of @data. 2178 * 2179 * Params: 2180 * data = the location to store the serialised data at 2181 * 2182 * Since: 2.24 2183 */ 2184 public void store(void* data) 2185 { 2186 g_variant_store(gVariant, data); 2187 } 2188 2189 /** 2190 * If @value is floating, sink it. Otherwise, do nothing. 2191 * 2192 * Typically you want to use g_variant_ref_sink() in order to 2193 * automatically do the correct thing with respect to floating or 2194 * non-floating references, but there is one specific scenario where 2195 * this function is helpful. 2196 * 2197 * The situation where this function is helpful is when creating an API 2198 * that allows the user to provide a callback function that returns a 2199 * #GVariant. We certainly want to allow the user the flexibility to 2200 * return a non-floating reference from this callback (for the case 2201 * where the value that is being returned already exists). 2202 * 2203 * At the same time, the style of the #GVariant API makes it likely that 2204 * for newly-created #GVariant instances, the user can be saved some 2205 * typing if they are allowed to return a #GVariant with a floating 2206 * reference. 2207 * 2208 * Using this function on the return value of the user's callback allows 2209 * the user to do whichever is more convenient for them. The caller 2210 * will alway receives exactly one full reference to the value: either 2211 * the one that was returned in the first place, or a floating reference 2212 * that has been converted to a full reference. 2213 * 2214 * This function has an odd interaction when combined with 2215 * g_variant_ref_sink() running at the same time in another thread on 2216 * the same #GVariant instance. If g_variant_ref_sink() runs first then 2217 * the result will be that the floating reference is converted to a hard 2218 * reference. If g_variant_take_ref() runs first then the result will 2219 * be that the floating reference is converted to a hard reference and 2220 * an additional reference on top of that one is added. It is best to 2221 * avoid this situation. 2222 * 2223 * Return: the same @value 2224 */ 2225 public Variant takeRef() 2226 { 2227 auto p = g_variant_take_ref(gVariant); 2228 2229 if(p is null) 2230 { 2231 return null; 2232 } 2233 2234 return new Variant(cast(GVariant*) p); 2235 } 2236 2237 /** 2238 * Decreases the reference count of @value. When its reference count 2239 * drops to 0, the memory used by the variant is freed. 2240 * 2241 * Since: 2.24 2242 */ 2243 public void unref() 2244 { 2245 g_variant_unref(gVariant); 2246 } 2247 2248 /** 2249 * Determines if a given string is a valid D-Bus object path. You 2250 * should ensure that a string is a valid D-Bus object path before 2251 * passing it to g_variant_new_object_path(). 2252 * 2253 * A valid object path starts with '/' followed by zero or more 2254 * sequences of characters separated by '/' characters. Each sequence 2255 * must contain only the characters "[A-Z][a-z][0-9]_". No sequence 2256 * (including the one following the final '/' character) may be empty. 2257 * 2258 * Params: 2259 * str = a normal C nul-terminated string 2260 * 2261 * Return: %TRUE if @string is a D-Bus object path 2262 * 2263 * Since: 2.24 2264 */ 2265 public static bool isObjectPath(string str) 2266 { 2267 return g_variant_is_object_path(Str.toStringz(str)) != 0; 2268 } 2269 2270 /** 2271 * Determines if a given string is a valid D-Bus type signature. You 2272 * should ensure that a string is a valid D-Bus type signature before 2273 * passing it to g_variant_new_signature(). 2274 * 2275 * D-Bus type signatures consist of zero or more definite #GVariantType 2276 * strings in sequence. 2277 * 2278 * Params: 2279 * str = a normal C nul-terminated string 2280 * 2281 * Return: %TRUE if @string is a D-Bus type signature 2282 * 2283 * Since: 2.24 2284 */ 2285 public static bool isSignature(string str) 2286 { 2287 return g_variant_is_signature(Str.toStringz(str)) != 0; 2288 } 2289 2290 /** 2291 * Parses a #GVariant from a text representation. 2292 * 2293 * A single #GVariant is parsed from the content of @text. 2294 * 2295 * The format is described [here][gvariant-text]. 2296 * 2297 * The memory at @limit will never be accessed and the parser behaves as 2298 * if the character at @limit is the nul terminator. This has the 2299 * effect of bounding @text. 2300 * 2301 * If @endptr is non-%NULL then @text is permitted to contain data 2302 * following the value that this function parses and @endptr will be 2303 * updated to point to the first character past the end of the text 2304 * parsed by this function. If @endptr is %NULL and there is extra data 2305 * then an error is returned. 2306 * 2307 * If @type is non-%NULL then the value will be parsed to have that 2308 * type. This may result in additional parse errors (in the case that 2309 * the parsed value doesn't fit the type) but may also result in fewer 2310 * errors (in the case that the type would have been ambiguous, such as 2311 * with empty arrays). 2312 * 2313 * In the event that the parsing is successful, the resulting #GVariant 2314 * is returned. It is never floating, and must be freed with 2315 * g_variant_unref(). 2316 * 2317 * In case of any error, %NULL will be returned. If @error is non-%NULL 2318 * then it will be set to reflect the error that occurred. 2319 * 2320 * Officially, the language understood by the parser is "any string 2321 * produced by g_variant_print()". 2322 * 2323 * Params: 2324 * type = a #GVariantType, or %NULL 2325 * text = a string containing a GVariant in text form 2326 * limit = a pointer to the end of @text, or %NULL 2327 * endptr = a location to store the end pointer, or %NULL 2328 * 2329 * Return: a non-floating reference to a #GVariant, or %NULL 2330 * 2331 * Throws: GException on failure. 2332 */ 2333 public static Variant parse(VariantType type, string text, string limit, string[] endptr) 2334 { 2335 GError* err = null; 2336 2337 auto p = g_variant_parse((type is null) ? null : type.getVariantTypeStruct(), Str.toStringz(text), Str.toStringz(limit), Str.toStringzArray(endptr), &err); 2338 2339 if (err !is null) 2340 { 2341 throw new GException( new ErrorG(err) ); 2342 } 2343 2344 if(p is null) 2345 { 2346 return null; 2347 } 2348 2349 return new Variant(cast(GVariant*) p); 2350 } 2351 2352 /** 2353 * Pretty-prints a message showing the context of a #GVariant parse 2354 * error within the string for which parsing was attempted. 2355 * 2356 * The resulting string is suitable for output to the console or other 2357 * monospace media where newlines are treated in the usual way. 2358 * 2359 * The message will typically look something like one of the following: 2360 * 2361 * |[ 2362 * unterminated string constant: 2363 * (1, 2, 3, 'abc 2364 * ^^^^ 2365 * ]| 2366 * 2367 * or 2368 * 2369 * |[ 2370 * unable to find a common type: 2371 * [1, 2, 3, 'str'] 2372 * ^ ^^^^^ 2373 * ]| 2374 * 2375 * The format of the message may change in a future version. 2376 * 2377 * @error must have come from a failed attempt to g_variant_parse() and 2378 * @source_str must be exactly the same string that caused the error. 2379 * If @source_str was not nul-terminated when you passed it to 2380 * g_variant_parse() then you must add nul termination before using this 2381 * function. 2382 * 2383 * Params: 2384 * error = a #GError from the #GVariantParseError domain 2385 * sourceStr = the string that was given to the parser 2386 * 2387 * Return: the printed message 2388 * 2389 * Since: 2.40 2390 */ 2391 public static string parseErrorPrintContext(ErrorG error, string sourceStr) 2392 { 2393 return Str.toString(g_variant_parse_error_print_context((error is null) ? null : error.getErrorGStruct(), Str.toStringz(sourceStr))); 2394 } 2395 2396 public static GQuark parseErrorQuark() 2397 { 2398 return g_variant_parse_error_quark(); 2399 } 2400 2401 /** 2402 * Same as g_variant_error_quark(). 2403 * 2404 * Deprecated: Use g_variant_parse_error_quark() instead. 2405 */ 2406 public static GQuark parserGetErrorQuark() 2407 { 2408 return g_variant_parser_get_error_quark(); 2409 } 2410 }