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 * Return: a newly allocated string 1175 * 1176 * Since: 2.26 1177 */ 1178 public string dupBytestring() 1179 { 1180 size_t length; 1181 1182 return Str.toString(g_variant_dup_bytestring(gVariant, &length)); 1183 } 1184 1185 /** 1186 * Gets the contents of an array of array of bytes #GVariant. This call 1187 * makes a deep copy; the return result should be released with 1188 * g_strfreev(). 1189 * 1190 * If @length is non-%NULL then the number of elements in the result is 1191 * stored there. In any case, the resulting array will be 1192 * %NULL-terminated. 1193 * 1194 * For an empty array, @length will be set to 0 and a pointer to a 1195 * %NULL pointer will be returned. 1196 * 1197 * Return: an array of strings 1198 * 1199 * Since: 2.26 1200 */ 1201 public string[] dupBytestringArray() 1202 { 1203 size_t length; 1204 1205 return Str.toStringArray(g_variant_dup_bytestring_array(gVariant, &length)); 1206 } 1207 1208 /** 1209 * Gets the contents of an array of object paths #GVariant. This call 1210 * makes a deep copy; the return result should be released with 1211 * g_strfreev(). 1212 * 1213 * If @length is non-%NULL then the number of elements in the result 1214 * is stored there. In any case, the resulting array will be 1215 * %NULL-terminated. 1216 * 1217 * For an empty array, @length will be set to 0 and a pointer to a 1218 * %NULL pointer will be returned. 1219 * 1220 * Return: an array of strings 1221 * 1222 * Since: 2.30 1223 */ 1224 public string[] dupObjv() 1225 { 1226 size_t length; 1227 1228 return Str.toStringArray(g_variant_dup_objv(gVariant, &length)); 1229 } 1230 1231 /** 1232 * Similar to g_variant_get_string() except that instead of returning 1233 * a constant string, the string is duplicated. 1234 * 1235 * The string will always be UTF-8 encoded. 1236 * 1237 * The return value must be freed using g_free(). 1238 * 1239 * Params: 1240 * length = a pointer to a #gsize, to store the length 1241 * 1242 * Return: a newly allocated string, UTF-8 encoded 1243 * 1244 * Since: 2.24 1245 */ 1246 public string dupString(out size_t length) 1247 { 1248 return Str.toString(g_variant_dup_string(gVariant, &length)); 1249 } 1250 1251 /** 1252 * Gets the contents of an array of strings #GVariant. This call 1253 * makes a deep copy; the return result should be released with 1254 * g_strfreev(). 1255 * 1256 * If @length is non-%NULL then the number of elements in the result 1257 * is stored there. In any case, the resulting array will be 1258 * %NULL-terminated. 1259 * 1260 * For an empty array, @length will be set to 0 and a pointer to a 1261 * %NULL pointer will be returned. 1262 * 1263 * Return: an array of strings 1264 * 1265 * Since: 2.24 1266 */ 1267 public string[] dupStrv() 1268 { 1269 size_t length; 1270 1271 return Str.toStringArray(g_variant_dup_strv(gVariant, &length)); 1272 } 1273 1274 /** 1275 * Checks if @one and @two have the same type and value. 1276 * 1277 * The types of @one and @two are #gconstpointer only to allow use of 1278 * this function with #GHashTable. They must each be a #GVariant. 1279 * 1280 * Params: 1281 * two = a #GVariant instance 1282 * 1283 * Return: %TRUE if @one and @two are equal 1284 * 1285 * Since: 2.24 1286 */ 1287 public bool equal(Variant two) 1288 { 1289 return g_variant_equal(gVariant, (two is null) ? null : two.getVariantStruct()) != 0; 1290 } 1291 1292 /** 1293 * Returns the boolean value of @value. 1294 * 1295 * It is an error to call this function with a @value of any type 1296 * other than %G_VARIANT_TYPE_BOOLEAN. 1297 * 1298 * Return: %TRUE or %FALSE 1299 * 1300 * Since: 2.24 1301 */ 1302 public bool getBoolean() 1303 { 1304 return g_variant_get_boolean(gVariant) != 0; 1305 } 1306 1307 /** 1308 * Returns the byte value of @value. 1309 * 1310 * It is an error to call this function with a @value of any type 1311 * other than %G_VARIANT_TYPE_BYTE. 1312 * 1313 * Return: a #guchar 1314 * 1315 * Since: 2.24 1316 */ 1317 public char getByte() 1318 { 1319 return g_variant_get_byte(gVariant); 1320 } 1321 1322 /** 1323 * Returns the string value of a #GVariant instance with an 1324 * array-of-bytes type. The string has no particular encoding. 1325 * 1326 * If the array does not end with a nul terminator character, the empty 1327 * string is returned. For this reason, you can always trust that a 1328 * non-%NULL nul-terminated string will be returned by this function. 1329 * 1330 * If the array contains a nul terminator character somewhere other than 1331 * the last byte then the returned string is the string, up to the first 1332 * such nul character. 1333 * 1334 * It is an error to call this function with a @value that is not an 1335 * array of bytes. 1336 * 1337 * The return value remains valid as long as @value exists. 1338 * 1339 * Return: the constant string 1340 * 1341 * Since: 2.26 1342 */ 1343 public string getBytestring() 1344 { 1345 return Str.toString(g_variant_get_bytestring(gVariant)); 1346 } 1347 1348 /** 1349 * Gets the contents of an array of array of bytes #GVariant. This call 1350 * makes a shallow copy; the return result should be released with 1351 * g_free(), but the individual strings must not be modified. 1352 * 1353 * If @length is non-%NULL then the number of elements in the result is 1354 * stored there. In any case, the resulting array will be 1355 * %NULL-terminated. 1356 * 1357 * For an empty array, @length will be set to 0 and a pointer to a 1358 * %NULL pointer will be returned. 1359 * 1360 * Return: an array of constant strings 1361 * 1362 * Since: 2.26 1363 */ 1364 public string[] getBytestringArray() 1365 { 1366 size_t length; 1367 1368 return Str.toStringArray(g_variant_get_bytestring_array(gVariant, &length)); 1369 } 1370 1371 /** 1372 * Reads a child item out of a container #GVariant instance. This 1373 * includes variants, maybes, arrays, tuples and dictionary 1374 * entries. It is an error to call this function on any other type of 1375 * #GVariant. 1376 * 1377 * It is an error if @index_ is greater than the number of child items 1378 * in the container. See g_variant_n_children(). 1379 * 1380 * The returned value is never floating. You should free it with 1381 * g_variant_unref() when you're done with it. 1382 * 1383 * This function is O(1). 1384 * 1385 * Params: 1386 * index = the index of the child to fetch 1387 * 1388 * Return: the child at the specified index 1389 * 1390 * Since: 2.24 1391 */ 1392 public Variant getChildValue(size_t index) 1393 { 1394 auto p = g_variant_get_child_value(gVariant, index); 1395 1396 if(p is null) 1397 { 1398 return null; 1399 } 1400 1401 return new Variant(cast(GVariant*) p); 1402 } 1403 1404 /** 1405 * Returns a pointer to the serialised form of a #GVariant instance. 1406 * The returned data may not be in fully-normalised form if read from an 1407 * untrusted source. The returned data must not be freed; it remains 1408 * valid for as long as @value exists. 1409 * 1410 * If @value is a fixed-sized value that was deserialised from a 1411 * corrupted serialised container then %NULL may be returned. In this 1412 * case, the proper thing to do is typically to use the appropriate 1413 * number of nul bytes in place of @value. If @value is not fixed-sized 1414 * then %NULL is never returned. 1415 * 1416 * In the case that @value is already in serialised form, this function 1417 * is O(1). If the value is not already in serialised form, 1418 * serialisation occurs implicitly and is approximately O(n) in the size 1419 * of the result. 1420 * 1421 * To deserialise the data returned by this function, in addition to the 1422 * serialised data, you must know the type of the #GVariant, and (if the 1423 * machine might be different) the endianness of the machine that stored 1424 * it. As a result, file formats or network messages that incorporate 1425 * serialised #GVariants must include this information either 1426 * implicitly (for instance "the file always contains a 1427 * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or 1428 * explicitly (by storing the type and/or endianness in addition to the 1429 * serialised data). 1430 * 1431 * Return: the serialised form of @value, or %NULL 1432 * 1433 * Since: 2.24 1434 */ 1435 public void* getData() 1436 { 1437 return g_variant_get_data(gVariant); 1438 } 1439 1440 /** 1441 * Returns a pointer to the serialised form of a #GVariant instance. 1442 * The semantics of this function are exactly the same as 1443 * g_variant_get_data(), except that the returned #GBytes holds 1444 * a reference to the variant data. 1445 * 1446 * Return: A new #GBytes representing the variant data 1447 * 1448 * Since: 2.36 1449 */ 1450 public Bytes getDataAsBytes() 1451 { 1452 auto p = g_variant_get_data_as_bytes(gVariant); 1453 1454 if(p is null) 1455 { 1456 return null; 1457 } 1458 1459 return new Bytes(cast(GBytes*) p); 1460 } 1461 1462 /** 1463 * Returns the double precision floating point value of @value. 1464 * 1465 * It is an error to call this function with a @value of any type 1466 * other than %G_VARIANT_TYPE_DOUBLE. 1467 * 1468 * Return: a #gdouble 1469 * 1470 * Since: 2.24 1471 */ 1472 public double getDouble() 1473 { 1474 return g_variant_get_double(gVariant); 1475 } 1476 1477 /** 1478 * Provides access to the serialised data for an array of fixed-sized 1479 * items. 1480 * 1481 * @value must be an array with fixed-sized elements. Numeric types are 1482 * fixed-size, as are tuples containing only other fixed-sized types. 1483 * 1484 * @element_size must be the size of a single element in the array, 1485 * as given by the section on 1486 * [serialized data memory][gvariant-serialised-data-memory]. 1487 * 1488 * In particular, arrays of these fixed-sized types can be interpreted 1489 * as an array of the given C type, with @element_size set to the size 1490 * the appropriate type: 1491 * - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) 1492 * - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) 1493 * - %G_VARIANT_TYPE_BYTE: #guchar 1494 * - %G_VARIANT_TYPE_HANDLE: #guint32 1495 * - %G_VARIANT_TYPE_DOUBLE: #gdouble 1496 * 1497 * For example, if calling this function for an array of 32-bit integers, 1498 * you might say sizeof(gint32). This value isn't used except for the purpose 1499 * of a double-check that the form of the serialised data matches the caller's 1500 * expectation. 1501 * 1502 * @n_elements, which must be non-%NULL is set equal to the number of 1503 * items in the array. 1504 * 1505 * Params: 1506 * elementSize = the size of each element 1507 * 1508 * Return: a pointer to 1509 * the fixed array 1510 * 1511 * Since: 2.24 1512 */ 1513 public void[] getFixedArray(size_t elementSize) 1514 { 1515 size_t nElements; 1516 1517 auto p = g_variant_get_fixed_array(gVariant, &nElements, elementSize); 1518 1519 return p[0 .. nElements]; 1520 } 1521 1522 /** 1523 * Returns the 32-bit signed integer value of @value. 1524 * 1525 * It is an error to call this function with a @value of any type other 1526 * than %G_VARIANT_TYPE_HANDLE. 1527 * 1528 * By convention, handles are indexes into an array of file descriptors 1529 * that are sent alongside a D-Bus message. If you're not interacting 1530 * with D-Bus, you probably don't need them. 1531 * 1532 * Return: a #gint32 1533 * 1534 * Since: 2.24 1535 */ 1536 public int getHandle() 1537 { 1538 return g_variant_get_handle(gVariant); 1539 } 1540 1541 /** 1542 * Returns the 16-bit signed integer value of @value. 1543 * 1544 * It is an error to call this function with a @value of any type 1545 * other than %G_VARIANT_TYPE_INT16. 1546 * 1547 * Return: a #gint16 1548 * 1549 * Since: 2.24 1550 */ 1551 public short getInt16() 1552 { 1553 return g_variant_get_int16(gVariant); 1554 } 1555 1556 /** 1557 * Returns the 32-bit signed integer value of @value. 1558 * 1559 * It is an error to call this function with a @value of any type 1560 * other than %G_VARIANT_TYPE_INT32. 1561 * 1562 * Return: a #gint32 1563 * 1564 * Since: 2.24 1565 */ 1566 public int getInt32() 1567 { 1568 return g_variant_get_int32(gVariant); 1569 } 1570 1571 /** 1572 * Returns the 64-bit signed integer value of @value. 1573 * 1574 * It is an error to call this function with a @value of any type 1575 * other than %G_VARIANT_TYPE_INT64. 1576 * 1577 * Return: a #gint64 1578 * 1579 * Since: 2.24 1580 */ 1581 public long getInt64() 1582 { 1583 return g_variant_get_int64(gVariant); 1584 } 1585 1586 /** 1587 * Given a maybe-typed #GVariant instance, extract its value. If the 1588 * value is Nothing, then this function returns %NULL. 1589 * 1590 * Return: the contents of @value, or %NULL 1591 * 1592 * Since: 2.24 1593 */ 1594 public Variant getMaybe() 1595 { 1596 auto p = g_variant_get_maybe(gVariant); 1597 1598 if(p is null) 1599 { 1600 return null; 1601 } 1602 1603 return new Variant(cast(GVariant*) p); 1604 } 1605 1606 /** 1607 * Gets a #GVariant instance that has the same value as @value and is 1608 * trusted to be in normal form. 1609 * 1610 * If @value is already trusted to be in normal form then a new 1611 * reference to @value is returned. 1612 * 1613 * If @value is not already trusted, then it is scanned to check if it 1614 * is in normal form. If it is found to be in normal form then it is 1615 * marked as trusted and a new reference to it is returned. 1616 * 1617 * If @value is found not to be in normal form then a new trusted 1618 * #GVariant is created with the same value as @value. 1619 * 1620 * It makes sense to call this function if you've received #GVariant 1621 * data from untrusted sources and you want to ensure your serialised 1622 * output is definitely in normal form. 1623 * 1624 * Return: a trusted #GVariant 1625 * 1626 * Since: 2.24 1627 */ 1628 public Variant getNormalForm() 1629 { 1630 auto p = g_variant_get_normal_form(gVariant); 1631 1632 if(p is null) 1633 { 1634 return null; 1635 } 1636 1637 return new Variant(cast(GVariant*) p); 1638 } 1639 1640 /** 1641 * Gets the contents of an array of object paths #GVariant. This call 1642 * makes a shallow copy; the return result should be released with 1643 * g_free(), but the individual strings must not be modified. 1644 * 1645 * If @length is non-%NULL then the number of elements in the result 1646 * is stored there. In any case, the resulting array will be 1647 * %NULL-terminated. 1648 * 1649 * For an empty array, @length will be set to 0 and a pointer to a 1650 * %NULL pointer will be returned. 1651 * 1652 * Return: an array of constant strings 1653 * 1654 * Since: 2.30 1655 */ 1656 public string[] getObjv() 1657 { 1658 size_t length; 1659 1660 return Str.toStringArray(g_variant_get_objv(gVariant, &length)); 1661 } 1662 1663 /** 1664 * Determines the number of bytes that would be required to store @value 1665 * with g_variant_store(). 1666 * 1667 * If @value has a fixed-sized type then this function always returned 1668 * that fixed size. 1669 * 1670 * In the case that @value is already in serialised form or the size has 1671 * already been calculated (ie: this function has been called before) 1672 * then this function is O(1). Otherwise, the size is calculated, an 1673 * operation which is approximately O(n) in the number of values 1674 * involved. 1675 * 1676 * Return: the serialised size of @value 1677 * 1678 * Since: 2.24 1679 */ 1680 public size_t getSize() 1681 { 1682 return g_variant_get_size(gVariant); 1683 } 1684 1685 /** 1686 * Returns the string value of a #GVariant instance with a string 1687 * type. This includes the types %G_VARIANT_TYPE_STRING, 1688 * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. 1689 * 1690 * The string will always be UTF-8 encoded. 1691 * 1692 * If @length is non-%NULL then the length of the string (in bytes) is 1693 * returned there. For trusted values, this information is already 1694 * known. For untrusted values, a strlen() will be performed. 1695 * 1696 * It is an error to call this function with a @value of any type 1697 * other than those three. 1698 * 1699 * The return value remains valid as long as @value exists. 1700 * 1701 * Params: 1702 * length = a pointer to a #gsize, 1703 * to store the length 1704 * 1705 * Return: the constant string, UTF-8 encoded 1706 * 1707 * Since: 2.24 1708 */ 1709 public string getString(out size_t length) 1710 { 1711 return Str.toString(g_variant_get_string(gVariant, &length)); 1712 } 1713 1714 /** 1715 * Gets the contents of an array of strings #GVariant. This call 1716 * makes a shallow copy; the return result should be released with 1717 * g_free(), but the individual strings must not be modified. 1718 * 1719 * If @length is non-%NULL then the number of elements in the result 1720 * is stored there. In any case, the resulting array will be 1721 * %NULL-terminated. 1722 * 1723 * For an empty array, @length will be set to 0 and a pointer to a 1724 * %NULL pointer will be returned. 1725 * 1726 * Return: an array of constant strings 1727 * 1728 * Since: 2.24 1729 */ 1730 public string[] getStrv() 1731 { 1732 size_t length; 1733 1734 return Str.toStringArray(g_variant_get_strv(gVariant, &length)); 1735 } 1736 1737 /** 1738 * Determines the type of @value. 1739 * 1740 * The return value is valid for the lifetime of @value and must not 1741 * be freed. 1742 * 1743 * Return: a #GVariantType 1744 * 1745 * Since: 2.24 1746 */ 1747 public VariantType getType() 1748 { 1749 auto p = g_variant_get_type(gVariant); 1750 1751 if(p is null) 1752 { 1753 return null; 1754 } 1755 1756 return new VariantType(cast(GVariantType*) p); 1757 } 1758 1759 /** 1760 * Returns the type string of @value. Unlike the result of calling 1761 * g_variant_type_peek_string(), this string is nul-terminated. This 1762 * string belongs to #GVariant and must not be freed. 1763 * 1764 * Return: the type string for the type of @value 1765 * 1766 * Since: 2.24 1767 */ 1768 public string getTypeString() 1769 { 1770 return Str.toString(g_variant_get_type_string(gVariant)); 1771 } 1772 1773 /** 1774 * Returns the 16-bit unsigned integer value of @value. 1775 * 1776 * It is an error to call this function with a @value of any type 1777 * other than %G_VARIANT_TYPE_UINT16. 1778 * 1779 * Return: a #guint16 1780 * 1781 * Since: 2.24 1782 */ 1783 public ushort getUint16() 1784 { 1785 return g_variant_get_uint16(gVariant); 1786 } 1787 1788 /** 1789 * Returns the 32-bit unsigned integer value of @value. 1790 * 1791 * It is an error to call this function with a @value of any type 1792 * other than %G_VARIANT_TYPE_UINT32. 1793 * 1794 * Return: a #guint32 1795 * 1796 * Since: 2.24 1797 */ 1798 public uint getUint32() 1799 { 1800 return g_variant_get_uint32(gVariant); 1801 } 1802 1803 /** 1804 * Returns the 64-bit unsigned integer value of @value. 1805 * 1806 * It is an error to call this function with a @value of any type 1807 * other than %G_VARIANT_TYPE_UINT64. 1808 * 1809 * Return: a #guint64 1810 * 1811 * Since: 2.24 1812 */ 1813 public ulong getUint64() 1814 { 1815 return g_variant_get_uint64(gVariant); 1816 } 1817 1818 /** 1819 * This function is intended to be used by libraries based on #GVariant 1820 * that want to provide g_variant_get()-like functionality to their 1821 * users. 1822 * 1823 * The API is more general than g_variant_get() to allow a wider range 1824 * of possible uses. 1825 * 1826 * @format_string must still point to a valid format string, but it only 1827 * need to be nul-terminated if @endptr is %NULL. If @endptr is 1828 * non-%NULL then it is updated to point to the first character past the 1829 * end of the format string. 1830 * 1831 * @app is a pointer to a #va_list. The arguments, according to 1832 * @format_string, are collected from this #va_list and the list is left 1833 * pointing to the argument following the last. 1834 * 1835 * These two generalisations allow mixing of multiple calls to 1836 * g_variant_new_va() and g_variant_get_va() within a single actual 1837 * varargs call by the user. 1838 * 1839 * @format_string determines the C types that are used for unpacking 1840 * the values and also determines if the values are copied or borrowed, 1841 * see the section on 1842 * [GVariant format strings][gvariant-format-strings-pointers]. 1843 * 1844 * Params: 1845 * formatString = a string that is prefixed with a format string 1846 * endptr = location to store the end pointer, 1847 * or %NULL 1848 * app = a pointer to a #va_list 1849 * 1850 * Since: 2.24 1851 */ 1852 public void getVa(string formatString, string[] endptr, void** app) 1853 { 1854 g_variant_get_va(gVariant, Str.toStringz(formatString), Str.toStringzArray(endptr), app); 1855 } 1856 1857 /** 1858 * Unboxes @value. The result is the #GVariant instance that was 1859 * contained in @value. 1860 * 1861 * Return: the item contained in the variant 1862 * 1863 * Since: 2.24 1864 */ 1865 public Variant getVariant() 1866 { 1867 auto p = g_variant_get_variant(gVariant); 1868 1869 if(p is null) 1870 { 1871 return null; 1872 } 1873 1874 return new Variant(cast(GVariant*) p); 1875 } 1876 1877 /** 1878 * Generates a hash value for a #GVariant instance. 1879 * 1880 * The output of this function is guaranteed to be the same for a given 1881 * value only per-process. It may change between different processor 1882 * architectures or even different versions of GLib. Do not use this 1883 * function as a basis for building protocols or file formats. 1884 * 1885 * The type of @value is #gconstpointer only to allow use of this 1886 * function with #GHashTable. @value must be a #GVariant. 1887 * 1888 * Return: a hash value corresponding to @value 1889 * 1890 * Since: 2.24 1891 */ 1892 public uint hash() 1893 { 1894 return g_variant_hash(gVariant); 1895 } 1896 1897 /** 1898 * Checks if @value is a container. 1899 * 1900 * Return: %TRUE if @value is a container 1901 * 1902 * Since: 2.24 1903 */ 1904 public bool isContainer() 1905 { 1906 return g_variant_is_container(gVariant) != 0; 1907 } 1908 1909 /** 1910 * Checks whether @value has a floating reference count. 1911 * 1912 * This function should only ever be used to assert that a given variant 1913 * is or is not floating, or for debug purposes. To acquire a reference 1914 * to a variant that might be floating, always use g_variant_ref_sink() 1915 * or g_variant_take_ref(). 1916 * 1917 * See g_variant_ref_sink() for more information about floating reference 1918 * counts. 1919 * 1920 * Return: whether @value is floating 1921 * 1922 * Since: 2.26 1923 */ 1924 public bool isFloating() 1925 { 1926 return g_variant_is_floating(gVariant) != 0; 1927 } 1928 1929 /** 1930 * Checks if @value is in normal form. 1931 * 1932 * The main reason to do this is to detect if a given chunk of 1933 * serialised data is in normal form: load the data into a #GVariant 1934 * using g_variant_new_from_data() and then use this function to 1935 * check. 1936 * 1937 * If @value is found to be in normal form then it will be marked as 1938 * being trusted. If the value was already marked as being trusted then 1939 * this function will immediately return %TRUE. 1940 * 1941 * Return: %TRUE if @value is in normal form 1942 * 1943 * Since: 2.24 1944 */ 1945 public bool isNormalForm() 1946 { 1947 return g_variant_is_normal_form(gVariant) != 0; 1948 } 1949 1950 /** 1951 * Checks if a value has a type matching the provided type. 1952 * 1953 * Params: 1954 * type = a #GVariantType 1955 * 1956 * Return: %TRUE if the type of @value matches @type 1957 * 1958 * Since: 2.24 1959 */ 1960 public bool isOfType(VariantType type) 1961 { 1962 return g_variant_is_of_type(gVariant, (type is null) ? null : type.getVariantTypeStruct()) != 0; 1963 } 1964 1965 /** 1966 * Creates a heap-allocated #GVariantIter for iterating over the items 1967 * in @value. 1968 * 1969 * Use g_variant_iter_free() to free the return value when you no longer 1970 * need it. 1971 * 1972 * A reference is taken to @value and will be released only when 1973 * g_variant_iter_free() is called. 1974 * 1975 * Return: a new heap-allocated #GVariantIter 1976 * 1977 * Since: 2.24 1978 */ 1979 public VariantIter iterNew() 1980 { 1981 auto p = g_variant_iter_new(gVariant); 1982 1983 if(p is null) 1984 { 1985 return null; 1986 } 1987 1988 return new VariantIter(cast(GVariantIter*) p); 1989 } 1990 1991 /** 1992 * Looks up a value in a dictionary #GVariant. 1993 * 1994 * This function works with dictionaries of the type a{s*} (and equally 1995 * well with type a{o*}, but we only further discuss the string case 1996 * for sake of clarity). 1997 * 1998 * In the event that @dictionary has the type a{sv}, the @expected_type 1999 * string specifies what type of value is expected to be inside of the 2000 * variant. If the value inside the variant has a different type then 2001 * %NULL is returned. In the event that @dictionary has a value type other 2002 * than v then @expected_type must directly match the key type and it is 2003 * used to unpack the value directly or an error occurs. 2004 * 2005 * In either case, if @key is not found in @dictionary, %NULL is returned. 2006 * 2007 * If the key is found and the value has the correct type, it is 2008 * returned. If @expected_type was specified then any non-%NULL return 2009 * value will have this type. 2010 * 2011 * This function is currently implemented with a linear scan. If you 2012 * plan to do many lookups then #GVariantDict may be more efficient. 2013 * 2014 * Params: 2015 * key = the key to lookup in the dictionary 2016 * expectedType = a #GVariantType, or %NULL 2017 * 2018 * Return: the value of the dictionary key, or %NULL 2019 * 2020 * Since: 2.28 2021 */ 2022 public Variant lookupValue(string key, VariantType expectedType) 2023 { 2024 auto p = g_variant_lookup_value(gVariant, Str.toStringz(key), (expectedType is null) ? null : expectedType.getVariantTypeStruct()); 2025 2026 if(p is null) 2027 { 2028 return null; 2029 } 2030 2031 return new Variant(cast(GVariant*) p); 2032 } 2033 2034 /** 2035 * Determines the number of children in a container #GVariant instance. 2036 * This includes variants, maybes, arrays, tuples and dictionary 2037 * entries. It is an error to call this function on any other type of 2038 * #GVariant. 2039 * 2040 * For variants, the return value is always 1. For values with maybe 2041 * types, it is always zero or one. For arrays, it is the length of the 2042 * array. For tuples it is the number of tuple items (which depends 2043 * only on the type). For dictionary entries, it is always 2 2044 * 2045 * This function is O(1). 2046 * 2047 * Return: the number of children in the container 2048 * 2049 * Since: 2.24 2050 */ 2051 public size_t nChildren() 2052 { 2053 return g_variant_n_children(gVariant); 2054 } 2055 2056 /** 2057 * Pretty-prints @value in the format understood by g_variant_parse(). 2058 * 2059 * The format is described [here][gvariant-text]. 2060 * 2061 * If @type_annotate is %TRUE, then type information is included in 2062 * the output. 2063 * 2064 * Params: 2065 * typeAnnotate = %TRUE if type information should be included in 2066 * the output 2067 * 2068 * Return: a newly-allocated string holding the result. 2069 * 2070 * Since: 2.24 2071 */ 2072 public string print(bool typeAnnotate) 2073 { 2074 return Str.toString(g_variant_print(gVariant, typeAnnotate)); 2075 } 2076 2077 /** 2078 * Behaves as g_variant_print(), but operates on a #GString. 2079 * 2080 * If @string is non-%NULL then it is appended to and returned. Else, 2081 * a new empty #GString is allocated and it is returned. 2082 * 2083 * Params: 2084 * str = a #GString, or %NULL 2085 * typeAnnotate = %TRUE if type information should be included in 2086 * the output 2087 * 2088 * Return: a #GString containing the string 2089 * 2090 * Since: 2.24 2091 */ 2092 public StringG printString(StringG str, bool typeAnnotate) 2093 { 2094 auto p = g_variant_print_string(gVariant, (str is null) ? null : str.getStringGStruct(), typeAnnotate); 2095 2096 if(p is null) 2097 { 2098 return null; 2099 } 2100 2101 return new StringG(cast(GString*) p); 2102 } 2103 2104 /** 2105 * Increases the reference count of @value. 2106 * 2107 * Return: the same @value 2108 * 2109 * Since: 2.24 2110 */ 2111 public Variant doref() 2112 { 2113 auto p = g_variant_ref(gVariant); 2114 2115 if(p is null) 2116 { 2117 return null; 2118 } 2119 2120 return new Variant(cast(GVariant*) p); 2121 } 2122 2123 /** 2124 * #GVariant uses a floating reference count system. All functions with 2125 * names starting with `g_variant_new_` return floating 2126 * references. 2127 * 2128 * Calling g_variant_ref_sink() on a #GVariant with a floating reference 2129 * will convert the floating reference into a full reference. Calling 2130 * g_variant_ref_sink() on a non-floating #GVariant results in an 2131 * additional normal reference being added. 2132 * 2133 * In other words, if the @value is floating, then this call "assumes 2134 * ownership" of the floating reference, converting it to a normal 2135 * reference. If the @value is not floating, then this call adds a 2136 * new normal reference increasing the reference count by one. 2137 * 2138 * All calls that result in a #GVariant instance being inserted into a 2139 * container will call g_variant_ref_sink() on the instance. This means 2140 * that if the value was just created (and has only its floating 2141 * reference) then the container will assume sole ownership of the value 2142 * at that point and the caller will not need to unreference it. This 2143 * makes certain common styles of programming much easier while still 2144 * maintaining normal refcounting semantics in situations where values 2145 * are not floating. 2146 * 2147 * Return: the same @value 2148 * 2149 * Since: 2.24 2150 */ 2151 public Variant refSink() 2152 { 2153 auto p = g_variant_ref_sink(gVariant); 2154 2155 if(p is null) 2156 { 2157 return null; 2158 } 2159 2160 return new Variant(cast(GVariant*) p); 2161 } 2162 2163 /** 2164 * Stores the serialised form of @value at @data. @data should be 2165 * large enough. See g_variant_get_size(). 2166 * 2167 * The stored data is in machine native byte order but may not be in 2168 * fully-normalised form if read from an untrusted source. See 2169 * g_variant_get_normal_form() for a solution. 2170 * 2171 * As with g_variant_get_data(), to be able to deserialise the 2172 * serialised variant successfully, its type and (if the destination 2173 * machine might be different) its endianness must also be available. 2174 * 2175 * This function is approximately O(n) in the size of @data. 2176 * 2177 * Params: 2178 * data = the location to store the serialised data at 2179 * 2180 * Since: 2.24 2181 */ 2182 public void store(void* data) 2183 { 2184 g_variant_store(gVariant, data); 2185 } 2186 2187 /** 2188 * If @value is floating, sink it. Otherwise, do nothing. 2189 * 2190 * Typically you want to use g_variant_ref_sink() in order to 2191 * automatically do the correct thing with respect to floating or 2192 * non-floating references, but there is one specific scenario where 2193 * this function is helpful. 2194 * 2195 * The situation where this function is helpful is when creating an API 2196 * that allows the user to provide a callback function that returns a 2197 * #GVariant. We certainly want to allow the user the flexibility to 2198 * return a non-floating reference from this callback (for the case 2199 * where the value that is being returned already exists). 2200 * 2201 * At the same time, the style of the #GVariant API makes it likely that 2202 * for newly-created #GVariant instances, the user can be saved some 2203 * typing if they are allowed to return a #GVariant with a floating 2204 * reference. 2205 * 2206 * Using this function on the return value of the user's callback allows 2207 * the user to do whichever is more convenient for them. The caller 2208 * will alway receives exactly one full reference to the value: either 2209 * the one that was returned in the first place, or a floating reference 2210 * that has been converted to a full reference. 2211 * 2212 * This function has an odd interaction when combined with 2213 * g_variant_ref_sink() running at the same time in another thread on 2214 * the same #GVariant instance. If g_variant_ref_sink() runs first then 2215 * the result will be that the floating reference is converted to a hard 2216 * reference. If g_variant_take_ref() runs first then the result will 2217 * be that the floating reference is converted to a hard reference and 2218 * an additional reference on top of that one is added. It is best to 2219 * avoid this situation. 2220 * 2221 * Return: the same @value 2222 */ 2223 public Variant takeRef() 2224 { 2225 auto p = g_variant_take_ref(gVariant); 2226 2227 if(p is null) 2228 { 2229 return null; 2230 } 2231 2232 return new Variant(cast(GVariant*) p); 2233 } 2234 2235 /** 2236 * Decreases the reference count of @value. When its reference count 2237 * drops to 0, the memory used by the variant is freed. 2238 * 2239 * Since: 2.24 2240 */ 2241 public void unref() 2242 { 2243 g_variant_unref(gVariant); 2244 } 2245 2246 /** 2247 * Determines if a given string is a valid D-Bus object path. You 2248 * should ensure that a string is a valid D-Bus object path before 2249 * passing it to g_variant_new_object_path(). 2250 * 2251 * A valid object path starts with '/' followed by zero or more 2252 * sequences of characters separated by '/' characters. Each sequence 2253 * must contain only the characters "[A-Z][a-z][0-9]_". No sequence 2254 * (including the one following the final '/' character) may be empty. 2255 * 2256 * Params: 2257 * str = a normal C nul-terminated string 2258 * 2259 * Return: %TRUE if @string is a D-Bus object path 2260 * 2261 * Since: 2.24 2262 */ 2263 public static bool isObjectPath(string str) 2264 { 2265 return g_variant_is_object_path(Str.toStringz(str)) != 0; 2266 } 2267 2268 /** 2269 * Determines if a given string is a valid D-Bus type signature. You 2270 * should ensure that a string is a valid D-Bus type signature before 2271 * passing it to g_variant_new_signature(). 2272 * 2273 * D-Bus type signatures consist of zero or more definite #GVariantType 2274 * strings in sequence. 2275 * 2276 * Params: 2277 * str = a normal C nul-terminated string 2278 * 2279 * Return: %TRUE if @string is a D-Bus type signature 2280 * 2281 * Since: 2.24 2282 */ 2283 public static bool isSignature(string str) 2284 { 2285 return g_variant_is_signature(Str.toStringz(str)) != 0; 2286 } 2287 2288 /** 2289 * Parses a #GVariant from a text representation. 2290 * 2291 * A single #GVariant is parsed from the content of @text. 2292 * 2293 * The format is described [here][gvariant-text]. 2294 * 2295 * The memory at @limit will never be accessed and the parser behaves as 2296 * if the character at @limit is the nul terminator. This has the 2297 * effect of bounding @text. 2298 * 2299 * If @endptr is non-%NULL then @text is permitted to contain data 2300 * following the value that this function parses and @endptr will be 2301 * updated to point to the first character past the end of the text 2302 * parsed by this function. If @endptr is %NULL and there is extra data 2303 * then an error is returned. 2304 * 2305 * If @type is non-%NULL then the value will be parsed to have that 2306 * type. This may result in additional parse errors (in the case that 2307 * the parsed value doesn't fit the type) but may also result in fewer 2308 * errors (in the case that the type would have been ambiguous, such as 2309 * with empty arrays). 2310 * 2311 * In the event that the parsing is successful, the resulting #GVariant 2312 * is returned. 2313 * 2314 * In case of any error, %NULL will be returned. If @error is non-%NULL 2315 * then it will be set to reflect the error that occurred. 2316 * 2317 * Officially, the language understood by the parser is "any string 2318 * produced by g_variant_print()". 2319 * 2320 * Params: 2321 * type = a #GVariantType, or %NULL 2322 * text = a string containing a GVariant in text form 2323 * limit = a pointer to the end of @text, or %NULL 2324 * endptr = a location to store the end pointer, or %NULL 2325 * 2326 * Return: a reference to a #GVariant, or %NULL 2327 * 2328 * Throws: GException on failure. 2329 */ 2330 public static Variant parse(VariantType type, string text, string limit, string[] endptr) 2331 { 2332 GError* err = null; 2333 2334 auto p = g_variant_parse((type is null) ? null : type.getVariantTypeStruct(), Str.toStringz(text), Str.toStringz(limit), Str.toStringzArray(endptr), &err); 2335 2336 if (err !is null) 2337 { 2338 throw new GException( new ErrorG(err) ); 2339 } 2340 2341 if(p is null) 2342 { 2343 return null; 2344 } 2345 2346 return new Variant(cast(GVariant*) p); 2347 } 2348 2349 /** 2350 * Pretty-prints a message showing the context of a #GVariant parse 2351 * error within the string for which parsing was attempted. 2352 * 2353 * The resulting string is suitable for output to the console or other 2354 * monospace media where newlines are treated in the usual way. 2355 * 2356 * The message will typically look something like one of the following: 2357 * 2358 * |[ 2359 * unterminated string constant: 2360 * (1, 2, 3, 'abc 2361 * ^^^^ 2362 * ]| 2363 * 2364 * or 2365 * 2366 * |[ 2367 * unable to find a common type: 2368 * [1, 2, 3, 'str'] 2369 * ^ ^^^^^ 2370 * ]| 2371 * 2372 * The format of the message may change in a future version. 2373 * 2374 * @error must have come from a failed attempt to g_variant_parse() and 2375 * @source_str must be exactly the same string that caused the error. 2376 * If @source_str was not nul-terminated when you passed it to 2377 * g_variant_parse() then you must add nul termination before using this 2378 * function. 2379 * 2380 * Params: 2381 * error = a #GError from the #GVariantParseError domain 2382 * sourceStr = the string that was given to the parser 2383 * 2384 * Return: the printed message 2385 * 2386 * Since: 2.40 2387 */ 2388 public static string parseErrorPrintContext(ErrorG error, string sourceStr) 2389 { 2390 return Str.toString(g_variant_parse_error_print_context((error is null) ? null : error.getErrorGStruct(), Str.toStringz(sourceStr))); 2391 } 2392 2393 public static GQuark parseErrorQuark() 2394 { 2395 return g_variant_parse_error_quark(); 2396 } 2397 2398 /** 2399 * Same as g_variant_error_quark(). 2400 * 2401 * Deprecated: Use g_variant_parse_error_quark() instead. 2402 */ 2403 public static GQuark parserGetErrorQuark() 2404 { 2405 return g_variant_parser_get_error_quark(); 2406 } 2407 }