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.1 of the License, 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 100 * to 18446744073709551615 (inclusive). That's a really big number, 101 * but a Rubik's cube can have a bit more than twice as many possible 102 * 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 GLIB_AVAILABLE_IN_2_60 378 gsize g_variant_type_string_get_depth_ (const gchar *type_string); 379 380 G_END_DECLS 381 382 #endif /* __G_VARIANT_TYPE_H__ */ 383