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   } flags;
 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  * If the interface is an enum of flags type, is_pointer is 0, otherwise it is 1.
 496  */
 497 typedef struct {
 498   guint8  pointer  :1;
 499   guint8  reserved :2;
 500   guint8  tag      :5;
 501   guint8  reserved2;
 502   guint16 interface;
 503 } InterfaceTypeBlob;
 504
 505 /**
 506  * ArrayTypeBlob:
 507  * @zero_terminated: Indicates that the array must be terminated by a suitable #NULL
 508  * value.
 509  * @has_length: Indicates that length points to a parameter specifying the length
 510  * of the array. If both has_length and zero_terminated are set, the
 511  * convention is to pass -1 for the length if the array is
 512  * zero-terminated.
 513  * @length: The index of the parameter which is used to pass the length of the
 514  * array. The parameter must be an integer type and have the same
 515  * direction as this one.
 516  * @type: The type of the array elements.
 517  *
 518  * Arrays are passed by reference, thus is_pointer is always 1.
 519  */
 520 typedef struct {
 521   guint16 pointer         :1;
 522   guint16 reserved        :2;
 523   guint16 tag             :5;
 524
 525   guint16 zero_terminated :1;
 526   guint16 has_length      :1;
 527   guint16 has_size        :1;
 528   guint16 reserved2       :5;
 529
 530   union {
 531     guint16 length;
 532     guint16 size;
 533   } dimensions;
 534
 535   SimpleTypeBlob type;
 536 } ArrayTypeBlob;
 537
 538 /**
 539  * ParamTypeBlob:
 540  * @n_types: The number of parameter types to follow.
 541  * @type: Describes the type of the list elements.
 542  *
 543  */
 544 typedef struct {
 545   guint8         pointer  :1;
 546   guint8         reserved :2;
 547   guint8         tag      :5;
 548
 549   guint8         reserved2;
 550   guint16        n_types;
 551
 552   SimpleTypeBlob type[];
 553 } ParamTypeBlob;
 554
 555 /**
 556  * ErrorTypeBlob:
 557  * @n_domains: The number of domains to follow
 558  * @domains:  Indices of the directory entries for the error domains
 559  */
 560 typedef struct {
 561   guint8  pointer  :1;
 562   guint8  reserved :2;
 563   guint8  tag      :5;
 564
 565   guint8  reserved2;
 566   guint16 n_domains;
 567
 568   guint16 domains[];
 569 }  ErrorTypeBlob;
 570
 571 /**
 572  * ErrorDomainBlob:
 573  * @get_quark: The symbol name of the function which must be called to obtain the
 574  * GQuark for the error domain.
 575  * @error_codes: Index of the InterfaceBlob describing the enumeration which lists
 576  * the possible error codes.
 577  */
 578 typedef struct {
 579   guint16 blob_type;  /* 10 */
 580
 581   guint16 deprecated : 1;
 582   guint16 reserved   :15;
 583
 584   guint32 name;
 585
 586   guint32 get_quark;
 587   guint16 error_codes;
 588   guint16 reserved2;
 589 } ErrorDomainBlob;
 590
 591 /**
 592  * ValueBlob:
 593  * @deprecated: Whether this value is deprecated
 594  * @value: The numerical value
 595  * @name: Name of blob
 596  *
 597  * Values commonly occur in enums and flags.
 598  */
 599 typedef struct {
 600   guint32 deprecated : 1;
 601   guint32 reserved   :31;
 602   guint32 name;
 603   guint32 value;
 604 } ValueBlob;
 605
 606 /**
 607  * FieldBlob:
 608  * @name: The name of the field.
 609  * @readable:
 610  * @writable: How the field may be accessed.
 611  * @bits: If this field is part of a bitfield, the number of bits which it
 612  * uses, otherwise 0.
 613  * @struct_offset:
 614  * The offset of the field in the struct. The value 0xFFFF indicates
 615  * that the struct offset is unknown.
 616  * @type: The type of the field.
 617  */
 618 typedef struct {
 619   guint32        name;
 620
 621   guint8         readable :1;
 622   guint8         writable :1;
 623   guint8         reserved :6;
 624   guint8         bits;
 625
 626   guint16        struct_offset;
 627
 628   guint32        reserved2;
 629
 630   SimpleTypeBlob type;
 631 } FieldBlob;
 632
 633 /**
 634  * RegisteredTypeBlob:
 635  * @gtype_name: The name under which the type is registered with GType.
 636  * @gtype_init: The symbol name of the get_type() function which registers the type.
 637  */
 638 typedef struct {
 639   guint16 blob_type;
 640   guint16 deprecated   : 1;
 641   guint16 unregistered : 1;
 642   guint16 reserved :14;
 643   guint32 name;
 644
 645   guint32 gtype_name;
 646   guint32 gtype_init;
 647 } RegisteredTypeBlob;
 648
 649 /**
 650  * StructBlob:
 651  * @blob_type: #BLOB_TYPE_STRUCT
 652  * @deprecated: Whether this structure is deprecated
 653  * @unregistered: If this is set, the type is not registered with GType.
 654  * @alignment: The byte boundary that the struct is aligned to in memory
 655  * @is_gtype_struct: Whether this structure is the class or interface layout for a GObject
 656  * @size: The size of the struct in bytes.
 657  * @gtype_name: String name of the associated #GType
 658  * @gtype_init: String naming the symbol which gets the runtime #GType
 659  * @n_fields:
 660  * @n_functions: The lengths of the arrays.
 661  * @fields: An array of n_fields FieldBlobs.
 662  * @functions: An array of n_functions FunctionBlobs. The described functions
 663  * should be considered as methods of the struct.
 664  */
 665 typedef struct {
 666   guint16   blob_type;
 667
 668   guint16   deprecated   : 1;
 669   guint16   unregistered : 1;
 670   guint16   is_gtype_struct : 1;
 671   guint16   alignment    : 6;
 672   guint16   reserved     : 7;
 673
 674   guint32   name;
 675
 676   guint32   gtype_name;
 677   guint32   gtype_init;
 678
 679   guint32   size;
 680
 681   guint16   n_fields;
 682   guint16   n_methods;
 683
 684   guint32   reserved2;
 685   guint32   reserved3;
 686
 687 #if 0
 688   /* variable-length parts of the blob */
 689   FieldBlob    fields[];
 690   FunctionBlob methods[];
 691 #endif
 692 } StructBlob;
 693
 694 /**
 695  * UnionBlob;
 696  * @unregistered: If this is set, the type is not registered with GType.
 697  * @discriminated: Is set if the union is discriminated
 698  * @alignment: The byte boundary that the union is aligned to in memory
 699  * @size: The size of the union in bytes.
 700  * @gtype_name: String name of the associated #GType
 701  * @gtype_init: String naming the symbol which gets the runtime #GType
 702  * @n_fields: Length of the arrays
 703  * @discriminator_offset: Offset from the beginning of the union where the
 704  * discriminator of a discriminated union is located.
 705  * The value 0xFFFF indicates that the discriminator offset
 706  * is unknown.
 707  * @discriminator_type: Type of the discriminator
 708  * @discriminator_values: On discriminator value per field
 709  * @fields: Array of FieldBlobs describing the alternative branches of the union
 710  */
 711 typedef struct {
 712   guint16      blob_type;
 713   guint16      deprecated    : 1;
 714   guint16      unregistered  : 1;
 715   guint16      discriminated : 1;
 716   guint16      alignment     : 6;
 717   guint16      reserved      : 7;
 718   guint32      name;
 719
 720   guint32      gtype_name;
 721   guint32      gtype_init;
 722
 723   guint32      size;
 724
 725   guint16      n_fields;
 726   guint16      n_functions;
 727
 728   guint32      reserved2;
 729   guint32      reserved3;
 730
 731   gint32       discriminator_offset;
 732   SimpleTypeBlob discriminator_type;
 733
 734 #if 0
 735   FieldBlob    fields[];
 736   FunctionBlob functions[];
 737   ConstantBlob discriminator_values[]
 738 #endif
 739 } UnionBlob;
 740
 741 /**
 742  * EnumBlob:
 743  * @unregistered: If this is set, the type is not registered with GType.
 744  * @storage_type: The tag of the type used for the enum in the C ABI
 745  * (will be a signed or unsigned integral type)
 746  * @gtype_name: String name of the associated #GType
 747  * @gtype_init: String naming the symbol which gets the runtime #GType
 748  * @n_values: The lengths of the values arrays.
 749  * @values: Describes the enum values.
 750  */
 751 typedef struct {
 752   guint16   blob_type;
 753
 754   guint16   deprecated   : 1;
 755   guint16   unregistered : 1;
 756   guint16   storage_type : 5;
 757   guint16   reserved     : 9;
 758
 759   guint32   name;
 760
 761   guint32   gtype_name;
 762   guint32   gtype_init;
 763
 764   guint16   n_values;
 765   guint16   reserved2;
 766
 767   guint32   reserved3;
 768
 769   ValueBlob values[];
 770 } EnumBlob;
 771
 772 /**
 773  * PropertyBlob:
 774  * @name:     The name of the property.
 775  * @readable:
 776  * @writable:
 777  * @construct:
 778  * @construct_only: The ParamFlags used when registering the property.
 779  * @type: Describes the type of the property.
 780  */
 781 typedef struct {
 782   guint32        name;
 783
 784   guint32        deprecated     : 1;
 785   guint32        readable       : 1;
 786   guint32        writable       : 1;
 787   guint32        construct      : 1;
 788   guint32        construct_only : 1;
 789   guint32        reserved       :27;
 790
 791   guint32        reserved2;
 792
 793   SimpleTypeBlob type;
 794 } PropertyBlob;
 795
 796 /**
 797  * SignalBlob:
 798  * @name: The name of the signal.
 799  * @run_first:
 800  * @run_last:
 801  * @run_cleanup:
 802  * @no_recurse:
 803  * @detailed:
 804  * @action:
 805  * @no_hooks: The flags used when registering the signal.
 806  * @has_class_closure: Set if the signal has a class closure.
 807  * @true_stops_emit: Whether the signal has true-stops-emit semantics
 808  * @class_closure: The index of the class closure in the list of virtual functions
 809  * of the object or interface on which the signal is defined.
 810  * @signature: Offset of the SignatureBlob describing the parameter types and the
 811  * return value type.
 812  */
 813 typedef struct {
 814   guint16 deprecated        : 1;
 815   guint16 run_first         : 1;
 816   guint16 run_last          : 1;
 817   guint16 run_cleanup       : 1;
 818   guint16 no_recurse        : 1;
 819   guint16 detailed          : 1;
 820   guint16 action            : 1;
 821   guint16 no_hooks          : 1;
 822   guint16 has_class_closure : 1;
 823   guint16 true_stops_emit   : 1;
 824   guint16 reserved          : 6;
 825
 826   guint16 class_closure;
 827
 828   guint32 name;
 829
 830   guint32 reserved2;
 831
 832   guint32 signature;
 833 } SignalBlob;
 834
 835 /**
 836  * VFuncBlob:
 837  * @name: The name of the virtual function.
 838  * @must_chain_up: If set, every implementation of this virtual function must
 839  * chain up to the implementation of the parent class.
 840  * @must_be_implemented: If set, every derived class must override this virtual function.
 841  * @must_not_be_implemented: If set, derived class must not override this virtual function.
 842  * @class_closure: Set if this virtual function is the class closure of a signal.
 843  * @signal: The index of the signal in the list of signals of the object or
 844  * interface to which this virtual function belongs.
 845  * @struct_offset: The offset of the function pointer in the class struct. The value
 846  * 0xFFFF indicates that the struct offset is unknown.
 847  * @invoker: If a method invoker for this virtual exists, this is the offset in the
 848  * class structure of the method.  If no method is known, this value will be 0x3ff.
 849  * @signature:
 850  * Offset of the SignatureBlob describing the parameter types and the
 851  * return value type.
 852  */
 853 typedef struct {
 854   guint32 name;
 855
 856   guint16 must_chain_up           : 1;
 857   guint16 must_be_implemented     : 1;
 858   guint16 must_not_be_implemented : 1;
 859   guint16 class_closure           : 1;
 860   guint16 reserved                :12;
 861   guint16 signal;
 862
 863   guint16 struct_offset;
 864   guint16 invoker : 10; /* Number of bits matches @index in FunctionBlob */
 865   guint16 reserved2 : 6;
 866
 867   guint32 reserved3;
 868   guint32 signature;
 869 } VFuncBlob;
 870
 871 /**
 872  * ObjectBlob:
 873  * @blob_type: #BLOB_TYPE_OBJECT
 874  * @gtype_name: String name of the associated #GType
 875  * @gtype_init: String naming the symbol which gets the runtime #GType
 876  * @parent: The directory index of the parent type. This is only set for
 877  * objects. If an object does not have a parent, it is zero.
 878  * @n_interfaces:
 879  * @n_fields:
 880  * @n_properties:
 881  * @n_methods:
 882  * @n_signals:
 883  * @n_vfuncs:
 884  * @n_constants: The lengths of the arrays.Up to 16bits of padding may be inserted
 885  * between the arrays to ensure that they start on a 32bit boundary.
 886  * @interfaces: An array of indices of directory entries for the implemented
 887  * interfaces.
 888  * @fields: Describes the fields.
 889  * @methods: Describes the methods, constructors, setters and getters.
 890  * @properties: Describes the properties.
 891  * @signals: Describes the signals.
 892  * @vfuncs: Describes the virtual functions.
 893  * @constants: Describes the constants.
 894  */
 895 typedef struct {
 896   guint16   blob_type;  /* 7 */
 897   guint16   deprecated   : 1;
 898   guint16   abstract     : 1;
 899   guint16   reserved     :14;
 900   guint32   name;
 901
 902   guint32   gtype_name;
 903   guint32   gtype_init;
 904
 905   guint16   parent;
 906   guint16   gtype_struct;
 907
 908   guint16   n_interfaces;
 909   guint16   n_fields;
 910   guint16   n_properties;
 911   guint16   n_methods;
 912   guint16   n_signals;
 913   guint16   n_vfuncs;
 914   guint16   n_constants;
 915   guint16   reserved2;
 916
 917   guint32   reserved3;
 918   guint32   reserved4;
 919
 920   guint16   interfaces[];
 921
 922 #if 0
 923   /* variable-length parts of the blob */
 924   FieldBlob           fields[];
 925   PropertyBlob        properties[];
 926   FunctionBlob        methods[];
 927   SignalBlob          signals[];
 928   VFuncBlob           vfuncs[];
 929   ConstantBlob        constants[];
 930 #endif
 931 } ObjectBlob;
 932
 933 /**
 934  * InterfaceBlob:
 935  * @gtype_struct: Name of the interface "class" C structure
 936  * @n_prerequisites: Number of prerequisites
 937  * @n_properties: Number of properties
 938  * @n_methods: Number of methods
 939  * @n_signals: Number of signals
 940  * @n_vfuncs: Number of virtual functions
 941  * @n_constants: The lengths of the arrays.
 942  * Up to 16bits of padding may be inserted between the arrays to ensure that they
 943  * start on a 32bit boundary.
 944  * @prerequisites: An array of indices of directory entries for required interfaces.
 945  * @methods: Describes the methods, constructors, setters and getters.
 946  * @properties: Describes the properties.
 947  * @signals:  Describes the signals.
 948  * @vfuncs: Describes the virtual functions.
 949  * @constants: Describes the constants.
 950  */
 951 typedef struct {
 952   guint16 blob_type;
 953   guint16 deprecated   : 1;
 954   guint16 reserved     :15;
 955   guint32 name;
 956
 957   guint32 gtype_name;
 958   guint32 gtype_init;
 959   guint16 gtype_struct;
 960
 961   guint16 n_prerequisites;
 962   guint16 n_properties;
 963   guint16 n_methods;
 964   guint16 n_signals;
 965   guint16 n_vfuncs;
 966   guint16 n_constants;
 967
 968   guint32 reserved2;
 969   guint32 reserved3;
 970
 971   guint16 prerequisites[];
 972
 973 #if 0
 974   /* variable-length parts of the blob */
 975   PropertyBlob        properties[];
 976   FunctionBlob        methods[];
 977   SignalBlob          signals[];
 978   VFuncBlob           vfuncs[];
 979   ConstantBlob        constants[];
 980 #endif
 981 } InterfaceBlob;
 982
 983 /**
 984  * ConstantBlob:
 985  * @type: The type of the value. In most cases this should be a numeric
 986  * type or string.
 987  * @size: The size of the value in bytes.
 988  * @offset: The offset of the value in the typelib.
 989  */
 990 typedef struct {
 991   guint16        blob_type;
 992   guint16        deprecated   : 1;
 993   guint16        reserved     :15;
 994   guint32        name;
 995
 996   SimpleTypeBlob type;
 997
 998   guint32        size;
 999   guint32        offset;
1000
1001   guint32        reserved2;
1002 } ConstantBlob;
1003
1004 /**
1005  * AttributeBlob:
1006  * @offset: The offset of the typelib entry to which this attribute refers.
1007  * Attributes are kept sorted by offset, so that the attributes
1008  * of an entry can be found by a binary search.
1009  * @name: The name of the attribute, a string.
1010  * @value: The value of the attribute (also a string)
1011  */
1012 typedef struct {
1013   guint32 offset;
1014   guint32 name;
1015   guint32 value;
1016 } AttributeBlob;
1017
1018 struct _GTypelib {
1019   guchar *data;
1020   gsize len;
1021   gboolean owns_memory;
1022   GMappedFile *mfile;
1023   GList *modules;
1024   gboolean open_attempted;
1025 };
1026
1027 DirEntry *g_typelib_get_dir_entry (GTypelib *typelib,
1028                                    guint16   index);
1029
1030 void      g_typelib_check_sanity (void);
1031
1032 #define   g_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)])
1033
1034
1035 typedef enum
1036 {
1037   G_TYPELIB_ERROR_INVALID,
1038   G_TYPELIB_ERROR_INVALID_HEADER,
1039   G_TYPELIB_ERROR_INVALID_DIRECTORY,
1040   G_TYPELIB_ERROR_INVALID_ENTRY,
1041   G_TYPELIB_ERROR_INVALID_BLOB
1042 } GTypelibError;
1043
1044 #define G_TYPELIB_ERROR (g_typelib_error_quark ())
1045
1046 GQuark g_typelib_error_quark (void);
1047
1048 gboolean g_typelib_validate (GTypelib  *typelib,
1049                              GError    **error);
1050
1051
1052 G_END_DECLS
1053
1054 #endif  /* __G_TYPELIB_H__ */
1055