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