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