gobject/gtype.h

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General
  15  * Public License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
  20 #error "Only <glib-object.h> can be included directly."
  21 #endif
  22
  23 #ifndef __G_TYPE_H__
  24 #define __G_TYPE_H__
  25
  26 #include        <glib.h>
  27
  28 G_BEGIN_DECLS
  29
  30 /* Basic Type Macros
  31  */
  32 /**
  33  * G_TYPE_FUNDAMENTAL:
  34  * @type: A #GType value.
  35  *
  36  * The fundamental type which is the ancestor of @type.
  37  * Fundamental types are types that serve as ultimate bases for the derived types,
  38  * thus they are the roots of distinct inheritance hierarchies.
  39  */
  40 #define G_TYPE_FUNDAMENTAL(type)        (g_type_fundamental (type))
  41 /**
  42  * G_TYPE_FUNDAMENTAL_MAX:
  43  *
  44  * An integer constant that represents the number of identifiers reserved
  45  * for types that are assigned at compile-time.
  46  */
  47 #define G_TYPE_FUNDAMENTAL_MAX          (255 << G_TYPE_FUNDAMENTAL_SHIFT)
  48
  49 /* Constant fundamental types,
  50  * introduced by g_type_init().
  51  */
  52 /**
  53  * G_TYPE_INVALID:
  54  *
  55  * An invalid #GType used as error return value in some functions which return
  56  * a #GType.
  57  */
  58 #define G_TYPE_INVALID                  G_TYPE_MAKE_FUNDAMENTAL (0)
  59 /**
  60  * G_TYPE_NONE:
  61  *
  62  * A fundamental type which is used as a replacement for the C
  63  * <literal>void</literal> return type.
  64  */
  65 #define G_TYPE_NONE                     G_TYPE_MAKE_FUNDAMENTAL (1)
  66 /**
  67  * G_TYPE_INTERFACE:
  68  *
  69  * The fundamental type from which all interfaces are derived.
  70  */
  71 #define G_TYPE_INTERFACE                G_TYPE_MAKE_FUNDAMENTAL (2)
  72 /**
  73  * G_TYPE_CHAR:
  74  *
  75  * The fundamental type corresponding to #gchar.
  76  * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
  77  * This may or may not be the same type a the C type "gchar".
  78  */
  79 #define G_TYPE_CHAR                     G_TYPE_MAKE_FUNDAMENTAL (3)
  80 /**
  81  * G_TYPE_UCHAR:
  82  *
  83  * The fundamental type corresponding to #guchar.
  84  */
  85 #define G_TYPE_UCHAR                    G_TYPE_MAKE_FUNDAMENTAL (4)
  86 /**
  87  * G_TYPE_BOOLEAN:
  88  *
  89  * The fundamental type corresponding to #gboolean.
  90  */
  91 #define G_TYPE_BOOLEAN                  G_TYPE_MAKE_FUNDAMENTAL (5)
  92 /**
  93  * G_TYPE_INT:
  94  *
  95  * The fundamental type corresponding to #gint.
  96  */
  97 #define G_TYPE_INT                      G_TYPE_MAKE_FUNDAMENTAL (6)
  98 /**
  99  * G_TYPE_UINT:
 100  *
 101  * The fundamental type corresponding to #guint.
 102  */
 103 #define G_TYPE_UINT                     G_TYPE_MAKE_FUNDAMENTAL (7)
 104 /**
 105  * G_TYPE_LONG:
 106  *
 107  * The fundamental type corresponding to #glong.
 108  */
 109 #define G_TYPE_LONG                     G_TYPE_MAKE_FUNDAMENTAL (8)
 110 /**
 111  * G_TYPE_ULONG:
 112  *
 113  * The fundamental type corresponding to #gulong.
 114  */
 115 #define G_TYPE_ULONG                    G_TYPE_MAKE_FUNDAMENTAL (9)
 116 /**
 117  * G_TYPE_INT64:
 118  *
 119  * The fundamental type corresponding to #gint64.
 120  */
 121 #define G_TYPE_INT64                    G_TYPE_MAKE_FUNDAMENTAL (10)
 122 /**
 123  * G_TYPE_UINT64:
 124  *
 125  * The fundamental type corresponding to #guint64.
 126  */
 127 #define G_TYPE_UINT64                   G_TYPE_MAKE_FUNDAMENTAL (11)
 128 /**
 129  * G_TYPE_ENUM:
 130  *
 131  * The fundamental type from which all enumeration types are derived.
 132  */
 133 #define G_TYPE_ENUM                     G_TYPE_MAKE_FUNDAMENTAL (12)
 134 /**
 135  * G_TYPE_FLAGS:
 136  *
 137  * The fundamental type from which all flags types are derived.
 138  */
 139 #define G_TYPE_FLAGS                    G_TYPE_MAKE_FUNDAMENTAL (13)
 140 /**
 141  * G_TYPE_FLOAT:
 142  *
 143  * The fundamental type corresponding to #gfloat.
 144  */
 145 #define G_TYPE_FLOAT                    G_TYPE_MAKE_FUNDAMENTAL (14)
 146 /**
 147  * G_TYPE_DOUBLE:
 148  *
 149  * The fundamental type corresponding to #gdouble.
 150  */
 151 #define G_TYPE_DOUBLE                   G_TYPE_MAKE_FUNDAMENTAL (15)
 152 /**
 153  * G_TYPE_STRING:
 154  *
 155  * The fundamental type corresponding to nul-terminated C strings.
 156  */
 157 #define G_TYPE_STRING                   G_TYPE_MAKE_FUNDAMENTAL (16)
 158 /**
 159  * G_TYPE_POINTER:
 160  *
 161  * The fundamental type corresponding to #gpointer.
 162  */
 163 #define G_TYPE_POINTER                  G_TYPE_MAKE_FUNDAMENTAL (17)
 164 /**
 165  * G_TYPE_BOXED:
 166  *
 167  * The fundamental type from which all boxed types are derived.
 168  */
 169 #define G_TYPE_BOXED                    G_TYPE_MAKE_FUNDAMENTAL (18)
 170 /**
 171  * G_TYPE_PARAM:
 172  *
 173  * The fundamental type from which all #GParamSpec types are derived.
 174  */
 175 #define G_TYPE_PARAM                    G_TYPE_MAKE_FUNDAMENTAL (19)
 176 /**
 177  * G_TYPE_OBJECT:
 178  *
 179  * The fundamental type for #GObject.
 180  */
 181 #define G_TYPE_OBJECT                   G_TYPE_MAKE_FUNDAMENTAL (20)
 182 /**
 183  * G_TYPE_VARIANT:
 184  *
 185  * The fundamental type corresponding to #GVariant.
 186  *
 187  * All floating #GVariant instances passed through the #GType system are
 188  * consumed.
 189  *
 190  * Note that callbacks in closures, and signal handlers
 191  * for signals of return type %G_TYPE_VARIANT, must never return floating
 192  * variants.
 193  *
 194  * Note: GLib 2.24 did include a boxed type with this name. It was replaced
 195  * with this fundamental type in 2.26.
 196  *
 197  * Since: 2.26
 198  */
 199 #define G_TYPE_VARIANT                  G_TYPE_MAKE_FUNDAMENTAL (21)
 200
 201
 202 /* Reserved fundamental type numbers to create new fundamental
 203  * type IDs with G_TYPE_MAKE_FUNDAMENTAL().
 204  * Send email to gtk-devel-list@gnome.org for reservations.
 205  */
 206 /**
 207  * G_TYPE_FUNDAMENTAL_SHIFT:
 208  *
 209  * Shift value used in converting numbers to type IDs.
 210  */
 211 #define G_TYPE_FUNDAMENTAL_SHIFT        (2)
 212 /**
 213  * G_TYPE_MAKE_FUNDAMENTAL:
 214  * @x: the fundamental type number.
 215  *
 216  * Get the type ID for the fundamental type number @x.
 217  * Use g_type_fundamental_next() instead of this macro to create new fundamental
 218  * types.
 219  *
 220  * Returns: the GType
 221  */
 222 #define G_TYPE_MAKE_FUNDAMENTAL(x)      ((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT))
 223 /**
 224  * G_TYPE_RESERVED_GLIB_FIRST:
 225  *
 226  * First fundamental type number to create a new fundamental type id with
 227  * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
 228  */
 229 #define G_TYPE_RESERVED_GLIB_FIRST      (22)
 230 /**
 231  * G_TYPE_RESERVED_GLIB_LAST:
 232  *
 233  * Last fundamental type number reserved for GLib.
 234  */
 235 #define G_TYPE_RESERVED_GLIB_LAST       (31)
 236 /**
 237  * G_TYPE_RESERVED_BSE_FIRST:
 238  *
 239  * First fundamental type number to create a new fundamental type id with
 240  * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
 241  */
 242 #define G_TYPE_RESERVED_BSE_FIRST       (32)
 243 /**
 244  * G_TYPE_RESERVED_BSE_LAST:
 245  *
 246  * Last fundamental type number reserved for BSE.
 247  */
 248 #define G_TYPE_RESERVED_BSE_LAST        (48)
 249 /**
 250  * G_TYPE_RESERVED_USER_FIRST:
 251  *
 252  * First available fundamental type number to create new fundamental
 253  * type id with G_TYPE_MAKE_FUNDAMENTAL().
 254  */
 255 #define G_TYPE_RESERVED_USER_FIRST      (49)
 256
 257
 258 /* Type Checking Macros
 259  */
 260 /**
 261  * G_TYPE_IS_FUNDAMENTAL:
 262  * @type: A #GType value.
 263  *
 264  * Checks if @type is a fundamental type.
 265  *
 266  * Returns: %TRUE on success.
 267  */
 268 #define G_TYPE_IS_FUNDAMENTAL(type)             ((type) <= G_TYPE_FUNDAMENTAL_MAX)
 269 /**
 270  * G_TYPE_IS_DERIVED:
 271  * @type: A #GType value.
 272  *
 273  * Checks if @type is derived (or in object-oriented terminology:
 274  * inherited) from another type (this holds true for all non-fundamental
 275  * types).
 276  *
 277  * Returns: %TRUE on success.
 278  */
 279 #define G_TYPE_IS_DERIVED(type)                 ((type) > G_TYPE_FUNDAMENTAL_MAX)
 280 /**
 281  * G_TYPE_IS_INTERFACE:
 282  * @type: A #GType value.
 283  *
 284  * Checks if @type is an interface type.
 285  * An interface type provides a pure API, the implementation
 286  * of which is provided by another type (which is then said to conform
 287  * to the interface).  GLib interfaces are somewhat analogous to Java
 288  * interfaces and C++ classes containing only pure virtual functions,
 289  * with the difference that GType interfaces are not derivable (but see
 290  * g_type_interface_add_prerequisite() for an alternative).
 291  *
 292  * Returns: %TRUE on success.
 293  */
 294 #define G_TYPE_IS_INTERFACE(type)               (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)
 295 /**
 296  * G_TYPE_IS_CLASSED:
 297  * @type: A #GType value.
 298  *
 299  * Checks if @type is a classed type.
 300  *
 301  * Returns: %TRUE on success.
 302  */
 303 #define G_TYPE_IS_CLASSED(type)                 (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))
 304 /**
 305  * G_TYPE_IS_INSTANTIATABLE:
 306  * @type: A #GType value.
 307  *
 308  * Checks if @type can be instantiated.  Instantiation is the
 309  * process of creating an instance (object) of this type.
 310  *
 311  * Returns: %TRUE on success.
 312  */
 313 #define G_TYPE_IS_INSTANTIATABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))
 314 /**
 315  * G_TYPE_IS_DERIVABLE:
 316  * @type: A #GType value.
 317  *
 318  * Checks if @type is a derivable type.  A derivable type can
 319  * be used as the base class of a flat (single-level) class hierarchy.
 320  *
 321  * Returns: %TRUE on success.
 322  */
 323 #define G_TYPE_IS_DERIVABLE(type)               (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))
 324 /**
 325  * G_TYPE_IS_DEEP_DERIVABLE:
 326  * @type: A #GType value.
 327  *
 328  * Checks if @type is a deep derivable type.  A deep derivable type
 329  * can be used as the base class of a deep (multi-level) class hierarchy.
 330  *
 331  * Returns: %TRUE on success.
 332  */
 333 #define G_TYPE_IS_DEEP_DERIVABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))
 334 /**
 335  * G_TYPE_IS_ABSTRACT:
 336  * @type: A #GType value.
 337  *
 338  * Checks if @type is an abstract type.  An abstract type cannot be
 339  * instantiated and is normally used as an abstract base class for
 340  * derived classes.
 341  *
 342  * Returns: %TRUE on success.
 343  */
 344 #define G_TYPE_IS_ABSTRACT(type)                (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))
 345 /**
 346  * G_TYPE_IS_VALUE_ABSTRACT:
 347  * @type: A #GType value.
 348  *
 349  * Checks if @type is an abstract value type.  An abstract value type introduces
 350  * a value table, but can't be used for g_value_init() and is normally used as
 351  * an abstract base type for derived value types.
 352  *
 353  * Returns: %TRUE on success.
 354  */
 355 #define G_TYPE_IS_VALUE_ABSTRACT(type)          (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
 356 /**
 357  * G_TYPE_IS_VALUE_TYPE:
 358  * @type: A #GType value.
 359  *
 360  * Checks if @type is a value type and can be used with g_value_init().
 361  *
 362  * Returns: %TRUE on success.
 363  */
 364 #define G_TYPE_IS_VALUE_TYPE(type)              (g_type_check_is_value_type (type))
 365 /**
 366  * G_TYPE_HAS_VALUE_TABLE:
 367  * @type: A #GType value.
 368  *
 369  * Checks if @type has a #GTypeValueTable.
 370  *
 371  * Returns: %TRUE on success.
 372  */
 373 #define G_TYPE_HAS_VALUE_TABLE(type)            (g_type_value_table_peek (type) != NULL)
 374
 375
 376 /* Typedefs
 377  */
 378 /**
 379  * GType:
 380  *
 381  * A numerical value which represents the unique identifier of a registered
 382  * type.
 383  */
 384 #if     GLIB_SIZEOF_SIZE_T != GLIB_SIZEOF_LONG || !defined __cplusplus
 385 typedef gsize                           GType;
 386 #else   /* for historic reasons, C++ links against gulong GTypes */
 387 typedef gulong                          GType;
 388 #endif
 389 typedef struct _GValue                  GValue;
 390 typedef union  _GTypeCValue             GTypeCValue;
 391 typedef struct _GTypePlugin             GTypePlugin;
 392 typedef struct _GTypeClass              GTypeClass;
 393 typedef struct _GTypeInterface          GTypeInterface;
 394 typedef struct _GTypeInstance           GTypeInstance;
 395 typedef struct _GTypeInfo               GTypeInfo;
 396 typedef struct _GTypeFundamentalInfo    GTypeFundamentalInfo;
 397 typedef struct _GInterfaceInfo          GInterfaceInfo;
 398 typedef struct _GTypeValueTable         GTypeValueTable;
 399 typedef struct _GTypeQuery              GTypeQuery;
 400
 401
 402 /* Basic Type Structures
 403  */
 404 /**
 405  * GTypeClass:
 406  *
 407  * An opaque structure used as the base of all classes.
 408  */
 409 struct _GTypeClass
 410 {
 411   /*< private >*/
 412   GType g_type;
 413 };
 414 /**
 415  * GTypeInstance:
 416  *
 417  * An opaque structure used as the base of all type instances.
 418  */
 419 struct _GTypeInstance
 420 {
 421   /*< private >*/
 422   GTypeClass *g_class;
 423 };
 424 /**
 425  * GTypeInterface:
 426  *
 427  * An opaque structure used as the base of all interface types.
 428  */
 429 struct _GTypeInterface
 430 {
 431   /*< private >*/
 432   GType g_type;         /* iface type */
 433   GType g_instance_type;
 434 };
 435 /**
 436  * GTypeQuery:
 437  * @type: the #GType value of the type.
 438  * @type_name: the name of the type.
 439  * @class_size: the size of the class structure.
 440  * @instance_size: the size of the instance structure.
 441  *
 442  * A structure holding information for a specific type. It is
 443  * filled in by the g_type_query() function.
 444  */
 445 struct _GTypeQuery
 446 {
 447   GType         type;
 448   const gchar  *type_name;
 449   guint         class_size;
 450   guint         instance_size;
 451 };
 452
 453
 454 /* Casts, checks and accessors for structured types
 455  * usage of these macros is reserved to type implementations only
 456  */
 457 /*< protected >*/
 458 /**
 459  * G_TYPE_CHECK_INSTANCE:
 460  * @instance: Location of a #GTypeInstance structure.
 461  *
 462  * Checks if @instance is a valid #GTypeInstance structure,
 463  * otherwise issues a warning and returns %FALSE.
 464  *
 465  * This macro should only be used in type implementations.
 466  *
 467  * Returns: %TRUE on success.
 468  */
 469 #define G_TYPE_CHECK_INSTANCE(instance)                         (_G_TYPE_CHI ((GTypeInstance*) (instance)))
 470 /**
 471  * G_TYPE_CHECK_INSTANCE_CAST:
 472  * @instance: Location of a #GTypeInstance structure.
 473  * @g_type: The type to be returned.
 474  * @c_type: The corresponding C type of @g_type.
 475  *
 476  * Checks that @instance is an instance of the type identified by @g_type
 477  * and issues a warning if this is not the case. Returns @instance casted
 478  * to a pointer to @c_type.
 479  *
 480  * This macro should only be used in type implementations.
 481  */
 482 #define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type)    (_G_TYPE_CIC ((instance), (g_type), c_type))
 483 /**
 484  * G_TYPE_CHECK_INSTANCE_TYPE:
 485  * @instance: Location of a #GTypeInstance structure.
 486  * @g_type: The type to be checked
 487  *
 488  * Checks if @instance is an instance of the type identified by @g_type.
 489  *
 490  * This macro should only be used in type implementations.
 491  *
 492  * Returns: %TRUE on success.
 493  */
 494 #define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type)            (_G_TYPE_CIT ((instance), (g_type)))
 495 /**
 496  * G_TYPE_INSTANCE_GET_CLASS:
 497  * @instance: Location of the #GTypeInstance structure.
 498  * @g_type: The #GType of the class to be returned.
 499  * @c_type: The C type of the class structure.
 500  *
 501  * Get the class structure of a given @instance, casted
 502  * to a specified ancestor type @g_type of the instance.
 503  *
 504  * Note that while calling a GInstanceInitFunc(), the class pointer gets
 505  * modified, so it might not always return the expected pointer.
 506  *
 507  * This macro should only be used in type implementations.
 508  *
 509  * Returns: a pointer to the class structure
 510  */
 511 #define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type)     (_G_TYPE_IGC ((instance), (g_type), c_type))
 512 /**
 513  * G_TYPE_INSTANCE_GET_INTERFACE:
 514  * @instance: Location of the #GTypeInstance structure.
 515  * @g_type: The #GType of the interface to be returned.
 516  * @c_type: The C type of the interface structure.
 517  *
 518  * Get the interface structure for interface @g_type of a given @instance.
 519  *
 520  * This macro should only be used in type implementations.
 521  *
 522  * Returns: a pointer to the interface structure
 523  */
 524 #define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type))
 525 /**
 526  * G_TYPE_CHECK_CLASS_CAST:
 527  * @g_class: Location of a #GTypeClass structure.
 528  * @g_type: The type to be returned.
 529  * @c_type: The corresponding C type of class structure of @g_type.
 530  *
 531  * Checks that @g_class is a class structure of the type identified by @g_type
 532  * and issues a warning if this is not the case. Returns @g_class casted
 533  * to a pointer to @c_type.
 534  *
 535  * This macro should only be used in type implementations.
 536  */
 537 #define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type)        (_G_TYPE_CCC ((g_class), (g_type), c_type))
 538 /**
 539  * G_TYPE_CHECK_CLASS_TYPE:
 540  * @g_class: Location of a #GTypeClass structure.
 541  * @g_type: The type to be checked.
 542  *
 543  * Checks if @g_class is a class structure of the type identified by
 544  * @g_type.
 545  *
 546  * This macro should only be used in type implementations.
 547  *
 548  * Returns: %TRUE on success.
 549  */
 550 #define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type)                (_G_TYPE_CCT ((g_class), (g_type)))
 551 /**
 552  * G_TYPE_CHECK_VALUE:
 553  * @value: a #GValue
 554  *
 555  * Checks if @value has been initialized to hold values
 556  * of a value type.
 557  *
 558  * This macro should only be used in type implementations.
 559  *
 560  * Returns: %TRUE on success.
 561  */
 562 #define G_TYPE_CHECK_VALUE(value)                               (_G_TYPE_CHV ((value)))
 563 /**
 564  * G_TYPE_CHECK_VALUE_TYPE:
 565  * @value: a #GValue
 566  * @g_type: The type to be checked.
 567  *
 568  * Checks if @value has been initialized to hold values
 569  * of type @g_type.
 570  *
 571  * This macro should only be used in type implementations.
 572  *
 573  * Returns: %TRUE on success.
 574  */
 575 #define G_TYPE_CHECK_VALUE_TYPE(value, g_type)                  (_G_TYPE_CVH ((value), (g_type)))
 576 /**
 577  * G_TYPE_FROM_INSTANCE:
 578  * @instance: Location of a valid #GTypeInstance structure.
 579  *
 580  * Get the type identifier from a given @instance structure.
 581  *
 582  * This macro should only be used in type implementations.
 583  *
 584  * Returns: the #GType
 585  */
 586 #define G_TYPE_FROM_INSTANCE(instance)                          (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class))
 587 /**
 588  * G_TYPE_FROM_CLASS:
 589  * @g_class: Location of a valid #GTypeClass structure.
 590  *
 591  * Get the type identifier from a given @class structure.
 592  *
 593  * This macro should only be used in type implementations.
 594  *
 595  * Returns: the #GType
 596  */
 597 #define G_TYPE_FROM_CLASS(g_class)                              (((GTypeClass*) (g_class))->g_type)
 598 /**
 599  * G_TYPE_FROM_INTERFACE:
 600  * @g_iface: Location of a valid #GTypeInterface structure.
 601  *
 602  * Get the type identifier from a given @interface structure.
 603  *
 604  * This macro should only be used in type implementations.
 605  *
 606  * Returns: the #GType
 607  */
 608 #define G_TYPE_FROM_INTERFACE(g_iface)                          (((GTypeInterface*) (g_iface))->g_type)
 609
 610 /**
 611  * G_TYPE_INSTANCE_GET_PRIVATE:
 612  * @instance: the instance of a type deriving from @private_type.
 613  * @g_type: the type identifying which private data to retrieve.
 614  * @c_type: The C type for the private structure.
 615  *
 616  * Gets the private structure for a particular type.
 617  * The private structure must have been registered in the
 618  * class_init function with g_type_class_add_private().
 619  *
 620  * This macro should only be used in type implementations.
 621  *
 622  * Since: 2.4
 623  * Returns: a pointer to the private data structure.
 624  */
 625 #define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type)   ((c_type*) g_type_instance_get_private ((GTypeInstance*) (instance), (g_type)))
 626
 627 /**
 628  * G_TYPE_CLASS_GET_PRIVATE:
 629  * @klass: the class of a type deriving from @private_type.
 630  * @g_type: the type identifying which private data to retrieve.
 631  * @c_type: The C type for the private structure.
 632  *
 633  * Gets the private class structure for a particular type.
 634  * The private structure must have been registered in the
 635  * get_type() function with g_type_add_class_private().
 636  *
 637  * This macro should only be used in type implementations.
 638  *
 639  * Since: 2.24
 640  * Returns: a pointer to the private data structure.
 641  */
 642 #define G_TYPE_CLASS_GET_PRIVATE(klass, g_type, c_type)   ((c_type*) g_type_class_get_private ((GTypeClass*) (klass), (g_type)))
 643
 644 /**
 645  * GTypeDebugFlags:
 646  * @G_TYPE_DEBUG_NONE: Print no messages.
 647  * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping.
 648  * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions.
 649  * @G_TYPE_DEBUG_MASK: Mask covering all debug flags.
 650  *
 651  * The <type>GTypeDebugFlags</type> enumeration values can be passed to
 652  * g_type_init_with_debug_flags() to trigger debugging messages during runtime.
 653  * Note that the messages can also be triggered by setting the
 654  * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of
 655  * "objects" and "signals".
 656  */
 657 typedef enum    /*< skip >*/
 658 {
 659   G_TYPE_DEBUG_NONE     = 0,
 660   G_TYPE_DEBUG_OBJECTS  = 1 << 0,
 661   G_TYPE_DEBUG_SIGNALS  = 1 << 1,
 662   G_TYPE_DEBUG_MASK     = 0x03
 663 } GTypeDebugFlags;
 664
 665
 666 /* --- prototypes --- */
 667 void                  g_type_init                    (void);
 668 void                  g_type_init_with_debug_flags   (GTypeDebugFlags  debug_flags);
 669 const gchar *         g_type_name                    (GType            type);
 670 GQuark                g_type_qname                   (GType            type);
 671 GType                 g_type_from_name               (const gchar     *name);
 672 GType                 g_type_parent                  (GType            type);
 673 guint                 g_type_depth                   (GType            type);
 674 GType                 g_type_next_base               (GType            leaf_type,
 675                                                       GType            root_type);
 676 gboolean              g_type_is_a                    (GType            type,
 677                                                       GType            is_a_type);
 678 gpointer              g_type_class_ref               (GType            type);
 679 gpointer              g_type_class_peek              (GType            type);
 680 gpointer              g_type_class_peek_static       (GType            type);
 681 void                  g_type_class_unref             (gpointer         g_class);
 682 gpointer              g_type_class_peek_parent       (gpointer         g_class);
 683 gpointer              g_type_interface_peek          (gpointer         instance_class,
 684                                                       GType            iface_type);
 685 gpointer              g_type_interface_peek_parent   (gpointer         g_iface);
 686
 687 gpointer              g_type_default_interface_ref   (GType            g_type);
 688 gpointer              g_type_default_interface_peek  (GType            g_type);
 689 void                  g_type_default_interface_unref (gpointer         g_iface);
 690
 691 /* g_free() the returned arrays */
 692 GType*                g_type_children                (GType            type,
 693                                                       guint           *n_children);
 694 GType*                g_type_interfaces              (GType            type,
 695                                                       guint           *n_interfaces);
 696
 697 /* per-type _static_ data */
 698 void                  g_type_set_qdata               (GType            type,
 699                                                       GQuark           quark,
 700                                                       gpointer         data);
 701 gpointer              g_type_get_qdata               (GType            type,
 702                                                       GQuark           quark);
 703 void                  g_type_query                   (GType            type,
 704                                                       GTypeQuery      *query);
 705
 706
 707 /* --- type registration --- */
 708 /**
 709  * GBaseInitFunc:
 710  * @g_class: The #GTypeClass structure to initialize.
 711  *
 712  * A callback function used by the type system to do base initialization
 713  * of the class structures of derived types. It is called as part of the
 714  * initialization process of all derived classes and should reallocate
 715  * or reset all dynamic class members copied over from the parent class.
 716  * For example, class members (such as strings) that are not sufficiently
 717  * handled by a plain memory copy of the parent class into the derived class
 718  * have to be altered. See GClassInitFunc() for a discussion of the class
 719  * intialization process.
 720  */
 721 typedef void   (*GBaseInitFunc)              (gpointer         g_class);
 722 /**
 723  * GBaseFinalizeFunc:
 724  * @g_class: The #GTypeClass structure to finalize.
 725  *
 726  * A callback function used by the type system to finalize those portions
 727  * of a derived types class structure that were setup from the corresponding
 728  * GBaseInitFunc() function. Class finalization basically works the inverse
 729  * way in which class intialization is performed.
 730  * See GClassInitFunc() for a discussion of the class intialization process.
 731  */
 732 typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);
 733 /**
 734  * GClassInitFunc:
 735  * @g_class: The #GTypeClass structure to initialize.
 736  * @class_data: The @class_data member supplied via the #GTypeInfo structure.
 737  *
 738  * A callback function used by the type system to initialize the class
 739  * of a specific type. This function should initialize all static class
 740  * members.
 741  * The initialization process of a class involves:
 742  * <itemizedlist>
 743  * <listitem><para>
 744  *      1 - Copying common members from the parent class over to the
 745  *      derived class structure.
 746  * </para></listitem>
 747  * <listitem><para>
 748  *      2 -  Zero initialization of the remaining members not copied
 749  *      over from the parent class.
 750  * </para></listitem>
 751  * <listitem><para>
 752  *      3 - Invocation of the GBaseInitFunc() initializers of all parent
 753  *      types and the class' type.
 754  * </para></listitem>
 755  * <listitem><para>
 756  *      4 - Invocation of the class' GClassInitFunc() initializer.
 757  * </para></listitem>
 758  * </itemizedlist>
 759  * Since derived classes are partially initialized through a memory copy
 760  * of the parent class, the general rule is that GBaseInitFunc() and
 761  * GBaseFinalizeFunc() should take care of necessary reinitialization
 762  * and release of those class members that were introduced by the type
 763  * that specified these GBaseInitFunc()/GBaseFinalizeFunc().
 764  * GClassInitFunc() should only care about initializing static
 765  * class members, while dynamic class members (such as allocated strings
 766  * or reference counted resources) are better handled by a GBaseInitFunc()
 767  * for this type, so proper initialization of the dynamic class members
 768  * is performed for class initialization of derived types as well.
 769  * An example may help to correspond the intend of the different class
 770  * initializers:
 771  *
 772  * |[
 773  * typedef struct {
 774  *   GObjectClass parent_class;
 775  *   gint         static_integer;
 776  *   gchar       *dynamic_string;
 777  * } TypeAClass;
 778  * static void
 779  * type_a_base_class_init (TypeAClass *class)
 780  * {
 781  *   class->dynamic_string = g_strdup ("some string");
 782  * }
 783  * static void
 784  * type_a_base_class_finalize (TypeAClass *class)
 785  * {
 786  *   g_free (class->dynamic_string);
 787  * }
 788  * static void
 789  * type_a_class_init (TypeAClass *class)
 790  * {
 791  *   class->static_integer = 42;
 792  * }
 793  *
 794  * typedef struct {
 795  *   TypeAClass   parent_class;
 796  *   gfloat       static_float;
 797  *   GString     *dynamic_gstring;
 798  * } TypeBClass;
 799  * static void
 800  * type_b_base_class_init (TypeBClass *class)
 801  * {
 802  *   class->dynamic_gstring = g_string_new ("some other string");
 803  * }
 804  * static void
 805  * type_b_base_class_finalize (TypeBClass *class)
 806  * {
 807  *   g_string_free (class->dynamic_gstring);
 808  * }
 809  * static void
 810  * type_b_class_init (TypeBClass *class)
 811  * {
 812  *   class->static_float = 3.14159265358979323846;
 813  * }
 814  * ]|
 815  * Initialization of TypeBClass will first cause initialization of
 816  * TypeAClass (derived classes reference their parent classes, see
 817  * g_type_class_ref() on this).
 818  * Initialization of TypeAClass roughly involves zero-initializing its fields,
 819  * then calling its GBaseInitFunc() type_a_base_class_init() to allocate
 820  * its dynamic members (dynamic_string), and finally calling its GClassInitFunc()
 821  * type_a_class_init() to initialize its static members (static_integer).
 822  * The first step in the initialization process of TypeBClass is then
 823  * a plain memory copy of the contents of TypeAClass into TypeBClass and
 824  * zero-initialization of the remaining fields in TypeBClass.
 825  * The dynamic members of TypeAClass within TypeBClass now need
 826  * reinitialization which is performed by calling type_a_base_class_init()
 827  * with an argument of TypeBClass.
 828  * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init()
 829  * is called to allocate the dynamic members of TypeBClass (dynamic_gstring),
 830  * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(),
 831  * is called to complete the initialization process with the static members
 832  * (static_float).
 833  * Corresponding finalization counter parts to the GBaseInitFunc() functions
 834  * have to be provided to release allocated resources at class finalization
 835  * time.
 836  */
 837 typedef void   (*GClassInitFunc)             (gpointer         g_class,
 838                                               gpointer         class_data);
 839 /**
 840  * GClassFinalizeFunc:
 841  * @g_class: The #GTypeClass structure to finalize.
 842  * @class_data: The @class_data member supplied via the #GTypeInfo structure.
 843  *
 844  * A callback function used by the type system to finalize a class.
 845  * This function is rarely needed, as dynamically allocated class resources
 846  * should be handled by GBaseInitFunc() and GBaseFinalizeFunc().
 847  * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo
 848  * structure of a static type is invalid, because classes of static types
 849  * will never be finalized (they are artificially kept alive when their
 850  * reference count drops to zero).
 851  */
 852 typedef void   (*GClassFinalizeFunc)         (gpointer         g_class,
 853                                               gpointer         class_data);
 854 /**
 855  * GInstanceInitFunc:
 856  * @instance: The instance to initialize.
 857  * @g_class: The class of the type the instance is created for.
 858  *
 859  * A callback function used by the type system to initialize a new
 860  * instance of a type. This function initializes all instance members and
 861  * allocates any resources required by it.
 862  * Initialization of a derived instance involves calling all its parent
 863  * types instance initializers, so the class member of the instance
 864  * is altered during its initialization to always point to the class that
 865  * belongs to the type the current initializer was introduced for.
 866  */
 867 typedef void   (*GInstanceInitFunc)          (GTypeInstance   *instance,
 868                                               gpointer         g_class);
 869 /**
 870  * GInterfaceInitFunc:
 871  * @g_iface: The interface structure to initialize.
 872  * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
 873  *
 874  * A callback function used by the type system to initialize a new
 875  * interface.  This function should initialize all internal data and
 876  * allocate any resources required by the interface.
 877  */
 878 typedef void   (*GInterfaceInitFunc)         (gpointer         g_iface,
 879                                               gpointer         iface_data);
 880 /**
 881  * GInterfaceFinalizeFunc:
 882  * @g_iface: The interface structure to finalize.
 883  * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
 884  *
 885  * A callback function used by the type system to finalize an interface.
 886  * This function should destroy any internal data and release any resources
 887  * allocated by the corresponding GInterfaceInitFunc() function.
 888  */
 889 typedef void   (*GInterfaceFinalizeFunc)     (gpointer         g_iface,
 890                                               gpointer         iface_data);
 891 /**
 892  * GTypeClassCacheFunc:
 893  * @cache_data: data that was given to the g_type_add_class_cache_func() call
 894  * @g_class: The #GTypeClass structure which is unreferenced
 895  *
 896  * A callback function which is called when the reference count of a class
 897  * drops to zero. It may use g_type_class_ref() to prevent the class from
 898  * being freed. You should not call g_type_class_unref() from a
 899  * #GTypeClassCacheFunc function to prevent infinite recursion, use
 900  * g_type_class_unref_uncached() instead.
 901  *
 902  * The functions have to check the class id passed in to figure
 903  * whether they actually want to cache the class of this type, since all
 904  * classes are routed through the same #GTypeClassCacheFunc chain.
 905  *
 906  * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
 907  *  called, %FALSE to continue.
 908  */
 909 typedef gboolean (*GTypeClassCacheFunc)      (gpointer         cache_data,
 910                                               GTypeClass      *g_class);
 911 /**
 912  * GTypeInterfaceCheckFunc:
 913  * @check_data: data passed to g_type_add_interface_check().
 914  * @g_iface: the interface that has been initialized
 915  *
 916  * A callback called after an interface vtable is initialized.
 917  * See g_type_add_interface_check().
 918  *
 919  * Since: 2.4
 920  */
 921 typedef void     (*GTypeInterfaceCheckFunc)  (gpointer         check_data,
 922                                               gpointer         g_iface);
 923 /**
 924  * GTypeFundamentalFlags:
 925  * @G_TYPE_FLAG_CLASSED: Indicates a classed type.
 926  * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed).
 927  * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type.
 928  * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable).
 929  *
 930  * Bit masks used to check or determine specific characteristics of a
 931  * fundamental type.
 932  */
 933 typedef enum    /*< skip >*/
 934 {
 935   G_TYPE_FLAG_CLASSED           = (1 << 0),
 936   G_TYPE_FLAG_INSTANTIATABLE    = (1 << 1),
 937   G_TYPE_FLAG_DERIVABLE         = (1 << 2),
 938   G_TYPE_FLAG_DEEP_DERIVABLE    = (1 << 3)
 939 } GTypeFundamentalFlags;
 940 /**
 941  * GTypeFlags:
 942  * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be
 943  *  created for an abstract type.
 944  * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type
 945  *  that introduces a value table, but can't be used for
 946  *  g_value_init().
 947  *
 948  * Bit masks used to check or determine characteristics of a type.
 949  */
 950 typedef enum    /*< skip >*/
 951 {
 952   G_TYPE_FLAG_ABSTRACT          = (1 << 4),
 953   G_TYPE_FLAG_VALUE_ABSTRACT    = (1 << 5)
 954 } GTypeFlags;
 955 /**
 956  * GTypeInfo:
 957  * @class_size: Size of the class structure (required for interface, classed and instantiatable types).
 958  * @base_init: Location of the base initialization function (optional).
 959  * @base_finalize: Location of the base finalization function (optional).
 960  * @class_init: Location of the class initialization function for
 961  *  classed and instantiatable types. Location of the default vtable
 962  *  inititalization function for interface types. (optional) This function
 963  *  is used both to fill in virtual functions in the class or default vtable,
 964  *  and to do type-specific setup such as registering signals and object
 965  *  properties.
 966  * @class_finalize: Location of the class finalization function for
 967  *  classed and instantiatable types. Location fo the default vtable
 968  *  finalization function for interface types. (optional)
 969  * @class_data: User-supplied data passed to the class init/finalize functions.
 970  * @instance_size: Size of the instance (object) structure (required for instantiatable types only).
 971  * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now.
 972  * @instance_init: Location of the instance initialization function (optional, for instantiatable types only).
 973  * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only
 974  *  useful for fundamental types).
 975  *
 976  * This structure is used to provide the type system with the information
 977  * required to initialize and destruct (finalize) a type's class and
 978  * its instances.
 979  * The initialized structure is passed to the g_type_register_static() function
 980  * (or is copied into the provided #GTypeInfo structure in the
 981  * g_type_plugin_complete_type_info()). The type system will perform a deep
 982  * copy of this structure, so its memory does not need to be persistent
 983  * across invocation of g_type_register_static().
 984  */
 985 struct _GTypeInfo
 986 {
 987   /* interface types, classed types, instantiated types */
 988   guint16                class_size;
 989
 990   GBaseInitFunc          base_init;
 991   GBaseFinalizeFunc      base_finalize;
 992
 993   /* interface types, classed types, instantiated types */
 994   GClassInitFunc         class_init;
 995   GClassFinalizeFunc     class_finalize;
 996   gconstpointer          class_data;
 997
 998   /* instantiated types */
 999   guint16                instance_size;
1000   guint16                n_preallocs;
1001   GInstanceInitFunc      instance_init;
1002
1003   /* value handling */
1004   const GTypeValueTable *value_table;
1005 };
1006 /**
1007  * GTypeFundamentalInfo:
1008  * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type
1009  *
1010  * A structure that provides information to the type system which is
1011  * used specifically for managing fundamental types.
1012  */
1013 struct _GTypeFundamentalInfo
1014 {
1015   GTypeFundamentalFlags  type_flags;
1016 };
1017 /**
1018  * GInterfaceInfo:
1019  * @interface_init: location of the interface initialization function
1020  * @interface_finalize: location of the interface finalization function
1021  * @interface_data: user-supplied data passed to the interface init/finalize functions
1022  *
1023  * A structure that provides information to the type system which is
1024  * used specifically for managing interface types.
1025  */
1026 struct _GInterfaceInfo
1027 {
1028   GInterfaceInitFunc     interface_init;
1029   GInterfaceFinalizeFunc interface_finalize;
1030   gpointer               interface_data;
1031 };
1032 /**
1033  * GTypeValueTable:
1034  * @value_init: Default initialize @values contents by poking values
1035  *  directly into the value->data array. The data array of
1036  *  the #GValue passed into this function was zero-filled
1037  *  with <function>memset()</function>, so no care has to
1038  *  be taken to free any
1039  *  old contents. E.g. for the implementation of a string
1040  *  value that may never be %NULL, the implementation might
1041  *  look like:
1042  *  |[
1043  *  value->data[0].v_pointer = g_strdup ("");
1044  *  ]|
1045  * @value_free: Free any old contents that might be left in the
1046  *  data array of the passed in @value. No resources may
1047  *  remain allocated through the #GValue contents after
1048  *  this function returns. E.g. for our above string type:
1049  *  |[
1050  *  // only free strings without a specific flag for static storage
1051  *  if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
1052  *    g_free (value->data[0].v_pointer);
1053  *  ]|
1054  * @value_copy: @dest_value is a #GValue with zero-filled data section
1055  *  and @src_value is a properly setup #GValue of same or
1056  *  derived type.
1057  *  The purpose of this function is to copy the contents of
1058  *  @src_value into @dest_value in a way, that even after
1059  *  @src_value has been freed, the contents of @dest_value
1060  *  remain valid. String type example:
1061  *  |[
1062  *  dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);
1063  *  ]|
1064  * @value_peek_pointer: If the value contents fit into a pointer, such as objects
1065  *  or strings, return this pointer, so the caller can peek at
1066  *  the current contents. To extend on our above string example:
1067  *  |[
1068  *  return value->data[0].v_pointer;
1069  *  ]|
1070  * @collect_format: A string format describing how to collect the contents of
1071  *  this value bit-by-bit. Each character in the format represents
1072  *  an argument to be collected, and the characters themselves indicate
1073  *  the type of the argument. Currently supported arguments are:
1074  *  <variablelist>
1075  *  <varlistentry><term /><listitem><para>
1076  *  'i' - Integers. passed as collect_values[].v_int.
1077  *  </para></listitem></varlistentry>
1078  *  <varlistentry><term /><listitem><para>
1079  *  'l' - Longs. passed as collect_values[].v_long.
1080  *  </para></listitem></varlistentry>
1081  *  <varlistentry><term /><listitem><para>
1082  *  'd' - Doubles. passed as collect_values[].v_double.
1083  *  </para></listitem></varlistentry>
1084  *  <varlistentry><term /><listitem><para>
1085  *  'p' - Pointers. passed as collect_values[].v_pointer.
1086  *  </para></listitem></varlistentry>
1087  *  </variablelist>
1088  *  It should be noted that for variable argument list construction,
1089  *  ANSI C promotes every type smaller than an integer to an int, and
1090  *  floats to doubles. So for collection of short int or char, 'i'
1091  *  needs to be used, and for collection of floats 'd'.
1092  * @collect_value: The collect_value() function is responsible for converting the
1093  *  values collected from a variable argument list into contents
1094  *  suitable for storage in a GValue. This function should setup
1095  *  @value similar to value_init(); e.g. for a string value that
1096  *  does not allow %NULL pointers, it needs to either spew an error,
1097  *  or do an implicit conversion by storing an empty string.
1098  *  The @value passed in to this function has a zero-filled data
1099  *  array, so just like for value_init() it is guaranteed to not
1100  *  contain any old contents that might need freeing.
1101  *  @n_collect_values is exactly the string length of @collect_format,
1102  *  and @collect_values is an array of unions #GTypeCValue with
1103  *  length @n_collect_values, containing the collected values
1104  *  according to @collect_format.
1105  *  @collect_flags is an argument provided as a hint by the caller.
1106  *  It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating,
1107  *  that the collected value contents may be considered "static"
1108  *  for the duration of the @value lifetime.
1109  *  Thus an extra copy of the contents stored in @collect_values is
1110  *  not required for assignment to @value.
1111  *  For our above string example, we continue with:
1112  *  |[
1113  *  if (!collect_values[0].v_pointer)
1114  *    value->data[0].v_pointer = g_strdup ("");
1115  *  else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
1116  *  {
1117  *    value->data[0].v_pointer = collect_values[0].v_pointer;
1118  *    // keep a flag for the value_free() implementation to not free this string
1119  *    value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
1120  *  }
1121  *  else
1122  *    value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer);
1123  *  return NULL;
1124  *  ]|
1125  *  It should be noted, that it is generally a bad idea to follow the
1126  *  #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to
1127  *  reentrancy requirements and reference count assertions performed
1128  *  by the signal emission code, reference counts should always be
1129  *  incremented for reference counted contents stored in the value->data
1130  *  array.  To deviate from our string example for a moment, and taking
1131  *  a look at an exemplary implementation for collect_value() of
1132  *  #GObject:
1133  *  |[
1134  *  if (collect_values[0].v_pointer)
1135  *  {
1136  *    GObject *object = G_OBJECT (collect_values[0].v_pointer);
1137  *    // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
1138  *    value->data[0].v_pointer = g_object_ref (object);
1139  *    return NULL;
1140  *  }
1141  *  else
1142  *    return g_strdup_printf ("Object passed as invalid NULL pointer");
1143  *  }
1144  *  ]|
1145  *  The reference count for valid objects is always incremented,
1146  *  regardless of @collect_flags. For invalid objects, the example
1147  *  returns a newly allocated string without altering @value.
1148  *  Upon success, collect_value() needs to return %NULL. If, however,
1149  *  an error condition occurred, collect_value() may spew an
1150  *  error by returning a newly allocated non-%NULL string, giving
1151  *  a suitable description of the error condition.
1152  *  The calling code makes no assumptions about the @value
1153  *  contents being valid upon error returns, @value
1154  *  is simply thrown away without further freeing. As such, it is
1155  *  a good idea to not allocate #GValue contents, prior to returning
1156  *  an error, however, collect_values() is not obliged to return
1157  *  a correctly setup @value for error returns, simply because
1158  *  any non-%NULL return is considered a fatal condition so further
1159  *  program behaviour is undefined.
1160  * @lcopy_format: Format description of the arguments to collect for @lcopy_value,
1161  *  analogous to @collect_format. Usually, @lcopy_format string consists
1162  *  only of 'p's to provide lcopy_value() with pointers to storage locations.
1163  * @lcopy_value: This function is responsible for storing the @value contents into
1164  *  arguments passed through a variable argument list which got
1165  *  collected into @collect_values according to @lcopy_format.
1166  *  @n_collect_values equals the string length of @lcopy_format,
1167  *  and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS.
1168  *  In contrast to collect_value(), lcopy_value() is obliged to
1169  *  always properly support %G_VALUE_NOCOPY_CONTENTS.
1170  *  Similar to collect_value() the function may prematurely abort
1171  *  by returning a newly allocated string describing an error condition.
1172  *  To complete the string example:
1173  *  |[
1174  *  gchar **string_p = collect_values[0].v_pointer;
1175  *  if (!string_p)
1176  *    return g_strdup_printf ("string location passed as NULL");
1177  *  if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
1178  *    *string_p = value->data[0].v_pointer;
1179  *  else
1180  *    *string_p = g_strdup (value->data[0].v_pointer);
1181  *  ]|
1182  *  And an illustrative version of lcopy_value() for
1183  *  reference-counted types:
1184  *  |[
1185  *  GObject **object_p = collect_values[0].v_pointer;
1186  *  if (!object_p)
1187  *    return g_strdup_printf ("object location passed as NULL");
1188  *  if (!value->data[0].v_pointer)
1189  *    *object_p = NULL;
1190  *  else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /&ast; always honour &ast;/
1191  *    *object_p = value->data[0].v_pointer;
1192  *  else
1193  *    *object_p = g_object_ref (value->data[0].v_pointer);
1194  *  return NULL;
1195  *  ]|
1196  *
1197  * The #GTypeValueTable provides the functions required by the #GValue implementation,
1198  * to serve as a container for values of a type.
1199  */
1200
1201 struct _GTypeValueTable
1202 {
1203   void     (*value_init)         (GValue       *value);
1204   void     (*value_free)         (GValue       *value);
1205   void     (*value_copy)         (const GValue *src_value,
1206                                   GValue       *dest_value);
1207   /* varargs functionality (optional) */
1208   gpointer (*value_peek_pointer) (const GValue *value);
1209   gchar     *collect_format;
1210   gchar*   (*collect_value)      (GValue       *value,
1211                                   guint         n_collect_values,
1212                                   GTypeCValue  *collect_values,
1213                                   guint         collect_flags);
1214   gchar     *lcopy_format;
1215   gchar*   (*lcopy_value)        (const GValue *value,
1216                                   guint         n_collect_values,
1217                                   GTypeCValue  *collect_values,
1218                                   guint         collect_flags);
1219 };
1220 GType g_type_register_static            (GType                       parent_type,
1221                                          const gchar                *type_name,
1222                                          const GTypeInfo            *info,
1223                                          GTypeFlags                  flags);
1224 GType g_type_register_static_simple     (GType                       parent_type,
1225                                          const gchar                *type_name,
1226                                          guint                       class_size,
1227                                          GClassInitFunc              class_init,
1228                                          guint                       instance_size,
1229                                          GInstanceInitFunc           instance_init,
1230                                          GTypeFlags                  flags);
1231
1232 GType g_type_register_dynamic           (GType                       parent_type,
1233                                          const gchar                *type_name,
1234                                          GTypePlugin                *plugin,
1235                                          GTypeFlags                  flags);
1236 GType g_type_register_fundamental       (GType                       type_id,
1237                                          const gchar                *type_name,
1238                                          const GTypeInfo            *info,
1239                                          const GTypeFundamentalInfo *finfo,
1240                                          GTypeFlags                  flags);
1241 void  g_type_add_interface_static       (GType                       instance_type,
1242                                          GType                       interface_type,
1243                                          const GInterfaceInfo       *info);
1244 void  g_type_add_interface_dynamic      (GType                       instance_type,
1245                                          GType                       interface_type,
1246                                          GTypePlugin                *plugin);
1247 void  g_type_interface_add_prerequisite (GType                       interface_type,
1248                                          GType                       prerequisite_type);
1249 GType*g_type_interface_prerequisites    (GType                       interface_type,
1250                                          guint                      *n_prerequisites);
1251 void     g_type_class_add_private       (gpointer                    g_class,
1252                                          gsize                       private_size);
1253 gpointer g_type_instance_get_private    (GTypeInstance              *instance,
1254                                          GType                       private_type);
1255
1256 void      g_type_add_class_private      (GType                       class_type,
1257                                          gsize                       private_size);
1258 gpointer  g_type_class_get_private      (GTypeClass                 *klass,
1259                                          GType                       private_type);
1260
1261
1262 /* --- GType boilerplate --- */
1263 /**
1264  * G_DEFINE_TYPE:
1265  * @TN: The name of the new type, in Camel case.
1266  * @t_n: The name of the new type, in lowercase, with words
1267  *  separated by '_'.
1268  * @T_P: The #GType of the parent type.
1269  *
1270  * A convenience macro for type implementations, which declares a
1271  * class initialization function, an instance initialization function (see #GTypeInfo for information about
1272  * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines
1273  * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example.
1274  *
1275  * Since: 2.4
1276  */
1277 #define G_DEFINE_TYPE(TN, t_n, T_P)                         G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
1278 /**
1279  * G_DEFINE_TYPE_WITH_CODE:
1280  * @TN: The name of the new type, in Camel case.
1281  * @t_n: The name of the new type in lowercase, with words separated by '_'.
1282  * @T_P: The #GType of the parent type.
1283  * @_C_: Custom code that gets inserted in the *_get_type() function.
1284  *
1285  * A convenience macro for type implementations.
1286  * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the
1287  * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
1288  * See G_DEFINE_TYPE_EXTENDED() for an example.
1289  *
1290  * Since: 2.4
1291  */
1292 #define G_DEFINE_TYPE_WITH_CODE(TN, t_n, T_P, _C_)          _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, 0) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
1293 /**
1294  * G_DEFINE_ABSTRACT_TYPE:
1295  * @TN: The name of the new type, in Camel case.
1296  * @t_n: The name of the new type, in lowercase, with words
1297  *  separated by '_'.
1298  * @T_P: The #GType of the parent type.
1299  *
1300  * A convenience macro for type implementations.
1301  * Similar to G_DEFINE_TYPE(), but defines an abstract type.
1302  * See G_DEFINE_TYPE_EXTENDED() for an example.
1303  *
1304  * Since: 2.4
1305  */
1306 #define G_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P)                G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
1307 /**
1308  * G_DEFINE_ABSTRACT_TYPE_WITH_CODE:
1309  * @TN: The name of the new type, in Camel case.
1310  * @t_n: The name of the new type, in lowercase, with words
1311  *  separated by '_'.
1312  * @T_P: The #GType of the parent type.
1313  * @_C_: Custom code that gets inserted in the @type_name_get_type() function.
1314  *
1315  * A convenience macro for type implementations.
1316  * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to
1317  * insert custom code into the *_get_type() function, e.g. interface implementations
1318  * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example.
1319  *
1320  * Since: 2.4
1321  */
1322 #define G_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
1323 /**
1324  * G_DEFINE_TYPE_EXTENDED:
1325  * @TN: The name of the new type, in Camel case.
1326  * @t_n: The name of the new type, in lowercase, with words
1327  *    separated by '_'.
1328  * @T_P: The #GType of the parent type.
1329  * @_f_: #GTypeFlags to pass to g_type_register_static()
1330  * @_C_: Custom code that gets inserted in the *_get_type() function.
1331  *
1332  * The most general convenience macro for type implementations, on which
1333  * G_DEFINE_TYPE(), etc are based.
1334  *
1335  * |[
1336  * G_DEFINE_TYPE_EXTENDED (GtkGadget,
1337  *                         gtk_gadget,
1338  *                         GTK_TYPE_WIDGET,
1339  *                         0,
1340  *                         G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
1341  *                                                gtk_gadget_gizmo_init));
1342  * ]|
1343  * expands to
1344  * |[
1345  * static void     gtk_gadget_init       (GtkGadget      *self);
1346  * static void     gtk_gadget_class_init (GtkGadgetClass *klass);
1347  * static gpointer gtk_gadget_parent_class = NULL;
1348  * static void     gtk_gadget_class_intern_init (gpointer klass)
1349  * {
1350  *   gtk_gadget_parent_class = g_type_class_peek_parent (klass);
1351  *   gtk_gadget_class_init ((GtkGadgetClass*) klass);
1352  * }
1353  *
1354  * GType
1355  * gtk_gadget_get_type (void)
1356  * {
1357  *   static volatile gsize g_define_type_id__volatile = 0;
1358  *   if (g_once_init_enter (&g_define_type_id__volatile))
1359  *     {
1360  *       GType g_define_type_id =
1361  *         g_type_register_static_simple (GTK_TYPE_WIDGET,
1362  *                                        g_intern_static_string ("GtkGadget"),
1363  *                                        sizeof (GtkGadgetClass),
1364  *                                        (GClassInitFunc) gtk_gadget_class_intern_init,
1365  *                                        sizeof (GtkGadget),
1366  *                                        (GInstanceInitFunc) gtk_gadget_init,
1367  *                                        (GTypeFlags) flags);
1368  *       {
1369  *         const GInterfaceInfo g_implement_interface_info = {
1370  *           (GInterfaceInitFunc) gtk_gadget_gizmo_init
1371  *         };
1372  *         g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
1373  *       }
1374  *       g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
1375  *     }
1376  *   return g_define_type_id__volatile;
1377  * }
1378  * ]|
1379  * The only pieces which have to be manually provided are the definitions of
1380  * the instance and class structure and the definitions of the instance and
1381  * class init functions.
1382  *
1383  * Since: 2.4
1384  */
1385 #define G_DEFINE_TYPE_EXTENDED(TN, t_n, T_P, _f_, _C_)      _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, _f_) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
1386
1387 /**
1388  * G_DEFINE_INTERFACE:
1389  * @TN: The name of the new type, in Camel case.
1390  * @t_n: The name of the new type, in lowercase, with words separated by '_'.
1391  * @T_P: The #GType of the prerequisite type for the interface, or 0
1392  * (%G_TYPE_INVALID) for no prerequisite type.
1393  *
1394  * A convenience macro for #GTypeInterface definitions, which declares
1395  * a default vtable initialization function and defines a *_get_type()
1396  * function.
1397  *
1398  * The macro expects the interface initialization function to have the
1399  * name <literal>t_n ## _default_init</literal>, and the interface
1400  * structure to have the name <literal>TN ## Interface</literal>.
1401  *
1402  * Since: 2.24
1403  */
1404 #define G_DEFINE_INTERFACE(TN, t_n, T_P)                    G_DEFINE_INTERFACE_WITH_CODE(TN, t_n, T_P, ;)
1405
1406 /**
1407  * G_DEFINE_INTERFACE_WITH_CODE:
1408  * @TN: The name of the new type, in Camel case.
1409  * @t_n: The name of the new type, in lowercase, with words separated by '_'.
1410  * @T_P: The #GType of the prerequisite type for the interface, or 0
1411  * (%G_TYPE_INVALID) for no prerequisite type.
1412  * @_C_: Custom code that gets inserted in the *_get_type() function.
1413  *
1414  * A convenience macro for #GTypeInterface definitions. Similar to
1415  * G_DEFINE_INTERFACE(), but allows you to insert custom code into the
1416  * *_get_type() function, e.g. additional interface implementations
1417  * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See
1418  * G_DEFINE_TYPE_EXTENDED() for a similar example using
1419  * G_DEFINE_TYPE_WITH_CODE().
1420  *
1421  * Since: 2.24
1422  */
1423 #define G_DEFINE_INTERFACE_WITH_CODE(TN, t_n, T_P, _C_)     _G_DEFINE_INTERFACE_EXTENDED_BEGIN(TN, t_n, T_P) {_C_;} _G_DEFINE_INTERFACE_EXTENDED_END()
1424
1425 /**
1426  * G_IMPLEMENT_INTERFACE:
1427  * @TYPE_IFACE: The #GType of the interface to add
1428  * @iface_init: The interface init function
1429  *
1430  * A convenience macro to ease interface addition in the @_C_ section
1431  * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
1432  * See G_DEFINE_TYPE_EXTENDED() for an example.
1433  *
1434  * Note that this macro can only be used together with the G_DEFINE_TYPE_*
1435  * macros, since it depends on variable names from those macros.
1436  *
1437  * Since: 2.4
1438  */
1439 #define G_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init)       { \
1440   const GInterfaceInfo g_implement_interface_info = { \
1441     (GInterfaceInitFunc) iface_init, NULL, NULL \
1442   }; \
1443   g_type_add_interface_static (g_define_type_id, TYPE_IFACE, &g_implement_interface_info); \
1444 }
1445
1446 #define _G_DEFINE_TYPE_EXTENDED_BEGIN(TypeName, type_name, TYPE_PARENT, flags) \
1447 \
1448 static void     type_name##_init              (TypeName        *self); \
1449 static void     type_name##_class_init        (TypeName##Class *klass); \
1450 static gpointer type_name##_parent_class = NULL; \
1451 static void     type_name##_class_intern_init (gpointer klass) \
1452 { \
1453   type_name##_parent_class = g_type_class_peek_parent (klass); \
1454   type_name##_class_init ((TypeName##Class*) klass); \
1455 } \
1456 \
1457 GType \
1458 type_name##_get_type (void) \
1459 { \
1460   static volatile gsize g_define_type_id__volatile = 0; \
1461   if (g_once_init_enter (&g_define_type_id__volatile))  \
1462     { \
1463       GType g_define_type_id = \
1464         g_type_register_static_simple (TYPE_PARENT, \
1465                                        g_intern_static_string (#TypeName), \
1466                                        sizeof (TypeName##Class), \
1467                                        (GClassInitFunc) type_name##_class_intern_init, \
1468                                        sizeof (TypeName), \
1469                                        (GInstanceInitFunc) type_name##_init, \
1470                                        (GTypeFlags) flags); \
1471       { /* custom code follows */
1472 #define _G_DEFINE_TYPE_EXTENDED_END()   \
1473         /* following custom code */     \
1474       }                                 \
1475       g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); \
1476     }                                   \
1477   return g_define_type_id__volatile;    \
1478 } /* closes type_name##_get_type() */
1479
1480 #define _G_DEFINE_INTERFACE_EXTENDED_BEGIN(TypeName, type_name, TYPE_PREREQ) \
1481 \
1482 static void     type_name##_default_init        (TypeName##Interface *klass); \
1483 \
1484 GType \
1485 type_name##_get_type (void) \
1486 { \
1487   static volatile gsize g_define_type_id__volatile = 0; \
1488   if (g_once_init_enter (&g_define_type_id__volatile))  \
1489     { \
1490       GType g_define_type_id = \
1491         g_type_register_static_simple (G_TYPE_INTERFACE, \
1492                                        g_intern_static_string (#TypeName), \
1493                                        sizeof (TypeName##Interface), \
1494                                        (GClassInitFunc)type_name##_default_init, \
1495                                        0, \
1496                                        (GInstanceInitFunc)NULL, \
1497                                        (GTypeFlags) 0); \
1498       if (TYPE_PREREQ) \
1499         g_type_interface_add_prerequisite (g_define_type_id, TYPE_PREREQ); \
1500       { /* custom code follows */
1501 #define _G_DEFINE_INTERFACE_EXTENDED_END()      \
1502         /* following custom code */             \
1503       }                                         \
1504       g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); \
1505     }                                           \
1506   return g_define_type_id__volatile;                    \
1507 } /* closes type_name##_get_type() */
1508
1509 /**
1510  * G_DEFINE_BOXED_TYPE:
1511  * @TypeName: The name of the new type, in Camel case.
1512  * @type_name: The name of the new type, in lowercase, with words
1513  *  separated by '_'.
1514  * @copy_func: the #GBoxedCopyFunc for the new type
1515  * @free_func: the #GBoxedFreeFunc for the new type
1516  *
1517  * A convenience macro for boxed type implementations, which defines a
1518  * type_name_get_type() function registering the boxed type.
1519  *
1520  * Since: 2.26
1521  */
1522 #define G_DEFINE_BOXED_TYPE(TypeName, type_name, copy_func, free_func) G_DEFINE_BOXED_TYPE_WITH_CODE (TypeName, type_name, copy_func, free_func, {})
1523 /**
1524  * G_DEFINE_BOXED_TYPE_WITH_CODE:
1525  * @TypeName: The name of the new type, in Camel case.
1526  * @type_name: The name of the new type, in lowercase, with words
1527  *  separated by '_'.
1528  * @copy_func: the #GBoxedCopyFunc for the new type
1529  * @free_func: the #GBoxedFreeFunc for the new type
1530  * @_C_: Custom code that gets inserted in the *_get_type() function.
1531  *
1532  * A convenience macro for boxed type implementations.
1533  * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the
1534  * type_name_get_type() function, e.g. to register value transformations with
1535  * g_value_register_transform_func().
1536  *
1537  * Since: 2.26
1538  */
1539 #define G_DEFINE_BOXED_TYPE_WITH_CODE(TypeName, type_name, copy_func, free_func, _C_) _G_DEFINE_BOXED_TYPE_BEGIN (TypeName, type_name, copy_func, free_func) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
1540
1541 #if !defined (__cplusplus) && (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 7))
1542 #define _G_DEFINE_BOXED_TYPE_BEGIN(TypeName, type_name, copy_func, free_func) \
1543 GType \
1544 type_name##_get_type (void) \
1545 { \
1546   static volatile gsize g_define_type_id__volatile = 0; \
1547   if (g_once_init_enter (&g_define_type_id__volatile))  \
1548     { \
1549       GType (* _g_register_boxed) \
1550         (const gchar *, \
1551          union \
1552            { \
1553              TypeName * (*do_copy_type) (TypeName *); \
1554              TypeName * (*do_const_copy_type) (const TypeName *); \
1555              GBoxedCopyFunc do_copy_boxed; \
1556            } __attribute__((__transparent_union__)), \
1557          union \
1558            { \
1559              void (* do_free_type) (TypeName *); \
1560              GBoxedFreeFunc do_free_boxed; \
1561            } __attribute__((__transparent_union__)) \
1562         ) = g_boxed_type_register_static; \
1563       GType g_define_type_id = \
1564         _g_register_boxed (g_intern_static_string (#TypeName), copy_func, free_func); \
1565       { /* custom code follows */
1566 #else
1567 #define _G_DEFINE_BOXED_TYPE_BEGIN(TypeName, type_name, copy_func, free_func) \
1568 GType \
1569 type_name##_get_type (void) \
1570 { \
1571   static volatile gsize g_define_type_id__volatile = 0; \
1572   if (g_once_init_enter (&g_define_type_id__volatile))  \
1573     { \
1574       GType g_define_type_id = \
1575         g_boxed_type_register_static (g_intern_static_string (#TypeName), \
1576                                       (GBoxedCopyFunc) copy_func, \
1577                                       (GBoxedFreeFunc) free_func); \
1578       { /* custom code follows */
1579 #endif /* __GNUC__ */
1580
1581 /**
1582  * G_DEFINE_POINTER_TYPE:
1583  * @TypeName: The name of the new type, in Camel case.
1584  * @type_name: The name of the new type, in lowercase, with words
1585  *  separated by '_'.
1586  *
1587  * A convenience macro for pointer type implementations, which defines a
1588  * type_name_get_type() function registering the pointer type.
1589  *
1590  * Since: 2.26
1591  */
1592 #define G_DEFINE_POINTER_TYPE(TypeName, type_name) G_DEFINE_POINTER_TYPE_WITH_CODE (TypeName, type_name, {})
1593 /**
1594  * G_DEFINE_POINTER_TYPE_WITH_CODE:
1595  * @TypeName: The name of the new type, in Camel case.
1596  * @type_name: The name of the new type, in lowercase, with words
1597  *  separated by '_'.
1598  * @_C_: Custom code that gets inserted in the *_get_type() function.
1599  *
1600  * A convenience macro for pointer type implementations.
1601  * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the
1602  * type_name_get_type() function.
1603  *
1604  * Since: 2.26
1605  */
1606 #define G_DEFINE_POINTER_TYPE_WITH_CODE(TypeName, type_name, _C_) _G_DEFINE_POINTER_TYPE_BEGIN (TypeName, type_name) {_C_;} _G_DEFINE_TYPE_EXTENDED_END()
1607
1608 #define _G_DEFINE_POINTER_TYPE_BEGIN(TypeName, type_name) \
1609 GType \
1610 type_name##_get_type (void) \
1611 { \
1612   static volatile gsize g_define_type_id__volatile = 0; \
1613   if (g_once_init_enter (&g_define_type_id__volatile))  \
1614     { \
1615       GType g_define_type_id = \
1616         g_pointer_type_register_static (g_intern_static_string (#TypeName)); \
1617       { /* custom code follows */
1618
1619 /* --- protected (for fundamental type implementations) --- */
1620 GTypePlugin*     g_type_get_plugin              (GType               type);
1621 GTypePlugin*     g_type_interface_get_plugin    (GType               instance_type,
1622                                                  GType               interface_type);
1623 GType            g_type_fundamental_next        (void);
1624 GType            g_type_fundamental             (GType               type_id);
1625 GTypeInstance*   g_type_create_instance         (GType               type);
1626 void             g_type_free_instance           (GTypeInstance      *instance);
1627
1628 void             g_type_add_class_cache_func    (gpointer            cache_data,
1629                                                  GTypeClassCacheFunc cache_func);
1630 void             g_type_remove_class_cache_func (gpointer            cache_data,
1631                                                  GTypeClassCacheFunc cache_func);
1632 void             g_type_class_unref_uncached    (gpointer            g_class);
1633
1634 void             g_type_add_interface_check     (gpointer                check_data,
1635                                                  GTypeInterfaceCheckFunc check_func);
1636 void             g_type_remove_interface_check  (gpointer                check_data,
1637                                                  GTypeInterfaceCheckFunc check_func);
1638
1639 GTypeValueTable* g_type_value_table_peek        (GType               type);
1640
1641
1642 /*< private >*/
1643 gboolean         g_type_check_instance          (GTypeInstance      *instance) G_GNUC_PURE;
1644 GTypeInstance*   g_type_check_instance_cast     (GTypeInstance      *instance,
1645                                                  GType               iface_type);
1646 gboolean         g_type_check_instance_is_a     (GTypeInstance      *instance,
1647                                                  GType               iface_type) G_GNUC_PURE;
1648 GTypeClass*      g_type_check_class_cast        (GTypeClass         *g_class,
1649                                                  GType               is_a_type);
1650 gboolean         g_type_check_class_is_a        (GTypeClass         *g_class,
1651                                                  GType               is_a_type) G_GNUC_PURE;
1652 gboolean         g_type_check_is_value_type     (GType               type) G_GNUC_CONST;
1653 gboolean         g_type_check_value             (GValue             *value) G_GNUC_PURE;
1654 gboolean         g_type_check_value_holds       (GValue             *value,
1655                                                  GType               type) G_GNUC_PURE;
1656 gboolean         g_type_test_flags              (GType               type,
1657                                                  guint               flags) G_GNUC_CONST;
1658
1659
1660 /* --- debugging functions --- */
1661 const gchar *    g_type_name_from_instance      (GTypeInstance  *instance);
1662 const gchar *    g_type_name_from_class         (GTypeClass     *g_class);
1663
1664
1665 /* --- implementation bits --- */
1666 #ifndef G_DISABLE_CAST_CHECKS
1667 #  define _G_TYPE_CIC(ip, gt, ct) \
1668     ((ct*) g_type_check_instance_cast ((GTypeInstance*) ip, gt))
1669 #  define _G_TYPE_CCC(cp, gt, ct) \
1670     ((ct*) g_type_check_class_cast ((GTypeClass*) cp, gt))
1671 #else /* G_DISABLE_CAST_CHECKS */
1672 #  define _G_TYPE_CIC(ip, gt, ct)       ((ct*) ip)
1673 #  define _G_TYPE_CCC(cp, gt, ct)       ((ct*) cp)
1674 #endif /* G_DISABLE_CAST_CHECKS */
1675 #define _G_TYPE_CHI(ip)                 (g_type_check_instance ((GTypeInstance*) ip))
1676 #define _G_TYPE_CHV(vl)                 (g_type_check_value ((GValue*) vl))
1677 #define _G_TYPE_IGC(ip, gt, ct)         ((ct*) (((GTypeInstance*) ip)->g_class))
1678 #define _G_TYPE_IGI(ip, gt, ct)         ((ct*) g_type_interface_peek (((GTypeInstance*) ip)->g_class, gt))
1679 #ifdef  __GNUC__
1680 #  define _G_TYPE_CIT(ip, gt)             (G_GNUC_EXTENSION ({ \
1681   GTypeInstance *__inst = (GTypeInstance*) ip; GType __t = gt; gboolean __r; \
1682   if (!__inst) \
1683     __r = FALSE; \
1684   else if (__inst->g_class && __inst->g_class->g_type == __t) \
1685     __r = TRUE; \
1686   else \
1687     __r = g_type_check_instance_is_a (__inst, __t); \
1688   __r; \
1689 }))
1690 #  define _G_TYPE_CCT(cp, gt)             (G_GNUC_EXTENSION ({ \
1691   GTypeClass *__class = (GTypeClass*) cp; GType __t = gt; gboolean __r; \
1692   if (!__class) \
1693     __r = FALSE; \
1694   else if (__class->g_type == __t) \
1695     __r = TRUE; \
1696   else \
1697     __r = g_type_check_class_is_a (__class, __t); \
1698   __r; \
1699 }))
1700 #  define _G_TYPE_CVH(vl, gt)             (G_GNUC_EXTENSION ({ \
1701   GValue *__val = (GValue*) vl; GType __t = gt; gboolean __r; \
1702   if (!__val) \
1703     __r = FALSE; \
1704   else if (__val->g_type == __t)                \
1705     __r = TRUE; \
1706   else \
1707     __r = g_type_check_value_holds (__val, __t); \
1708   __r; \
1709 }))
1710 #else  /* !__GNUC__ */
1711 #  define _G_TYPE_CIT(ip, gt)             (g_type_check_instance_is_a ((GTypeInstance*) ip, gt))
1712 #  define _G_TYPE_CCT(cp, gt)             (g_type_check_class_is_a ((GTypeClass*) cp, gt))
1713 #  define _G_TYPE_CVH(vl, gt)             (g_type_check_value_holds ((GValue*) vl, gt))
1714 #endif /* !__GNUC__ */
1715 /**
1716  * G_TYPE_FLAG_RESERVED_ID_BIT:
1717  *
1718  * A bit in the type number that's supposed to be left untouched.
1719  */
1720 #define G_TYPE_FLAG_RESERVED_ID_BIT     ((GType) (1 << 0))
1721 extern GTypeDebugFlags                  _g_type_debug_flags;
1722
1723 G_END_DECLS
1724
1725 #endif /* __G_TYPE_H__ */