glib-2.0/glib/gvarianttype.h

0001 /*
0002  * Copyright © 2007, 2008 Ryan Lortie
0003  * Copyright © 2009, 2010 Codethink Limited
0004  *
0005  * SPDX-License-Identifier: LGPL-2.1-or-later
0006  *
0007  * This library is free software; you can redistribute it and/or
0008  * modify it under the terms of the GNU Lesser General Public
0009  * License as published by the Free Software Foundation; either
0010  * version 2.1 of the License, or (at your option) any later version.
0011  *
0012  * This library is distributed in the hope that it will be useful,
0013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015  * Lesser General Public License for more details.
0016  *
0017  * You should have received a copy of the GNU Lesser General Public
0018  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
0019  *
0020  * Author: Ryan Lortie <desrt@desrt.ca>
0021  */
0022
0023 #ifndef __G_VARIANT_TYPE_H__
0024 #define __G_VARIANT_TYPE_H__
0025
0026 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0027 #error "Only <glib.h> can be included directly."
0028 #endif
0029
0030 #include <glib/gtypes.h>
0031
0032 G_BEGIN_DECLS
0033
0034 typedef struct _GVariantType GVariantType;
0035
0036 /**
0037  * G_VARIANT_TYPE_BOOLEAN:
0038  *
0039  * The type of a value that can be either true or false.
0040  **/
0041 #define G_VARIANT_TYPE_BOOLEAN              ((const GVariantType *) "b")
0042
0043 /**
0044  * G_VARIANT_TYPE_BYTE:
0045  *
0046  * The type of an integer value that can range from 0 to 255.
0047  **/
0048 #define G_VARIANT_TYPE_BYTE                 ((const GVariantType *) "y")
0049
0050 /**
0051  * G_VARIANT_TYPE_INT16:
0052  *
0053  * The type of an integer value that can range from -32768 to 32767.
0054  **/
0055 #define G_VARIANT_TYPE_INT16                ((const GVariantType *) "n")
0056
0057 /**
0058  * G_VARIANT_TYPE_UINT16:
0059  *
0060  * The type of an integer value that can range from 0 to 65535.
0061  *
0062  * There were about this many people living in Toronto in the 1870s.
0063  **/
0064 #define G_VARIANT_TYPE_UINT16               ((const GVariantType *) "q")
0065
0066 /**
0067  * G_VARIANT_TYPE_INT32:
0068  *
0069  * The type of an integer value that can range from -2147483648 to
0070  * 2147483647.
0071  **/
0072 #define G_VARIANT_TYPE_INT32                ((const GVariantType *) "i")
0073
0074 /**
0075  * G_VARIANT_TYPE_UINT32:
0076  *
0077  * The type of an integer value that can range from 0 to 4294967295.
0078  *
0079  * That’s one number for everyone who was around in the late 1970s.
0080  **/
0081 #define G_VARIANT_TYPE_UINT32               ((const GVariantType *) "u")
0082
0083 /**
0084  * G_VARIANT_TYPE_INT64:
0085  *
0086  * The type of an integer value that can range from
0087  * -9223372036854775808 to 9223372036854775807.
0088  **/
0089 #define G_VARIANT_TYPE_INT64                ((const GVariantType *) "x")
0090
0091 /**
0092  * G_VARIANT_TYPE_UINT64:
0093  *
0094  * The type of an integer value that can range from 0
0095  * to 18446744073709551615 (inclusive).
0096  *
0097  * That’s a really big number, but a Rubik’s cube can have a bit more than
0098  * twice as many possible positions.
0099  **/
0100 #define G_VARIANT_TYPE_UINT64               ((const GVariantType *) "t")
0101
0102 /**
0103  * G_VARIANT_TYPE_DOUBLE:
0104  *
0105  * The type of a double precision
0106  * [IEEE 754 floating point number](https://en.wikipedia.org/wiki/IEEE_754).
0107  *
0108  * These go up to about 1.80e308 (plus and minus) but miss out on
0109  * some numbers in between.  In any case, that’s far greater than the
0110  * estimated number of fundamental particles in the observable
0111  * universe.
0112  **/
0113 #define G_VARIANT_TYPE_DOUBLE               ((const GVariantType *) "d")
0114
0115 /**
0116  * G_VARIANT_TYPE_STRING:
0117  *
0118  * The type of a string.
0119  *
0120  * `""` is a string.  `NULL` is not a string.
0121  **/
0122 #define G_VARIANT_TYPE_STRING               ((const GVariantType *) "s")
0123
0124 /**
0125  * G_VARIANT_TYPE_OBJECT_PATH:
0126  *
0127  * The type of a
0128  * [D-Bus object path](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path).
0129  *
0130  * These are strings of a specific format used to identify objects at a given
0131  * destination on the bus.
0132  *
0133  * If you are not interacting with D-Bus, then there is no reason to make
0134  * use of this type.  If you are, then the D-Bus specification contains a
0135  * [precise description of valid object paths](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path).
0136  **/
0137 #define G_VARIANT_TYPE_OBJECT_PATH          ((const GVariantType *) "o")
0138
0139 /**
0140  * G_VARIANT_TYPE_SIGNATURE:
0141  *
0142  * The type of a
0143  * [D-Bus type signature](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system).
0144  *
0145  * These are strings of a specific format used as type signatures for D-Bus
0146  * methods and messages.
0147  *
0148  * If you are not interacting with D-Bus, then there is no reason to make
0149  * use of this type.  If you are, then the D-Bus specification contains a
0150  * [precise description of valid signature strings](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system).
0151  **/
0152 #define G_VARIANT_TYPE_SIGNATURE            ((const GVariantType *) "g")
0153
0154 /**
0155  * G_VARIANT_TYPE_VARIANT:
0156  *
0157  * The type of a box that contains any other value (including another
0158  * variant).
0159  **/
0160 #define G_VARIANT_TYPE_VARIANT              ((const GVariantType *) "v")
0161
0162 /**
0163  * G_VARIANT_TYPE_HANDLE:
0164  *
0165  * The type of a 32-bit signed integer value, that by convention, is used
0166  * as an index into an array of file descriptors that are sent alongside
0167  * a D-Bus message.
0168  *
0169  * If you are not interacting with D-Bus, then there is no reason to make
0170  * use of this type.
0171  **/
0172 #define G_VARIANT_TYPE_HANDLE               ((const GVariantType *) "h")
0173
0174 /**
0175  * G_VARIANT_TYPE_UNIT:
0176  *
0177  * The empty tuple type.
0178  *
0179  * Has only one instance.  Known also as ‘triv’ or ‘void’.
0180  **/
0181 #define G_VARIANT_TYPE_UNIT                 ((const GVariantType *) "()")
0182
0183 /**
0184  * G_VARIANT_TYPE_ANY:
0185  *
0186  * An indefinite type that is a supertype of every type (including
0187  * itself).
0188  **/
0189 #define G_VARIANT_TYPE_ANY                  ((const GVariantType *) "*")
0190
0191 /**
0192  * G_VARIANT_TYPE_BASIC:
0193  *
0194  * An indefinite type that is a supertype of every basic (ie:
0195  * non-container) type.
0196  **/
0197 #define G_VARIANT_TYPE_BASIC                ((const GVariantType *) "?")
0198
0199 /**
0200  * G_VARIANT_TYPE_MAYBE:
0201  *
0202  * An indefinite type that is a supertype of every ‘maybe’ type.
0203  **/
0204 #define G_VARIANT_TYPE_MAYBE                ((const GVariantType *) "m*")
0205
0206 /**
0207  * G_VARIANT_TYPE_ARRAY:
0208  *
0209  * An indefinite type that is a supertype of every array type.
0210  **/
0211 #define G_VARIANT_TYPE_ARRAY                ((const GVariantType *) "a*")
0212
0213 /**
0214  * G_VARIANT_TYPE_TUPLE:
0215  *
0216  * An indefinite type that is a supertype of every tuple type,
0217  * regardless of the number of items in the tuple.
0218  **/
0219 #define G_VARIANT_TYPE_TUPLE                ((const GVariantType *) "r")
0220
0221 /**
0222  * G_VARIANT_TYPE_DICT_ENTRY:
0223  *
0224  * An indefinite type that is a supertype of every dictionary entry
0225  * type.
0226  **/
0227 #define G_VARIANT_TYPE_DICT_ENTRY           ((const GVariantType *) "{?*}")
0228
0229 /**
0230  * G_VARIANT_TYPE_DICTIONARY:
0231  *
0232  * An indefinite type that is a supertype of every dictionary type —
0233  * that is, any array type that has an element type equal to any
0234  * dictionary entry type.
0235  **/
0236 #define G_VARIANT_TYPE_DICTIONARY           ((const GVariantType *) "a{?*}")
0237
0238 /**
0239  * G_VARIANT_TYPE_STRING_ARRAY:
0240  *
0241  * The type of an array of strings.
0242  **/
0243 #define G_VARIANT_TYPE_STRING_ARRAY         ((const GVariantType *) "as")
0244
0245 /**
0246  * G_VARIANT_TYPE_OBJECT_PATH_ARRAY:
0247  *
0248  * The type of an array of object paths.
0249  **/
0250 #define G_VARIANT_TYPE_OBJECT_PATH_ARRAY    ((const GVariantType *) "ao")
0251
0252 /**
0253  * G_VARIANT_TYPE_BYTESTRING:
0254  *
0255  * The type of an array of bytes.
0256  *
0257  * This type is commonly used to pass around strings that may not be valid
0258  * UTF-8, such as file system paths.  In that case, the
0259  * convention is that the nul terminator character should be included as
0260  * the last character in the array.
0261  **/
0262 #define G_VARIANT_TYPE_BYTESTRING           ((const GVariantType *) "ay")
0263
0264 /**
0265  * G_VARIANT_TYPE_BYTESTRING_ARRAY:
0266  *
0267  * The type of an array of byte strings (an array of arrays of bytes).
0268  **/
0269 #define G_VARIANT_TYPE_BYTESTRING_ARRAY     ((const GVariantType *) "aay")
0270
0271 /**
0272  * G_VARIANT_TYPE_VARDICT:
0273  *
0274  * The type of a dictionary mapping strings to variants (the ubiquitous
0275  * `a{sv}` type).
0276  *
0277  * Since: 2.30
0278  **/
0279 #define G_VARIANT_TYPE_VARDICT              ((const GVariantType *) "a{sv}")
0280
0281
0282 /**
0283  * G_VARIANT_TYPE:
0284  * @type_string: a well-formed [type@GLib.VariantType] type string
0285  *
0286  * Converts a string to a const [type@GLib.VariantType].
0287  *
0288  * Depending on the current debugging level, this function may perform a runtime
0289  * check to ensure that @string is a valid [type@GLib.Variant] type string.
0290  *
0291  * It is always a programmer error to use this macro with an invalid
0292  * type string. If in doubt, use [func@GLib.variant_type_string_is_valid] to
0293  * check if the string is valid.
0294  *
0295  * Since 2.24
0296  **/
0297 #ifndef G_DISABLE_CAST_CHECKS
0298 # define G_VARIANT_TYPE(type_string)            (g_variant_type_checked_ ((type_string)))
0299 #else
0300 # define G_VARIANT_TYPE(type_string)            ((const GVariantType *) (type_string))
0301 #endif
0302
0303 /* type string checking */
0304 GLIB_AVAILABLE_IN_ALL
0305 gboolean                        g_variant_type_string_is_valid          (const gchar         *type_string) G_GNUC_CONST;
0306 GLIB_AVAILABLE_IN_ALL
0307 gboolean                        g_variant_type_string_scan              (const gchar         *string,
0308                                                                          const gchar         *limit,
0309                                                                          const gchar        **endptr);
0310
0311 /* create/destroy */
0312 GLIB_AVAILABLE_IN_ALL
0313 void                            g_variant_type_free                     (GVariantType        *type);
0314 GLIB_AVAILABLE_IN_ALL
0315 GVariantType *                  g_variant_type_copy                     (const GVariantType  *type);
0316 GLIB_AVAILABLE_IN_ALL
0317 GVariantType *                  g_variant_type_new                      (const gchar         *type_string);
0318
0319 /* getters */
0320 GLIB_AVAILABLE_IN_ALL
0321 gsize                           g_variant_type_get_string_length        (const GVariantType  *type);
0322 GLIB_AVAILABLE_IN_ALL
0323 const gchar *                   g_variant_type_peek_string              (const GVariantType  *type);
0324 GLIB_AVAILABLE_IN_ALL
0325 gchar *                         g_variant_type_dup_string               (const GVariantType  *type);
0326
0327 /* classification */
0328 GLIB_AVAILABLE_IN_ALL
0329 gboolean                        g_variant_type_is_definite              (const GVariantType  *type) G_GNUC_CONST;
0330 GLIB_AVAILABLE_IN_ALL
0331 gboolean                        g_variant_type_is_container             (const GVariantType  *type) G_GNUC_CONST;
0332 GLIB_AVAILABLE_IN_ALL
0333 gboolean                        g_variant_type_is_basic                 (const GVariantType  *type) G_GNUC_CONST;
0334 GLIB_AVAILABLE_IN_ALL
0335 gboolean                        g_variant_type_is_maybe                 (const GVariantType  *type) G_GNUC_CONST;
0336 GLIB_AVAILABLE_IN_ALL
0337 gboolean                        g_variant_type_is_array                 (const GVariantType  *type) G_GNUC_CONST;
0338 GLIB_AVAILABLE_IN_ALL
0339 gboolean                        g_variant_type_is_tuple                 (const GVariantType  *type) G_GNUC_CONST;
0340 GLIB_AVAILABLE_IN_ALL
0341 gboolean                        g_variant_type_is_dict_entry            (const GVariantType  *type) G_GNUC_CONST;
0342 GLIB_AVAILABLE_IN_ALL
0343 gboolean                        g_variant_type_is_variant               (const GVariantType  *type) G_GNUC_CONST;
0344
0345 /* for hash tables */
0346 GLIB_AVAILABLE_IN_ALL
0347 guint                           g_variant_type_hash                     (gconstpointer        type);
0348 GLIB_AVAILABLE_IN_ALL
0349 gboolean                        g_variant_type_equal                    (gconstpointer        type1,
0350                                                                          gconstpointer        type2);
0351
0352 /* subtypes */
0353 GLIB_AVAILABLE_IN_ALL
0354 gboolean                        g_variant_type_is_subtype_of            (const GVariantType  *type,
0355                                                                          const GVariantType  *supertype) G_GNUC_CONST;
0356
0357 /* type iterator interface */
0358 GLIB_AVAILABLE_IN_ALL
0359 const GVariantType *            g_variant_type_element                  (const GVariantType  *type) G_GNUC_CONST;
0360 GLIB_AVAILABLE_IN_ALL
0361 const GVariantType *            g_variant_type_first                    (const GVariantType  *type) G_GNUC_CONST;
0362 GLIB_AVAILABLE_IN_ALL
0363 const GVariantType *            g_variant_type_next                     (const GVariantType  *type) G_GNUC_CONST;
0364 GLIB_AVAILABLE_IN_ALL
0365 gsize                           g_variant_type_n_items                  (const GVariantType  *type) G_GNUC_CONST;
0366 GLIB_AVAILABLE_IN_ALL
0367 const GVariantType *            g_variant_type_key                      (const GVariantType  *type) G_GNUC_CONST;
0368 GLIB_AVAILABLE_IN_ALL
0369 const GVariantType *            g_variant_type_value                    (const GVariantType  *type) G_GNUC_CONST;
0370
0371 /* constructors */
0372 GLIB_AVAILABLE_IN_ALL
0373 GVariantType *                  g_variant_type_new_array                (const GVariantType  *element);
0374 GLIB_AVAILABLE_IN_ALL
0375 GVariantType *                  g_variant_type_new_maybe                (const GVariantType  *element);
0376 GLIB_AVAILABLE_IN_ALL
0377 GVariantType *                  g_variant_type_new_tuple                (const GVariantType * const *items,
0378                                                                          gint                 length);
0379 GLIB_AVAILABLE_IN_ALL
0380 GVariantType *                  g_variant_type_new_dict_entry           (const GVariantType  *key,
0381                                                                          const GVariantType  *value);
0382
0383 /*< private >*/
0384 GLIB_AVAILABLE_IN_ALL
0385 const GVariantType *            g_variant_type_checked_                 (const gchar *type_string);
0386 GLIB_AVAILABLE_IN_2_60
0387 gsize                           g_variant_type_string_get_depth_        (const gchar *type_string);
0388
0389 G_END_DECLS
0390
0391 #endif /* __G_VARIANT_TYPE_H__ */