girepository/gitypes.h

   1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*-
   2  * GObject introspection: types
   3  *
   4  * Copyright (C) 2005 Matthias Clasen
   5  * Copyright (C) 2008,2009 Red Hat, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #ifndef __GITYPES_H__
  24 #define __GITYPES_H__
  25
  26 #if !defined (__GIREPOSITORY_H_INSIDE__) && !defined (GI_COMPILATION)
  27 #error "Only <girepository.h> can be included directly."
  28 #endif
  29
  30 G_BEGIN_DECLS
  31
  32 typedef struct _GIBaseInfoStub GIBaseInfo;
  33
  34 /**
  35  * GICallableInfo:
  36  *
  37  * Represents a callable, either #GIFunctionInfo, #GICallbackInfo or
  38  * #GIVFuncInfo.
  39  */
  40 typedef GIBaseInfo GICallableInfo;
  41
  42 /**
  43  * GIFunctionInfo:
  44  *
  45  * Represents a function, eg arguments and return value.
  46  */
  47 typedef GIBaseInfo GIFunctionInfo;
  48
  49 /**
  50  * GICallbackInfo:
  51  *
  52  * Represents a callback, eg arguments and return value.
  53  */
  54 typedef GIBaseInfo GICallbackInfo;
  55
  56 /**
  57  * GIRegisteredTypeInfo:
  58  *
  59  * Represent a registered type.
  60  */
  61 typedef GIBaseInfo GIRegisteredTypeInfo;
  62
  63 /**
  64  * GIStructInfo:
  65  *
  66  * Represents a struct.
  67  */
  68 typedef GIBaseInfo GIStructInfo;
  69
  70 /**
  71  * GIUnionInfo:
  72  *
  73  * Represents a union.
  74  */
  75 typedef GIBaseInfo GIUnionInfo;
  76
  77 /**
  78  * GIEnumInfo:
  79  *
  80  * Represents an enum or a flag.
  81  */
  82 typedef GIBaseInfo GIEnumInfo;
  83
  84 /**
  85  * GIObjectInfo:
  86  *
  87  * Represents an object.
  88  */
  89 typedef GIBaseInfo GIObjectInfo;
  90
  91 /**
  92  * GIInterfaceInfo:
  93  *
  94  * Represents an interface.
  95  */
  96 typedef GIBaseInfo GIInterfaceInfo;
  97
  98 /**
  99  * GIConstantInfo:
 100  *
 101  * Represents a constant.
 102  */
 103 typedef GIBaseInfo GIConstantInfo;
 104
 105 /**
 106  * GIValueInfo:
 107  *
 108  * Represents a enum value of a #GIEnumInfo.
 109  */
 110 typedef GIBaseInfo GIValueInfo;
 111
 112 /**
 113  * GISignalInfo:
 114  *
 115  * Represents a signal.
 116  */
 117 typedef GIBaseInfo GISignalInfo;
 118
 119 /**
 120  * GIVFuncInfo
 121  *
 122  * Represents a virtual function.
 123  */
 124 typedef GIBaseInfo GIVFuncInfo;
 125
 126 /**
 127  * GIPropertyInfo:
 128  *
 129  * Represents a property of a #GIObjectInfo or a #GIInterfaceInfo.
 130  */
 131 typedef GIBaseInfo GIPropertyInfo;
 132
 133 /**
 134  * GIFieldInfo:
 135  *
 136  * Represents a field of a #GIStructInfo or a #GIUnionInfo.
 137  */
 138 typedef GIBaseInfo GIFieldInfo;
 139
 140 /**
 141  * GIArgInfo:
 142  *
 143  * Represents an argument.
 144  */
 145 typedef GIBaseInfo GIArgInfo;
 146
 147 /**
 148  * GITypeInfo:
 149  *
 150  * Represents type information, direction, transfer etc.
 151  */
 152 typedef GIBaseInfo GITypeInfo;
 153
 154 /**
 155  * GIUnresolvedInfo:
 156  *
 157  * Represents a unresolved type in a typelib.
 158  */
 159 typedef struct _GIUnresolvedInfo GIUnresolvedInfo;
 160
 161 union _GIArgument
 162 {
 163   gboolean v_boolean;
 164   gint8    v_int8;
 165   guint8   v_uint8;
 166   gint16   v_int16;
 167   guint16  v_uint16;
 168   gint32   v_int32;
 169   guint32  v_uint32;
 170   gint64   v_int64;
 171   guint64  v_uint64;
 172   gfloat   v_float;
 173   gdouble  v_double;
 174   gshort   v_short;
 175   gushort  v_ushort;
 176   gint     v_int;
 177   guint    v_uint;
 178   glong    v_long;
 179   gulong   v_ulong;
 180   gssize   v_ssize;
 181   gsize    v_size;
 182   gchar *  v_string;
 183   gpointer v_pointer;
 184 };
 185 typedef union _GIArgument GIArgument;
 186
 187 /**
 188  * GIInfoType:
 189  * @GI_INFO_TYPE_INVALID: invalid type
 190  * @GI_INFO_TYPE_FUNCTION: function, see #GIFunctionInfo
 191  * @GI_INFO_TYPE_CALLBACK: callback, see #GIFunctionInfo
 192  * @GI_INFO_TYPE_STRUCT: struct, see #GIStructInfo
 193  * @GI_INFO_TYPE_BOXED: boxed, see #GIStructInfo or #GIUnionInfo
 194  * @GI_INFO_TYPE_ENUM: enum, see #GIEnumInfo
 195  * @GI_INFO_TYPE_FLAGS: flags, see #GIEnumInfo
 196  * @GI_INFO_TYPE_OBJECT: object, see #GIObjectInfo
 197  * @GI_INFO_TYPE_INTERFACE: interface, see #GIInterfaceInfo
 198  * @GI_INFO_TYPE_CONSTANT: contant, see #GIConstantInfo
 199  * @GI_INFO_TYPE_UNION: union, see #GIUnionInfo
 200  * @GI_INFO_TYPE_VALUE: enum value, see #GIValueInfo
 201  * @GI_INFO_TYPE_SIGNAL: signal, see #GISignalInfo
 202  * @GI_INFO_TYPE_VFUNC: virtual function, see #GIVFuncInfo
 203  * @GI_INFO_TYPE_PROPERTY: GObject property, see #GIPropertyInfo
 204  * @GI_INFO_TYPE_FIELD: struct or union field, see #GIFieldInfo
 205  * @GI_INFO_TYPE_ARG: argument of a function or callback, see #GIArgInfo
 206  * @GI_INFO_TYPE_TYPE: type information, see #GITypeInfo
 207  * @GI_INFO_TYPE_UNRESOLVED: unresolved type, a type which is not present in
 208  * the typelib, or any of its dependencies.
 209  *
 210  * The type of a GIBaseInfo struct.
 211  */
 212 typedef enum
 213 {
 214   GI_INFO_TYPE_INVALID,
 215   GI_INFO_TYPE_FUNCTION,
 216   GI_INFO_TYPE_CALLBACK,
 217   GI_INFO_TYPE_STRUCT,
 218   GI_INFO_TYPE_BOXED,
 219   GI_INFO_TYPE_ENUM,         /*  5 */
 220   GI_INFO_TYPE_FLAGS,
 221   GI_INFO_TYPE_OBJECT,
 222   GI_INFO_TYPE_INTERFACE,
 223   GI_INFO_TYPE_CONSTANT,
 224   GI_INFO_TYPE_INVALID_0,    /* 10 */  /** DELETED - used to be ERROR_DOMAIN **/
 225   GI_INFO_TYPE_UNION,
 226   GI_INFO_TYPE_VALUE,
 227   GI_INFO_TYPE_SIGNAL,
 228   GI_INFO_TYPE_VFUNC,
 229   GI_INFO_TYPE_PROPERTY,     /* 15 */
 230   GI_INFO_TYPE_FIELD,
 231   GI_INFO_TYPE_ARG,
 232   GI_INFO_TYPE_TYPE,
 233   GI_INFO_TYPE_UNRESOLVED
 234 } GIInfoType;
 235
 236 /**
 237  * GITransfer:
 238  * @GI_TRANSFER_NOTHING: transfer nothing from the callee (function or the type
 239  * instance the property belongs to) to the caller. The callee retains the
 240  * ownership of the transfer and the caller doesn't need to do anything to free
 241  * up the resources of this transfer.
 242  * @GI_TRANSFER_CONTAINER: transfer the container (list, array, hash table) from
 243  * the callee to the caller. The callee retains the ownership of the individual
 244  * items in the container and the caller has to free up the container resources
 245  * (g_list_free()/g_hash_table_destroy() etc) of this transfer.
 246  * @GI_TRANSFER_EVERYTHING: transfer everything, eg the container and its
 247  * contents from the callee to the caller. This is the case when the callee
 248  * creates a copy of all the data it returns. The caller is responsible for
 249  * cleaning up the container and item resources of this transfer.
 250  *
 251  * The transfer is the exchange of data between two parts, from the callee to
 252  * the caller. The callee is either a function/method/signal or an
 253  * object/interface where a property is defined. The caller is the side
 254  * accessing a property or calling a function.
 255  * #GITransfer specifies who's responsible for freeing the resources after the
 256  * ownership transfer is complete. In case of a containing type such as a list,
 257  * an array or a hash table the container itself is specified differently from
 258  * the items within the container itself. Each container is freed differently,
 259  * check the documentation for the types themselves for information on how to
 260  * free them.
 261  */
 262 typedef enum {
 263   GI_TRANSFER_NOTHING,
 264   GI_TRANSFER_CONTAINER,
 265   GI_TRANSFER_EVERYTHING
 266 } GITransfer;
 267
 268 /**
 269  * GIDirection:
 270  * @GI_DIRECTION_IN: in argument.
 271  * @GI_DIRECTION_OUT: out argument.
 272  * @GI_DIRECTION_INOUT: in and out argument.
 273  *
 274  * The direction of a #GIArgInfo.
 275  */
 276 typedef enum  {
 277   GI_DIRECTION_IN,
 278   GI_DIRECTION_OUT,
 279   GI_DIRECTION_INOUT
 280 } GIDirection;
 281
 282 /**
 283  * GIScopeType:
 284  * @GI_SCOPE_TYPE_INVALID: The argument is not of callback type.
 285  * @GI_SCOPE_TYPE_CALL: The callback and associated user_data is only
 286  * used during the call to this function.
 287  * @GI_SCOPE_TYPE_ASYNC: The callback and associated user_data is
 288  * only used until the callback is invoked, and the callback.
 289  * is invoked always exactly once.
 290  * @GI_SCOPE_TYPE_NOTIFIED: The callback and and associated
 291  * user_data is used until the caller is notfied via the destroy_notify.
 292  *
 293  * Scope type of a #GIArgInfo representing callback, determines how the
 294  * callback is invoked and is used to decided when the invoke structs
 295  * can be freed.
 296  */
 297 typedef enum {
 298   GI_SCOPE_TYPE_INVALID,
 299   GI_SCOPE_TYPE_CALL,
 300   GI_SCOPE_TYPE_ASYNC,
 301   GI_SCOPE_TYPE_NOTIFIED
 302 } GIScopeType;
 303
 304 /**
 305  * GITypeTag:
 306  * @GI_TYPE_TAG_VOID: void
 307  * @GI_TYPE_TAG_BOOLEAN: boolean
 308  * @GI_TYPE_TAG_INT8: 8-bit signed integer
 309  * @GI_TYPE_TAG_UINT8: 8-bit unsigned integer
 310  * @GI_TYPE_TAG_INT16: 16-bit signed integer
 311  * @GI_TYPE_TAG_UINT16: 16-bit unsigned integer
 312  * @GI_TYPE_TAG_INT32: 32-bit signed integer
 313  * @GI_TYPE_TAG_UINT32: 32-bit unsigned integer
 314  * @GI_TYPE_TAG_INT64: 64-bit signed integer
 315  * @GI_TYPE_TAG_UINT64: 64-bit unsigned integer
 316  * @GI_TYPE_TAG_FLOAT: float
 317  * @GI_TYPE_TAG_DOUBLE: double floating point
 318  * @GI_TYPE_TAG_UNICHAR: Unicode character
 319  * @GI_TYPE_TAG_GTYPE: a #GType
 320  * @GI_TYPE_TAG_UTF8: a UTF-8 encoded string
 321  * @GI_TYPE_TAG_FILENAME: a filename, encoded in the same encoding
 322  * as the native filesystem is using.
 323  * @GI_TYPE_TAG_ARRAY: an array
 324  * @GI_TYPE_TAG_INTERFACE: an extended interface object
 325  * @GI_TYPE_TAG_GLIST: a #GList
 326  * @GI_TYPE_TAG_GSLIST: a #GSList
 327  * @GI_TYPE_TAG_GHASH: a #GHashTable
 328  * @GI_TYPE_TAG_ERROR: a #GError
 329  *
 330  * The type tag of a #GITypeInfo.
 331  */
 332 typedef enum {
 333   /* Basic types */
 334   GI_TYPE_TAG_VOID      =  0,
 335   GI_TYPE_TAG_BOOLEAN   =  1,
 336   GI_TYPE_TAG_INT8      =  2,
 337   GI_TYPE_TAG_UINT8     =  3,
 338   GI_TYPE_TAG_INT16     =  4,
 339   GI_TYPE_TAG_UINT16    =  5,
 340   GI_TYPE_TAG_INT32     =  6,
 341   GI_TYPE_TAG_UINT32    =  7,
 342   GI_TYPE_TAG_INT64     =  8,
 343   GI_TYPE_TAG_UINT64    =  9,
 344   GI_TYPE_TAG_FLOAT     = 10,
 345   GI_TYPE_TAG_DOUBLE    = 11,
 346   GI_TYPE_TAG_GTYPE     = 12,
 347   GI_TYPE_TAG_UTF8      = 13,
 348   GI_TYPE_TAG_FILENAME  = 14,
 349   /* Non-basic types; compare with G_TYPE_TAG_IS_BASIC */
 350   GI_TYPE_TAG_ARRAY     = 15,
 351   GI_TYPE_TAG_INTERFACE = 16,
 352   GI_TYPE_TAG_GLIST     = 17,
 353   GI_TYPE_TAG_GSLIST    = 18,
 354   GI_TYPE_TAG_GHASH     = 19,
 355   GI_TYPE_TAG_ERROR     = 20,
 356   /* Another basic type */
 357   GI_TYPE_TAG_UNICHAR   = 21
 358   /* Note - there is only room currently for 32 tags.
 359    * See docs/typelib-format.txt SimpleTypeBlob definition */
 360 } GITypeTag;
 361
 362 #define GI_TYPE_TAG_N_TYPES (GI_TYPE_TAG_UNICHAR+1)
 363
 364 /* These were removed and no longer appear in the typelib;
 365  * instead, the machine-specific versions like INT32 are
 366  * always used.
 367  */
 368 #define GI_TYPE_TAG_SHORT GI_TYPE_TAG_SHORT_WAS_REMOVED
 369 #define GI_TYPE_TAG_INT   GI_TYPE_TAG_INT_WAS_REMOVED
 370 #define GI_TYPE_TAG_LONG  GI_TYPE_TAG_LONG_WAS_REMOVED
 371
 372 /**
 373  * GIArrayType:
 374  * @GI_ARRAY_TYPE_C: a C array, char[] for instance
 375  * @GI_ARRAY_TYPE_ARRAY: a @GArray array
 376  * @GI_ARRAY_TYPE_PTR_ARRAY: a #GPtrArray array
 377  * @GI_ARRAY_TYPE_BYTE_ARRAY: a #GByteArray array
 378  *
 379  * The type of array in a #GITypeInfo.
 380  */
 381 typedef enum {
 382   GI_ARRAY_TYPE_C,
 383   GI_ARRAY_TYPE_ARRAY,
 384   GI_ARRAY_TYPE_PTR_ARRAY,
 385   GI_ARRAY_TYPE_BYTE_ARRAY
 386 } GIArrayType;
 387
 388 /**
 389  * GIFieldInfoFlags:
 390  * @GI_FIELD_IS_READABLE: field is readable.
 391  * @GI_FIELD_IS_WRITABLE: field is writable.
 392  *
 393  * Flags for a #GIFieldInfo.
 394  */
 395
 396 typedef enum
 397 {
 398   GI_FIELD_IS_READABLE = 1 << 0,
 399   GI_FIELD_IS_WRITABLE = 1 << 1
 400 } GIFieldInfoFlags;
 401
 402 /**
 403  * GIVFuncInfoFlags:
 404  * @GI_VFUNC_MUST_CHAIN_UP: chains up to the parent type
 405  * @GI_VFUNC_MUST_OVERRIDE: overrides
 406  * @GI_VFUNC_MUST_NOT_OVERRIDE: does not override
 407  * @GI_VFUNC_THROWS: Includes a #GError
 408  *
 409  * Flags of a #GIVFuncInfo struct.
 410  */
 411 typedef enum
 412 {
 413   GI_VFUNC_MUST_CHAIN_UP     = 1 << 0,
 414   GI_VFUNC_MUST_OVERRIDE     = 1 << 1,
 415   GI_VFUNC_MUST_NOT_OVERRIDE = 1 << 2,
 416   GI_VFUNC_THROWS =            1 << 3
 417 } GIVFuncInfoFlags;
 418
 419 /**
 420  * GIFunctionInfoFlags:
 421  * @GI_FUNCTION_IS_METHOD: is a method.
 422  * @GI_FUNCTION_IS_CONSTRUCTOR: is a constructor.
 423  * @GI_FUNCTION_IS_GETTER: is a getter of a #GIPropertyInfo.
 424  * @GI_FUNCTION_IS_SETTER: is a setter of a #GIPropertyInfo.
 425  * @GI_FUNCTION_WRAPS_VFUNC: represents a virtual function.
 426  * @GI_FUNCTION_THROWS: the function may throw an error.
 427  *
 428  * Flags for a #GIFunctionInfo struct.
 429  */
 430 typedef enum
 431 {
 432   GI_FUNCTION_IS_METHOD      = 1 << 0,
 433   GI_FUNCTION_IS_CONSTRUCTOR = 1 << 1,
 434   GI_FUNCTION_IS_GETTER      = 1 << 2,
 435   GI_FUNCTION_IS_SETTER      = 1 << 3,
 436   GI_FUNCTION_WRAPS_VFUNC    = 1 << 4,
 437   GI_FUNCTION_THROWS         = 1 << 5
 438 } GIFunctionInfoFlags;
 439
 440 #ifndef __GI_SCANNER__
 441 /* backwards compatibility */
 442 typedef union _GIArgument GArgument;
 443 typedef struct _GITypelib GTypelib;
 444 #endif
 445
 446 G_END_DECLS
 447
 448 #endif  /* __GITYPES_H__ */
 449