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__ */ |
376 | |