git.roojs.org Git - gnome.gobject-introspection/blob - girepository/gtypelib.h

   1 /* GObject introspection: struct definitions for the binary
   2  * typelib format, validation
   3  *
   4  * Copyright (C) 2005 Matthias Clasen
   5  * Copyright (C) 2008,2009 Red Hat, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #ifndef __G_TYPELIB_H__
  24 #define __G_TYPELIB_H__
  25
  26 #include <gmodule.h>
  27 #include "girepository.h"
  28
  29 G_BEGIN_DECLS
  30
  31 /**
  32  * SECTION:gtypelib
  33  * @short_description: Layout and accessors for typelib
  34  * @stability: Stable
  35  *
  36  * The "typelib" is a binary, readonly, memory-mappable database
  37  * containing reflective information about a GObject library.
  38  *
  39  * The format of GObject typelib is strongly influenced by the Mozilla XPCOM
  40  * format.
  41  *
  42  * Some of the differences to XPCOM include:
  43  * - Type information is stored not quite as compactly (XPCOM stores it inline
  44  * in function descriptions in variable-sized blobs of 1 to n bytes. We store
  45  * 16 bits of type information for each parameter, which is enough to encode
  46  * simple types inline. Complex (e.g. recursive) types are stored out of line
  47  * in a separate list of types.
  48  * - String and complex type data is stored outside of typelib entry blobs,
  49  * references are stored as offsets relative to the start of the typelib.
  50  * One possibility is to store the strings and types in a pools at the end
  51  * of the typelib.
  52  *
  53  * The typelib has the following general format.
  54  *
  55  * typelib ::= header, directory, blobs, attributes, attributedata
  56  *
  57  * directory ::= list of entries
  58  *
  59  * entry ::= blob type, name, namespace, offset
  60  * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|errordomain|union
  61  * attributes ::= list of attributes, sorted by offset
  62  * attribute ::= offset, key, value
  63  * attributedata ::= string data for attributes
  64  *
  65  * Details
  66  *
  67  * We describe the fragments that make up the typelib in the form of C structs
  68  * (although some fall short of being valid C structs since they contain multiple
  69  * flexible arrays).
  70  */
  71
  72 /*
  73 TYPELIB HISTORY
  74 -----
  75 Version 1.0
  76 - Rename class_struct to gtype_struct, add to interfaces
  77
  78 Changes since 0.9:
  79 - Add padding to structures
  80
  81 Changes since 0.8:
  82 - Add class struct concept to ObjectBlob
  83 - Add is_class_struct bit to StructBlob
  84
  85 Changes since 0.7:
  86 - Add dependencies
  87
  88 Changes since 0.6:
  89 - rename metadata to typelib, to follow xpcom terminology
  90
  91 Changes since 0.5:
  92 - basic type cleanup:
  93   + remove GString
  94   + add [u]int, [u]long, [s]size_t
  95   + rename string to utf8, add filename
  96 - allow blob_type to be zero for non-local entries
  97
  98 Changes since 0.4:
  99 - add a UnionBlob
 100
 101 Changes since 0.3:
 102 - drop short_name for ValueBlob
 103
 104 Changes since 0.2:
 105 - make inline types 4 bytes after all, remove header->types and allow
 106   types to appear anywhere
 107 - allow error domains in the directory
 108
 109 Changes since 0.1:
 110
 111 - drop comments about _GOBJ_METADATA
 112 - drop string pool, strings can appear anywhere
 113 - use 'blob' as collective name for the various blob types
 114 - rename 'type' field in blobs to 'blob_type'
 115 - rename 'type_name' and 'type_init' fields to 'gtype_name', 'gtype_init'
 116 - shrink directory entries to 12 bytes
 117 - merge struct and boxed blobs
 118 - split interface blobs into enum, object and interface blobs
 119 - add an 'unregistered' flag to struct and enum blobs
 120 - add a 'wraps_vfunc' flag to function blobs and link them to
 121   the vfuncs they wrap
 122 - restrict value blobs to only occur inside enums and flags again
 123 - add constant blobs, allow them toplevel, in interfaces and in objects
 124 - rename 'receiver_owns_value' and 'receiver_owns_container' to
 125   'transfer_ownership' and 'transfer_container_ownership'
 126 - add a 'struct_offset' field to virtual function and field blobs
 127 - add 'dipper' and 'optional' flags to arg blobs
 128 - add a 'true_stops_emit' flag to signal blobs
 129 - add variable blob sizes to header
 130 - store offsets to signature blobs instead of including them directly
 131 - change the type offset to be measured in words rather than bytes
 132 */
 133
 134 /**
 135  * G_IR_MAGIC:
 136  *
 137  * Identifying prefix for the typelib.  This was inspired by XPCOM,
 138  * which in turn borrowed from PNG.
 139  */
 140 #define G_IR_MAGIC "GOBJ\nMETADATA\r\n\032"
 141
 142 /**
 143  * GTypelibBlobType:
 144  * @BLOB_TYPE_INVALID: Should not appear in code
 145  * @BLOB_TYPE_FUNCTION: A #FunctionBlob
 146  * @BLOB_TYPE_CALLBACK: A #CallbackBlob
 147  * @BLOB_TYPE_STRUCT: A #StructBlob
 148  * @BLOB_TYPE_BOXED: Can be either a #StructBlob or #UnionBlob
 149  * @BLOB_TYPE_ENUM: An #EnumBlob
 150  * @BLOB_TYPE_FLAGS: An #EnumBlob
 151  * @BLOB_TYPE_OBJECT: An #ObjectBlob
 152  * @BLOB_TYPE_INTERFACE: An #InterfaceBlob
 153  * @BLOB_TYPE_CONSTANT: A #ConstantBlob
 154  * @BLOB_TYPE_ERROR_DOMAIN: A #ErrorDomainBlob
 155  * @BLOB_TYPE_UNION: A #UnionBlob
 156  *
 157  * The integral value of this enumeration appears in each "Blob"
 158  * component of a typelib to identify its type.
 159  */
 160 typedef enum {
 161   BLOB_TYPE_INVALID,
 162   BLOB_TYPE_FUNCTION,
 163   BLOB_TYPE_CALLBACK,
 164   BLOB_TYPE_STRUCT,
 165   BLOB_TYPE_BOXED,
 166   BLOB_TYPE_ENUM,
 167   BLOB_TYPE_FLAGS,
 168   BLOB_TYPE_OBJECT,
 169   BLOB_TYPE_INTERFACE,
 170   BLOB_TYPE_CONSTANT,
 171   BLOB_TYPE_ERROR_DOMAIN,
 172   BLOB_TYPE_UNION
 173 } GTypelibBlobType;
 174
 175 #define BLOB_IS_REGISTERED_TYPE(blob)               \
 176         ((blob)->blob_type == BLOB_TYPE_STRUCT ||   \
 177          (blob)->blob_type == BLOB_TYPE_UNION  ||   \
 178          (blob)->blob_type == BLOB_TYPE_ENUM   ||   \
 179          (blob)->blob_type == BLOB_TYPE_OBJECT ||   \
 180          (blob)->blob_type == BLOB_TYPE_INTERFACE)
 181
 182 /**
 183  * Header:
 184  * @magic: See #G_IR_MAGIC.
 185  * @major_version: The version of the typelib format. Minor version changes indicate
 186  * compatible changes and should still allow the typelib to be parsed
 187  * by a parser designed for the same major_version.
 188  * @minor_version: See major_version.
 189  * @n_entries: The number of entries in the directory.
 190  * @n_local_entries: The number of entries referring to blobs in this typelib. The
 191  * local entries must occur before the unresolved entries.
 192  * @directory: Offset of the directory in the typelib.
 193  * @n_attributes: Number of attribute blocks
 194  * @attributes: Offset of the list of attributes in the typelib.
 195  * @dependencies: Offset of a single string, which is the list of
 196  * dependencies, separated by the '|' character.  The
 197  * dependencies are required in order to avoid having programs
 198  * consuming a typelib check for an "Unresolved" type return
 199  * from every API call.
 200  * @size: The size in bytes of the typelib.
 201  * @namespace: Offset of the namespace string in the typelib.
 202  * @nsversion: Offset of the namespace version string in the typelib.
 203  * @shared_library: This field is the set of shared libraries associated
 204  * with the typelib.  The entries are separated by the '|' (pipe) character.
 205  * @entry_blob_size: The sizes of fixed-size blobs. Recording this information here
 206  * allows to write parser which continue to work if the format is
 207  * extended by adding new fields to the end of the fixed-size blobs.
 208  * @function_blob_size: See above.
 209  * @callback_blob_size: See above.
 210  * @signal_blob_size: See above.
 211  * @vfunc_blob_size: See above.
 212  * @arg_blob_size: See above.
 213  * @property_blob_size: See above.
 214  * @field_blob_size: See above.
 215  * @value_blob_size: See above.
 216  * @attribute_blob_size: See above.
 217  * @constant_blob_size: See above.
 218  * @object_blob_size: See above.
 219  * @union_blob_size: See above.
 220  * @signature_blob_size: See above.
 221  * @enum_blob_size: See above.
 222  * @struct_blob_size: See above.
 223  * @error_domain_blob_size: See above.
 224  * @interface_blob_size: For variable-size blobs, the size of the struct up to the first
 225  * flexible array member. Recording this information here allows to
 226  * write parser which continue to work if the format is extended by
 227  * adding new fields before the first flexible array member in
 228  * variable-size blobs.
 229  *
 230  * The header structure appears exactly once at the beginning of a typelib.  It is a
 231  * collection of meta-information, such as the number of entries and dependencies.
 232  */
 233 typedef struct {
 234   gchar   magic[16];
 235   guint8  major_version;
 236   guint8  minor_version;
 237   guint16 reserved;
 238   guint16 n_entries;
 239   guint16 n_local_entries;
 240   guint32 directory;
 241   guint32 n_attributes;
 242   guint32 attributes;
 243
 244   guint32 dependencies;
 245
 246   guint32 size;
 247   guint32 namespace;
 248   guint32 nsversion;
 249   guint32 shared_library;
 250   guint32 c_prefix;
 251
 252   guint16 entry_blob_size;
 253   guint16 function_blob_size;
 254   guint16 callback_blob_size;
 255   guint16 signal_blob_size;
 256   guint16 vfunc_blob_size;
 257   guint16 arg_blob_size;
 258   guint16 property_blob_size;
 259   guint16 field_blob_size;
 260   guint16 value_blob_size;
 261   guint16 attribute_blob_size;
 262   guint16 constant_blob_size;
 263   guint16 error_domain_blob_size;
 264
 265   guint16 signature_blob_size;
 266   guint16 enum_blob_size;
 267   guint16 struct_blob_size;
 268   guint16 object_blob_size;
 269   guint16 interface_blob_size;
 270   guint16 union_blob_size;
 271
 272   guint16 padding[7];
 273 } Header;
 274
 275 /**
 276  * DirEntry:
 277  * @blob_type: A #GTypelibBlobType
 278  * @local: Whether this entry refers to a blob in this typelib.
 279  * @name: The name of the entry.
 280  * @offset:   If is_local is set, this is the offset of the blob in the typelib.
 281  * Otherwise, it is the offset of the namespace in which the blob has
 282  * to be looked up by name.
 283  *
 284  * References to directory entries are stored as 1-based 16-bit indexes.
 285  *
 286  * All blobs pointed to by a directory entry start with the same layout for
 287  * the first 8 bytes (the reserved flags may be used by some blob types)
 288  */
 289 typedef struct {
 290   guint16 blob_type;
 291
 292   guint16 local    : 1;
 293   guint16 reserved :15;
 294
 295   guint32 name;
 296   guint32 offset;
 297 } DirEntry;
 298
 299 /**
 300  * SimpleTypeBlob:
 301  * @is_pointer: Indicates whether the type is passed by reference.
 302  * @tag: A #GITypeTag
 303  * @offset:  Offset relative to header->types that points to a TypeBlob.
 304  * Unlike other offsets, this is in words (ie 32bit units) rather
 305  * than bytes.
 306  */
 307 typedef union
 308 {
 309   struct
 310   {
 311     guint reserved   : 8;
 312     guint reserved2  :16;
 313     guint pointer    : 1;
 314     guint reserved3  : 2;
 315     guint tag        : 5;
 316   };
 317   guint32    offset;
 318 } SimpleTypeBlob;
 319
 320 /*
 321  * ArgBlob:
 322  * @name: A suggested name for the parameter.
 323  * @in: The parameter is an input to the function
 324  * @out: The parameter is used to return an output of the function.
 325  * Parameters can be both in and out. Out parameters implicitly
 326  * add another level of indirection to the parameter type. Ie if
 327  * the type is uint32 in an out parameter, the function actually
 328  * takes an uint32*.
 329  * @dipper: The parameter is a pointer to a struct or object that will
 330  * receive an output of the function.
 331  * @allow_none: Only meaningful for types which are passed as pointers.
 332  * For an in parameter, indicates if it is ok to pass NULL in, for
 333  * an out parameter, whether it may return NULL. Note that NULL is a
 334  * valid GList and GSList value, thus allow_none will normally be set
 335  * for parameters of these types.
 336  * @optional: For an out parameter, indicates that NULL may be passed in
 337  * if the value is not needed.
 338  * @transfer_ownership: For an in parameter, indicates that the function takes over
 339  * ownership of the parameter value. For an out parameter, it
 340  * indicates that the caller is responsible for freeing the return
 341  * value.
 342  * @transfer_container_ownership: For container types, indicates that the
 343  * ownership of the container,  but not of its contents is transferred. This is typically the case
 344  * for out parameters returning lists of statically allocated things.
 345  * @is_return_value: The parameter should be considered the return value of the function.
 346  * Only out parameters can be marked as return value, and there can be
 347  * at most one per function call. If an out parameter is marked as
 348  * return value, the actual return value of the function should be
 349  * either void or a boolean indicating the success of the call.
 350  * @scope: A #GIScopeType. If the parameter is of a callback type, this denotes the scope
 351  * of the user_data and the callback function pointer itself
 352  * (for languages that emit code at run-time).
 353  * @closure: Index of the closure (user_data) parameter associated with the callback,
 354  * or -1.
 355  * @destroy: Index of the destroy notfication callback parameter associated with
 356  * the callback, or -1.
 357  * @arg_type: Describes the type of the parameter. See details below.
 358  *
 359  * Types are specified by four bytes. If the three high bytes are zero,
 360  * the low byte describes a basic type, otherwise the 32bit number is an
 361  * offset which points to a TypeBlob.
 362  */
 363 typedef struct {
 364   guint32        name;
 365
 366   guint          in                           : 1;
 367   guint          out                          : 1;
 368   guint          dipper                       : 1;
 369   guint          allow_none                   : 1;
 370   guint          optional                     : 1;
 371   guint          transfer_ownership           : 1;
 372   guint          transfer_container_ownership : 1;
 373   guint          return_value                 : 1;
 374   guint          scope                        : 3;
 375   guint          reserved                     :21;
 376
 377   gint8        closure;
 378   gint8        destroy;
 379
 380   SimpleTypeBlob arg_type;
 381 } ArgBlob;
 382
 383 /**
 384  * SignatureBlob:
 385  * @return_type: Describes the type of the return value. See details below.
 386  * @may_return_null: Only relevant for pointer types. Indicates whether the caller
 387  * must expect NULL as a return value.
 388  * @caller_owns_return_value: If set, the caller is responsible for freeing the return value
 389  * if it is no longer needed.
 390  * @caller_owns_return_container: This flag is only relevant if the return type is a container type.
 391  * If the flag is set, the caller is resonsible for freeing the
 392  * container, but not its contents.
 393  * @n_arguments: The number of arguments that this function expects, also the length
 394  * of the array of ArgBlobs.
 395  * @arguments: An array of ArgBlob for the arguments of the function.
 396  */
 397 typedef struct {
 398   SimpleTypeBlob return_type;
 399
 400   guint16        may_return_null              : 1;
 401   guint16        caller_owns_return_value     : 1;
 402   guint16        caller_owns_return_container : 1;
 403   guint16        reserved                     :13;
 404
 405   guint16        n_arguments;
 406
 407   ArgBlob        arguments[];
 408 } SignatureBlob;
 409
 410 /**
 411  * CommonBlob:
 412  * @blob_type: A #GTypelibBlobType
 413  * @deprecated: Whether the blob is deprecated.
 414  * @name: The name of the blob.
 415  *
 416  * The #CommonBlob is shared between #FunctionBlob,
 417  * #CallbackBlob, #SignalBlob.
 418  */
 419 typedef struct {
 420   guint16 blob_type;  /* 1 */
 421
 422   guint16 deprecated : 1;
 423   guint16 reserved   :15;
 424
 425   guint32 name;
 426 } CommonBlob;
 427
 428 /**
 429  * FunctionBlob:
 430  * @blob_Type: #BLOB_TYPE_FUNCTION
 431  * @symbol:   The symbol which can be used to obtain the function pointer with
 432  * dlsym().
 433  * @deprecated: The function is deprecated.
 434  * @setter: The function is a setter for a property. Language bindings may
 435  * prefer to not bind individual setters and rely on the generic
 436  * g_object_set().
 437  * @getter: The function is a getter for a property. Language bindings may
 438  * prefer to not bind individual getters and rely on the generic
 439  * g_object_get().
 440  * @constructor:The function acts as a constructor for the object it is contained
 441  * in.
 442  * @wraps_vfunc: The function is a simple wrapper for a virtual function.
 443  * @index: Index of the property that this function is a setter or getter of
 444  * in the array of properties of the containing interface, or index
 445  * of the virtual function that this function wraps.
 446  * @signature: Offset of the SignatureBlob describing the parameter types and the
 447  * return value type.
 448  * @is_static: The function is a "static method"; in other words it's a pure
 449  * function whose name is conceptually scoped to the object.
 450  */
 451 typedef struct {
 452   guint16 blob_type;  /* 1 */
 453
 454   guint16 deprecated  : 1;
 455   guint16 setter      : 1;
 456   guint16 getter      : 1;
 457   guint16 constructor : 1;
 458   guint16 wraps_vfunc : 1;
 459   guint16 throws      : 1;
 460   guint16 index       :10;
 461   /* Note the bits above need to match CommonBlob
 462    * and are thus exhausted, extend things using
 463    * the reserved block below. */
 464
 465   guint32 name;
 466   guint32 symbol;
 467   guint32 signature;
 468
 469   guint16 is_static   : 1;
 470   guint16 reserved    : 15;
 471   guint16 reserved2   : 16;
 472 } FunctionBlob;
 473
 474 /**
 475  * CallbackBlob:
 476  * @signature: Offset of the #SignatureBlob describing the parameter types and the
 477  * return value type.
 478  */
 479 typedef struct {
 480   guint16 blob_type;  /* 2 */
 481
 482   guint16 deprecated : 1;
 483   guint16 reserved   :15;
 484
 485   guint32 name;
 486   guint32 signature;
 487 } CallbackBlob;
 488
 489 /**
 490  * InterfaceTypeBlob:
 491  * @pointer: Whether this type represents an indirection
 492  * @tag: A #GITypeTag
 493  * @interface: Index of the directory entry for the interface.
 494  *
 495  * Types which are described by an entry in the typelib have a tag value of 21.
 496  * If the interface is an enum of flags type, is_pointer is 0, otherwise it is 1.
 497  */
 498 typedef struct {
 499   guint8  pointer  :1;
 500   guint8  reserved :2;
 501   guint8  tag      :5;
 502   guint8  reserved2;
 503   guint16 interface;
 504 } InterfaceTypeBlob;
 505
 506 /**
 507  * ArrayTypeBlob:
 508  * @zero_terminated: Indicates that the array must be terminated by a suitable #NULL
 509  * value.
 510  * @has_length: Indicates that length points to a parameter specifying the length
 511  * of the array. If both has_length and zero_terminated are set, the
 512  * convention is to pass -1 for the length if the array is
 513  * zero-terminated.
 514  * @length: The index of the parameter which is used to pass the length of the
 515  * array. The parameter must be an integer type and have the same
 516  * direction as this one.
 517  * @type: The type of the array elements.
 518  *
 519  * Arrays have a tag value of 20. They are passed by reference, thus is_pointer
 520  * is always 1.
 521  */
 522 typedef struct {
 523   guint16 pointer         :1;
 524   guint16 reserved        :2;
 525   guint16 tag             :5;
 526
 527   guint16 zero_terminated :1;
 528   guint16 has_length      :1;
 529   guint16 has_size        :1;
 530   guint16 reserved2       :5;
 531
 532   union {
 533     guint16 length;
 534     guint16 size;
 535   };
 536
 537   SimpleTypeBlob type;
 538 } ArrayTypeBlob;
 539
 540 /**
 541  * ParamTypeBlob:
 542  * @n_types: The number of parameter types to follow.
 543  * @type: Describes the type of the list elements.
 544  *
 545  */
 546 typedef struct {
 547   guint8         pointer  :1;
 548   guint8         reserved :2;
 549   guint8         tag      :5;
 550
 551   guint8         reserved2;
 552   guint16        n_types;
 553
 554   SimpleTypeBlob type[];
 555 } ParamTypeBlob;
 556
 557 /**
 558  * ErrorTypeBlob:
 559  * @n_domains: The number of domains to follow
 560  * @domains:  Indices of the directory entries for the error domains
 561  */
 562 typedef struct {
 563   guint8  pointer  :1;
 564   guint8  reserved :2;
 565   guint8  tag      :5;
 566
 567   guint8  reserved2;
 568   guint16 n_domains;
 569
 570   guint16 domains[];
 571 }  ErrorTypeBlob;
 572
 573 /**
 574  * ErrorDomainBlob:
 575  * @get_quark: The symbol name of the function which must be called to obtain the
 576  * GQuark for the error domain.
 577  * @error_codes: Index of the InterfaceBlob describing the enumeration which lists
 578  * the possible error codes.
 579  */
 580 typedef struct {
 581   guint16 blob_type;  /* 10 */
 582
 583   guint16 deprecated : 1;
 584   guint16 reserved   :15;
 585
 586   guint32 name;
 587
 588   guint32 get_quark;
 589   guint16 error_codes;
 590   guint16 reserved2;
 591 } ErrorDomainBlob;
 592
 593 /**
 594  * ValueBlob:
 595  * @deprecated: Whether this value is deprecated
 596  * @value: The numerical value
 597  * @name: Name of blob
 598  *
 599  * Values commonly occur in enums and flags.
 600  */
 601 typedef struct {
 602   guint32 deprecated : 1;
 603   guint32 reserved   :31;
 604   guint32 name;
 605   guint32 value;
 606 } ValueBlob;
 607
 608 /**
 609  * FieldBlob:
 610  * @name: The name of the field.
 611  * @readable:
 612  * @writable: How the field may be accessed.
 613  * @bits: If this field is part of a bitfield, the number of bits which it
 614  * uses, otherwise 0.
 615  * @struct_offset:
 616  * The offset of the field in the struct. The value 0xFFFF indicates
 617  * that the struct offset is unknown.
 618  * @type: The type of the field.
 619  */
 620 typedef struct {
 621   guint32        name;
 622
 623   guint8         readable :1;
 624   guint8         writable :1;
 625   guint8         reserved :6;
 626   guint8         bits;
 627
 628   guint16        struct_offset;
 629
 630   guint32        reserved2;
 631
 632   SimpleTypeBlob type;
 633 } FieldBlob;
 634
 635 /**
 636  * RegisteredTypeBlob:
 637  * @gtype_name: The name under which the type is registered with GType.
 638  * @gtype_init: The symbol name of the get_type() function which registers the type.
 639  */
 640 typedef struct {
 641   guint16 blob_type;
 642   guint16 deprecated   : 1;
 643   guint16 unregistered : 1;
 644   guint16 reserved :14;
 645   guint32 name;
 646
 647   guint32 gtype_name;
 648   guint32 gtype_init;
 649 } RegisteredTypeBlob;
 650
 651 /**
 652  * StructBlob:
 653  * @blob_type: #BLOB_TYPE_STRUCT
 654  * @deprecated: Whether this structure is deprecated
 655  * @unregistered: If this is set, the type is not registered with GType.
 656  * @alignment: The byte boundary that the struct is aligned to in memory
 657  * @is_gtype_struct: Whether this structure is the class or interface layout for a GObject
 658  * @size: The size of the struct in bytes.
 659  * @gtype_name: String name of the associated #GType
 660  * @gtype_init: String naming the symbol which gets the runtime #GType
 661  * @n_fields:
 662  * @n_functions: The lengths of the arrays.
 663  * @fields: An array of n_fields FieldBlobs.
 664  * @functions: An array of n_functions FunctionBlobs. The described functions
 665  * should be considered as methods of the struct.
 666  */
 667 typedef struct {
 668   guint16   blob_type;
 669
 670   guint16   deprecated   : 1;
 671   guint16   unregistered : 1;
 672   guint16   is_gtype_struct : 1;
 673   guint16   alignment    : 6;
 674   guint16   reserved     : 7;
 675
 676   guint32   name;
 677
 678   guint32   gtype_name;
 679   guint32   gtype_init;
 680
 681   guint32   size;
 682
 683   guint16   n_fields;
 684   guint16   n_methods;
 685
 686   guint32   reserved2;
 687   guint32   reserved3;
 688
 689 #if 0
 690   /* variable-length parts of the blob */
 691   FieldBlob    fields[];
 692   FunctionBlob methods[];
 693 #endif
 694 } StructBlob;
 695
 696 /**
 697  * UnionBlob;
 698  * @unregistered: If this is set, the type is not registered with GType.
 699  * @discriminated: Is set if the union is discriminated
 700  * @alignment: The byte boundary that the union is aligned to in memory
 701  * @size: The size of the union in bytes.
 702  * @gtype_name: String name of the associated #GType
 703  * @gtype_init: String naming the symbol which gets the runtime #GType
 704  * @n_fields: Length of the arrays
 705  * @discriminator_offset: Offset from the beginning of the union where the
 706  * discriminator of a discriminated union is located.
 707  * The value 0xFFFF indicates that the discriminator offset
 708  * is unknown.
 709  * @discriminator_type: Type of the discriminator
 710  * @discriminator_values: On discriminator value per field
 711  * @fields: Array of FieldBlobs describing the alternative branches of the union
 712  */
 713 typedef struct {
 714   guint16      blob_type;
 715   guint16      deprecated    : 1;
 716   guint16      unregistered  : 1;
 717   guint16      discriminated : 1;
 718   guint16      alignment     : 6;
 719   guint16      reserved      : 7;
 720   guint32      name;
 721
 722   guint32      gtype_name;
 723   guint32      gtype_init;
 724
 725   guint32      size;
 726
 727   guint16      n_fields;
 728   guint16      n_functions;
 729
 730   guint32      reserved2;
 731   guint32      reserved3;
 732
 733   gint32       discriminator_offset;
 734   SimpleTypeBlob discriminator_type;
 735
 736 #if 0
 737   FieldBlob    fields[];
 738   FunctionBlob functions[];
 739   ConstantBlob discriminator_values[]
 740 #endif
 741 } UnionBlob;
 742
 743 /**
 744  * EnumBlob:
 745  * @unregistered: If this is set, the type is not registered with GType.
 746  * @storage_type: The tag of the type used for the enum in the C ABI
 747  * (will be a signed or unsigned integral type)
 748  * @gtype_name: String name of the associated #GType
 749  * @gtype_init: String naming the symbol which gets the runtime #GType
 750  * @n_values: The lengths of the values arrays.
 751  * @values: Describes the enum values.
 752  */
 753 typedef struct {
 754   guint16   blob_type;
 755
 756   guint16   deprecated   : 1;
 757   guint16   unregistered : 1;
 758   guint16   storage_type : 5;
 759   guint16   reserved     : 9;
 760
 761   guint32   name;
 762
 763   guint32   gtype_name;
 764   guint32   gtype_init;
 765
 766   guint16   n_values;
 767   guint16   reserved2;
 768
 769   guint32   reserved3;
 770
 771   ValueBlob values[];
 772 } EnumBlob;
 773
 774 /**
 775  * PropertyBlob:
 776  * @name:     The name of the property.
 777  * @readable:
 778  * @writable:
 779  * @construct:
 780  * @construct_only: The ParamFlags used when registering the property.
 781  * @type: Describes the type of the property.
 782  */
 783 typedef struct {
 784   guint32        name;
 785
 786   guint32        deprecated     : 1;
 787   guint32        readable       : 1;
 788   guint32        writable       : 1;
 789   guint32        construct      : 1;
 790   guint32        construct_only : 1;
 791   guint32        reserved       :27;
 792
 793   guint32        reserved2;
 794
 795   SimpleTypeBlob type;
 796 } PropertyBlob;
 797
 798 /**
 799  * SignalBlob:
 800  * @name: The name of the signal.
 801  * @run_first:
 802  * @run_last:
 803  * @run_cleanup:
 804  * @no_recurse:
 805  * @detailed:
 806  * @action:
 807  * @no_hooks: The flags used when registering the signal.
 808  * @has_class_closure: Set if the signal has a class closure.
 809  * @true_stops_emit: Whether the signal has true-stops-emit semantics
 810  * @class_closure: The index of the class closure in the list of virtual functions
 811  * of the object or interface on which the signal is defined.
 812  * @signature: Offset of the SignatureBlob describing the parameter types and the
 813  * return value type.
 814  */
 815 typedef struct {
 816   guint16 deprecated        : 1;
 817   guint16 run_first         : 1;
 818   guint16 run_last          : 1;
 819   guint16 run_cleanup       : 1;
 820   guint16 no_recurse        : 1;
 821   guint16 detailed          : 1;
 822   guint16 action            : 1;
 823   guint16 no_hooks          : 1;
 824   guint16 has_class_closure : 1;
 825   guint16 true_stops_emit   : 1;
 826   guint16 reserved          : 6;
 827
 828   guint16 class_closure;
 829
 830   guint32 name;
 831
 832   guint32 reserved2;
 833
 834   guint32 signature;
 835 } SignalBlob;
 836
 837 /**
 838  * VFuncBlob:
 839  * @name: The name of the virtual function.
 840  * @must_chain_up: If set, every implementation of this virtual function must
 841  * chain up to the implementation of the parent class.
 842  * @must_be_implemented: If set, every derived class must override this virtual function.
 843  * @must_not_be_implemented: If set, derived class must not override this virtual function.
 844  * @class_closure: Set if this virtual function is the class closure of a signal.
 845  * @signal: The index of the signal in the list of signals of the object or
 846  * interface to which this virtual function belongs.
 847  * @struct_offset: The offset of the function pointer in the class struct. The value
 848  * 0xFFFF indicates that the struct offset is unknown.
 849  * @invoker: If a method invoker for this virtual exists, this is the offset in the
 850  * class structure of the method.  If no method is known, this value will be 0x3ff.
 851  * @signature:
 852  * Offset of the SignatureBlob describing the parameter types and the
 853  * return value type.
 854  */
 855 typedef struct {
 856   guint32 name;
 857
 858   guint16 must_chain_up           : 1;
 859   guint16 must_be_implemented     : 1;
 860   guint16 must_not_be_implemented : 1;
 861   guint16 class_closure           : 1;
 862   guint16 reserved                :12;
 863   guint16 signal;
 864
 865   guint16 struct_offset;
 866   guint16 invoker : 10; /* Number of bits matches @index in FunctionBlob */
 867   guint16 reserved2 : 6;
 868
 869   guint32 reserved3;
 870   guint32 signature;
 871 } VFuncBlob;
 872
 873 /**
 874  * ObjectBlob:
 875  * @blob_type: #BLOB_TYPE_OBJECT
 876  * @gtype_name: String name of the associated #GType
 877  * @gtype_init: String naming the symbol which gets the runtime #GType
 878  * @parent: The directory index of the parent type. This is only set for
 879  * objects. If an object does not have a parent, it is zero.
 880  * @n_interfaces:
 881  * @n_fields:
 882  * @n_properties:
 883  * @n_methods:
 884  * @n_signals:
 885  * @n_vfuncs:
 886  * @n_constants: The lengths of the arrays.Up to 16bits of padding may be inserted
 887  * between the arrays to ensure that they start on a 32bit boundary.
 888  * @interfaces: An array of indices of directory entries for the implemented
 889  * interfaces.
 890  * @fields: Describes the fields.
 891  * @methods: Describes the methods, constructors, setters and getters.
 892  * @properties: Describes the properties.
 893  * @signals: Describes the signals.
 894  * @vfuncs: Describes the virtual functions.
 895  * @constants: Describes the constants.
 896  */
 897 typedef struct {
 898   guint16   blob_type;  /* 7 */
 899   guint16   deprecated   : 1;
 900   guint16   abstract     : 1;
 901   guint16   reserved     :14;
 902   guint32   name;
 903
 904   guint32   gtype_name;
 905   guint32   gtype_init;
 906
 907   guint16   parent;
 908   guint16   gtype_struct;
 909
 910   guint16   n_interfaces;
 911   guint16   n_fields;
 912   guint16   n_properties;
 913   guint16   n_methods;
 914   guint16   n_signals;
 915   guint16   n_vfuncs;
 916   guint16   n_constants;
 917   guint16   reserved2;
 918
 919   guint32   reserved3;
 920   guint32   reserved4;
 921
 922   guint16   interfaces[];
 923
 924 #if 0
 925   /* variable-length parts of the blob */
 926   FieldBlob           fields[];
 927   PropertyBlob        properties[];
 928   FunctionBlob        methods[];
 929   SignalBlob          signals[];
 930   VFuncBlob           vfuncs[];
 931   ConstantBlob        constants[];
 932 #endif
 933 } ObjectBlob;
 934
 935 /**
 936  * InterfaceBlob:
 937  * @gtype_struct: Name of the interface "class" C structure
 938  * @n_prerequisites: Number of prerequisites
 939  * @n_properties: Number of properties
 940  * @n_methods: Number of methods
 941  * @n_signals: Number of signals
 942  * @n_vfuncs: Number of virtual functions
 943  * @n_constants: The lengths of the arrays.
 944  * Up to 16bits of padding may be inserted between the arrays to ensure that they
 945  * start on a 32bit boundary.
 946  * @prerequisites: An array of indices of directory entries for required interfaces.
 947  * @methods: Describes the methods, constructors, setters and getters.
 948  * @properties: Describes the properties.
 949  * @signals:  Describes the signals.
 950  * @vfuncs: Describes the virtual functions.
 951  * @constants: Describes the constants.
 952  */
 953 typedef struct {
 954   guint16 blob_type;
 955   guint16 deprecated   : 1;
 956   guint16 reserved     :15;
 957   guint32 name;
 958
 959   guint32 gtype_name;
 960   guint32 gtype_init;
 961   guint16 gtype_struct;
 962
 963   guint16 n_prerequisites;
 964   guint16 n_properties;
 965   guint16 n_methods;
 966   guint16 n_signals;
 967   guint16 n_vfuncs;
 968   guint16 n_constants;
 969
 970   guint32 reserved2;
 971   guint32 reserved3;
 972
 973   guint16 prerequisites[];
 974
 975 #if 0
 976   /* variable-length parts of the blob */
 977   PropertyBlob        properties[];
 978   FunctionBlob        methods[];
 979   SignalBlob          signals[];
 980   VFuncBlob           vfuncs[];
 981   ConstantBlob        constants[];
 982 #endif
 983 } InterfaceBlob;
 984
 985 /**
 986  * ConstantBlob:
 987  * @type: The type of the value. In most cases this should be a numeric
 988  * type or string.
 989  * @size: The size of the value in bytes.
 990  * @offset: The offset of the value in the typelib.
 991  */
 992 typedef struct {
 993   guint16        blob_type;
 994   guint16        deprecated   : 1;
 995   guint16        reserved     :15;
 996   guint32        name;
 997
 998   SimpleTypeBlob type;
 999
1000   guint32        size;
1001   guint32        offset;
1002
1003   guint32        reserved2;
1004 } ConstantBlob;
1005
1006 /**
1007  * AttributeBlob:
1008  * @offset: The offset of the typelib entry to which this attribute refers.
1009  * Attributes are kept sorted by offset, so that the attributes
1010  * of an entry can be found by a binary search.
1011  * @name: The name of the attribute, a string.
1012  * @value: The value of the attribute (also a string)
1013  */
1014 typedef struct {
1015   guint32 offset;
1016   guint32 name;
1017   guint32 value;
1018 } AttributeBlob;
1019
1020 struct _GTypelib {
1021   guchar *data;
1022   gsize len;
1023   gboolean owns_memory;
1024   GMappedFile *mfile;
1025   GList *modules;
1026 };
1027
1028 DirEntry *g_typelib_get_dir_entry (GTypelib *typelib,
1029                                    guint16   index);
1030
1031 void      g_typelib_check_sanity (void);
1032
1033 #define   g_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)])
1034
1035
1036 typedef enum
1037 {
1038   G_TYPELIB_ERROR_INVALID,
1039   G_TYPELIB_ERROR_INVALID_HEADER,
1040   G_TYPELIB_ERROR_INVALID_DIRECTORY,
1041   G_TYPELIB_ERROR_INVALID_ENTRY,
1042   G_TYPELIB_ERROR_INVALID_BLOB
1043 } GTypelibError;
1044
1045 #define G_TYPELIB_ERROR (g_typelib_error_quark ())
1046
1047 GQuark g_typelib_error_quark (void);
1048
1049 gboolean g_typelib_validate (GTypelib  *typelib,
1050                              GError    **error);
1051
1052
1053 G_END_DECLS
1054
1055 #endif  /* __G_TYPELIB_H__ */
1056