1 /* GObject - GLib Type, Object, Parameter and Signal Library

     2  * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.

     3  * Portions copyright (c) 2006-2009 Nokia Corporation.  All rights reserved.

     4  *

     5  * This library is free software; you can redistribute it and/or

     6  * modify it under the terms of the GNU Lesser General Public

     7  * License as published by the Free Software Foundation; either

     8  * version 2 of the License, or (at your option) any later version.

     9  *

    10  * This library is distributed in the hope that it will be useful,

    11  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    13  * Lesser General Public License for more details.

    14  *

    15  * You should have received a copy of the GNU Lesser General

    16  * Public License along with this library; if not, write to the

    17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,

    18  * Boston, MA 02111-1307, USA.

    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 #ifndef __G_TYPE_H__

    25 #define __G_TYPE_H__

    26 

    27 #include        <glib.h>

    28 

    29 G_BEGIN_DECLS

    30 

    31 /* Basic Type Macros

    32  */

    33 /**

    34  * G_TYPE_FUNDAMENTAL:

    35  * @type: A #GType value.

    36  * 

    37  * The fundamental type which is the ancestor of @type.

    38  * Fundamental types are types that serve as ultimate bases for the derived types, 

    39  * thus they are the roots of distinct inheritance hierarchies.

    40  */

    41 #define G_TYPE_FUNDAMENTAL(type)	(g_type_fundamental (type))

    42 /**

    43  * G_TYPE_FUNDAMENTAL_MAX:

    44  * 

    45  * An integer constant that represents the number of identifiers reserved

    46  * for types that are assigned at compile-time.

    47  */

    48 #define	G_TYPE_FUNDAMENTAL_MAX		(255 << G_TYPE_FUNDAMENTAL_SHIFT)

    49 

    50 /* Constant fundamental types,

    51  * introduced by g_type_init().

    52  */

    53 /**

    54  * G_TYPE_INVALID:

    55  * 

    56  * An invalid #GType used as error return value in some functions which return

    57  * a #GType. 

    58  */

    59 #define G_TYPE_INVALID			G_TYPE_MAKE_FUNDAMENTAL (0)

    60 /**

    61  * G_TYPE_NONE:

    62  * 

    63  * A fundamental type which is used as a replacement for the C

    64  * <literal>void</literal> return type.

    65  */

    66 #define G_TYPE_NONE			G_TYPE_MAKE_FUNDAMENTAL (1)

    67 /**

    68  * G_TYPE_INTERFACE:

    69  * 

    70  * The fundamental type from which all interfaces are derived.

    71  */

    72 #define G_TYPE_INTERFACE		G_TYPE_MAKE_FUNDAMENTAL (2)

    73 /**

    74  * G_TYPE_CHAR:

    75  * 

    76  * The fundamental type corresponding to #gchar.

    77  * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.

    78  * This may or may not be the same type a the C type "gchar".

    79  */

    80 #define G_TYPE_CHAR			G_TYPE_MAKE_FUNDAMENTAL (3)

    81 /**

    82  * G_TYPE_UCHAR:

    83  * 

    84  * The fundamental type corresponding to #guchar.

    85  */

    86 #define G_TYPE_UCHAR			G_TYPE_MAKE_FUNDAMENTAL (4)

    87 /**

    88  * G_TYPE_BOOLEAN:

    89  * 

    90  * The fundamental type corresponding to #gboolean.

    91  */

    92 #define G_TYPE_BOOLEAN			G_TYPE_MAKE_FUNDAMENTAL (5)

    93 /**

    94  * G_TYPE_INT:

    95  * 

    96  * The fundamental type corresponding to #gint.

    97  */

    98 #define G_TYPE_INT			G_TYPE_MAKE_FUNDAMENTAL (6)

    99 /**

   100  * G_TYPE_UINT:

   101  * 

   102  * The fundamental type corresponding to #guint.

   103  */

   104 #define G_TYPE_UINT			G_TYPE_MAKE_FUNDAMENTAL (7)

   105 /**

   106  * G_TYPE_LONG:

   107  * 

   108  * The fundamental type corresponding to #glong.

   109  */

   110 #define G_TYPE_LONG			G_TYPE_MAKE_FUNDAMENTAL (8)

   111 /**

   112  * G_TYPE_ULONG:

   113  * 

   114  * The fundamental type corresponding to #gulong.

   115  */

   116 #define G_TYPE_ULONG			G_TYPE_MAKE_FUNDAMENTAL (9)

   117 /**

   118  * G_TYPE_INT64:

   119  * 

   120  * The fundamental type corresponding to #gint64.

   121  */

   122 #define G_TYPE_INT64			G_TYPE_MAKE_FUNDAMENTAL (10)

   123 /**

   124  * G_TYPE_UINT64:

   125  * 

   126  * The fundamental type corresponding to #guint64.

   127  */

   128 #define G_TYPE_UINT64			G_TYPE_MAKE_FUNDAMENTAL (11)

   129 /**

   130  * G_TYPE_ENUM:

   131  * 

   132  * The fundamental type from which all enumeration types are derived.

   133  */

   134 #define G_TYPE_ENUM			G_TYPE_MAKE_FUNDAMENTAL (12)

   135 /**

   136  * G_TYPE_FLAGS:

   137  * 

   138  * The fundamental type from which all flags types are derived.

   139  */

   140 #define G_TYPE_FLAGS			G_TYPE_MAKE_FUNDAMENTAL (13)

   141 /**

   142  * G_TYPE_FLOAT:

   143  * 

   144  * The fundamental type corresponding to #gfloat.

   145  */

   146 #define G_TYPE_FLOAT			G_TYPE_MAKE_FUNDAMENTAL (14)

   147 /**

   148  * G_TYPE_DOUBLE:

   149  * 

   150  * The fundamental type corresponding to #gdouble.

   151  */

   152 #define G_TYPE_DOUBLE			G_TYPE_MAKE_FUNDAMENTAL (15)

   153 /**

   154  * G_TYPE_STRING:

   155  * 

   156  * The fundamental type corresponding to nul-terminated C strings.

   157  */

   158 #define G_TYPE_STRING			G_TYPE_MAKE_FUNDAMENTAL (16)

   159 /**

   160  * G_TYPE_POINTER:

   161  * 

   162  * The fundamental type corresponding to #gpointer.

   163  */

   164 #define G_TYPE_POINTER			G_TYPE_MAKE_FUNDAMENTAL (17)

   165 /**

   166  * G_TYPE_BOXED:

   167  * 

   168  * The fundamental type from which all boxed types are derived.

   169  */

   170 #define G_TYPE_BOXED			G_TYPE_MAKE_FUNDAMENTAL (18)

   171 /**

   172  * G_TYPE_PARAM:

   173  * 

   174  * The fundamental type from which all #GParamSpec types are derived.

   175  */

   176 #define G_TYPE_PARAM			G_TYPE_MAKE_FUNDAMENTAL (19)

   177 /**

   178  * G_TYPE_OBJECT:

   179  * 

   180  * The fundamental type for #GObject.

   181  */

   182 #define G_TYPE_OBJECT			G_TYPE_MAKE_FUNDAMENTAL (20)

   183 

   184 

   185 /* Reserved fundamental type numbers to create new fundamental

   186  * type IDs with G_TYPE_MAKE_FUNDAMENTAL().

   187  * Send email to gtk-devel-list@gnome.org for reservations.

   188  */

   189 /**

   190  * G_TYPE_FUNDAMENTAL_SHIFT:

   191  *

   192  * Shift value used in converting numbers to type IDs.

   193  */

   194 #define	G_TYPE_FUNDAMENTAL_SHIFT	(2)

   195 /**

   196  * G_TYPE_MAKE_FUNDAMENTAL:

   197  * @x: the fundamental type number.

   198  * 

   199  * Get the type ID for the fundamental type number @x.

   200  * Use g_type_fundamental_next() instead of this macro to create new fundamental 

   201  * types.

   202  *

   203  * Returns: the GType

   204  */

   205 #define	G_TYPE_MAKE_FUNDAMENTAL(x)	((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT))

   206 /**

   207  * G_TYPE_RESERVED_GLIB_FIRST:

   208  * 

   209  * First fundamental type number to create a new fundamental type id with

   210  * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.

   211  */

   212 #define G_TYPE_RESERVED_GLIB_FIRST	(21)

   213 /**

   214  * G_TYPE_RESERVED_GLIB_LAST:

   215  * 

   216  * Last fundamental type number reserved for GLib.

   217  */

   218 #define G_TYPE_RESERVED_GLIB_LAST	(31)

   219 /**

   220  * G_TYPE_RESERVED_BSE_FIRST:

   221  * 

   222  * First fundamental type number to create a new fundamental type id with

   223  * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.

   224  */

   225 #define G_TYPE_RESERVED_BSE_FIRST	(32)

   226 /**

   227  * G_TYPE_RESERVED_BSE_LAST:

   228  * 

   229  * Last fundamental type number reserved for BSE.

   230  */

   231 #define G_TYPE_RESERVED_BSE_LAST	(48)

   232 /**

   233  * G_TYPE_RESERVED_USER_FIRST:

   234  * 

   235  * First available fundamental type number to create new fundamental 

   236  * type id with G_TYPE_MAKE_FUNDAMENTAL().

   237  */

   238 #define G_TYPE_RESERVED_USER_FIRST	(49)

   239 

   240 

   241 /* Type Checking Macros

   242  */

   243 /**

   244  * G_TYPE_IS_FUNDAMENTAL:

   245  * @type: A #GType value.

   246  * 

   247  * Checks if @type is a fundamental type.

   248  *

   249  * Returns: %TRUE on success.

   250  */

   251 #define G_TYPE_IS_FUNDAMENTAL(type)             ((type) <= G_TYPE_FUNDAMENTAL_MAX)

   252 /**

   253  * G_TYPE_IS_DERIVED:

   254  * @type: A #GType value.

   255  * 

   256  * Checks if @type is derived (or in object-oriented terminology:

   257  * inherited) from another type (this holds true for all non-fundamental

   258  * types).

   259  *

   260  * Returns: %TRUE on success.

   261  */

   262 #define G_TYPE_IS_DERIVED(type)                 ((type) > G_TYPE_FUNDAMENTAL_MAX)

   263 /**

   264  * G_TYPE_IS_INTERFACE:

   265  * @type: A #GType value.

   266  * 

   267  * Checks if @type is an interface type.

   268  * An interface type provides a pure API, the implementation

   269  * of which is provided by another type (which is then said to conform

   270  * to the interface).  GLib interfaces are somewhat analogous to Java

   271  * interfaces and C++ classes containing only pure virtual functions, 

   272  * with the difference that GType interfaces are not derivable (but see

   273  * g_type_interface_add_prerequisite() for an alternative).

   274  *

   275  * Returns: %TRUE on success.

   276  */

   277 #define G_TYPE_IS_INTERFACE(type)               (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)

   278 /**

   279  * G_TYPE_IS_CLASSED:

   280  * @type: A #GType value.

   281  * 

   282  * Checks if @type is a classed type.

   283  *

   284  * Returns: %TRUE on success.

   285  */

   286 #define G_TYPE_IS_CLASSED(type)                 (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))

   287 /**

   288  * G_TYPE_IS_INSTANTIATABLE:

   289  * @type: A #GType value.

   290  * 

   291  * Checks if @type can be instantiated.  Instantiation is the

   292  * process of creating an instance (object) of this type.

   293  *

   294  * Returns: %TRUE on success.

   295  */

   296 #define G_TYPE_IS_INSTANTIATABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))

   297 /**

   298  * G_TYPE_IS_DERIVABLE:

   299  * @type: A #GType value.

   300  * 

   301  * Checks if @type is a derivable type.  A derivable type can

   302  * be used as the base class of a flat (single-level) class hierarchy.

   303  *

   304  * Returns: %TRUE on success.

   305  */

   306 #define G_TYPE_IS_DERIVABLE(type)               (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))

   307 /**

   308  * G_TYPE_IS_DEEP_DERIVABLE:

   309  * @type: A #GType value.

   310  * 

   311  * Checks if @type is a deep derivable type.  A deep derivable type

   312  * can be used as the base class of a deep (multi-level) class hierarchy.

   313  *

   314  * Returns: %TRUE on success.

   315  */

   316 #define G_TYPE_IS_DEEP_DERIVABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))

   317 /**

   318  * G_TYPE_IS_ABSTRACT:

   319  * @type: A #GType value.

   320  * 

   321  * Checks if @type is an abstract type.  An abstract type can not be

   322  * instantiated and is normally used as an abstract base class for

   323  * derived classes.

   324  *

   325  * Returns: %TRUE on success.

   326  */

   327 #define G_TYPE_IS_ABSTRACT(type)                (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))

   328 /**

   329  * G_TYPE_IS_VALUE_ABSTRACT:

   330  * @type: A #GType value.

   331  * 

   332  * Checks if @type is an abstract value type.  An abstract value type introduces

   333  * a value table, but can't be used for g_value_init() and is normally used as

   334  * an abstract base type for derived value types.

   335  *

   336  * Returns: %TRUE on success.

   337  */

   338 #define G_TYPE_IS_VALUE_ABSTRACT(type)          (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))

   339 /**

   340  * G_TYPE_IS_VALUE_TYPE:

   341  * @type: A #GType value.

   342  * 

   343  * Checks if @type is a value type and can be used with g_value_init(). 

   344  *

   345  * Returns: %TRUE on success.

   346  */

   347 #define G_TYPE_IS_VALUE_TYPE(type)              (g_type_check_is_value_type (type))

   348 /**

   349  * G_TYPE_HAS_VALUE_TABLE:

   350  * @type: A #GType value.

   351  * 

   352  * Checks if @type has a #GTypeValueTable.

   353  *

   354  * Returns: %TRUE on success.

   355  */

   356 #define G_TYPE_HAS_VALUE_TABLE(type)            (g_type_value_table_peek (type) != NULL)

   357 

   358 

   359 /* Typedefs

   360  */

   361 /**

   362  * GType:

   363  * 

   364  * A numerical value which represents the unique identifier of a registered

   365  * type.

   366  */

   367 #if     GLIB_SIZEOF_SIZE_T != GLIB_SIZEOF_LONG || !defined __cplusplus

   368 typedef gsize                           GType;

   369 #else   /* for historic reasons, C++ links against gulong GTypes */

   370 typedef gulong                          GType;

   371 #endif

   372 typedef struct _GValue                  GValue;

   373 typedef union  _GTypeCValue             GTypeCValue;

   374 typedef struct _GTypePlugin             GTypePlugin;

   375 typedef struct _GTypeClass              GTypeClass;

   376 typedef struct _GTypeInterface          GTypeInterface;

   377 typedef struct _GTypeInstance           GTypeInstance;

   378 typedef struct _GTypeInfo               GTypeInfo;

   379 typedef struct _GTypeFundamentalInfo    GTypeFundamentalInfo;

   380 typedef struct _GInterfaceInfo          GInterfaceInfo;

   381 typedef struct _GTypeValueTable         GTypeValueTable;

   382 typedef struct _GTypeQuery		GTypeQuery;

   383 

   384 

   385 /* Basic Type Structures

   386  */

   387 /**

   388  * GTypeClass:

   389  * 

   390  * An opaque structure used as the base of all classes.

   391  */

   392 struct _GTypeClass

   393 {

   394   /*< private >*/

   395   GType g_type;

   396 };

   397 /**

   398  * GTypeInstance:

   399  * 

   400  * An opaque structure used as the base of all type instances.

   401  */

   402 struct _GTypeInstance

   403 {

   404   /*< private >*/

   405   GTypeClass *g_class;

   406 };

   407 /**

   408  * GTypeInterface:

   409  * 

   410  * An opaque structure used as the base of all interface types.

   411  */

   412 struct _GTypeInterface

   413 {

   414   /*< private >*/

   415   GType g_type;         /* iface type */

   416   GType g_instance_type;

   417 };

   418 /**

   419  * GTypeQuery:

   420  * @type: the #GType value of the type.

   421  * @type_name: the name of the type.

   422  * @class_size: the size of the class structure.

   423  * @instance_size: the size of the instance structure.

   424  * 

   425  * A structure holding information for a specific type. It is

   426  * filled in by the g_type_query() function.

   427  */

   428 struct _GTypeQuery

   429 {

   430   GType		type;

   431   const gchar  *type_name;

   432   guint		class_size;

   433   guint		instance_size;

   434 };

   435 

   436 

   437 /* Casts, checks and accessors for structured types

   438  * usage of these macros is reserved to type implementations only

   439  */

   440 /*< protected >*/

   441 /**

   442  * G_TYPE_CHECK_INSTANCE:

   443  * @instance: Location of a #GTypeInstance structure.

   444  * 

   445  * Checks if @instance is a valid #GTypeInstance structure,

   446  * otherwise issues a warning and returns %FALSE.

   447  * 

   448  * This macro should only be used in type implementations.

   449  *

   450  * Returns: %TRUE on success.

   451  */

   452 #define G_TYPE_CHECK_INSTANCE(instance)				(_G_TYPE_CHI ((GTypeInstance*) (instance)))

   453 /**

   454  * G_TYPE_CHECK_INSTANCE_CAST:

   455  * @instance: Location of a #GTypeInstance structure.

   456  * @g_type: The type to be returned.

   457  * @c_type: The corresponding C type of @g_type.

   458  * 

   459  * Checks that @instance is an instance of the type identified by @g_type

   460  * and issues a warning if this is not the case. Returns @instance casted 

   461  * to a pointer to @c_type.

   462  * 

   463  * This macro should only be used in type implementations.

   464  */

   465 #define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type)    (_G_TYPE_CIC ((instance), (g_type), c_type))

   466 /**

   467  * G_TYPE_CHECK_INSTANCE_TYPE:

   468  * @instance: Location of a #GTypeInstance structure.

   469  * @g_type: The type to be checked

   470  * 

   471  * Checks if @instance is an instance of the type identified by @g_type.

   472  * 

   473  * This macro should only be used in type implementations.

   474  *

   475  * Returns: %TRUE on success.

   476  */

   477 #define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type)            (_G_TYPE_CIT ((instance), (g_type)))

   478 /**

   479  * G_TYPE_INSTANCE_GET_CLASS:

   480  * @instance: Location of the #GTypeInstance structure.

   481  * @g_type: The #GType of the class to be returned.

   482  * @c_type: The C type of the class structure.

   483  * 

   484  * Get the class structure of a given @instance, casted

   485  * to a specified ancestor type @g_type of the instance.

   486  * 

   487  * Note that while calling a GInstanceInitFunc(), the class pointer gets

   488  * modified, so it might not always return the expected pointer.

   489  * 

   490  * This macro should only be used in type implementations.

   491  *

   492  * Returns: a pointer to the class structure

   493  */

   494 #define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type)     (_G_TYPE_IGC ((instance), (g_type), c_type))

   495 /**

   496  * G_TYPE_INSTANCE_GET_INTERFACE:

   497  * @instance: Location of the #GTypeInstance structure.

   498  * @g_type: The #GType of the interface to be returned.

   499  * @c_type: The C type of the interface structure.

   500  * 

   501  * Get the interface structure for interface @g_type of a given @instance.

   502  * 

   503  * This macro should only be used in type implementations.

   504  *

   505  * Returns: a pointer to the interface structure

   506  */

   507 #define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type))

   508 /**

   509  * G_TYPE_CHECK_CLASS_CAST:

   510  * @g_class: Location of a #GTypeClass structure.

   511  * @g_type: The type to be returned.

   512  * @c_type: The corresponding C type of class structure of @g_type.

   513  * 

   514  * Checks that @g_class is a class structure of the type identified by @g_type

   515  * and issues a warning if this is not the case. Returns @g_class casted 

   516  * to a pointer to @c_type.

   517  * 

   518  * This macro should only be used in type implementations.

   519  */

   520 #define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type)        (_G_TYPE_CCC ((g_class), (g_type), c_type))

   521 /**

   522  * G_TYPE_CHECK_CLASS_TYPE:

   523  * @g_class: Location of a #GTypeClass structure.

   524  * @g_type: The type to be checked.

   525  * 

   526  * Checks if @g_class is a class structure of the type identified by 

   527  * @g_type.

   528  * 

   529  * This macro should only be used in type implementations.

   530  *

   531  * Returns: %TRUE on success.

   532  */

   533 #define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type)                (_G_TYPE_CCT ((g_class), (g_type)))

   534 /**

   535  * G_TYPE_CHECK_VALUE:

   536  * @value: a #GValue

   537  * 

   538  * Checks if @value has been initialized to hold values

   539  * of a value type.

   540  * 

   541  * This macro should only be used in type implementations.

   542  *

   543  * Returns: %TRUE on success.

   544  */

   545 #define G_TYPE_CHECK_VALUE(value)				(_G_TYPE_CHV ((value)))

   546 /**

   547  * G_TYPE_CHECK_VALUE_TYPE:

   548  * @value: a #GValue

   549  * @g_type: The type to be checked.

   550  * 

   551  * Checks if @value has been initialized to hold values

   552  * of type @g_type. 

   553  * 

   554  * This macro should only be used in type implementations.

   555  *

   556  * Returns: %TRUE on success.

   557  */

   558 #define G_TYPE_CHECK_VALUE_TYPE(value, g_type)			(_G_TYPE_CVH ((value), (g_type)))

   559 /**

   560  * G_TYPE_FROM_INSTANCE:

   561  * @instance: Location of a valid #GTypeInstance structure.

   562  * 

   563  * Get the type identifier from a given @instance structure. 

   564  * 

   565  * This macro should only be used in type implementations.

   566  *

   567  * Returns: the #GType

   568  */

   569 #define G_TYPE_FROM_INSTANCE(instance)                          (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class))

   570 /**

   571  * G_TYPE_FROM_CLASS:

   572  * @g_class: Location of a valid #GTypeClass structure.

   573  * 

   574  * Get the type identifier from a given @class structure.

   575  * 

   576  * This macro should only be used in type implementations.

   577  *

   578  * Returns: the #GType

   579  */

   580 #define G_TYPE_FROM_CLASS(g_class)                              (((GTypeClass*) (g_class))->g_type)

   581 /**

   582  * G_TYPE_FROM_INTERFACE:

   583  * @g_iface: Location of a valid #GTypeInterface structure.

   584  * 

   585  * Get the type identifier from a given @interface structure.

   586  * 

   587  * This macro should only be used in type implementations.

   588  *

   589  * Returns: the #GType

   590  */

   591 #define G_TYPE_FROM_INTERFACE(g_iface)                          (((GTypeInterface*) (g_iface))->g_type)

   592 

   593 /**

   594  * G_TYPE_INSTANCE_GET_PRIVATE:

   595  * @instance: the instance of a type deriving from @private_type.

   596  * @g_type: the type identifying which private data to retrieve.

   597  * @c_type: The C type for the private structure.

   598  * 

   599  * Gets the private structure for a particular type.

   600  * The private structure must have been registered in the

   601  * class_init function with g_type_class_add_private().

   602  * 

   603  * This macro should only be used in type implementations.

   604  * 

   605  * Since: 2.4

   606  * Returns: a pointer to the private data structure.

   607  */

   608 #define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type)   ((c_type*) g_type_instance_get_private ((GTypeInstance*) (instance), (g_type)))

   609 

   610 

   611 /**

   612  * GTypeDebugFlags:

   613  * @G_TYPE_DEBUG_NONE: Print no messages.

   614  * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping.

   615  * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions.

   616  * @G_TYPE_DEBUG_MASK: Mask covering all debug flags.

   617  * 

   618  * The <type>GTypeDebugFlags</type> enumeration values can be passed to

   619  * g_type_init_with_debug_flags() to trigger debugging messages during runtime.

   620  * Note that the messages can also be triggered by setting the

   621  * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of 

   622  * "objects" and "signals".

   623  */

   624 typedef enum	/*< skip >*/

   625 {

   626   G_TYPE_DEBUG_NONE	= 0,

   627   G_TYPE_DEBUG_OBJECTS	= 1 << 0,

   628   G_TYPE_DEBUG_SIGNALS	= 1 << 1,

   629   G_TYPE_DEBUG_MASK	= 0x03

   630 } GTypeDebugFlags;

   631 

   632 

   633 /* --- prototypes --- */

   634 IMPORT_C void                  g_type_init                    (void);

   635 IMPORT_C void                  g_type_init_with_debug_flags   (GTypeDebugFlags  debug_flags);

   636 IMPORT_C G_CONST_RETURN gchar* g_type_name                    (GType            type);

   637 IMPORT_C GQuark                g_type_qname                   (GType            type);

   638 IMPORT_C GType                 g_type_from_name               (const gchar     *name);

   639 IMPORT_C GType                 g_type_parent                  (GType            type);

   640 IMPORT_C guint                 g_type_depth                   (GType            type);

   641 IMPORT_C GType                 g_type_next_base               (GType            leaf_type,

   642 						      GType            root_type);

   643 IMPORT_C gboolean              g_type_is_a                    (GType            type,

   644 						      GType            is_a_type);

   645 IMPORT_C gpointer              g_type_class_ref               (GType            type);

   646 IMPORT_C gpointer              g_type_class_peek              (GType            type);

   647 IMPORT_C gpointer              g_type_class_peek_static       (GType            type);

   648 IMPORT_C void                  g_type_class_unref             (gpointer         g_class);

   649 IMPORT_C gpointer              g_type_class_peek_parent       (gpointer         g_class);

   650 IMPORT_C gpointer              g_type_interface_peek          (gpointer         instance_class,

   651 						      GType            iface_type);

   652 IMPORT_C gpointer              g_type_interface_peek_parent   (gpointer         g_iface);

   653 

   654 IMPORT_C gpointer              g_type_default_interface_ref   (GType            g_type);

   655 IMPORT_C gpointer              g_type_default_interface_peek  (GType            g_type);

   656 IMPORT_C void                  g_type_default_interface_unref (gpointer         g_iface);

   657 

   658 /* g_free() the returned arrays */

   659 IMPORT_C GType*                g_type_children                (GType            type,

   660 						      guint           *n_children);

   661 IMPORT_C GType*                g_type_interfaces              (GType            type,

   662 						      guint           *n_interfaces);

   663 

   664 /* per-type _static_ data */

   665 IMPORT_C void                  g_type_set_qdata               (GType            type,

   666 						      GQuark           quark,

   667 						      gpointer         data);

   668 IMPORT_C gpointer              g_type_get_qdata               (GType            type,

   669 						      GQuark           quark);

   670 IMPORT_C void		      g_type_query		     (GType	       type,

   671 						      GTypeQuery      *query);

   672 

   673 

   674 /* --- type registration --- */

   675 /**

   676  * GBaseInitFunc:

   677  * @g_class: The #GTypeClass structure to initialize.

   678  * 

   679  * A callback function used by the type system to do base initialization

   680  * of the class structures of derived types. It is called as part of the

   681  * initialization process of all derived classes and should reallocate

   682  * or reset all dynamic class members copied over from the parent class.

   683  * For example, class members (such as strings) that are not sufficiently

   684  * handled by a plain memory copy of the parent class into the derived class

   685  * have to be altered. See GClassInitFunc() for a discussion of the class

   686  * intialization process.

   687  */

   688 typedef void   (*GBaseInitFunc)              (gpointer         g_class);

   689 /**

   690  * GBaseFinalizeFunc:

   691  * @g_class: The #GTypeClass structure to finalize.

   692  * 

   693  * A callback function used by the type system to finalize those portions

   694  * of a derived types class structure that were setup from the corresponding

   695  * GBaseInitFunc() function. Class finalization basically works the inverse

   696  * way in which class intialization is performed.

   697  * See GClassInitFunc() for a discussion of the class intialization process.

   698  */

   699 typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);

   700 /**

   701  * GClassInitFunc:

   702  * @g_class: The #GTypeClass structure to initialize.

   703  * @class_data: The @class_data member supplied via the #GTypeInfo structure.

   704  * 

   705  * A callback function used by the type system to initialize the class

   706  * of a specific type. This function should initialize all static class

   707  * members.

   708  * The initialization process of a class involves:

   709  * <itemizedlist>

   710  * <listitem><para>

   711  * 	1 - Copying common members from the parent class over to the

   712  * 	derived class structure.

   713  * </para></listitem>

   714  * <listitem><para>

   715  * 	2 -  Zero initialization of the remaining members not copied

   716  * 	over from the parent class.

   717  * </para></listitem>

   718  * <listitem><para>

   719  * 	3 - Invocation of the GBaseInitFunc() initializers of all parent

   720  * 	types and the class' type.

   721  * </para></listitem>

   722  * <listitem><para>

   723  * 	4 - Invocation of the class' GClassInitFunc() initializer.

   724  * </para></listitem>

   725  * </itemizedlist>

   726  * Since derived classes are partially initialized through a memory copy

   727  * of the parent class, the general rule is that GBaseInitFunc() and

   728  * GBaseFinalizeFunc() should take care of necessary reinitialization

   729  * and release of those class members that were introduced by the type

   730  * that specified these GBaseInitFunc()/GBaseFinalizeFunc().

   731  * GClassInitFunc() should only care about initializing static

   732  * class members, while dynamic class members (such as allocated strings

   733  * or reference counted resources) are better handled by a GBaseInitFunc()

   734  * for this type, so proper initialization of the dynamic class members

   735  * is performed for class initialization of derived types as well.

   736  * An example may help to correspond the intend of the different class

   737  * initializers:

   738  * 

   739  * |[

   740  * typedef struct {

   741  *   GObjectClass parent_class;

   742  *   gint         static_integer;

   743  *   gchar       *dynamic_string;

   744  * } TypeAClass;

   745  * static void

   746  * type_a_base_class_init (TypeAClass *class)

   747  * {

   748  *   class->dynamic_string = g_strdup ("some string");

   749  * }

   750  * static void

   751  * type_a_base_class_finalize (TypeAClass *class)

   752  * {

   753  *   g_free (class->dynamic_string);

   754  * }

   755  * static void

   756  * type_a_class_init (TypeAClass *class)

   757  * {

   758  *   class->static_integer = 42;

   759  * }

   760  * 

   761  * typedef struct {

   762  *   TypeAClass   parent_class;

   763  *   gfloat       static_float;

   764  *   GString     *dynamic_gstring;

   765  * } TypeBClass;

   766  * static void

   767  * type_b_base_class_init (TypeBClass *class)

   768  * {

   769  *   class->dynamic_gstring = g_string_new ("some other string");

   770  * }

   771  * static void

   772  * type_b_base_class_finalize (TypeBClass *class)

   773  * {

   774  *   g_string_free (class->dynamic_gstring);

   775  * }

   776  * static void

   777  * type_b_class_init (TypeBClass *class)

   778  * {

   779  *   class->static_float = 3.14159265358979323846;

   780  * }

   781  * ]|

   782  * Initialization of TypeBClass will first cause initialization of

   783  * TypeAClass (derived classes reference their parent classes, see

   784  * g_type_class_ref() on this).

   785  * Initialization of TypeAClass roughly involves zero-initializing its fields,

   786  * then calling its GBaseInitFunc() type_a_base_class_init() to allocate

   787  * its dynamic members (dynamic_string), and finally calling its GClassInitFunc()

   788  * type_a_class_init() to initialize its static members (static_integer).

   789  * The first step in the initialization process of TypeBClass is then

   790  * a plain memory copy of the contents of TypeAClass into TypeBClass and 

   791  * zero-initialization of the remaining fields in TypeBClass.

   792  * The dynamic members of TypeAClass within TypeBClass now need

   793  * reinitialization which is performed by calling type_a_base_class_init()

   794  * with an argument of TypeBClass.

   795  * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init()

   796  * is called to allocate the dynamic members of TypeBClass (dynamic_gstring),

   797  * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(),

   798  * is called to complete the initialization process with the static members

   799  * (static_float).

   800  * Corresponding finalization counter parts to the GBaseInitFunc() functions

   801  * have to be provided to release allocated resources at class finalization

   802  * time.

   803  */

   804 typedef void   (*GClassInitFunc)             (gpointer         g_class,

   805 					      gpointer         class_data);

   806 /**

   807  * GClassFinalizeFunc:

   808  * @g_class: The #GTypeClass structure to finalize.

   809  * @class_data: The @class_data member supplied via the #GTypeInfo structure.

   810  * 

   811  * A callback function used by the type system to finalize a class.

   812  * This function is rarely needed, as dynamically allocated class resources

   813  * should be handled by GBaseInitFunc() and GBaseFinalizeFunc().

   814  * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo

   815  * structure of a static type is invalid, because classes of static types

   816  * will never be finalized (they are artificially kept alive when their

   817  * reference count drops to zero).

   818  */

   819 typedef void   (*GClassFinalizeFunc)         (gpointer         g_class,

   820 					      gpointer         class_data);

   821 /**

   822  * GInstanceInitFunc:

   823  * @instance: The instance to initialize.

   824  * @g_class: The class of the type the instance is created for.

   825  * 

   826  * A callback function used by the type system to initialize a new

   827  * instance of a type. This function initializes all instance members and

   828  * allocates any resources required by it.

   829  * Initialization of a derived instance involves calling all its parent

   830  * types instance initializers, so the class member of the instance

   831  * is altered during its initialization to always point to the class that

   832  * belongs to the type the current initializer was introduced for.

   833  */

   834 typedef void   (*GInstanceInitFunc)          (GTypeInstance   *instance,

   835 					      gpointer         g_class);

   836 /**

   837  * GInterfaceInitFunc:

   838  * @g_iface: The interface structure to initialize.

   839  * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.

   840  * 

   841  * A callback function used by the type system to initialize a new

   842  * interface.  This function should initialize all internal data and

   843  * allocate any resources required by the interface.

   844  */

   845 typedef void   (*GInterfaceInitFunc)         (gpointer         g_iface,

   846 					      gpointer         iface_data);

   847 /**

   848  * GInterfaceFinalizeFunc:

   849  * @g_iface: The interface structure to finalize.

   850  * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.

   851  * 

   852  * A callback function used by the type system to finalize an interface.

   853  * This function should destroy any internal data and release any resources

   854  * allocated by the corresponding GInterfaceInitFunc() function.

   855  */

   856 typedef void   (*GInterfaceFinalizeFunc)     (gpointer         g_iface,

   857 					      gpointer         iface_data);

   858 /**

   859  * GTypeClassCacheFunc:

   860  * @cache_data: data that was given to the g_type_add_class_cache_func() call

   861  * @g_class: The #GTypeClass structure which is unreferenced

   862  * 

   863  * A callback function which is called when the reference count of a class 

   864  * drops to zero. It may use g_type_class_ref() to prevent the class from

   865  * being freed. You should not call g_type_class_unref() from a 

   866  * #GTypeClassCacheFunc function to prevent infinite recursion, use 

   867  * g_type_class_unref_uncached() instead.

   868  * 

   869  * The functions have to check the class id passed in to figure 

   870  * whether they actually want to cache the class of this type, since all

   871  * classes are routed through the same #GTypeClassCacheFunc chain.

   872  * 

   873  * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being 

   874  *  called, %FALSE to continue.

   875  */

   876 typedef gboolean (*GTypeClassCacheFunc)	     (gpointer	       cache_data,

   877 					      GTypeClass      *g_class);

   878 /**

   879  * GTypeInterfaceCheckFunc:

   880  * @check_data: data passed to g_type_add_interface_check().

   881  * @g_iface: the interface that has been initialized

   882  * 

   883  * A callback called after an interface vtable is initialized.

   884  * See g_type_add_interface_check().

   885  * 

   886  * Since: 2.4

   887  */

   888 typedef void     (*GTypeInterfaceCheckFunc)  (gpointer	       check_data,

   889 					      gpointer         g_iface);

   890 /**

   891  * GTypeFundamentalFlags:

   892  * @G_TYPE_FLAG_CLASSED: Indicates a classed type.

   893  * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed).

   894  * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type.

   895  * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable).

   896  * 

   897  * Bit masks used to check or determine specific characteristics of a

   898  * fundamental type.

   899  */

   900 typedef enum    /*< skip >*/

   901 {

   902   G_TYPE_FLAG_CLASSED           = (1 << 0),

   903   G_TYPE_FLAG_INSTANTIATABLE    = (1 << 1),

   904   G_TYPE_FLAG_DERIVABLE         = (1 << 2),

   905   G_TYPE_FLAG_DEEP_DERIVABLE    = (1 << 3)

   906 } GTypeFundamentalFlags;

   907 /**

   908  * GTypeFlags:

   909  * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be

   910  *  created for an abstract type.

   911  * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type

   912  *  that introduces a value table, but can't be used for

   913  *  g_value_init().

   914  * 

   915  * Bit masks used to check or determine characteristics of a type.

   916  */

   917 typedef enum    /*< skip >*/

   918 {

   919   G_TYPE_FLAG_ABSTRACT		= (1 << 4),

   920   G_TYPE_FLAG_VALUE_ABSTRACT	= (1 << 5)

   921 } GTypeFlags;

   922 /**

   923  * GTypeInfo:

   924  * @class_size: Size of the class structure (required for interface, classed and instantiatable types).

   925  * @base_init: Location of the base initialization function (optional).

   926  * @base_finalize: Location of the base finalization function (optional).

   927  * @class_init: Location of the class initialization function for

   928  *  classed and instantiatable types. Location of the default vtable 

   929  *  inititalization function for interface types. (optional) This function 

   930  *  is used both to fill in virtual functions in the class or default vtable, 

   931  *  and to do type-specific setup such as registering signals and object

   932  *  properties.

   933  * @class_finalize: Location of the class finalization function for

   934  *  classed and instantiatable types. Location fo the default vtable 

   935  *  finalization function for interface types. (optional)

   936  * @class_data: User-supplied data passed to the class init/finalize functions.

   937  * @instance_size: Size of the instance (object) structure (required for instantiatable types only).

   938  * @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.

   939  * @instance_init: Location of the instance initialization function (optional, for instantiatable types only).

   940  * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only

   941  *  useful for fundamental types).

   942  * 

   943  * This structure is used to provide the type system with the information

   944  * required to initialize and destruct (finalize) a type's class and

   945  * its instances.

   946  * The initialized structure is passed to the g_type_register_static() function

   947  * (or is copied into the provided #GTypeInfo structure in the

   948  * g_type_plugin_complete_type_info()). The type system will perform a deep

   949  * copy of this structure, so its memory does not need to be persistent

   950  * across invocation of g_type_register_static().

   951  */

   952 struct _GTypeInfo

   953 {

   954   /* interface types, classed types, instantiated types */

   955   guint16                class_size;

   956   

   957   GBaseInitFunc          base_init;

   958   GBaseFinalizeFunc      base_finalize;

   959   

   960   /* interface types, classed types, instantiated types */

   961   GClassInitFunc         class_init;

   962   GClassFinalizeFunc     class_finalize;

   963   gconstpointer          class_data;

   964   

   965   /* instantiated types */

   966   guint16                instance_size;

   967   guint16                n_preallocs;

   968   GInstanceInitFunc      instance_init;

   969   

   970   /* value handling */

   971   const GTypeValueTable	*value_table;

   972 };

   973 /**

   974  * GTypeFundamentalInfo:

   975  * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type

   976  * 

   977  * A structure that provides information to the type system which is

   978  * used specifically for managing fundamental types.  

   979  */

   980 struct _GTypeFundamentalInfo

   981 {

   982   GTypeFundamentalFlags  type_flags;

   983 };

   984 /**

   985  * GInterfaceInfo:

   986  * @interface_init: location of the interface initialization function

   987  * @interface_finalize: location of the interface finalization function

   988  * @interface_data: user-supplied data passed to the interface init/finalize functions

   989  * 

   990  * A structure that provides information to the type system which is

   991  * used specifically for managing interface types.

   992  */

   993 struct _GInterfaceInfo

   994 {

   995   GInterfaceInitFunc     interface_init;

   996   GInterfaceFinalizeFunc interface_finalize;

   997   gpointer               interface_data;

   998 };

   999 /**

  1000  * GTypeValueTable:

  1001  * @value_init: Default initialize @values contents by poking values

  1002  *  directly into the value->data array. The data array of

  1003  *  the #GValue passed into this function was zero-filled

  1004  *  with <function>memset()</function>, so no care has to

  1005  *  be taken to free any

  1006  *  old contents. E.g. for the implementation of a string

  1007  *  value that may never be %NULL, the implementation might

  1008  *  look like:

  1009  *  |[

  1010  *  value->data[0].v_pointer = g_strdup ("");

  1011  *  ]|

  1012  * @value_free: Free any old contents that might be left in the

  1013  *  data array of the passed in @value. No resources may

  1014  *  remain allocated through the #GValue contents after

  1015  *  this function returns. E.g. for our above string type:

  1016  *  |[

  1017  *  // only free strings without a specific flag for static storage

  1018  *  if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))

  1019  *    g_free (value->data[0].v_pointer);

  1020  *  ]|

  1021  * @value_copy: @dest_value is a #GValue with zero-filled data section

  1022  *  and @src_value is a properly setup #GValue of same or

  1023  *  derived type.

  1024  *  The purpose of this function is to copy the contents of

  1025  *  @src_value into @dest_value in a way, that even after

  1026  *  @src_value has been freed, the contents of @dest_value

  1027  *  remain valid. String type example:

  1028  *  |[

  1029  *  dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);

  1030  *  ]|

  1031  * @value_peek_pointer: If the value contents fit into a pointer, such as objects

  1032  *  or strings, return this pointer, so the caller can peek at

  1033  *  the current contents. To extend on our above string example:

  1034  *  |[

  1035  *  return value->data[0].v_pointer;

  1036  *  ]|

  1037  * @collect_format: A string format describing how to collect the contents of

  1038  *  this value bit-by-bit. Each character in the format represents

  1039  *  an argument to be collected, and the characters themselves indicate

  1040  *  the type of the argument. Currently supported arguments are:

  1041  *  <variablelist>

  1042  *  <varlistentry><term /><listitem><para>

  1043  *  'i' - Integers. passed as collect_values[].v_int.

  1044  *  </para></listitem></varlistentry>

  1045  *  <varlistentry><term /><listitem><para>

  1046  *  'l' - Longs. passed as collect_values[].v_long.

  1047  *  </para></listitem></varlistentry>

  1048  *  <varlistentry><term /><listitem><para>

  1049  *  'd' - Doubles. passed as collect_values[].v_double.

  1050  *  </para></listitem></varlistentry>

  1051  *  <varlistentry><term /><listitem><para>

  1052  *  'p' - Pointers. passed as collect_values[].v_pointer.

  1053  *  </para></listitem></varlistentry>

  1054  *  </variablelist>

  1055  *  It should be noted that for variable argument list construction,

  1056  *  ANSI C promotes every type smaller than an integer to an int, and

  1057  *  floats to doubles. So for collection of short int or char, 'i'

  1058  *  needs to be used, and for collection of floats 'd'.

  1059  * @collect_value: The collect_value() function is responsible for converting the

  1060  *  values collected from a variable argument list into contents

  1061  *  suitable for storage in a GValue. This function should setup

  1062  *  @value similar to value_init(); e.g. for a string value that

  1063  *  does not allow %NULL pointers, it needs to either spew an error,

  1064  *  or do an implicit conversion by storing an empty string.

  1065  *  The @value passed in to this function has a zero-filled data

  1066  *  array, so just like for value_init() it is guaranteed to not

  1067  *  contain any old contents that might need freeing.

  1068  *  @n_collect_values is exactly the string length of @collect_format,

  1069  *  and @collect_values is an array of unions #GTypeCValue with

  1070  *  length @n_collect_values, containing the collected values

  1071  *  according to @collect_format.

  1072  *  @collect_flags is an argument provided as a hint by the caller.

  1073  *  It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating,

  1074  *  that the collected value contents may be considered "static"

  1075  *  for the duration of the @value lifetime.

  1076  *  Thus an extra copy of the contents stored in @collect_values is

  1077  *  not required for assignment to @value.

  1078  *  For our above string example, we continue with:

  1079  *  |[

  1080  *  if (!collect_values[0].v_pointer)

  1081  *    value->data[0].v_pointer = g_strdup ("");

  1082  *  else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)

  1083  *  {

  1084  *    value->data[0].v_pointer = collect_values[0].v_pointer;

  1085  *    // keep a flag for the value_free() implementation to not free this string

  1086  *    value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;

  1087  *  }

  1088  *  else

  1089  *    value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer);

  1090  *  return NULL;

  1091  *  ]|

  1092  *  It should be noted, that it is generally a bad idea to follow the

  1093  *  #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to

  1094  *  reentrancy requirements and reference count assertions performed

  1095  *  by the #GSignal code, reference counts should always be incremented

  1096  *  for reference counted contents stored in the value->data array.

  1097  *  To deviate from our string example for a moment, and taking a look

  1098  *  at an exemplary implementation for collect_value() of #GObject:

  1099  *  |[

  1100  *  if (collect_values[0].v_pointer)

  1101  *  {

  1102  *    GObject *object = G_OBJECT (collect_values[0].v_pointer);

  1103  *    // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types

  1104  *    value->data[0].v_pointer = g_object_ref (object);

  1105  *    return NULL;

  1106  *  }

  1107  *  else

  1108  *    return g_strdup_printf ("Object passed as invalid NULL pointer");

  1109  *  }

  1110  *  ]|

  1111  *  The reference count for valid objects is always incremented,

  1112  *  regardless of @collect_flags. For invalid objects, the example

  1113  *  returns a newly allocated string without altering @value.

  1114  *  Upon success, collect_value() needs to return %NULL. If, however,

  1115  *  an error condition occurred, collect_value() may spew an

  1116  *  error by returning a newly allocated non-%NULL string, giving

  1117  *  a suitable description of the error condition.

  1118  *  The calling code makes no assumptions about the @value

  1119  *  contents being valid upon error returns, @value

  1120  *  is simply thrown away without further freeing. As such, it is

  1121  *  a good idea to not allocate #GValue contents, prior to returning

  1122  *  an error, however, collect_values() is not obliged to return

  1123  *  a correctly setup @value for error returns, simply because

  1124  *  any non-%NULL return is considered a fatal condition so further

  1125  *  program behaviour is undefined.

  1126  * @lcopy_format: Format description of the arguments to collect for @lcopy_value,

  1127  *  analogous to @collect_format. Usually, @lcopy_format string consists

  1128  *  only of 'p's to provide lcopy_value() with pointers to storage locations.

  1129  * @lcopy_value: This function is responsible for storing the @value contents into

  1130  *  arguments passed through a variable argument list which got

  1131  *  collected into @collect_values according to @lcopy_format.

  1132  *  @n_collect_values equals the string length of @lcopy_format,

  1133  *  and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS.

  1134  *  In contrast to collect_value(), lcopy_value() is obliged to

  1135  *  always properly support %G_VALUE_NOCOPY_CONTENTS.