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