From 85a6b48602bc3e8e68e1048de375fc32ae825347 Mon Sep 17 00:00:00 2001 From: Johan Dahlin Date: Tue, 18 May 2010 18:10:51 -0300 Subject: [girepository] Document most of the structs --- docs/reference/gi-sections.txt | 3 +- girepository/girepository.c | 2 +- girepository/girepository.h | 300 +++++++++++++++++++++++++++++++++++++++-- girepository/girffi.c | 2 + girepository/girffi.h | 7 +- girepository/gtypelib.h | 48 +++++-- 6 files changed, 337 insertions(+), 25 deletions(-) diff --git a/docs/reference/gi-sections.txt b/docs/reference/gi-sections.txt index abab2996..b481896f 100644 --- a/docs/reference/gi-sections.txt +++ b/docs/reference/gi-sections.txt @@ -26,7 +26,6 @@ GIUnresolvedInfo GTypelib GIArrayType GIAttributeIter -GIBaseInfoStub GIRepository G_IREPOSITORY_CLASS G_IREPOSITORY_GET_CLASS @@ -204,6 +203,8 @@ g_constant_info_get_value G_TYPE_TAG_IS_BASIC g_irepository_get_type + +GIBaseInfoStub
diff --git a/girepository/girepository.c b/girepository/girepository.c index d4be01db..684db66e 100644 --- a/girepository/girepository.c +++ b/girepository/girepository.c @@ -1149,7 +1149,7 @@ find_namespace_latest (const gchar *namespace, * @repository: (allow-none): Repository, may be %NULL for the default * @namespace_: GI namespace to use, e.g. "Gtk" * @version: (allow-none): Version of namespace, may be %NULL for latest - * @flags: Set of %GIRepositoryLoadFlags, may be %0 + * @flags: Set of %GIRepositoryLoadFlags, may be 0 * @error: a #GError. * * Force the namespace @namespace_ to be loaded if it isn't already. diff --git a/girepository/girepository.h b/girepository/girepository.h index 9e62ab15..36a1d39c 100644 --- a/girepository/girepository.h +++ b/girepository/girepository.h @@ -41,6 +41,7 @@ typedef struct _GIRepositoryPrivate GIRepositoryPrivate; typedef struct _GIBaseInfoStub GIBaseInfo; struct _GIBaseInfoStub { + /* */ gint32 dummy1; gint32 dummy2; gpointer dummy3; @@ -51,27 +52,141 @@ struct _GIBaseInfoStub { gpointer padding[4]; }; +/** + * GICallableInfo: + * + * Represents a callable, either #GIFunctionInfo, #GICallbackInfo or + * #GIVFuncInfo. + */ typedef GIBaseInfo GICallableInfo; + +/** + * GIFunctionInfo: + * + * Represents a function, eg arguments and return value. + */ typedef GIBaseInfo GIFunctionInfo; + +/** + * 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; + +/** + * GIValueInfo: + * + * Represents a enum value of a #GIEnumInfo. + */ typedef GIBaseInfo GIValueInfo; + +/** + * GISignalInfo: + * + * Represents a signal. + */ typedef GIBaseInfo GISignalInfo; + +/** + * GIVFuncInfo + * + * Represents a virtual function. + */ 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; + +/** + * GIErrorDomainInfo: + * + * Represents a #GError error domain. + */ typedef GIBaseInfo GIErrorDomainInfo; -typedef struct _GIUnresolvedInfo GIUnresolvedInfo; -typedef struct _GTypelib GTypelib; +/** + * GIUnresolvedInfo: + * + * Represents a unresolved type in a typelib. + */ +typedef struct _GIUnresolvedInfo GIUnresolvedInfo; + +typedef struct _GTypelib GTypelib; struct _GIRepository { @@ -86,6 +201,13 @@ struct _GIRepositoryClass GObjectClass parent; }; +/** + * GIRepositoryLoadFlags + * @G_IREPOSITORY_LOAD_FLAG_LAZY: Load the types lazily. + * + * Flags that controlls how a typelib is loaded by + * GIRepositry, used by g_irepository_load_typelib(). + */ typedef enum { G_IREPOSITORY_LOAD_FLAG_LAZY = 1 << 0 @@ -149,6 +271,16 @@ gboolean g_typelib_symbol (GTypelib *typelib, gpointer *symbol); const gchar * g_typelib_get_namespace (GTypelib *typelib); +/** + * GIRepositoryError: + * @G_IREPOSITORY_ERROR_TYPELIB_NOT_FOUND: the typelib could not be found. + * @G_IREPOSITORY_ERROR_NAMESPACE_MISMATCH: the namespace does not match the + * requested namespace. + * @G_IREPOSITORY_ERROR_NAMESPACE_VERSION_CONFLICT: the version of the + * typelib does not match the requested version. + * @G_IREPOSITORY_ERROR_LIBRARY_NOT_FOUND: the library used by the typelib + * could not be found. + */ typedef enum { G_IREPOSITORY_ERROR_TYPELIB_NOT_FOUND, @@ -173,6 +305,32 @@ void gi_cclosure_marshal_generic (GClosure *closure, /* Types of objects registered in the repository */ +/** + * GIInfoType: + * @GI_INFO_TYPE_INVALID: invalid type + * @GI_INFO_TYPE_FUNCTION: function, see #GIFunctionInfo + * @GI_INFO_TYPE_CALLBACK: callback, see #GICallbackInfo + * @GI_INFO_TYPE_STRUCT: struct, see #GIStructInfo + * @GI_INFO_TYPE_BOXED: boxed, see #GIBoxedInfo + * @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_ERROR_DOMAIN: error domain for a #GError, see #GIErrorDomainInfo + * @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, @@ -200,7 +358,14 @@ typedef enum /* GIBaseInfo */ +/** + * GIAttributeIter: + * + * An opaque structure used to iterate over attributes + * in a #GIBaseInfo struct. + */ typedef struct { + /* */ gpointer data; gpointer data2; gpointer data3; @@ -232,6 +397,17 @@ GIBaseInfo * g_info_new (GIInfoType type, /* GIFunctionInfo */ +/** + * 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, @@ -275,6 +451,18 @@ typedef union #define G_INVOKE_ERROR (g_invoke_error_quark ()) GQuark g_invoke_error_quark (void); +/** + * GInvokeError: + * @G_INVOKE_ERROR_FAILED: invokation failed, unknown error. + * @G_INVOKE_ERROR_SYMBOL_NOT_FOUND: symbol couldn't be found in any of the + * libraries associated with the typelib of the function. + * @G_INVOKE_ERROR_ARGUMENT_MISMATCH: the arguments provided didn't match + * the expected arguments for the functions type signature. + * + * An error occuring while invoking a function via + * g_function_info_invoke(). + */ + typedef enum { G_INVOKE_ERROR_FAILED, @@ -293,6 +481,16 @@ gboolean g_function_info_invoke (GIFunctionInfo *info, /* GICallableInfo */ +/** + * GITransfer: + * @GI_TRANSFER_NOTHING: transfer nothing to the caller + * @GI_TRANSFER_CONTAINER: transfer the container (eg list, array, + * hashtable), but no the contents to the caller. + * @GI_TRANSFER_EVERYTHING: transfer everything to the caller. + * + * Represent the transfer ownership information of a #GICallableInfo or + * a #GIArgInfo. + */ typedef enum { GI_TRANSFER_NOTHING, GI_TRANSFER_CONTAINER, @@ -313,21 +511,40 @@ void g_callable_info_load_arg (GICallableInfo *info, /* GIArgInfo */ +/** + * 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 and associated + * user_data is used until the caller is notfied via the destroy_notify. + * + * 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, /* 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 and associated user_data is - used until the caller is notfied via the destroy_notify */ + GI_SCOPE_TYPE_INVALID, + GI_SCOPE_TYPE_CALL, + GI_SCOPE_TYPE_ASYNC, + GI_SCOPE_TYPE_NOTIFIED } GIScopeType; GIDirection g_arg_info_get_direction (GIArgInfo *info); @@ -344,8 +561,42 @@ void g_arg_info_load_type (GIArgInfo *info, GITypeInfo *type); -/* GITypeInfo */ - +/** + * 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_SHORT: signed short + * @GI_TYPE_TAG_USHORT: unsigned hosrt + * @GI_TYPE_TAG_INT: signed integer + * @GI_TYPE_TAG_UINT: unsigned integer + * @GI_TYPE_TAG_LONG: signed long + * @GI_TYPE_TAG_ULONG: unsigned long + * @GI_TYPE_TAG_SSIZE: ssize_t + * @GI_TYPE_TAG_SIZE: size_t + * @GI_TYPE_TAG_FLOAT: float + * @GI_TYPE_TAG_DOUBLE: double floating point + * @GI_TYPE_TAG_TIME_T: time_t + * @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 + * + * The type tag of a #GITypeInfo. + */ typedef enum { /* Basic types */ GI_TYPE_TAG_VOID = 0, @@ -383,6 +634,15 @@ typedef enum { * See docs/typelib-format.txt SimpleTypeBlob definition */ } GITypeTag; +/** + * 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, @@ -421,6 +681,14 @@ glong g_value_info_get_value (GIValueInfo *info); /* GIFieldInfo */ +/** + * 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, @@ -561,6 +829,14 @@ gboolean g_signal_info_true_stops_emit (GISignalInfo /* GIVFuncInfo */ +/** + * 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 + * + * Flags of a #GIVFuncInfo struct. + */ typedef enum { GI_VFUNC_MUST_CHAIN_UP = 1 << 0, diff --git a/girepository/girffi.c b/girepository/girffi.c index 3f0b6705..6716324e 100644 --- a/girepository/girffi.c +++ b/girepository/girffi.c @@ -198,6 +198,8 @@ g_callable_info_get_ffi_return_type (GICallableInfo *callable_info) * A primary intent of this function is that a dynamic structure allocated * by a language binding could contain a #GIFunctionInvoker structure * inside the binding's function mapping. + * + * Returns: %TRUE on success, %FALSE otherwise with @error set. */ gboolean g_function_info_prep_invoker (GIFunctionInfo *info, diff --git a/girepository/girffi.h b/girepository/girffi.h index 54ce7b58..56d85a18 100644 --- a/girepository/girffi.h +++ b/girepository/girffi.h @@ -31,12 +31,17 @@ typedef void (*GIFFIClosureCallback) (ffi_cif *, void **, void *); +/** + * GIFunctionInvoker: + * @cif: the cif + * @native_address: the native adress + */ typedef struct _GIFunctionInvoker GIFunctionInvoker; struct _GIFunctionInvoker { ffi_cif cif; gpointer native_address; - + /* */ gpointer padding[3]; }; diff --git a/girepository/gtypelib.h b/girepository/gtypelib.h index 1ca83c86..617cb39f 100644 --- a/girepository/gtypelib.h +++ b/girepository/gtypelib.h @@ -202,6 +202,7 @@ typedef enum { * @nsversion: Offset of the namespace version string in the typelib. * @shared_library: This field is the set of shared libraries associated * with the typelib. The entries are separated by the '|' (pipe) character. + * @c_prefix: The prefix for the function names of the library * @entry_blob_size: The sizes of fixed-size blobs. Recording this information here * allows to write parser which continue to work if the format is * extended by adding new fields to the end of the fixed-size blobs. @@ -234,7 +235,9 @@ typedef struct { gchar magic[16]; guint8 major_version; guint8 minor_version; + /* */ guint16 reserved; + /* */ guint16 n_entries; guint16 n_local_entries; guint32 directory; @@ -269,6 +272,7 @@ typedef struct { guint16 interface_blob_size; guint16 union_blob_size; + /* */ guint16 padding[7]; } Header; @@ -290,8 +294,9 @@ typedef struct { guint16 blob_type; guint16 local : 1; + /* */ guint16 reserved :15; - + /* */ guint32 name; guint32 offset; } DirEntry; @@ -322,16 +327,20 @@ typedef union { struct { + /* */ guint reserved : 8; guint reserved2 :16; + /* */ guint pointer : 1; + /* */ guint reserved3 : 2; + /* */ guint tag : 5; } flags; guint32 offset; } SimpleTypeBlob; -/* +/** * ArgBlob: * @name: A suggested name for the parameter. * @in: The parameter is an input to the function @@ -356,7 +365,7 @@ typedef union * @transfer_container_ownership: For container types, indicates that the * ownership of the container, but not of its contents is transferred. This is typically the case * for out parameters returning lists of statically allocated things. - * @is_return_value: The parameter should be considered the return value of the function. + * @return_value: The parameter should be considered the return value of the function. * Only out parameters can be marked as return value, and there can be * at most one per function call. If an out parameter is marked as * return value, the actual return value of the function should be @@ -386,8 +395,9 @@ typedef struct { guint transfer_container_ownership : 1; guint return_value : 1; guint scope : 3; + /* */ guint reserved :21; - + /* */ gint8 closure; gint8 destroy; @@ -434,8 +444,9 @@ typedef struct { guint16 blob_type; /* 1 */ guint16 deprecated : 1; + /* */ guint16 reserved :15; - + /* */ guint32 name; } CommonBlob; @@ -494,8 +505,9 @@ typedef struct { guint16 blob_type; /* 2 */ guint16 deprecated : 1; + /* */ guint16 reserved :15; - + /* */ guint32 name; guint32 signature; } CallbackBlob; @@ -510,9 +522,13 @@ typedef struct { */ typedef struct { guint8 pointer :1; + /* */ guint8 reserved :2; + /* */ guint8 tag :5; + /* */ guint8 reserved2; + /* */ guint16 interface; } InterfaceTypeBlob; @@ -533,7 +549,6 @@ typedef struct { * direction as this one. * @size: The fixed size of the array. * @type: The type of the array elements. - * * Arrays are passed by reference, thus is_pointer is always 1. */ typedef struct { @@ -618,7 +633,9 @@ typedef struct { */ typedef struct { guint32 deprecated : 1; + /* */ guint32 reserved :31; + /* */ guint32 name; gint32 value; } ValueBlob; @@ -681,9 +698,7 @@ typedef struct { * @gtype_name: String name of the associated #GType * @gtype_init: String naming the symbol which gets the runtime #GType * @n_fields: - * @n_functions: The lengths of the arrays. * @fields: An array of n_fields FieldBlobs. - * @functions: An array of n_functions FunctionBlobs. The described functions * should be considered as methods of the struct. */ typedef struct { @@ -730,7 +745,6 @@ typedef struct { * The value 0xFFFF indicates that the discriminator offset * is unknown. * @discriminator_type: Type of the discriminator - * @discriminator_values: On discriminator value per field * @fields: Array of FieldBlobs describing the alternative branches of the union */ typedef struct { @@ -1040,7 +1054,11 @@ typedef struct { guint32 value; } AttributeBlob; +/** + * GTypelib: + */ struct _GTypelib { + /* */ guchar *data; gsize len; gboolean owns_memory; @@ -1057,6 +1075,16 @@ void g_typelib_check_sanity (void); #define g_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)]) +/** + * GTypelibError: + * @G_TYPELIB_ERROR_INVALID: the typelib is invalid + * @G_TYPELIB_ERROR_INVALID_HEADER: the typelib header is invalid + * @G_TYPELIB_ERROR_INVALID_DIRECTORY: the typelib directory is invalid + * @G_TYPELIB_ERROR_INVALID_ENTRY: a typelib entry is invalid + * @G_TYPELIB_ERROR_INVALID_BLOB: a typelib blob is invalid + * + * A error set while validating the #GTypelib + */ typedef enum { G_TYPELIB_ERROR_INVALID, -- cgit v1.2.1