glib/gvarianttype.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 #ifndef __G_VARIANT_TYPE_H__
  24 #define __G_VARIANT_TYPE_H__
  25
  26 #include <glib/gmessages.h>
  27 #include <glib/gtypes.h>
  28
  29 G_BEGIN_DECLS
  30
  31 /**
  32  * GVariantType:
  33  *
  34  * A type in the GVariant type system.
  35  *
  36  * Two types may not be compared by value; use g_variant_type_equal() or
  37  * g_variant_type_is_subtype().  May be copied using
  38  * g_variant_type_copy() and freed using g_variant_type_free().
  39  **/
  40 typedef struct _GVariantType GVariantType;
  41
  42 /**
  43  * G_VARIANT_TYPE_BOOLEAN:
  44  *
  45  * The type of a value that can be either %TRUE or %FALSE.
  46  **/
  47 #define G_VARIANT_TYPE_BOOLEAN              ((const GVariantType *) "b")
  48
  49 /**
  50  * G_VARIANT_TYPE_BYTE:
  51  *
  52  * The type of an integer value that can range from 0 to 255.
  53  **/
  54 #define G_VARIANT_TYPE_BYTE                 ((const GVariantType *) "y")
  55
  56 /**
  57  * G_VARIANT_TYPE_INT16:
  58  *
  59  * The type of an integer value that can range from -32768 to 32767.
  60  **/
  61 #define G_VARIANT_TYPE_INT16                ((const GVariantType *) "n")
  62
  63 /**
  64  * G_VARIANT_TYPE_UINT16:
  65  *
  66  * The type of an integer value that can range from 0 to 65535.
  67  * There were about this many people living in Toronto in the 1870s.
  68  **/
  69 #define G_VARIANT_TYPE_UINT16               ((const GVariantType *) "q")
  70
  71 /**
  72  * G_VARIANT_TYPE_INT32:
  73  *
  74  * The type of an integer value that can range from -2147483648 to
  75  * 2147483647.
  76  **/
  77 #define G_VARIANT_TYPE_INT32                ((const GVariantType *) "i")
  78
  79 /**
  80  * G_VARIANT_TYPE_UINT32:
  81  *
  82  * The type of an integer value that can range from 0 to 4294967295.
  83  * That's one number for everyone who was around in the late 1970s.
  84  **/
  85 #define G_VARIANT_TYPE_UINT32               ((const GVariantType *) "u")
  86
  87 /**
  88  * G_VARIANT_TYPE_INT64:
  89  *
  90  * The type of an integer value that can range from
  91  * -9223372036854775808 to 9223372036854775807.
  92  **/
  93 #define G_VARIANT_TYPE_INT64                ((const GVariantType *) "x")
  94
  95 /**
  96  * G_VARIANT_TYPE_UINT64:
  97  *
  98  * The type of an integer value that can range from 0 to
  99  * 18446744073709551616.  That's a really big number, but a Rubik's
 100  * cube can have a bit more than twice as many possible positions.
 101  **/
 102 #define G_VARIANT_TYPE_UINT64               ((const GVariantType *) "t")
 103
 104 /**
 105  * G_VARIANT_TYPE_DOUBLE:
 106  *
 107  * The type of a double precision IEEE754 floating point number.
 108  * These guys go up to about 1.80e308 (plus and minus) but miss out on
 109  * some numbers in between.  In any case, that's far greater than the
 110  * estimated number of fundamental particles in the observable
 111  * universe.
 112  **/
 113 #define G_VARIANT_TYPE_DOUBLE               ((const GVariantType *) "d")
 114
 115 /**
 116  * G_VARIANT_TYPE_STRING:
 117  *
 118  * The type of a string.  "" is a string.  %NULL is not a string.
 119  **/
 120 #define G_VARIANT_TYPE_STRING               ((const GVariantType *) "s")
 121
 122 /**
 123  * G_VARIANT_TYPE_OBJECT_PATH:
 124  *
 125  * The type of a DBus object reference.  These are strings of a
 126  * specific format used to identify objects at a given destination on
 127  * the bus.
 128  *
 129  * If you are not interacting with DBus, then there is no reason to make
 130  * use of this type.  If you are, then the DBus specification contains a
 131  * precise description of valid object paths.
 132  **/
 133 #define G_VARIANT_TYPE_OBJECT_PATH          ((const GVariantType *) "o")
 134
 135 /**
 136  * G_VARIANT_TYPE_SIGNATURE:
 137  *
 138  * The type of a DBus type signature.  These are strings of a specific
 139  * format used as type signatures for DBus methods and messages.
 140  *
 141  * If you are not interacting with DBus, then there is no reason to make
 142  * use of this type.  If you are, then the DBus specification contains a
 143  * precise description of valid signature strings.
 144  **/
 145 #define G_VARIANT_TYPE_SIGNATURE            ((const GVariantType *) "g")
 146
 147 /**
 148  * G_VARIANT_TYPE_VARIANT:
 149  *
 150  * The type of a box that contains any other value (including another
 151  * variant).
 152  **/
 153 #define G_VARIANT_TYPE_VARIANT              ((const GVariantType *) "v")
 154
 155 /**
 156  * G_VARIANT_TYPE_HANDLE:
 157  *
 158  * The type of a 32bit signed integer value, that by convention, is used
 159  * as an index into an array of file descriptors that are sent alongside
 160  * a DBus message.
 161  *
 162  * If you are not interacting with DBus, then there is no reason to make
 163  * use of this type.
 164  **/
 165 #define G_VARIANT_TYPE_HANDLE               ((const GVariantType *) "h")
 166
 167 /**
 168  * G_VARIANT_TYPE_UNIT:
 169  *
 170  * The empty tuple type.  Has only one instance.  Known also as "triv"
 171  * or "void".
 172  **/
 173 #define G_VARIANT_TYPE_UNIT                 ((const GVariantType *) "()")
 174
 175 /**
 176  * G_VARIANT_TYPE_ANY:
 177  *
 178  * An indefinite type that is a supertype of every type (including
 179  * itself).
 180  **/
 181 #define G_VARIANT_TYPE_ANY                  ((const GVariantType *) "*")
 182
 183 /**
 184  * G_VARIANT_TYPE_BASIC:
 185  *
 186  * An indefinite type that is a supertype of every basic (ie:
 187  * non-container) type.
 188  **/
 189 #define G_VARIANT_TYPE_BASIC                ((const GVariantType *) "?")
 190
 191 /**
 192  * G_VARIANT_TYPE_MAYBE:
 193  *
 194  * An indefinite type that is a supertype of every maybe type.
 195  **/
 196 #define G_VARIANT_TYPE_MAYBE                ((const GVariantType *) "m*")
 197
 198 /**
 199  * G_VARIANT_TYPE_ARRAY:
 200  *
 201  * An indefinite type that is a supertype of every array type.
 202  **/
 203 #define G_VARIANT_TYPE_ARRAY                ((const GVariantType *) "a*")
 204
 205 /**
 206  * G_VARIANT_TYPE_TUPLE:
 207  *
 208  * An indefinite type that is a supertype of every tuple type,
 209  * regardless of the number of items in the tuple.
 210  **/
 211 #define G_VARIANT_TYPE_TUPLE                ((const GVariantType *) "r")
 212
 213 /**
 214  * G_VARIANT_TYPE_DICT_ENTRY:
 215  *
 216  * An indefinite type that is a supertype of every dictionary entry
 217  * type.
 218  **/
 219 #define G_VARIANT_TYPE_DICT_ENTRY           ((const GVariantType *) "{?*}")
 220
 221 /**
 222  * G_VARIANT_TYPE_DICTIONARY:
 223  *
 224  * An indefinite type that is a supertype of every dictionary type --
 225  * that is, any array type that has an element type equal to any
 226  * dictionary entry type.
 227  **/
 228 #define G_VARIANT_TYPE_DICTIONARY           ((const GVariantType *) "a{?*}")
 229
 230 /**
 231  * G_VARIANT_TYPE:
 232  * @type_string: a well-formed #GVariantType type string
 233  *
 234  * Converts a string to a const #GVariantType.  Depending on the
 235  * current debugging level, this function may perform a runtime check
 236  * to ensure that @string is a valid GVariant type string.
 237  *
 238  * It is always a programmer error to use this macro with an invalid
 239  * type string.
 240  *
 241  * Since 2.24
 242  **/
 243 #ifndef G_DISABLE_CHECKS
 244 # define G_VARIANT_TYPE(type_string)            (g_variant_type_checked_ ((type_string)))
 245 #else
 246 # define G_VARIANT_TYPE(type_string)            ((const GVariantType *) (type_string))
 247 #endif
 248
 249 /* type string checking */
 250 gboolean                        g_variant_type_string_is_valid          (const gchar         *type_string);
 251 gboolean                        g_variant_type_string_scan              (const gchar         *string,
 252                                                                          const gchar         *limit,
 253                                                                          const gchar        **endptr);
 254
 255 /* create/destroy */
 256 void                            g_variant_type_free                     (GVariantType        *type);
 257 GVariantType *                  g_variant_type_copy                     (const GVariantType  *type);
 258 GVariantType *                  g_variant_type_new                      (const gchar         *type_string);
 259
 260 /* getters */
 261 gsize                           g_variant_type_get_string_length        (const GVariantType  *type);
 262 const gchar *                   g_variant_type_peek_string              (const GVariantType  *type);
 263 gchar *                         g_variant_type_dup_string               (const GVariantType  *type);
 264
 265 /* classification */
 266 gboolean                        g_variant_type_is_definite              (const GVariantType  *type);
 267 gboolean                        g_variant_type_is_container             (const GVariantType  *type);
 268 gboolean                        g_variant_type_is_basic                 (const GVariantType  *type);
 269 gboolean                        g_variant_type_is_maybe                 (const GVariantType  *type);
 270 gboolean                        g_variant_type_is_array                 (const GVariantType  *type);
 271 gboolean                        g_variant_type_is_tuple                 (const GVariantType  *type);
 272 gboolean                        g_variant_type_is_dict_entry            (const GVariantType  *type);
 273 gboolean                        g_variant_type_is_variant               (const GVariantType  *type);
 274
 275 /* for hash tables */
 276 guint                           g_variant_type_hash                     (gconstpointer        type);
 277 gboolean                        g_variant_type_equal                    (gconstpointer        type1,
 278                                                                          gconstpointer        type2);
 279
 280 /* subtypes */
 281 gboolean                        g_variant_type_is_subtype_of            (const GVariantType  *type,
 282                                                                          const GVariantType  *supertype);
 283
 284 /* type iterator interface */
 285 const GVariantType *            g_variant_type_element                  (const GVariantType  *type);
 286 const GVariantType *            g_variant_type_first                    (const GVariantType  *type);
 287 const GVariantType *            g_variant_type_next                     (const GVariantType  *type);
 288 gsize                           g_variant_type_n_items                  (const GVariantType  *type);
 289 const GVariantType *            g_variant_type_key                      (const GVariantType  *type);
 290 const GVariantType *            g_variant_type_value                    (const GVariantType  *type);
 291
 292 /* constructors */
 293 GVariantType *                  g_variant_type_new_array                (const GVariantType  *element);
 294 GVariantType *                  g_variant_type_new_maybe                (const GVariantType  *element);
 295 GVariantType *                  g_variant_type_new_tuple                (const GVariantType * const *items,
 296                                                                          gint                 length);
 297 GVariantType *                  g_variant_type_new_dict_entry           (const GVariantType  *key,
 298                                                                          const GVariantType  *value);
 299
 300 /*< private >*/
 301 const GVariantType *            g_variant_type_checked_                 (const gchar *);
 302
 303 G_END_DECLS
 304
 305 #endif /* __G_VARIANT_TYPE_H__ */