1/*
2 * Copyright © 2007, 2008 Ryan Lortie
3 * Copyright © 2009, 2010 Codethink Limited
4 *
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.1 of the License, or (at your option) any later version.
9 *
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.
14 *
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/>.
17 *
18 * Author: Ryan Lortie <desrt@desrt.ca>
19 */
20
21#ifndef __G_VARIANT_TYPE_H__
22#define __G_VARIANT_TYPE_H__
23
24#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
25#error "Only <glib.h> can be included directly."
26#endif
27
28#include <glib/gtypes.h>
29
30G_BEGIN_DECLS
31
32/**
33 * GVariantType:
34 *
35 * A type in the GVariant type system.
36 *
37 * Two types may not be compared by value; use g_variant_type_equal() or
38 * g_variant_type_is_subtype_of(). May be copied using
39 * g_variant_type_copy() and freed using g_variant_type_free().
40 **/
41typedef struct _GVariantType GVariantType;
42
43/**
44 * G_VARIANT_TYPE_BOOLEAN:
45 *
46 * The type of a value that can be either %TRUE or %FALSE.
47 **/
48#define G_VARIANT_TYPE_BOOLEAN ((const GVariantType *) "b")
49
50/**
51 * G_VARIANT_TYPE_BYTE:
52 *
53 * The type of an integer value that can range from 0 to 255.
54 **/
55#define G_VARIANT_TYPE_BYTE ((const GVariantType *) "y")
56
57/**
58 * G_VARIANT_TYPE_INT16:
59 *
60 * The type of an integer value that can range from -32768 to 32767.
61 **/
62#define G_VARIANT_TYPE_INT16 ((const GVariantType *) "n")
63
64/**
65 * G_VARIANT_TYPE_UINT16:
66 *
67 * The type of an integer value that can range from 0 to 65535.
68 * There were about this many people living in Toronto in the 1870s.
69 **/
70#define G_VARIANT_TYPE_UINT16 ((const GVariantType *) "q")
71
72/**
73 * G_VARIANT_TYPE_INT32:
74 *
75 * The type of an integer value that can range from -2147483648 to
76 * 2147483647.
77 **/
78#define G_VARIANT_TYPE_INT32 ((const GVariantType *) "i")
79
80/**
81 * G_VARIANT_TYPE_UINT32:
82 *
83 * The type of an integer value that can range from 0 to 4294967295.
84 * That's one number for everyone who was around in the late 1970s.
85 **/
86#define G_VARIANT_TYPE_UINT32 ((const GVariantType *) "u")
87
88/**
89 * G_VARIANT_TYPE_INT64:
90 *
91 * The type of an integer value that can range from
92 * -9223372036854775808 to 9223372036854775807.
93 **/
94#define G_VARIANT_TYPE_INT64 ((const GVariantType *) "x")
95
96/**
97 * G_VARIANT_TYPE_UINT64:
98 *
99 * The type of an integer value that can range from 0
100 * to 18446744073709551615 (inclusive). That's a really big number,
101 * but a Rubik's cube can have a bit more than twice as many possible
102 * positions.
103 **/
104#define G_VARIANT_TYPE_UINT64 ((const GVariantType *) "t")
105
106/**
107 * G_VARIANT_TYPE_DOUBLE:
108 *
109 * The type of a double precision IEEE754 floating point number.
110 * These guys go up to about 1.80e308 (plus and minus) but miss out on
111 * some numbers in between. In any case, that's far greater than the
112 * estimated number of fundamental particles in the observable
113 * universe.
114 **/
115#define G_VARIANT_TYPE_DOUBLE ((const GVariantType *) "d")
116
117/**
118 * G_VARIANT_TYPE_STRING:
119 *
120 * The type of a string. "" is a string. %NULL is not a string.
121 **/
122#define G_VARIANT_TYPE_STRING ((const GVariantType *) "s")
123
124/**
125 * G_VARIANT_TYPE_OBJECT_PATH:
126 *
127 * The type of a D-Bus object reference. These are strings of a
128 * specific format used to identify objects at a given destination on
129 * the bus.
130 *
131 * If you are not interacting with D-Bus, then there is no reason to make
132 * use of this type. If you are, then the D-Bus specification contains a
133 * precise description of valid object paths.
134 **/
135#define G_VARIANT_TYPE_OBJECT_PATH ((const GVariantType *) "o")
136
137/**
138 * G_VARIANT_TYPE_SIGNATURE:
139 *
140 * The type of a D-Bus type signature. These are strings of a specific
141 * format used as type signatures for D-Bus methods and messages.
142 *
143 * If you are not interacting with D-Bus, then there is no reason to make
144 * use of this type. If you are, then the D-Bus specification contains a
145 * precise description of valid signature strings.
146 **/
147#define G_VARIANT_TYPE_SIGNATURE ((const GVariantType *) "g")
148
149/**
150 * G_VARIANT_TYPE_VARIANT:
151 *
152 * The type of a box that contains any other value (including another
153 * variant).
154 **/
155#define G_VARIANT_TYPE_VARIANT ((const GVariantType *) "v")
156
157/**
158 * G_VARIANT_TYPE_HANDLE:
159 *
160 * The type of a 32bit signed integer value, that by convention, is used
161 * as an index into an array of file descriptors that are sent alongside
162 * a D-Bus message.
163 *
164 * If you are not interacting with D-Bus, then there is no reason to make
165 * use of this type.
166 **/
167#define G_VARIANT_TYPE_HANDLE ((const GVariantType *) "h")
168
169/**
170 * G_VARIANT_TYPE_UNIT:
171 *
172 * The empty tuple type. Has only one instance. Known also as "triv"
173 * or "void".
174 **/
175#define G_VARIANT_TYPE_UNIT ((const GVariantType *) "()")
176
177/**
178 * G_VARIANT_TYPE_ANY:
179 *
180 * An indefinite type that is a supertype of every type (including
181 * itself).
182 **/
183#define G_VARIANT_TYPE_ANY ((const GVariantType *) "*")
184
185/**
186 * G_VARIANT_TYPE_BASIC:
187 *
188 * An indefinite type that is a supertype of every basic (ie:
189 * non-container) type.
190 **/
191#define G_VARIANT_TYPE_BASIC ((const GVariantType *) "?")
192
193/**
194 * G_VARIANT_TYPE_MAYBE:
195 *
196 * An indefinite type that is a supertype of every maybe type.
197 **/
198#define G_VARIANT_TYPE_MAYBE ((const GVariantType *) "m*")
199
200/**
201 * G_VARIANT_TYPE_ARRAY:
202 *
203 * An indefinite type that is a supertype of every array type.
204 **/
205#define G_VARIANT_TYPE_ARRAY ((const GVariantType *) "a*")
206
207/**
208 * G_VARIANT_TYPE_TUPLE:
209 *
210 * An indefinite type that is a supertype of every tuple type,
211 * regardless of the number of items in the tuple.
212 **/
213#define G_VARIANT_TYPE_TUPLE ((const GVariantType *) "r")
214
215/**
216 * G_VARIANT_TYPE_DICT_ENTRY:
217 *
218 * An indefinite type that is a supertype of every dictionary entry
219 * type.
220 **/
221#define G_VARIANT_TYPE_DICT_ENTRY ((const GVariantType *) "{?*}")
222
223/**
224 * G_VARIANT_TYPE_DICTIONARY:
225 *
226 * An indefinite type that is a supertype of every dictionary type --
227 * that is, any array type that has an element type equal to any
228 * dictionary entry type.
229 **/
230#define G_VARIANT_TYPE_DICTIONARY ((const GVariantType *) "a{?*}")
231
232/**
233 * G_VARIANT_TYPE_STRING_ARRAY:
234 *
235 * The type of an array of strings.
236 **/
237#define G_VARIANT_TYPE_STRING_ARRAY ((const GVariantType *) "as")
238
239/**
240 * G_VARIANT_TYPE_OBJECT_PATH_ARRAY:
241 *
242 * The type of an array of object paths.
243 **/
244#define G_VARIANT_TYPE_OBJECT_PATH_ARRAY ((const GVariantType *) "ao")
245
246/**
247 * G_VARIANT_TYPE_BYTESTRING:
248 *
249 * The type of an array of bytes. This type is commonly used to pass
250 * around strings that may not be valid utf8. In that case, the
251 * convention is that the nul terminator character should be included as
252 * the last character in the array.
253 **/
254#define G_VARIANT_TYPE_BYTESTRING ((const GVariantType *) "ay")
255
256/**
257 * G_VARIANT_TYPE_BYTESTRING_ARRAY:
258 *
259 * The type of an array of byte strings (an array of arrays of bytes).
260 **/
261#define G_VARIANT_TYPE_BYTESTRING_ARRAY ((const GVariantType *) "aay")
262
263/**
264 * G_VARIANT_TYPE_VARDICT:
265 *
266 * The type of a dictionary mapping strings to variants (the ubiquitous
267 * "a{sv}" type).
268 *
269 * Since: 2.30
270 **/
271#define G_VARIANT_TYPE_VARDICT ((const GVariantType *) "a{sv}")
272
273
274/**
275 * G_VARIANT_TYPE:
276 * @type_string: a well-formed #GVariantType type string
277 *
278 * Converts a string to a const #GVariantType. Depending on the
279 * current debugging level, this function may perform a runtime check
280 * to ensure that @string is a valid GVariant type string.
281 *
282 * It is always a programmer error to use this macro with an invalid
283 * type string. If in doubt, use g_variant_type_string_is_valid() to
284 * check if the string is valid.
285 *
286 * Since 2.24
287 **/
288#ifndef G_DISABLE_CHECKS
289# define G_VARIANT_TYPE(type_string) (g_variant_type_checked_ ((type_string)))
290#else
291# define G_VARIANT_TYPE(type_string) ((const GVariantType *) (type_string))
292#endif
293
294/* type string checking */
295GLIB_AVAILABLE_IN_ALL
296gboolean g_variant_type_string_is_valid (const gchar *type_string);
297GLIB_AVAILABLE_IN_ALL
298gboolean g_variant_type_string_scan (const gchar *string,
299 const gchar *limit,
300 const gchar **endptr);
301
302/* create/destroy */
303GLIB_AVAILABLE_IN_ALL
304void g_variant_type_free (GVariantType *type);
305GLIB_AVAILABLE_IN_ALL
306GVariantType * g_variant_type_copy (const GVariantType *type);
307GLIB_AVAILABLE_IN_ALL
308GVariantType * g_variant_type_new (const gchar *type_string);
309
310/* getters */
311GLIB_AVAILABLE_IN_ALL
312gsize g_variant_type_get_string_length (const GVariantType *type);
313GLIB_AVAILABLE_IN_ALL
314const gchar * g_variant_type_peek_string (const GVariantType *type);
315GLIB_AVAILABLE_IN_ALL
316gchar * g_variant_type_dup_string (const GVariantType *type);
317
318/* classification */
319GLIB_AVAILABLE_IN_ALL
320gboolean g_variant_type_is_definite (const GVariantType *type);
321GLIB_AVAILABLE_IN_ALL
322gboolean g_variant_type_is_container (const GVariantType *type);
323GLIB_AVAILABLE_IN_ALL
324gboolean g_variant_type_is_basic (const GVariantType *type);
325GLIB_AVAILABLE_IN_ALL
326gboolean g_variant_type_is_maybe (const GVariantType *type);
327GLIB_AVAILABLE_IN_ALL
328gboolean g_variant_type_is_array (const GVariantType *type);
329GLIB_AVAILABLE_IN_ALL
330gboolean g_variant_type_is_tuple (const GVariantType *type);
331GLIB_AVAILABLE_IN_ALL
332gboolean g_variant_type_is_dict_entry (const GVariantType *type);
333GLIB_AVAILABLE_IN_ALL
334gboolean g_variant_type_is_variant (const GVariantType *type);
335
336/* for hash tables */
337GLIB_AVAILABLE_IN_ALL
338guint g_variant_type_hash (gconstpointer type);
339GLIB_AVAILABLE_IN_ALL
340gboolean g_variant_type_equal (gconstpointer type1,
341 gconstpointer type2);
342
343/* subtypes */
344GLIB_AVAILABLE_IN_ALL
345gboolean g_variant_type_is_subtype_of (const GVariantType *type,
346 const GVariantType *supertype);
347
348/* type iterator interface */
349GLIB_AVAILABLE_IN_ALL
350const GVariantType * g_variant_type_element (const GVariantType *type);
351GLIB_AVAILABLE_IN_ALL
352const GVariantType * g_variant_type_first (const GVariantType *type);
353GLIB_AVAILABLE_IN_ALL
354const GVariantType * g_variant_type_next (const GVariantType *type);
355GLIB_AVAILABLE_IN_ALL
356gsize g_variant_type_n_items (const GVariantType *type);
357GLIB_AVAILABLE_IN_ALL
358const GVariantType * g_variant_type_key (const GVariantType *type);
359GLIB_AVAILABLE_IN_ALL
360const GVariantType * g_variant_type_value (const GVariantType *type);
361
362/* constructors */
363GLIB_AVAILABLE_IN_ALL
364GVariantType * g_variant_type_new_array (const GVariantType *element);
365GLIB_AVAILABLE_IN_ALL
366GVariantType * g_variant_type_new_maybe (const GVariantType *element);
367GLIB_AVAILABLE_IN_ALL
368GVariantType * g_variant_type_new_tuple (const GVariantType * const *items,
369 gint length);
370GLIB_AVAILABLE_IN_ALL
371GVariantType * g_variant_type_new_dict_entry (const GVariantType *key,
372 const GVariantType *value);
373
374/*< private >*/
375GLIB_AVAILABLE_IN_ALL
376const GVariantType * g_variant_type_checked_ (const gchar *);
377GLIB_AVAILABLE_IN_2_56
378gsize g_variant_type_string_get_depth_ (const gchar *type_string);
379
380G_END_DECLS
381
382#endif /* __G_VARIANT_TYPE_H__ */
383