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_H__
24 #define __G_VARIANT_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/gvarianttype.h>
31 #include <glib/gstring.h>
32 #include <glib/gbytes.h>
33
34 G_BEGIN_DECLS
35
36 typedef struct _GVariant GVariant;
37
38 typedef enum
39 {
40 G_VARIANT_CLASS_BOOLEAN = 'b',
41 G_VARIANT_CLASS_BYTE = 'y',
42 G_VARIANT_CLASS_INT16 = 'n',
43 G_VARIANT_CLASS_UINT16 = 'q',
44 G_VARIANT_CLASS_INT32 = 'i',
45 G_VARIANT_CLASS_UINT32 = 'u',
46 G_VARIANT_CLASS_INT64 = 'x',
47 G_VARIANT_CLASS_UINT64 = 't',
48 G_VARIANT_CLASS_HANDLE = 'h',
49 G_VARIANT_CLASS_DOUBLE = 'd',
50 G_VARIANT_CLASS_STRING = 's',
51 G_VARIANT_CLASS_OBJECT_PATH = 'o',
52 G_VARIANT_CLASS_SIGNATURE = 'g',
53 G_VARIANT_CLASS_VARIANT = 'v',
54 G_VARIANT_CLASS_MAYBE = 'm',
55 G_VARIANT_CLASS_ARRAY = 'a',
56 G_VARIANT_CLASS_TUPLE = '(',
57 G_VARIANT_CLASS_DICT_ENTRY = '{'
58 } GVariantClass;
59
60 GLIB_AVAILABLE_IN_ALL
61 void g_variant_unref (GVariant *value);
62 GLIB_AVAILABLE_IN_ALL
63 GVariant * g_variant_ref (GVariant *value);
64 GLIB_AVAILABLE_IN_ALL
65 GVariant * g_variant_ref_sink (GVariant *value);
66 GLIB_AVAILABLE_IN_ALL
67 gboolean g_variant_is_floating (GVariant *value);
68 GLIB_AVAILABLE_IN_ALL
69 GVariant * g_variant_take_ref (GVariant *value);
70
71 GLIB_AVAILABLE_IN_ALL
72 const GVariantType * g_variant_get_type (GVariant *value);
73 GLIB_AVAILABLE_IN_ALL
74 const gchar * g_variant_get_type_string (GVariant *value);
75 GLIB_AVAILABLE_IN_ALL
76 gboolean g_variant_is_of_type (GVariant *value,
77 const GVariantType *type);
78 GLIB_AVAILABLE_IN_ALL
79 gboolean g_variant_is_container (GVariant *value);
80 GLIB_AVAILABLE_IN_ALL
81 GVariantClass g_variant_classify (GVariant *value);
82 GLIB_AVAILABLE_IN_ALL
83 GVariant * g_variant_new_boolean (gboolean value);
84 GLIB_AVAILABLE_IN_ALL
85 GVariant * g_variant_new_byte (guint8 value);
86 GLIB_AVAILABLE_IN_ALL
87 GVariant * g_variant_new_int16 (gint16 value);
88 GLIB_AVAILABLE_IN_ALL
89 GVariant * g_variant_new_uint16 (guint16 value);
90 GLIB_AVAILABLE_IN_ALL
91 GVariant * g_variant_new_int32 (gint32 value);
92 GLIB_AVAILABLE_IN_ALL
93 GVariant * g_variant_new_uint32 (guint32 value);
94 GLIB_AVAILABLE_IN_ALL
95 GVariant * g_variant_new_int64 (gint64 value);
96 GLIB_AVAILABLE_IN_ALL
97 GVariant * g_variant_new_uint64 (guint64 value);
98 GLIB_AVAILABLE_IN_ALL
99 GVariant * g_variant_new_handle (gint32 value);
100 GLIB_AVAILABLE_IN_ALL
101 GVariant * g_variant_new_double (gdouble value);
102 GLIB_AVAILABLE_IN_ALL
103 GVariant * g_variant_new_string (const gchar *string);
104 GLIB_AVAILABLE_IN_2_38
105 GVariant * g_variant_new_take_string (gchar *string);
106 GLIB_AVAILABLE_IN_2_38
107 GVariant * g_variant_new_printf (const gchar *format_string,
108 ...) G_GNUC_PRINTF (1, 2);
109 GLIB_AVAILABLE_IN_ALL
110 GVariant * g_variant_new_object_path (const gchar *object_path);
111 GLIB_AVAILABLE_IN_ALL
112 gboolean g_variant_is_object_path (const gchar *string);
113 GLIB_AVAILABLE_IN_ALL
114 GVariant * g_variant_new_signature (const gchar *signature);
115 GLIB_AVAILABLE_IN_ALL
116 gboolean g_variant_is_signature (const gchar *string);
117 GLIB_AVAILABLE_IN_ALL
118 GVariant * g_variant_new_variant (GVariant *value);
119 GLIB_AVAILABLE_IN_ALL
120 GVariant * g_variant_new_strv (const gchar * const *strv,
121 gssize length);
122 GLIB_AVAILABLE_IN_2_30
123 GVariant * g_variant_new_objv (const gchar * const *strv,
124 gssize length);
125 GLIB_AVAILABLE_IN_ALL
126 GVariant * g_variant_new_bytestring (const gchar *string);
127 GLIB_AVAILABLE_IN_ALL
128 GVariant * g_variant_new_bytestring_array (const gchar * const *strv,
129 gssize length);
130 GLIB_AVAILABLE_IN_ALL
131 GVariant * g_variant_new_fixed_array (const GVariantType *element_type,
132 gconstpointer elements,
133 gsize n_elements,
134 gsize element_size);
135 GLIB_AVAILABLE_IN_ALL
136 gboolean g_variant_get_boolean (GVariant *value);
137 GLIB_AVAILABLE_IN_ALL
138 guint8 g_variant_get_byte (GVariant *value);
139 GLIB_AVAILABLE_IN_ALL
140 gint16 g_variant_get_int16 (GVariant *value);
141 GLIB_AVAILABLE_IN_ALL
142 guint16 g_variant_get_uint16 (GVariant *value);
143 GLIB_AVAILABLE_IN_ALL
144 gint32 g_variant_get_int32 (GVariant *value);
145 GLIB_AVAILABLE_IN_ALL
146 guint32 g_variant_get_uint32 (GVariant *value);
147 GLIB_AVAILABLE_IN_ALL
148 gint64 g_variant_get_int64 (GVariant *value);
149 GLIB_AVAILABLE_IN_ALL
150 guint64 g_variant_get_uint64 (GVariant *value);
151 GLIB_AVAILABLE_IN_ALL
152 gint32 g_variant_get_handle (GVariant *value);
153 GLIB_AVAILABLE_IN_ALL
154 gdouble g_variant_get_double (GVariant *value);
155 GLIB_AVAILABLE_IN_ALL
156 GVariant * g_variant_get_variant (GVariant *value);
157 GLIB_AVAILABLE_IN_ALL
158 const gchar * g_variant_get_string (GVariant *value,
159 gsize *length);
160 GLIB_AVAILABLE_IN_ALL
161 gchar * g_variant_dup_string (GVariant *value,
162 gsize *length);
163 GLIB_AVAILABLE_IN_ALL
164 const gchar ** g_variant_get_strv (GVariant *value,
165 gsize *length);
166 GLIB_AVAILABLE_IN_ALL
167 gchar ** g_variant_dup_strv (GVariant *value,
168 gsize *length);
169 GLIB_AVAILABLE_IN_2_30
170 const gchar ** g_variant_get_objv (GVariant *value,
171 gsize *length);
172 GLIB_AVAILABLE_IN_ALL
173 gchar ** g_variant_dup_objv (GVariant *value,
174 gsize *length);
175 GLIB_AVAILABLE_IN_ALL
176 const gchar * g_variant_get_bytestring (GVariant *value);
177 GLIB_AVAILABLE_IN_ALL
178 gchar * g_variant_dup_bytestring (GVariant *value,
179 gsize *length);
180 GLIB_AVAILABLE_IN_ALL
181 const gchar ** g_variant_get_bytestring_array (GVariant *value,
182 gsize *length);
183 GLIB_AVAILABLE_IN_ALL
184 gchar ** g_variant_dup_bytestring_array (GVariant *value,
185 gsize *length);
186
187 GLIB_AVAILABLE_IN_ALL
188 GVariant * g_variant_new_maybe (const GVariantType *child_type,
189 GVariant *child);
190 GLIB_AVAILABLE_IN_ALL
191 GVariant * g_variant_new_array (const GVariantType *child_type,
192 GVariant * const *children,
193 gsize n_children);
194 GLIB_AVAILABLE_IN_ALL
195 GVariant * g_variant_new_tuple (GVariant * const *children,
196 gsize n_children);
197 GLIB_AVAILABLE_IN_ALL
198 GVariant * g_variant_new_dict_entry (GVariant *key,
199 GVariant *value);
200
201 GLIB_AVAILABLE_IN_ALL
202 GVariant * g_variant_get_maybe (GVariant *value);
203 GLIB_AVAILABLE_IN_ALL
204 gsize g_variant_n_children (GVariant *value);
205 GLIB_AVAILABLE_IN_ALL
206 void g_variant_get_child (GVariant *value,
207 gsize index_,
208 const gchar *format_string,
209 ...);
210 GLIB_AVAILABLE_IN_ALL
211 GVariant * g_variant_get_child_value (GVariant *value,
212 gsize index_);
213 GLIB_AVAILABLE_IN_ALL
214 gboolean g_variant_lookup (GVariant *dictionary,
215 const gchar *key,
216 const gchar *format_string,
217 ...);
218 GLIB_AVAILABLE_IN_ALL
219 GVariant * g_variant_lookup_value (GVariant *dictionary,
220 const gchar *key,
221 const GVariantType *expected_type);
222 GLIB_AVAILABLE_IN_ALL
223 gconstpointer g_variant_get_fixed_array (GVariant *value,
224 gsize *n_elements,
225 gsize element_size);
226
227 GLIB_AVAILABLE_IN_ALL
228 gsize g_variant_get_size (GVariant *value);
229 GLIB_AVAILABLE_IN_ALL
230 gconstpointer g_variant_get_data (GVariant *value);
231 GLIB_AVAILABLE_IN_2_36
232 GBytes * g_variant_get_data_as_bytes (GVariant *value);
233 GLIB_AVAILABLE_IN_ALL
234 void g_variant_store (GVariant *value,
235 gpointer data);
236
237 GLIB_AVAILABLE_IN_ALL
238 gchar * g_variant_print (GVariant *value,
239 gboolean type_annotate);
240 GLIB_AVAILABLE_IN_ALL
241 GString * g_variant_print_string (GVariant *value,
242 GString *string,
243 gboolean type_annotate);
244
245 GLIB_AVAILABLE_IN_ALL
246 guint g_variant_hash (gconstpointer value);
247 GLIB_AVAILABLE_IN_ALL
248 gboolean g_variant_equal (gconstpointer one,
249 gconstpointer two);
250
251 GLIB_AVAILABLE_IN_ALL
252 GVariant * g_variant_get_normal_form (GVariant *value);
253 GLIB_AVAILABLE_IN_ALL
254 gboolean g_variant_is_normal_form (GVariant *value);
255 GLIB_AVAILABLE_IN_ALL
256 GVariant * g_variant_byteswap (GVariant *value);
257
258 GLIB_AVAILABLE_IN_2_36
259 GVariant * g_variant_new_from_bytes (const GVariantType *type,
260 GBytes *bytes,
261 gboolean trusted);
262 GLIB_AVAILABLE_IN_ALL
263 GVariant * g_variant_new_from_data (const GVariantType *type,
264 gconstpointer data,
265 gsize size,
266 gboolean trusted,
267 GDestroyNotify notify,
268 gpointer user_data);
269
270 typedef struct _GVariantIter GVariantIter;
271 struct _GVariantIter {
272 /*< private >*/
273 guintptr x[16];
274 };
275
276 GLIB_AVAILABLE_IN_ALL
277 GVariantIter * g_variant_iter_new (GVariant *value);
278 GLIB_AVAILABLE_IN_ALL
279 gsize g_variant_iter_init (GVariantIter *iter,
280 GVariant *value);
281 GLIB_AVAILABLE_IN_ALL
282 GVariantIter * g_variant_iter_copy (GVariantIter *iter);
283 GLIB_AVAILABLE_IN_ALL
284 gsize g_variant_iter_n_children (GVariantIter *iter);
285 GLIB_AVAILABLE_IN_ALL
286 void g_variant_iter_free (GVariantIter *iter);
287 GLIB_AVAILABLE_IN_ALL
288 GVariant * g_variant_iter_next_value (GVariantIter *iter);
289 GLIB_AVAILABLE_IN_ALL
290 gboolean g_variant_iter_next (GVariantIter *iter,
291 const gchar *format_string,
292 ...);
293 GLIB_AVAILABLE_IN_ALL
294 gboolean g_variant_iter_loop (GVariantIter *iter,
295 const gchar *format_string,
296 ...);
297
298
299 typedef struct _GVariantBuilder GVariantBuilder;
300 struct _GVariantBuilder {
301 /*< private >*/
302 union
303 {
304 struct {
305 gsize partial_magic;
306 const GVariantType *type;
307 guintptr y[14];
308 } s;
309 guintptr x[16];
310 } u;
311 };
312
313 typedef enum
314 {
315 G_VARIANT_PARSE_ERROR_FAILED,
316 G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED,
317 G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE,
318 G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED,
319 G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END,
320 G_VARIANT_PARSE_ERROR_INVALID_CHARACTER,
321 G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING,
322 G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH,
323 G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE,
324 G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING,
325 G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE,
326 G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE,
327 G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG,
328 G_VARIANT_PARSE_ERROR_TYPE_ERROR,
329 G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN,
330 G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD,
331 G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT,
332 G_VARIANT_PARSE_ERROR_VALUE_EXPECTED,
333 G_VARIANT_PARSE_ERROR_RECURSION
334 } GVariantParseError;
335 #define G_VARIANT_PARSE_ERROR (g_variant_parse_error_quark ())
336
337 GLIB_DEPRECATED_IN_2_38_FOR(g_variant_parse_error_quark)
338 GQuark g_variant_parser_get_error_quark (void);
339
340 GLIB_AVAILABLE_IN_ALL
341 GQuark g_variant_parse_error_quark (void);
342
343 /**
344 * G_VARIANT_BUILDER_INIT:
345 * @variant_type: a const GVariantType*
346 *
347 * A stack-allocated #GVariantBuilder must be initialized if it is
348 * used together with g_auto() to avoid warnings or crashes if
349 * function returns before g_variant_builder_init() is called on the
350 * builder.
351 *
352 * This macro can be used as initializer instead of an
353 * explicit zeroing a variable when declaring it and a following
354 * g_variant_builder_init(), but it cannot be assigned to a variable.
355 *
356 * The passed @variant_type should be a static GVariantType to avoid
357 * lifetime issues, as copying the @variant_type does not happen in
358 * the G_VARIANT_BUILDER_INIT() call, but rather in functions that
359 * make sure that #GVariantBuilder is valid.
360 *
361 * |[<!-- language="C" -->
362 * g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING);
363 * ]|
364 *
365 * Since: 2.50
366 */
367 #define G_VARIANT_BUILDER_INIT(variant_type) \
368 { \
369 { \
370 { \
371 2942751021u /* == GVSB_MAGIC_PARTIAL, see gvariant.c */, variant_type, { 0, } \
372 } \
373 } \
374 }
375
376 GLIB_AVAILABLE_IN_ALL
377 GVariantBuilder * g_variant_builder_new (const GVariantType *type);
378 GLIB_AVAILABLE_IN_ALL
379 void g_variant_builder_unref (GVariantBuilder *builder);
380 GLIB_AVAILABLE_IN_ALL
381 GVariantBuilder * g_variant_builder_ref (GVariantBuilder *builder);
382 GLIB_AVAILABLE_IN_ALL
383 void g_variant_builder_init (GVariantBuilder *builder,
384 const GVariantType *type);
385 GLIB_AVAILABLE_IN_ALL
386 GVariant * g_variant_builder_end (GVariantBuilder *builder);
387 GLIB_AVAILABLE_IN_ALL
388 void g_variant_builder_clear (GVariantBuilder *builder);
389 GLIB_AVAILABLE_IN_ALL
390 void g_variant_builder_open (GVariantBuilder *builder,
391 const GVariantType *type);
392 GLIB_AVAILABLE_IN_ALL
393 void g_variant_builder_close (GVariantBuilder *builder);
394 GLIB_AVAILABLE_IN_ALL
395 void g_variant_builder_add_value (GVariantBuilder *builder,
396 GVariant *value);
397 GLIB_AVAILABLE_IN_ALL
398 void g_variant_builder_add (GVariantBuilder *builder,
399 const gchar *format_string,
400 ...);
401 GLIB_AVAILABLE_IN_ALL
402 void g_variant_builder_add_parsed (GVariantBuilder *builder,
403 const gchar *format,
404 ...);
405
406 GLIB_AVAILABLE_IN_ALL
407 GVariant * g_variant_new (const gchar *format_string,
408 ...);
409 GLIB_AVAILABLE_IN_ALL
410 void g_variant_get (GVariant *value,
411 const gchar *format_string,
412 ...);
413 GLIB_AVAILABLE_IN_ALL
414 GVariant * g_variant_new_va (const gchar *format_string,
415 const gchar **endptr,
416 va_list *app);
417 GLIB_AVAILABLE_IN_ALL
418 void g_variant_get_va (GVariant *value,
419 const gchar *format_string,
420 const gchar **endptr,
421 va_list *app);
422 GLIB_AVAILABLE_IN_2_34
423 gboolean g_variant_check_format_string (GVariant *value,
424 const gchar *format_string,
425 gboolean copy_only);
426
427 GLIB_AVAILABLE_IN_ALL
428 GVariant * g_variant_parse (const GVariantType *type,
429 const gchar *text,
430 const gchar *limit,
431 const gchar **endptr,
432 GError **error);
433 GLIB_AVAILABLE_IN_ALL
434 GVariant * g_variant_new_parsed (const gchar *format,
435 ...);
436 GLIB_AVAILABLE_IN_ALL
437 GVariant * g_variant_new_parsed_va (const gchar *format,
438 va_list *app);
439
440 GLIB_AVAILABLE_IN_2_40
441 gchar * g_variant_parse_error_print_context (GError *error,
442 const gchar *source_str);
443
444 GLIB_AVAILABLE_IN_ALL
445 gint g_variant_compare (gconstpointer one,
446 gconstpointer two);
447
448 typedef struct _GVariantDict GVariantDict;
449 struct _GVariantDict {
450 /*< private >*/
451 union
452 {
453 struct {
454 GVariant *asv;
455 gsize partial_magic;
456 guintptr y[14];
457 } s;
458 guintptr x[16];
459 } u;
460 };
461
462 /**
463 * G_VARIANT_DICT_INIT:
464 * @asv: (nullable): a GVariant*
465 *
466 * A stack-allocated #GVariantDict must be initialized if it is used
467 * together with g_auto() to avoid warnings or crashes if function
468 * returns before g_variant_dict_init() is called on the builder.
469 *
470 * This macro can be used as initializer instead of an explicit
471 * zeroing a variable when declaring it and a following
472 * g_variant_dict_init(), but it cannot be assigned to a variable.
473 *
474 * The passed @asv has to live long enough for #GVariantDict to gather
475 * the entries from, as the gathering does not happen in the
476 * G_VARIANT_DICT_INIT() call, but rather in functions that make sure
477 * that #GVariantDict is valid. In context where the initialization
478 * value has to be a constant expression, the only possible value of
479 * @asv is %NULL. It is still possible to call g_variant_dict_init()
480 * safely with a different @asv right after the variable was
481 * initialized with G_VARIANT_DICT_INIT().
482 *
483 * |[<!-- language="C" -->
484 * g_autoptr(GVariant) variant = get_asv_variant ();
485 * g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant);
486 * ]|
487 *
488 * Since: 2.50
489 */
490 #define G_VARIANT_DICT_INIT(asv) \
491 { \
492 { \
493 { \
494 asv, 3488698669u /* == GVSD_MAGIC_PARTIAL, see gvariant.c */, { 0, } \
495 } \
496 } \
497 }
498
499 GLIB_AVAILABLE_IN_2_40
500 GVariantDict * g_variant_dict_new (GVariant *from_asv);
501
502 GLIB_AVAILABLE_IN_2_40
503 void g_variant_dict_init (GVariantDict *dict,
504 GVariant *from_asv);
505
506 GLIB_AVAILABLE_IN_2_40
507 gboolean g_variant_dict_lookup (GVariantDict *dict,
508 const gchar *key,
509 const gchar *format_string,
510 ...);
511 GLIB_AVAILABLE_IN_2_40
512 GVariant * g_variant_dict_lookup_value (GVariantDict *dict,
513 const gchar *key,
514 const GVariantType *expected_type);
515 GLIB_AVAILABLE_IN_2_40
516 gboolean g_variant_dict_contains (GVariantDict *dict,
517 const gchar *key);
518 GLIB_AVAILABLE_IN_2_40
519 void g_variant_dict_insert (GVariantDict *dict,
520 const gchar *key,
521 const gchar *format_string,
522 ...);
523 GLIB_AVAILABLE_IN_2_40
524 void g_variant_dict_insert_value (GVariantDict *dict,
525 const gchar *key,
526 GVariant *value);
527 GLIB_AVAILABLE_IN_2_40
528 gboolean g_variant_dict_remove (GVariantDict *dict,
529 const gchar *key);
530 GLIB_AVAILABLE_IN_2_40
531 void g_variant_dict_clear (GVariantDict *dict);
532 GLIB_AVAILABLE_IN_2_40
533 GVariant * g_variant_dict_end (GVariantDict *dict);
534 GLIB_AVAILABLE_IN_2_40
535 GVariantDict * g_variant_dict_ref (GVariantDict *dict);
536 GLIB_AVAILABLE_IN_2_40
537 void g_variant_dict_unref (GVariantDict *dict);
538
539 G_END_DECLS
540
541 #endif /* __G_VARIANT_H__ */