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