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