2 * Copyright © 2007, 2008 Ryan Lortie
3 * Copyright © 2009, 2010 Codethink Limited
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the licence, or (at your option) any later version.
10 * This library 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 GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 * Author: Ryan Lortie <desrt@desrt.ca>
21 #ifndef __G_VARIANT_TYPE_H__
22 #define __G_VARIANT_TYPE_H__
24 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
25 #error "Only <glib.h> can be included directly."
28 #include <glib/gmessages.h>
29 #include <glib/gtypes.h>
36 * A type in the GVariant type system.
38 * Two types may not be compared by value; use g_variant_type_equal() or
39 * g_variant_type_is_subtype_of(). May be copied using
40 * g_variant_type_copy() and freed using g_variant_type_free().
42 typedef struct _GVariantType GVariantType;
45 * G_VARIANT_TYPE_BOOLEAN:
47 * The type of a value that can be either %TRUE or %FALSE.
49 #define G_VARIANT_TYPE_BOOLEAN ((const GVariantType *) "b")
52 * G_VARIANT_TYPE_BYTE:
54 * The type of an integer value that can range from 0 to 255.
56 #define G_VARIANT_TYPE_BYTE ((const GVariantType *) "y")
59 * G_VARIANT_TYPE_INT16:
61 * The type of an integer value that can range from -32768 to 32767.
63 #define G_VARIANT_TYPE_INT16 ((const GVariantType *) "n")
66 * G_VARIANT_TYPE_UINT16:
68 * The type of an integer value that can range from 0 to 65535.
69 * There were about this many people living in Toronto in the 1870s.
71 #define G_VARIANT_TYPE_UINT16 ((const GVariantType *) "q")
74 * G_VARIANT_TYPE_INT32:
76 * The type of an integer value that can range from -2147483648 to
79 #define G_VARIANT_TYPE_INT32 ((const GVariantType *) "i")
82 * G_VARIANT_TYPE_UINT32:
84 * The type of an integer value that can range from 0 to 4294967295.
85 * That's one number for everyone who was around in the late 1970s.
87 #define G_VARIANT_TYPE_UINT32 ((const GVariantType *) "u")
90 * G_VARIANT_TYPE_INT64:
92 * The type of an integer value that can range from
93 * -9223372036854775808 to 9223372036854775807.
95 #define G_VARIANT_TYPE_INT64 ((const GVariantType *) "x")
98 * G_VARIANT_TYPE_UINT64:
100 * The type of an integer value that can range from 0 to
101 * 18446744073709551616. That's a really big number, but a Rubik's
102 * cube can have a bit more than twice as many possible positions.
104 #define G_VARIANT_TYPE_UINT64 ((const GVariantType *) "t")
107 * G_VARIANT_TYPE_FLOAT:
109 * The type of a single precision IEEE754 floating point number. You
110 * can store a number as large as 3.40e38 in these (plus and minus) but
111 * there are some gaps on the way.
113 #define G_VARIANT_TYPE_FLOAT ((const GVariantType *) "f")
116 * G_VARIANT_TYPE_DOUBLE:
118 * The type of a double precision IEEE754 floating point number.
119 * These guys go up to about 1.80e308 (plus and minus) but miss out on
120 * some numbers in between. In any case, that's far greater than the
121 * estimated number of fundamental particles in the observable
124 #define G_VARIANT_TYPE_DOUBLE ((const GVariantType *) "d")
127 * G_VARIANT_TYPE_STRING:
129 * The type of a string. "" is a string. %NULL is not a string.
131 #define G_VARIANT_TYPE_STRING ((const GVariantType *) "s")
134 * G_VARIANT_TYPE_OBJECT_PATH:
136 * The type of a D-Bus object reference. These are strings of a
137 * specific format used to identify objects at a given destination on
140 * If you are not interacting with D-Bus, then there is no reason to make
141 * use of this type. If you are, then the D-Bus specification contains a
142 * precise description of valid object paths.
144 #define G_VARIANT_TYPE_OBJECT_PATH ((const GVariantType *) "o")
147 * G_VARIANT_TYPE_SIGNATURE:
149 * The type of a D-Bus type signature. These are strings of a specific
150 * format used as type signatures for D-Bus methods and messages.
152 * If you are not interacting with D-Bus, then there is no reason to make
153 * use of this type. If you are, then the D-Bus specification contains a
154 * precise description of valid signature strings.
156 #define G_VARIANT_TYPE_SIGNATURE ((const GVariantType *) "g")
159 * G_VARIANT_TYPE_VARIANT:
161 * The type of a box that contains any other value (including another
164 #define G_VARIANT_TYPE_VARIANT ((const GVariantType *) "v")
167 * G_VARIANT_TYPE_HANDLE:
169 * The type of a 32bit signed integer value, that by convention, is used
170 * as an index into an array of file descriptors that are sent alongside
173 * If you are not interacting with D-Bus, then there is no reason to make
176 #define G_VARIANT_TYPE_HANDLE ((const GVariantType *) "h")
179 * G_VARIANT_TYPE_UNIT:
181 * The empty tuple type. Has only one instance. Known also as "triv"
184 #define G_VARIANT_TYPE_UNIT ((const GVariantType *) "()")
187 * G_VARIANT_TYPE_ANY:
189 * An indefinite type that is a supertype of every type (including
192 #define G_VARIANT_TYPE_ANY ((const GVariantType *) "*")
195 * G_VARIANT_TYPE_BASIC:
197 * An indefinite type that is a supertype of every basic (ie:
198 * non-container) type.
200 #define G_VARIANT_TYPE_BASIC ((const GVariantType *) "?")
203 * G_VARIANT_TYPE_MAYBE:
205 * An indefinite type that is a supertype of every maybe type.
207 #define G_VARIANT_TYPE_MAYBE ((const GVariantType *) "m*")
210 * G_VARIANT_TYPE_ARRAY:
212 * An indefinite type that is a supertype of every array type.
214 #define G_VARIANT_TYPE_ARRAY ((const GVariantType *) "a*")
217 * G_VARIANT_TYPE_TUPLE:
219 * An indefinite type that is a supertype of every tuple type,
220 * regardless of the number of items in the tuple.
222 #define G_VARIANT_TYPE_TUPLE ((const GVariantType *) "r")
225 * G_VARIANT_TYPE_DICT_ENTRY:
227 * An indefinite type that is a supertype of every dictionary entry
230 #define G_VARIANT_TYPE_DICT_ENTRY ((const GVariantType *) "{?*}")
233 * G_VARIANT_TYPE_DICTIONARY:
235 * An indefinite type that is a supertype of every dictionary type --
236 * that is, any array type that has an element type equal to any
237 * dictionary entry type.
239 #define G_VARIANT_TYPE_DICTIONARY ((const GVariantType *) "a{?*}")
242 * G_VARIANT_TYPE_STRING_ARRAY:
244 * The type of an array of strings.
246 #define G_VARIANT_TYPE_STRING_ARRAY ((const GVariantType *) "as")
249 * G_VARIANT_TYPE_OBJECT_PATH_ARRAY:
251 * The type of an array of object paths.
253 #define G_VARIANT_TYPE_OBJECT_PATH_ARRAY ((const GVariantType *) "ao")
256 * G_VARIANT_TYPE_BYTESTRING:
258 * The type of an array of bytes. This type is commonly used to pass
259 * around strings that may not be valid utf8. In that case, the
260 * convention is that the nul terminator character should be included as
261 * the last character in the array.
263 #define G_VARIANT_TYPE_BYTESTRING ((const GVariantType *) "ay")
266 * G_VARIANT_TYPE_BYTESTRING_ARRAY:
268 * The type of an array of byte strings (an array of arrays of bytes).
270 #define G_VARIANT_TYPE_BYTESTRING_ARRAY ((const GVariantType *) "aay")
273 * G_VARIANT_TYPE_VARDICT:
275 * The type of a dictionary mapping strings to variants (the ubiquitous
280 #define G_VARIANT_TYPE_VARDICT ((const GVariantType *) "a{sv}")
285 * @type_string: a well-formed #GVariantType type string
287 * Converts a string to a const #GVariantType. Depending on the
288 * current debugging level, this function may perform a runtime check
289 * to ensure that @string is a valid GVariant type string.
291 * It is always a programmer error to use this macro with an invalid
292 * type string. If in doubt, use g_variant_type_string_is_valid() to
293 * check if the string is valid.
297 #ifndef G_DISABLE_CHECKS
298 # define G_VARIANT_TYPE(type_string) (g_variant_type_checked_ ((type_string)))
300 # define G_VARIANT_TYPE(type_string) ((const GVariantType *) (type_string))
303 /* type string checking */
304 GLIB_AVAILABLE_IN_ALL
305 gboolean g_variant_type_string_is_valid (const gchar *type_string);
306 GLIB_AVAILABLE_IN_ALL
307 gboolean g_variant_type_string_scan (const gchar *string,
309 const gchar **endptr);
312 GLIB_AVAILABLE_IN_ALL
313 void g_variant_type_free (GVariantType *type);
314 GLIB_AVAILABLE_IN_ALL
315 GVariantType * g_variant_type_copy (const GVariantType *type);
316 GLIB_AVAILABLE_IN_ALL
317 GVariantType * g_variant_type_new (const gchar *type_string);
320 GLIB_AVAILABLE_IN_ALL
321 gsize g_variant_type_get_string_length (const GVariantType *type);
322 GLIB_AVAILABLE_IN_ALL
323 const gchar * g_variant_type_peek_string (const GVariantType *type);
324 GLIB_AVAILABLE_IN_ALL
325 gchar * g_variant_type_dup_string (const GVariantType *type);
328 GLIB_AVAILABLE_IN_ALL
329 gboolean g_variant_type_is_definite (const GVariantType *type);
330 GLIB_AVAILABLE_IN_ALL
331 gboolean g_variant_type_is_container (const GVariantType *type);
332 GLIB_AVAILABLE_IN_ALL
333 gboolean g_variant_type_is_basic (const GVariantType *type);
334 GLIB_AVAILABLE_IN_ALL
335 gboolean g_variant_type_is_maybe (const GVariantType *type);
336 GLIB_AVAILABLE_IN_ALL
337 gboolean g_variant_type_is_array (const GVariantType *type);
338 GLIB_AVAILABLE_IN_ALL
339 gboolean g_variant_type_is_tuple (const GVariantType *type);
340 GLIB_AVAILABLE_IN_ALL
341 gboolean g_variant_type_is_dict_entry (const GVariantType *type);
342 GLIB_AVAILABLE_IN_ALL
343 gboolean g_variant_type_is_variant (const GVariantType *type);
345 /* for hash tables */
346 GLIB_AVAILABLE_IN_ALL
347 guint g_variant_type_hash (gconstpointer type);
348 GLIB_AVAILABLE_IN_ALL
349 gboolean g_variant_type_equal (gconstpointer type1,
350 gconstpointer type2);
353 GLIB_AVAILABLE_IN_ALL
354 gboolean g_variant_type_is_subtype_of (const GVariantType *type,
355 const GVariantType *supertype);
357 /* type iterator interface */
358 GLIB_AVAILABLE_IN_ALL
359 const GVariantType * g_variant_type_element (const GVariantType *type);
360 GLIB_AVAILABLE_IN_ALL
361 const GVariantType * g_variant_type_first (const GVariantType *type);
362 GLIB_AVAILABLE_IN_ALL
363 const GVariantType * g_variant_type_next (const GVariantType *type);
364 GLIB_AVAILABLE_IN_ALL
365 gsize g_variant_type_n_items (const GVariantType *type);
366 GLIB_AVAILABLE_IN_ALL
367 const GVariantType * g_variant_type_key (const GVariantType *type);
368 GLIB_AVAILABLE_IN_ALL
369 const GVariantType * g_variant_type_value (const GVariantType *type);
372 GLIB_AVAILABLE_IN_ALL
373 GVariantType * g_variant_type_new_array (const GVariantType *element);
374 GLIB_AVAILABLE_IN_ALL
375 GVariantType * g_variant_type_new_maybe (const GVariantType *element);
376 GLIB_AVAILABLE_IN_ALL
377 GVariantType * g_variant_type_new_tuple (const GVariantType * const *items,
379 GLIB_AVAILABLE_IN_ALL
380 GVariantType * g_variant_type_new_dict_entry (const GVariantType *key,
381 const GVariantType *value);
384 GLIB_AVAILABLE_IN_ALL
385 const GVariantType * g_variant_type_checked_ (const gchar *);
389 #endif /* __G_VARIANT_TYPE_H__ */