mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-06 01:16:17 +01:00
458cc700ce
Move the SECTION into the struct docs, update the documentation comment syntax, and add `Since: 2.80` everywhere. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3155
503 lines
13 KiB
C
503 lines
13 KiB
C
/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*-
|
|
* GObject introspection: types
|
|
*
|
|
* Copyright (C) 2005 Matthias Clasen
|
|
* Copyright (C) 2008,2009 Red Hat, Inc.
|
|
*
|
|
* SPDX-License-Identifier: LGPL-2.1-or-later
|
|
*
|
|
* This library is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
* License as published by the Free Software Foundation; either
|
|
* version 2 of the License, or (at your option) any later version.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
* License along with this library; if not, write to the
|
|
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
|
* Boston, MA 02111-1307, USA.
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#if !defined (__GIREPOSITORY_H_INSIDE__) && !defined (GI_COMPILATION)
|
|
#error "Only <girepository.h> can be included directly."
|
|
#endif
|
|
|
|
#include <glib.h>
|
|
|
|
G_BEGIN_DECLS
|
|
|
|
typedef struct _GIBaseInfoStub {
|
|
/*< private >*/
|
|
gint32 dummy1;
|
|
gint32 dummy2;
|
|
gpointer dummy3;
|
|
gpointer dummy4;
|
|
gpointer dummy5;
|
|
guint32 dummy6;
|
|
guint32 dummy7;
|
|
gpointer padding[4];
|
|
} GIBaseInfo;
|
|
|
|
/**
|
|
* GICallableInfo:
|
|
*
|
|
* Represents a callable, either #GIFunctionInfo, #GICallbackInfo or
|
|
* #GIVFuncInfo.
|
|
*/
|
|
typedef GIBaseInfo GICallableInfo;
|
|
|
|
/**
|
|
* GIFunctionInfo:
|
|
*
|
|
* Represents a function, eg arguments and return value.
|
|
*/
|
|
typedef GIBaseInfo GIFunctionInfo;
|
|
|
|
/**
|
|
* SECTION:gicallbackinfo
|
|
* @title: GICallbackInfo
|
|
* @short_description: Struct representing a callback
|
|
*
|
|
* GICallbackInfo represents a callback.
|
|
*/
|
|
|
|
/**
|
|
* GICallbackInfo:
|
|
*
|
|
* Represents a callback, eg arguments and return value.
|
|
*/
|
|
typedef GIBaseInfo GICallbackInfo;
|
|
|
|
/**
|
|
* GIRegisteredTypeInfo:
|
|
*
|
|
* Represent a registered type.
|
|
*/
|
|
typedef GIBaseInfo GIRegisteredTypeInfo;
|
|
|
|
/**
|
|
* GIStructInfo:
|
|
*
|
|
* Represents a struct.
|
|
*/
|
|
typedef GIBaseInfo GIStructInfo;
|
|
|
|
/**
|
|
* GIUnionInfo:
|
|
*
|
|
* Represents a union.
|
|
*/
|
|
typedef GIBaseInfo GIUnionInfo;
|
|
|
|
/**
|
|
* GIEnumInfo:
|
|
*
|
|
* Represents an enum or a flag.
|
|
*/
|
|
typedef GIBaseInfo GIEnumInfo;
|
|
|
|
/**
|
|
* GIObjectInfo:
|
|
*
|
|
* Represents an object.
|
|
*/
|
|
typedef GIBaseInfo GIObjectInfo;
|
|
|
|
/**
|
|
* GIInterfaceInfo:
|
|
*
|
|
* Represents an interface.
|
|
*/
|
|
typedef GIBaseInfo GIInterfaceInfo;
|
|
|
|
/**
|
|
* GIConstantInfo:
|
|
*
|
|
* Represents a constant.
|
|
*/
|
|
typedef GIBaseInfo GIConstantInfo;
|
|
|
|
/**
|
|
* SECTION:givalueinfo
|
|
* @title: GIValueInfo
|
|
* @short_description: Struct representing a value
|
|
*
|
|
* GIValueInfo represents a value.
|
|
*/
|
|
|
|
/**
|
|
* GIValueInfo:
|
|
*
|
|
* Represents a enum value of a #GIEnumInfo.
|
|
*/
|
|
typedef GIBaseInfo GIValueInfo;
|
|
|
|
/**
|
|
* GISignalInfo:
|
|
*
|
|
* Represents a signal.
|
|
*/
|
|
typedef GIBaseInfo GISignalInfo;
|
|
|
|
/* Documented in givfuncinfo.c */
|
|
typedef GIBaseInfo GIVFuncInfo;
|
|
|
|
/**
|
|
* GIPropertyInfo:
|
|
*
|
|
* Represents a property of a #GIObjectInfo or a #GIInterfaceInfo.
|
|
*/
|
|
typedef GIBaseInfo GIPropertyInfo;
|
|
|
|
/**
|
|
* GIFieldInfo:
|
|
*
|
|
* Represents a field of a #GIStructInfo or a #GIUnionInfo.
|
|
*/
|
|
typedef GIBaseInfo GIFieldInfo;
|
|
|
|
/**
|
|
* GIArgInfo:
|
|
*
|
|
* Represents an argument.
|
|
*/
|
|
typedef GIBaseInfo GIArgInfo;
|
|
|
|
/**
|
|
* GITypeInfo:
|
|
*
|
|
* Represents type information, direction, transfer etc.
|
|
*/
|
|
typedef GIBaseInfo GITypeInfo;
|
|
|
|
/**
|
|
* GIUnresolvedInfo:
|
|
*
|
|
* Represents a unresolved type in a typelib.
|
|
*/
|
|
typedef struct _GIUnresolvedInfo GIUnresolvedInfo;
|
|
|
|
union _GIArgument
|
|
{
|
|
gboolean v_boolean;
|
|
gint8 v_int8;
|
|
guint8 v_uint8;
|
|
gint16 v_int16;
|
|
guint16 v_uint16;
|
|
gint32 v_int32;
|
|
guint32 v_uint32;
|
|
gint64 v_int64;
|
|
guint64 v_uint64;
|
|
gfloat v_float;
|
|
gdouble v_double;
|
|
gshort v_short;
|
|
gushort v_ushort;
|
|
gint v_int;
|
|
guint v_uint;
|
|
glong v_long;
|
|
gulong v_ulong;
|
|
gssize v_ssize;
|
|
gsize v_size;
|
|
gchar * v_string;
|
|
gpointer v_pointer;
|
|
};
|
|
|
|
/**
|
|
* GIArgument:
|
|
* @v_boolean: TODO
|
|
* @v_int8: TODO
|
|
* @v_uint8: TODO
|
|
* @v_int16: TODO
|
|
* @v_uint16: TODO
|
|
* @v_int32: TODO
|
|
* @v_uint32: TODO
|
|
* @v_int64: TODO
|
|
* @v_uint64: TODO
|
|
* @v_float: TODO
|
|
* @v_double: TODO
|
|
* @v_short: TODO
|
|
* @v_ushort: TODO
|
|
* @v_int: TODO
|
|
* @v_uint: TODO
|
|
* @v_long: TODO
|
|
* @v_ulong: TODO
|
|
* @v_ssize: TODO
|
|
* @v_size: TODO
|
|
* @v_string: TODO
|
|
* @v_pointer: TODO
|
|
*
|
|
* Stores an argument of varying type
|
|
*/
|
|
typedef union _GIArgument GIArgument;
|
|
|
|
/**
|
|
* GIInfoType:
|
|
* @GI_INFO_TYPE_INVALID: invalid type
|
|
* @GI_INFO_TYPE_FUNCTION: function, see #GIFunctionInfo
|
|
* @GI_INFO_TYPE_CALLBACK: callback, see #GIFunctionInfo
|
|
* @GI_INFO_TYPE_STRUCT: struct, see #GIStructInfo
|
|
* @GI_INFO_TYPE_BOXED: boxed, see #GIStructInfo or #GIUnionInfo
|
|
* @GI_INFO_TYPE_ENUM: enum, see #GIEnumInfo
|
|
* @GI_INFO_TYPE_FLAGS: flags, see #GIEnumInfo
|
|
* @GI_INFO_TYPE_OBJECT: object, see #GIObjectInfo
|
|
* @GI_INFO_TYPE_INTERFACE: interface, see #GIInterfaceInfo
|
|
* @GI_INFO_TYPE_CONSTANT: contant, see #GIConstantInfo
|
|
* @GI_INFO_TYPE_INVALID_0: deleted, used to be GI_INFO_TYPE_ERROR_DOMAIN.
|
|
* @GI_INFO_TYPE_UNION: union, see #GIUnionInfo
|
|
* @GI_INFO_TYPE_VALUE: enum value, see #GIValueInfo
|
|
* @GI_INFO_TYPE_SIGNAL: signal, see #GISignalInfo
|
|
* @GI_INFO_TYPE_VFUNC: virtual function, see #GIVFuncInfo
|
|
* @GI_INFO_TYPE_PROPERTY: GObject property, see #GIPropertyInfo
|
|
* @GI_INFO_TYPE_FIELD: struct or union field, see #GIFieldInfo
|
|
* @GI_INFO_TYPE_ARG: argument of a function or callback, see #GIArgInfo
|
|
* @GI_INFO_TYPE_TYPE: type information, see #GITypeInfo
|
|
* @GI_INFO_TYPE_UNRESOLVED: unresolved type, a type which is not present in
|
|
* the typelib, or any of its dependencies.
|
|
*
|
|
* The type of a GIBaseInfo struct.
|
|
*/
|
|
typedef enum
|
|
{
|
|
GI_INFO_TYPE_INVALID,
|
|
GI_INFO_TYPE_FUNCTION,
|
|
GI_INFO_TYPE_CALLBACK,
|
|
GI_INFO_TYPE_STRUCT,
|
|
GI_INFO_TYPE_BOXED,
|
|
GI_INFO_TYPE_ENUM, /* 5 */
|
|
GI_INFO_TYPE_FLAGS,
|
|
GI_INFO_TYPE_OBJECT,
|
|
GI_INFO_TYPE_INTERFACE,
|
|
GI_INFO_TYPE_CONSTANT,
|
|
GI_INFO_TYPE_INVALID_0, /* 10 */
|
|
GI_INFO_TYPE_UNION,
|
|
GI_INFO_TYPE_VALUE,
|
|
GI_INFO_TYPE_SIGNAL,
|
|
GI_INFO_TYPE_VFUNC,
|
|
GI_INFO_TYPE_PROPERTY, /* 15 */
|
|
GI_INFO_TYPE_FIELD,
|
|
GI_INFO_TYPE_ARG,
|
|
GI_INFO_TYPE_TYPE,
|
|
GI_INFO_TYPE_UNRESOLVED
|
|
} GIInfoType;
|
|
|
|
/**
|
|
* GITransfer:
|
|
* @GI_TRANSFER_NOTHING: transfer nothing from the callee (function or the type
|
|
* instance the property belongs to) to the caller. The callee retains the
|
|
* ownership of the transfer and the caller doesn't need to do anything to free
|
|
* up the resources of this transfer.
|
|
* @GI_TRANSFER_CONTAINER: transfer the container (list, array, hash table) from
|
|
* the callee to the caller. The callee retains the ownership of the individual
|
|
* items in the container and the caller has to free up the container resources
|
|
* (g_list_free()/g_hash_table_destroy() etc) of this transfer.
|
|
* @GI_TRANSFER_EVERYTHING: transfer everything, eg the container and its
|
|
* contents from the callee to the caller. This is the case when the callee
|
|
* creates a copy of all the data it returns. The caller is responsible for
|
|
* cleaning up the container and item resources of this transfer.
|
|
*
|
|
* The transfer is the exchange of data between two parts, from the callee to
|
|
* the caller. The callee is either a function/method/signal or an
|
|
* object/interface where a property is defined. The caller is the side
|
|
* accessing a property or calling a function.
|
|
* #GITransfer specifies who's responsible for freeing the resources after the
|
|
* ownership transfer is complete. In case of a containing type such as a list,
|
|
* an array or a hash table the container itself is specified differently from
|
|
* the items within the container itself. Each container is freed differently,
|
|
* check the documentation for the types themselves for information on how to
|
|
* free them.
|
|
*/
|
|
typedef enum {
|
|
GI_TRANSFER_NOTHING,
|
|
GI_TRANSFER_CONTAINER,
|
|
GI_TRANSFER_EVERYTHING
|
|
} GITransfer;
|
|
|
|
/**
|
|
* GIDirection:
|
|
* @GI_DIRECTION_IN: in argument.
|
|
* @GI_DIRECTION_OUT: out argument.
|
|
* @GI_DIRECTION_INOUT: in and out argument.
|
|
*
|
|
* The direction of a #GIArgInfo.
|
|
*/
|
|
typedef enum {
|
|
GI_DIRECTION_IN,
|
|
GI_DIRECTION_OUT,
|
|
GI_DIRECTION_INOUT
|
|
} GIDirection;
|
|
|
|
/**
|
|
* GIScopeType:
|
|
* @GI_SCOPE_TYPE_INVALID: The argument is not of callback type.
|
|
* @GI_SCOPE_TYPE_CALL: The callback and associated user_data is only
|
|
* used during the call to this function.
|
|
* @GI_SCOPE_TYPE_ASYNC: The callback and associated user_data is
|
|
* only used until the callback is invoked, and the callback.
|
|
* is invoked always exactly once.
|
|
* @GI_SCOPE_TYPE_NOTIFIED: The callback and associated
|
|
* user_data is used until the caller is notfied via the destroy_notify.
|
|
* @GI_SCOPE_TYPE_FOREVER: The callback and associated user_data is
|
|
* used until the process terminates
|
|
*
|
|
* Scope type of a #GIArgInfo representing callback, determines how the
|
|
* callback is invoked and is used to decided when the invoke structs
|
|
* can be freed.
|
|
*/
|
|
typedef enum {
|
|
GI_SCOPE_TYPE_INVALID,
|
|
GI_SCOPE_TYPE_CALL,
|
|
GI_SCOPE_TYPE_ASYNC,
|
|
GI_SCOPE_TYPE_NOTIFIED,
|
|
GI_SCOPE_TYPE_FOREVER
|
|
} GIScopeType;
|
|
|
|
/**
|
|
* GITypeTag:
|
|
* @GI_TYPE_TAG_VOID: void
|
|
* @GI_TYPE_TAG_BOOLEAN: boolean
|
|
* @GI_TYPE_TAG_INT8: 8-bit signed integer
|
|
* @GI_TYPE_TAG_UINT8: 8-bit unsigned integer
|
|
* @GI_TYPE_TAG_INT16: 16-bit signed integer
|
|
* @GI_TYPE_TAG_UINT16: 16-bit unsigned integer
|
|
* @GI_TYPE_TAG_INT32: 32-bit signed integer
|
|
* @GI_TYPE_TAG_UINT32: 32-bit unsigned integer
|
|
* @GI_TYPE_TAG_INT64: 64-bit signed integer
|
|
* @GI_TYPE_TAG_UINT64: 64-bit unsigned integer
|
|
* @GI_TYPE_TAG_FLOAT: float
|
|
* @GI_TYPE_TAG_DOUBLE: double floating point
|
|
* @GI_TYPE_TAG_GTYPE: a #GType
|
|
* @GI_TYPE_TAG_UTF8: a UTF-8 encoded string
|
|
* @GI_TYPE_TAG_FILENAME: a filename, encoded in the same encoding
|
|
* as the native filesystem is using.
|
|
* @GI_TYPE_TAG_ARRAY: an array
|
|
* @GI_TYPE_TAG_INTERFACE: an extended interface object
|
|
* @GI_TYPE_TAG_GLIST: a #GList
|
|
* @GI_TYPE_TAG_GSLIST: a #GSList
|
|
* @GI_TYPE_TAG_GHASH: a #GHashTable
|
|
* @GI_TYPE_TAG_ERROR: a #GError
|
|
* @GI_TYPE_TAG_UNICHAR: Unicode character
|
|
*
|
|
* The type tag of a #GITypeInfo.
|
|
*/
|
|
typedef enum {
|
|
/* Basic types */
|
|
GI_TYPE_TAG_VOID = 0,
|
|
GI_TYPE_TAG_BOOLEAN = 1,
|
|
GI_TYPE_TAG_INT8 = 2, /* Start of GI_TYPE_TAG_IS_NUMERIC types */
|
|
GI_TYPE_TAG_UINT8 = 3,
|
|
GI_TYPE_TAG_INT16 = 4,
|
|
GI_TYPE_TAG_UINT16 = 5,
|
|
GI_TYPE_TAG_INT32 = 6,
|
|
GI_TYPE_TAG_UINT32 = 7,
|
|
GI_TYPE_TAG_INT64 = 8,
|
|
GI_TYPE_TAG_UINT64 = 9,
|
|
GI_TYPE_TAG_FLOAT = 10,
|
|
GI_TYPE_TAG_DOUBLE = 11, /* End of numeric types */
|
|
GI_TYPE_TAG_GTYPE = 12,
|
|
GI_TYPE_TAG_UTF8 = 13,
|
|
GI_TYPE_TAG_FILENAME = 14,
|
|
/* Non-basic types; compare with GI_TYPE_TAG_IS_BASIC */
|
|
GI_TYPE_TAG_ARRAY = 15, /* container (see GI_TYPE_TAG_IS_CONTAINER) */
|
|
GI_TYPE_TAG_INTERFACE = 16,
|
|
GI_TYPE_TAG_GLIST = 17, /* container */
|
|
GI_TYPE_TAG_GSLIST = 18, /* container */
|
|
GI_TYPE_TAG_GHASH = 19, /* container */
|
|
GI_TYPE_TAG_ERROR = 20,
|
|
/* Another basic type */
|
|
GI_TYPE_TAG_UNICHAR = 21
|
|
/* Note - there is currently only room for 32 tags */
|
|
} GITypeTag;
|
|
|
|
/**
|
|
* GI_TYPE_TAG_N_TYPES:
|
|
*
|
|
* TODO
|
|
*/
|
|
#define GI_TYPE_TAG_N_TYPES (GI_TYPE_TAG_UNICHAR+1)
|
|
|
|
#ifndef __GTK_DOC_IGNORE__
|
|
/* These were removed and no longer appear in the typelib;
|
|
* instead, the machine-specific versions like INT32 are
|
|
* always used.
|
|
*/
|
|
#define GI_TYPE_TAG_SHORT GI_TYPE_TAG_SHORT_WAS_REMOVED
|
|
#define GI_TYPE_TAG_INT GI_TYPE_TAG_INT_WAS_REMOVED
|
|
#define GI_TYPE_TAG_LONG GI_TYPE_TAG_LONG_WAS_REMOVED
|
|
#endif
|
|
|
|
/**
|
|
* GIArrayType:
|
|
* @GI_ARRAY_TYPE_C: a C array, char[] for instance
|
|
* @GI_ARRAY_TYPE_ARRAY: a @GArray array
|
|
* @GI_ARRAY_TYPE_PTR_ARRAY: a #GPtrArray array
|
|
* @GI_ARRAY_TYPE_BYTE_ARRAY: a #GByteArray array
|
|
*
|
|
* The type of array in a #GITypeInfo.
|
|
*/
|
|
typedef enum {
|
|
GI_ARRAY_TYPE_C,
|
|
GI_ARRAY_TYPE_ARRAY,
|
|
GI_ARRAY_TYPE_PTR_ARRAY,
|
|
GI_ARRAY_TYPE_BYTE_ARRAY
|
|
} GIArrayType;
|
|
|
|
/**
|
|
* GIFieldInfoFlags:
|
|
* @GI_FIELD_IS_READABLE: field is readable.
|
|
* @GI_FIELD_IS_WRITABLE: field is writable.
|
|
*
|
|
* Flags for a #GIFieldInfo.
|
|
*/
|
|
|
|
typedef enum
|
|
{
|
|
GI_FIELD_IS_READABLE = 1 << 0,
|
|
GI_FIELD_IS_WRITABLE = 1 << 1
|
|
} GIFieldInfoFlags;
|
|
|
|
/**
|
|
* GIVFuncInfoFlags:
|
|
* @GI_VFUNC_MUST_CHAIN_UP: chains up to the parent type
|
|
* @GI_VFUNC_MUST_OVERRIDE: overrides
|
|
* @GI_VFUNC_MUST_NOT_OVERRIDE: does not override
|
|
* @GI_VFUNC_THROWS: Includes a #GError
|
|
*
|
|
* Flags of a #GIVFuncInfo struct.
|
|
*/
|
|
typedef enum
|
|
{
|
|
GI_VFUNC_MUST_CHAIN_UP = 1 << 0,
|
|
GI_VFUNC_MUST_OVERRIDE = 1 << 1,
|
|
GI_VFUNC_MUST_NOT_OVERRIDE = 1 << 2,
|
|
GI_VFUNC_THROWS = 1 << 3
|
|
} GIVFuncInfoFlags;
|
|
|
|
/**
|
|
* GIFunctionInfoFlags:
|
|
* @GI_FUNCTION_IS_METHOD: is a method.
|
|
* @GI_FUNCTION_IS_CONSTRUCTOR: is a constructor.
|
|
* @GI_FUNCTION_IS_GETTER: is a getter of a #GIPropertyInfo.
|
|
* @GI_FUNCTION_IS_SETTER: is a setter of a #GIPropertyInfo.
|
|
* @GI_FUNCTION_WRAPS_VFUNC: represents a virtual function.
|
|
* @GI_FUNCTION_THROWS: the function may throw an error.
|
|
*
|
|
* Flags for a #GIFunctionInfo struct.
|
|
*/
|
|
typedef enum
|
|
{
|
|
GI_FUNCTION_IS_METHOD = 1 << 0,
|
|
GI_FUNCTION_IS_CONSTRUCTOR = 1 << 1,
|
|
GI_FUNCTION_IS_GETTER = 1 << 2,
|
|
GI_FUNCTION_IS_SETTER = 1 << 3,
|
|
GI_FUNCTION_WRAPS_VFUNC = 1 << 4,
|
|
GI_FUNCTION_THROWS = 1 << 5
|
|
} GIFunctionInfoFlags;
|
|
|
|
G_END_DECLS
|