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 of the licence, 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_DOUBLE        = 'd',
  48   G_VARIANT_CLASS_STRING        = 's',
  49   G_VARIANT_CLASS_OBJECT_PATH   = 'o',
  50   G_VARIANT_CLASS_SIGNATURE     = 'g',
  51   G_VARIANT_CLASS_VARIANT       = 'v',
  52   G_VARIANT_CLASS_MAYBE         = 'm',
  53   G_VARIANT_CLASS_ARRAY         = 'a',
  54   G_VARIANT_CLASS_TUPLE         = '(',
  55   G_VARIANT_CLASS_DICT_ENTRY    = '{'
  56 } GVariantClass;
  57
  58 GLIB_AVAILABLE_IN_ALL
  59 void                            g_variant_unref                         (GVariant             *value);
  60 GLIB_AVAILABLE_IN_ALL
  61 GVariant *                      g_variant_ref                           (GVariant             *value);
  62 GLIB_AVAILABLE_IN_ALL
  63 GVariant *                      g_variant_ref_sink                      (GVariant             *value);
  64 GLIB_AVAILABLE_IN_ALL
  65 gboolean                        g_variant_is_floating                   (GVariant             *value);
  66 GLIB_AVAILABLE_IN_ALL
  67 GVariant *                      g_variant_take_ref                      (GVariant             *value);
  68
  69 GLIB_AVAILABLE_IN_ALL
  70 const GVariantType *            g_variant_get_type                      (GVariant             *value);
  71 GLIB_AVAILABLE_IN_ALL
  72 const gchar *                   g_variant_get_type_string               (GVariant             *value);
  73 GLIB_AVAILABLE_IN_ALL
  74 gboolean                        g_variant_is_of_type                    (GVariant             *value,
  75                                                                          const GVariantType   *type);
  76 GLIB_AVAILABLE_IN_ALL
  77 gboolean                        g_variant_is_container                  (GVariant             *value);
  78 GLIB_AVAILABLE_IN_ALL
  79 GVariantClass                   g_variant_classify                      (GVariant             *value);
  80 GLIB_AVAILABLE_IN_ALL
  81 GVariant *                      g_variant_new_boolean                   (gboolean              value);
  82 GLIB_AVAILABLE_IN_ALL
  83 GVariant *                      g_variant_new_byte                      (guchar                value);
  84 GLIB_AVAILABLE_IN_ALL
  85 GVariant *                      g_variant_new_int16                     (gint16                value);
  86 GLIB_AVAILABLE_IN_ALL
  87 GVariant *                      g_variant_new_uint16                    (guint16               value);
  88 GLIB_AVAILABLE_IN_ALL
  89 GVariant *                      g_variant_new_int32                     (gint32                value);
  90 GLIB_AVAILABLE_IN_ALL
  91 GVariant *                      g_variant_new_uint32                    (guint32               value);
  92 GLIB_AVAILABLE_IN_ALL
  93 GVariant *                      g_variant_new_int64                     (gint64                value);
  94 GLIB_AVAILABLE_IN_ALL
  95 GVariant *                      g_variant_new_uint64                    (guint64               value);
  96 GLIB_AVAILABLE_IN_ALL
  97 GVariant *                      g_variant_new_handle                    (gint32                value);
  98 GLIB_AVAILABLE_IN_ALL
  99 GVariant *                      g_variant_new_double                    (gdouble               value);
 100 GLIB_AVAILABLE_IN_ALL
 101 GVariant *                      g_variant_new_string                    (const gchar          *string);
 102 GLIB_AVAILABLE_IN_2_38
 103 GVariant *                      g_variant_new_take_string               (gchar                *string);
 104 GLIB_AVAILABLE_IN_2_38
 105 GVariant *                      g_variant_new_printf                    (const gchar          *format_string,
 106                                                                          ...) G_GNUC_PRINTF (1, 2);
 107 GLIB_AVAILABLE_IN_ALL
 108 GVariant *                      g_variant_new_object_path               (const gchar          *object_path);
 109 GLIB_AVAILABLE_IN_ALL
 110 gboolean                        g_variant_is_object_path                (const gchar          *string);
 111 GLIB_AVAILABLE_IN_ALL
 112 GVariant *                      g_variant_new_signature                 (const gchar          *signature);
 113 GLIB_AVAILABLE_IN_ALL
 114 gboolean                        g_variant_is_signature                  (const gchar          *string);
 115 GLIB_AVAILABLE_IN_ALL
 116 GVariant *                      g_variant_new_variant                   (GVariant             *value);
 117 GLIB_AVAILABLE_IN_ALL
 118 GVariant *                      g_variant_new_strv                      (const gchar * const  *strv,
 119                                                                          gssize                length);
 120 GLIB_AVAILABLE_IN_2_30
 121 GVariant *                      g_variant_new_objv                      (const gchar * const  *strv,
 122                                                                          gssize                length);
 123 GLIB_AVAILABLE_IN_ALL
 124 GVariant *                      g_variant_new_bytestring                (const gchar          *string);
 125 GLIB_AVAILABLE_IN_ALL
 126 GVariant *                      g_variant_new_bytestring_array          (const gchar * const  *strv,
 127                                                                          gssize                length);
 128 GLIB_AVAILABLE_IN_ALL
 129 GVariant *                      g_variant_new_fixed_array               (const GVariantType   *element_type,
 130                                                                          gconstpointer         elements,
 131                                                                          gsize                 n_elements,
 132                                                                          gsize                 element_size);
 133 GLIB_AVAILABLE_IN_ALL
 134 gboolean                        g_variant_get_boolean                   (GVariant             *value);
 135 GLIB_AVAILABLE_IN_ALL
 136 guchar                          g_variant_get_byte                      (GVariant             *value);
 137 GLIB_AVAILABLE_IN_ALL
 138 gint16                          g_variant_get_int16                     (GVariant             *value);
 139 GLIB_AVAILABLE_IN_ALL
 140 guint16                         g_variant_get_uint16                    (GVariant             *value);
 141 GLIB_AVAILABLE_IN_ALL
 142 gint32                          g_variant_get_int32                     (GVariant             *value);
 143 GLIB_AVAILABLE_IN_ALL
 144 guint32                         g_variant_get_uint32                    (GVariant             *value);
 145 GLIB_AVAILABLE_IN_ALL
 146 gint64                          g_variant_get_int64                     (GVariant             *value);
 147 GLIB_AVAILABLE_IN_ALL
 148 guint64                         g_variant_get_uint64                    (GVariant             *value);
 149 GLIB_AVAILABLE_IN_ALL
 150 gint32                          g_variant_get_handle                    (GVariant             *value);
 151 GLIB_AVAILABLE_IN_ALL
 152 gdouble                         g_variant_get_double                    (GVariant             *value);
 153 GLIB_AVAILABLE_IN_ALL
 154 GVariant *                      g_variant_get_variant                   (GVariant             *value);
 155 GLIB_AVAILABLE_IN_ALL
 156 const gchar *                   g_variant_get_string                    (GVariant             *value,
 157                                                                          gsize                *length);
 158 GLIB_AVAILABLE_IN_ALL
 159 gchar *                         g_variant_dup_string                    (GVariant             *value,
 160                                                                          gsize                *length);
 161 GLIB_AVAILABLE_IN_ALL
 162 const gchar **                  g_variant_get_strv                      (GVariant             *value,
 163                                                                          gsize                *length);
 164 GLIB_AVAILABLE_IN_ALL
 165 gchar **                        g_variant_dup_strv                      (GVariant             *value,
 166                                                                          gsize                *length);
 167 GLIB_AVAILABLE_IN_2_30
 168 const gchar **                  g_variant_get_objv                      (GVariant             *value,
 169                                                                          gsize                *length);
 170 GLIB_AVAILABLE_IN_ALL
 171 gchar **                        g_variant_dup_objv                      (GVariant             *value,
 172                                                                          gsize                *length);
 173 GLIB_AVAILABLE_IN_ALL
 174 const gchar *                   g_variant_get_bytestring                (GVariant             *value);
 175 GLIB_AVAILABLE_IN_ALL
 176 gchar *                         g_variant_dup_bytestring                (GVariant             *value,
 177                                                                          gsize                *length);
 178 GLIB_AVAILABLE_IN_ALL
 179 const gchar **                  g_variant_get_bytestring_array          (GVariant             *value,
 180                                                                          gsize                *length);
 181 GLIB_AVAILABLE_IN_ALL
 182 gchar **                        g_variant_dup_bytestring_array          (GVariant             *value,
 183                                                                          gsize                *length);
 184
 185 GLIB_AVAILABLE_IN_ALL
 186 GVariant *                      g_variant_new_maybe                     (const GVariantType   *child_type,
 187                                                                          GVariant             *child);
 188 GLIB_AVAILABLE_IN_ALL
 189 GVariant *                      g_variant_new_array                     (const GVariantType   *child_type,
 190                                                                          GVariant * const     *children,
 191                                                                          gsize                 n_children);
 192 GLIB_AVAILABLE_IN_ALL
 193 GVariant *                      g_variant_new_tuple                     (GVariant * const     *children,
 194                                                                          gsize                 n_children);
 195 GLIB_AVAILABLE_IN_ALL
 196 GVariant *                      g_variant_new_dict_entry                (GVariant             *key,
 197                                                                          GVariant             *value);
 198
 199 GLIB_AVAILABLE_IN_ALL
 200 GVariant *                      g_variant_get_maybe                     (GVariant             *value);
 201 GLIB_AVAILABLE_IN_ALL
 202 gsize                           g_variant_n_children                    (GVariant             *value);
 203 GLIB_AVAILABLE_IN_ALL
 204 void                            g_variant_get_child                     (GVariant             *value,
 205                                                                          gsize                 index_,
 206                                                                          const gchar          *format_string,
 207                                                                          ...);
 208 GLIB_AVAILABLE_IN_ALL
 209 GVariant *                      g_variant_get_child_value               (GVariant             *value,
 210                                                                          gsize                 index_);
 211 GLIB_AVAILABLE_IN_ALL
 212 gboolean                        g_variant_lookup                        (GVariant             *dictionary,
 213                                                                          const gchar          *key,
 214                                                                          const gchar          *format_string,
 215                                                                          ...);
 216 GLIB_AVAILABLE_IN_ALL
 217 GVariant *                      g_variant_lookup_value                  (GVariant             *dictionary,
 218                                                                          const gchar          *key,
 219                                                                          const GVariantType   *expected_type);
 220 GLIB_AVAILABLE_IN_ALL
 221 gconstpointer                   g_variant_get_fixed_array               (GVariant             *value,
 222                                                                          gsize                *n_elements,
 223                                                                          gsize                 element_size);
 224
 225 GLIB_AVAILABLE_IN_ALL
 226 gsize                           g_variant_get_size                      (GVariant             *value);
 227 GLIB_AVAILABLE_IN_ALL
 228 gconstpointer                   g_variant_get_data                      (GVariant             *value);
 229 GLIB_AVAILABLE_IN_2_36
 230 GBytes *                        g_variant_get_data_as_bytes             (GVariant             *value);
 231 GLIB_AVAILABLE_IN_ALL
 232 void                            g_variant_store                         (GVariant             *value,
 233                                                                          gpointer              data);
 234
 235 GLIB_AVAILABLE_IN_ALL
 236 gchar *                         g_variant_print                         (GVariant             *value,
 237                                                                          gboolean              type_annotate);
 238 GLIB_AVAILABLE_IN_ALL
 239 GString *                       g_variant_print_string                  (GVariant             *value,
 240                                                                          GString              *string,
 241                                                                          gboolean              type_annotate);
 242
 243 GLIB_AVAILABLE_IN_ALL
 244 guint                           g_variant_hash                          (gconstpointer         value);
 245 GLIB_AVAILABLE_IN_ALL
 246 gboolean                        g_variant_equal                         (gconstpointer         one,
 247                                                                          gconstpointer         two);
 248
 249 GLIB_AVAILABLE_IN_ALL
 250 GVariant *                      g_variant_get_normal_form               (GVariant             *value);
 251 GLIB_AVAILABLE_IN_ALL
 252 gboolean                        g_variant_is_normal_form                (GVariant             *value);
 253 GLIB_AVAILABLE_IN_ALL
 254 GVariant *                      g_variant_byteswap                      (GVariant             *value);
 255
 256 GLIB_AVAILABLE_IN_2_36
 257 GVariant *                      g_variant_new_from_bytes                (const GVariantType   *type,
 258                                                                          GBytes               *bytes,
 259                                                                          gboolean              trusted);
 260 GLIB_AVAILABLE_IN_ALL
 261 GVariant *                      g_variant_new_from_data                 (const GVariantType   *type,
 262                                                                          gconstpointer         data,
 263                                                                          gsize                 size,
 264                                                                          gboolean              trusted,
 265                                                                          GDestroyNotify        notify,
 266                                                                          gpointer              user_data);
 267
 268 typedef struct _GVariantIter GVariantIter;
 269 struct _GVariantIter {
 270   /*< private >*/
 271   gsize x[16];
 272 };
 273
 274 GLIB_AVAILABLE_IN_ALL
 275 GVariantIter *                  g_variant_iter_new                      (GVariant             *value);
 276 GLIB_AVAILABLE_IN_ALL
 277 gsize                           g_variant_iter_init                     (GVariantIter         *iter,
 278                                                                          GVariant             *value);
 279 GLIB_AVAILABLE_IN_ALL
 280 GVariantIter *                  g_variant_iter_copy                     (GVariantIter         *iter);
 281 GLIB_AVAILABLE_IN_ALL
 282 gsize                           g_variant_iter_n_children               (GVariantIter         *iter);
 283 GLIB_AVAILABLE_IN_ALL
 284 void                            g_variant_iter_free                     (GVariantIter         *iter);
 285 GLIB_AVAILABLE_IN_ALL
 286 GVariant *                      g_variant_iter_next_value               (GVariantIter         *iter);
 287 GLIB_AVAILABLE_IN_ALL
 288 gboolean                        g_variant_iter_next                     (GVariantIter         *iter,
 289                                                                          const gchar          *format_string,
 290                                                                          ...);
 291 GLIB_AVAILABLE_IN_ALL
 292 gboolean                        g_variant_iter_loop                     (GVariantIter         *iter,
 293                                                                          const gchar          *format_string,
 294                                                                          ...);
 295
 296
 297 typedef struct _GVariantBuilder GVariantBuilder;
 298 struct _GVariantBuilder {
 299   /*< private >*/
 300   gsize x[16];
 301 };
 302
 303 typedef enum
 304 {
 305   G_VARIANT_PARSE_ERROR_FAILED,
 306   G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED,
 307   G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE,
 308   G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED,
 309   G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END,
 310   G_VARIANT_PARSE_ERROR_INVALID_CHARACTER,
 311   G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING,
 312   G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH,
 313   G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE,
 314   G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING,
 315   G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE,
 316   G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE,
 317   G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG,
 318   G_VARIANT_PARSE_ERROR_TYPE_ERROR,
 319   G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN,
 320   G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD,
 321   G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT,
 322   G_VARIANT_PARSE_ERROR_VALUE_EXPECTED
 323 } GVariantParseError;
 324 #define G_VARIANT_PARSE_ERROR (g_variant_parse_error_quark ())
 325
 326 GLIB_DEPRECATED_IN_2_38_FOR(g_variant_parse_error_quark)
 327 GQuark                          g_variant_parser_get_error_quark        (void);
 328
 329 GLIB_AVAILABLE_IN_ALL
 330 GQuark                          g_variant_parse_error_quark             (void);
 331
 332 GLIB_AVAILABLE_IN_ALL
 333 GVariantBuilder *               g_variant_builder_new                   (const GVariantType   *type);
 334 GLIB_AVAILABLE_IN_ALL
 335 void                            g_variant_builder_unref                 (GVariantBuilder      *builder);
 336 GLIB_AVAILABLE_IN_ALL
 337 GVariantBuilder *               g_variant_builder_ref                   (GVariantBuilder      *builder);
 338 GLIB_AVAILABLE_IN_ALL
 339 void                            g_variant_builder_init                  (GVariantBuilder      *builder,
 340                                                                          const GVariantType   *type);
 341 GLIB_AVAILABLE_IN_ALL
 342 GVariant *                      g_variant_builder_end                   (GVariantBuilder      *builder);
 343 GLIB_AVAILABLE_IN_ALL
 344 void                            g_variant_builder_clear                 (GVariantBuilder      *builder);
 345 GLIB_AVAILABLE_IN_ALL
 346 void                            g_variant_builder_open                  (GVariantBuilder      *builder,
 347                                                                          const GVariantType   *type);
 348 GLIB_AVAILABLE_IN_ALL
 349 void                            g_variant_builder_close                 (GVariantBuilder      *builder);
 350 GLIB_AVAILABLE_IN_ALL
 351 void                            g_variant_builder_add_value             (GVariantBuilder      *builder,
 352                                                                          GVariant             *value);
 353 GLIB_AVAILABLE_IN_ALL
 354 void                            g_variant_builder_add                   (GVariantBuilder      *builder,
 355                                                                          const gchar          *format_string,
 356                                                                          ...);
 357 GLIB_AVAILABLE_IN_ALL
 358 void                            g_variant_builder_add_parsed            (GVariantBuilder      *builder,
 359                                                                          const gchar          *format,
 360                                                                          ...);
 361
 362 GLIB_AVAILABLE_IN_ALL
 363 GVariant *                      g_variant_new                           (const gchar          *format_string,
 364                                                                          ...);
 365 GLIB_AVAILABLE_IN_ALL
 366 void                            g_variant_get                           (GVariant             *value,
 367                                                                          const gchar          *format_string,
 368                                                                          ...);
 369 GLIB_AVAILABLE_IN_ALL
 370 GVariant *                      g_variant_new_va                        (const gchar          *format_string,
 371                                                                          const gchar         **endptr,
 372                                                                          va_list              *app);
 373 GLIB_AVAILABLE_IN_ALL
 374 void                            g_variant_get_va                        (GVariant             *value,
 375                                                                          const gchar          *format_string,
 376                                                                          const gchar         **endptr,
 377                                                                          va_list              *app);
 378 GLIB_AVAILABLE_IN_2_34
 379 gboolean                        g_variant_check_format_string           (GVariant             *value,
 380                                                                          const gchar          *format_string,
 381                                                                          gboolean              copy_only);
 382
 383 GLIB_AVAILABLE_IN_ALL
 384 GVariant *                      g_variant_parse                         (const GVariantType   *type,
 385                                                                          const gchar          *text,
 386                                                                          const gchar          *limit,
 387                                                                          const gchar         **endptr,
 388                                                                          GError              **error);
 389 GLIB_AVAILABLE_IN_ALL
 390 GVariant *                      g_variant_new_parsed                    (const gchar          *format,
 391                                                                          ...);
 392 GLIB_AVAILABLE_IN_ALL
 393 GVariant *                      g_variant_new_parsed_va                 (const gchar          *format,
 394                                                                          va_list              *app);
 395
 396 GLIB_AVAILABLE_IN_2_40
 397 gchar *                         g_variant_parse_error_print_context     (GError               *error,
 398                                                                          const gchar          *source_str);
 399
 400 GLIB_AVAILABLE_IN_ALL
 401 gint                            g_variant_compare                       (gconstpointer one,
 402                                                                          gconstpointer two);
 403
 404 typedef struct _GVariantDict GVariantDict;
 405 struct _GVariantDict {
 406   /*< private >*/
 407   gsize x[16];
 408 };
 409
 410 GLIB_AVAILABLE_IN_2_40
 411 GVariantDict *                  g_variant_dict_new                      (GVariant             *from_asv);
 412
 413 GLIB_AVAILABLE_IN_2_40
 414 void                            g_variant_dict_init                     (GVariantDict         *dict,
 415                                                                          GVariant             *from_asv);
 416
 417 GLIB_AVAILABLE_IN_2_40
 418 gboolean                        g_variant_dict_lookup                   (GVariantDict         *dict,
 419                                                                          const gchar          *key,
 420                                                                          const gchar          *format_string,
 421                                                                          ...);
 422 GLIB_AVAILABLE_IN_2_40
 423 GVariant *                      g_variant_dict_lookup_value             (GVariantDict         *dict,
 424                                                                          const gchar          *key,
 425                                                                          const GVariantType   *expected_type);
 426 GLIB_AVAILABLE_IN_2_40
 427 gboolean                        g_variant_dict_contains                 (GVariantDict         *dict,
 428                                                                          const gchar          *key);
 429 GLIB_AVAILABLE_IN_2_40
 430 void                            g_variant_dict_insert                   (GVariantDict         *dict,
 431                                                                          const gchar          *key,
 432                                                                          const gchar          *format_string,
 433                                                                          ...);
 434 GLIB_AVAILABLE_IN_2_40
 435 void                            g_variant_dict_insert_value             (GVariantDict         *dict,
 436                                                                          const gchar          *key,
 437                                                                          GVariant             *value);
 438 GLIB_AVAILABLE_IN_2_40
 439 gboolean                        g_variant_dict_remove                   (GVariantDict         *dict,
 440                                                                          const gchar          *key);
 441 GLIB_AVAILABLE_IN_2_40
 442 void                            g_variant_dict_clear                    (GVariantDict         *dict);
 443 GLIB_AVAILABLE_IN_2_40
 444 GVariant *                      g_variant_dict_end                      (GVariantDict         *dict);
 445 GLIB_AVAILABLE_IN_2_40
 446 GVariantDict *                  g_variant_dict_ref                      (GVariantDict         *dict);
 447 GLIB_AVAILABLE_IN_2_40
 448 void                            g_variant_dict_unref                    (GVariantDict         *dict);
 449
 450 G_END_DECLS
 451
 452 #endif /* __G_VARIANT_H__ */