glib/gvarianttype.h

   1 /*
   2  * Copyright © 2007, 2008 Ryan Lortie
   3  * Copyright © 2009, 2010 Codethink Limited
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-or-later
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  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/gtypes.h>
  31
  32 G_BEGIN_DECLS
  33
  34 /**
  35  * GVariantType:
  36  *
  37  * A type in the GVariant type system.
  38  *
  39  * Two types may not be compared by value; use g_variant_type_equal() or
  40  * g_variant_type_is_subtype_of().  May be copied using
  41  * g_variant_type_copy() and freed using g_variant_type_free().
  42  **/
  43 typedef struct _GVariantType GVariantType;
  44
  45 /**
  46  * G_VARIANT_TYPE_BOOLEAN:
  47  *
  48  * The type of a value that can be either %TRUE or %FALSE.
  49  **/
  50 #define G_VARIANT_TYPE_BOOLEAN              ((const GVariantType *) "b")
  51
  52 /**
  53  * G_VARIANT_TYPE_BYTE:
  54  *
  55  * The type of an integer value that can range from 0 to 255.
  56  **/
  57 #define G_VARIANT_TYPE_BYTE                 ((const GVariantType *) "y")
  58
  59 /**
  60  * G_VARIANT_TYPE_INT16:
  61  *
  62  * The type of an integer value that can range from -32768 to 32767.
  63  **/
  64 #define G_VARIANT_TYPE_INT16                ((const GVariantType *) "n")
  65
  66 /**
  67  * G_VARIANT_TYPE_UINT16:
  68  *
  69  * The type of an integer value that can range from 0 to 65535.
  70  * There were about this many people living in Toronto in the 1870s.
  71  **/
  72 #define G_VARIANT_TYPE_UINT16               ((const GVariantType *) "q")
  73
  74 /**
  75  * G_VARIANT_TYPE_INT32:
  76  *
  77  * The type of an integer value that can range from -2147483648 to
  78  * 2147483647.
  79  **/
  80 #define G_VARIANT_TYPE_INT32                ((const GVariantType *) "i")
  81
  82 /**
  83  * G_VARIANT_TYPE_UINT32:
  84  *
  85  * The type of an integer value that can range from 0 to 4294967295.
  86  * That's one number for everyone who was around in the late 1970s.
  87  **/
  88 #define G_VARIANT_TYPE_UINT32               ((const GVariantType *) "u")
  89
  90 /**
  91  * G_VARIANT_TYPE_INT64:
  92  *
  93  * The type of an integer value that can range from
  94  * -9223372036854775808 to 9223372036854775807.
  95  **/
  96 #define G_VARIANT_TYPE_INT64                ((const GVariantType *) "x")
  97
  98 /**
  99  * G_VARIANT_TYPE_UINT64:
 100  *
 101  * The type of an integer value that can range from 0
 102  * to 18446744073709551615 (inclusive).  That's a really big number,
 103  * but a Rubik's cube can have a bit more than twice as many possible
 104  * 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 GLIB_AVAILABLE_IN_2_60
 380 gsize                           g_variant_type_string_get_depth_        (const gchar *type_string);
 381
 382 G_END_DECLS
 383
 384 #endif /* __G_VARIANT_TYPE_H__ */