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