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 * SPDX-License-Identifier: LGPL-2.1-or-later
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation; either
12 * version 2 of the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library; if not, write to the
21 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22 * Boston, MA 02111-1307, USA.
23 */
24
25 #pragma once
26
27 #if !defined (__GIREPOSITORY_H_INSIDE__) && !defined (GI_COMPILATION)
28 #error "Only <girepository.h> can be included directly."
29 #endif
30
31 #include <glib.h>
32 #include <glib-object.h>
33
34 #include "gi-visibility.h"
35
36 G_BEGIN_DECLS
37
38 /* Documented in gibaseinfo.c */
39 typedef struct _GIBaseInfo GIBaseInfo;
40 typedef struct _GIBaseInfoClass GIBaseInfoClass;
41
42 /* Documented in gicallableinfo.c */
43 typedef struct _GICallableInfo GICallableInfo;
44 GI_AVAILABLE_IN_ALL GType gi_callable_info_get_type (void);
45
46 /* Documented in gifunctioninfo.c */
47 typedef struct _GIFunctionInfo GIFunctionInfo;
48 GI_AVAILABLE_IN_ALL GType gi_function_info_get_type (void);
49
50 /* Documented in gicallbackinfo.c */
51 typedef struct _GICallbackInfo GICallbackInfo;
52 GI_AVAILABLE_IN_ALL GType gi_callback_info_get_type (void);
53
54 /* Documented in giregisteredtypeinfo.c */
55 typedef struct _GIRegisteredTypeInfo GIRegisteredTypeInfo;
56 GI_AVAILABLE_IN_ALL GType gi_registered_type_info_get_type (void);
57
58 /* Documented in gistructinfo.c */
59 typedef struct _GIStructInfo GIStructInfo;
60 GI_AVAILABLE_IN_ALL GType gi_struct_info_get_type (void);
61
62 /* Documented in giunioninfo.c */
63 typedef struct _GIUnionInfo GIUnionInfo;
64 GI_AVAILABLE_IN_ALL GType gi_union_info_get_type (void);
65
66 /* Documented in gienuminfo.c */
67 typedef struct _GIEnumInfo GIEnumInfo;
68 GI_AVAILABLE_IN_ALL GType gi_enum_info_get_type (void);
69
70 /* Documented in giobjectinfo.c */
71 typedef struct _GIObjectInfo GIObjectInfo;
72 GI_AVAILABLE_IN_ALL GType gi_object_info_get_type (void);
73
74 /* Documented in giinterfaceinfo.c */
75 typedef struct _GIInterfaceInfo GIInterfaceInfo;
76 GI_AVAILABLE_IN_ALL GType gi_interface_info_get_type (void);
77
78 /* Documented in giconstantinfo.c */
79 typedef struct _GIConstantInfo GIConstantInfo;
80 GI_AVAILABLE_IN_ALL GType gi_constant_info_get_type (void);
81
82 /* Documented in givalueinfo.c */
83 typedef struct _GIValueInfo GIValueInfo;
84 GI_AVAILABLE_IN_ALL GType gi_value_info_get_type (void);
85
86 /* Documented in gisignalinfo.c */
87 typedef struct _GISignalInfo GISignalInfo;
88 GI_AVAILABLE_IN_ALL GType gi_signal_info_get_type (void);
89
90 /* Documented in givfuncinfo.c */
91 typedef struct _GIVFuncInfo GIVFuncInfo;
92 GI_AVAILABLE_IN_ALL GType gi_vfunc_info_get_type (void);
93
94 /* Documented in gipropertyinfo.c */
95 typedef struct _GIPropertyInfo GIPropertyInfo;
96 GI_AVAILABLE_IN_ALL GType gi_property_info_get_type (void);
97
98 /* Documented in gifieldinfo.c */
99 typedef struct _GIFieldInfo GIFieldInfo;
100 GI_AVAILABLE_IN_ALL GType gi_field_info_get_type (void);
101
102 /* Documented in giarginfo.c */
103 typedef struct _GIArgInfo GIArgInfo;
104 GI_AVAILABLE_IN_ALL GType gi_arg_info_get_type (void);
105
106 /* Documented in gitypeinfo.c */
107 typedef struct _GITypeInfo GITypeInfo;
108 GI_AVAILABLE_IN_ALL GType gi_type_info_get_type (void);
109
110 /* Documented in giunresolvedinfo.c */
111 typedef struct _GIUnresolvedInfo GIUnresolvedInfo;
112 GI_AVAILABLE_IN_ALL GType gi_unresolved_info_get_type (void);
113
114 union _GIArgument
115 {
116 gboolean v_boolean;
117 gint8 v_int8;
118 guint8 v_uint8;
119 gint16 v_int16;
120 guint16 v_uint16;
121 gint32 v_int32;
122 guint32 v_uint32;
123 gint64 v_int64;
124 guint64 v_uint64;
125 gfloat v_float;
126 gdouble v_double;
127 gshort v_short;
128 gushort v_ushort;
129 gint v_int;
130 guint v_uint;
131 glong v_long;
132 gulong v_ulong;
133 gssize v_ssize;
134 gsize v_size;
135 gchar * v_string;
136 gpointer v_pointer;
137 };
138
139 /**
140 * GIArgument:
141 * @v_boolean: boolean value
142 * @v_int8: 8-bit signed integer value
143 * @v_uint8: 8-bit unsigned integer value
144 * @v_int16: 16-bit signed integer value
145 * @v_uint16: 16-bit unsigned integer value
146 * @v_int32: 32-bit signed integer value
147 * @v_uint32: 32-bit unsigned integer value
148 * @v_int64: 64-bit signed integer value
149 * @v_uint64: 64-bit unsigned integer value
150 * @v_float: single float value
151 * @v_double: double float value
152 * @v_short: signed short integer value
153 * @v_ushort: unsigned short integer value
154 * @v_int: signed integer value
155 * @v_uint: unsigned integer value
156 * @v_long: signed long integer value
157 * @v_ulong: unsigned long integer value
158 * @v_ssize: sized `size_t` value
159 * @v_size: unsigned `size_t` value
160 * @v_string: nul-terminated string value
161 * @v_pointer: arbitrary pointer value
162 *
163 * Stores an argument of varying type.
164 *
165 * Since: 2.80
166 */
167 typedef union _GIArgument GIArgument;
168
169 /**
170 * GIInfoType:
171 * @GI_INFO_TYPE_INVALID: invalid type
172 * @GI_INFO_TYPE_FUNCTION: function, see [class@GIRepository.FunctionInfo]
173 * @GI_INFO_TYPE_CALLBACK: callback, see [class@GIRepository.FunctionInfo]
174 * @GI_INFO_TYPE_STRUCT: struct, see [class@GIRepository.StructInfo]
175 * @GI_INFO_TYPE_BOXED: boxed, see [class@GIRepository.StructInfo] or
176 * [class@GIRepository.UnionInfo]
177 * @GI_INFO_TYPE_ENUM: enum, see [class@GIRepository.EnumInfo]
178 * @GI_INFO_TYPE_FLAGS: flags, see [class@GIRepository.EnumInfo]
179 * @GI_INFO_TYPE_OBJECT: object, see [class@GIRepository.ObjectInfo]
180 * @GI_INFO_TYPE_INTERFACE: interface, see [class@GIRepository.InterfaceInfo]
181 * @GI_INFO_TYPE_CONSTANT: constant, see [class@GIRepository.ConstantInfo]
182 * @GI_INFO_TYPE_INVALID_0: deleted, used to be `GI_INFO_TYPE_ERROR_DOMAIN`.
183 * @GI_INFO_TYPE_UNION: union, see [class@GIRepository.UnionInfo]
184 * @GI_INFO_TYPE_VALUE: enum value, see [class@GIRepository.ValueInfo]
185 * @GI_INFO_TYPE_SIGNAL: signal, see [class@GIRepository.SignalInfo]
186 * @GI_INFO_TYPE_VFUNC: virtual function, see [class@GIRepository.VFuncInfo]
187 * @GI_INFO_TYPE_PROPERTY: [class@GObject.Object] property, see
188 * [class@GIRepository.PropertyInfo]
189 * @GI_INFO_TYPE_FIELD: struct or union field, see
190 * [class@GIRepository.FieldInfo]
191 * @GI_INFO_TYPE_ARG: argument of a function or callback, see
192 * [class@GIRepository.ArgInfo]
193 * @GI_INFO_TYPE_TYPE: type information, see [class@GIRepository.TypeInfo]
194 * @GI_INFO_TYPE_UNRESOLVED: unresolved type, a type which is not present in
195 * the typelib, or any of its dependencies, see
196 * [class@GIRepository.UnresolvedInfo]
197 * @GI_INFO_TYPE_CALLABLE: an abstract type representing any callable (function,
198 * callback, vfunc), see [class@GIRepository.CallableInfo]
199 * @GI_INFO_TYPE_REGISTERED_TYPE: an abstract type representing any registered
200 * type (enum, interface, object, struct, union), see
201 * [class@GIRepository.RegisteredTypeInfo]
202 *
203 * The type of a [class@GIRepository.BaseInfo] struct.
204 *
205 * See [const@GIRepository.INFO_TYPE_N_TYPES] for the total number of elements
206 * in this enum.
207 *
208 * Since: 2.80
209 */
210 typedef enum
211 {
212 GI_INFO_TYPE_INVALID,
213 GI_INFO_TYPE_FUNCTION,
214 GI_INFO_TYPE_CALLBACK,
215 GI_INFO_TYPE_STRUCT,
216 GI_INFO_TYPE_BOXED,
217 GI_INFO_TYPE_ENUM, /* 5 */
218 GI_INFO_TYPE_FLAGS,
219 GI_INFO_TYPE_OBJECT,
220 GI_INFO_TYPE_INTERFACE,
221 GI_INFO_TYPE_CONSTANT,
222 GI_INFO_TYPE_INVALID_0, /* 10 */
223 GI_INFO_TYPE_UNION,
224 GI_INFO_TYPE_VALUE,
225 GI_INFO_TYPE_SIGNAL,
226 GI_INFO_TYPE_VFUNC,
227 GI_INFO_TYPE_PROPERTY, /* 15 */
228 GI_INFO_TYPE_FIELD,
229 GI_INFO_TYPE_ARG,
230 GI_INFO_TYPE_TYPE,
231 GI_INFO_TYPE_UNRESOLVED,
232 GI_INFO_TYPE_CALLABLE, /* 20 */
233 GI_INFO_TYPE_REGISTERED_TYPE,
234 /* keep GI_INFO_TYPE_N_TYPES in sync with this */
235 } GIInfoType;
236
237 /**
238 * GI_INFO_TYPE_N_TYPES:
239 *
240 * Number of entries in [enum@GIRepository.InfoType].
241 *
242 * Since: 2.80
243 */
244 #define GI_INFO_TYPE_N_TYPES (GI_INFO_TYPE_REGISTERED_TYPE + 1)
245
246 /**
247 * GITransfer:
248 * @GI_TRANSFER_NOTHING: Transfer nothing from the callee (function or the type
249 * instance the property belongs to) to the caller. The callee retains the
250 * ownership of the transfer and the caller doesn’t need to do anything to
251 * free up the resources of this transfer.
252 * @GI_TRANSFER_CONTAINER: Transfer the container (list, array, hash table) from
253 * the callee to the caller. The callee retains the ownership of the
254 * individual items in the container and the caller has to free up the
255 * container resources ([func@GLib.List.free],
256 * [func@GLib.HashTable.destroy], etc) of this transfer.
257 * @GI_TRANSFER_EVERYTHING: Transfer everything, e.g. the container and its
258 * contents from the callee to the caller. This is the case when the callee
259 * creates a copy of all the data it returns. The caller is responsible for
260 * cleaning up the container and item resources of this transfer.
261 *
262 * `GITransfer` specifies who’s responsible for freeing the resources after an
263 * ownership transfer is complete.
264 *
265 * The transfer is the exchange of data between two parts, from the callee to
266 * the caller.
267 *
268 * The callee is either a function/method/signal or an object/interface where a
269 * property is defined. The caller is the side accessing a property or calling a
270 * function.
271 *
272 * In the case of a containing type such as a list, an array or a hash table the
273 * container itself is specified differently from the items within the
274 * container. Each container is freed differently, check the documentation for
275 * the types themselves for information on how to free them.
276 *
277 * Since: 2.80
278 */
279 typedef enum {
280 GI_TRANSFER_NOTHING,
281 GI_TRANSFER_CONTAINER,
282 GI_TRANSFER_EVERYTHING
283 } GITransfer;
284
285 /**
286 * GIDirection:
287 * @GI_DIRECTION_IN: ‘in’ argument.
288 * @GI_DIRECTION_OUT: ‘out’ argument.
289 * @GI_DIRECTION_INOUT: ‘in and out’ argument.
290 *
291 * The direction of a [class@GIRepository.ArgInfo].
292 *
293 * Since: 2.80
294 */
295 typedef enum {
296 GI_DIRECTION_IN,
297 GI_DIRECTION_OUT,
298 GI_DIRECTION_INOUT
299 } GIDirection;
300
301 /**
302 * GIScopeType:
303 * @GI_SCOPE_TYPE_INVALID: The argument is not of callback type.
304 * @GI_SCOPE_TYPE_CALL: The callback and associated `user_data` is only
305 * used during the call to this function.
306 * @GI_SCOPE_TYPE_ASYNC: The callback and associated `user_data` is
307 * only used until the callback is invoked, and the callback.
308 * is invoked always exactly once.
309 * @GI_SCOPE_TYPE_NOTIFIED: The callback and associated
310 * `user_data` is used until the caller is notified via the
311 * [type@GLib.DestroyNotify].
312 * @GI_SCOPE_TYPE_FOREVER: The callback and associated `user_data` is
313 * used until the process terminates
314 *
315 * Scope type of a [class@GIRepository.ArgInfo] representing callback,
316 * determines how the callback is invoked and is used to decided when the invoke
317 * structs can be freed.
318 *
319 * Since: 2.80
320 */
321 typedef enum {
322 GI_SCOPE_TYPE_INVALID,
323 GI_SCOPE_TYPE_CALL,
324 GI_SCOPE_TYPE_ASYNC,
325 GI_SCOPE_TYPE_NOTIFIED,
326 GI_SCOPE_TYPE_FOREVER
327 } GIScopeType;
328
329 /**
330 * GITypeTag:
331 * @GI_TYPE_TAG_VOID: void
332 * @GI_TYPE_TAG_BOOLEAN: boolean
333 * @GI_TYPE_TAG_INT8: 8-bit signed integer
334 * @GI_TYPE_TAG_UINT8: 8-bit unsigned integer
335 * @GI_TYPE_TAG_INT16: 16-bit signed integer
336 * @GI_TYPE_TAG_UINT16: 16-bit unsigned integer
337 * @GI_TYPE_TAG_INT32: 32-bit signed integer
338 * @GI_TYPE_TAG_UINT32: 32-bit unsigned integer
339 * @GI_TYPE_TAG_INT64: 64-bit signed integer
340 * @GI_TYPE_TAG_UINT64: 64-bit unsigned integer
341 * @GI_TYPE_TAG_FLOAT: float
342 * @GI_TYPE_TAG_DOUBLE: double floating point
343 * @GI_TYPE_TAG_GTYPE: a [type@GObject.Type]
344 * @GI_TYPE_TAG_UTF8: a UTF-8 encoded string
345 * @GI_TYPE_TAG_FILENAME: a filename, encoded in the same encoding
346 * as the native filesystem is using.
347 * @GI_TYPE_TAG_ARRAY: an array
348 * @GI_TYPE_TAG_INTERFACE: an extended interface object
349 * @GI_TYPE_TAG_GLIST: a [type@GLib.List]
350 * @GI_TYPE_TAG_GSLIST: a [type@GLib.SList]
351 * @GI_TYPE_TAG_GHASH: a [type@GLib.HashTable]
352 * @GI_TYPE_TAG_ERROR: a [type@GLib.Error]
353 * @GI_TYPE_TAG_UNICHAR: Unicode character
354 *
355 * The type tag of a [class@GIRepository.TypeInfo].
356 *
357 * Since: 2.80
358 */
359 typedef enum {
360 /* Basic types */
361 GI_TYPE_TAG_VOID = 0,
362 GI_TYPE_TAG_BOOLEAN = 1,
363 GI_TYPE_TAG_INT8 = 2, /* Start of GI_TYPE_TAG_IS_NUMERIC types */
364 GI_TYPE_TAG_UINT8 = 3,
365 GI_TYPE_TAG_INT16 = 4,
366 GI_TYPE_TAG_UINT16 = 5,
367 GI_TYPE_TAG_INT32 = 6,
368 GI_TYPE_TAG_UINT32 = 7,
369 GI_TYPE_TAG_INT64 = 8,
370 GI_TYPE_TAG_UINT64 = 9,
371 GI_TYPE_TAG_FLOAT = 10,
372 GI_TYPE_TAG_DOUBLE = 11, /* End of numeric types */
373 GI_TYPE_TAG_GTYPE = 12,
374 GI_TYPE_TAG_UTF8 = 13,
375 GI_TYPE_TAG_FILENAME = 14,
376 /* Non-basic types; compare with GI_TYPE_TAG_IS_BASIC */
377 GI_TYPE_TAG_ARRAY = 15, /* container (see GI_TYPE_TAG_IS_CONTAINER) */
378 GI_TYPE_TAG_INTERFACE = 16,
379 GI_TYPE_TAG_GLIST = 17, /* container */
380 GI_TYPE_TAG_GSLIST = 18, /* container */
381 GI_TYPE_TAG_GHASH = 19, /* container */
382 GI_TYPE_TAG_ERROR = 20,
383 /* Another basic type */
384 GI_TYPE_TAG_UNICHAR = 21
385 /* Note - there is currently only room for 32 tags */
386 } GITypeTag;
387
388 /**
389 * GI_TYPE_TAG_N_TYPES:
390 *
391 * Number of entries in [enum@GIRepository.TypeTag].
392 *
393 * Since: 2.80
394 */
395 #define GI_TYPE_TAG_N_TYPES (GI_TYPE_TAG_UNICHAR+1)
396
397 /**
398 * GIArrayType:
399 * @GI_ARRAY_TYPE_C: a C array, `char[]` for instance
400 * @GI_ARRAY_TYPE_ARRAY: a [type@GLib.Array] array
401 * @GI_ARRAY_TYPE_PTR_ARRAY: a [type@GLib.PtrArray] array
402 * @GI_ARRAY_TYPE_BYTE_ARRAY: a [type@GLib.ByteArray] array
403 *
404 * The type of array in a [class@GIRepository.TypeInfo].
405 *
406 * Since: 2.80
407 */
408 typedef enum {
409 GI_ARRAY_TYPE_C,
410 GI_ARRAY_TYPE_ARRAY,
411 GI_ARRAY_TYPE_PTR_ARRAY,
412 GI_ARRAY_TYPE_BYTE_ARRAY
413 } GIArrayType;
414
415 /**
416 * GIFieldInfoFlags:
417 * @GI_FIELD_IS_READABLE: field is readable.
418 * @GI_FIELD_IS_WRITABLE: field is writable.
419 *
420 * Flags for a [class@GIRepository.FieldInfo].
421 *
422 * Since: 2.80
423 */
424
425 typedef enum
426 {
427 GI_FIELD_IS_READABLE = 1 << 0,
428 GI_FIELD_IS_WRITABLE = 1 << 1
429 } GIFieldInfoFlags;
430
431 /**
432 * GIVFuncInfoFlags:
433 * @GI_VFUNC_MUST_CHAIN_UP: chains up to the parent type
434 * @GI_VFUNC_MUST_OVERRIDE: overrides
435 * @GI_VFUNC_MUST_NOT_OVERRIDE: does not override
436 * @GI_VFUNC_THROWS: includes a [type@GLib.Error]
437 *
438 * Flags of a [class@GIRepository.VFuncInfo] struct.
439 *
440 * Since: 2.80
441 */
442 typedef enum
443 {
444 GI_VFUNC_MUST_CHAIN_UP = 1 << 0,
445 GI_VFUNC_MUST_OVERRIDE = 1 << 1,
446 GI_VFUNC_MUST_NOT_OVERRIDE = 1 << 2,
447 GI_VFUNC_THROWS = 1 << 3
448 } GIVFuncInfoFlags;
449
450 /**
451 * GIFunctionInfoFlags:
452 * @GI_FUNCTION_IS_METHOD: is a method.
453 * @GI_FUNCTION_IS_CONSTRUCTOR: is a constructor.
454 * @GI_FUNCTION_IS_GETTER: is a getter of a [class@GIRepository.PropertyInfo].
455 * @GI_FUNCTION_IS_SETTER: is a setter of a [class@GIRepository.PropertyInfo].
456 * @GI_FUNCTION_WRAPS_VFUNC: represents a virtual function.
457 * @GI_FUNCTION_THROWS: the function may throw an error.
458 *
459 * Flags for a [class@GIRepository.FunctionInfo] struct.
460 *
461 * Since: 2.80
462 */
463 typedef enum
464 {
465 GI_FUNCTION_IS_METHOD = 1 << 0,
466 GI_FUNCTION_IS_CONSTRUCTOR = 1 << 1,
467 GI_FUNCTION_IS_GETTER = 1 << 2,
468 GI_FUNCTION_IS_SETTER = 1 << 3,
469 GI_FUNCTION_WRAPS_VFUNC = 1 << 4,
470 GI_FUNCTION_THROWS = 1 << 5
471 } GIFunctionInfoFlags;
472
473 G_END_DECLS