girepository/gitypelib-internal.h

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