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

source code of gtk/subprojects/glib/glib/gvariant.h