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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Author: Ryan Lortie <desrt@desrt.ca>
  21  */
  22
  23 #if defined(G_DISABLE_SINGLE_INCLUDES) && !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  24 #error "Only <glib.h> can be included directly."
  25 #endif
  26
  27 #ifndef __G_VARIANT_H__
  28 #define __G_VARIANT_H__
  29
  30 #include <glib/gvarianttype.h>
  31 #include <glib/gstring.h>
  32
  33 G_BEGIN_DECLS
  34
  35 typedef struct _GVariant        GVariant;
  36
  37 typedef enum
  38 {
  39   G_VARIANT_CLASS_BOOLEAN       = 'b',
  40   G_VARIANT_CLASS_BYTE          = 'y',
  41   G_VARIANT_CLASS_INT16         = 'n',
  42   G_VARIANT_CLASS_UINT16        = 'q',
  43   G_VARIANT_CLASS_INT32         = 'i',
  44   G_VARIANT_CLASS_UINT32        = 'u',
  45   G_VARIANT_CLASS_INT64         = 'x',
  46   G_VARIANT_CLASS_UINT64        = 't',
  47   G_VARIANT_CLASS_HANDLE        = 'h',
  48   G_VARIANT_CLASS_DOUBLE        = 'd',
  49   G_VARIANT_CLASS_STRING        = 's',
  50   G_VARIANT_CLASS_OBJECT_PATH   = 'o',
  51   G_VARIANT_CLASS_SIGNATURE     = 'g',
  52   G_VARIANT_CLASS_VARIANT       = 'v',
  53   G_VARIANT_CLASS_MAYBE         = 'm',
  54   G_VARIANT_CLASS_ARRAY         = 'a',
  55   G_VARIANT_CLASS_TUPLE         = '(',
  56   G_VARIANT_CLASS_DICT_ENTRY    = '{'
  57 } GVariantClass;
  58
  59 void                            g_variant_unref                         (GVariant             *value);
  60 GVariant *                      g_variant_ref                           (GVariant             *value);
  61 GVariant *                      g_variant_ref_sink                      (GVariant             *value);
  62 gboolean                        g_variant_is_floating                   (GVariant             *value);
  63
  64 const GVariantType *            g_variant_get_type                      (GVariant             *value);
  65 const gchar *                   g_variant_get_type_string               (GVariant             *value);
  66 gboolean                        g_variant_is_of_type                    (GVariant             *value,
  67                                                                          const GVariantType   *type);
  68 gboolean                        g_variant_is_container                  (GVariant             *value);
  69 GVariantClass                   g_variant_classify                      (GVariant             *value);
  70 GVariant *                      g_variant_new_boolean                   (gboolean              value);
  71 GVariant *                      g_variant_new_byte                      (guchar                value);
  72 GVariant *                      g_variant_new_int16                     (gint16                value);
  73 GVariant *                      g_variant_new_uint16                    (guint16               value);
  74 GVariant *                      g_variant_new_int32                     (gint32                value);
  75 GVariant *                      g_variant_new_uint32                    (guint32               value);
  76 GVariant *                      g_variant_new_int64                     (gint64                value);
  77 GVariant *                      g_variant_new_uint64                    (guint64               value);
  78 GVariant *                      g_variant_new_handle                    (gint32                value);
  79 GVariant *                      g_variant_new_double                    (gdouble               value);
  80 GVariant *                      g_variant_new_string                    (const gchar          *string);
  81 GVariant *                      g_variant_new_object_path               (const gchar          *object_path);
  82 gboolean                        g_variant_is_object_path                (const gchar          *string);
  83 GVariant *                      g_variant_new_signature                 (const gchar          *signature);
  84 gboolean                        g_variant_is_signature                  (const gchar          *string);
  85 GVariant *                      g_variant_new_variant                   (GVariant             *value);
  86 GVariant *                      g_variant_new_strv                      (const gchar * const  *strv,
  87                                                                          gssize                length);
  88 GVariant *                      g_variant_new_bytestring                (const gchar          *string);
  89 GVariant *                      g_variant_new_bytestring_array          (const gchar * const  *strv,
  90                                                                          gssize                length);
  91
  92 gboolean                        g_variant_get_boolean                   (GVariant             *value);
  93 guchar                          g_variant_get_byte                      (GVariant             *value);
  94 gint16                          g_variant_get_int16                     (GVariant             *value);
  95 guint16                         g_variant_get_uint16                    (GVariant             *value);
  96 gint32                          g_variant_get_int32                     (GVariant             *value);
  97 guint32                         g_variant_get_uint32                    (GVariant             *value);
  98 gint64                          g_variant_get_int64                     (GVariant             *value);
  99 guint64                         g_variant_get_uint64                    (GVariant             *value);
 100 gint32                          g_variant_get_handle                    (GVariant             *value);
 101 gdouble                         g_variant_get_double                    (GVariant             *value);
 102 GVariant *                      g_variant_get_variant                   (GVariant             *value);
 103 const gchar *                   g_variant_get_string                    (GVariant             *value,
 104                                                                          gsize                *length);
 105 gchar *                         g_variant_dup_string                    (GVariant             *value,
 106                                                                          gsize                *length);
 107 const gchar **                  g_variant_get_strv                      (GVariant             *value,
 108                                                                          gsize                *length);
 109 gchar **                        g_variant_dup_strv                      (GVariant             *value,
 110                                                                          gsize                *length);
 111 const gchar *                   g_variant_get_bytestring                (GVariant             *value);
 112 gchar *                         g_variant_dup_bytestring                (GVariant             *value,
 113                                                                          gsize                *length);
 114 const gchar **                  g_variant_get_bytestring_array          (GVariant             *value,
 115                                                                          gsize                *length);
 116 gchar **                        g_variant_dup_bytestring_array          (GVariant             *value,
 117                                                                          gsize                *length);
 118
 119 GVariant *                      g_variant_new_maybe                     (const GVariantType   *child_type,
 120                                                                          GVariant             *child);
 121 GVariant *                      g_variant_new_array                     (const GVariantType   *child_type,
 122                                                                          GVariant * const     *children,
 123                                                                          gsize                 n_children);
 124 GVariant *                      g_variant_new_tuple                     (GVariant * const     *children,
 125                                                                          gsize                 n_children);
 126 GVariant *                      g_variant_new_dict_entry                (GVariant             *key,
 127                                                                          GVariant             *value);
 128
 129 GVariant *                      g_variant_get_maybe                     (GVariant             *value);
 130 gsize                           g_variant_n_children                    (GVariant             *value);
 131 void                            g_variant_get_child                     (GVariant             *value,
 132                                                                          gsize                 index_,
 133                                                                          const gchar          *format_string,
 134                                                                          ...);
 135 GVariant *                      g_variant_get_child_value               (GVariant             *value,
 136                                                                          gsize                 index_);
 137 gboolean                        g_variant_lookup                        (GVariant             *dictionary,
 138                                                                          const gchar          *key,
 139                                                                          const gchar          *format_string,
 140                                                                          ...);
 141 GVariant *                      g_variant_lookup_value                  (GVariant             *dictionary,
 142                                                                          const gchar          *key,
 143                                                                          const GVariantType   *expected_type);
 144 gconstpointer                   g_variant_get_fixed_array               (GVariant             *value,
 145                                                                          gsize                *n_elements,
 146                                                                          gsize                 element_size);
 147
 148 gsize                           g_variant_get_size                      (GVariant             *value);
 149 gconstpointer                   g_variant_get_data                      (GVariant             *value);
 150 void                            g_variant_store                         (GVariant             *value,
 151                                                                          gpointer              data);
 152
 153 gchar *                         g_variant_print                         (GVariant             *value,
 154                                                                          gboolean              type_annotate);
 155 GString *                       g_variant_print_string                  (GVariant             *value,
 156                                                                          GString              *string,
 157                                                                          gboolean              type_annotate);
 158
 159 guint                           g_variant_hash                          (gconstpointer         value);
 160 gboolean                        g_variant_equal                         (gconstpointer         one,
 161                                                                          gconstpointer         two);
 162
 163 GVariant *                      g_variant_get_normal_form               (GVariant             *value);
 164 gboolean                        g_variant_is_normal_form                (GVariant             *value);
 165 GVariant *                      g_variant_byteswap                      (GVariant             *value);
 166 GVariant *                      g_variant_new_from_data                 (const GVariantType   *type,
 167                                                                          gconstpointer         data,
 168                                                                          gsize                 size,
 169                                                                          gboolean              trusted,
 170                                                                          GDestroyNotify        notify,
 171                                                                          gpointer              user_data);
 172
 173 typedef struct _GVariantIter GVariantIter;
 174 struct _GVariantIter {
 175   /*< private >*/
 176   gsize x[16];
 177 };
 178
 179 GVariantIter *                  g_variant_iter_new                      (GVariant             *value);
 180 gsize                           g_variant_iter_init                     (GVariantIter         *iter,
 181                                                                          GVariant             *value);
 182 GVariantIter *                  g_variant_iter_copy                     (GVariantIter         *iter);
 183 gsize                           g_variant_iter_n_children               (GVariantIter         *iter);
 184 void                            g_variant_iter_free                     (GVariantIter         *iter);
 185 GVariant *                      g_variant_iter_next_value               (GVariantIter         *iter);
 186 gboolean                        g_variant_iter_next                     (GVariantIter         *iter,
 187                                                                          const gchar          *format_string,
 188                                                                          ...);
 189 gboolean                        g_variant_iter_loop                     (GVariantIter         *iter,
 190                                                                          const gchar          *format_string,
 191                                                                          ...);
 192
 193
 194 typedef struct _GVariantBuilder GVariantBuilder;
 195 struct _GVariantBuilder {
 196   /*< private >*/
 197   gsize x[16];
 198 };
 199
 200 typedef enum
 201 {
 202   G_VARIANT_PARSE_ERROR_FAILED,
 203   G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED,
 204   G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE,
 205   G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED,
 206   G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END,
 207   G_VARIANT_PARSE_ERROR_INVALID_CHARACTER,
 208   G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING,
 209   G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH,
 210   G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE,
 211   G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING,
 212   G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE,
 213   G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE,
 214   G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG,
 215   G_VARIANT_PARSE_ERROR_TYPE_ERROR,
 216   G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN,
 217   G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD,
 218   G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT,
 219   G_VARIANT_PARSE_ERROR_VALUE_EXPECTED
 220 } GVariantParseError;
 221 #define G_VARIANT_PARSE_ERROR (g_variant_parser_get_error_quark ())
 222
 223 GQuark                          g_variant_parser_get_error_quark        (void);
 224
 225 GVariantBuilder *               g_variant_builder_new                   (const GVariantType   *type);
 226 void                            g_variant_builder_unref                 (GVariantBuilder      *builder);
 227 GVariantBuilder *               g_variant_builder_ref                   (GVariantBuilder      *builder);
 228 void                            g_variant_builder_init                  (GVariantBuilder      *builder,
 229                                                                          const GVariantType   *type);
 230 GVariant *                      g_variant_builder_end                   (GVariantBuilder      *builder);
 231 void                            g_variant_builder_clear                 (GVariantBuilder      *builder);
 232 void                            g_variant_builder_open                  (GVariantBuilder      *builder,
 233                                                                          const GVariantType   *type);
 234 void                            g_variant_builder_close                 (GVariantBuilder      *builder);
 235 void                            g_variant_builder_add_value             (GVariantBuilder      *builder,
 236                                                                          GVariant             *value);
 237 void                            g_variant_builder_add                   (GVariantBuilder      *builder,
 238                                                                          const gchar          *format_string,
 239                                                                          ...);
 240 void                            g_variant_builder_add_parsed            (GVariantBuilder      *builder,
 241                                                                          const gchar          *format,
 242                                                                          ...);
 243
 244 GVariant *                      g_variant_new                           (const gchar          *format_string,
 245                                                                          ...);
 246 void                            g_variant_get                           (GVariant             *value,
 247                                                                          const gchar          *format_string,
 248                                                                          ...);
 249 GVariant *                      g_variant_new_va                        (const gchar          *format_string,
 250                                                                          const gchar         **endptr,
 251                                                                          va_list              *app);
 252 void                            g_variant_get_va                        (GVariant             *value,
 253                                                                          const gchar          *format_string,
 254                                                                          const gchar         **endptr,
 255                                                                          va_list              *app);
 256
 257
 258 GVariant *                      g_variant_parse                         (const GVariantType   *type,
 259                                                                          const gchar          *text,
 260                                                                          const gchar          *limit,
 261                                                                          const gchar         **endptr,
 262                                                                          GError              **error);
 263 GVariant *                      g_variant_new_parsed                    (const gchar          *format,
 264                                                                          ...);
 265 GVariant *                      g_variant_new_parsed_va                 (const gchar          *format,
 266                                                                          va_list              *app);
 267
 268 gint                            g_variant_compare                       (gconstpointer one,
 269                                                                          gconstpointer two);
 270 G_END_DECLS
 271
 272 #endif /* __G_VARIANT_H__ */