glib/gvariant.h

   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   gsize 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       gsize y[14];
 308     } s;
 309     gsize 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       gsize y[14];
 457     } s;
 458     gsize 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__ */