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