Bug 556489 – callback annotations
[gnome.gobject-introspection] / girepository / girepository.h
1 /* GObject introspection: Repository
2  *
3  * Copyright (C) 2005 Matthias Clasen
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 Public
16  * 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
21 #ifndef __G_IREPOSITORY_H__
22 #define __G_IREPOSITORY_H__
23
24 #include <glib-object.h>
25 #include <gmodule.h>
26
27 G_BEGIN_DECLS
28
29 #define G_TYPE_IREPOSITORY      (g_irepository_get_type ())
30 #define G_IREPOSITORY(obj)      (G_TYPE_CHECK_INSTANCE_CAST ((obj), G_TYPE_IREPOSITORY, GIRepository))
31
32 typedef struct _GIRepository         GIRepository; 
33 typedef struct _GIRepositoryClass    GIRepositoryClass; 
34 typedef struct _GIRepositoryPrivate  GIRepositoryPrivate; 
35 typedef struct _GIBaseInfo           GIBaseInfo;
36 typedef struct _GICallableInfo       GICallableInfo;
37 typedef struct _GIFunctionInfo       GIFunctionInfo;
38 typedef struct _GICallbackInfo       GICallbackInfo;
39 typedef struct _GIRegisteredTypeInfo GIRegisteredTypeInfo;
40 typedef struct _GIStructInfo         GIStructInfo;
41 typedef struct _GIUnionInfo          GIUnionInfo;
42 typedef struct _GIEnumInfo           GIEnumInfo;
43 typedef struct _GIObjectInfo         GIObjectInfo;
44 typedef struct _GIInterfaceInfo      GIInterfaceInfo;
45 typedef struct _GIConstantInfo       GIConstantInfo;
46 typedef struct _GIValueInfo          GIValueInfo;
47 typedef struct _GISignalInfo         GISignalInfo;
48 typedef struct _GIVFuncInfo          GIVFuncInfo;
49 typedef struct _GIPropertyInfo       GIPropertyInfo;
50 typedef struct _GIFieldInfo          GIFieldInfo;
51 typedef struct _GIArgInfo            GIArgInfo;
52 typedef struct _GITypeInfo           GITypeInfo;
53 typedef struct _GIErrorDomainInfo    GIErrorDomainInfo;
54 typedef struct _GIUnresolvedInfo     GIUnresolvedInfo;
55 typedef struct _GTypelib            GTypelib;
56
57 struct _GIRepository 
58
59   GObject parent; 
60
61   /*< private >*/
62   GIRepositoryPrivate *priv;
63 };
64
65 struct _GIRepositoryClass
66
67   GObjectClass parent; 
68 };
69
70 typedef enum
71 {
72   G_IREPOSITORY_LOAD_FLAG_LAZY = 1 << 0
73 } GIRepositoryLoadFlags;
74
75 /* Repository */
76
77 GType         g_irepository_get_type      (void) G_GNUC_CONST;
78 GIRepository *g_irepository_get_default   (void);
79 void          g_irepository_prepend_search_path (const char *directory);
80 GSList *      g_irepository_get_search_path     (void);
81 const char *  g_irepository_load_typelib  (GIRepository *repository,
82                                            GTypelib     *typelib,
83                                            GIRepositoryLoadFlags flags,
84                                            GError      **error);
85 gboolean      g_irepository_is_registered (GIRepository *repository,
86                                            const gchar  *namespace,
87                                            const gchar  *version);
88 GIBaseInfo *  g_irepository_find_by_name  (GIRepository *repository,
89                                            const gchar  *namespace,
90                                            const gchar  *name);
91 GTypelib *    g_irepository_require       (GIRepository *repository,
92                                            const gchar  *namespace,
93                                            const gchar  *version,
94                                            GIRepositoryLoadFlags flags,
95                                            GError      **error);
96 gchar      ** g_irepository_get_dependencies (GIRepository *repository,
97                                               const gchar  *namespace);
98 gchar      ** g_irepository_get_loaded_namespaces (GIRepository *repository);
99 GIBaseInfo *  g_irepository_find_by_gtype (GIRepository *repository,
100                                            GType         gtype);
101 gint          g_irepository_get_n_infos   (GIRepository *repository,
102                                            const gchar  *namespace);
103 GIBaseInfo *  g_irepository_get_info      (GIRepository *repository,
104                                            const gchar  *namespace,
105                                            gint          index);
106 const gchar * g_irepository_get_typelib_path   (GIRepository *repository,
107                                                 const gchar  *namespace);
108 const gchar * g_irepository_get_shared_library (GIRepository *repository,
109                                                 const gchar  *namespace);
110 const gchar * g_irepository_get_version (GIRepository *repository,
111                                          const gchar  *namespace);
112
113 GOptionGroup * g_irepository_get_option_group (void);
114
115 gboolean       g_irepository_dump  (const char *arg, GError **error);
116
117 /* Typelib */
118
119 GTypelib *   g_typelib_new_from_memory       (guchar       *memory,
120                                                 gsize         len);
121 GTypelib *   g_typelib_new_from_const_memory (const guchar *memory,
122                                                 gsize         len);
123 GTypelib *   g_typelib_new_from_mapped_file  (GMappedFile  *mfile);
124 void          g_typelib_free                  (GTypelib    *typelib);
125
126 gboolean      g_typelib_symbol                (GTypelib    *typelib,
127                                                const gchar *symbol_name,
128                                                gpointer    *symbol);
129 const gchar * g_typelib_get_namespace         (GTypelib    *typelib);
130
131 typedef enum
132 {
133   G_IREPOSITORY_ERROR_TYPELIB_NOT_FOUND,
134   G_IREPOSITORY_ERROR_NAMESPACE_MISMATCH,
135   G_IREPOSITORY_ERROR_NAMESPACE_VERSION_CONFLICT,
136   G_IREPOSITORY_ERROR_LIBRARY_NOT_FOUND
137 } GIRepositoryError;
138
139 #define G_IREPOSITORY_ERROR (g_irepository_error_quark ())
140
141 GQuark g_irepository_error_quark (void);
142
143
144 /* Types of objects registered in the repository */
145
146 typedef enum 
147 {
148   GI_INFO_TYPE_INVALID,
149   GI_INFO_TYPE_FUNCTION,
150   GI_INFO_TYPE_CALLBACK,
151   GI_INFO_TYPE_STRUCT,
152   GI_INFO_TYPE_BOXED,
153   GI_INFO_TYPE_ENUM,
154   GI_INFO_TYPE_FLAGS,
155   GI_INFO_TYPE_OBJECT,
156   GI_INFO_TYPE_INTERFACE,
157   GI_INFO_TYPE_CONSTANT,
158   GI_INFO_TYPE_ERROR_DOMAIN,
159   GI_INFO_TYPE_UNION,
160   GI_INFO_TYPE_VALUE,
161   GI_INFO_TYPE_SIGNAL,
162   GI_INFO_TYPE_VFUNC,
163   GI_INFO_TYPE_PROPERTY,
164   GI_INFO_TYPE_FIELD,
165   GI_INFO_TYPE_ARG,
166   GI_INFO_TYPE_TYPE,
167   GI_INFO_TYPE_UNRESOLVED
168 } GIInfoType;
169
170
171 /* GIBaseInfo */
172
173 GIBaseInfo *           g_base_info_ref              (GIBaseInfo   *info);
174 void                   g_base_info_unref            (GIBaseInfo   *info);
175 GIInfoType             g_base_info_get_type         (GIBaseInfo   *info);
176 const gchar *          g_base_info_get_name         (GIBaseInfo   *info);
177 const gchar *          g_base_info_get_namespace    (GIBaseInfo   *info);
178 gboolean               g_base_info_is_deprecated    (GIBaseInfo   *info);
179 const gchar *          g_base_info_get_annotation   (GIBaseInfo   *info,
180                                                      const gchar  *name);
181 GIBaseInfo *           g_base_info_get_container    (GIBaseInfo   *info);
182 GTypelib *             g_base_info_get_typelib      (GIBaseInfo   *info);
183
184 GIBaseInfo *           g_info_new                   (GIInfoType    type,
185                                                      GIBaseInfo   *container,
186                                                      GTypelib     *typelib, 
187                                                      guint32       offset);
188
189
190 /* GIFunctionInfo */
191
192 typedef enum
193 {
194   GI_FUNCTION_IS_METHOD      = 1 << 0,
195   GI_FUNCTION_IS_CONSTRUCTOR = 1 << 1,
196   GI_FUNCTION_IS_GETTER      = 1 << 2,
197   GI_FUNCTION_IS_SETTER      = 1 << 3,
198   GI_FUNCTION_WRAPS_VFUNC    = 1 << 4,
199   GI_FUNCTION_THROWS         = 1 << 5
200 } GIFunctionInfoFlags;
201
202 const gchar *           g_function_info_get_symbol     (GIFunctionInfo *info);
203 GIFunctionInfoFlags     g_function_info_get_flags      (GIFunctionInfo *info);
204 GIPropertyInfo *        g_function_info_get_property   (GIFunctionInfo *info);
205 GIVFuncInfo *           g_function_info_get_vfunc      (GIFunctionInfo *info);
206
207 typedef union 
208 {
209   gboolean v_boolean;
210   gint8    v_int8;
211   guint8   v_uint8;
212   gint16   v_int16;
213   guint16  v_uint16;
214   gint32   v_int32;
215   guint32  v_uint32;
216   gint64   v_int64;
217   guint64  v_uint64;
218   gfloat   v_float;
219   gdouble  v_double;
220   gint     v_int;
221   guint    v_uint;
222   glong    v_long;
223   gulong   v_ulong;
224   gssize   v_ssize;
225   gsize    v_size;
226   gchar *  v_string;
227   gpointer v_pointer;
228 } GArgument;
229
230 #define G_INVOKE_ERROR (g_invoke_error_quark ())
231 GQuark g_invoke_error_quark (void);
232
233 typedef enum
234 {
235   G_INVOKE_ERROR_FAILED,
236   G_INVOKE_ERROR_SYMBOL_NOT_FOUND,
237   G_INVOKE_ERROR_ARGUMENT_MISMATCH
238 } GInvokeError;
239
240 gboolean              g_function_info_invoke         (GIFunctionInfo *info, 
241                                                       const GArgument  *in_args,
242                                                       int               n_in_args,
243                                                       const GArgument  *out_args,
244                                                       int               n_out_args,
245                                                       GArgument        *return_value,
246                                                       GError          **error);
247
248
249 /* GICallableInfo */
250
251 typedef enum {
252   GI_TRANSFER_NOTHING,
253   GI_TRANSFER_CONTAINER,
254   GI_TRANSFER_EVERYTHING
255 } GITransfer;
256
257 GITypeInfo *           g_callable_info_get_return_type (GICallableInfo *info);
258 GITransfer             g_callable_info_get_caller_owns (GICallableInfo *info);
259 gboolean               g_callable_info_may_return_null (GICallableInfo *info);
260 gint                   g_callable_info_get_n_args      (GICallableInfo *info);
261 GIArgInfo *            g_callable_info_get_arg         (GICallableInfo *info,
262                                                         gint           n);
263
264 /* GIArgInfo */
265
266 typedef enum  {
267   GI_DIRECTION_IN,
268   GI_DIRECTION_OUT,
269   GI_DIRECTION_INOUT
270 } GIDirection;
271
272 typedef enum {
273   GI_SCOPE_TYPE_INVALID,
274   GI_SCOPE_TYPE_CALL,
275   GI_SCOPE_TYPE_OBJECT,
276   GI_SCOPE_TYPE_ASYNC,
277   GI_SCOPE_TYPE_NOTIFIED
278 } GIScopeType;
279
280 GIDirection            g_arg_info_get_direction          (GIArgInfo *info);
281 gboolean               g_arg_info_is_dipper              (GIArgInfo *info);
282 gboolean               g_arg_info_is_return_value        (GIArgInfo *info);
283 gboolean               g_arg_info_is_optional            (GIArgInfo *info);
284 gboolean               g_arg_info_may_be_null            (GIArgInfo *info);
285 GITransfer             g_arg_info_get_ownership_transfer (GIArgInfo *info);
286 GIScopeType            g_arg_info_get_scope              (GIArgInfo *info);
287 gint                   g_arg_info_get_closure            (GIArgInfo *info);
288 gint                   g_arg_info_get_destroy            (GIArgInfo *info);
289 GITypeInfo *           g_arg_info_get_type               (GIArgInfo *info);
290
291
292 /* GITypeInfo */
293
294 typedef enum {
295   /* Basic types */
296   GI_TYPE_TAG_VOID      =  0,
297   GI_TYPE_TAG_BOOLEAN   =  1,
298   GI_TYPE_TAG_INT8      =  2,
299   GI_TYPE_TAG_UINT8     =  3,
300   GI_TYPE_TAG_INT16     =  4,
301   GI_TYPE_TAG_UINT16    =  5,  
302   GI_TYPE_TAG_INT32     =  6,
303   GI_TYPE_TAG_UINT32    =  7,
304   GI_TYPE_TAG_INT64     =  8,
305   GI_TYPE_TAG_UINT64    =  9,
306   GI_TYPE_TAG_INT       = 10,
307   GI_TYPE_TAG_UINT      = 11,
308   GI_TYPE_TAG_LONG      = 12,
309   GI_TYPE_TAG_ULONG     = 13,
310   GI_TYPE_TAG_SSIZE     = 14,
311   GI_TYPE_TAG_SIZE      = 15,
312   GI_TYPE_TAG_FLOAT     = 16,
313   GI_TYPE_TAG_DOUBLE    = 17,
314   GI_TYPE_TAG_TIME_T    = 18,
315   GI_TYPE_TAG_GTYPE     = 19,
316   GI_TYPE_TAG_UTF8      = 20,
317   GI_TYPE_TAG_FILENAME  = 21,
318   /* Non-basic types */
319   GI_TYPE_TAG_ARRAY     = 22,
320   GI_TYPE_TAG_INTERFACE = 23,
321   GI_TYPE_TAG_GLIST     = 24,
322   GI_TYPE_TAG_GSLIST    = 25,
323   GI_TYPE_TAG_GHASH     = 26,
324   GI_TYPE_TAG_ERROR     = 27
325   /* Note - there is only room currently for 32 tags.
326    * See docs/typelib-format.txt SimpleTypeBlob definition */
327 } GITypeTag;
328
329 #define G_TYPE_TAG_IS_BASIC(tag) (tag < GI_TYPE_TAG_ARRAY)
330
331 const gchar*           g_type_tag_to_string            (GITypeTag   type);
332
333 gboolean               g_type_info_is_pointer          (GITypeInfo *info);
334 GITypeTag              g_type_info_get_tag             (GITypeInfo *info);
335 GITypeInfo *           g_type_info_get_param_type      (GITypeInfo *info,
336                                                         gint       n);
337 GIBaseInfo *           g_type_info_get_interface       (GITypeInfo *info);
338 gint                   g_type_info_get_array_length    (GITypeInfo *info);
339 gint                   g_type_info_get_array_fixed_size(GITypeInfo *info);
340 gboolean               g_type_info_is_zero_terminated  (GITypeInfo *info);
341
342 gint                   g_type_info_get_n_error_domains (GITypeInfo *info);
343 GIErrorDomainInfo     *g_type_info_get_error_domain    (GITypeInfo *info,
344                                                         gint       n);
345
346 /* GIErrorDomainInfo */
347
348 const gchar *          g_error_domain_info_get_quark   (GIErrorDomainInfo *info);
349 GIInterfaceInfo *           g_error_domain_info_get_codes (GIErrorDomainInfo *info);
350
351
352 /* GIValueInfo */
353  
354 glong                  g_value_info_get_value      (GIValueInfo *info);
355
356
357 /* GIFieldInfo */
358
359 typedef enum
360 {
361   GI_FIELD_IS_READABLE = 1 << 0,
362   GI_FIELD_IS_WRITABLE = 1 << 1
363 } GIFieldInfoFlags;
364
365 GIFieldInfoFlags       g_field_info_get_flags      (GIFieldInfo *info);
366 gint                   g_field_info_get_size       (GIFieldInfo *info);
367 gint                   g_field_info_get_offset     (GIFieldInfo *info);
368 GITypeInfo *           g_field_info_get_type       (GIFieldInfo *info);
369
370 gboolean g_field_info_get_field (GIFieldInfo     *field_info,
371                                  gpointer         mem,
372                                  GArgument       *value);
373 gboolean g_field_info_set_field (GIFieldInfo     *field_info,
374                                  gpointer         mem,
375                                  const GArgument *value);
376
377 /* GIUnionInfo */
378 gint                   g_union_info_get_n_fields  (GIUnionInfo *info);
379 GIFieldInfo *          g_union_info_get_field     (GIUnionInfo *info,
380                                                    gint         n);
381 gint                   g_union_info_get_n_methods (GIUnionInfo *info);
382 GIFunctionInfo *       g_union_info_get_method    (GIUnionInfo *info,
383                                                    gint         n);
384 gboolean               g_union_info_is_discriminated (GIUnionInfo *info);
385 gint                   g_union_info_get_discriminator_offset (GIUnionInfo *info);
386 GITypeInfo *           g_union_info_get_discriminator_type (GIUnionInfo *info);
387 GIConstantInfo *       g_union_info_get_discriminator      (GIUnionInfo *info,
388                                                             gint         n);
389 GIFunctionInfo *       g_union_info_find_method    (GIUnionInfo *info,
390                                                     const gchar *name);
391 gsize                  g_union_info_get_size       (GIUnionInfo *info);
392 gsize                  g_union_info_get_alignment  (GIUnionInfo *info);
393
394
395 /* GIStructInfo */
396 gint                   g_struct_info_get_n_fields  (GIStructInfo *info);
397 GIFieldInfo *          g_struct_info_get_field     (GIStructInfo *info,
398                                                     gint         n);
399 gint                   g_struct_info_get_n_methods (GIStructInfo *info);
400 GIFunctionInfo *       g_struct_info_get_method    (GIStructInfo *info,
401                                                     gint         n);
402 GIFunctionInfo *       g_struct_info_find_method   (GIStructInfo *info,
403                                                     const gchar *name);
404 gsize                  g_struct_info_get_size      (GIStructInfo *info);
405 gsize                  g_struct_info_get_alignment (GIStructInfo *info);
406
407 /* GIRegisteredTypeInfo */
408
409 const gchar *          g_registered_type_info_get_type_name (GIRegisteredTypeInfo *info);
410 const gchar *          g_registered_type_info_get_type_init (GIRegisteredTypeInfo *info);
411 GType                  g_registered_type_info_get_g_type    (GIRegisteredTypeInfo *info);
412
413 /* GIEnumInfo */
414
415 gint                   g_enum_info_get_n_values             (GIEnumInfo      *info);
416 GIValueInfo  *         g_enum_info_get_value                (GIEnumInfo      *info,
417                                                              gint            n);
418 GITypeTag              g_enum_info_get_storage_type         (GIEnumInfo      *info);
419
420 /* GIObjectInfo */
421
422 const gchar *          g_object_info_get_type_name          (GIObjectInfo    *info);
423 const gchar *          g_object_info_get_type_init          (GIObjectInfo    *info);
424 gboolean               g_object_info_get_abstract           (GIObjectInfo    *info);
425 GIObjectInfo *         g_object_info_get_parent             (GIObjectInfo    *info);
426 gint                   g_object_info_get_n_interfaces       (GIObjectInfo    *info);
427 GIInterfaceInfo *      g_object_info_get_interface          (GIObjectInfo    *info,
428                                                              gint            n);
429 gint                   g_object_info_get_n_fields           (GIObjectInfo    *info);
430 GIFieldInfo *          g_object_info_get_field              (GIObjectInfo    *info,
431                                                              gint            n);
432 gint                   g_object_info_get_n_properties       (GIObjectInfo    *info);
433 GIPropertyInfo *       g_object_info_get_property           (GIObjectInfo    *info,
434                                                              gint            n);
435 gint                   g_object_info_get_n_methods          (GIObjectInfo    *info);
436 GIFunctionInfo *       g_object_info_get_method             (GIObjectInfo    *info,
437                                                              gint            n);
438 GIFunctionInfo *       g_object_info_find_method            (GIObjectInfo *info,
439                                                              const gchar *name);
440 gint                   g_object_info_get_n_signals          (GIObjectInfo    *info);
441 GISignalInfo *         g_object_info_get_signal             (GIObjectInfo    *info,
442                                                              gint            n);
443 gint                   g_object_info_get_n_vfuncs           (GIObjectInfo    *info);
444 GIVFuncInfo *          g_object_info_get_vfunc              (GIObjectInfo    *info,
445                                                              gint            n);
446 gint                   g_object_info_get_n_constants        (GIObjectInfo    *info);
447 GIConstantInfo *       g_object_info_get_constant           (GIObjectInfo    *info,
448                                                              gint            n);
449
450                                                              
451 /* GIInterfaceInfo */
452
453 gint                   g_interface_info_get_n_prerequisites (GIInterfaceInfo *info);
454 GIBaseInfo *           g_interface_info_get_prerequisite    (GIInterfaceInfo *info,
455                                                              gint        n);
456 gint                   g_interface_info_get_n_properties    (GIInterfaceInfo *info);
457 GIPropertyInfo *       g_interface_info_get_property        (GIInterfaceInfo *info,
458                                                              gint        n);
459 gint                   g_interface_info_get_n_methods       (GIInterfaceInfo *info);
460 GIFunctionInfo *       g_interface_info_get_method          (GIInterfaceInfo *info,
461                                                              gint        n);
462 GIFunctionInfo *       g_interface_info_find_method         (GIInterfaceInfo *info,
463                                                              const gchar *name);
464 gint                   g_interface_info_get_n_signals       (GIInterfaceInfo *info);
465 GISignalInfo *         g_interface_info_get_signal          (GIInterfaceInfo *info,
466                                                              gint        n);
467 gint                   g_interface_info_get_n_vfuncs        (GIInterfaceInfo *info);
468 GIVFuncInfo *          g_interface_info_get_vfunc           (GIInterfaceInfo *info,
469                                                              gint        n);
470 gint                   g_interface_info_get_n_constants     (GIInterfaceInfo *info);
471 GIConstantInfo *       g_interface_info_get_constant        (GIInterfaceInfo *info,
472                                                              gint        n);
473
474
475 /* GIPropertyInfo  */
476
477 GParamFlags             g_property_info_get_flags                (GIPropertyInfo         *info);
478 GITypeInfo *            g_property_info_get_type                 (GIPropertyInfo         *info);
479
480
481 /* GISignalInfo */
482
483 GSignalFlags            g_signal_info_get_flags                  (GISignalInfo           *info);
484 GIVFuncInfo *           g_signal_info_get_class_closure          (GISignalInfo           *info);
485 gboolean                g_signal_info_true_stops_emit            (GISignalInfo           *info);
486
487
488 /* GIVFuncInfo */
489
490 typedef enum
491 {
492   GI_VFUNC_MUST_CHAIN_UP     = 1 << 0,
493   GI_VFUNC_MUST_OVERRIDE     = 1 << 1,
494   GI_VFUNC_MUST_NOT_OVERRIDE = 1 << 2
495 } GIVFuncInfoFlags;
496
497 GIVFuncInfoFlags        g_vfunc_info_get_flags                   (GIVFuncInfo            *info);
498 gint                    g_vfunc_info_get_offset                  (GIVFuncInfo            *info);
499 GISignalInfo *          g_vfunc_info_get_signal                  (GIVFuncInfo            *info);
500
501
502 /* GIConstantInfo */
503
504 GITypeInfo *            g_constant_info_get_type                 (GIConstantInfo         *info);
505 gint                    g_constant_info_get_value                (GIConstantInfo         *info,
506                                                                   GArgument             *value);
507
508
509 G_END_DECLS
510
511 #endif  /* __G_IREPOSITORY_H__ */
512