From 5b613e587adbd1c69eb9c568e5966c32bdc30258 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Thu, 12 Feb 2009 01:46:59 +0000 Subject: Bug 571373 - Move typelib docs from typelib-format.txt into girepository.h typelib-format.txt was growing out of date; a good solution to this is to move it closer to the code it's documenting. By doing this we also gain the ability to use gtk-doc on it. --- diff --git a/docs/reference/gi-docs.sgml b/docs/reference/gi-docs.sgml index f22449a..7492384 100644 --- a/docs/reference/gi-docs.sgml +++ b/docs/reference/gi-docs.sgml @@ -29,20 +29,15 @@ Bla bla bla bla bla --> - - GIR markup format - - + + GObject Introspection Tools - - Typelib binary format - &gi-gtypelib; + &g-ir-scanner; + &g-ir-compiler; + &g-ir-generator; +--> GIRepository @@ -54,15 +49,20 @@ Bla bla bla bla bla &gi-girffi; + + GIR markup format + + - &g-ir-scanner; - &g-ir-compiler; - &g-ir-generator; + + Typelib binary format + &gi-gtypelib; ---> diff --git a/docs/reference/gi-sections.txt b/docs/reference/gi-sections.txt index 0371c70..69d87ed 100644 --- a/docs/reference/gi-sections.txt +++ b/docs/reference/gi-sections.txt @@ -189,8 +189,35 @@ g_irepository_get_type
gtypelib -G_IR_MAGIC GTypelib +G_IR_MAGIC +GTypelibBlobType +Header +DirEntry +SimpleTypeBlob +ArgBlob +SignatureBlob +CommonBlob +FunctionBlob +CallbackBlob +InterfaceTypeBlob +ArrayTypeBlob +ParamTypeBlob +ErrorTypeBlob +ErrorDomainBlob +ValueBlob +FieldBlob +RegisteredTypeBlob +StructBlob +UnionBlob +EnumBlob +PropertyBlob +SignalBlob +VFuncBlob +ObjectBlob +InterfaceBlob +ConstantBlob +AnnotationBlob g_typelib_get_dir_entry g_typelib_check_sanity g_typelib_get_string diff --git a/docs/typelib-format.txt b/docs/typelib-format.txt deleted file mode 100644 index 68125cd..0000000 --- a/docs/typelib-format.txt +++ /dev/null @@ -1,1152 +0,0 @@ -GObject binary typelib for introspection ------------------------------------------ - -Version 0.9 - -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 - - -Typelib --------- - -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. - -Overview --------- - -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). - -Header (70 bytes) - -struct Header -{ - gchar[16] magic; - guint8 major_version; - guint8 minor_version; - guint16 reserved; - - guint16 n_entries; - guint16 n_local_entries; - guint32 directory; - guint32 annotations; - - guint32 dependencies; - - guint32 size; - guint32 namespace; - guint32 nsversion; - - guint16 entry_blob_size; /* 12 */ - guint16 function_blob_size; /* 16 */ - guint16 callback_blob_size; /* 12 */ - guint16 signal_blob_size; /* 12 */ - guint16 vfunc_blob_size; /* 16 */ - guint16 arg_blob_size; /* 12 */ - guint16 property_blob_size; /* 12 */ - guint16 field_blob_size; /* 12 */ - guint16 value_blob_size; /* 16 */ - guint16 constant_blob_size; /* 20 */ - guint16 error_domain_blob_size; /* 16 */ - guint16 annotation_blob_size; /* 12 */ - - guint16 signature_blob_size; /* 4 */ - guint16 enum_blob_size; /* 20 */ - guint16 struct_blob_size; /* 20 */ - guint16 object_blob_size; /* 32 */ - guint16 interface_blob_size; /* 28 */ - guint16 union_blob_size; /* 28 */ -} - -magic: The string "GOBJ\nMETADATA\r\n\032". This was inspired by XPCOM, - which in turn borrowed from PNG. - -major_version, -minor_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. - -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. - FIXME: need to specify if and how the directory is sorted - -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 of the typelib. - -namespace: - Offset of the namespace string in the typelib. -nsversion: - Offset of the namespace version string in the typelib. - -entry_blob_size: -function_blob_size: -callback_blob_size: -signal_blob_size: -vfunc_blob_size: -arg_blob_size: -property_blob_size: -field_blob_size: -value_blob_size: -annotation_blob_size: -constant_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. - -signature_blob_size: -enum_blob_size: -struct_blob_size: -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. - - -Directory entry (12 bytes) - -References to directory entries are stored as 1-based 16-bit indexes. - -struct DirectoryEntry -{ - guint16 blob_type; - - guint is_local : 1; - guint reserved :15; - - guint32 name; - guint32 offset; -} - -blob_type: - The type of blob this entry points to: - 0 unknown (allowed only for non-local entries) - 1 function - 2 callback - 3 struct - 4 boxed - 5 enum - 6 flags - 7 object - 8 interface - 9 constant - 10 errordomain - - -is_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. - - -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) - -struct InterfacePrefix -{ - guint16 blob_type; - guint deprecated : 1; - guint reserved :15; - guint32 name; -} - -blob_type: - An integer specifying the type of the blob, see DirectoryEntry - for details. - -deprecated: - Whether the blob is deprecated. - -name: The name of the blob. - - -The SignatureBlob is shared between Functions, -Callbacks, Signals and VirtualFunctions. - -SignatureBlob (8 + 12 * n_arguments bytes) - -struct SignatureBlob -{ - SimpleTypeBlob return_type; - - guint may_return_null : 1; - guint caller_owns_return_value : 1; - guint caller_owns_return_container : 1; - guint reserved :13; - - guint16 n_arguments; - - ArgBlob[] arguments; -} - - -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. - - -FunctionBlob (20 bytes) - -struct FunctionBlob -{ - guint16 blob_type; /* 1 */ - - guint deprecated : 1; - guint is_setter : 1; - guint is_getter : 1; - guint is_constructor : 1; - guint wraps_vfunc : 1; - guint throws : 1; - guint index :10; - - guint32 name; - guint32 c_name; - guint32 signature; - guint is_static : 1; - guint reserved : 31; -} - -c_name: The symbol which can be used to obtain the function pointer with - dlsym(). - -deprecated - The function is deprecated. - -is_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(). - -is_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(). - -is_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. - - -CallbackBlob (12 bytes) - -struct CallbackBlob -{ - guint16 blob_type; /* 2 */ - - guint deprecated : 1; - guint reserved :15; - - guint32 name; - guint32 signature; -} - -signature: - Offset of the SignatureBlob describing the parameter types and the - return value type. - - -ArgBlob (12 bytes) - -struct ArgBlob -{ - guint32 name; - - guint in : 1; - guint out : 1; - guint dipper : 1; - guint allow_none : 1; - guint optional : 1; - guint transfer_ownership : 1; - guint transfer_container_ownership : 1; - guint is_return_value : 1; - guint scope : 3; - guint reserved :21: - - gint8 closure; - gint8 destroy; - - SimpleTypeBlob arg_type; -} - -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: - 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). - - 0 invalid -- the argument is not of callback type - 1 call -- the callback and associated user_data is - only used during the call to this function - 2 object -- the callback and associated user_data is - used until the object containing this method is destroyed - 3 async -- the callback and associated user_data is - only used until the callback is invoked, and the callback - is invoked always exactly once. - 4 notified -- the callback and and associated user_data is - used until the caller is notfied via the destroy_notify - -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. - - -SimpleTypeBlob (4 bytes) - -union SimpleTypeBlob -{ - struct - { - guint reserved :24; /* 0 */ - guint is_pointer : 1; - guint reserved : 2; - guint tag : 5; - }; - guint32 offset; -} - -is_pointer: - indicates whether the type is passed by reference. - -tag: specifies what kind of type is described, as follows: - 0 void - 1 boolean (booleans are passed as ints) - 2 int8 - 3 uint8 - 4 int16 - 5 uint16 - 6 int32 - 7 uint32 - 8 int64 - 9 uint64 - 10 int - 11 uint - 12 long - 13 ulong - 14 ssize_t - 15 size_t - 16 float - 17 double - 18 time_t - 19 GType - 20 utf8 (these are zero-terminated char[] and assumed to be - in UTF-8) - 21 filename (these are zero-terminated char[] and assumed to be - in the GLib filename encoding) - - For utf8 and filename is_pointer will always be set. - -offset: Offset relative to header->types that points to a TypeBlob. - Unlike other offsets, this is in words (ie 32bit units) rather - than bytes. - - -TypeBlob (4 or more bytes) - -union TypeBlob -{ - ArrayTypeBlob array_type; - InterfaceTypeBlob interface_type; - ParameterTypeBlob parameter_type; - ErrorTypeBlob error_type; -} - - -ArrayTypeBlob (4 bytes) - -Arrays have a tag value of 20. They are passed by reference, thus is_pointer -is always 1. - -struct ArrayTypeBlob -{ - guint is_pointer :1; /* 1 */ - guint reserved :2; - guint tag :5; /* 20 */ - guint zero_terminated :1; - guint has_length :1; - guint length :6; - - SimpleTypeBlob type; -} - -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. - FIXME: what does this mean for types of field and properties ? - -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. - - -InterfaceTypeBlob (4 bytes) - -struct InterfaceTypeBlob -{ - guint is_pointer :1; - guint reserved :2; - guint tag :5; /* 21 */ - guint8 reserved; - - guint16 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. - -interface: - Index of the directory entry for the interface. - - -ParameterTypeBlob (4 + n * 4 bytes) - -GLists have a tag value of 22, GSLists have a tag value of 23, GHashTables have a -tag value of 24. They are passed by reference, thus is_pointer is always 1. - -struct ParameterTypeBlob -{ - guint is_pointer :1; /* 1 */ - guint reserved :2; - guint tag :5; /* 22, 23 or 24 */ - guint reserved :8; - - guint16 n_types; - - SimpleTypeBlob type[]; -} - -n_types: The number of parameter types to follow. - -type: Describes the type of the list elements. - - -ErrorTypeBlob (4 + 2 * n_domains bytes) - -struct ErrorTypeBlob -{ - guint is_pointer :1; /* 1 */ - guint reserved :2; - guint tag :5; /* 25 */ - - guint8 reserved; - - guint16 n_domains; - - guint16 domains[]; -} - -n_domains: - The number of domains to follow - -domains: Indices of the directory entries for the error domains - - -ErrorDomainBlob (16 bytes) - -struct ErrorDomainBlob -{ - guint16 blob_type; /* 10 */ - - guint deprecated : 1; - guint reserved :15; - - guint32 name; - - guint32 get_quark; - guint16 error_codes; -} - -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. - - -PropertyBlob (12 bytes) - -struct PropertyBlob -{ - guint32 name; - - guint deprecated : 1; - guint readable : 1; - guint writable : 1; - guint construct : 1; - guint construct_only : 1; - guint reserved :27 - - SimpleTypeBlob type; -} - -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. - - -SignalBlob (12 bytes) - -struct SignalBlob -{ - guint32 name; - - guint deprecated : 1; - guint run_first : 1; - guint run_last : 1; - guint run_cleanup : 1; - guint no_recurse : 1; - guint detailed : 1; - guint action : 1; - guint no_hooks : 1; - guint has_class_closure : 1; - guint true_stops_emit : 1; - guint reserved : 5; - - guint16 class_closure; - guint32 signature; -} - -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. - - -VirtualFunctionBlob (16 bytes) - -struct VirtualFunctionBlob -{ - guint32 name; - - guint must_chain_up : 1; - guint must_be_implemented : 1; - guint must_not_be_implemented : 1; - guint is_class_closure : 1; - guint reserved :12; - - guint16 signal; - guint16 struct_offset; - guint16 reserved; - guint32 signature; -} - -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. - -is_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. - - -FieldBlob (12 bytes) - -struct FieldBlob -{ - guint32 name; - - guint readable : 1; - guint writable : 1; - guint reserved : 6; - guint8 bits; - - guint16 struct_offset; - - SimpleTypeBlob type; -} - -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. - - -ValueBlob (12 bytes) - -Values commonly occur in enums and flags. - -struct ValueBlob -{ - guint deprecated : 1; - guint reserved :31; - guint32 name; - - guint32 value; -} - -value: The numerical value; - - -GTypeBlob (8 bytes) - -struct GTypeBlob -{ - guint32 gtype_name; - guint32 gtype_init; -} - -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. - - -StructBlob (20 + 8 * n_fields + x * n_functions) - -struct StructBlob -{ - guint16 blob_type; /* 3: struct, 4: boxed */ - guint deprecated : 1; - guint unregistered : 1; - guint alignment : 6; - guint is_class_struct : 1 - guint reserved : 7; - guint32 name; - - GTypeBlob gtype; - - guint32 size; - - guint16 n_fields; - guint16 n_functions; - - FieldBlob fields[]; - FunctionBlob functions[]; -} - -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: For types which are registered with GType, contains the - information about the GType. Otherwise unused. - -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. - - -EnumBlob (20 + 16 * n_values) - -struct EnumBlob -{ - guint16 blob_type; /* 5: enum, 6: flags */ - guint deprecated : 1; - guint unregistered : 1; - guint storage_type : 5; - guint reserved : 9; - guint32 name; - - GTypeBlob gtype; - - guint16 n_values; - guint16 reserved; - - ValueBlob values[]; -} - -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: For types which are registered with GType, contains the - information about the GType. Otherwise unused. - -n_values: - The lengths of the values arrays. - -values: Describes the enum values. - - -ObjectBlob (36 + x bytes) - -struct ObjectBlob -{ - guint16 blob_type; /* 7 */ - guint deprecated : 1; - guint abstract : 1; - guint reserved :14; - guint32 name; - - GTypeBlob gtype; - - guint16 parent; - guint16 class_struct; - - guint16 n_interfaces; - guint16 n_fields; - guint16 n_properties; - guint16 n_methods; - guint16 n_signals; - guint16 n_virtual_functions; - guint16 n_constants; - - guint16 interfaces[]; - - FieldBlob fields[]; - PropertyBlob properties[]; - FunctionBlob methods[]; - SignalBlob signals[]; - VirtualFunctionBlob virtual_functions[]; - ConstantBlob constants[]; -} - -gtype: Contains the information about the 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_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. - -interfaces: - An array of indices of directory entries for the implemented - interfaces. - -fields: Describes the fields. - -functions: - Describes the methods, constructors, setters and getters. - -properties: - Describes the properties. - -signals: Describes the signals. - -virtual_functions: - Describes the virtual functions. - -constants: - Describes the constants. - - -InterfaceBlob (28 + x bytes) - -struct InterfaceBlob -{ - guint16 blob_type; /* 8 */ - guint deprecated : 1; - guint reserved :15; - guint32 name; - - GTypeBlob gtype; - - guint16 n_prerequisites; - guint16 n_properties; - guint16 n_methods; - guint16 n_signals; - guint16 n_virtual_functions; - guint16 n_constants; - - guint16 prerequisites[]; - - PropertyBlob properties[]; - FunctionBlob methods[]; - SignalBlob signals[]; - VirtualFunctionBlob virtual_functions[]; - ConstantBlob constants[]; -} - -n_prerequisites: -n_properties: -n_methods: -n_signals: -n_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. - -functions: - Describes the methods, constructors, setters and getters. - -properties: - Describes the properties. - -signals: Describes the signals. - -virtual_functions: - Describes the virtual functions. - -constants: - Describes the constants. - - -ConstantBlob (20 bytes) - -struct ConstantBlob -{ - guint16 blob_type; /* 9 */ - guint deprecated : 1; - guint reserved :15; - guint32 name; - - SimpleTypeBlob type; - guint32 size; - guint32 offset; -} - -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. - - -AnnotationBlob (12 bytes) - -struct AnnotationBlob -{ - guint32 offset; - guint32 name; - guint32 value; -} - -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) - - -UnionBlob (28 + x bytes) - -struct UnionBlob -{ - guint16 blob_type; /* 11 */ - guint deprecated : 1; - guint unregistered : 1; - guint discriminated : 1; - guint alignment : 6; - guint reserved : 7; - guint32 name; - - GTypeBlob gtype; - - guint32 size; - - guint16 n_fields; - guint16 n_functions; - - gint32 discriminator_offset; - SimpleTypeBlob discriminator_type; - - FieldBlob fields[]; - FunctionBlob functions[]; - ConstantBlob discriminator_values[] -} - -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: For types which are registered with GType, contains the - information about the GType. Otherwise unused. - -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 diff --git a/girepository/girepository.h b/girepository/girepository.h index 7ec8612..3508f4d 100644 --- a/girepository/girepository.h +++ b/girepository/girepository.h @@ -279,11 +279,16 @@ typedef enum { } GIDirection; typedef enum { - GI_SCOPE_TYPE_INVALID, - GI_SCOPE_TYPE_CALL, - GI_SCOPE_TYPE_OBJECT, - GI_SCOPE_TYPE_ASYNC, - GI_SCOPE_TYPE_NOTIFIED + 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_OBJECT, /* The callback and associated user_data is used until + the object containing this method is destroyed */ + 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 */ } GIScopeType; GIDirection g_arg_info_get_direction (GIArgInfo *info); 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; -- cgit v0.9.1