glib/gvariant.h

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