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 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  27 #error "Only <glib.h> can be included directly."
  28 #endif
  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 D-Bus 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 D-Bus, then there is no reason to make
 134  * use of this type.  If you are, then the D-Bus 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 D-Bus type signature.  These are strings of a specific
 143  * format used as type signatures for D-Bus methods and messages.
 144  *
 145  * If you are not interacting with D-Bus, then there is no reason to make
 146  * use of this type.  If you are, then the D-Bus 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 D-Bus message.
 165  *
 166  * If you are not interacting with D-Bus, 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_OBJECT_PATH_ARRAY:
 243  *
 244  * The type of an array of object paths.
 245  **/
 246 #define G_VARIANT_TYPE_OBJECT_PATH_ARRAY    ((const GVariantType *) "ao")
 247
 248 /**
 249  * G_VARIANT_TYPE_BYTESTRING:
 250  *
 251  * The type of an array of bytes.  This type is commonly used to pass
 252  * around strings that may not be valid utf8.  In that case, the
 253  * convention is that the nul terminator character should be included as
 254  * the last character in the array.
 255  **/
 256 #define G_VARIANT_TYPE_BYTESTRING           ((const GVariantType *) "ay")
 257
 258 /**
 259  * G_VARIANT_TYPE_BYTESTRING_ARRAY:
 260  *
 261  * The type of an array of byte strings (an array of arrays of bytes).
 262  **/
 263 #define G_VARIANT_TYPE_BYTESTRING_ARRAY     ((const GVariantType *) "aay")
 264
 265 /**
 266  * G_VARIANT_TYPE_VARDICT:
 267  *
 268  * The type of a dictionary mapping strings to variants (the ubiquitous
 269  * "a{sv}" type).
 270  *
 271  * Since: 2.30
 272  **/
 273 #define G_VARIANT_TYPE_VARDICT              ((const GVariantType *) "a{sv}")
 274
 275
 276 /**
 277  * G_VARIANT_TYPE:
 278  * @type_string: a well-formed #GVariantType type string
 279  *
 280  * Converts a string to a const #GVariantType.  Depending on the
 281  * current debugging level, this function may perform a runtime check
 282  * to ensure that @string is a valid GVariant type string.
 283  *
 284  * It is always a programmer error to use this macro with an invalid
 285  * type string. If in doubt, use g_variant_type_string_is_valid() to
 286  * check if the string is valid.
 287  *
 288  * Since 2.24
 289  **/
 290 #ifndef G_DISABLE_CHECKS
 291 # define G_VARIANT_TYPE(type_string)            (g_variant_type_checked_ ((type_string)))
 292 #else
 293 # define G_VARIANT_TYPE(type_string)            ((const GVariantType *) (type_string))
 294 #endif
 295
 296 /* type string checking */
 297 GLIB_AVAILABLE_IN_ALL
 298 gboolean                        g_variant_type_string_is_valid          (const gchar         *type_string);
 299 GLIB_AVAILABLE_IN_ALL
 300 gboolean                        g_variant_type_string_scan              (const gchar         *string,
 301                                                                          const gchar         *limit,
 302                                                                          const gchar        **endptr);
 303
 304 /* create/destroy */
 305 GLIB_AVAILABLE_IN_ALL
 306 void                            g_variant_type_free                     (GVariantType        *type);
 307 GLIB_AVAILABLE_IN_ALL
 308 GVariantType *                  g_variant_type_copy                     (const GVariantType  *type);
 309 GLIB_AVAILABLE_IN_ALL
 310 GVariantType *                  g_variant_type_new                      (const gchar         *type_string);
 311
 312 /* getters */
 313 GLIB_AVAILABLE_IN_ALL
 314 gsize                           g_variant_type_get_string_length        (const GVariantType  *type);
 315 GLIB_AVAILABLE_IN_ALL
 316 const gchar *                   g_variant_type_peek_string              (const GVariantType  *type);
 317 GLIB_AVAILABLE_IN_ALL
 318 gchar *                         g_variant_type_dup_string               (const GVariantType  *type);
 319
 320 /* classification */
 321 GLIB_AVAILABLE_IN_ALL
 322 gboolean                        g_variant_type_is_definite              (const GVariantType  *type);
 323 GLIB_AVAILABLE_IN_ALL
 324 gboolean                        g_variant_type_is_container             (const GVariantType  *type);
 325 GLIB_AVAILABLE_IN_ALL
 326 gboolean                        g_variant_type_is_basic                 (const GVariantType  *type);
 327 GLIB_AVAILABLE_IN_ALL
 328 gboolean                        g_variant_type_is_maybe                 (const GVariantType  *type);
 329 GLIB_AVAILABLE_IN_ALL
 330 gboolean                        g_variant_type_is_array                 (const GVariantType  *type);
 331 GLIB_AVAILABLE_IN_ALL
 332 gboolean                        g_variant_type_is_tuple                 (const GVariantType  *type);
 333 GLIB_AVAILABLE_IN_ALL
 334 gboolean                        g_variant_type_is_dict_entry            (const GVariantType  *type);
 335 GLIB_AVAILABLE_IN_ALL
 336 gboolean                        g_variant_type_is_variant               (const GVariantType  *type);
 337
 338 /* for hash tables */
 339 GLIB_AVAILABLE_IN_ALL
 340 guint                           g_variant_type_hash                     (gconstpointer        type);
 341 GLIB_AVAILABLE_IN_ALL
 342 gboolean                        g_variant_type_equal                    (gconstpointer        type1,
 343                                                                          gconstpointer        type2);
 344
 345 /* subtypes */
 346 GLIB_AVAILABLE_IN_ALL
 347 gboolean                        g_variant_type_is_subtype_of            (const GVariantType  *type,
 348                                                                          const GVariantType  *supertype);
 349
 350 /* type iterator interface */
 351 GLIB_AVAILABLE_IN_ALL
 352 const GVariantType *            g_variant_type_element                  (const GVariantType  *type);
 353 GLIB_AVAILABLE_IN_ALL
 354 const GVariantType *            g_variant_type_first                    (const GVariantType  *type);
 355 GLIB_AVAILABLE_IN_ALL
 356 const GVariantType *            g_variant_type_next                     (const GVariantType  *type);
 357 GLIB_AVAILABLE_IN_ALL
 358 gsize                           g_variant_type_n_items                  (const GVariantType  *type);
 359 GLIB_AVAILABLE_IN_ALL
 360 const GVariantType *            g_variant_type_key                      (const GVariantType  *type);
 361 GLIB_AVAILABLE_IN_ALL
 362 const GVariantType *            g_variant_type_value                    (const GVariantType  *type);
 363
 364 /* constructors */
 365 GLIB_AVAILABLE_IN_ALL
 366 GVariantType *                  g_variant_type_new_array                (const GVariantType  *element);
 367 GLIB_AVAILABLE_IN_ALL
 368 GVariantType *                  g_variant_type_new_maybe                (const GVariantType  *element);
 369 GLIB_AVAILABLE_IN_ALL
 370 GVariantType *                  g_variant_type_new_tuple                (const GVariantType * const *items,
 371                                                                          gint                 length);
 372 GLIB_AVAILABLE_IN_ALL
 373 GVariantType *                  g_variant_type_new_dict_entry           (const GVariantType  *key,
 374                                                                          const GVariantType  *value);
 375
 376 /*< private >*/
 377 GLIB_AVAILABLE_IN_ALL
 378 const GVariantType *            g_variant_type_checked_                 (const gchar *);
 379
 380 G_END_DECLS
 381
 382 #endif /* __G_VARIANT_TYPE_H__ */