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