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. 813 * 814 * Params: 815 * str = a normal UTF-8 nul-terminated string 816 * 817 * Return: a floating reference to a new string #GVariant instance 818 * 819 * Since: 2.24 820 * 821 * Throws: ConstructionException GTK+ fails to create the object. 822 */ 823 public this(string str) 824 { 825 auto p = g_variant_new_string(Str.toStringz(str)); 826 827 if(p is null) 828 { 829 throw new ConstructionException("null returned by new_string"); 830 } 831 832 this(cast(GVariant*) p); 833 } 834 835 /** 836 * Constructs an array of strings #GVariant from the given array of 837 * strings. 838 * 839 * If @length is -1 then @strv is %NULL-terminated. 840 * 841 * Params: 842 * strv = an array of strings 843 * length = the length of @strv, or -1 844 * 845 * Return: a new floating #GVariant instance 846 * 847 * Since: 2.24 848 * 849 * Throws: ConstructionException GTK+ fails to create the object. 850 */ 851 public this(string[] strv) 852 { 853 auto p = g_variant_new_strv(Str.toStringzArray(strv), cast(ptrdiff_t)strv.length); 854 855 if(p is null) 856 { 857 throw new ConstructionException("null returned by new_strv"); 858 } 859 860 this(cast(GVariant*) p); 861 } 862 863 /** 864 * Creates a new tuple #GVariant out of the items in @children. The 865 * type is determined from the types of @children. No entry in the 866 * @children array may be %NULL. 867 * 868 * If @n_children is 0 then the unit tuple is constructed. 869 * 870 * If the @children are floating references (see g_variant_ref_sink()), the 871 * new instance takes ownership of them as if via g_variant_ref_sink(). 872 * 873 * Params: 874 * children = the items to make the tuple out of 875 * nChildren = the length of @children 876 * 877 * Return: a floating reference to a new #GVariant tuple 878 * 879 * Since: 2.24 880 * 881 * Throws: ConstructionException GTK+ fails to create the object. 882 */ 883 public this(Variant[] children) 884 { 885 GVariant*[] childrenArray = new GVariant*[children.length]; 886 for ( int i = 0; i < children.length; i++ ) 887 { 888 childrenArray[i] = children[i].getVariantStruct(); 889 } 890 891 auto p = g_variant_new_tuple(childrenArray.ptr, cast(size_t)children.length); 892 893 if(p is null) 894 { 895 throw new ConstructionException("null returned by new_tuple"); 896 } 897 898 this(cast(GVariant*) p); 899 } 900 901 /** 902 * Creates a new uint16 #GVariant instance. 903 * 904 * Params: 905 * value = a #guint16 value 906 * 907 * Return: a floating reference to a new uint16 #GVariant instance 908 * 909 * Since: 2.24 910 * 911 * Throws: ConstructionException GTK+ fails to create the object. 912 */ 913 public this(ushort value) 914 { 915 auto p = g_variant_new_uint16(value); 916 917 if(p is null) 918 { 919 throw new ConstructionException("null returned by new_uint16"); 920 } 921 922 this(cast(GVariant*) p); 923 } 924 925 /** 926 * Creates a new uint32 #GVariant instance. 927 * 928 * Params: 929 * value = a #guint32 value 930 * 931 * Return: a floating reference to a new uint32 #GVariant instance 932 * 933 * Since: 2.24 934 * 935 * Throws: ConstructionException GTK+ fails to create the object. 936 */ 937 public this(uint value) 938 { 939 auto p = g_variant_new_uint32(value); 940 941 if(p is null) 942 { 943 throw new ConstructionException("null returned by new_uint32"); 944 } 945 946 this(cast(GVariant*) p); 947 } 948 949 /** 950 * Creates a new uint64 #GVariant instance. 951 * 952 * Params: 953 * value = a #guint64 value 954 * 955 * Return: a floating reference to a new uint64 #GVariant instance 956 * 957 * Since: 2.24 958 * 959 * Throws: ConstructionException GTK+ fails to create the object. 960 */ 961 public this(ulong value) 962 { 963 auto p = g_variant_new_uint64(value); 964 965 if(p is null) 966 { 967 throw new ConstructionException("null returned by new_uint64"); 968 } 969 970 this(cast(GVariant*) p); 971 } 972 973 /** 974 * This function is intended to be used by libraries based on 975 * #GVariant that want to provide g_variant_new()-like functionality 976 * to their users. 977 * 978 * The API is more general than g_variant_new() to allow a wider range 979 * of possible uses. 980 * 981 * @format_string must still point to a valid format string, but it only 982 * needs to be nul-terminated if @endptr is %NULL. If @endptr is 983 * non-%NULL then it is updated to point to the first character past the 984 * end of the format string. 985 * 986 * @app is a pointer to a #va_list. The arguments, according to 987 * @format_string, are collected from this #va_list and the list is left 988 * pointing to the argument following the last. 989 * 990 * Note that the arguments in @app must be of the correct width for their 991 * types specified in @format_string when collected into the #va_list. 992 * See the [GVariant varargs documentation][gvariant-varargs. 993 * 994 * These two generalisations allow mixing of multiple calls to 995 * g_variant_new_va() and g_variant_get_va() within a single actual 996 * varargs call by the user. 997 * 998 * The return value will be floating if it was a newly created GVariant 999 * instance (for example, if the format string was "(ii)"). In the case 1000 * that the format_string was '*', '?', 'r', or a format starting with 1001 * '@' then the collected #GVariant pointer will be returned unmodified, 1002 * without adding any additional references. 1003 * 1004 * In order to behave correctly in all cases it is necessary for the 1005 * calling function to g_variant_ref_sink() the return result before 1006 * returning control to the user that originally provided the pointer. 1007 * At this point, the caller will have their own full reference to the 1008 * result. This can also be done by adding the result to a container, 1009 * or by passing it to another g_variant_new() call. 1010 * 1011 * Params: 1012 * formatString = a string that is prefixed with a format string 1013 * endptr = location to store the end pointer, 1014 * or %NULL 1015 * app = a pointer to a #va_list 1016 * 1017 * Return: a new, usually floating, #GVariant 1018 * 1019 * Since: 2.24 1020 * 1021 * Throws: ConstructionException GTK+ fails to create the object. 1022 */ 1023 public this(string formatString, string[] endptr, void** app) 1024 { 1025 auto p = g_variant_new_va(Str.toStringz(formatString), Str.toStringzArray(endptr), app); 1026 1027 if(p is null) 1028 { 1029 throw new ConstructionException("null returned by new_va"); 1030 } 1031 1032 this(cast(GVariant*) p); 1033 } 1034 1035 /** 1036 * Boxes @value. The result is a #GVariant instance representing a 1037 * variant containing the original value. 1038 * 1039 * If @child is a floating reference (see g_variant_ref_sink()), the new 1040 * instance takes ownership of @child. 1041 * 1042 * Params: 1043 * value = a #GVariant instance 1044 * 1045 * Return: a floating reference to a new variant #GVariant instance 1046 * 1047 * Since: 2.24 1048 * 1049 * Throws: ConstructionException GTK+ fails to create the object. 1050 */ 1051 public this(Variant value) 1052 { 1053 auto p = g_variant_new_variant((value is null) ? null : value.getVariantStruct()); 1054 1055 if(p is null) 1056 { 1057 throw new ConstructionException("null returned by new_variant"); 1058 } 1059 1060 this(cast(GVariant*) p); 1061 } 1062 1063 /** 1064 * Performs a byteswapping operation on the contents of @value. The 1065 * result is that all multi-byte numeric data contained in @value is 1066 * byteswapped. That includes 16, 32, and 64bit signed and unsigned 1067 * integers as well as file handles and double precision floating point 1068 * values. 1069 * 1070 * This function is an identity mapping on any value that does not 1071 * contain multi-byte numeric data. That include strings, booleans, 1072 * bytes and containers containing only these things (recursively). 1073 * 1074 * The returned value is always in normal form and is marked as trusted. 1075 * 1076 * Return: the byteswapped form of @value 1077 * 1078 * Since: 2.24 1079 */ 1080 public Variant byteswap() 1081 { 1082 auto p = g_variant_byteswap(gVariant); 1083 1084 if(p is null) 1085 { 1086 return null; 1087 } 1088 1089 return new Variant(cast(GVariant*) p); 1090 } 1091 1092 /** 1093 * Checks if calling g_variant_get() with @format_string on @value would 1094 * be valid from a type-compatibility standpoint. @format_string is 1095 * assumed to be a valid format string (from a syntactic standpoint). 1096 * 1097 * If @copy_only is %TRUE then this function additionally checks that it 1098 * would be safe to call g_variant_unref() on @value immediately after 1099 * the call to g_variant_get() without invalidating the result. This is 1100 * only possible if deep copies are made (ie: there are no pointers to 1101 * the data inside of the soon-to-be-freed #GVariant instance). If this 1102 * check fails then a g_critical() is printed and %FALSE is returned. 1103 * 1104 * This function is meant to be used by functions that wish to provide 1105 * varargs accessors to #GVariant values of uncertain values (eg: 1106 * g_variant_lookup() or g_menu_model_get_item_attribute()). 1107 * 1108 * Params: 1109 * formatString = a valid #GVariant format string 1110 * copyOnly = %TRUE to ensure the format string makes deep copies 1111 * 1112 * Return: %TRUE if @format_string is safe to use 1113 * 1114 * Since: 2.34 1115 */ 1116 public bool checkFormatString(string formatString, bool copyOnly) 1117 { 1118 return g_variant_check_format_string(gVariant, Str.toStringz(formatString), copyOnly) != 0; 1119 } 1120 1121 /** 1122 * Classifies @value according to its top-level type. 1123 * 1124 * Return: the #GVariantClass of @value 1125 * 1126 * Since: 2.24 1127 */ 1128 public GVariantClass classify() 1129 { 1130 return g_variant_classify(gVariant); 1131 } 1132 1133 /** 1134 * Compares @one and @two. 1135 * 1136 * The types of @one and @two are #gconstpointer only to allow use of 1137 * this function with #GTree, #GPtrArray, etc. They must each be a 1138 * #GVariant. 1139 * 1140 * Comparison is only defined for basic types (ie: booleans, numbers, 1141 * strings). For booleans, %FALSE is less than %TRUE. Numbers are 1142 * ordered in the usual way. Strings are in ASCII lexographical order. 1143 * 1144 * It is a programmer error to attempt to compare container values or 1145 * two values that have types that are not exactly equal. For example, 1146 * you cannot compare a 32-bit signed integer with a 32-bit unsigned 1147 * integer. Also note that this function is not particularly 1148 * well-behaved when it comes to comparison of doubles; in particular, 1149 * the handling of incomparable values (ie: NaN) is undefined. 1150 * 1151 * If you only require an equality comparison, g_variant_equal() is more 1152 * general. 1153 * 1154 * Params: 1155 * two = a #GVariant instance of the same type 1156 * 1157 * Return: negative value if a < b; 1158 * zero if a = b; 1159 * positive value if a > b. 1160 * 1161 * Since: 2.26 1162 */ 1163 public int compare(Variant two) 1164 { 1165 return g_variant_compare(gVariant, (two is null) ? null : two.getVariantStruct()); 1166 } 1167 1168 /** 1169 * Similar to g_variant_get_bytestring() except that instead of 1170 * returning a constant string, the string is duplicated. 1171 * 1172 * The return value must be freed using g_free(). 1173 * 1174 * Params: 1175 * length = a pointer to a #gsize, to store 1176 * the length (not including the nul terminator) 1177 * 1178 * Return: a newly allocated string 1179 * 1180 * Since: 2.26 1181 */ 1182 public string dupBytestring() 1183 { 1184 size_t length; 1185 1186 return Str.toString(g_variant_dup_bytestring(gVariant, &length)); 1187 } 1188 1189 /** 1190 * Gets the contents of an array of array of bytes #GVariant. This call 1191 * makes a deep copy; the return result should be released with 1192 * g_strfreev(). 1193 * 1194 * If @length is non-%NULL then the number of elements in the result is 1195 * stored there. In any case, the resulting array will be 1196 * %NULL-terminated. 1197 * 1198 * For an empty array, @length will be set to 0 and a pointer to a 1199 * %NULL pointer will be returned. 1200 * 1201 * Params: 1202 * length = the length of the result, or %NULL 1203 * 1204 * Return: an array of strings 1205 * 1206 * Since: 2.26 1207 */ 1208 public string[] dupBytestringArray() 1209 { 1210 size_t length; 1211 1212 return Str.toStringArray(g_variant_dup_bytestring_array(gVariant, &length)); 1213 } 1214 1215 /** 1216 * Gets the contents of an array of object paths #GVariant. This call 1217 * makes a deep copy; the return result should be released with 1218 * g_strfreev(). 1219 * 1220 * If @length is non-%NULL then the number of elements in the result 1221 * is stored there. In any case, the resulting array will be 1222 * %NULL-terminated. 1223 * 1224 * For an empty array, @length will be set to 0 and a pointer to a 1225 * %NULL pointer will be returned. 1226 * 1227 * Params: 1228 * length = the length of the result, or %NULL 1229 * 1230 * Return: an array of strings 1231 * 1232 * Since: 2.30 1233 */ 1234 public string[] dupObjv() 1235 { 1236 size_t length; 1237 1238 return Str.toStringArray(g_variant_dup_objv(gVariant, &length)); 1239 } 1240 1241 /** 1242 * Similar to g_variant_get_string() except that instead of returning 1243 * a constant string, the string is duplicated. 1244 * 1245 * The string will always be UTF-8 encoded. 1246 * 1247 * The return value must be freed using g_free(). 1248 * 1249 * Params: 1250 * length = a pointer to a #gsize, to store the length 1251 * 1252 * Return: a newly allocated string, UTF-8 encoded 1253 * 1254 * Since: 2.24 1255 */ 1256 public string dupString(out size_t length) 1257 { 1258 return Str.toString(g_variant_dup_string(gVariant, &length)); 1259 } 1260 1261 /** 1262 * Gets the contents of an array of strings #GVariant. This call 1263 * makes a deep copy; the return result should be released with 1264 * g_strfreev(). 1265 * 1266 * If @length is non-%NULL then the number of elements in the result 1267 * is stored there. In any case, the resulting array will be 1268 * %NULL-terminated. 1269 * 1270 * For an empty array, @length will be set to 0 and a pointer to a 1271 * %NULL pointer will be returned. 1272 * 1273 * Params: 1274 * length = the length of the result, or %NULL 1275 * 1276 * Return: an array of strings 1277 * 1278 * Since: 2.24 1279 */ 1280 public string[] dupStrv() 1281 { 1282 size_t length; 1283 1284 return Str.toStringArray(g_variant_dup_strv(gVariant, &length)); 1285 } 1286 1287 /** 1288 * Checks if @one and @two have the same type and value. 1289 * 1290 * The types of @one and @two are #gconstpointer only to allow use of 1291 * this function with #GHashTable. They must each be a #GVariant. 1292 * 1293 * Params: 1294 * two = a #GVariant instance 1295 * 1296 * Return: %TRUE if @one and @two are equal 1297 * 1298 * Since: 2.24 1299 */ 1300 public bool equal(Variant two) 1301 { 1302 return g_variant_equal(gVariant, (two is null) ? null : two.getVariantStruct()) != 0; 1303 } 1304 1305 /** 1306 * Returns the boolean value of @value. 1307 * 1308 * It is an error to call this function with a @value of any type 1309 * other than %G_VARIANT_TYPE_BOOLEAN. 1310 * 1311 * Return: %TRUE or %FALSE 1312 * 1313 * Since: 2.24 1314 */ 1315 public bool getBoolean() 1316 { 1317 return g_variant_get_boolean(gVariant) != 0; 1318 } 1319 1320 /** 1321 * Returns the byte value of @value. 1322 * 1323 * It is an error to call this function with a @value of any type 1324 * other than %G_VARIANT_TYPE_BYTE. 1325 * 1326 * Return: a #guchar 1327 * 1328 * Since: 2.24 1329 */ 1330 public char getByte() 1331 { 1332 return g_variant_get_byte(gVariant); 1333 } 1334 1335 /** 1336 * Returns the string value of a #GVariant instance with an 1337 * array-of-bytes type. The string has no particular encoding. 1338 * 1339 * If the array does not end with a nul terminator character, the empty 1340 * string is returned. For this reason, you can always trust that a 1341 * non-%NULL nul-terminated string will be returned by this function. 1342 * 1343 * If the array contains a nul terminator character somewhere other than 1344 * the last byte then the returned string is the string, up to the first 1345 * such nul character. 1346 * 1347 * It is an error to call this function with a @value that is not an 1348 * array of bytes. 1349 * 1350 * The return value remains valid as long as @value exists. 1351 * 1352 * Return: the constant string 1353 * 1354 * Since: 2.26 1355 */ 1356 public string getBytestring() 1357 { 1358 return Str.toString(g_variant_get_bytestring(gVariant)); 1359 } 1360 1361 /** 1362 * Gets the contents of an array of array of bytes #GVariant. This call 1363 * makes a shallow copy; the return result should be released with 1364 * g_free(), but the individual strings must not be modified. 1365 * 1366 * If @length is non-%NULL then the number of elements in the result is 1367 * stored there. In any case, the resulting array will be 1368 * %NULL-terminated. 1369 * 1370 * For an empty array, @length will be set to 0 and a pointer to a 1371 * %NULL pointer will be returned. 1372 * 1373 * Params: 1374 * length = the length of the result, or %NULL 1375 * 1376 * Return: an array of constant strings 1377 * 1378 * Since: 2.26 1379 */ 1380 public string[] getBytestringArray() 1381 { 1382 size_t length; 1383 1384 return Str.toStringArray(g_variant_get_bytestring_array(gVariant, &length)); 1385 } 1386 1387 /** 1388 * Reads a child item out of a container #GVariant instance. This 1389 * includes variants, maybes, arrays, tuples and dictionary 1390 * entries. It is an error to call this function on any other type of 1391 * #GVariant. 1392 * 1393 * It is an error if @index_ is greater than the number of child items 1394 * in the container. See g_variant_n_children(). 1395 * 1396 * The returned value is never floating. You should free it with 1397 * g_variant_unref() when you're done with it. 1398 * 1399 * This function is O(1). 1400 * 1401 * Params: 1402 * index = the index of the child to fetch 1403 * 1404 * Return: the child at the specified index 1405 * 1406 * Since: 2.24 1407 */ 1408 public Variant getChildValue(size_t index) 1409 { 1410 auto p = g_variant_get_child_value(gVariant, index); 1411 1412 if(p is null) 1413 { 1414 return null; 1415 } 1416 1417 return new Variant(cast(GVariant*) p); 1418 } 1419 1420 /** 1421 * Returns a pointer to the serialised form of a #GVariant instance. 1422 * The returned data may not be in fully-normalised form if read from an 1423 * untrusted source. The returned data must not be freed; it remains 1424 * valid for as long as @value exists. 1425 * 1426 * If @value is a fixed-sized value that was deserialised from a 1427 * corrupted serialised container then %NULL may be returned. In this 1428 * case, the proper thing to do is typically to use the appropriate 1429 * number of nul bytes in place of @value. If @value is not fixed-sized 1430 * then %NULL is never returned. 1431 * 1432 * In the case that @value is already in serialised form, this function 1433 * is O(1). If the value is not already in serialised form, 1434 * serialisation occurs implicitly and is approximately O(n) in the size 1435 * of the result. 1436 * 1437 * To deserialise the data returned by this function, in addition to the 1438 * serialised data, you must know the type of the #GVariant, and (if the 1439 * machine might be different) the endianness of the machine that stored 1440 * it. As a result, file formats or network messages that incorporate 1441 * serialised #GVariants must include this information either 1442 * implicitly (for instance "the file always contains a 1443 * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or 1444 * explicitly (by storing the type and/or endianness in addition to the 1445 * serialised data). 1446 * 1447 * Return: the serialised form of @value, or %NULL 1448 * 1449 * Since: 2.24 1450 */ 1451 public void* getData() 1452 { 1453 return g_variant_get_data(gVariant); 1454 } 1455 1456 /** 1457 * Returns a pointer to the serialised form of a #GVariant instance. 1458 * The semantics of this function are exactly the same as 1459 * g_variant_get_data(), except that the returned #GBytes holds 1460 * a reference to the variant data. 1461 * 1462 * Return: A new #GBytes representing the variant data 1463 * 1464 * Since: 2.36 1465 */ 1466 public Bytes getDataAsBytes() 1467 { 1468 auto p = g_variant_get_data_as_bytes(gVariant); 1469 1470 if(p is null) 1471 { 1472 return null; 1473 } 1474 1475 return new Bytes(cast(GBytes*) p); 1476 } 1477 1478 /** 1479 * Returns the double precision floating point value of @value. 1480 * 1481 * It is an error to call this function with a @value of any type 1482 * other than %G_VARIANT_TYPE_DOUBLE. 1483 * 1484 * Return: a #gdouble 1485 * 1486 * Since: 2.24 1487 */ 1488 public double getDouble() 1489 { 1490 return g_variant_get_double(gVariant); 1491 } 1492 1493 /** 1494 * Provides access to the serialised data for an array of fixed-sized 1495 * items. 1496 * 1497 * @value must be an array with fixed-sized elements. Numeric types are 1498 * fixed-size, as are tuples containing only other fixed-sized types. 1499 * 1500 * @element_size must be the size of a single element in the array, 1501 * as given by the section on 1502 * [serialized data memory][gvariant-serialised-data-memory]. 1503 * 1504 * In particular, arrays of these fixed-sized types can be interpreted 1505 * as an array of the given C type, with @element_size set to the size 1506 * the appropriate type: 1507 * - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) 1508 * - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) 1509 * - %G_VARIANT_TYPE_BYTE: #guchar 1510 * - %G_VARIANT_TYPE_HANDLE: #guint32 1511 * - %G_VARIANT_TYPE_DOUBLE: #gdouble 1512 * 1513 * For example, if calling this function for an array of 32-bit integers, 1514 * you might say sizeof(gint32). This value isn't used except for the purpose 1515 * of a double-check that the form of the serialised data matches the caller's 1516 * expectation. 1517 * 1518 * @n_elements, which must be non-%NULL is set equal to the number of 1519 * items in the array. 1520 * 1521 * Params: 1522 * nElements = a pointer to the location to store the number of items 1523 * elementSize = the size of each element 1524 * 1525 * Return: a pointer to 1526 * the fixed array 1527 * 1528 * Since: 2.24 1529 */ 1530 public void[] getFixedArray(size_t elementSize) 1531 { 1532 size_t nElements; 1533 1534 auto p = g_variant_get_fixed_array(gVariant, &nElements, elementSize); 1535 1536 return p[0 .. nElements]; 1537 } 1538 1539 /** 1540 * Returns the 32-bit signed integer value of @value. 1541 * 1542 * It is an error to call this function with a @value of any type other 1543 * than %G_VARIANT_TYPE_HANDLE. 1544 * 1545 * By convention, handles are indexes into an array of file descriptors 1546 * that are sent alongside a D-Bus message. If you're not interacting 1547 * with D-Bus, you probably don't need them. 1548 * 1549 * Return: a #gint32 1550 * 1551 * Since: 2.24 1552 */ 1553 public int getHandle() 1554 { 1555 return g_variant_get_handle(gVariant); 1556 } 1557 1558 /** 1559 * Returns the 16-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_INT16. 1563 * 1564 * Return: a #gint16 1565 * 1566 * Since: 2.24 1567 */ 1568 public short getInt16() 1569 { 1570 return g_variant_get_int16(gVariant); 1571 } 1572 1573 /** 1574 * Returns the 32-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_INT32. 1578 * 1579 * Return: a #gint32 1580 * 1581 * Since: 2.24 1582 */ 1583 public int getInt32() 1584 { 1585 return g_variant_get_int32(gVariant); 1586 } 1587 1588 /** 1589 * Returns the 64-bit signed integer value of @value. 1590 * 1591 * It is an error to call this function with a @value of any type 1592 * other than %G_VARIANT_TYPE_INT64. 1593 * 1594 * Return: a #gint64 1595 * 1596 * Since: 2.24 1597 */ 1598 public long getInt64() 1599 { 1600 return g_variant_get_int64(gVariant); 1601 } 1602 1603 /** 1604 * Given a maybe-typed #GVariant instance, extract its value. If the 1605 * value is Nothing, then this function returns %NULL. 1606 * 1607 * Return: the contents of @value, or %NULL 1608 * 1609 * Since: 2.24 1610 */ 1611 public Variant getMaybe() 1612 { 1613 auto p = g_variant_get_maybe(gVariant); 1614 1615 if(p is null) 1616 { 1617 return null; 1618 } 1619 1620 return new Variant(cast(GVariant*) p); 1621 } 1622 1623 /** 1624 * Gets a #GVariant instance that has the same value as @value and is 1625 * trusted to be in normal form. 1626 * 1627 * If @value is already trusted to be in normal form then a new 1628 * reference to @value is returned. 1629 * 1630 * If @value is not already trusted, then it is scanned to check if it 1631 * is in normal form. If it is found to be in normal form then it is 1632 * marked as trusted and a new reference to it is returned. 1633 * 1634 * If @value is found not to be in normal form then a new trusted 1635 * #GVariant is created with the same value as @value. 1636 * 1637 * It makes sense to call this function if you've received #GVariant 1638 * data from untrusted sources and you want to ensure your serialised 1639 * output is definitely in normal form. 1640 * 1641 * Return: a trusted #GVariant 1642 * 1643 * Since: 2.24 1644 */ 1645 public Variant getNormalForm() 1646 { 1647 auto p = g_variant_get_normal_form(gVariant); 1648 1649 if(p is null) 1650 { 1651 return null; 1652 } 1653 1654 return new Variant(cast(GVariant*) p); 1655 } 1656 1657 /** 1658 * Gets the contents of an array of object paths #GVariant. This call 1659 * makes a shallow copy; the return result should be released with 1660 * g_free(), but the individual strings must not be modified. 1661 * 1662 * If @length is non-%NULL then the number of elements in the result 1663 * is stored there. In any case, the resulting array will be 1664 * %NULL-terminated. 1665 * 1666 * For an empty array, @length will be set to 0 and a pointer to a 1667 * %NULL pointer will be returned. 1668 * 1669 * Params: 1670 * length = the length of the result, or %NULL 1671 * 1672 * Return: an array of constant strings 1673 * 1674 * Since: 2.30 1675 */ 1676 public string[] getObjv() 1677 { 1678 size_t length; 1679 1680 return Str.toStringArray(g_variant_get_objv(gVariant, &length)); 1681 } 1682 1683 /** 1684 * Determines the number of bytes that would be required to store @value 1685 * with g_variant_store(). 1686 * 1687 * If @value has a fixed-sized type then this function always returned 1688 * that fixed size. 1689 * 1690 * In the case that @value is already in serialised form or the size has 1691 * already been calculated (ie: this function has been called before) 1692 * then this function is O(1). Otherwise, the size is calculated, an 1693 * operation which is approximately O(n) in the number of values 1694 * involved. 1695 * 1696 * Return: the serialised size of @value 1697 * 1698 * Since: 2.24 1699 */ 1700 public size_t getSize() 1701 { 1702 return g_variant_get_size(gVariant); 1703 } 1704 1705 /** 1706 * Returns the string value of a #GVariant instance with a string 1707 * type. This includes the types %G_VARIANT_TYPE_STRING, 1708 * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. 1709 * 1710 * The string will always be UTF-8 encoded. 1711 * 1712 * If @length is non-%NULL then the length of the string (in bytes) is 1713 * returned there. For trusted values, this information is already 1714 * known. For untrusted values, a strlen() will be performed. 1715 * 1716 * It is an error to call this function with a @value of any type 1717 * other than those three. 1718 * 1719 * The return value remains valid as long as @value exists. 1720 * 1721 * Params: 1722 * length = a pointer to a #gsize, 1723 * to store the length 1724 * 1725 * Return: the constant string, UTF-8 encoded 1726 * 1727 * Since: 2.24 1728 */ 1729 public string getString(out size_t length) 1730 { 1731 return Str.toString(g_variant_get_string(gVariant, &length)); 1732 } 1733 1734 /** 1735 * Gets the contents of an array of strings #GVariant. This call 1736 * makes a shallow copy; the return result should be released with 1737 * g_free(), but the individual strings must not be modified. 1738 * 1739 * If @length is non-%NULL then the number of elements in the result 1740 * is stored there. In any case, the resulting array will be 1741 * %NULL-terminated. 1742 * 1743 * For an empty array, @length will be set to 0 and a pointer to a 1744 * %NULL pointer will be returned. 1745 * 1746 * Params: 1747 * length = the length of the result, or %NULL 1748 * 1749 * Return: an array of constant strings 1750 * 1751 * Since: 2.24 1752 */ 1753 public string[] getStrv() 1754 { 1755 size_t length; 1756 1757 return Str.toStringArray(g_variant_get_strv(gVariant, &length)); 1758 } 1759 1760 /** 1761 * Determines the type of @value. 1762 * 1763 * The return value is valid for the lifetime of @value and must not 1764 * be freed. 1765 * 1766 * Return: a #GVariantType 1767 * 1768 * Since: 2.24 1769 */ 1770 public VariantType getType() 1771 { 1772 auto p = g_variant_get_type(gVariant); 1773 1774 if(p is null) 1775 { 1776 return null; 1777 } 1778 1779 return new VariantType(cast(GVariantType*) p); 1780 } 1781 1782 /** 1783 * Returns the type string of @value. Unlike the result of calling 1784 * g_variant_type_peek_string(), this string is nul-terminated. This 1785 * string belongs to #GVariant and must not be freed. 1786 * 1787 * Return: the type string for the type of @value 1788 * 1789 * Since: 2.24 1790 */ 1791 public string getTypeString() 1792 { 1793 return Str.toString(g_variant_get_type_string(gVariant)); 1794 } 1795 1796 /** 1797 * Returns the 16-bit unsigned integer value of @value. 1798 * 1799 * It is an error to call this function with a @value of any type 1800 * other than %G_VARIANT_TYPE_UINT16. 1801 * 1802 * Return: a #guint16 1803 * 1804 * Since: 2.24 1805 */ 1806 public ushort getUint16() 1807 { 1808 return g_variant_get_uint16(gVariant); 1809 } 1810 1811 /** 1812 * Returns the 32-bit unsigned integer value of @value. 1813 * 1814 * It is an error to call this function with a @value of any type 1815 * other than %G_VARIANT_TYPE_UINT32. 1816 * 1817 * Return: a #guint32 1818 * 1819 * Since: 2.24 1820 */ 1821 public uint getUint32() 1822 { 1823 return g_variant_get_uint32(gVariant); 1824 } 1825 1826 /** 1827 * Returns the 64-bit unsigned integer value of @value. 1828 * 1829 * It is an error to call this function with a @value of any type 1830 * other than %G_VARIANT_TYPE_UINT64. 1831 * 1832 * Return: a #guint64 1833 * 1834 * Since: 2.24 1835 */ 1836 public ulong getUint64() 1837 { 1838 return g_variant_get_uint64(gVariant); 1839 } 1840 1841 /** 1842 * This function is intended to be used by libraries based on #GVariant 1843 * that want to provide g_variant_get()-like functionality to their 1844 * users. 1845 * 1846 * The API is more general than g_variant_get() to allow a wider range 1847 * of possible uses. 1848 * 1849 * @format_string must still point to a valid format string, but it only 1850 * need to be nul-terminated if @endptr is %NULL. If @endptr is 1851 * non-%NULL then it is updated to point to the first character past the 1852 * end of the format string. 1853 * 1854 * @app is a pointer to a #va_list. The arguments, according to 1855 * @format_string, are collected from this #va_list and the list is left 1856 * pointing to the argument following the last. 1857 * 1858 * These two generalisations allow mixing of multiple calls to 1859 * g_variant_new_va() and g_variant_get_va() within a single actual 1860 * varargs call by the user. 1861 * 1862 * @format_string determines the C types that are used for unpacking 1863 * the values and also determines if the values are copied or borrowed, 1864 * see the section on 1865 * [GVariant format strings][gvariant-format-strings-pointers]. 1866 * 1867 * Params: 1868 * formatString = a string that is prefixed with a format string 1869 * endptr = location to store the end pointer, 1870 * or %NULL 1871 * app = a pointer to a #va_list 1872 * 1873 * Since: 2.24 1874 */ 1875 public void getVa(string formatString, string[] endptr, void** app) 1876 { 1877 g_variant_get_va(gVariant, Str.toStringz(formatString), Str.toStringzArray(endptr), app); 1878 } 1879 1880 /** 1881 * Unboxes @value. The result is the #GVariant instance that was 1882 * contained in @value. 1883 * 1884 * Return: the item contained in the variant 1885 * 1886 * Since: 2.24 1887 */ 1888 public Variant getVariant() 1889 { 1890 auto p = g_variant_get_variant(gVariant); 1891 1892 if(p is null) 1893 { 1894 return null; 1895 } 1896 1897 return new Variant(cast(GVariant*) p); 1898 } 1899 1900 /** 1901 * Generates a hash value for a #GVariant instance. 1902 * 1903 * The output of this function is guaranteed to be the same for a given 1904 * value only per-process. It may change between different processor 1905 * architectures or even different versions of GLib. Do not use this 1906 * function as a basis for building protocols or file formats. 1907 * 1908 * The type of @value is #gconstpointer only to allow use of this 1909 * function with #GHashTable. @value must be a #GVariant. 1910 * 1911 * Return: a hash value corresponding to @value 1912 * 1913 * Since: 2.24 1914 */ 1915 public uint hash() 1916 { 1917 return g_variant_hash(gVariant); 1918 } 1919 1920 /** 1921 * Checks if @value is a container. 1922 * 1923 * Return: %TRUE if @value is a container 1924 * 1925 * Since: 2.24 1926 */ 1927 public bool isContainer() 1928 { 1929 return g_variant_is_container(gVariant) != 0; 1930 } 1931 1932 /** 1933 * Checks whether @value has a floating reference count. 1934 * 1935 * This function should only ever be used to assert that a given variant 1936 * is or is not floating, or for debug purposes. To acquire a reference 1937 * to a variant that might be floating, always use g_variant_ref_sink() 1938 * or g_variant_take_ref(). 1939 * 1940 * See g_variant_ref_sink() for more information about floating reference 1941 * counts. 1942 * 1943 * Return: whether @value is floating 1944 * 1945 * Since: 2.26 1946 */ 1947 public bool isFloating() 1948 { 1949 return g_variant_is_floating(gVariant) != 0; 1950 } 1951 1952 /** 1953 * Checks if @value is in normal form. 1954 * 1955 * The main reason to do this is to detect if a given chunk of 1956 * serialised data is in normal form: load the data into a #GVariant 1957 * using g_variant_new_from_data() and then use this function to 1958 * check. 1959 * 1960 * If @value is found to be in normal form then it will be marked as 1961 * being trusted. If the value was already marked as being trusted then 1962 * this function will immediately return %TRUE. 1963 * 1964 * Return: %TRUE if @value is in normal form 1965 * 1966 * Since: 2.24 1967 */ 1968 public bool isNormalForm() 1969 { 1970 return g_variant_is_normal_form(gVariant) != 0; 1971 } 1972 1973 /** 1974 * Checks if a value has a type matching the provided type. 1975 * 1976 * Params: 1977 * type = a #GVariantType 1978 * 1979 * Return: %TRUE if the type of @value matches @type 1980 * 1981 * Since: 2.24 1982 */ 1983 public bool isOfType(VariantType type) 1984 { 1985 return g_variant_is_of_type(gVariant, (type is null) ? null : type.getVariantTypeStruct()) != 0; 1986 } 1987 1988 /** 1989 * Creates a heap-allocated #GVariantIter for iterating over the items 1990 * in @value. 1991 * 1992 * Use g_variant_iter_free() to free the return value when you no longer 1993 * need it. 1994 * 1995 * A reference is taken to @value and will be released only when 1996 * g_variant_iter_free() is called. 1997 * 1998 * Return: a new heap-allocated #GVariantIter 1999 * 2000 * Since: 2.24 2001 */ 2002 public VariantIter iterNew() 2003 { 2004 auto p = g_variant_iter_new(gVariant); 2005 2006 if(p is null) 2007 { 2008 return null; 2009 } 2010 2011 return new VariantIter(cast(GVariantIter*) p); 2012 } 2013 2014 /** 2015 * Looks up a value in a dictionary #GVariant. 2016 * 2017 * This function works with dictionaries of the type a{s*} (and equally 2018 * well with type a{o*}, but we only further discuss the string case 2019 * for sake of clarity). 2020 * 2021 * In the event that @dictionary has the type a{sv}, the @expected_type 2022 * string specifies what type of value is expected to be inside of the 2023 * variant. If the value inside the variant has a different type then 2024 * %NULL is returned. In the event that @dictionary has a value type other 2025 * than v then @expected_type must directly match the key type and it is 2026 * used to unpack the value directly or an error occurs. 2027 * 2028 * In either case, if @key is not found in @dictionary, %NULL is returned. 2029 * 2030 * If the key is found and the value has the correct type, it is 2031 * returned. If @expected_type was specified then any non-%NULL return 2032 * value will have this type. 2033 * 2034 * This function is currently implemented with a linear scan. If you 2035 * plan to do many lookups then #GVariantDict may be more efficient. 2036 * 2037 * Params: 2038 * key = the key to lookup in the dictionary 2039 * expectedType = a #GVariantType, or %NULL 2040 * 2041 * Return: the value of the dictionary key, or %NULL 2042 * 2043 * Since: 2.28 2044 */ 2045 public Variant lookupValue(string key, VariantType expectedType) 2046 { 2047 auto p = g_variant_lookup_value(gVariant, Str.toStringz(key), (expectedType is null) ? null : expectedType.getVariantTypeStruct()); 2048 2049 if(p is null) 2050 { 2051 return null; 2052 } 2053 2054 return new Variant(cast(GVariant*) p); 2055 } 2056 2057 /** 2058 * Determines the number of children in a container #GVariant instance. 2059 * This includes variants, maybes, arrays, tuples and dictionary 2060 * entries. It is an error to call this function on any other type of 2061 * #GVariant. 2062 * 2063 * For variants, the return value is always 1. For values with maybe 2064 * types, it is always zero or one. For arrays, it is the length of the 2065 * array. For tuples it is the number of tuple items (which depends 2066 * only on the type). For dictionary entries, it is always 2 2067 * 2068 * This function is O(1). 2069 * 2070 * Return: the number of children in the container 2071 * 2072 * Since: 2.24 2073 */ 2074 public size_t nChildren() 2075 { 2076 return g_variant_n_children(gVariant); 2077 } 2078 2079 /** 2080 * Pretty-prints @value in the format understood by g_variant_parse(). 2081 * 2082 * The format is described [here][gvariant-text]. 2083 * 2084 * If @type_annotate is %TRUE, then type information is included in 2085 * the output. 2086 * 2087 * Params: 2088 * typeAnnotate = %TRUE if type information should be included in 2089 * the output 2090 * 2091 * Return: a newly-allocated string holding the result. 2092 * 2093 * Since: 2.24 2094 */ 2095 public string print(bool typeAnnotate) 2096 { 2097 return Str.toString(g_variant_print(gVariant, typeAnnotate)); 2098 } 2099 2100 /** 2101 * Behaves as g_variant_print(), but operates on a #GString. 2102 * 2103 * If @string is non-%NULL then it is appended to and returned. Else, 2104 * a new empty #GString is allocated and it is returned. 2105 * 2106 * Params: 2107 * str = a #GString, or %NULL 2108 * typeAnnotate = %TRUE if type information should be included in 2109 * the output 2110 * 2111 * Return: a #GString containing the string 2112 * 2113 * Since: 2.24 2114 */ 2115 public StringG printString(StringG str, bool typeAnnotate) 2116 { 2117 auto p = g_variant_print_string(gVariant, (str is null) ? null : str.getStringGStruct(), typeAnnotate); 2118 2119 if(p is null) 2120 { 2121 return null; 2122 } 2123 2124 return new StringG(cast(GString*) p); 2125 } 2126 2127 /** 2128 * Increases the reference count of @value. 2129 * 2130 * Return: the same @value 2131 * 2132 * Since: 2.24 2133 */ 2134 public Variant doref() 2135 { 2136 auto p = g_variant_ref(gVariant); 2137 2138 if(p is null) 2139 { 2140 return null; 2141 } 2142 2143 return new Variant(cast(GVariant*) p); 2144 } 2145 2146 /** 2147 * #GVariant uses a floating reference count system. All functions with 2148 * names starting with `g_variant_new_` return floating 2149 * references. 2150 * 2151 * Calling g_variant_ref_sink() on a #GVariant with a floating reference 2152 * will convert the floating reference into a full reference. Calling 2153 * g_variant_ref_sink() on a non-floating #GVariant results in an 2154 * additional normal reference being added. 2155 * 2156 * In other words, if the @value is floating, then this call "assumes 2157 * ownership" of the floating reference, converting it to a normal 2158 * reference. If the @value is not floating, then this call adds a 2159 * new normal reference increasing the reference count by one. 2160 * 2161 * All calls that result in a #GVariant instance being inserted into a 2162 * container will call g_variant_ref_sink() on the instance. This means 2163 * that if the value was just created (and has only its floating 2164 * reference) then the container will assume sole ownership of the value 2165 * at that point and the caller will not need to unreference it. This 2166 * makes certain common styles of programming much easier while still 2167 * maintaining normal refcounting semantics in situations where values 2168 * are not floating. 2169 * 2170 * Return: the same @value 2171 * 2172 * Since: 2.24 2173 */ 2174 public Variant refSink() 2175 { 2176 auto p = g_variant_ref_sink(gVariant); 2177 2178 if(p is null) 2179 { 2180 return null; 2181 } 2182 2183 return new Variant(cast(GVariant*) p); 2184 } 2185 2186 /** 2187 * Stores the serialised form of @value at @data. @data should be 2188 * large enough. See g_variant_get_size(). 2189 * 2190 * The stored data is in machine native byte order but may not be in 2191 * fully-normalised form if read from an untrusted source. See 2192 * g_variant_get_normal_form() for a solution. 2193 * 2194 * As with g_variant_get_data(), to be able to deserialise the 2195 * serialised variant successfully, its type and (if the destination 2196 * machine might be different) its endianness must also be available. 2197 * 2198 * This function is approximately O(n) in the size of @data. 2199 * 2200 * Params: 2201 * data = the location to store the serialised data at 2202 * 2203 * Since: 2.24 2204 */ 2205 public void store(void* data) 2206 { 2207 g_variant_store(gVariant, data); 2208 } 2209 2210 /** 2211 * If @value is floating, sink it. Otherwise, do nothing. 2212 * 2213 * Typically you want to use g_variant_ref_sink() in order to 2214 * automatically do the correct thing with respect to floating or 2215 * non-floating references, but there is one specific scenario where 2216 * this function is helpful. 2217 * 2218 * The situation where this function is helpful is when creating an API 2219 * that allows the user to provide a callback function that returns a 2220 * #GVariant. We certainly want to allow the user the flexibility to 2221 * return a non-floating reference from this callback (for the case 2222 * where the value that is being returned already exists). 2223 * 2224 * At the same time, the style of the #GVariant API makes it likely that 2225 * for newly-created #GVariant instances, the user can be saved some 2226 * typing if they are allowed to return a #GVariant with a floating 2227 * reference. 2228 * 2229 * Using this function on the return value of the user's callback allows 2230 * the user to do whichever is more convenient for them. The caller 2231 * will alway receives exactly one full reference to the value: either 2232 * the one that was returned in the first place, or a floating reference 2233 * that has been converted to a full reference. 2234 * 2235 * This function has an odd interaction when combined with 2236 * g_variant_ref_sink() running at the same time in another thread on 2237 * the same #GVariant instance. If g_variant_ref_sink() runs first then 2238 * the result will be that the floating reference is converted to a hard 2239 * reference. If g_variant_take_ref() runs first then the result will 2240 * be that the floating reference is converted to a hard reference and 2241 * an additional reference on top of that one is added. It is best to 2242 * avoid this situation. 2243 * 2244 * Return: the same @value 2245 */ 2246 public Variant takeRef() 2247 { 2248 auto p = g_variant_take_ref(gVariant); 2249 2250 if(p is null) 2251 { 2252 return null; 2253 } 2254 2255 return new Variant(cast(GVariant*) p); 2256 } 2257 2258 /** 2259 * Decreases the reference count of @value. When its reference count 2260 * drops to 0, the memory used by the variant is freed. 2261 * 2262 * Since: 2.24 2263 */ 2264 public void unref() 2265 { 2266 g_variant_unref(gVariant); 2267 } 2268 2269 /** 2270 * Determines if a given string is a valid D-Bus object path. You 2271 * should ensure that a string is a valid D-Bus object path before 2272 * passing it to g_variant_new_object_path(). 2273 * 2274 * A valid object path starts with '/' followed by zero or more 2275 * sequences of characters separated by '/' characters. Each sequence 2276 * must contain only the characters "[A-Z][a-z][0-9]_". No sequence 2277 * (including the one following the final '/' character) may be empty. 2278 * 2279 * Params: 2280 * str = a normal C nul-terminated string 2281 * 2282 * Return: %TRUE if @string is a D-Bus object path 2283 * 2284 * Since: 2.24 2285 */ 2286 public static bool isObjectPath(string str) 2287 { 2288 return g_variant_is_object_path(Str.toStringz(str)) != 0; 2289 } 2290 2291 /** 2292 * Determines if a given string is a valid D-Bus type signature. You 2293 * should ensure that a string is a valid D-Bus type signature before 2294 * passing it to g_variant_new_signature(). 2295 * 2296 * D-Bus type signatures consist of zero or more definite #GVariantType 2297 * strings in sequence. 2298 * 2299 * Params: 2300 * str = a normal C nul-terminated string 2301 * 2302 * Return: %TRUE if @string is a D-Bus type signature 2303 * 2304 * Since: 2.24 2305 */ 2306 public static bool isSignature(string str) 2307 { 2308 return g_variant_is_signature(Str.toStringz(str)) != 0; 2309 } 2310 2311 /** 2312 * Parses a #GVariant from a text representation. 2313 * 2314 * A single #GVariant is parsed from the content of @text. 2315 * 2316 * The format is described [here][gvariant-text]. 2317 * 2318 * The memory at @limit will never be accessed and the parser behaves as 2319 * if the character at @limit is the nul terminator. This has the 2320 * effect of bounding @text. 2321 * 2322 * If @endptr is non-%NULL then @text is permitted to contain data 2323 * following the value that this function parses and @endptr will be 2324 * updated to point to the first character past the end of the text 2325 * parsed by this function. If @endptr is %NULL and there is extra data 2326 * then an error is returned. 2327 * 2328 * If @type is non-%NULL then the value will be parsed to have that 2329 * type. This may result in additional parse errors (in the case that 2330 * the parsed value doesn't fit the type) but may also result in fewer 2331 * errors (in the case that the type would have been ambiguous, such as 2332 * with empty arrays). 2333 * 2334 * In the event that the parsing is successful, the resulting #GVariant 2335 * is returned. 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 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); 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 return Str.toString(g_variant_parse_error_print_context((error is null) ? null : error.getErrorGStruct(), Str.toStringz(sourceStr))); 2414 } 2415 2416 public static GQuark parseErrorQuark() 2417 { 2418 return g_variant_parse_error_quark(); 2419 } 2420 2421 /** 2422 * Same as g_variant_error_quark(). 2423 * 2424 * Deprecated: Use g_variant_parse_error_quark() instead. 2425 */ 2426 public static GQuark parserGetErrorQuark() 2427 { 2428 return g_variant_parser_get_error_quark(); 2429 } 2430 }