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