diff options
Diffstat (limited to 'girepository/gtypelib.h')
| -rw-r--r-- | girepository/gtypelib.h | 587 |
1 files changed, 530 insertions, 57 deletions
diff --git a/girepository/gtypelib.h b/girepository/gtypelib.h index ee7442f..5ab2acb 100644 --- a/girepository/gtypelib.h +++ b/girepository/gtypelib.h @@ -2,6 +2,7 @@ * typelib format, validation * * Copyright (C) 2005 Matthias Clasen + * Copyright (C) 2008,2009 Red Hat, Inc. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -27,10 +28,134 @@ G_BEGIN_DECLS +/** + * SECTION:gtypelib + * @short_description: Layout and accessors for typelib + * @stability: Stable + * + * The "typelib" is a binary, readonly, memory-mappable database + * containing reflective information about a GObject library. + * + * The format of GObject typelib is strongly influenced by the Mozilla XPCOM + * format. + * + * Some of the differences to XPCOM include: + * - Type information is stored not quite as compactly (XPCOM stores it inline + * in function descriptions in variable-sized blobs of 1 to n bytes. We store + * 16 bits of type information for each parameter, which is enough to encode + * simple types inline. Complex (e.g. recursive) types are stored out of line + * in a separate list of types. + * - String and complex type data is stored outside of typelib entry blobs, + * references are stored as offsets relative to the start of the typelib. + * One possibility is to store the strings and types in a pools at the end + * of the typelib. + * + * The typelib has the following general format. + * + * typelib ::= header, directory, blobs, annotations + * + * directory ::= list of entries + * + * entry ::= blob type, name, namespace, offset + * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|errordomain|union + * annotations ::= list of annotations, sorted by offset + * annotation ::= offset, key, value + * + * Details + * + * We describe the fragments that make up the typelib in the form of C structs + * (although some fall short of being valid C structs since they contain multiple + * flexible arrays). + */ + +/* +TYPELIB HISTORY +----- +Version 1.0 + +Changes since 0.9: +- Add padding to structures + +Changes since 0.8: +- Add class struct concept to ObjectBlob +- Add is_class_struct bit to StructBlob + +Changes since 0.7: +- Add dependencies + +Changes since 0.6: +- rename metadata to typelib, to follow xpcom terminology + +Changes since 0.5: +- basic type cleanup: + + remove GString + + add [u]int, [u]long, [s]size_t + + rename string to utf8, add filename +- allow blob_type to be zero for non-local entries + +Changes since 0.4: +- add a UnionBlob + +Changes since 0.3: +- drop short_name for ValueBlob + +Changes since 0.2: +- make inline types 4 bytes after all, remove header->types and allow + types to appear anywhere +- allow error domains in the directory + +Changes since 0.1: + +- drop comments about _GOBJ_METADATA +- drop string pool, strings can appear anywhere +- use 'blob' as collective name for the various blob types +- rename 'type' field in blobs to 'blob_type' +- rename 'type_name' and 'type_init' fields to 'gtype_name', 'gtype_init' +- shrink directory entries to 12 bytes +- merge struct and boxed blobs +- split interface blobs into enum, object and interface blobs +- add an 'unregistered' flag to struct and enum blobs +- add a 'wraps_vfunc' flag to function blobs and link them to + the vfuncs they wrap +- restrict value blobs to only occur inside enums and flags again +- add constant blobs, allow them toplevel, in interfaces and in objects +- rename 'receiver_owns_value' and 'receiver_owns_container' to + 'transfer_ownership' and 'transfer_container_ownership' +- add a 'struct_offset' field to virtual function and field blobs +- add 'dipper' and 'optional' flags to arg blobs +- add a 'true_stops_emit' flag to signal blobs +- add variable blob sizes to header +- store offsets to signature blobs instead of including them directly +- change the type offset to be measured in words rather than bytes +*/ + +/** + * G_IR_MAGIC: + * + * Identifying prefix for the typelib. This was inspired by XPCOM, + * which in turn borrowed from PNG. + */ #define G_IR_MAGIC "GOBJ\nMETADATA\r\n\032" -enum -{ +/** + * GTypelibBlobType: + * @BLOB_TYPE_INVALID: Should not appear in code + * @BLOB_TYPE_FUNCTION: A #FunctionBlob + * @BLOB_TYPE_CALLBACK: A #CallbackBlob + * @BLOB_TYPE_STRUCT: A #StructBlob + * @BLOB_TYPE_BOXED: Can be either a #StructBlob or #UnionBlob + * @BLOB_TYPE_ENUM: An #EnumBlob + * @BLOB_TYPE_FLAGS: An #EnumBlob + * @BLOB_TYPE_OBJECT: An #ObjectBlob + * @BLOB_TYPE_INTERFACE: An #InterfaceBlob + * @BLOB_TYPE_CONSTANT: A #ConstantBlob + * @BLOB_TYPE_ERROR_DOMAIN: A #ErrorDomainBlob + * @BLOB_TYPE_UNION: A #UnionBlob + * + * The integral value of this enumeration appears in each "Blob" + * component of a typelib to identify its type. + */ +typedef enum { BLOB_TYPE_INVALID, BLOB_TYPE_FUNCTION, BLOB_TYPE_CALLBACK, @@ -43,7 +168,7 @@ enum BLOB_TYPE_CONSTANT, BLOB_TYPE_ERROR_DOMAIN, BLOB_TYPE_UNION -}; +} GTypelibBlobType; #define BLOB_IS_REGISTERED_TYPE(blob) \ ((blob)->blob_type == BLOB_TYPE_STRUCT || \ @@ -52,8 +177,58 @@ enum (blob)->blob_type == BLOB_TYPE_OBJECT || \ (blob)->blob_type == BLOB_TYPE_INTERFACE) -typedef struct -{ +/** + * Header: + * @magic: See #G_IR_MAGIC. + * @major_version: The version of the typelib format. Minor version changes indicate + * compatible changes and should still allow the typelib to be parsed + * by a parser designed for the same major_version. + * @minor_version: See major_version. + * @n_entries: The number of entries in the directory. + * @n_local_entries: The number of entries referring to blobs in this typelib. The + * local entries must occur before the unresolved entries. + * @directory: Offset of the directory in the typelib. + * @n_annotations: Number of annotation blocks + * @annotations: Offset of the list of annotations in the typelib. + * @dependencies: Offset of a single string, which is the list of + * dependencies, separated by the '|' character. The + * dependencies are required in order to avoid having programs + * consuming a typelib check for an "Unresolved" type return + * from every API call. + * @size: The size in bytes of the typelib. + * @namespace: Offset of the namespace string in the typelib. + * @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. + * @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. + * @function_blob_size: See above. + * @callback_blob_size: See above. + * @signal_blob_size: See above. + * @vfunc_blob_size: See above. + * @arg_blob_size: See above. + * @property_blob_size: See above. + * @field_blob_size: See above. + * @value_blob_size: See above. + * @annotation_blob_size: See above. + * @constant_blob_size: See above. + * @object_blob_size: See above. + * @union_blob_size: See above. + * @signature_blob_size: See above. + * @enum_blob_size: See above. + * @struct_blob_size: See above. + * @error_domain_blob_size: See above. + * @interface_blob_size: For variable-size blobs, the size of the struct up to the first + * flexible array member. Recording this information here allows to + * write parser which continue to work if the format is extended by + * adding new fields before the first flexible array member in + * variable-size blobs. + * + * The header structure appears exactly once at the beginning of a typelib. It is a + * collection of meta-information, such as the number of entries and dependencies. + */ +typedef struct { gchar magic[16]; guint8 major_version; guint8 minor_version; @@ -94,8 +269,21 @@ typedef struct guint16 padding[7]; } Header; -typedef struct -{ +/** + * DirEntry: + * @blob_type: A #GTypelibBlobType + * @local: Whether this entry refers to a blob in this typelib. + * @name: The name of the entry. + * @offset: If is_local is set, this is the offset of the blob in the typelib. + * Otherwise, it is the offset of the namespace in which the blob has + * to be looked up by name. + * + * References to directory entries are stored as 1-based 16-bit indexes. + * + * All blobs pointed to by a directory entry start with the same layout for + * the first 8 bytes (the reserved flags may be used by some blob types) + */ +typedef struct { guint16 blob_type; guint16 local : 1; @@ -105,7 +293,14 @@ typedef struct guint32 offset; } DirEntry; - +/** + * SimpleTypeBlob: + * @is_pointer: Indicates whether the type is passed by reference. + * @tag: A #GITypeTag + * @offset: Offset relative to header->types that points to a TypeBlob. + * Unlike other offsets, this is in words (ie 32bit units) rather + * than bytes. + */ typedef union { struct @@ -119,9 +314,50 @@ typedef union guint32 offset; } SimpleTypeBlob; - -typedef struct -{ +/* + * ArgBlob: + * @name: A suggested name for the parameter. + * @in: The parameter is an input to the function + * @out: The parameter is used to return an output of the function. + * Parameters can be both in and out. Out parameters implicitly + * add another level of indirection to the parameter type. Ie if + * the type is uint32 in an out parameter, the function actually + * takes an uint32*. + * @dipper: The parameter is a pointer to a struct or object that will + * receive an output of the function. + * @allow_none: Only meaningful for types which are passed as pointers. + * For an in parameter, indicates if it is ok to pass NULL in, for + * an out parameter, whether it may return NULL. Note that NULL is a + * valid GList and GSList value, thus allow_none will normally be set + * for parameters of these types. + * @optional: For an out parameter, indicates that NULL may be passed in + * if the value is not needed. + * @transfer_ownership: For an in parameter, indicates that the function takes over + * ownership of the parameter value. For an out parameter, it + * indicates that the caller is responsible for freeing the return + * value. + * @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. + * 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 + * either void or a boolean indicating the success of the call. + * @scope: A #GIScopeType. If the parameter is of a callback type, this denotes the scope + * of the user_data and the callback function pointer itself + * (for languages that emit code at run-time). + * @closure: Index of the closure (user_data) parameter associated with the callback, + * or -1. + * @destroy: Index of the destroy notfication callback parameter associated with + * the callback, or -1. + * @arg_type: Describes the type of the parameter. See details below. + * + * Types are specified by four bytes. If the three high bytes are zero, + * the low byte describes a basic type, otherwise the 32bit number is an + * offset which points to a TypeBlob. + */ +typedef struct { guint32 name; guint in : 1; @@ -141,8 +377,21 @@ typedef struct SimpleTypeBlob arg_type; } ArgBlob; -typedef struct -{ +/** + * SignatureBlob: + * @return_type: Describes the type of the return value. See details below. + * @may_return_null: Only relevant for pointer types. Indicates whether the caller + * must expect NULL as a return value. + * @caller_owns_return_value: If set, the caller is responsible for freeing the return value + * if it is no longer needed. + * @caller_owns_return_container: This flag is only relevant if the return type is a container type. + * If the flag is set, the caller is resonsible for freeing the + * container, but not its contents. + * @n_arguments: The number of arguments that this function expects, also the length + * of the array of ArgBlobs. + * @arguments: An array of ArgBlob for the arguments of the function. + */ +typedef struct { SimpleTypeBlob return_type; guint16 may_return_null : 1; @@ -155,8 +404,16 @@ typedef struct ArgBlob arguments[]; } SignatureBlob; -typedef struct -{ +/** + * CommonBlob: + * @blob_type: A #GTypelibBlobType + * @deprecated: Whether the blob is deprecated. + * @name: The name of the blob. + * + * The #CommonBlob is shared between #FunctionBlob, + * #CallbackBlob, #SignalBlob. + */ +typedef struct { guint16 blob_type; /* 1 */ guint16 deprecated : 1; @@ -165,8 +422,30 @@ typedef struct guint32 name; } CommonBlob; -typedef struct -{ +/** + * FunctionBlob: + * @blob_Type: #BLOB_TYPE_FUNCTION + * @symbol: The symbol which can be used to obtain the function pointer with + * dlsym(). + * @deprecated: The function is deprecated. + * @setter: The function is a setter for a property. Language bindings may + * prefer to not bind individual setters and rely on the generic + * g_object_set(). + * @getter: The function is a getter for a property. Language bindings may + * prefer to not bind individual getters and rely on the generic + * g_object_get(). + * @constructor:The function acts as a constructor for the object it is contained + * in. + * @wraps_vfunc: The function is a simple wrapper for a virtual function. + * @index: Index of the property that this function is a setter or getter of + * in the array of properties of the containing interface, or index + * of the virtual function that this function wraps. + * @signature: Offset of the SignatureBlob describing the parameter types and the + * return value type. + * @is_static: The function is a "static method"; in other words it's a pure + * function whose name is conceptually scoped to the object. + */ +typedef struct { guint16 blob_type; /* 1 */ guint16 deprecated : 1; @@ -189,8 +468,12 @@ typedef struct guint16 reserved2 : 16; } FunctionBlob; -typedef struct -{ +/** + * CallbackBlob: + * @signature: Offset of the #SignatureBlob describing the parameter types and the + * return value type. + */ +typedef struct { guint16 blob_type; /* 2 */ guint16 deprecated : 1; @@ -200,8 +483,16 @@ typedef struct guint32 signature; } CallbackBlob; -typedef struct -{ +/** + * InterfaceTypeBlob: + * @pointer: Whether this type represents an indirection + * @tag: A #GITypeTag + * @interface: Index of the directory entry for the interface. + * + * Types which are described by an entry in the typelib have a tag value of 21. + * If the interface is an enum of flags type, is_pointer is 0, otherwise it is 1. + */ +typedef struct { guint8 pointer :1; guint8 reserved :2; guint8 tag :5; @@ -209,8 +500,23 @@ typedef struct guint16 interface; } InterfaceTypeBlob; -typedef struct -{ +/** + * ArrayTypeBlob: + * @zero_terminated: Indicates that the array must be terminated by a suitable #NULL + * value. + * @has_length: Indicates that length points to a parameter specifying the length + * of the array. If both has_length and zero_terminated are set, the + * convention is to pass -1 for the length if the array is + * zero-terminated. + * @length: The index of the parameter which is used to pass the length of the + * array. The parameter must be an integer type and have the same + * direction as this one. + * @type: The type of the array elements. + * + * Arrays have a tag value of 20. They are passed by reference, thus is_pointer + * is always 1. + */ +typedef struct { guint16 pointer :1; guint16 reserved :2; guint16 tag :5; @@ -228,8 +534,13 @@ typedef struct SimpleTypeBlob type; } ArrayTypeBlob; -typedef struct -{ +/** + * ParamTypeBlob: + * @n_types: The number of parameter types to follow. + * @type: Describes the type of the list elements. + * + */ +typedef struct { guint8 pointer :1; guint8 reserved :2; guint8 tag :5; @@ -240,8 +551,12 @@ typedef struct SimpleTypeBlob type[]; } ParamTypeBlob; -typedef struct -{ +/** + * ErrorTypeBlob: + * @n_domains: The number of domains to follow + * @domains: Indices of the directory entries for the error domains + */ +typedef struct { guint8 pointer :1; guint8 reserved :2; guint8 tag :5; @@ -252,8 +567,14 @@ typedef struct guint16 domains[]; } ErrorTypeBlob; -typedef struct -{ +/** + * ErrorDomainBlob: + * @get_quark: The symbol name of the function which must be called to obtain the + * GQuark for the error domain. + * @error_codes: Index of the InterfaceBlob describing the enumeration which lists + * the possible error codes. + */ +typedef struct { guint16 blob_type; /* 10 */ guint16 deprecated : 1; @@ -266,16 +587,34 @@ typedef struct guint16 reserved2; } ErrorDomainBlob; -typedef struct -{ +/** + * ValueBlob: + * @deprecated: Whether this value is deprecated + * @value: The numerical value + * @name: Name of blob + * + * Values commonly occur in enums and flags. + */ +typedef struct { guint32 deprecated : 1; guint32 reserved :31; guint32 name; guint32 value; } ValueBlob; -typedef struct -{ +/** + * FieldBlob: + * @name: The name of the field. + * @readable: + * @writable: How the field may be accessed. + * @bits: If this field is part of a bitfield, the number of bits which it + * uses, otherwise 0. + * @struct_offset: + * The offset of the field in the struct. The value 0xFFFF indicates + * that the struct offset is unknown. + * @type: The type of the field. + */ +typedef struct { guint32 name; guint8 readable :1; @@ -288,8 +627,12 @@ typedef struct SimpleTypeBlob type; } FieldBlob; -typedef struct -{ +/** + * RegisteredTypeBlob: + * @gtype_name: The name under which the type is registered with GType. + * @gtype_init: The symbol name of the get_type() function which registers the type. + */ +typedef struct { guint16 blob_type; guint16 deprecated : 1; guint16 unregistered : 1; @@ -300,8 +643,23 @@ typedef struct guint32 gtype_init; } RegisteredTypeBlob; -typedef struct -{ +/** + * StructBlob: + * @blob_type: #BLOB_TYPE_STRUCT + * @deprecated: Whether this structure is deprecated + * @unregistered: If this is set, the type is not registered with GType. + * @alignment: The byte boundary that the struct is aligned to in memory + * @is_class_struct: Whether this structure is the "class structure" for a GObject + * @size: The size of the struct in bytes. + * @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 { guint16 blob_type; guint16 deprecated : 1; @@ -327,8 +685,24 @@ typedef struct #endif } StructBlob; -typedef struct -{ +/** + * UnionBlob; + * @unregistered: If this is set, the type is not registered with GType. + * @discriminated: Is set if the union is discriminated + * @alignment: The byte boundary that the union is aligned to in memory + * @size: The size of the union in bytes. + * @gtype_name: String name of the associated #GType + * @gtype_init: String naming the symbol which gets the runtime #GType + * @n_fields: Length of the arrays + * @discriminator_offset: Offset from the beginning of the union where the + * discriminator of a discriminated union is located. + * 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 { guint16 blob_type; guint16 deprecated : 1; guint16 unregistered : 1; @@ -355,8 +729,17 @@ typedef struct #endif } UnionBlob; -typedef struct -{ +/** + * EnumBlob: + * @unregistered: If this is set, the type is not registered with GType. + * @storage_type: The tag of the type used for the enum in the C ABI + * (will be a signed or unsigned integral type) + * @gtype_name: String name of the associated #GType + * @gtype_init: String naming the symbol which gets the runtime #GType + * @n_values: The lengths of the values arrays. + * @values: Describes the enum values. + */ +typedef struct { guint16 blob_type; guint16 deprecated : 1; @@ -375,8 +758,16 @@ typedef struct ValueBlob values[]; } EnumBlob; -typedef struct -{ +/** + * PropertyBlob: + * @name: The name of the property. + * @readable: + * @writable: + * @construct: + * @construct_only: The ParamFlags used when registering the property. + * @type: Describes the type of the property. + */ +typedef struct { guint32 name; guint32 deprecated : 1; @@ -390,8 +781,24 @@ typedef struct } PropertyBlob; -typedef struct -{ +/** + * SignalBlob: + * @name: The name of the signal. + * @run_first: + * @run_last: + * @run_cleanup: + * @no_recurse: + * @detailed: + * @action: + * @no_hooks: The flags used when registering the signal. + * @has_class_closure: Set if the signal has a class closure. + * @true_stops_emit: Whether the signal has true-stops-emit semantics + * @class_closure: The index of the class closure in the list of virtual functions + * of the object or interface on which the signal is defined. + * @signature: Offset of the SignatureBlob describing the parameter types and the + * return value type. + */ +typedef struct { guint16 deprecated : 1; guint16 run_first : 1; guint16 run_last : 1; @@ -411,8 +818,24 @@ typedef struct guint32 signature; } SignalBlob; -typedef struct -{ +/** + * VFuncBlob: + * @name: The name of the virtual function. + * @must_chain_up: If set, every implementation of this virtual function must + * chain up to the implementation of the parent class. + * @must_be_implemented: If set, every derived class must override this virtual function. + * @must_not_be_implemented: If set, derived class must not override this virtual function. + * @class_closure: Set if this virtual function is the class closure of a signal. + * @signal: The index of the signal in the list of signals of the object or + * interface to which this virtual function belongs. + * @struct_offset: + * The offset of the function pointer in the class struct. The value + * 0xFFFF indicates that the struct offset is unknown. + * @signature: + * Offset of the SignatureBlob describing the parameter types and the + * return value type. + */ +typedef struct { guint32 name; guint16 must_chain_up : 1; @@ -427,8 +850,31 @@ typedef struct guint32 signature; } VFuncBlob; -typedef struct -{ +/** + * ObjectBlob: + * @blob_type: #BLOB_TYPE_OBJECT + * @gtype_name: String name of the associated #GType + * @gtype_init: String naming the symbol which gets the runtime #GType + * @parent: The directory index of the parent type. This is only set for + * objects. If an object does not have a parent, it is zero. + * @n_interfaces: + * @n_fields: + * @n_properties: + * @n_methods: + * @n_signals: + * @n_vfuncs: + * @n_constants: The lengths of the arrays.Up to 16bits of padding may be inserted + * between the arrays to ensure that they start on a 32bit boundary. + * @interfaces: An array of indices of directory entries for the implemented + * interfaces. + * @fields: Describes the fields. + * @methods: Describes the methods, constructors, setters and getters. + * @properties: Describes the properties. + * @signals: Describes the signals. + * @vfuncs: Describes the virtual functions. + * @constants: Describes the constants. + */ +typedef struct { guint16 blob_type; /* 7 */ guint16 deprecated : 1; guint16 abstract : 1; @@ -463,8 +909,24 @@ typedef struct #endif } ObjectBlob; -typedef struct -{ +/** + * InterfaceBlob: + * @n_prerequisites: Number of prerequisites + * @n_properties: Number of properties + * @n_methods: Number of methods + * @n_signals: Number of signals + * @n_vfuncs: Number of virtual functions + * @n_constants: The lengths of the arrays. + * Up to 16bits of padding may be inserted between the arrays to ensure that they + * start on a 32bit boundary. + * @prerequisites: An array of indices of directory entries for required interfaces. + * @methods: Describes the methods, constructors, setters and getters. + * @properties: Describes the properties. + * @signals: Describes the signals. + * @vfuncs: Describes the virtual functions. + * @constants: Describes the constants. + */ +typedef struct { guint16 blob_type; guint16 deprecated : 1; guint16 reserved :15; @@ -492,9 +954,14 @@ typedef struct #endif } InterfaceBlob; - -typedef struct -{ +/** + * ConstantBlob: + * @type: The type of the value. In most cases this should be a numeric + * type or string. + * @size: The size of the value in bytes. + * @offset: The offset of the value in the typelib. + */ +typedef struct { guint16 blob_type; guint16 deprecated : 1; guint16 reserved :15; @@ -506,14 +973,20 @@ typedef struct guint32 offset; } ConstantBlob; -typedef struct -{ +/** + * AnnotationBlob: + * @offset: The offset of the typelib entry to which this annotation refers. + * Annotations are kept sorted by offset, so that the annotations + * of an entry can be found by a binary search. + * @name: The name of the annotation, a string. + * @value: The value of the annotation (also a string) + */ +typedef struct { guint32 offset; guint32 name; guint32 value; } AnnotationBlob; - struct _GTypelib { guchar *data; gsize len; |