glib-2.0/glib/gvariant.h

0001 /*
0002  * Copyright © 2007, 2008 Ryan Lortie
0003  * Copyright © 2009, 2010 Codethink Limited
0004  *
0005  * SPDX-License-Identifier: LGPL-2.1-or-later
0006  *
0007  * This library is free software; you can redistribute it and/or
0008  * modify it under the terms of the GNU Lesser General Public
0009  * License as published by the Free Software Foundation; either
0010  * version 2.1 of the License, or (at your option) any later version.
0011  *
0012  * This library is distributed in the hope that it will be useful,
0013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015  * Lesser General Public License for more details.
0016  *
0017  * You should have received a copy of the GNU Lesser General Public
0018  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
0019  *
0020  * Author: Ryan Lortie <desrt@desrt.ca>
0021  */
0022
0023 #ifndef __G_VARIANT_H__
0024 #define __G_VARIANT_H__
0025
0026 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0027 #error "Only <glib.h> can be included directly."
0028 #endif
0029
0030 #include <glib/gvarianttype.h>
0031 #include <glib/gstring.h>
0032 #include <glib/gbytes.h>
0033
0034 G_BEGIN_DECLS
0035
0036 typedef struct _GVariant        GVariant;
0037
0038 typedef enum
0039 {
0040   G_VARIANT_CLASS_BOOLEAN       = 'b',
0041   G_VARIANT_CLASS_BYTE          = 'y',
0042   G_VARIANT_CLASS_INT16         = 'n',
0043   G_VARIANT_CLASS_UINT16        = 'q',
0044   G_VARIANT_CLASS_INT32         = 'i',
0045   G_VARIANT_CLASS_UINT32        = 'u',
0046   G_VARIANT_CLASS_INT64         = 'x',
0047   G_VARIANT_CLASS_UINT64        = 't',
0048   G_VARIANT_CLASS_HANDLE        = 'h',
0049   G_VARIANT_CLASS_DOUBLE        = 'd',
0050   G_VARIANT_CLASS_STRING        = 's',
0051   G_VARIANT_CLASS_OBJECT_PATH   = 'o',
0052   G_VARIANT_CLASS_SIGNATURE     = 'g',
0053   G_VARIANT_CLASS_VARIANT       = 'v',
0054   G_VARIANT_CLASS_MAYBE         = 'm',
0055   G_VARIANT_CLASS_ARRAY         = 'a',
0056   G_VARIANT_CLASS_TUPLE         = '(',
0057   G_VARIANT_CLASS_DICT_ENTRY    = '{'
0058 } GVariantClass;
0059
0060 GLIB_AVAILABLE_IN_ALL
0061 void                            g_variant_unref                         (GVariant             *value);
0062 GLIB_AVAILABLE_IN_ALL
0063 GVariant *                      g_variant_ref                           (GVariant             *value);
0064 GLIB_AVAILABLE_IN_ALL
0065 GVariant *                      g_variant_ref_sink                      (GVariant             *value);
0066 GLIB_AVAILABLE_IN_ALL
0067 gboolean                        g_variant_is_floating                   (GVariant             *value);
0068 GLIB_AVAILABLE_IN_ALL
0069 GVariant *                      g_variant_take_ref                      (GVariant             *value);
0070
0071 GLIB_AVAILABLE_IN_ALL
0072 const GVariantType *            g_variant_get_type                      (GVariant             *value);
0073 GLIB_AVAILABLE_IN_ALL
0074 const gchar *                   g_variant_get_type_string               (GVariant             *value);
0075 GLIB_AVAILABLE_IN_ALL
0076 gboolean                        g_variant_is_of_type                    (GVariant             *value,
0077                                                                          const GVariantType   *type);
0078 GLIB_AVAILABLE_IN_ALL
0079 gboolean                        g_variant_is_container                  (GVariant             *value);
0080 GLIB_AVAILABLE_IN_ALL
0081 GVariantClass                   g_variant_classify                      (GVariant             *value);
0082 GLIB_AVAILABLE_IN_ALL
0083 GVariant *                      g_variant_new_boolean                   (gboolean              value);
0084 GLIB_AVAILABLE_IN_ALL
0085 GVariant *                      g_variant_new_byte                      (guint8                value);
0086 GLIB_AVAILABLE_IN_ALL
0087 GVariant *                      g_variant_new_int16                     (gint16                value);
0088 GLIB_AVAILABLE_IN_ALL
0089 GVariant *                      g_variant_new_uint16                    (guint16               value);
0090 GLIB_AVAILABLE_IN_ALL
0091 GVariant *                      g_variant_new_int32                     (gint32                value);
0092 GLIB_AVAILABLE_IN_ALL
0093 GVariant *                      g_variant_new_uint32                    (guint32               value);
0094 GLIB_AVAILABLE_IN_ALL
0095 GVariant *                      g_variant_new_int64                     (gint64                value);
0096 GLIB_AVAILABLE_IN_ALL
0097 GVariant *                      g_variant_new_uint64                    (guint64               value);
0098 GLIB_AVAILABLE_IN_ALL
0099 GVariant *                      g_variant_new_handle                    (gint32                value);
0100 GLIB_AVAILABLE_IN_ALL
0101 GVariant *                      g_variant_new_double                    (gdouble               value);
0102 GLIB_AVAILABLE_IN_ALL
0103 GVariant *                      g_variant_new_string                    (const gchar          *string);
0104 GLIB_AVAILABLE_IN_2_38
0105 GVariant *                      g_variant_new_take_string               (gchar                *string);
0106 GLIB_AVAILABLE_IN_2_38
0107 GVariant *                      g_variant_new_printf                    (const gchar          *format_string,
0108                                                                          ...) G_GNUC_PRINTF (1, 2);
0109 GLIB_AVAILABLE_IN_ALL
0110 GVariant *                      g_variant_new_object_path               (const gchar          *object_path);
0111 GLIB_AVAILABLE_IN_ALL
0112 gboolean                        g_variant_is_object_path                (const gchar          *string);
0113 GLIB_AVAILABLE_IN_ALL
0114 GVariant *                      g_variant_new_signature                 (const gchar          *signature);
0115 GLIB_AVAILABLE_IN_ALL
0116 gboolean                        g_variant_is_signature                  (const gchar          *string);
0117 GLIB_AVAILABLE_IN_ALL
0118 GVariant *                      g_variant_new_variant                   (GVariant             *value);
0119 GLIB_AVAILABLE_IN_ALL
0120 GVariant *                      g_variant_new_strv                      (const gchar * const  *strv,
0121                                                                          gssize                length);
0122 GLIB_AVAILABLE_IN_2_30
0123 GVariant *                      g_variant_new_objv                      (const gchar * const  *strv,
0124                                                                          gssize                length);
0125 GLIB_AVAILABLE_IN_ALL
0126 GVariant *                      g_variant_new_bytestring                (const gchar          *string);
0127 GLIB_AVAILABLE_IN_ALL
0128 GVariant *                      g_variant_new_bytestring_array          (const gchar * const  *strv,
0129                                                                          gssize                length);
0130 GLIB_AVAILABLE_IN_ALL
0131 GVariant *                      g_variant_new_fixed_array               (const GVariantType   *element_type,
0132                                                                          gconstpointer         elements,
0133                                                                          gsize                 n_elements,
0134                                                                          gsize                 element_size);
0135 GLIB_AVAILABLE_IN_ALL
0136 gboolean                        g_variant_get_boolean                   (GVariant             *value);
0137 GLIB_AVAILABLE_IN_ALL
0138 guint8                          g_variant_get_byte                      (GVariant             *value);
0139 GLIB_AVAILABLE_IN_ALL
0140 gint16                          g_variant_get_int16                     (GVariant             *value);
0141 GLIB_AVAILABLE_IN_ALL
0142 guint16                         g_variant_get_uint16                    (GVariant             *value);
0143 GLIB_AVAILABLE_IN_ALL
0144 gint32                          g_variant_get_int32                     (GVariant             *value);
0145 GLIB_AVAILABLE_IN_ALL
0146 guint32                         g_variant_get_uint32                    (GVariant             *value);
0147 GLIB_AVAILABLE_IN_ALL
0148 gint64                          g_variant_get_int64                     (GVariant             *value);
0149 GLIB_AVAILABLE_IN_ALL
0150 guint64                         g_variant_get_uint64                    (GVariant             *value);
0151 GLIB_AVAILABLE_IN_ALL
0152 gint32                          g_variant_get_handle                    (GVariant             *value);
0153 GLIB_AVAILABLE_IN_ALL
0154 gdouble                         g_variant_get_double                    (GVariant             *value);
0155 GLIB_AVAILABLE_IN_ALL
0156 GVariant *                      g_variant_get_variant                   (GVariant             *value);
0157 GLIB_AVAILABLE_IN_ALL
0158 const gchar *                   g_variant_get_string                    (GVariant             *value,
0159                                                                          gsize                *length);
0160 GLIB_AVAILABLE_IN_ALL
0161 gchar *                         g_variant_dup_string                    (GVariant             *value,
0162                                                                          gsize                *length);
0163 GLIB_AVAILABLE_IN_ALL
0164 const gchar **                  g_variant_get_strv                      (GVariant             *value,
0165                                                                          gsize                *length);
0166 GLIB_AVAILABLE_IN_ALL
0167 gchar **                        g_variant_dup_strv                      (GVariant             *value,
0168                                                                          gsize                *length);
0169 GLIB_AVAILABLE_IN_2_30
0170 const gchar **                  g_variant_get_objv                      (GVariant             *value,
0171                                                                          gsize                *length);
0172 GLIB_AVAILABLE_IN_ALL
0173 gchar **                        g_variant_dup_objv                      (GVariant             *value,
0174                                                                          gsize                *length);
0175 GLIB_AVAILABLE_IN_ALL
0176 const gchar *                   g_variant_get_bytestring                (GVariant             *value);
0177 GLIB_AVAILABLE_IN_ALL
0178 gchar *                         g_variant_dup_bytestring                (GVariant             *value,
0179                                                                          gsize                *length);
0180 GLIB_AVAILABLE_IN_ALL
0181 const gchar **                  g_variant_get_bytestring_array          (GVariant             *value,
0182                                                                          gsize                *length);
0183 GLIB_AVAILABLE_IN_ALL
0184 gchar **                        g_variant_dup_bytestring_array          (GVariant             *value,
0185                                                                          gsize                *length);
0186
0187 GLIB_AVAILABLE_IN_ALL
0188 GVariant *                      g_variant_new_maybe                     (const GVariantType   *child_type,
0189                                                                          GVariant             *child);
0190 GLIB_AVAILABLE_IN_ALL
0191 GVariant *                      g_variant_new_array                     (const GVariantType   *child_type,
0192                                                                          GVariant * const     *children,
0193                                                                          gsize                 n_children);
0194 GLIB_AVAILABLE_IN_ALL
0195 GVariant *                      g_variant_new_tuple                     (GVariant * const     *children,
0196                                                                          gsize                 n_children);
0197 GLIB_AVAILABLE_IN_ALL
0198 GVariant *                      g_variant_new_dict_entry                (GVariant             *key,
0199                                                                          GVariant             *value);
0200
0201 GLIB_AVAILABLE_IN_ALL
0202 GVariant *                      g_variant_get_maybe                     (GVariant             *value);
0203 GLIB_AVAILABLE_IN_ALL
0204 gsize                           g_variant_n_children                    (GVariant             *value);
0205 GLIB_AVAILABLE_IN_ALL
0206 void                            g_variant_get_child                     (GVariant             *value,
0207                                                                          gsize                 index_,
0208                                                                          const gchar          *format_string,
0209                                                                          ...);
0210 GLIB_AVAILABLE_IN_ALL
0211 GVariant *                      g_variant_get_child_value               (GVariant             *value,
0212                                                                          gsize                 index_);
0213 GLIB_AVAILABLE_IN_ALL
0214 gboolean                        g_variant_lookup                        (GVariant             *dictionary,
0215                                                                          const gchar          *key,
0216                                                                          const gchar          *format_string,
0217                                                                          ...);
0218 GLIB_AVAILABLE_IN_ALL
0219 GVariant *                      g_variant_lookup_value                  (GVariant             *dictionary,
0220                                                                          const gchar          *key,
0221                                                                          const GVariantType   *expected_type);
0222 GLIB_AVAILABLE_IN_ALL
0223 gconstpointer                   g_variant_get_fixed_array               (GVariant             *value,
0224                                                                          gsize                *n_elements,
0225                                                                          gsize                 element_size);
0226
0227 GLIB_AVAILABLE_IN_ALL
0228 gsize                           g_variant_get_size                      (GVariant             *value);
0229 GLIB_AVAILABLE_IN_ALL
0230 gconstpointer                   g_variant_get_data                      (GVariant             *value);
0231 GLIB_AVAILABLE_IN_2_36
0232 GBytes *                        g_variant_get_data_as_bytes             (GVariant             *value);
0233 GLIB_AVAILABLE_IN_ALL
0234 void                            g_variant_store                         (GVariant             *value,
0235                                                                          gpointer              data);
0236
0237 GLIB_AVAILABLE_IN_ALL
0238 gchar *                         g_variant_print                         (GVariant             *value,
0239                                                                          gboolean              type_annotate);
0240 GLIB_AVAILABLE_IN_ALL
0241 GString *                       g_variant_print_string                  (GVariant             *value,
0242                                                                          GString              *string,
0243                                                                          gboolean              type_annotate);
0244
0245 GLIB_AVAILABLE_IN_ALL
0246 guint                           g_variant_hash                          (gconstpointer         value);
0247 GLIB_AVAILABLE_IN_ALL
0248 gboolean                        g_variant_equal                         (gconstpointer         one,
0249                                                                          gconstpointer         two);
0250
0251 GLIB_AVAILABLE_IN_ALL
0252 GVariant *                      g_variant_get_normal_form               (GVariant             *value);
0253 GLIB_AVAILABLE_IN_ALL
0254 gboolean                        g_variant_is_normal_form                (GVariant             *value);
0255 GLIB_AVAILABLE_IN_ALL
0256 GVariant *                      g_variant_byteswap                      (GVariant             *value);
0257
0258 GLIB_AVAILABLE_IN_2_36
0259 GVariant *                      g_variant_new_from_bytes                (const GVariantType   *type,
0260                                                                          GBytes               *bytes,
0261                                                                          gboolean              trusted);
0262 GLIB_AVAILABLE_IN_ALL
0263 GVariant *                      g_variant_new_from_data                 (const GVariantType   *type,
0264                                                                          gconstpointer         data,
0265                                                                          gsize                 size,
0266                                                                          gboolean              trusted,
0267                                                                          GDestroyNotify        notify,
0268                                                                          gpointer              user_data);
0269
0270 typedef struct _GVariantIter GVariantIter;
0271 struct _GVariantIter {
0272   /*< private >*/
0273   guintptr x[16];
0274 };
0275
0276 GLIB_AVAILABLE_IN_ALL
0277 GVariantIter *                  g_variant_iter_new                      (GVariant             *value);
0278 GLIB_AVAILABLE_IN_ALL
0279 gsize                           g_variant_iter_init                     (GVariantIter         *iter,
0280                                                                          GVariant             *value);
0281 GLIB_AVAILABLE_IN_ALL
0282 GVariantIter *                  g_variant_iter_copy                     (GVariantIter         *iter);
0283 GLIB_AVAILABLE_IN_ALL
0284 gsize                           g_variant_iter_n_children               (GVariantIter         *iter);
0285 GLIB_AVAILABLE_IN_ALL
0286 void                            g_variant_iter_free                     (GVariantIter         *iter);
0287 GLIB_AVAILABLE_IN_ALL
0288 GVariant *                      g_variant_iter_next_value               (GVariantIter         *iter);
0289 GLIB_AVAILABLE_IN_ALL
0290 gboolean                        g_variant_iter_next                     (GVariantIter         *iter,
0291                                                                          const gchar          *format_string,
0292                                                                          ...);
0293 GLIB_AVAILABLE_IN_ALL
0294 gboolean                        g_variant_iter_loop                     (GVariantIter         *iter,
0295                                                                          const gchar          *format_string,
0296                                                                          ...);
0297
0298
0299 typedef struct _GVariantBuilder GVariantBuilder;
0300 struct _GVariantBuilder {
0301   /*< private >*/
0302   union
0303   {
0304     struct {
0305       gsize partial_magic;
0306       const GVariantType *type;
0307       guintptr y[14];
0308     } s;
0309     guintptr x[16];
0310   } u;
0311 };
0312
0313 typedef enum
0314 {
0315   G_VARIANT_PARSE_ERROR_FAILED,
0316   G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED,
0317   G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE,
0318   G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED,
0319   G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END,
0320   G_VARIANT_PARSE_ERROR_INVALID_CHARACTER,
0321   G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING,
0322   G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH,
0323   G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE,
0324   G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING,
0325   G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE,
0326   G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE,
0327   G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG,
0328   G_VARIANT_PARSE_ERROR_TYPE_ERROR,
0329   G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN,
0330   G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD,
0331   G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT,
0332   G_VARIANT_PARSE_ERROR_VALUE_EXPECTED,
0333   G_VARIANT_PARSE_ERROR_RECURSION
0334 } GVariantParseError;
0335 #define G_VARIANT_PARSE_ERROR (g_variant_parse_error_quark ())
0336
0337 GLIB_DEPRECATED_IN_2_38_FOR(g_variant_parse_error_quark)
0338 GQuark                          g_variant_parser_get_error_quark        (void);
0339
0340 GLIB_AVAILABLE_IN_ALL
0341 GQuark                          g_variant_parse_error_quark             (void);
0342
0343 /**
0344  * G_VARIANT_BUILDER_INIT:
0345  * @variant_type: a const GVariantType*
0346  *
0347  * A stack-allocated #GVariantBuilder must be initialized if it is
0348  * used together with g_auto() to avoid warnings or crashes if
0349  * function returns before g_variant_builder_init() is called on the
0350  * builder.
0351  *
0352  * This macro can be used as initializer instead of an
0353  * explicit zeroing a variable when declaring it and a following
0354  * g_variant_builder_init(), but it cannot be assigned to a variable.
0355  *
0356  * The passed @variant_type should be a static GVariantType to avoid
0357  * lifetime issues, as copying the @variant_type does not happen in
0358  * the G_VARIANT_BUILDER_INIT() call, but rather in functions that
0359  * make sure that #GVariantBuilder is valid.
0360  *
0361  * |[<!-- language="C" -->
0362  *   g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING);
0363  * ]|
0364  *
0365  * Since: 2.50
0366  */
0367 #define G_VARIANT_BUILDER_INIT(variant_type)                                          \
0368   {                                                                                   \
0369     {                                                                                 \
0370       {                                                                               \
0371         2942751021u /* == GVSB_MAGIC_PARTIAL, see gvariant.c */, variant_type, { 0, } \
0372       }                                                                               \
0373     }                                                                                 \
0374   }
0375
0376 GLIB_AVAILABLE_IN_ALL
0377 GVariantBuilder *               g_variant_builder_new                   (const GVariantType   *type);
0378 GLIB_AVAILABLE_IN_ALL
0379 void                            g_variant_builder_unref                 (GVariantBuilder      *builder);
0380 GLIB_AVAILABLE_IN_ALL
0381 GVariantBuilder *               g_variant_builder_ref                   (GVariantBuilder      *builder);
0382 GLIB_AVAILABLE_IN_ALL
0383 void                            g_variant_builder_init                  (GVariantBuilder      *builder,
0384                                                                          const GVariantType   *type);
0385 GLIB_AVAILABLE_IN_ALL
0386 GVariant *                      g_variant_builder_end                   (GVariantBuilder      *builder);
0387 GLIB_AVAILABLE_IN_ALL
0388 void                            g_variant_builder_clear                 (GVariantBuilder      *builder);
0389 GLIB_AVAILABLE_IN_ALL
0390 void                            g_variant_builder_open                  (GVariantBuilder      *builder,
0391                                                                          const GVariantType   *type);
0392 GLIB_AVAILABLE_IN_ALL
0393 void                            g_variant_builder_close                 (GVariantBuilder      *builder);
0394 GLIB_AVAILABLE_IN_ALL
0395 void                            g_variant_builder_add_value             (GVariantBuilder      *builder,
0396                                                                          GVariant             *value);
0397 GLIB_AVAILABLE_IN_ALL
0398 void                            g_variant_builder_add                   (GVariantBuilder      *builder,
0399                                                                          const gchar          *format_string,
0400                                                                          ...);
0401 GLIB_AVAILABLE_IN_ALL
0402 void                            g_variant_builder_add_parsed            (GVariantBuilder      *builder,
0403                                                                          const gchar          *format,
0404                                                                          ...);
0405
0406 GLIB_AVAILABLE_IN_ALL
0407 GVariant *                      g_variant_new                           (const gchar          *format_string,
0408                                                                          ...);
0409 GLIB_AVAILABLE_IN_ALL
0410 void                            g_variant_get                           (GVariant             *value,
0411                                                                          const gchar          *format_string,
0412                                                                          ...);
0413 GLIB_AVAILABLE_IN_ALL
0414 GVariant *                      g_variant_new_va                        (const gchar          *format_string,
0415                                                                          const gchar         **endptr,
0416                                                                          va_list              *app);
0417 GLIB_AVAILABLE_IN_ALL
0418 void                            g_variant_get_va                        (GVariant             *value,
0419                                                                          const gchar          *format_string,
0420                                                                          const gchar         **endptr,
0421                                                                          va_list              *app);
0422 GLIB_AVAILABLE_IN_2_34
0423 gboolean                        g_variant_check_format_string           (GVariant             *value,
0424                                                                          const gchar          *format_string,
0425                                                                          gboolean              copy_only);
0426
0427 GLIB_AVAILABLE_IN_ALL
0428 GVariant *                      g_variant_parse                         (const GVariantType   *type,
0429                                                                          const gchar          *text,
0430                                                                          const gchar          *limit,
0431                                                                          const gchar         **endptr,
0432                                                                          GError              **error);
0433 GLIB_AVAILABLE_IN_ALL
0434 GVariant *                      g_variant_new_parsed                    (const gchar          *format,
0435                                                                          ...);
0436 GLIB_AVAILABLE_IN_ALL
0437 GVariant *                      g_variant_new_parsed_va                 (const gchar          *format,
0438                                                                          va_list              *app);
0439
0440 GLIB_AVAILABLE_IN_2_40
0441 gchar *                         g_variant_parse_error_print_context     (GError               *error,
0442                                                                          const gchar          *source_str);
0443
0444 GLIB_AVAILABLE_IN_ALL
0445 gint                            g_variant_compare                       (gconstpointer one,
0446                                                                          gconstpointer two);
0447
0448 typedef struct _GVariantDict GVariantDict;
0449 struct _GVariantDict {
0450   /*< private >*/
0451   union
0452   {
0453     struct {
0454       GVariant *asv;
0455       gsize partial_magic;
0456       guintptr y[14];
0457     } s;
0458     guintptr x[16];
0459   } u;
0460 };
0461
0462 /**
0463  * G_VARIANT_DICT_INIT:
0464  * @asv: (nullable): a GVariant*
0465  *
0466  * A stack-allocated #GVariantDict must be initialized if it is used
0467  * together with g_auto() to avoid warnings or crashes if function
0468  * returns before g_variant_dict_init() is called on the builder.
0469  *
0470  * This macro can be used as initializer instead of an explicit
0471  * zeroing a variable when declaring it and a following
0472  * g_variant_dict_init(), but it cannot be assigned to a variable.
0473  *
0474  * The passed @asv has to live long enough for #GVariantDict to gather
0475  * the entries from, as the gathering does not happen in the
0476  * G_VARIANT_DICT_INIT() call, but rather in functions that make sure
0477  * that #GVariantDict is valid.  In context where the initialization
0478  * value has to be a constant expression, the only possible value of
0479  * @asv is %NULL.  It is still possible to call g_variant_dict_init()
0480  * safely with a different @asv right after the variable was
0481  * initialized with G_VARIANT_DICT_INIT().
0482  *
0483  * |[<!-- language="C" -->
0484  *   g_autoptr(GVariant) variant = get_asv_variant ();
0485  *   g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant);
0486  * ]|
0487  *
0488  * Since: 2.50
0489  */
0490 #define G_VARIANT_DICT_INIT(asv)                                             \
0491   {                                                                          \
0492     {                                                                        \
0493       {                                                                      \
0494         asv, 3488698669u /* == GVSD_MAGIC_PARTIAL, see gvariant.c */, { 0, } \
0495       }                                                                      \
0496     }                                                                        \
0497   }
0498
0499 GLIB_AVAILABLE_IN_2_40
0500 GVariantDict *                  g_variant_dict_new                      (GVariant             *from_asv);
0501
0502 GLIB_AVAILABLE_IN_2_40
0503 void                            g_variant_dict_init                     (GVariantDict         *dict,
0504                                                                          GVariant             *from_asv);
0505
0506 GLIB_AVAILABLE_IN_2_40
0507 gboolean                        g_variant_dict_lookup                   (GVariantDict         *dict,
0508                                                                          const gchar          *key,
0509                                                                          const gchar          *format_string,
0510                                                                          ...);
0511 GLIB_AVAILABLE_IN_2_40
0512 GVariant *                      g_variant_dict_lookup_value             (GVariantDict         *dict,
0513                                                                          const gchar          *key,
0514                                                                          const GVariantType   *expected_type);
0515 GLIB_AVAILABLE_IN_2_40
0516 gboolean                        g_variant_dict_contains                 (GVariantDict         *dict,
0517                                                                          const gchar          *key);
0518 GLIB_AVAILABLE_IN_2_40
0519 void                            g_variant_dict_insert                   (GVariantDict         *dict,
0520                                                                          const gchar          *key,
0521                                                                          const gchar          *format_string,
0522                                                                          ...);
0523 GLIB_AVAILABLE_IN_2_40
0524 void                            g_variant_dict_insert_value             (GVariantDict         *dict,
0525                                                                          const gchar          *key,
0526                                                                          GVariant             *value);
0527 GLIB_AVAILABLE_IN_2_40
0528 gboolean                        g_variant_dict_remove                   (GVariantDict         *dict,
0529                                                                          const gchar          *key);
0530 GLIB_AVAILABLE_IN_2_40
0531 void                            g_variant_dict_clear                    (GVariantDict         *dict);
0532 GLIB_AVAILABLE_IN_2_40
0533 GVariant *                      g_variant_dict_end                      (GVariantDict         *dict);
0534 GLIB_AVAILABLE_IN_2_40
0535 GVariantDict *                  g_variant_dict_ref                      (GVariantDict         *dict);
0536 GLIB_AVAILABLE_IN_2_40
0537 void                            g_variant_dict_unref                    (GVariantDict         *dict);
0538
0539 G_END_DECLS
0540
0541 #endif /* __G_VARIANT_H__ */