1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. --  Glib.Variant.Gvariant is a variant datatype; it stores a value along with 
  26. --  information about the type of that value. The range of possible values is 
  27. --  determined by the type. The type system used by Glib.Variant.Gvariant is 
  28. --  Glib.Variant.Gvariant_Type. 
  29. -- 
  30. --  Glib.Variant.Gvariant instances always have a type and a value (which are 
  31. --  given at construction time). The type and value of a Glib.Variant.Gvariant 
  32. --  instance can never change other than by the Glib.Variant.Gvariant itself 
  33. --  being destroyed. A Glib.Variant.Gvariant cannot contain a pointer. 
  34. -- 
  35. --  Glib.Variant.Gvariant is reference counted using Glib.Variant.Ref and 
  36. --  Glib.Variant.Unref. Glib.Variant.Gvariant also has floating reference 
  37. --  counts -- see Glib.Variant.Ref_Sink. 
  38. -- 
  39. --  Glib.Variant.Gvariant is completely threadsafe. A Glib.Variant.Gvariant 
  40. --  instance can be concurrently accessed in any way from any number of threads 
  41. --  without problems. 
  42. -- 
  43. --  Glib.Variant.Gvariant is heavily optimised for dealing with data in 
  44. --  serialised form. It works particularly well with data located in 
  45. --  memory-mapped files. It can perform nearly all deserialisation operations 
  46. --  in a small constant time, usually touching only a single memory page. 
  47. --  Serialised Glib.Variant.Gvariant data can also be sent over the network. 
  48. -- 
  49. --  Glib.Variant.Gvariant is largely compatible with D-Bus. Almost all types 
  50. --  of Glib.Variant.Gvariant instances can be sent over D-Bus. See 
  51. --  Glib.Variant.Gvariant_Type for exceptions. (However, 
  52. --  Glib.Variant.Gvariant's serialisation format is not the same as the 
  53. --  serialisation format of a D-Bus message body: use 
  54. --  Gdbus.Message.Gdbus_Message, in the gio library, for those.) 
  55. -- 
  56. --  For space-efficiency, the Glib.Variant.Gvariant serialisation format does 
  57. --  not automatically include the variant's type or endianness, which must 
  58. --  either be implied from context (such as knowledge that a particular file 
  59. --  format always contains a little-endian G_VARIANT_TYPE_VARIANT) or supplied 
  60. --  out-of-band (for instance, a type and/or endianness indicator could be 
  61. --  placed at the beginning of a file, network message or network stream). 
  62. -- 
  63. --  A Glib.Variant.Gvariant's size is limited mainly by any lower level 
  64. --  operating system constraints, such as the number of bits in Gsize. For 
  65. --  example, it is reasonable to have a 2GB file mapped into memory with 
  66. --  Gmapped.File.Gmapped_File, and call g_variant_new_from_data on it. 
  67. -- 
  68. --  For convenience to C programmers, Glib.Variant.Gvariant features powerful 
  69. --  varargs-based value construction and destruction. This feature is designed 
  70. --  to be embedded in other libraries. 
  71. -- 
  72. --  There is a Python-inspired text language for describing 
  73. --  Glib.Variant.Gvariant values. Glib.Variant.Gvariant includes a printer for 
  74. --  this language and a parser with type inferencing. 
  75. -- 
  76. --  
  77. -- 
  78. --  == Memory Use == 
  79. -- 
  80. --  
  81. -- 
  82. --  Glib.Variant.Gvariant tries to be quite efficient with respect to memory 
  83. --  use. This section gives a rough idea of how much memory is used by the 
  84. --  current implementation. The information here is subject to change in the 
  85. --  future. 
  86. -- 
  87. --  The memory allocated by Glib.Variant.Gvariant can be grouped into 4 broad 
  88. --  purposes: memory for serialised data, memory for the type information 
  89. --  cache, buffer management memory and memory for the Glib.Variant.Gvariant 
  90. --  structure itself. 
  91. -- 
  92. --  == Serialised Data Memory == 
  93. -- 
  94. --  
  95. -- 
  96. --  This is the memory that is used for storing GVariant data in serialised 
  97. --  form. This is what would be sent over the network or what would end up on 
  98. --  disk. 
  99. -- 
  100. --  The amount of memory required to store a boolean is 1 byte. 16, 32 and 64 
  101. --  bit integers and double precision floating point numbers use their 
  102. --  "natural" size. Strings (including object path and signature strings) are 
  103. --  stored with a nul terminator, and as such use the length of the string plus 
  104. --  1 byte. 
  105. -- 
  106. --  Maybe types use no space at all to represent the null value and use the 
  107. --  same amount of space (sometimes plus one byte) as the equivalent 
  108. --  non-maybe-typed value to represent the non-null case. 
  109. -- 
  110. --  Arrays use the amount of space required to store each of their members, 
  111. --  concatenated. Additionally, if the items stored in an array are not of a 
  112. --  fixed-size (ie: strings, other arrays, etc) then an additional framing 
  113. --  offset is stored for each item. The size of this offset is either 1, 2 or 4 
  114. --  bytes depending on the overall size of the container. Additionally, extra 
  115. --  padding bytes are added as required for alignment of child values. 
  116. -- 
  117. --  Tuples (including dictionary entries) use the amount of space required to 
  118. --  store each of their members, concatenated, plus one framing offset (as per 
  119. --  arrays) for each non-fixed-sized item in the tuple, except for the last 
  120. --  one. Additionally, extra padding bytes are added as required for alignment 
  121. --  of child values. 
  122. -- 
  123. --  Variants use the same amount of space as the item inside of the variant, 
  124. --  plus 1 byte, plus the length of the type string for the item inside the 
  125. --  variant. 
  126. -- 
  127. --  As an example, consider a dictionary mapping strings to variants. In the 
  128. --  case that the dictionary is empty, 0 bytes are required for the 
  129. --  serialisation. 
  130. -- 
  131. --  If we add an item "width" that maps to the int32 value of 500 then we will 
  132. --  use 4 byte to store the int32 (so 6 for the variant containing it) and 6 
  133. --  bytes for the string. The variant must be aligned to 8 after the 6 bytes of 
  134. --  the string, so that's 2 extra bytes. 6 (string) + 2 (padding) + 6 (variant) 
  135. --  is 14 bytes used for the dictionary entry. An additional 1 byte is added to 
  136. --  the array as a framing offset making a total of 15 bytes. 
  137. -- 
  138. --  If we add another entry, "title" that maps to a nullable string that 
  139. --  happens to have a value of null, then we use 0 bytes for the null value 
  140. --  (and 3 bytes for the variant to contain it along with its type string) plus 
  141. --  6 bytes for the string. Again, we need 2 padding bytes. That makes a total 
  142. --  of 6 + 2 + 3 = 11 bytes. 
  143. -- 
  144. --  We now require extra padding between the two items in the array. After the 
  145. --  14 bytes of the first item, that's 2 bytes required. We now require 2 
  146. --  framing offsets for an extra two bytes. 14 + 2 + 11 + 2 = 29 bytes to 
  147. --  encode the entire two-item dictionary. 
  148. -- 
  149. --  == Type Information Cache == 
  150. -- 
  151. --  
  152. -- 
  153. --  For each GVariant type that currently exists in the program a type 
  154. --  information structure is kept in the type information cache. The type 
  155. --  information structure is required for rapid deserialisation. 
  156. -- 
  157. --  Continuing with the above example, if a Glib.Variant.Gvariant exists with 
  158. --  the type "a{sv}" then a type information struct will exist for "a{sv}", 
  159. --  "{sv}", "s", and "v". Multiple uses of the same type will share the same 
  160. --  type information. Additionally, all single-digit types are stored in 
  161. --  read-only static memory and do not contribute to the writable memory 
  162. --  footprint of a program using Glib.Variant.Gvariant. 
  163. -- 
  164. --  Aside from the type information structures stored in read-only memory, 
  165. --  there are two forms of type information. One is used for container types 
  166. --  where there is a single element type: arrays and maybe types. The other is 
  167. --  used for container types where there are multiple element types: tuples and 
  168. --  dictionary entries. 
  169. -- 
  170. --  Array type info structures are 6 * sizeof (void *), plus the memory 
  171. --  required to store the type string itself. This means that on 32bit systems, 
  172. --  the cache entry for "a{sv}" would require 30 bytes of memory (plus malloc 
  173. --  overhead). 
  174. -- 
  175. --  Tuple type info structures are 6 * sizeof (void *), plus 4 * sizeof (void 
  176. --  *) for each item in the tuple, plus the memory required to store the type 
  177. --  string itself. A 2-item tuple, for example, would have a type information 
  178. --  structure that consumed writable memory in the size of 14 * sizeof (void *) 
  179. --  (plus type string) This means that on 32bit systems, the cache entry for 
  180. --  "{sv}" would require 61 bytes of memory (plus malloc overhead). 
  181. -- 
  182. --  This means that in total, for our "a{sv}" example, 91 bytes of type 
  183. --  information would be allocated. 
  184. -- 
  185. --  The type information cache, additionally, uses a GHash_Table to store and 
  186. --  lookup the cached items and stores a pointer to this hash table in static 
  187. --  storage. The hash table is freed when there are zero items in the type 
  188. --  cache. 
  189. -- 
  190. --  Although these sizes may seem large it is important to remember that a 
  191. --  program will probably only have a very small number of different types of 
  192. --  values in it and that only one type information structure is required for 
  193. --  many different values of the same type. 
  194. -- 
  195. --  == Buffer Management Memory == 
  196. -- 
  197. --  
  198. -- 
  199. --  Glib.Variant.Gvariant uses an internal buffer management structure to deal 
  200. --  with the various different possible sources of serialised data that it 
  201. --  uses. The buffer is responsible for ensuring that the correct call is made 
  202. --  when the data is no longer in use by Glib.Variant.Gvariant. This may 
  203. --  involve a g_free or a g_slice_free or even g_mapped_file_unref. 
  204. -- 
  205. --  One buffer management structure is used for each chunk of serialised data. 
  206. --  The size of the buffer management structure is 4 * (void *). On 32bit 
  207. --  systems, that's 16 bytes. 
  208. -- 
  209. --  == GVariant structure == 
  210. -- 
  211. --  
  212. -- 
  213. --  The size of a Glib.Variant.Gvariant structure is 6 * (void *). On 32 bit 
  214. --  systems, that's 24 bytes. 
  215. -- 
  216. --  Glib.Variant.Gvariant structures only exist if they are explicitly created 
  217. --  with API calls. For example, if a Glib.Variant.Gvariant is constructed out 
  218. --  of serialised data for the example given above (with the dictionary) then 
  219. --  although there are 9 individual values that comprise the entire dictionary 
  220. --  (two keys, two values, two variants containing the values, two dictionary 
  221. --  entries, plus the dictionary itself), only 1 Glib.Variant.Gvariant instance 
  222. --  exists -- the one referring to the dictionary. 
  223. -- 
  224. --  If calls are made to start accessing the other values then 
  225. --  Glib.Variant.Gvariant instances will exist for those values only for as 
  226. --  long as they are in use (ie: until you call Glib.Variant.Unref). The type 
  227. --  information is shared. The serialised data and the buffer management 
  228. --  structure for that serialised data is shared by the child. 
  229. -- 
  230. --  == Summary == 
  231. -- 
  232. --  
  233. -- 
  234. --  To put the entire example together, for our dictionary mapping strings to 
  235. --  variants (with two entries, as given above), we are using 91 bytes of 
  236. --  memory for type information, 29 byes of memory for the serialised data, 16 
  237. --  bytes for buffer management and 24 bytes for the Glib.Variant.Gvariant 
  238. --  instance, or a total of 160 bytes, plus malloc overhead. If we were to use 
  239. --  Glib.Variant.Get_Child_Value to access the two dictionary entries, we would 
  240. --  use an additional 48 bytes. If we were to have other dictionaries of the 
  241. --  same type, we would use more memory for the serialised data and buffer 
  242. --  management for those dictionaries, but the type information would be 
  243. --  shared. 
  244. -- 
  245. --  </description> 
  246. pragma Ada_2005; 
  247.  
  248. pragma Warnings (Off, "*is already use-visible*"); 
  249. with GNAT.Strings;            use GNAT.Strings; 
  250. with Glib;                    use Glib; 
  251. with Glib.Generic_Properties; use Glib.Generic_Properties; 
  252. with Glib.String;             use Glib.String; 
  253.  
  254. package Glib.Variant is 
  255.  
  256.    type Gvariant is new Glib.C_Boxed with null record; 
  257.    Null_Gvariant : constant Gvariant; 
  258.  
  259.    function From_Object (Object : System.Address) return Gvariant; 
  260.    function From_Object_Free (B : access Gvariant'Class) return Gvariant; 
  261.    pragma Inline (From_Object_Free, From_Object); 
  262.  
  263.    type GVariant_Class is ( 
  264.       Class_Tuple, 
  265.       Class_Array, 
  266.       Class_Boolean, 
  267.       Class_Double, 
  268.       Class_Signature, 
  269.       Class_Handle, 
  270.       Class_Int32, 
  271.       Class_Maybe, 
  272.       Class_Int16, 
  273.       Class_Object_Path, 
  274.       Class_Uint16, 
  275.       Class_String, 
  276.       Class_Uint64, 
  277.       Class_Uint32, 
  278.       Class_Variant, 
  279.       Class_Int64, 
  280.       Class_Byte, 
  281.       Class_Dict_Entry); 
  282.    pragma Convention (C, GVariant_Class); 
  283.    --  The range of possible top-level types of Glib.Variant.Gvariant 
  284.    --  instances. 
  285.  
  286.    for GVariant_Class use ( 
  287.       Class_Tuple => 40, 
  288.       Class_Array => 97, 
  289.       Class_Boolean => 98, 
  290.       Class_Double => 100, 
  291.       Class_Signature => 103, 
  292.       Class_Handle => 104, 
  293.       Class_Int32 => 105, 
  294.       Class_Maybe => 109, 
  295.       Class_Int16 => 110, 
  296.       Class_Object_Path => 111, 
  297.       Class_Uint16 => 113, 
  298.       Class_String => 115, 
  299.       Class_Uint64 => 116, 
  300.       Class_Uint32 => 117, 
  301.       Class_Variant => 118, 
  302.       Class_Int64 => 120, 
  303.       Class_Byte => 121, 
  304.       Class_Dict_Entry => 123); 
  305.  
  306.    type Gvariant_Iter is new Glib.C_Proxy; 
  307.  
  308.    type Gvariant_Type is new Glib.C_Proxy; 
  309.  
  310.    ---------------------------- 
  311.    -- Enumeration Properties -- 
  312.    ---------------------------- 
  313.  
  314.    package GVariant_Class_Properties is 
  315.       new Generic_Internal_Discrete_Property (GVariant_Class); 
  316.    type Property_GVariant_Class is new GVariant_Class_Properties.Property; 
  317.  
  318.    ------------------ 
  319.    -- Constructors -- 
  320.    ------------------ 
  321.  
  322.    procedure G_New_Boolean (Self : out Gvariant; Value : Boolean); 
  323.    --  Creates a new boolean Glib.Variant.Gvariant instance -- either True or 
  324.    --  False. 
  325.    --  Since: gtk+ 2.24 
  326.    --  "value": a Boolean value 
  327.  
  328.    function Gvariant_New_Boolean (Value : Boolean) return Gvariant; 
  329.    --  Creates a new boolean Glib.Variant.Gvariant instance -- either True or 
  330.    --  False. 
  331.    --  Since: gtk+ 2.24 
  332.    --  "value": a Boolean value 
  333.  
  334.    procedure G_New_Byte (Self : out Gvariant; Value : Guchar); 
  335.    --  Creates a new byte Glib.Variant.Gvariant instance. 
  336.    --  Since: gtk+ 2.24 
  337.    --  "value": a Guint8 value 
  338.  
  339.    function Gvariant_New_Byte (Value : Guchar) return Gvariant; 
  340.    --  Creates a new byte Glib.Variant.Gvariant instance. 
  341.    --  Since: gtk+ 2.24 
  342.    --  "value": a Guint8 value 
  343.  
  344.    procedure G_New_Bytestring (Self : out Gvariant; String : Gint_Array); 
  345.    --  Creates an array-of-bytes Glib.Variant.Gvariant with the contents of 
  346.    --  String. This function is just like g_variant_new_string except that the 
  347.    --  string need not be valid utf8. 
  348.    --  The nul terminator character at the end of the string is stored in the 
  349.    --  array. 
  350.    --  Since: gtk+ 2.26 
  351.    --  "string": a normal nul-terminated string in no particular encoding 
  352.  
  353.    function Gvariant_New_Bytestring (String : Gint_Array) return Gvariant; 
  354.    --  Creates an array-of-bytes Glib.Variant.Gvariant with the contents of 
  355.    --  String. This function is just like g_variant_new_string except that the 
  356.    --  string need not be valid utf8. 
  357.    --  The nul terminator character at the end of the string is stored in the 
  358.    --  array. 
  359.    --  Since: gtk+ 2.26 
  360.    --  "string": a normal nul-terminated string in no particular encoding 
  361.  
  362.    procedure G_New_Bytestring_Array 
  363.       (Self   : out Gvariant; 
  364.        Strv   : GNAT.Strings.String_List; 
  365.        Length : Gssize); 
  366.    --  Constructs an array of bytestring Glib.Variant.Gvariant from the given 
  367.    --  array of strings. 
  368.    --  If Length is -1 then Strv is null-terminated. 
  369.    --  Since: gtk+ 2.26 
  370.    --  "strv": an array of strings 
  371.    --  "length": the length of Strv, or -1 
  372.  
  373.    function Gvariant_New_Bytestring_Array 
  374.       (Strv   : GNAT.Strings.String_List; 
  375.        Length : Gssize) return Gvariant; 
  376.    --  Constructs an array of bytestring Glib.Variant.Gvariant from the given 
  377.    --  array of strings. 
  378.    --  If Length is -1 then Strv is null-terminated. 
  379.    --  Since: gtk+ 2.26 
  380.    --  "strv": an array of strings 
  381.    --  "length": the length of Strv, or -1 
  382.  
  383.    procedure G_New_Dict_Entry 
  384.       (Self  : out Gvariant; 
  385.        Key   : Gvariant; 
  386.        Value : Gvariant); 
  387.    --  Creates a new dictionary entry Glib.Variant.Gvariant. Key and Value 
  388.    --  must be non-null. Key must be a value of a basic type (ie: not a 
  389.    --  container). 
  390.    --  If the Key or Value are floating references (see 
  391.    --  Glib.Variant.Ref_Sink), the new instance takes ownership of them as if 
  392.    --  via Glib.Variant.Ref_Sink. 
  393.    --  Since: gtk+ 2.24 
  394.    --  "key": a basic Glib.Variant.Gvariant, the key 
  395.    --  "value": a Glib.Variant.Gvariant, the value 
  396.  
  397.    procedure G_New_Dict_Entry 
  398.       (Self  : out Gvariant_Type; 
  399.        Key   : Gvariant_Type; 
  400.        Value : Gvariant_Type); 
  401.    --  Constructs the type corresponding to a dictionary entry with a key of 
  402.    --  type Key and a value of type Value. 
  403.    --  It is appropriate to call Glib.Variant.Free on the return value. 
  404.    --  "key": a basic Glib.Variant.Gvariant_Type 
  405.    --  "value": a Glib.Variant.Gvariant_Type 
  406.  
  407.    function Gvariant_New_Dict_Entry 
  408.       (Key   : Gvariant; 
  409.        Value : Gvariant) return Gvariant; 
  410.    --  Creates a new dictionary entry Glib.Variant.Gvariant. Key and Value 
  411.    --  must be non-null. Key must be a value of a basic type (ie: not a 
  412.    --  container). 
  413.    --  If the Key or Value are floating references (see 
  414.    --  Glib.Variant.Ref_Sink), the new instance takes ownership of them as if 
  415.    --  via Glib.Variant.Ref_Sink. 
  416.    --  Since: gtk+ 2.24 
  417.    --  "key": a basic Glib.Variant.Gvariant, the key 
  418.    --  "value": a Glib.Variant.Gvariant, the value 
  419.  
  420.    procedure G_New_Double (Self : out Gvariant; Value : Gdouble); 
  421.    --  Creates a new double Glib.Variant.Gvariant instance. 
  422.    --  Since: gtk+ 2.24 
  423.    --  "value": a Gdouble floating point value 
  424.  
  425.    function Gvariant_New_Double (Value : Gdouble) return Gvariant; 
  426.    --  Creates a new double Glib.Variant.Gvariant instance. 
  427.    --  Since: gtk+ 2.24 
  428.    --  "value": a Gdouble floating point value 
  429.  
  430.    procedure G_New_Handle (Self : out Gvariant; Value : Gint32); 
  431.    --  Creates a new handle Glib.Variant.Gvariant instance. 
  432.    --  By convention, handles are indexes into an array of file descriptors 
  433.    --  that are sent alongside a D-Bus message. If you're not interacting with 
  434.    --  D-Bus, you probably don't need them. 
  435.    --  Since: gtk+ 2.24 
  436.    --  "value": a Gint32 value 
  437.  
  438.    function Gvariant_New_Handle (Value : Gint32) return Gvariant; 
  439.    --  Creates a new handle Glib.Variant.Gvariant instance. 
  440.    --  By convention, handles are indexes into an array of file descriptors 
  441.    --  that are sent alongside a D-Bus message. If you're not interacting with 
  442.    --  D-Bus, you probably don't need them. 
  443.    --  Since: gtk+ 2.24 
  444.    --  "value": a Gint32 value 
  445.  
  446.    procedure G_New_Int16 (Self : out Gvariant; Value : Gint16); 
  447.    --  Creates a new int16 Glib.Variant.Gvariant instance. 
  448.    --  Since: gtk+ 2.24 
  449.    --  "value": a Gint16 value 
  450.  
  451.    function Gvariant_New_Int16 (Value : Gint16) return Gvariant; 
  452.    --  Creates a new int16 Glib.Variant.Gvariant instance. 
  453.    --  Since: gtk+ 2.24 
  454.    --  "value": a Gint16 value 
  455.  
  456.    procedure G_New_Int32 (Self : out Gvariant; Value : Gint32); 
  457.    --  Creates a new int32 Glib.Variant.Gvariant instance. 
  458.    --  Since: gtk+ 2.24 
  459.    --  "value": a Gint32 value 
  460.  
  461.    function Gvariant_New_Int32 (Value : Gint32) return Gvariant; 
  462.    --  Creates a new int32 Glib.Variant.Gvariant instance. 
  463.    --  Since: gtk+ 2.24 
  464.    --  "value": a Gint32 value 
  465.  
  466.    procedure G_New_Int64 (Self : out Gvariant; Value : Gint64); 
  467.    --  Creates a new int64 Glib.Variant.Gvariant instance. 
  468.    --  Since: gtk+ 2.24 
  469.    --  "value": a Gint64 value 
  470.  
  471.    function Gvariant_New_Int64 (Value : Gint64) return Gvariant; 
  472.    --  Creates a new int64 Glib.Variant.Gvariant instance. 
  473.    --  Since: gtk+ 2.24 
  474.    --  "value": a Gint64 value 
  475.  
  476.    procedure G_New_Object_Path 
  477.       (Self        : out Gvariant; 
  478.        Object_Path : UTF8_String); 
  479.    --  Creates a D-Bus object path Glib.Variant.Gvariant with the contents of 
  480.    --  String. String must be a valid D-Bus object path. Use 
  481.    --  Glib.Variant.Is_Object_Path if you're not sure. 
  482.    --  Since: gtk+ 2.24 
  483.    --  "object_path": a normal C nul-terminated string 
  484.  
  485.    function Gvariant_New_Object_Path 
  486.       (Object_Path : UTF8_String) return Gvariant; 
  487.    --  Creates a D-Bus object path Glib.Variant.Gvariant with the contents of 
  488.    --  String. String must be a valid D-Bus object path. Use 
  489.    --  Glib.Variant.Is_Object_Path if you're not sure. 
  490.    --  Since: gtk+ 2.24 
  491.    --  "object_path": a normal C nul-terminated string 
  492.  
  493.    procedure G_New_Objv 
  494.       (Self   : out Gvariant; 
  495.        Strv   : GNAT.Strings.String_List; 
  496.        Length : Gssize); 
  497.    --  Constructs an array of object paths Glib.Variant.Gvariant from the 
  498.    --  given array of strings. 
  499.    --  Each string must be a valid Glib.Variant.Gvariant object path; see 
  500.    --  Glib.Variant.Is_Object_Path. 
  501.    --  If Length is -1 then Strv is null-terminated. 
  502.    --  Since: gtk+ 2.30 
  503.    --  "strv": an array of strings 
  504.    --  "length": the length of Strv, or -1 
  505.  
  506.    function Gvariant_New_Objv 
  507.       (Strv   : GNAT.Strings.String_List; 
  508.        Length : Gssize) return Gvariant; 
  509.    --  Constructs an array of object paths Glib.Variant.Gvariant from the 
  510.    --  given array of strings. 
  511.    --  Each string must be a valid Glib.Variant.Gvariant object path; see 
  512.    --  Glib.Variant.Is_Object_Path. 
  513.    --  If Length is -1 then Strv is null-terminated. 
  514.    --  Since: gtk+ 2.30 
  515.    --  "strv": an array of strings 
  516.    --  "length": the length of Strv, or -1 
  517.  
  518.    procedure G_New_Signature (Self : out Gvariant; Signature : UTF8_String); 
  519.    --  Creates a D-Bus type signature Glib.Variant.Gvariant with the contents 
  520.    --  of String. String must be a valid D-Bus type signature. Use 
  521.    --  Glib.Variant.Is_Signature if you're not sure. 
  522.    --  Since: gtk+ 2.24 
  523.    --  "signature": a normal C nul-terminated string 
  524.  
  525.    function Gvariant_New_Signature (Signature : UTF8_String) return Gvariant; 
  526.    --  Creates a D-Bus type signature Glib.Variant.Gvariant with the contents 
  527.    --  of String. String must be a valid D-Bus type signature. Use 
  528.    --  Glib.Variant.Is_Signature if you're not sure. 
  529.    --  Since: gtk+ 2.24 
  530.    --  "signature": a normal C nul-terminated string 
  531.  
  532.    procedure G_New_String (Self : out Gvariant; String : UTF8_String); 
  533.    --  Creates a string Glib.Variant.Gvariant with the contents of String. 
  534.    --  String must be valid utf8. 
  535.    --  Since: gtk+ 2.24 
  536.    --  "string": a normal utf8 nul-terminated string 
  537.  
  538.    function Gvariant_New_String (String : UTF8_String) return Gvariant; 
  539.    --  Creates a string Glib.Variant.Gvariant with the contents of String. 
  540.    --  String must be valid utf8. 
  541.    --  Since: gtk+ 2.24 
  542.    --  "string": a normal utf8 nul-terminated string 
  543.  
  544.    procedure G_New_Strv 
  545.       (Self   : out Gvariant; 
  546.        Strv   : GNAT.Strings.String_List; 
  547.        Length : Gssize); 
  548.    --  Constructs an array of strings Glib.Variant.Gvariant from the given 
  549.    --  array of strings. 
  550.    --  If Length is -1 then Strv is null-terminated. 
  551.    --  Since: gtk+ 2.24 
  552.    --  "strv": an array of strings 
  553.    --  "length": the length of Strv, or -1 
  554.  
  555.    function Gvariant_New_Strv 
  556.       (Strv   : GNAT.Strings.String_List; 
  557.        Length : Gssize) return Gvariant; 
  558.    --  Constructs an array of strings Glib.Variant.Gvariant from the given 
  559.    --  array of strings. 
  560.    --  If Length is -1 then Strv is null-terminated. 
  561.    --  Since: gtk+ 2.24 
  562.    --  "strv": an array of strings 
  563.    --  "length": the length of Strv, or -1 
  564.  
  565.    procedure G_New_Uint16 (Self : out Gvariant; Value : Guint16); 
  566.    --  Creates a new uint16 Glib.Variant.Gvariant instance. 
  567.    --  Since: gtk+ 2.24 
  568.    --  "value": a Guint16 value 
  569.  
  570.    function Gvariant_New_Uint16 (Value : Guint16) return Gvariant; 
  571.    --  Creates a new uint16 Glib.Variant.Gvariant instance. 
  572.    --  Since: gtk+ 2.24 
  573.    --  "value": a Guint16 value 
  574.  
  575.    procedure G_New_Uint32 (Self : out Gvariant; Value : Guint32); 
  576.    --  Creates a new uint32 Glib.Variant.Gvariant instance. 
  577.    --  Since: gtk+ 2.24 
  578.    --  "value": a Guint32 value 
  579.  
  580.    function Gvariant_New_Uint32 (Value : Guint32) return Gvariant; 
  581.    --  Creates a new uint32 Glib.Variant.Gvariant instance. 
  582.    --  Since: gtk+ 2.24 
  583.    --  "value": a Guint32 value 
  584.  
  585.    procedure G_New_Uint64 (Self : out Gvariant; Value : Guint64); 
  586.    --  Creates a new uint64 Glib.Variant.Gvariant instance. 
  587.    --  Since: gtk+ 2.24 
  588.    --  "value": a Guint64 value 
  589.  
  590.    function Gvariant_New_Uint64 (Value : Guint64) return Gvariant; 
  591.    --  Creates a new uint64 Glib.Variant.Gvariant instance. 
  592.    --  Since: gtk+ 2.24 
  593.    --  "value": a Guint64 value 
  594.  
  595.    procedure G_New_Variant (Self : out Gvariant; Value : Gvariant); 
  596.    --  Boxes Value. The result is a Glib.Variant.Gvariant instance 
  597.    --  representing a variant containing the original value. 
  598.    --  If Child is a floating reference (see Glib.Variant.Ref_Sink), the new 
  599.    --  instance takes ownership of Child. 
  600.    --  Since: gtk+ 2.24 
  601.    --  "value": a Glib.Variant.Gvariant instance 
  602.  
  603.    function Gvariant_New_Variant (Value : Gvariant) return Gvariant; 
  604.    --  Boxes Value. The result is a Glib.Variant.Gvariant instance 
  605.    --  representing a variant containing the original value. 
  606.    --  If Child is a floating reference (see Glib.Variant.Ref_Sink), the new 
  607.    --  instance takes ownership of Child. 
  608.    --  Since: gtk+ 2.24 
  609.    --  "value": a Glib.Variant.Gvariant instance 
  610.  
  611.    procedure G_New (Self : out Gvariant_Type; Type_String : UTF8_String); 
  612.    --  Creates a new Glib.Variant.Gvariant_Type corresponding to the type 
  613.    --  string given by Type_String. It is appropriate to call Glib.Variant.Free 
  614.    --  on the return value. 
  615.    --  It is a programmer error to call this function with an invalid type 
  616.    --  string. Use Glib.Variant.String_Is_Valid if you are unsure. 
  617.    --  Since: gtk+ 2.24 
  618.    --  "type_string": a valid GVariant type string 
  619.  
  620.    function Gvariant_Type_New 
  621.       (Type_String : UTF8_String) return Gvariant_Type; 
  622.    --  Creates a new Glib.Variant.Gvariant_Type corresponding to the type 
  623.    --  string given by Type_String. It is appropriate to call Glib.Variant.Free 
  624.    --  on the return value. 
  625.    --  It is a programmer error to call this function with an invalid type 
  626.    --  string. Use Glib.Variant.String_Is_Valid if you are unsure. 
  627.    --  Since: gtk+ 2.24 
  628.    --  "type_string": a valid GVariant type string 
  629.  
  630.    function Gvariant_Type_New_Dict_Entry 
  631.       (Key   : Gvariant_Type; 
  632.        Value : Gvariant_Type) return Gvariant_Type; 
  633.    --  Constructs the type corresponding to a dictionary entry with a key of 
  634.    --  type Key and a value of type Value. 
  635.    --  It is appropriate to call Glib.Variant.Free on the return value. 
  636.    --  "key": a basic Glib.Variant.Gvariant_Type 
  637.    --  "value": a Glib.Variant.Gvariant_Type 
  638.  
  639.    function Get_Type return Glib.GType; 
  640.    pragma Import (C, Get_Type, "g_variant_type_get_gtype"); 
  641.  
  642.    ------------- 
  643.    -- Methods -- 
  644.    ------------- 
  645.  
  646.    function Byteswap (Self : Gvariant) return Gvariant; 
  647.    --  Performs a byteswapping operation on the contents of Value. The result 
  648.    --  is that all multi-byte numeric data contained in Value is byteswapped. 
  649.    --  That includes 16, 32, and 64bit signed and unsigned integers as well as 
  650.    --  file handles and double precision floating point values. 
  651.    --  This function is an identity mapping on any value that does not contain 
  652.    --  multi-byte numeric data. That include strings, booleans, bytes and 
  653.    --  containers containing only these things (recursively). 
  654.    --  The returned value is always in normal form and is marked as trusted. 
  655.    --  Since: gtk+ 2.24 
  656.  
  657.    function Check_Format_String 
  658.       (Self          : Gvariant; 
  659.        Format_String : UTF8_String; 
  660.        Copy_Only     : Boolean) return Boolean; 
  661.    --  Checks if calling g_variant_get with Format_String on Value would be 
  662.    --  valid from a type-compatibility standpoint. Format_String is assumed to 
  663.    --  be a valid format string (from a syntactic standpoint). 
  664.    --  If Copy_Only is True then this function additionally checks that it 
  665.    --  would be safe to call Glib.Variant.Unref on Value immediately after the 
  666.    --  call to g_variant_get without invalidating the result. This is only 
  667.    --  possible if deep copies are made (ie: there are no pointers to the data 
  668.    --  inside of the soon-to-be-freed Glib.Variant.Gvariant instance). If this 
  669.    --  check fails then a g_critical is printed and False is returned. 
  670.    --  This function is meant to be used by functions that wish to provide 
  671.    --  varargs accessors to Glib.Variant.Gvariant values of uncertain values 
  672.    --  (eg: g_variant_lookup or g_menu_model_get_item_attribute). 
  673.    --  Since: gtk+ 2.34 
  674.    --  "format_string": a valid Glib.Variant.Gvariant format string 
  675.    --  "copy_only": True to ensure the format string makes deep copies 
  676.  
  677.    function Classify (Self : Gvariant) return GVariant_Class; 
  678.    --  Classifies Value according to its top-level type. 
  679.    --  Since: gtk+ 2.24 
  680.  
  681.    function Dup_Bytestring_Array 
  682.       (Self   : Gvariant; 
  683.        Length : access Gsize) return GNAT.Strings.String_List; 
  684.    --  Gets the contents of an array of array of bytes Glib.Variant.Gvariant. 
  685.    --  This call makes a deep copy; the return result should be released with 
  686.    --  g_strfreev. 
  687.    --  If Length is non-null then the number of elements in the result is 
  688.    --  stored there. In any case, the resulting array will be null-terminated. 
  689.    --  For an empty array, Length will be set to 0 and a pointer to a null 
  690.    --  pointer will be returned. 
  691.    --  Since: gtk+ 2.26 
  692.    --  "length": the length of the result, or null 
  693.  
  694.    function Dup_Objv 
  695.       (Self   : Gvariant; 
  696.        Length : access Gsize) return GNAT.Strings.String_List; 
  697.    --  Gets the contents of an array of object paths Glib.Variant.Gvariant. 
  698.    --  This call makes a deep copy; the return result should be released with 
  699.    --  g_strfreev. 
  700.    --  If Length is non-null then the number of elements in the result is 
  701.    --  stored there. In any case, the resulting array will be null-terminated. 
  702.    --  For an empty array, Length will be set to 0 and a pointer to a null 
  703.    --  pointer will be returned. 
  704.    --  Since: gtk+ 2.30 
  705.    --  "length": the length of the result, or null 
  706.  
  707.    function Dup_String 
  708.       (Self   : Gvariant; 
  709.        Length : access Gsize) return UTF8_String; 
  710.    --  Similar to Glib.Variant.Get_String except that instead of returning a 
  711.    --  constant string, the string is duplicated. 
  712.    --  The string will always be utf8 encoded. 
  713.    --  The return value must be freed using g_free. 
  714.    --  Since: gtk+ 2.24 
  715.    --  "length": a pointer to a Gsize, to store the length 
  716.  
  717.    function Dup_String (Self : Gvariant_Type) return UTF8_String; 
  718.    --  Returns a newly-allocated copy of the type string corresponding to 
  719.    --  Type. The returned string is nul-terminated. It is appropriate to call 
  720.    --  g_free on the return value. 
  721.  
  722.    function Dup_Strv 
  723.       (Self   : Gvariant; 
  724.        Length : access Gsize) return GNAT.Strings.String_List; 
  725.    --  Gets the contents of an array of strings Glib.Variant.Gvariant. This 
  726.    --  call makes a deep copy; the return result should be released with 
  727.    --  g_strfreev. 
  728.    --  If Length is non-null then the number of elements in the result is 
  729.    --  stored there. In any case, the resulting array will be null-terminated. 
  730.    --  For an empty array, Length will be set to 0 and a pointer to a null 
  731.    --  pointer will be returned. 
  732.    --  Since: gtk+ 2.24 
  733.    --  "length": the length of the result, or null 
  734.  
  735.    function Get_Boolean (Self : Gvariant) return Boolean; 
  736.    --  Returns the boolean value of Value. 
  737.    --  It is an error to call this function with a Value of any type other 
  738.    --  than G_VARIANT_TYPE_BOOLEAN. 
  739.    --  Since: gtk+ 2.24 
  740.  
  741.    function Get_Byte (Self : Gvariant) return Guchar; 
  742.    --  Returns the byte value of Value. 
  743.    --  It is an error to call this function with a Value of any type other 
  744.    --  than G_VARIANT_TYPE_BYTE. 
  745.    --  Since: gtk+ 2.24 
  746.  
  747.    function Get_Bytestring_Array 
  748.       (Self   : Gvariant; 
  749.        Length : access Gsize) return GNAT.Strings.String_List; 
  750.    --  Gets the contents of an array of array of bytes Glib.Variant.Gvariant. 
  751.    --  This call makes a shallow copy; the return result should be released 
  752.    --  with g_free, but the individual strings must not be modified. 
  753.    --  If Length is non-null then the number of elements in the result is 
  754.    --  stored there. In any case, the resulting array will be null-terminated. 
  755.    --  For an empty array, Length will be set to 0 and a pointer to a null 
  756.    --  pointer will be returned. 
  757.    --  Since: gtk+ 2.26 
  758.    --  "length": the length of the result, or null 
  759.  
  760.    function Get_Child_Value (Self : Gvariant; Index : Gsize) return Gvariant; 
  761.    --  Reads a child item out of a container Glib.Variant.Gvariant instance. 
  762.    --  This includes variants, maybes, arrays, tuples and dictionary entries. 
  763.    --  It is an error to call this function on any other type of 
  764.    --  Glib.Variant.Gvariant. 
  765.    --  It is an error if Index_ is greater than the number of child items in 
  766.    --  the container. See Glib.Variant.N_Children. 
  767.    --  The returned value is never floating. You should free it with 
  768.    --  Glib.Variant.Unref when you're done with it. 
  769.    --  This function is O(1). 
  770.    --  Since: gtk+ 2.24 
  771.    --  "index_": the index of the child to fetch 
  772.  
  773.    function Get_Double (Self : Gvariant) return Gdouble; 
  774.    --  Returns the double precision floating point value of Value. 
  775.    --  It is an error to call this function with a Value of any type other 
  776.    --  than G_VARIANT_TYPE_DOUBLE. 
  777.    --  Since: gtk+ 2.24 
  778.  
  779.    function Get_Handle (Self : Gvariant) return Gint32; 
  780.    --  Returns the 32-bit signed integer value of Value. 
  781.    --  It is an error to call this function with a Value of any type other 
  782.    --  than G_VARIANT_TYPE_HANDLE. 
  783.    --  By convention, handles are indexes into an array of file descriptors 
  784.    --  that are sent alongside a D-Bus message. If you're not interacting with 
  785.    --  D-Bus, you probably don't need them. 
  786.    --  Since: gtk+ 2.24 
  787.  
  788.    function Get_Int16 (Self : Gvariant) return Gint16; 
  789.    --  Returns the 16-bit signed integer value of Value. 
  790.    --  It is an error to call this function with a Value of any type other 
  791.    --  than G_VARIANT_TYPE_INT16. 
  792.    --  Since: gtk+ 2.24 
  793.  
  794.    function Get_Int32 (Self : Gvariant) return Gint32; 
  795.    --  Returns the 32-bit signed integer value of Value. 
  796.    --  It is an error to call this function with a Value of any type other 
  797.    --  than G_VARIANT_TYPE_INT32. 
  798.    --  Since: gtk+ 2.24 
  799.  
  800.    function Get_Int64 (Self : Gvariant) return Gint64; 
  801.    --  Returns the 64-bit signed integer value of Value. 
  802.    --  It is an error to call this function with a Value of any type other 
  803.    --  than G_VARIANT_TYPE_INT64. 
  804.    --  Since: gtk+ 2.24 
  805.  
  806.    function Get_Maybe (Self : Gvariant) return Gvariant; 
  807.    --  Given a maybe-typed Glib.Variant.Gvariant instance, extract its value. 
  808.    --  If the value is Nothing, then this function returns null. 
  809.    --  Since: gtk+ 2.24 
  810.  
  811.    function Get_Normal_Form (Self : Gvariant) return Gvariant; 
  812.    --  Gets a Glib.Variant.Gvariant instance that has the same value as Value 
  813.    --  and is trusted to be in normal form. 
  814.    --  If Value is already trusted to be in normal form then a new reference 
  815.    --  to Value is returned. 
  816.    --  If Value is not already trusted, then it is scanned to check if it is 
  817.    --  in normal form. If it is found to be in normal form then it is marked as 
  818.    --  trusted and a new reference to it is returned. 
  819.    --  If Value is found not to be in normal form then a new trusted 
  820.    --  Glib.Variant.Gvariant is created with the same value as Value. 
  821.    --  It makes sense to call this function if you've received 
  822.    --  Glib.Variant.Gvariant data from untrusted sources and you want to ensure 
  823.    --  your serialised output is definitely in normal form. 
  824.    --  Since: gtk+ 2.24 
  825.  
  826.    function Get_Objv 
  827.       (Self   : Gvariant; 
  828.        Length : access Gsize) return GNAT.Strings.String_List; 
  829.    --  Gets the contents of an array of object paths Glib.Variant.Gvariant. 
  830.    --  This call makes a shallow copy; the return result should be released 
  831.    --  with g_free, but the individual strings must not be modified. 
  832.    --  If Length is non-null then the number of elements in the result is 
  833.    --  stored there. In any case, the resulting array will be null-terminated. 
  834.    --  For an empty array, Length will be set to 0 and a pointer to a null 
  835.    --  pointer will be returned. 
  836.    --  Since: gtk+ 2.30 
  837.    --  "length": the length of the result, or null 
  838.  
  839.    function Get_Size (Self : Gvariant) return Gsize; 
  840.    --  Determines the number of bytes that would be required to store Value 
  841.    --  with Glib.Variant.Store. 
  842.    --  If Value has a fixed-sized type then this function always returned that 
  843.    --  fixed size. 
  844.    --  In the case that Value is already in serialised form or the size has 
  845.    --  already been calculated (ie: this function has been called before) then 
  846.    --  this function is O(1). Otherwise, the size is calculated, an operation 
  847.    --  which is approximately O(n) in the number of values involved. 
  848.    --  Since: gtk+ 2.24 
  849.  
  850.    function Get_String 
  851.       (Self   : Gvariant; 
  852.        Length : access Gsize) return UTF8_String; 
  853.    --  Returns the string value of a Glib.Variant.Gvariant instance with a 
  854.    --  string type. This includes the types G_VARIANT_TYPE_STRING, 
  855.    --  G_VARIANT_TYPE_OBJECT_PATH and G_VARIANT_TYPE_SIGNATURE. 
  856.    --  The string will always be utf8 encoded. 
  857.    --  If Length is non-null then the length of the string (in bytes) is 
  858.    --  returned there. For trusted values, this information is already known. 
  859.    --  For untrusted values, a strlen will be performed. 
  860.    --  It is an error to call this function with a Value of any type other 
  861.    --  than those three. 
  862.    --  The return value remains valid as long as Value exists. 
  863.    --  Since: gtk+ 2.24 
  864.    --  "length": a pointer to a Gsize, to store the length 
  865.  
  866.    function Get_Strv 
  867.       (Self   : Gvariant; 
  868.        Length : access Gsize) return GNAT.Strings.String_List; 
  869.    --  Gets the contents of an array of strings Glib.Variant.Gvariant. This 
  870.    --  call makes a shallow copy; the return result should be released with 
  871.    --  g_free, but the individual strings must not be modified. 
  872.    --  If Length is non-null then the number of elements in the result is 
  873.    --  stored there. In any case, the resulting array will be null-terminated. 
  874.    --  For an empty array, Length will be set to 0 and a pointer to a null 
  875.    --  pointer will be returned. 
  876.    --  Since: gtk+ 2.24 
  877.    --  "length": the length of the result, or null 
  878.  
  879.    function Get_Type (Self : Gvariant) return Gvariant_Type; 
  880.    --  Determines the type of Value. 
  881.    --  The return value is valid for the lifetime of Value and must not be 
  882.    --  freed. 
  883.    --  Since: gtk+ 2.24 
  884.  
  885.    function Get_Type_String (Self : Gvariant) return UTF8_String; 
  886.    --  Returns the type string of Value. Unlike the result of calling 
  887.    --  Glib.Variant.Peek_String, this string is nul-terminated. This string 
  888.    --  belongs to Glib.Variant.Gvariant and must not be freed. 
  889.    --  Since: gtk+ 2.24 
  890.  
  891.    function Get_Uint16 (Self : Gvariant) return Guint16; 
  892.    --  Returns the 16-bit unsigned integer value of Value. 
  893.    --  It is an error to call this function with a Value of any type other 
  894.    --  than G_VARIANT_TYPE_UINT16. 
  895.    --  Since: gtk+ 2.24 
  896.  
  897.    function Get_Uint32 (Self : Gvariant) return Guint32; 
  898.    --  Returns the 32-bit unsigned integer value of Value. 
  899.    --  It is an error to call this function with a Value of any type other 
  900.    --  than G_VARIANT_TYPE_UINT32. 
  901.    --  Since: gtk+ 2.24 
  902.  
  903.    function Get_Uint64 (Self : Gvariant) return Guint64; 
  904.    --  Returns the 64-bit unsigned integer value of Value. 
  905.    --  It is an error to call this function with a Value of any type other 
  906.    --  than G_VARIANT_TYPE_UINT64. 
  907.    --  Since: gtk+ 2.24 
  908.  
  909.    function Get_Variant (Self : Gvariant) return Gvariant; 
  910.    --  Unboxes Value. The result is the Glib.Variant.Gvariant instance that 
  911.    --  was contained in Value. 
  912.    --  Since: gtk+ 2.24 
  913.  
  914.    function Hash (Self : Gvariant) return Guint; 
  915.    --  Generates a hash value for a Glib.Variant.Gvariant instance. 
  916.    --  The output of this function is guaranteed to be the same for a given 
  917.    --  value only per-process. It may change between different processor 
  918.    --  architectures or even different versions of GLib. Do not use this 
  919.    --  function as a basis for building protocols or file formats. 
  920.    --  The type of Value is gconstpointer only to allow use of this function 
  921.    --  with GHash_Table. Value must be a Glib.Variant.Gvariant. 
  922.    --  Since: gtk+ 2.24 
  923.  
  924.    function Is_Container (Self : Gvariant) return Boolean; 
  925.    --  Checks if Value is a container. 
  926.    --  Since: gtk+ 2.24 
  927.  
  928.    function Is_Container (Self : Gvariant_Type) return Boolean; 
  929.    --  Determines if the given Type is a container type. 
  930.    --  Container types are any array, maybe, tuple, or dictionary entry types 
  931.    --  plus the variant type. 
  932.    --  This function returns True for any indefinite type for which every 
  933.    --  definite subtype is a container -- G_VARIANT_TYPE_ARRAY, for example. 
  934.  
  935.    function Is_Floating (Self : Gvariant) return Boolean; 
  936.    --  Checks whether Value has a floating reference count. 
  937.    --  This function should only ever be used to assert that a given variant 
  938.    --  is or is not floating, or for debug purposes. To acquire a reference to 
  939.    --  a variant that might be floating, always use Glib.Variant.Ref_Sink or 
  940.    --  Glib.Variant.Take_Ref. 
  941.    --  See Glib.Variant.Ref_Sink for more information about floating reference 
  942.    --  counts. 
  943.    --  Since: gtk+ 2.26 
  944.  
  945.    function Is_Normal_Form (Self : Gvariant) return Boolean; 
  946.    --  Checks if Value is in normal form. 
  947.    --  The main reason to do this is to detect if a given chunk of serialised 
  948.    --  data is in normal form: load the data into a Glib.Variant.Gvariant using 
  949.    --  g_variant_new_from_data and then use this function to check. 
  950.    --  If Value is found to be in normal form then it will be marked as being 
  951.    --  trusted. If the value was already marked as being trusted then this 
  952.    --  function will immediately return True. 
  953.    --  Since: gtk+ 2.24 
  954.  
  955.    function Is_Of_Type 
  956.       (Self     : Gvariant; 
  957.        The_Type : Gvariant_Type) return Boolean; 
  958.    --  Checks if a value has a type matching the provided type. 
  959.    --  Since: gtk+ 2.24 
  960.    --  "type": a Glib.Variant.Gvariant_Type 
  961.  
  962.    function Iter_New (Self : Gvariant) return Gvariant_Iter; 
  963.    --  Creates a heap-allocated Glib.Variant.Gvariant_Iter for iterating over 
  964.    --  the items in Value. 
  965.    --  Use g_variant_iter_free to free the return value when you no longer 
  966.    --  need it. 
  967.    --  A reference is taken to Value and will be released only when 
  968.    --  g_variant_iter_free is called. 
  969.    --  Since: gtk+ 2.24 
  970.  
  971.    function Lookup_Value 
  972.       (Self          : Gvariant; 
  973.        Key           : UTF8_String; 
  974.        Expected_Type : Gvariant_Type) return Gvariant; 
  975.    --  Looks up a value in a dictionary Glib.Variant.Gvariant. 
  976.    --  This function works with dictionaries of the type 'a{s*}' (and equally 
  977.    --  well with type 'a{o*}', but we only further discuss the string case for 
  978.    --  sake of clarity). 
  979.    --  In the event that Dictionary has the type 'a{sv}', the Expected_Type 
  980.    --  string specifies what type of value is expected to be inside of the 
  981.    --  variant. If the value inside the variant has a different type then null 
  982.    --  is returned. In the event that Dictionary has a value type other than 
  983.    --  'v' then Expected_Type must directly match the key type and it is used 
  984.    --  to unpack the value directly or an error occurs. 
  985.    --  In either case, if Key is not found in Dictionary, null is returned. 
  986.    --  If the key is found and the value has the correct type, it is returned. 
  987.    --  If Expected_Type was specified then any non-null return value will have 
  988.    --  this type. 
  989.    --  Since: gtk+ 2.28 
  990.    --  "key": the key to lookup in the dictionary 
  991.    --  "expected_type": a Glib.Variant.Gvariant_Type, or null 
  992.  
  993.    function N_Children (Self : Gvariant) return Gsize; 
  994.    --  Determines the number of children in a container Glib.Variant.Gvariant 
  995.    --  instance. This includes variants, maybes, arrays, tuples and dictionary 
  996.    --  entries. It is an error to call this function on any other type of 
  997.    --  Glib.Variant.Gvariant. 
  998.    --  For variants, the return value is always 1. For values with maybe 
  999.    --  types, it is always zero or one. For arrays, it is the length of the 
  1000.    --  array. For tuples it is the number of tuple items (which depends only on 
  1001.    --  the type). For dictionary entries, it is always 2 
  1002.    --  This function is O(1). 
  1003.    --  Since: gtk+ 2.24 
  1004.  
  1005.    function Print 
  1006.       (Self          : Gvariant; 
  1007.        Type_Annotate : Boolean) return UTF8_String; 
  1008.    --  Pretty-prints Value in the format understood by Glib.Variant.Parse. 
  1009.    --  The format is described <link linkend='gvariant-text'>here</link>. 
  1010.    --  If Type_Annotate is True, then type information is included in the 
  1011.    --  output. 
  1012.    --  Since: gtk+ 2.24 
  1013.    --  "type_annotate": True if type information should be included in the 
  1014.    --  output 
  1015.  
  1016.    function Print_String 
  1017.       (Self          : Gvariant; 
  1018.        String        : Glib.String.Gstring; 
  1019.        Type_Annotate : Boolean) return Glib.String.Gstring; 
  1020.    --  Behaves as Glib.Variant.Print, but operates on a Glib.String.Gstring. 
  1021.    --  If String is non-null then it is appended to and returned. Else, a new 
  1022.    --  empty Glib.String.Gstring is allocated and it is returned. 
  1023.    --  Since: gtk+ 2.24 
  1024.    --  "string": a Glib.String.Gstring, or null 
  1025.    --  "type_annotate": True if type information should be included in the 
  1026.    --  output 
  1027.  
  1028.    function Ref (Self : Gvariant) return Gvariant; 
  1029.    --  Increases the reference count of Value. 
  1030.    --  Since: gtk+ 2.24 
  1031.  
  1032.    function Ref_Sink (Self : Gvariant) return Gvariant; 
  1033.    --  Glib.Variant.Gvariant uses a floating reference count system. All 
  1034.    --  functions with names starting with 'g_variant_new_' return floating 
  1035.    --  references. 
  1036.    --  Calling Glib.Variant.Ref_Sink on a Glib.Variant.Gvariant with a 
  1037.    --  floating reference will convert the floating reference into a full 
  1038.    --  reference. Calling Glib.Variant.Ref_Sink on a non-floating 
  1039.    --  Glib.Variant.Gvariant results in an additional normal reference being 
  1040.    --  added. 
  1041.    --  In other words, if the Value is floating, then this call "assumes 
  1042.    --  ownership" of the floating reference, converting it to a normal 
  1043.    --  reference. If the Value is not floating, then this call adds a new 
  1044.    --  normal reference increasing the reference count by one. 
  1045.    --  All calls that result in a Glib.Variant.Gvariant instance being 
  1046.    --  inserted into a container will call Glib.Variant.Ref_Sink on the 
  1047.    --  instance. This means that if the value was just created (and has only 
  1048.    --  its floating reference) then the container will assume sole ownership of 
  1049.    --  the value at that point and the caller will not need to unreference it. 
  1050.    --  This makes certain common styles of programming much easier while still 
  1051.    --  maintaining normal refcounting semantics in situations where values are 
  1052.    --  not floating. 
  1053.    --  Since: gtk+ 2.24 
  1054.  
  1055.    procedure Store (Self : Gvariant; Data : System.Address); 
  1056.    --  Stores the serialised form of Value at Data. Data should be large 
  1057.    --  enough. See Glib.Variant.Get_Size. 
  1058.    --  The stored data is in machine native byte order but may not be in 
  1059.    --  fully-normalised form if read from an untrusted source. See 
  1060.    --  Glib.Variant.Get_Normal_Form for a solution. 
  1061.    --  As with g_variant_get_data, to be able to deserialise the serialised 
  1062.    --  variant successfully, its type and (if the destination machine might be 
  1063.    --  different) its endianness must also be available. 
  1064.    --  This function is approximately O(n) in the size of Data. 
  1065.    --  Since: gtk+ 2.24 
  1066.    --  "data": the location to store the serialised data at 
  1067.  
  1068.    function Take_Ref (Self : Gvariant) return Gvariant; 
  1069.    --  If Value is floating, sink it. Otherwise, do nothing. 
  1070.    --  Typically you want to use Glib.Variant.Ref_Sink in order to 
  1071.    --  automatically do the correct thing with respect to floating or 
  1072.    --  non-floating references, but there is one specific scenario where this 
  1073.    --  function is helpful. 
  1074.    --  The situation where this function is helpful is when creating an API 
  1075.    --  that allows the user to provide a callback function that returns a 
  1076.    --  Glib.Variant.Gvariant. We certainly want to allow the user the 
  1077.    --  flexibility to return a non-floating reference from this callback (for 
  1078.    --  the case where the value that is being returned already exists). 
  1079.    --  At the same time, the style of the Glib.Variant.Gvariant API makes it 
  1080.    --  likely that for newly-created Glib.Variant.Gvariant instances, the user 
  1081.    --  can be saved some typing if they are allowed to return a 
  1082.    --  Glib.Variant.Gvariant with a floating reference. 
  1083.    --  Using this function on the return value of the user's callback allows 
  1084.    --  the user to do whichever is more convenient for them. The caller will 
  1085.    --  alway receives exactly one full reference to the value: either the one 
  1086.    --  that was returned in the first place, or a floating reference that has 
  1087.    --  been converted to a full reference. 
  1088.    --  This function has an odd interaction when combined with 
  1089.    --  Glib.Variant.Ref_Sink running at the same time in another thread on the 
  1090.    --  same Glib.Variant.Gvariant instance. If Glib.Variant.Ref_Sink runs first 
  1091.    --  then the result will be that the floating reference is converted to a 
  1092.    --  hard reference. If Glib.Variant.Take_Ref runs first then the result will 
  1093.    --  be that the floating reference is converted to a hard reference and an 
  1094.    --  additional reference on top of that one is added. It is best to avoid 
  1095.    --  this situation. 
  1096.  
  1097.    procedure Unref (Self : Gvariant); 
  1098.    --  Decreases the reference count of Value. When its reference count drops 
  1099.    --  to 0, the memory used by the variant is freed. 
  1100.    --  Since: gtk+ 2.24 
  1101.  
  1102.    function Init (Self : Gvariant_Iter; Value : Gvariant) return Gsize; 
  1103.    --  Initialises (without allocating) a Glib.Variant.Gvariant_Iter. Iter may 
  1104.    --  be completely uninitialised prior to this call; its old value is 
  1105.    --  ignored. 
  1106.    --  The iterator remains valid for as long as Value exists, and need not be 
  1107.    --  freed in any way. 
  1108.    --  Since: gtk+ 2.24 
  1109.    --  "value": a container Glib.Variant.Gvariant 
  1110.  
  1111.    function Next_Value (Self : Gvariant_Iter) return Gvariant; 
  1112.    --  Gets the next item in the container. If no more items remain then null 
  1113.    --  is returned. 
  1114.    --  Use Glib.Variant.Unref to drop your reference on the return value when 
  1115.    --  you no longer need it. 
  1116.    --  
  1117.    --  == Iterating with Glib.Variant.Next_Value == 
  1118.    --  
  1119.    --    /<!-- -->* recursively iterate a container *<!-- -->/ 
  1120.    --    void 
  1121.    --    iterate_container_recursive (GVariant *container) 
  1122.    --    { 
  1123.    --       GVariantIter iter; 
  1124.    --       GVariant *child; 
  1125.    --       g_variant_iter_init (&iter, container); 
  1126.    --       while ((child = g_variant_iter_next_value (&iter))) 
  1127.    --       { 
  1128.    --          g_print ("type '%s'\n", g_variant_get_type_string (child)); 
  1129.    --          if (g_variant_is_container (child)) 
  1130.    --          iterate_container_recursive (child); 
  1131.    --          g_variant_unref (child); 
  1132.    --       } 
  1133.    --    } 
  1134.    --  Since: gtk+ 2.24 
  1135.  
  1136.    function Copy (Self : Gvariant_Type) return Gvariant_Type; 
  1137.    pragma Import (C, Copy, "g_variant_type_copy"); 
  1138.    --  Makes a copy of a Glib.Variant.Gvariant_Type. It is appropriate to call 
  1139.    --  Glib.Variant.Free on the return value. Type may not be null. 
  1140.  
  1141.    function Element (Self : Gvariant_Type) return Gvariant_Type; 
  1142.    pragma Import (C, Element, "g_variant_type_element"); 
  1143.    --  Determines the element type of an array or maybe type. 
  1144.    --  This function may only be used with array or maybe types. 
  1145.  
  1146.    function First (Self : Gvariant_Type) return Gvariant_Type; 
  1147.    pragma Import (C, First, "g_variant_type_first"); 
  1148.    --  Determines the first item type of a tuple or dictionary entry type. 
  1149.    --  This function may only be used with tuple or dictionary entry types, 
  1150.    --  but must not be used with the generic tuple type G_VARIANT_TYPE_TUPLE. 
  1151.    --  In the case of a dictionary entry type, this returns the type of the 
  1152.    --  key. 
  1153.    --  null is returned in case of Type being G_VARIANT_TYPE_UNIT. 
  1154.    --  This call, together with Glib.Variant.Next provides an iterator 
  1155.    --  interface over tuple and dictionary entry types. 
  1156.  
  1157.    procedure Free (Self : Gvariant_Type); 
  1158.    pragma Import (C, Free, "g_variant_type_free"); 
  1159.    --  Frees a Glib.Variant.Gvariant_Type that was allocated with 
  1160.    --  Glib.Variant.Copy, g_variant_type_new or one of the container type 
  1161.    --  constructor functions. 
  1162.    --  In the case that Type is null, this function does nothing. 
  1163.    --  Since 2.24 
  1164.  
  1165.    function Get_String_Length (Self : Gvariant_Type) return Gsize; 
  1166.    pragma Import (C, Get_String_Length, "g_variant_type_get_string_length"); 
  1167.    --  Returns the length of the type string corresponding to the given Type. 
  1168.    --  This function must be used to determine the valid extent of the memory 
  1169.    --  region returned by Glib.Variant.Peek_String. 
  1170.  
  1171.    function Is_Array (Self : Gvariant_Type) return Boolean; 
  1172.    --  Determines if the given Type is an array type. This is true if the type 
  1173.    --  string for Type starts with an 'a'. 
  1174.    --  This function returns True for any indefinite type for which every 
  1175.    --  definite subtype is an array type -- G_VARIANT_TYPE_ARRAY, for example. 
  1176.  
  1177.    function Is_Basic (Self : Gvariant_Type) return Boolean; 
  1178.    --  Determines if the given Type is a basic type. 
  1179.    --  Basic types are booleans, bytes, integers, doubles, strings, object 
  1180.    --  paths and signatures. 
  1181.    --  Only a basic type may be used as the key of a dictionary entry. 
  1182.    --  This function returns False for all indefinite types except 
  1183.    --  G_VARIANT_TYPE_BASIC. 
  1184.  
  1185.    function Is_Definite (Self : Gvariant_Type) return Boolean; 
  1186.    --  Determines if the given Type is definite (ie: not indefinite). 
  1187.    --  A type is definite if its type string does not contain any indefinite 
  1188.    --  type characters ('*', '?', or 'r'). 
  1189.    --  A Glib.Variant.Gvariant instance may not have an indefinite type, so 
  1190.    --  calling this function on the result of Glib.Variant.Get_Type will always 
  1191.    --  result in True being returned. Calling this function on an indefinite 
  1192.    --  type like G_VARIANT_TYPE_ARRAY, however, will result in False being 
  1193.    --  returned. 
  1194.  
  1195.    function Is_Dict_Entry (Self : Gvariant_Type) return Boolean; 
  1196.    --  Determines if the given Type is a dictionary entry type. This is true 
  1197.    --  if the type string for Type starts with a '{'. 
  1198.    --  This function returns True for any indefinite type for which every 
  1199.    --  definite subtype is a dictionary entry type -- 
  1200.    --  G_VARIANT_TYPE_DICT_ENTRY, for example. 
  1201.  
  1202.    function Is_Maybe (Self : Gvariant_Type) return Boolean; 
  1203.    --  Determines if the given Type is a maybe type. This is true if the type 
  1204.    --  string for Type starts with an 'm'. 
  1205.    --  This function returns True for any indefinite type for which every 
  1206.    --  definite subtype is a maybe type -- G_VARIANT_TYPE_MAYBE, for example. 
  1207.  
  1208.    function Is_Subtype_Of 
  1209.       (Self      : Gvariant_Type; 
  1210.        Supertype : Gvariant_Type) return Boolean; 
  1211.    --  Checks if Type is a subtype of Supertype. 
  1212.    --  This function returns True if Type is a subtype of Supertype. All types 
  1213.    --  are considered to be subtypes of themselves. Aside from that, only 
  1214.    --  indefinite types can have subtypes. 
  1215.    --  "supertype": a Glib.Variant.Gvariant_Type 
  1216.  
  1217.    function Is_Tuple (Self : Gvariant_Type) return Boolean; 
  1218.    --  Determines if the given Type is a tuple type. This is true if the type 
  1219.    --  string for Type starts with a '(' or if Type is G_VARIANT_TYPE_TUPLE. 
  1220.    --  This function returns True for any indefinite type for which every 
  1221.    --  definite subtype is a tuple type -- G_VARIANT_TYPE_TUPLE, for example. 
  1222.  
  1223.    function Is_Variant (Self : Gvariant_Type) return Boolean; 
  1224.    --  Determines if the given Type is the variant type. 
  1225.  
  1226.    function Key (Self : Gvariant_Type) return Gvariant_Type; 
  1227.    pragma Import (C, Key, "g_variant_type_key"); 
  1228.    --  Determines the key type of a dictionary entry type. 
  1229.    --  This function may only be used with a dictionary entry type. Other than 
  1230.    --  the additional restriction, this call is equivalent to 
  1231.    --  Glib.Variant.First. 
  1232.  
  1233.    function N_Items (Self : Gvariant_Type) return Gsize; 
  1234.    pragma Import (C, N_Items, "g_variant_type_n_items"); 
  1235.    --  Determines the number of items contained in a tuple or dictionary entry 
  1236.    --  type. 
  1237.    --  This function may only be used with tuple or dictionary entry types, 
  1238.    --  but must not be used with the generic tuple type G_VARIANT_TYPE_TUPLE. 
  1239.    --  In the case of a dictionary entry type, this function will always 
  1240.    --  return 2. 
  1241.  
  1242.    function Next (Self : Gvariant_Type) return Gvariant_Type; 
  1243.    pragma Import (C, Next, "g_variant_type_next"); 
  1244.    --  Determines the next item type of a tuple or dictionary entry type. 
  1245.    --  Type must be the result of a previous call to Glib.Variant.First or 
  1246.    --  Glib.Variant.Next. 
  1247.    --  If called on the key type of a dictionary entry then this call returns 
  1248.    --  the value type. If called on the value type of a dictionary entry then 
  1249.    --  this call returns null. 
  1250.    --  For tuples, null is returned when Type is the last item in a tuple. 
  1251.  
  1252.    function Peek_String (Self : Gvariant_Type) return UTF8_String; 
  1253.    --  Returns the type string corresponding to the given Type. The result is 
  1254.    --  not nul-terminated; in order to determine its length you must call 
  1255.    --  Glib.Variant.Get_String_Length. 
  1256.    --  To get a nul-terminated string, see Glib.Variant.Dup_String. 
  1257.  
  1258.    function Value (Self : Gvariant_Type) return Gvariant_Type; 
  1259.    pragma Import (C, Value, "g_variant_type_value"); 
  1260.    --  Determines the value type of a dictionary entry type. 
  1261.    --  This function may only be used with a dictionary entry type. 
  1262.  
  1263.    --------------- 
  1264.    -- Functions -- 
  1265.    --------------- 
  1266.  
  1267.    function Is_Object_Path (String : UTF8_String) return Boolean; 
  1268.    --  Determines if a given string is a valid D-Bus object path. You should 
  1269.    --  ensure that a string is a valid D-Bus object path before passing it to 
  1270.    --  g_variant_new_object_path. 
  1271.    --  A valid object path starts with '/' followed by zero or more sequences 
  1272.    --  of characters separated by '/' characters. Each sequence must contain 
  1273.    --  only the characters "[A-Z][a-z][0-9]_". No sequence (including the one 
  1274.    --  following the final '/' character) may be empty. 
  1275.    --  Since: gtk+ 2.24 
  1276.    --  "string": a normal C nul-terminated string 
  1277.  
  1278.    function Is_Signature (String : UTF8_String) return Boolean; 
  1279.    --  Determines if a given string is a valid D-Bus type signature. You 
  1280.    --  should ensure that a string is a valid D-Bus type signature before 
  1281.    --  passing it to g_variant_new_signature. 
  1282.    --  D-Bus type signatures consist of zero or more definite 
  1283.    --  Glib.Variant.Gvariant_Type strings in sequence. 
  1284.    --  Since: gtk+ 2.24 
  1285.    --  "string": a normal C nul-terminated string 
  1286.  
  1287.    function Parse 
  1288.       (The_Type : Gvariant_Type; 
  1289.        Text     : UTF8_String; 
  1290.        Limit    : UTF8_String := ""; 
  1291.        Endptr   : GNAT.Strings.String_List) return Gvariant; 
  1292.    --  Parses a Glib.Variant.Gvariant from a text representation. 
  1293.    --  A single Glib.Variant.Gvariant is parsed from the content of Text. 
  1294.    --  The format is described <link linkend='gvariant-text'>here</link>. 
  1295.    --  The memory at Limit will never be accessed and the parser behaves as if 
  1296.    --  the character at Limit is the nul terminator. This has the effect of 
  1297.    --  bounding Text. 
  1298.    --  If Endptr is non-null then Text is permitted to contain data following 
  1299.    --  the value that this function parses and Endptr will be updated to point 
  1300.    --  to the first character past the end of the text parsed by this function. 
  1301.    --  If Endptr is null and there is extra data then an error is returned. 
  1302.    --  If Type is non-null then the value will be parsed to have that type. 
  1303.    --  This may result in additional parse errors (in the case that the parsed 
  1304.    --  value doesn't fit the type) but may also result in fewer errors (in the 
  1305.    --  case that the type would have been ambiguous, such as with empty 
  1306.    --  arrays). 
  1307.    --  In the event that the parsing is successful, the resulting 
  1308.    --  Glib.Variant.Gvariant is returned. 
  1309.    --  In case of any error, null will be returned. If Error is non-null then 
  1310.    --  it will be set to reflect the error that occurred. 
  1311.    --  Officially, the language understood by the parser is "any string 
  1312.    --  produced by Glib.Variant.Print". 
  1313.    --  "type": a Glib.Variant.Gvariant_Type, or null 
  1314.    --  "text": a string containing a GVariant in text form 
  1315.    --  "limit": a pointer to the end of Text, or null 
  1316.    --  "endptr": a location to store the end pointer, or null 
  1317.  
  1318.    function Parser_Get_Error_Quark return Glib.GQuark; 
  1319.  
  1320.    function String_Is_Valid (Type_String : UTF8_String) return Boolean; 
  1321.    --  Checks if Type_String is a valid GVariant type string. This call is 
  1322.    --  equivalent to calling g_variant_type_string_scan and confirming that the 
  1323.    --  following character is a nul terminator. 
  1324.    --  "type_string": a pointer to any string 
  1325.  
  1326. private 
  1327.  
  1328.    Null_Gvariant : constant Gvariant := (Glib.C_Boxed with null record); 
  1329.  
  1330. end Glib.Variant;