[girepository] Document most of the structs

This commit is contained in:
Johan Dahlin 2010-05-18 18:10:51 -03:00
parent 9f4cadec60
commit 51118b3338
5 changed files with 335 additions and 24 deletions

View File

@ -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.

View File

@ -41,6 +41,7 @@ typedef struct _GIRepositoryPrivate GIRepositoryPrivate;
typedef struct _GIBaseInfoStub GIBaseInfo;
struct _GIBaseInfoStub {
/* <private> */
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 {
/* <private> */
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,

View File

@ -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,

View File

@ -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;
/* <private> */
gpointer padding[3];
};

View File

@ -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;
/* <private> */
guint16 reserved;
/* <public> */
guint16 n_entries;
guint16 n_local_entries;
guint32 directory;
@ -269,6 +272,7 @@ typedef struct {
guint16 interface_blob_size;
guint16 union_blob_size;
/* <private> */
guint16 padding[7];
} Header;
@ -290,8 +294,9 @@ typedef struct {
guint16 blob_type;
guint16 local : 1;
/* <private> */
guint16 reserved :15;
/* <public> */
guint32 name;
guint32 offset;
} DirEntry;
@ -322,16 +327,20 @@ typedef union
{
struct
{
/* <private> */
guint reserved : 8;
guint reserved2 :16;
/* <public> */
guint pointer : 1;
/* <private> */
guint reserved3 : 2;
/* <public> */
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;
/* <private> */
guint reserved :21;
/* <public> */
gint8 closure;
gint8 destroy;
@ -434,8 +444,9 @@ typedef struct {
guint16 blob_type; /* 1 */
guint16 deprecated : 1;
/* <private> */
guint16 reserved :15;
/* <public> */
guint32 name;
} CommonBlob;
@ -494,8 +505,9 @@ typedef struct {
guint16 blob_type; /* 2 */
guint16 deprecated : 1;
/* <private> */
guint16 reserved :15;
/* <public> */
guint32 name;
guint32 signature;
} CallbackBlob;
@ -510,9 +522,13 @@ typedef struct {
*/
typedef struct {
guint8 pointer :1;
/* <private> */
guint8 reserved :2;
/* <public> */
guint8 tag :5;
/* <private> */
guint8 reserved2;
/* <public> */
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;
/* <private> */
guint32 reserved :31;
/* <public> */
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 {
/* <private> */
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,