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_H__ 22 #define __G_VARIANT_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/gvarianttype.h> 29 #include <glib/gstring.h> 30 #include <glib/gbytes.h> 31 32 G_BEGIN_DECLS 33 34 typedef struct _GVariant GVariant; 35 36 typedef enum 37 { 38 G_VARIANT_CLASS_BOOLEAN = 'b', 39 G_VARIANT_CLASS_BYTE = 'y', 40 G_VARIANT_CLASS_INT16 = 'n', 41 G_VARIANT_CLASS_UINT16 = 'q', 42 G_VARIANT_CLASS_INT32 = 'i', 43 G_VARIANT_CLASS_UINT32 = 'u', 44 G_VARIANT_CLASS_INT64 = 'x', 45 G_VARIANT_CLASS_UINT64 = 't', 46 G_VARIANT_CLASS_HANDLE = 'h', 47 G_VARIANT_CLASS_DOUBLE = 'd', 48 G_VARIANT_CLASS_STRING = 's', 49 G_VARIANT_CLASS_OBJECT_PATH = 'o', 50 G_VARIANT_CLASS_SIGNATURE = 'g', 51 G_VARIANT_CLASS_VARIANT = 'v', 52 G_VARIANT_CLASS_MAYBE = 'm', 53 G_VARIANT_CLASS_ARRAY = 'a', 54 G_VARIANT_CLASS_TUPLE = '(', 55 G_VARIANT_CLASS_DICT_ENTRY = '{' 56 } GVariantClass; 57 58 GLIB_AVAILABLE_IN_ALL 59 void g_variant_unref (GVariant *value); 60 GLIB_AVAILABLE_IN_ALL 61 GVariant * g_variant_ref (GVariant *value); 62 GLIB_AVAILABLE_IN_ALL 63 GVariant * g_variant_ref_sink (GVariant *value); 64 GLIB_AVAILABLE_IN_ALL 65 gboolean g_variant_is_floating (GVariant *value); 66 GLIB_AVAILABLE_IN_ALL 67 GVariant * g_variant_take_ref (GVariant *value); 68 69 GLIB_AVAILABLE_IN_ALL 70 const GVariantType * g_variant_get_type (GVariant *value); 71 GLIB_AVAILABLE_IN_ALL 72 const gchar * g_variant_get_type_string (GVariant *value); 73 GLIB_AVAILABLE_IN_ALL 74 gboolean g_variant_is_of_type (GVariant *value, 75 const GVariantType *type); 76 GLIB_AVAILABLE_IN_ALL 77 gboolean g_variant_is_container (GVariant *value); 78 GLIB_AVAILABLE_IN_ALL 79 GVariantClass g_variant_classify (GVariant *value); 80 GLIB_AVAILABLE_IN_ALL 81 GVariant * g_variant_new_boolean (gboolean value); 82 GLIB_AVAILABLE_IN_ALL 83 GVariant * g_variant_new_byte (guint8 value); 84 GLIB_AVAILABLE_IN_ALL 85 GVariant * g_variant_new_int16 (gint16 value); 86 GLIB_AVAILABLE_IN_ALL 87 GVariant * g_variant_new_uint16 (guint16 value); 88 GLIB_AVAILABLE_IN_ALL 89 GVariant * g_variant_new_int32 (gint32 value); 90 GLIB_AVAILABLE_IN_ALL 91 GVariant * g_variant_new_uint32 (guint32 value); 92 GLIB_AVAILABLE_IN_ALL 93 GVariant * g_variant_new_int64 (gint64 value); 94 GLIB_AVAILABLE_IN_ALL 95 GVariant * g_variant_new_uint64 (guint64 value); 96 GLIB_AVAILABLE_IN_ALL 97 GVariant * g_variant_new_handle (gint32 value); 98 GLIB_AVAILABLE_IN_ALL 99 GVariant * g_variant_new_double (gdouble value); 100 GLIB_AVAILABLE_IN_ALL 101 GVariant * g_variant_new_string (const gchar *string); 102 GLIB_AVAILABLE_IN_2_38 103 GVariant * g_variant_new_take_string (gchar *string); 104 GLIB_AVAILABLE_IN_2_38 105 GVariant * g_variant_new_printf (const gchar *format_string, 106 ...) G_GNUC_PRINTF (1, 2); 107 GLIB_AVAILABLE_IN_ALL 108 GVariant * g_variant_new_object_path (const gchar *object_path); 109 GLIB_AVAILABLE_IN_ALL 110 gboolean g_variant_is_object_path (const gchar *string); 111 GLIB_AVAILABLE_IN_ALL 112 GVariant * g_variant_new_signature (const gchar *signature); 113 GLIB_AVAILABLE_IN_ALL 114 gboolean g_variant_is_signature (const gchar *string); 115 GLIB_AVAILABLE_IN_ALL 116 GVariant * g_variant_new_variant (GVariant *value); 117 GLIB_AVAILABLE_IN_ALL 118 GVariant * g_variant_new_strv (const gchar * const *strv, 119 gssize length); 120 GLIB_AVAILABLE_IN_2_30 121 GVariant * g_variant_new_objv (const gchar * const *strv, 122 gssize length); 123 GLIB_AVAILABLE_IN_ALL 124 GVariant * g_variant_new_bytestring (const gchar *string); 125 GLIB_AVAILABLE_IN_ALL 126 GVariant * g_variant_new_bytestring_array (const gchar * const *strv, 127 gssize length); 128 GLIB_AVAILABLE_IN_ALL 129 GVariant * g_variant_new_fixed_array (const GVariantType *element_type, 130 gconstpointer elements, 131 gsize n_elements, 132 gsize element_size); 133 GLIB_AVAILABLE_IN_ALL 134 gboolean g_variant_get_boolean (GVariant *value); 135 GLIB_AVAILABLE_IN_ALL 136 guint8 g_variant_get_byte (GVariant *value); 137 GLIB_AVAILABLE_IN_ALL 138 gint16 g_variant_get_int16 (GVariant *value); 139 GLIB_AVAILABLE_IN_ALL 140 guint16 g_variant_get_uint16 (GVariant *value); 141 GLIB_AVAILABLE_IN_ALL 142 gint32 g_variant_get_int32 (GVariant *value); 143 GLIB_AVAILABLE_IN_ALL 144 guint32 g_variant_get_uint32 (GVariant *value); 145 GLIB_AVAILABLE_IN_ALL 146 gint64 g_variant_get_int64 (GVariant *value); 147 GLIB_AVAILABLE_IN_ALL 148 guint64 g_variant_get_uint64 (GVariant *value); 149 GLIB_AVAILABLE_IN_ALL 150 gint32 g_variant_get_handle (GVariant *value); 151 GLIB_AVAILABLE_IN_ALL 152 gdouble g_variant_get_double (GVariant *value); 153 GLIB_AVAILABLE_IN_ALL 154 GVariant * g_variant_get_variant (GVariant *value); 155 GLIB_AVAILABLE_IN_ALL 156 const gchar * g_variant_get_string (GVariant *value, 157 gsize *length); 158 GLIB_AVAILABLE_IN_ALL 159 gchar * g_variant_dup_string (GVariant *value, 160 gsize *length); 161 GLIB_AVAILABLE_IN_ALL 162 const gchar ** g_variant_get_strv (GVariant *value, 163 gsize *length); 164 GLIB_AVAILABLE_IN_ALL 165 gchar ** g_variant_dup_strv (GVariant *value, 166 gsize *length); 167 GLIB_AVAILABLE_IN_2_30 168 const gchar ** g_variant_get_objv (GVariant *value, 169 gsize *length); 170 GLIB_AVAILABLE_IN_ALL 171 gchar ** g_variant_dup_objv (GVariant *value, 172 gsize *length); 173 GLIB_AVAILABLE_IN_ALL 174 const gchar * g_variant_get_bytestring (GVariant *value); 175 GLIB_AVAILABLE_IN_ALL 176 gchar * g_variant_dup_bytestring (GVariant *value, 177 gsize *length); 178 GLIB_AVAILABLE_IN_ALL 179 const gchar ** g_variant_get_bytestring_array (GVariant *value, 180 gsize *length); 181 GLIB_AVAILABLE_IN_ALL 182 gchar ** g_variant_dup_bytestring_array (GVariant *value, 183 gsize *length); 184 185 GLIB_AVAILABLE_IN_ALL 186 GVariant * g_variant_new_maybe (const GVariantType *child_type, 187 GVariant *child); 188 GLIB_AVAILABLE_IN_ALL 189 GVariant * g_variant_new_array (const GVariantType *child_type, 190 GVariant * const *children, 191 gsize n_children); 192 GLIB_AVAILABLE_IN_ALL 193 GVariant * g_variant_new_tuple (GVariant * const *children, 194 gsize n_children); 195 GLIB_AVAILABLE_IN_ALL 196 GVariant * g_variant_new_dict_entry (GVariant *key, 197 GVariant *value); 198 199 GLIB_AVAILABLE_IN_ALL 200 GVariant * g_variant_get_maybe (GVariant *value); 201 GLIB_AVAILABLE_IN_ALL 202 gsize g_variant_n_children (GVariant *value); 203 GLIB_AVAILABLE_IN_ALL 204 void g_variant_get_child (GVariant *value, 205 gsize index_, 206 const gchar *format_string, 207 ...); 208 GLIB_AVAILABLE_IN_ALL 209 GVariant * g_variant_get_child_value (GVariant *value, 210 gsize index_); 211 GLIB_AVAILABLE_IN_ALL 212 gboolean g_variant_lookup (GVariant *dictionary, 213 const gchar *key, 214 const gchar *format_string, 215 ...); 216 GLIB_AVAILABLE_IN_ALL 217 GVariant * g_variant_lookup_value (GVariant *dictionary, 218 const gchar *key, 219 const GVariantType *expected_type); 220 GLIB_AVAILABLE_IN_ALL 221 gconstpointer g_variant_get_fixed_array (GVariant *value, 222 gsize *n_elements, 223 gsize element_size); 224 225 GLIB_AVAILABLE_IN_ALL 226 gsize g_variant_get_size (GVariant *value); 227 GLIB_AVAILABLE_IN_ALL 228 gconstpointer g_variant_get_data (GVariant *value); 229 GLIB_AVAILABLE_IN_2_36 230 GBytes * g_variant_get_data_as_bytes (GVariant *value); 231 GLIB_AVAILABLE_IN_ALL 232 void g_variant_store (GVariant *value, 233 gpointer data); 234 235 GLIB_AVAILABLE_IN_ALL 236 gchar * g_variant_print (GVariant *value, 237 gboolean type_annotate); 238 GLIB_AVAILABLE_IN_ALL 239 GString * g_variant_print_string (GVariant *value, 240 GString *string, 241 gboolean type_annotate); 242 243 GLIB_AVAILABLE_IN_ALL 244 guint g_variant_hash (gconstpointer value); 245 GLIB_AVAILABLE_IN_ALL 246 gboolean g_variant_equal (gconstpointer one, 247 gconstpointer two); 248 249 GLIB_AVAILABLE_IN_ALL 250 GVariant * g_variant_get_normal_form (GVariant *value); 251 GLIB_AVAILABLE_IN_ALL 252 gboolean g_variant_is_normal_form (GVariant *value); 253 GLIB_AVAILABLE_IN_ALL 254 GVariant * g_variant_byteswap (GVariant *value); 255 256 GLIB_AVAILABLE_IN_2_36 257 GVariant * g_variant_new_from_bytes (const GVariantType *type, 258 GBytes *bytes, 259 gboolean trusted); 260 GLIB_AVAILABLE_IN_ALL 261 GVariant * g_variant_new_from_data (const GVariantType *type, 262 gconstpointer data, 263 gsize size, 264 gboolean trusted, 265 GDestroyNotify notify, 266 gpointer user_data); 267 268 typedef struct _GVariantIter GVariantIter; 269 struct _GVariantIter { 270 /*< private >*/ 271 gsize x[16]; 272 }; 273 274 GLIB_AVAILABLE_IN_ALL 275 GVariantIter * g_variant_iter_new (GVariant *value); 276 GLIB_AVAILABLE_IN_ALL 277 gsize g_variant_iter_init (GVariantIter *iter, 278 GVariant *value); 279 GLIB_AVAILABLE_IN_ALL 280 GVariantIter * g_variant_iter_copy (GVariantIter *iter); 281 GLIB_AVAILABLE_IN_ALL 282 gsize g_variant_iter_n_children (GVariantIter *iter); 283 GLIB_AVAILABLE_IN_ALL 284 void g_variant_iter_free (GVariantIter *iter); 285 GLIB_AVAILABLE_IN_ALL 286 GVariant * g_variant_iter_next_value (GVariantIter *iter); 287 GLIB_AVAILABLE_IN_ALL 288 gboolean g_variant_iter_next (GVariantIter *iter, 289 const gchar *format_string, 290 ...); 291 GLIB_AVAILABLE_IN_ALL 292 gboolean g_variant_iter_loop (GVariantIter *iter, 293 const gchar *format_string, 294 ...); 295 296 297 typedef struct _GVariantBuilder GVariantBuilder; 298 struct _GVariantBuilder { 299 /*< private >*/ 300 union 301 { 302 struct { 303 gsize partial_magic; 304 const GVariantType *type; 305 gsize y[14]; 306 } s; 307 gsize x[16]; 308 } u; 309 }; 310 311 typedef enum 312 { 313 G_VARIANT_PARSE_ERROR_FAILED, 314 G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED, 315 G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE, 316 G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED, 317 G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END, 318 G_VARIANT_PARSE_ERROR_INVALID_CHARACTER, 319 G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING, 320 G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH, 321 G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE, 322 G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING, 323 G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE, 324 G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE, 325 G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG, 326 G_VARIANT_PARSE_ERROR_TYPE_ERROR, 327 G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN, 328 G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD, 329 G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT, 330 G_VARIANT_PARSE_ERROR_VALUE_EXPECTED, 331 G_VARIANT_PARSE_ERROR_RECURSION 332 } GVariantParseError; 333 #define G_VARIANT_PARSE_ERROR (g_variant_parse_error_quark ()) 334 335 GLIB_DEPRECATED_IN_2_38_FOR(g_variant_parse_error_quark) 336 GQuark g_variant_parser_get_error_quark (void); 337 338 GLIB_AVAILABLE_IN_ALL 339 GQuark g_variant_parse_error_quark (void); 340 341 /** 342 * G_VARIANT_BUILDER_INIT: 343 * @variant_type: a const GVariantType* 344 * 345 * A stack-allocated #GVariantBuilder must be initialized if it is 346 * used together with g_auto() to avoid warnings or crashes if 347 * function returns before g_variant_builder_init() is called on the 348 * builder. This macro can be used as initializer instead of an 349 * explicit zeroing a variable when declaring it and a following 350 * g_variant_builder_init(), but it cannot be assigned to a variable. 351 * 352 * The passed @variant_type should be a static GVariantType to avoid 353 * lifetime issues, as copying the @variant_type does not happen in 354 * the G_VARIANT_BUILDER_INIT() call, but rather in functions that 355 * make sure that #GVariantBuilder is valid. 356 * 357 * |[ 358 * g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING); 359 * ]| 360 * 361 * Since: 2.50 362 */ 363 #define G_VARIANT_BUILDER_INIT(variant_type) { { { 2942751021u, variant_type, { 0, } } } } 364 365 GLIB_AVAILABLE_IN_ALL 366 GVariantBuilder * g_variant_builder_new (const GVariantType *type); 367 GLIB_AVAILABLE_IN_ALL 368 void g_variant_builder_unref (GVariantBuilder *builder); 369 GLIB_AVAILABLE_IN_ALL 370 GVariantBuilder * g_variant_builder_ref (GVariantBuilder *builder); 371 GLIB_AVAILABLE_IN_ALL 372 void g_variant_builder_init (GVariantBuilder *builder, 373 const GVariantType *type); 374 GLIB_AVAILABLE_IN_ALL 375 GVariant * g_variant_builder_end (GVariantBuilder *builder); 376 GLIB_AVAILABLE_IN_ALL 377 void g_variant_builder_clear (GVariantBuilder *builder); 378 GLIB_AVAILABLE_IN_ALL 379 void g_variant_builder_open (GVariantBuilder *builder, 380 const GVariantType *type); 381 GLIB_AVAILABLE_IN_ALL 382 void g_variant_builder_close (GVariantBuilder *builder); 383 GLIB_AVAILABLE_IN_ALL 384 void g_variant_builder_add_value (GVariantBuilder *builder, 385 GVariant *value); 386 GLIB_AVAILABLE_IN_ALL 387 void g_variant_builder_add (GVariantBuilder *builder, 388 const gchar *format_string, 389 ...); 390 GLIB_AVAILABLE_IN_ALL 391 void g_variant_builder_add_parsed (GVariantBuilder *builder, 392 const gchar *format, 393 ...); 394 395 GLIB_AVAILABLE_IN_ALL 396 GVariant * g_variant_new (const gchar *format_string, 397 ...); 398 GLIB_AVAILABLE_IN_ALL 399 void g_variant_get (GVariant *value, 400 const gchar *format_string, 401 ...); 402 GLIB_AVAILABLE_IN_ALL 403 GVariant * g_variant_new_va (const gchar *format_string, 404 const gchar **endptr, 405 va_list *app); 406 GLIB_AVAILABLE_IN_ALL 407 void g_variant_get_va (GVariant *value, 408 const gchar *format_string, 409 const gchar **endptr, 410 va_list *app); 411 GLIB_AVAILABLE_IN_2_34 412 gboolean g_variant_check_format_string (GVariant *value, 413 const gchar *format_string, 414 gboolean copy_only); 415 416 GLIB_AVAILABLE_IN_ALL 417 GVariant * g_variant_parse (const GVariantType *type, 418 const gchar *text, 419 const gchar *limit, 420 const gchar **endptr, 421 GError **error); 422 GLIB_AVAILABLE_IN_ALL 423 GVariant * g_variant_new_parsed (const gchar *format, 424 ...); 425 GLIB_AVAILABLE_IN_ALL 426 GVariant * g_variant_new_parsed_va (const gchar *format, 427 va_list *app); 428 429 GLIB_AVAILABLE_IN_2_40 430 gchar * g_variant_parse_error_print_context (GError *error, 431 const gchar *source_str); 432 433 GLIB_AVAILABLE_IN_ALL 434 gint g_variant_compare (gconstpointer one, 435 gconstpointer two); 436 437 typedef struct _GVariantDict GVariantDict; 438 struct _GVariantDict { 439 /*< private >*/ 440 union 441 { 442 struct { 443 GVariant *asv; 444 gsize partial_magic; 445 gsize y[14]; 446 } s; 447 gsize x[16]; 448 } u; 449 }; 450 451 /** 452 * G_VARIANT_DICT_INIT: 453 * @asv: (nullable): a GVariant* 454 * 455 * A stack-allocated #GVariantDict must be initialized if it is used 456 * together with g_auto() to avoid warnings or crashes if function 457 * returns before g_variant_dict_init() is called on the builder. 458 * This macro can be used as initializer instead of an explicit 459 * zeroing a variable when declaring it and a following 460 * g_variant_dict_init(), but it cannot be assigned to a variable. 461 * 462 * The passed @asv has to live long enough for #GVariantDict to gather 463 * the entries from, as the gathering does not happen in the 464 * G_VARIANT_DICT_INIT() call, but rather in functions that make sure 465 * that #GVariantDict is valid. In context where the initialization 466 * value has to be a constant expression, the only possible value of 467 * @asv is %NULL. It is still possible to call g_variant_dict_init() 468 * safely with a different @asv right after the variable was 469 * initialized with G_VARIANT_DICT_INIT(). 470 * 471 * |[ 472 * g_autoptr(GVariant) variant = get_asv_variant (); 473 * g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant); 474 * ]| 475 * 476 * Since: 2.50 477 */ 478 #define G_VARIANT_DICT_INIT(asv) { { { asv, 3488698669u, { 0, } } } } 479 480 GLIB_AVAILABLE_IN_2_40 481 GVariantDict * g_variant_dict_new (GVariant *from_asv); 482 483 GLIB_AVAILABLE_IN_2_40 484 void g_variant_dict_init (GVariantDict *dict, 485 GVariant *from_asv); 486 487 GLIB_AVAILABLE_IN_2_40 488 gboolean g_variant_dict_lookup (GVariantDict *dict, 489 const gchar *key, 490 const gchar *format_string, 491 ...); 492 GLIB_AVAILABLE_IN_2_40 493 GVariant * g_variant_dict_lookup_value (GVariantDict *dict, 494 const gchar *key, 495 const GVariantType *expected_type); 496 GLIB_AVAILABLE_IN_2_40 497 gboolean g_variant_dict_contains (GVariantDict *dict, 498 const gchar *key); 499 GLIB_AVAILABLE_IN_2_40 500 void g_variant_dict_insert (GVariantDict *dict, 501 const gchar *key, 502 const gchar *format_string, 503 ...); 504 GLIB_AVAILABLE_IN_2_40 505 void g_variant_dict_insert_value (GVariantDict *dict, 506 const gchar *key, 507 GVariant *value); 508 GLIB_AVAILABLE_IN_2_40 509 gboolean g_variant_dict_remove (GVariantDict *dict, 510 const gchar *key); 511 GLIB_AVAILABLE_IN_2_40 512 void g_variant_dict_clear (GVariantDict *dict); 513 GLIB_AVAILABLE_IN_2_40 514 GVariant * g_variant_dict_end (GVariantDict *dict); 515 GLIB_AVAILABLE_IN_2_40 516 GVariantDict * g_variant_dict_ref (GVariantDict *dict); 517 GLIB_AVAILABLE_IN_2_40 518 void g_variant_dict_unref (GVariantDict *dict); 519 520 G_END_DECLS 521 522 #endif /* __G_VARIANT_H__ */ 523