XPCOM type libraries, or "typelibs", are binary interface description files generated by the XPIDL compiler. Type libraries enumerate the methods of one or more interfaces, including detailed type information for each method parameter. Typelibs might be more aptly named "interface libraries", but Microsoft has already established a precedent with their naming scheme and we'll stick with it to avoid developer confusion.
Ideally, XPCOM typelibs would be binary-compatible with those generated by Microsoft's MIDL compiler, but the MS typelib format is proprietary.
Note that the typelib is not merely a tokenized form of the IDL. Rather, it's intended to accurately represent binary XPCOM interfaces, with annotations derived from the IDL.
Record fields with type boolean occupy one bit, not one byte. A value of 1 represents true and a value of 0 represents false.
All integer fields with multibyte precision are stored in big-endian order, e.g. for a uint16 field, the high-order byte is stored in the file followed by the low-order byte.
TypeLibHeader {
char magic[16];
uint8 major_version;
uint8 minor_version;
uint16 num_interfaces;
uint32 file_length;
InterfaceDirectoryEntry* interface_directory;
uint8* data_pool;
Annotation annotations[];
}
The first 16 bytes of the file always contain the following values:(hex) 58 50 43 4f 4d 0a 54 79 70 65 4c 69 62 0d 0a 1a (C notation) X P C O M \n T y p e L i b \r \n \032This signature both identifies the file as an XPCOM typelib file and provides for immediate detection of common file-transfer problems, i.e. treatment of a binary file as if it was a text file. The CR-LF sequence catches file transformations that alter newline sequences. The control-Z character stops file display under MS-DOS. The sixth character, a linefeed, checks for the inverse of the CR-LF translation problem. (A nod to the PNG folks for the inspiration behind using these special characters in the header.)
These are the major and minor version numbers of the typelib file format. For this specification major_version is 0x01 and minor_version is 0x00. Typelib files that share the same major version but have different minor versions are compatible. Changes to the major version represent typelib file formats that are not backward-compatible with parsers designed only to read earlier major versions. If a typelib file is encountered with a major version for which support is not available, the rest of the file should not be parsed.
This indicates the count of InterfaceDirectoryEntry records that are at the offset indicated by the interface_directory field.
This field specifies a zero-relative byte offset from the beginning of the file. It identifies the start of an array of InterfaceDirectoryEntry records. If num_interfaces is zero, then this field should also be zero. The value of this field should be a multiple of 4, i.e. the interface directory must be aligned on a 4-byte boundary. (This is to guarantee aligned access if the typelib file is mmap'ed into memory.)
Total length of the typelib file, in bytes. This value can be compared to the length of the file reported by the OS so as to detect file truncation.
The data pool is a heap-like storage area that is the container for most kinds of typelib data including, but not limited to, InterfaceDescriptor, MethodDescriptor, ParamDescriptor, and TypeDescriptor records. Note that, unlike most file offsets in a typelib, the value of data_pool is zero-relative to the beginning of the file. Pointers to records within a typelib are 1-based (not zero-based) relative to the beginning of the data pool.
A variable-length array of variable-size records used to store secondary information, e.g. such as the name of the tool that generated the typelib file, the date it was generated, etc.
InterfaceDirectoryEntry {
uint128 iid;
Identifier* name;
Identifier* namespace;
InterfaceDescriptor* interface_descriptor;
}
An interface is said to be unresolved if its name is known, e.g. "nsISupports", but its IID and methods have not yet been determined. In that case, both the iid and the interface_descriptor field will be set to zero. If an interface is unresolved, then its typelib must be "linked" with another typelib to resolve the interface, namely a typelib that contains a resolved InterfaceDirectoryEntry that matches the specified name and namespace.
The iid field contains a 128-bit value representing the interface ID. The iid is created from an IID by concatenating the individual bytes of an IID in a particular order. For example, this IID:{00112233-4455-6677-8899-aabbccddeeff}is converted to the 128-bit value0x00112233445566778899aabbccddeeffNote that the byte storage order corresponds to the layout of the nsIID C-struct on a big-endian architecture.All InterfaceDirectoryEntry objects must appear sorted in increasing order of iid, so as to facilitate a binary search of the array. (This means that unresolved interfaces always appear at the beginning of the array.)
The human-readable name of this interface, e.g. "nsISupports", stored using the Identifier record format.
The human-readable identifier for the namespace of this interface, stored using the Identifier record format. This is the declared name of an interface's module in the XPIDL. The use of namespace permits identically-named interfaces that do not conflict. (Reference to an interface from one namespace to an interface in another namespace would probably be written as namespace.interfaceName.) If namespace is zero, the interface is in the default namespace.
This is a 1-based byte offset from the beginning of the data pool to the corresponding InterfaceDescriptor object.
InterfaceDescriptor {
uint16 parent_interface_index;
uint16 num_methods;
MethodDescriptor method_descriptors[num_methods];
uint16 num_constants;
ConstDescriptor const_descriptors[num_constants];
}
An interface's methods are specified by composing the methods of an interface from which it is derived with additional methods it defines. The method_descriptors array does not list any methods that the interface inherits from its parent. The parent_interface_index field contains an index into the interface_directory, thus identifying the InterfaceDirectoryEntry of the parent interface. The first entry in the interface_directory has index 1. This field has a value of zero for nsISupports, the root of the interface inheritance hierarchy.
The number of methods in the method_descriptors array.
This is an inline array of MethodDescriptor objects. The length of the array is determined by the num_methods field.
The number of scoped interface constants in the const_descriptors array.
This is an inline array of ConstDescriptor objects. The length of the array is determined by the num_constants field.
ConstDescriptor {
Identifier* name;
TypeDescriptor type;
<type> value;
}
The human-readable name of this constant, stored in the Identifier record format.
The type of the method parameter. Types are restricted to the following subset of TypeDescriptors: int8, uint8, int16, uint16, int32, uint32, int64, uint64, wchar_t, char, string
The type (and thus the size) of the value record is determined by the contents of the associated TypeDescriptor record. For instance, if type corresponds to int16, then value is a two-byte record consisting of a 16-bit signed integer. For a ConstDescriptor type of string, the value record is of type String*, i.e. an offset within the data pool to a String record containing the constant string.
MethodDescriptor {
boolean is_getter;
boolean is_setter;
boolean reserved;
boolean is_constructor;
boolean is_hidden;
uint3 reserved;
Identifier* name;
uint8 num_args;
ParamDescriptor params[num_args];
ParamDescriptor result;
}
This field is used to allow interface methods to act as property getters for object-oriented languages such as JavaScript. The is_getter flag would typically be set as a result of defining an XPIDL attribute. For example, if there was an XPIDL attribute named "Banjo", you could access the "Banjo" property on an interface from JavaScript like so: 'myInterface.Banjo'. Any prefix added by the XPIDL compiler to an attribute's identifier in a generated .h file, such as "Is" or "Get" should not appear in the method's name.
This field is used to allow interface methods to act as property setters for object-oriented languages such as JavaScript. The is_setter flag would typically set as a result of defining an XPIDL attribute. For example, if there was an XPIDL attribute named "Banjo", you could assign to the "Banjo" property on an interface using JavaScript like so: 'myInterface.Banjo = 3'. Any prefix added by the XPIDL compiler to an attribute's identifier in a generated .h file, such as "Set" should not appear in the method's name.
This field indicates the default constructor for this interface, which may be useful for interfaces that act like factories. For example, with an instance of an XPCOM interface named 'Foo', in JavaScript one might write 'new Foo(arg1, arg2)', thus calling this interface to be called; The argument signature of an XPCOM constructor is:NS_IRESULT ([arg,]*, out nsISomeInterface result)That is, it's a function that takes zero or more arguments and creates a new interface returned through the result output parameter.
Only one method in an interface can have this flag set.
If true, this field indicates that the method is not to be exposed to scripters, although it remains in the typelib to fill a slot in the interface's vtable.
The human-readable name of this method, e.g. "getWindow", stored in the Identifier record format. Any prefix added by the XPIDL compiler to an attribute's identifier in a generated .h file, such as "Is" or "Get" should not appear in the method's name.
The number of arguments that the method consumes. Also, the number of elements in the params array.
This is an inline array of ParamDescriptor objects. The length of the array is determined by the num_args field.
This is a single, inline ParamDescriptor object that identifies the actual return type of an XPCOM method. The result, however, does not always refer to the effective method return value when the invocation is from a scripting language, i.e. the return value as seen from a script-writer's perspective. In particular, it is possible to designate any out method argument as the method return value for scripting purposes. See the retval flag.
ParamDescriptor {
boolean in;
boolean out;
boolean retval;
uint5 reserved;
TypeDescriptor type;
}
If in is true, it indicates that the parameter is to be passed from caller to callee. This flag is always false for a method's result.
If out is true, it indicates that the parameter is to be passed from callee to caller. It is possible for a parameter to have both out and in bits set. For the actual method result, out is always false. Out parameters imply an additional level of indirection than specified by the parameter's TypeDescriptor, e.g. if the parameter's type specifies uint32, the actual type of the argument passed at runtime is a uint32*. Hence out parameters are always pointers.
If retval is true, it indicates that this parameter is to be considered the return value of the method for purposes of invocation from a scripting language. If the XPCOM method's result parameter does not have its retval flag set, then the method's return value must either be void or an nsresult (a bitfield encoded as a uint32) that indicates the success or failure of the method invocation. Note that when retval is set on a method parameter, the out flag must also be true.
A 5-bit field reserved for future use.
The type of the method parameter.
To efficiently describe all the type categories listed above, there are several different variants of TypeDescriptor records:
union TypeDescriptor {
SimpleTypeDescriptor;
InterfaceTypeDescriptor;
InterfaceIsTypeDescriptor;
OpaqueTypeDescriptor;
NamedTypeDescriptor;
EnumTypeDescriptor;
}
The first byte of all these TypeDescriptor variants has the identical layout:
TypeDescriptorPrefix {
boolean is_pointer;
boolean is_unique_pointer;
boolean is_reference;
uint5 tag;
}
This field is true only when representing C pointer/reference types.
This field cannot have a value of true unless is_pointer is also true. The unique_pointer field indicates if the parameter value can be aliased to another parameter value. If unique_pointer is true, it must not be possible to reach the memory pointed at by this argument value from any other argument to the method. This flag is used to promote efficiency when marshalling arguments for a remote method invocation.
This field cannot have a value of true unless is_pointer is also true. This field is true if the parameter is a reference, which is to say, it's a pointer that can't have a value of NULL.
The tag field indicates which of the variant TypeDescriptor records is being used, and hence the way any remaining fields should be parsed.
Value in tag field TypeDescriptor variant to use 0..17 SimpleTypeDescriptor 18 InterfaceTypeDescriptor 19 InterfaceIsTypeDescriptor 23..31 reserved
SimpleTypeDescriptor {
boolean is_pointer;
boolean is_unique_pointer;
boolean is_reference;
uint5 tag;
}
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
false
|
16
|
reserved
|
|
false
|
17
|
reserved
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(pointer to a single 16-bit character) |
|
|
|
reserved
|
|
|
|
|
|
|
|
|
|
true
|
16
|
char* (pointer to a NUL-terminated array)
|
|
true
|
17
|
wchar_t* (pointer to a NUL-terminated array)
|
InterfaceTypeDescriptor {
boolean is_pointer; // 1
boolean is_unique_pointer;
boolean is_reference;
uint5 tag;
uint16 interface_index;
}
Must always be 1 (true).
The tag field must have the decimal value 18.
This field specifies a index into the interface_directory, thus identifying an InterfaceDirectoryEntry. The first entry in the interface_directory has index 1. Note that the value is specified in terms of table entries, not bytes.
InterfaceIsTypeDescriptor {
boolean is_pointer;
boolean is_unique_pointer;
boolean is_reference;
uint5 tag;
uint8 arg_num;
}
Must always be 1 (true).
The tag field must have the decimal value 19.
The zero-based index of the method argument that describes the type of the interface pointer. The specified method argument must have type nsIID*.
OpaqueTypeDescriptor {
boolean is_pointer; // 1
uint2 reserved;
uint5 tag; // 20
Identifier* type_name;
}
Must have the value 1 (true).
Must have the value 20.
This is a string containing the name of an opaque type pointer, e.g. "PRThread*". Any whitespace in the name of a type should be removed so as to facilitate matching of type_name strings. It is recommended, but not required, that all OpaqueTypeDescriptor's that refer to the same type should point to the same Identifier record.
NamedTypeDescriptor {
boolean is_pointer;
boolean is_unique_pointer;
boolean is_reference;
uint5 tag; // 21
TypeDef* type;
}
Must have the value 21.
A 1-based offset within the data_pool that points to a TypeDef record that contains the name and detailed description of the type. All references to the same user-defined type within a typelib must point to the same TypeDef record.
An EnumTypeDescriptor is used to define an enumeration, i.e. a type that in C++ would be expressed using an enum declaration. The related EnumValue record specifies a mapping between a single human-readable name and a single value in the enumeration.
EnumValue {
Identifier name;
<type> value;
}
EnumTypeDescriptor {
boolean is_pointer;
boolean is_unique_pointer;
boolean is_reference;
uint5 tag; // 22
TypeDescriptor type; // int32
uint16 num_values;
EnumValue enum_values[num_values];
}
Must have the value 22.
Specifies the type of all values in the enumeration. For this version of the typelib, the only supported type is int32.
Specifies the length of the inline enum_values array that immediately follows.
An array of length num_values, each element of which contains a mapping between a human-readable name and a constant value.
The symbolic, human-readable name for the constant value that immediately follows in the EnumValue record.
The type (and thus the size) of the value record is determined by the contents of the associated TypeDescriptor record in the enclosing EnumTypeDescriptor. For instance, if type corresponds to int32, then value is a four-byte record consisting of a 32-bit signed, big-endian integer. In this version of the typelib specification, however, the only allowed type for enumeration values is int32.
A TypeDef record associates a human-readable name with a module-wide XPCOM type. TypeDef records and TypeDescriptor records are mutually recursive so as to allow descriptions of complex type. That is TypeDefs can both point to and be pointed at by TypeDescriptor records.
struct TypeDef {
Identifier name;
Identifier* namespace;
TypeDescriptor* type;
}
The human-readable name of this type, e.g. "MyEnum", stored using the Identifier record format. Note that name is an inline Identifier string, but namespace is a data pool offset to an Identifier string. (This is to facilitate sharing of the namespace string). There should only be a single TypeDef record of a given name and namespace in a typelib.
A data pool byte offset that points at the human-readable identifier for the namespace of this type, stored using the Identifier record format. This is the declared name of an interface's module in the XPIDL. The use of namespace permits identically-named types that do not conflict. If namespace is zero, the type is in the default namespace.
A data pool byte offset to a TypeDescriptor record containing the description of the named type. Note that type aliases may be formed by storing a pointer to a NamedTypeDescriptor record in the type_description slot.
Identifier {
char bytes[];
}
Unicode string encoded in UTF-8 format, NUL-terminated.
String {
uint16 length;
char bytes[length];
}
The length of the string, in characters (not bytes).
Unicode string encoded in UTF-8 format, with no null-termination. The length of the bytes array, measured in Unicode characters (not bytes), is reported by the length field.
union Annotation {
EmptyAnnotation
PrivateAnnotation
}
EmptyAnnotation {
boolean is_last;
uint7 tag; // 0
}
PrivateAnnotation {
boolean is_last;
uint7 tag; // 1
String creator;
String private_data;
}
When true, no more Annotation records follow the current record. If false, at least one Annotation record appears immediately after the current record.
The tag field discriminates among the variant record types for Annotation's. If the tag is 0, this record is an EmptyAnnotation. EmptyAnnotation's are ignored - they're only used to indicate an array of Annotation's that's completely empty. If the tag is 1, the record is a PrivateAnnotation.
A string that identifies the application/tool/code that created the annotation, e.g. "XPIDL Compiler, Version 1.2". There are no rules about the contents of the creator string other than that it be human-readable.
An opaque data array that is put into the typelib by the application/tool/code that created the typelib. There are no restrictions on the format of the private_data.
Draft 7 (3/11/98)
- InterfaceTypeDescriptors now always represent a pointer to an interface and never a pointer to a pointer to an interface type. The is_pointer flag on an InterfaceTypeDescriptor is always set.
- Eliminated is_varargs flag from MethodDescriptor. Methods with variable numbers of arguments cannot be expressed directly using XPIDL.
- Eliminated void* type from SimpleTypeDescriptor. Use of a void* as an XPCOM method parameter is discouraged, but if it must be done, it should be encoded using an OpaqueTypeDescriptor record.
Draft 6 (3/9/98)
- Added TypeDef records which contains module-wide XPCOM type definitions, i.e. equivalent to C++ typedefs.
- Added support for native (opaque) types, named types (references to typedefs), and enumeration types in method parameters. See OpaqueTypeDescriptor, NamedTypeDescriptor, and EnumTypeDescriptor.
- Shaver and jband pointer out a screwup in ParamDescriptors: Out parameters should imply an additional level of indirection than specified by the parameter's TypeDescriptor, e.g. if the parameter's type specifies uint32, the actual type of the argument passed at runtime is a uint32*.
- The 16-bit interface_directory table offsets were made one-based rather than zero-based, so that it's possible to specify a null interface as the parent of nsISupports.
- parent_interface should be a 16-bit interface_directory table offset, not a 32-bit file offset, in keeping with the changes made in draft 5.
Draft 5(1/24/98)
- References to a given InterfaceDirectoryEntry's were changed from a 32-bit file offset to a 16-bit table offset.
Draft 4 (1/14/98)
- Changed to big-endian layout due to arm-twisting. (Note resulting change to IID layout.)
- Changed entries in SimpleTypeDescriptor table to distinguish between a pointer to a single character and a pointer to a null-terminated array of characters, both for 8-bit and 16-bit characters. This also resulted in changes to the tag member of the TypeDescriptor field for InterfaceTypeDescriptor and InterfaceIsTypeDescriptor.
- Changed string type in SimpleTypeDescriptor to BSTR, since it's starting to look like this is what we may standardize on for XPCOM strings.
- Added interface namespace field to the InterfaceDirectoryEntry, aka CORBA modules, aka MIDL libraries. This is to allow for identically-named interfaces that don't clash.
- Added 'is_hidden' bit to MethodDescriptor for methods that are not exposed to script authors.
- Moved Document History and Known Issues to bottom of spec.
Draft 3 (1/5/98)
Added 'retval' flag and massaged description of 'in' and 'out' flags in the ParamDescriptor record. Fixed errors in descriptions of 'params' and 'result' members of the MethodDescriptor and in the description of 'method_descriptors' and 'const_descriptors' members of the InterfaceDescriptor record. (In all cases, these members were incorrectly described as byte offsets to other records even though the data layout notation indicated that they were stored inline.) Draft 2 (12/16/98)
Added "Document History" and "Known Issues" sections. Tweaked introduction. Changed pointers to InterfaceDescriptor records to instead point to InterfaceDirectoryEntry's so as to allow late-binding of interfaces using only the interface name. The interface name was moved from the InterfaceDescriptor to the InterfaceDirectoryEntry for the same reason. Changed the description of the parent_interface field of InterfaceDescriptor so that its use is not optional. Updated is_getter and is_setter text to be less confusing about whether or not method name prefixes are stored for getters and setters. (They're not.) Added is_varargs and is_constructor flags to MethodDescriptor. Added support for scoped interface constants. Nearly all uses of the String record type were changed to Identifier. Identifiers are NUL-terminated UTF-8 string records. That means you can't store embedded NUL characters in an identifier (method or interface name), but they're one byte shorter because the string length isn't stored as part of the record. Added support for private data to be attached to typelib files (Annotation records)