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_FLOAT:
 108  *
 109  * The type of a single precision IEEE754 floating point number.  You
 110  * can store a number as large as 3.40e38 in these (plus and minus) but
 111  * there are some gaps on the way.
 112  **/
 113 #define G_VARIANT_TYPE_FLOAT                ((const GVariantType *) "f")
 114
 115 /**
 116  * G_VARIANT_TYPE_DOUBLE:
 117  *
 118  * The type of a double precision IEEE754 floating point number.
 119  * These guys go up to about 1.80e308 (plus and minus) but miss out on
 120  * some numbers in between.  In any case, that's far greater than the
 121  * estimated number of fundamental particles in the observable
 122  * universe.
 123  **/
 124 #define G_VARIANT_TYPE_DOUBLE               ((const GVariantType *) "d")
 125
 126 /**
 127  * G_VARIANT_TYPE_STRING:
 128  *
 129  * The type of a string.  "" is a string.  %NULL is not a string.
 130  **/
 131 #define G_VARIANT_TYPE_STRING               ((const GVariantType *) "s")
 132
 133 /**
 134  * G_VARIANT_TYPE_OBJECT_PATH:
 135  *
 136  * The type of a D-Bus object reference.  These are strings of a
 137  * specific format used to identify objects at a given destination on
 138  * the bus.
 139  *
 140  * If you are not interacting with D-Bus, then there is no reason to make
 141  * use of this type.  If you are, then the D-Bus specification contains a
 142  * precise description of valid object paths.
 143  **/
 144 #define G_VARIANT_TYPE_OBJECT_PATH          ((const GVariantType *) "o")
 145
 146 /**
 147  * G_VARIANT_TYPE_SIGNATURE:
 148  *
 149  * The type of a D-Bus type signature.  These are strings of a specific
 150  * format used as type signatures for D-Bus methods and messages.
 151  *
 152  * If you are not interacting with D-Bus, then there is no reason to make
 153  * use of this type.  If you are, then the D-Bus specification contains a
 154  * precise description of valid signature strings.
 155  **/
 156 #define G_VARIANT_TYPE_SIGNATURE            ((const GVariantType *) "g")
 157
 158 /**
 159  * G_VARIANT_TYPE_VARIANT:
 160  *
 161  * The type of a box that contains any other value (including another
 162  * variant).
 163  **/
 164 #define G_VARIANT_TYPE_VARIANT              ((const GVariantType *) "v")
 165
 166 /**
 167  * G_VARIANT_TYPE_HANDLE:
 168  *
 169  * The type of a 32bit signed integer value, that by convention, is used
 170  * as an index into an array of file descriptors that are sent alongside
 171  * a D-Bus message.
 172  *
 173  * If you are not interacting with D-Bus, then there is no reason to make
 174  * use of this type.
 175  **/
 176 #define G_VARIANT_TYPE_HANDLE               ((const GVariantType *) "h")
 177
 178 /**
 179  * G_VARIANT_TYPE_UNIT:
 180  *
 181  * The empty tuple type.  Has only one instance.  Known also as "triv"
 182  * or "void".
 183  **/
 184 #define G_VARIANT_TYPE_UNIT                 ((const GVariantType *) "()")
 185
 186 /**
 187  * G_VARIANT_TYPE_ANY:
 188  *
 189  * An indefinite type that is a supertype of every type (including
 190  * itself).
 191  **/
 192 #define G_VARIANT_TYPE_ANY                  ((const GVariantType *) "*")
 193
 194 /**
 195  * G_VARIANT_TYPE_BASIC:
 196  *
 197  * An indefinite type that is a supertype of every basic (ie:
 198  * non-container) type.
 199  **/
 200 #define G_VARIANT_TYPE_BASIC                ((const GVariantType *) "?")
 201
 202 /**
 203  * G_VARIANT_TYPE_MAYBE:
 204  *
 205  * An indefinite type that is a supertype of every maybe type.
 206  **/
 207 #define G_VARIANT_TYPE_MAYBE                ((const GVariantType *) "m*")
 208
 209 /**
 210  * G_VARIANT_TYPE_ARRAY:
 211  *
 212  * An indefinite type that is a supertype of every array type.
 213  **/
 214 #define G_VARIANT_TYPE_ARRAY                ((const GVariantType *) "a*")
 215
 216 /**
 217  * G_VARIANT_TYPE_TUPLE:
 218  *
 219  * An indefinite type that is a supertype of every tuple type,
 220  * regardless of the number of items in the tuple.
 221  **/
 222 #define G_VARIANT_TYPE_TUPLE                ((const GVariantType *) "r")
 223
 224 /**
 225  * G_VARIANT_TYPE_DICT_ENTRY:
 226  *
 227  * An indefinite type that is a supertype of every dictionary entry
 228  * type.
 229  **/
 230 #define G_VARIANT_TYPE_DICT_ENTRY           ((const GVariantType *) "{?*}")
 231
 232 /**
 233  * G_VARIANT_TYPE_DICTIONARY:
 234  *
 235  * An indefinite type that is a supertype of every dictionary type --
 236  * that is, any array type that has an element type equal to any
 237  * dictionary entry type.
 238  **/
 239 #define G_VARIANT_TYPE_DICTIONARY           ((const GVariantType *) "a{?*}")
 240
 241 /**
 242  * G_VARIANT_TYPE_STRING_ARRAY:
 243  *
 244  * The type of an array of strings.
 245  **/
 246 #define G_VARIANT_TYPE_STRING_ARRAY         ((const GVariantType *) "as")
 247
 248 /**
 249  * G_VARIANT_TYPE_OBJECT_PATH_ARRAY:
 250  *
 251  * The type of an array of object paths.
 252  **/
 253 #define G_VARIANT_TYPE_OBJECT_PATH_ARRAY    ((const GVariantType *) "ao")
 254
 255 /**
 256  * G_VARIANT_TYPE_BYTESTRING:
 257  *
 258  * The type of an array of bytes.  This type is commonly used to pass
 259  * around strings that may not be valid utf8.  In that case, the
 260  * convention is that the nul terminator character should be included as
 261  * the last character in the array.
 262  **/
 263 #define G_VARIANT_TYPE_BYTESTRING           ((const GVariantType *) "ay")
 264
 265 /**
 266  * G_VARIANT_TYPE_BYTESTRING_ARRAY:
 267  *
 268  * The type of an array of byte strings (an array of arrays of bytes).
 269  **/
 270 #define G_VARIANT_TYPE_BYTESTRING_ARRAY     ((const GVariantType *) "aay")
 271
 272 /**
 273  * G_VARIANT_TYPE_VARDICT:
 274  *
 275  * The type of a dictionary mapping strings to variants (the ubiquitous
 276  * "a{sv}" type).
 277  *
 278  * Since: 2.30
 279  **/
 280 #define G_VARIANT_TYPE_VARDICT              ((const GVariantType *) "a{sv}")
 281
 282
 283 /**
 284  * G_VARIANT_TYPE:
 285  * @type_string: a well-formed #GVariantType type string
 286  *
 287  * Converts a string to a const #GVariantType.  Depending on the
 288  * current debugging level, this function may perform a runtime check
 289  * to ensure that @string is a valid GVariant type string.
 290  *
 291  * It is always a programmer error to use this macro with an invalid
 292  * type string. If in doubt, use g_variant_type_string_is_valid() to
 293  * check if the string is valid.
 294  *
 295  * Since 2.24
 296  **/
 297 #ifndef G_DISABLE_CHECKS
 298 # define G_VARIANT_TYPE(type_string)            (g_variant_type_checked_ ((type_string)))
 299 #else
 300 # define G_VARIANT_TYPE(type_string)            ((const GVariantType *) (type_string))
 301 #endif
 302
 303 /* type string checking */
 304 GLIB_AVAILABLE_IN_ALL
 305 gboolean                        g_variant_type_string_is_valid          (const gchar         *type_string);
 306 GLIB_AVAILABLE_IN_ALL
 307 gboolean                        g_variant_type_string_scan              (const gchar         *string,
 308                                                                          const gchar         *limit,
 309                                                                          const gchar        **endptr);
 310
 311 /* create/destroy */
 312 GLIB_AVAILABLE_IN_ALL
 313 void                            g_variant_type_free                     (GVariantType        *type);
 314 GLIB_AVAILABLE_IN_ALL
 315 GVariantType *                  g_variant_type_copy                     (const GVariantType  *type);
 316 GLIB_AVAILABLE_IN_ALL
 317 GVariantType *                  g_variant_type_new                      (const gchar         *type_string);
 318
 319 /* getters */
 320 GLIB_AVAILABLE_IN_ALL
 321 gsize                           g_variant_type_get_string_length        (const GVariantType  *type);
 322 GLIB_AVAILABLE_IN_ALL
 323 const gchar *                   g_variant_type_peek_string              (const GVariantType  *type);
 324 GLIB_AVAILABLE_IN_ALL
 325 gchar *                         g_variant_type_dup_string               (const GVariantType  *type);
 326
 327 /* classification */
 328 GLIB_AVAILABLE_IN_ALL
 329 gboolean                        g_variant_type_is_definite              (const GVariantType  *type);
 330 GLIB_AVAILABLE_IN_ALL
 331 gboolean                        g_variant_type_is_container             (const GVariantType  *type);
 332 GLIB_AVAILABLE_IN_ALL
 333 gboolean                        g_variant_type_is_basic                 (const GVariantType  *type);
 334 GLIB_AVAILABLE_IN_ALL
 335 gboolean                        g_variant_type_is_maybe                 (const GVariantType  *type);
 336 GLIB_AVAILABLE_IN_ALL
 337 gboolean                        g_variant_type_is_array                 (const GVariantType  *type);
 338 GLIB_AVAILABLE_IN_ALL
 339 gboolean                        g_variant_type_is_tuple                 (const GVariantType  *type);
 340 GLIB_AVAILABLE_IN_ALL
 341 gboolean                        g_variant_type_is_dict_entry            (const GVariantType  *type);
 342 GLIB_AVAILABLE_IN_ALL
 343 gboolean                        g_variant_type_is_variant               (const GVariantType  *type);
 344
 345 /* for hash tables */
 346 GLIB_AVAILABLE_IN_ALL
 347 guint                           g_variant_type_hash                     (gconstpointer        type);
 348 GLIB_AVAILABLE_IN_ALL
 349 gboolean                        g_variant_type_equal                    (gconstpointer        type1,
 350                                                                          gconstpointer        type2);
 351
 352 /* subtypes */
 353 GLIB_AVAILABLE_IN_ALL
 354 gboolean                        g_variant_type_is_subtype_of            (const GVariantType  *type,
 355                                                                          const GVariantType  *supertype);
 356
 357 /* type iterator interface */
 358 GLIB_AVAILABLE_IN_ALL
 359 const GVariantType *            g_variant_type_element                  (const GVariantType  *type);
 360 GLIB_AVAILABLE_IN_ALL
 361 const GVariantType *            g_variant_type_first                    (const GVariantType  *type);
 362 GLIB_AVAILABLE_IN_ALL
 363 const GVariantType *            g_variant_type_next                     (const GVariantType  *type);
 364 GLIB_AVAILABLE_IN_ALL
 365 gsize                           g_variant_type_n_items                  (const GVariantType  *type);
 366 GLIB_AVAILABLE_IN_ALL
 367 const GVariantType *            g_variant_type_key                      (const GVariantType  *type);
 368 GLIB_AVAILABLE_IN_ALL
 369 const GVariantType *            g_variant_type_value                    (const GVariantType  *type);
 370
 371 /* constructors */
 372 GLIB_AVAILABLE_IN_ALL
 373 GVariantType *                  g_variant_type_new_array                (const GVariantType  *element);
 374 GLIB_AVAILABLE_IN_ALL
 375 GVariantType *                  g_variant_type_new_maybe                (const GVariantType  *element);
 376 GLIB_AVAILABLE_IN_ALL
 377 GVariantType *                  g_variant_type_new_tuple                (const GVariantType * const *items,
 378                                                                          gint                 length);
 379 GLIB_AVAILABLE_IN_ALL
 380 GVariantType *                  g_variant_type_new_dict_entry           (const GVariantType  *key,
 381                                                                          const GVariantType  *value);
 382
 383 /*< private >*/
 384 GLIB_AVAILABLE_IN_ALL
 385 const GVariantType *            g_variant_type_checked_                 (const gchar *);
 386
 387 G_END_DECLS
 388
 389 #endif /* __G_VARIANT_TYPE_H__ */