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