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