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