XPCOM Type Library
File Format
Version 1.1, Revision 1
Scott Furman <fur@netscape.com>
John Bandhauer <jband@netscape.com>
Latest version:
http://mozilla.org/scriptable/typelib_file.html
Document History
Known Issues
Introduction
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. Thus, this document specifies a format quite different from the Microsoft format.
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.
Goals
- Represent all type information that is required for XPConnect, xpcom/proxy, and Blackwood
- Map an IID to an interface description quickly
- Allow for efficiency when interfaces are sparsely used, i.e. without requiring the entire typelib to be parsed or retained in memory
- Use a compact file format, so as to accommodate hundreds of interfaces and thousands of methods
- Allow for extensibility, so as to accommodate future additions to XPIDL
Non-goals
- Ability to reconstruct XPIDL source from type library
- Human-readable format
- File-level compatibility with MS typelibs
Notation
The syntax used in this document to specify the layout of file data appears similar to C structs. Unlike C structs, however, data members are not subject to alignment restrictions. Another difference from C structs is the use of pointer notation to represent 32-bit file offsets. For example,- uint16 *ByteOffsetTo16BitValue
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.
All records are 8-bit aligned. In some records reserved fields of less than 8 bits are specified to make that alignment explicit.
Filename Suffix
The standard suffix for XPCOM type libraries is .xpt.File Header
Every XPCOM typelib file begins with a header:
TypeLibHeader {
char magic[16];
uint8 major_version;
uint8 minor_version;
uint16 num_interfaces;
uint32 file_length;
InterfaceDirectoryEntry* interface_directory;
uint8* data_pool;
Annotation annotations[];
}
magic
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.)
major_version, minor_version
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.
num_interfaces
This indicates the count of InterfaceDirectoryEntry records that are at the offset indicated by the interface_directory field.
interface_directory
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.)
file_length
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.
data_pool
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.
annotations
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
A contiguous array of fixed-size InterfaceDirectoryEntry records begins at the byte offset identified by the interface_directory field in the file header. The array is used to quickly locate an interface description given its IID. No interface should appear more than once in the array.
InterfaceDirectoryEntry {
uint128 iid;
Identifier* name;
Identifier* namespace;
InterfaceDescriptor* interface_descriptor;
}
An interface is said to be unresolved if its methods and constants have not yet been determined. In order for an InterfaceDirectoryEntry to appear in the interface_directory at all the name (e.g. "nsISupports") must be present. The iid might be present. Only if the name and iid are present may the interface_descriptor be present. Only when all three are present is the interface said to be resolved. It is always permitted that namespace be missing. In any case, any missing fields must 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 iid, name, and namespace. Such linking might result in the merging of multiple typelibs - each containing some unresolved interfaces - into one typelib containing only resolved interfaces. It also might mean the activity of loading multiple typelibs at runtime and doing that resolution in memory.
iid
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.)
name
The human-readable name of this interface, e.g. "nsISupports", stored using the Identifier record format.
namespace
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.
interface_descriptor
This is a 1-based byte offset from the beginning of the data pool to the corresponding InterfaceDescriptor object.
InterfaceDescriptor
An InterfaceDescriptor is a variable-size record used to describe a single XPCOM interface, including all of its methods, scoped constants and types:
InterfaceDescriptor {
uint16 parent_interface_index;
uint16 num_methods;
MethodDescriptor method_descriptors[num_methods];
uint16 num_constants;
ConstDescriptor const_descriptors[num_constants];
boolean is_scriptable;
boolean is_function;
uint6 reserved;
}
parent_interface_index
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.
num_methods
The number of methods in the method_descriptors array.
method_descriptors
This is an inline array of MethodDescriptor objects. The length of the array is determined by the num_methods field.
num_constants
The number of scoped interface constants in the const_descriptors array.
const_descriptors
This is an inline array of ConstDescriptor objects. The length of the array is determined by the num_constants field.
is_scriptable
This field indicates that the interface has been marked to be visible to scripting languages. Individual method can be marked as hidden from scripting languages by setting the is_hidden flag on the individual methods.
is_function
This field indicates that the interface has been marked such that all of its methods will be considered to be functions. This allows us to support certain legacy interfaces for the JavaScript DOM that need to sometimes be able to treat functions as if they were objects with named methods. This flag is very rarely used and can generally be ignored.
reserved
ConstDescriptor
A ConstDescriptor is a variable-size record that records the name and value of a scoped interface constant. All ConstDescriptor records have this form:
ConstDescriptor {
Identifier* name;
TypeDescriptor type;
<type> value;
}
name
The human-readable name of this constant, stored in the Identifier record format.
type
The type of the method parameter. Types are restricted to the following subset of TypeDescriptors: int16, uint16, int32, uint32
value
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.
MethodDescriptor
A MethodDescriptor is a variable-size record used to describe a single interface method:
MethodDescriptor {
boolean is_getter;
boolean is_setter;
boolean is_not_xpcom;
boolean is_constructor;
boolean is_hidden;
uint3 reserved;
Identifier* name;
uint8 num_args;
ParamDescriptor params[num_args];
ParamDescriptor result;
}
is_getter
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.
is_setter
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.Note: If an interface has both a MethodDescriptor marked is_getter and a MethodDescriptor marked is_setter for the same named attribute then the two MethodDescriptors must be adjacent and the is_getter descriptor must preceed the is_setter descriptor.
is_not_xpcom
If true, this field indicates that the method does not follow xpcom calling conventions and can not be called by most proxying code or xpconnect. This is most useful for methods that do not return a nsresult; e.g the AddRef and Release methods of nsISupports. The method remains in the typelib to fill a slot in the interface's vtable.
is_constructor
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.
is_hidden
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.
name
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.
num_args
The number of arguments that the method consumes. Also, the number of elements in the params array.
params
This is an inline array of ParamDescriptor objects. The length of the array is determined by the num_args field.
result
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
A ParamDescriptor is a variable-size record used to describe either a single argument to a method or a method's result:
ParamDescriptor {
boolean in;
boolean out;
boolean retval;
boolean shared;
boolean dipper;
uint3 reserved;
TypeDescriptor type;
}
in
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.
out
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.
retval
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. However, a method marked as is_not_xpcom might have any return type and is assumed to not be describable by this typelib information. Note that when retval is set on a method parameter, the out flag must also be true.
shared
If shared is true, it indicates that this parameter does not follow the normal xpcom rules for transfer of ownership of pointer type object. It only makes sense to use this with params that are marked out and which are also pointer type things; e.g. strings. This flag indicates that the interface is providing a pointer to its own copy of the data rather that making a copy for the caller. This explicitly breaks the xpcom rules. This should be used as little as possible. Still, this flag does allow for this optimization where absolutely necessary.
dipper
If dipper is true, it indicates that this parameter uses a special means of being received as an out parameter. The idea is that in order to get an out value an object reference (the dipper) is passed by the caller as an in parameter of the method call and the value to be received is set in a call to that dipper object. The caller can then examine the dipper object to get the received value.The dipper flag should always be used with the in flag and never with the out flag. In practice, we use this parameter passing convention with the astring type.
reserved
A 3-bit field reserved for future use.
type
The type of the method parameter.
TypeDescriptor
A TypeDescriptor is a variable-size record used to identify the type of a method argument or return value. There are many categories of XPCOM types that need to be represented in the typelib:- scalar types, e.g. uint16 or boolean
- pointer to a scalar type, e.g. float*
- void (only allowed for method return type)
- interface pointer
- iid_is - that is, an interface pointer with type determined at runtime, or a pointer to such an interface pointer
- pointer to an nsIID structure (to act as the parameter to an iid_is)
- pointer to an an array with size or size and length information.
To efficiently describe all the type categories listed above, there are several different variants of TypeDescriptor records:
union TypeDescriptor {
SimpleTypeDescriptor;
InterfaceTypeDescriptor;
InterfaceIsTypeDescriptor;
ArrayTypeDescriptor;
}
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;
}
is_pointer
This field is true only when representing C pointer/reference types.
is_unique_pointer
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.
is_reference
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.
tag
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 20 ArrayTypeDescriptor 21 StringWithSizeTypeDescriptor 22 WideStringWithSizeTypeDescriptor 23..31 reserved
SimpleTypeDescriptor
The one-byte SimpleTypeDescriptor is a kind of TypeDescriptor used to represent scalar types, pointers to scalar types, the void type and, as a special case, the nsIID* type:SimpleTypeDescriptor {
boolean is_pointer;
boolean is_unique_pointer;
boolean is_reference;
uint5 tag;
}
is_pointer, tag
-
The is_pointer field is true only when representing C pointer/reference
types. The following table indicates the types that can be represented
by combining different values for these two fields:
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(8-bit value)1 |
|
|
|
(8-bit character)2 |
|
|
|
(16-bit character)3 |
|
|
|
|
|
|
|
|
|
|
|
|
|
false
|
16
|
reserved
|
|
false
|
17
|
reserved
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(pointer to a single 8-bit value)1 |
|
|
|
(pointer to a single 8-bit character)2 |
|
|
|
(pointer to a single 16-bit character)3 |
|
|
|
|
|
|
|
|
|
|
|
|
|
true
|
16
|
char*
(pointer to a NUL-terminated array)2 |
|
true
|
17
|
wchar_t*
(pointer to a NUL-terminated array)3 |
1Type boolean values are always passed as 8-bit values. They can contain 0 (zero) to represent false or 1 (one) to represent true. Other values are undefined.
2Type char values are always passed as 8-bit values. They can hold 7-bit ASCII characters only. Other character encodings (e.g. UTF-8) are not supported by char.
3We use wchar_t here to specifically mean a 16-bit data type. This is true even though wchar_t as a native type is implemented on some platforms using something other than a 16-bit data type. Each wchar_t character holds one Unicode character.
4The type astring* represents a pointer the C++ abstract
nsAString class. See the nsAString
documentation
and
declarations.
Note that this type uses the tag previously assigned to the (never implmented)
support for BSTR.
Note that this type is sometimes called domstring.
InterfaceTypeDescriptor
An InterfaceTypeDescriptor is used to represent a pointer to an interface type, e.g. nsISupports*:
InterfaceTypeDescriptor {
boolean is_pointer; // 1
boolean is_unique_pointer;
boolean is_reference;
uint5 tag; // 18
uint16 interface_index;
}
is_pointer
Must always be 1 (true).
tag
The tag field must have the decimal value 18.
interface_index
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
An InterfaceIsTypeDescriptor describes an interface pointer type. It is similar to an InterfaceTypeDescriptor except that the type of the interface pointer is specified at runtime by the value of another argument, rather than being specified by the typelib.
InterfaceIsTypeDescriptor {
boolean is_pointer; // 1
boolean is_unique_pointer;
boolean is_reference;
uint5 tag; //19
uint8 arg_num;
}
is_pointer
Must always be 1 (true).
tag
The tag field must have the decimal value 19.
arg_num
The zero-based index of the method argument that describes the type of the interface pointer. The specified method argument must have type nsIID*.
ArrayTypeDescriptor
An ArrayTypeDescriptor describes an array. Arrays are assumed to be allocated just like other pointer type objects. An array may contain a homeogenous series of any type that can appear in a parameter list. Array parameters are always associated with some other parameter whose value indicates the size of the array; i.e. how many elements the array contains.
ArrayTypeDescriptor {
boolean is_pointer; // 1
boolean is_unique_pointer;
boolean is_reference;
uint5 tag; //20
uint8 size_is_arg_num;
uint8 length_is_arg_num;
TypeDescriptor type_descriptor;
}
is_pointer
Must always be 1 (true).
tag
The tag field must have the decimal value 20.
size_is_arg_num
The zero-based index of the method argument that describes the count of elements in the array. The specified method argument must have type uint32.
length_is_arg_num
The zero-based index of the method argument that describes the count of elements in the array which are 'significant'. This allows for reusing a buffer which might get passed back and forth. While the size_is parameter allows for tracking the size of the buffer, the length_is parameter allows for tracking how many elements in the buffer are currently 'valid'. This may specify the same parameter that is used for size_is_arg_num. The specified method argument must have type uint32.
type_descriptor
This describes the type of the elements in the array. Any type that can be used as a parameter is allowed except the types ArrayTypeDescriptor, StringWithSizeTypeDescriptor, and WideStringWithSizeTypeDescriptor. This means that for this version of the spec multidimensional arrays are not supported. However, some future version may relax this restriction and allow for multidimensional arrays.
StringWithSizeTypeDescriptor
A StringWithSizeTypeDescriptor describes a string that has extra information which indicates which parameters will at runtime have information about the string's size and length. This is very much like an ArrayTypeDescriptor with a type of char except that some language mappings may choose to map this type with language specific string semantics rather than array-of-char sematics.
StringWithSizeTypeDescriptor {
boolean is_pointer; // 1
boolean is_unique_pointer;
boolean is_reference;
uint5 tag; //21
uint8 size_is_arg_num;
uint8 length_is_arg_num;
}
is_pointer
Must always be 1 (true).
tag
The tag field must have the decimal value 21.
size_is_arg_num
The zero-based index of the method argument that describes the count of chars in the string. The specified method argument must have type uint32. The runtime value of the referenced parameter is the count of actual characters and does not include any extra space that might be required for zero termintaion.
length_is_arg_num
The zero-based index of the method argument that describes the count of chars in the string which are 'significant'. This allows for reusing a buffer which might get passed back and forth. While the size_is parameter allows for tracking the size of the buffer, the length_is parameter allows for tracking how many elements in the buffer are currently 'valid'. This may specify the same parameter that is used for size_is_arg_num. The specified method argument must have type uint32. The runtime value of the referenced parameter is the count of actual characters and does not include any extra space that might be required for zero termintaion.
WideStringWithSizeTypeDescriptor
A WideStringWithSizeTypeDescriptor is just like a StringWithSizeTypeDescriptor except that the elements are wchar_t rather than char. It describes a wide string that has extra information which indicates which parameters will at runtime have information about the string's size and length. This is very much like an ArrayTypeDescriptor with a type of wchar_t except that some language mappings may choose to map this type with language specific wide string semantics rather than array-of-wchar_t sematics.
WideStringWithSizeTypeDescriptor {
boolean is_pointer; // 1
boolean is_unique_pointer;
boolean is_reference;
uint5 tag; //22
uint8 size_is_arg_num;
uint8 length_is_arg_num;
}
is_pointer
Must always be 1 (true).
tag
The tag field must have the decimal value 22.
size_is_arg_num
The zero-based index of the method argument that describes the count of char in the string. The specified method argument must have type uint32. The runtime value of the referenced parameter is the count of actual characters and does not include any extra space that might be required for zero termintaion.
length_is_arg_num
The zero-based index of the method argument that describes the count of chars in the string which are 'significant'. This allows for reusing a buffer which might get passed back and forth. While the size_is parameter allows for tracking the size of the buffer, the length_is parameter allows for tracking how many elements in the buffer are currently 'valid'. This may specify the same parameter that is used for size_is_arg_num. The specified method argument must have type uint32. The runtime value of the referenced parameter is the count of actual characters and does not include any extra space that might be required for zero termintaion.
Identifier
Identifier records are used to represent variable-length, human-readable strings:Identifier {
char bytes[];
}
bytes
Unicode string encoded in UTF-8 format, NUL-terminated.
String
String records are used to represent variable-length, human-readable strings, possibly with embedded NUL's:
String {
uint16 length;
char bytes[length];
}
length
The length of the string, in characters (not bytes).
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.
Annotation
Annotation records are variable-size records used to store secondary information about the typelib, e.g. such as the name of the tool that generated the typelib file, the date it was generated, etc. The information is stored with very loose format requirements so as to allow virtually any private data to be stored in the typelib.
union Annotation {
EmptyAnnotation
PrivateAnnotation
}
EmptyAnnotation {
boolean is_last;
uint7 tag; // 0
}
PrivateAnnotation {
boolean is_last;
uint7 tag; // 1
String creator;
String private_data;
}
is_last
When true, no more Annotation records follow the current record. If false, at least one Annotation record appears immediately after the current record.
tag
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.
creator
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.
private_data
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.
Document History
Version 1.1, Draft 1 (07 May 2001) [jband]
- Added is_function.
- Added astring.
- Added is_dipper.
Version 1.0, Draft 10 (27 April 2000) [jband] -- http://mozilla.org/scriptable/typelib_file_v1_d10.html
- This draft reflects typelibs as shipped with Netscape6 and through Mozilla 0.9
- Fixed Blackwood link.
- Added tighter specification of boolean
- Added tighter specification of char
- Added tighter specification of wchar_t
Version 1.0, Draft 9 (19 September 99) [jband] -- http://mozilla.org/scriptable/typelib_file_v1_d9.html
- Combined ArrayWithLengthTypeDescriptor into ArrayTypeDescriptor.
- Added StringWithSizeTypeDescriptor and WideStringWithSizeTypeDescriptor.
- Added reserved field to InterfaceDescriptor to pad record to 8-bit boundary.
- Added note that records are 8-bit aligned.
- Specified ordering of getter and setter MethodDecriptors.
- Removed VarArgs issue from 'Known Issues' section.
Version 1.0, Draft 8 (10 September 99) [jband] -- http://mozilla.org/scriptable/typelib_file_v1_d8.html
- Added ArrayTypeDescriptor and ArrayWithLengthTypeDescriptor.
- Removed OpaqueTypeDescriptor, NamedTypeDescriptor, EnumTypeDescriptor, and TypeDef. These were not implemented. They may well reappear in a subsequent version of the spec.
- Re-added void* as a supported type.
- Added shared as a flag for ParamDescriptor.
- Added is_not_xpcom as a flag for MethodDescriptor.
- Changed definition of 'unresolved' to include the case where both name and iid are known.
- Added flags to InterfaceDescriptor.
- Narrowed the list of supported const types to match the implementation.
- Note the fact that typelibs are used by technologies other than xpconnect.
- Fixed various typos.
Version 1.0, Draft 7 (3/11/98) -- http://mozilla.org/scriptable/typelib_file_v1_d7.html
- 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.
Version 1.0, Draft 6(3/9/98) -- http://mozilla.org/scriptable/typelib_file_v1_d6.html
- 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.
Version 1.0, Draft 5(1/24/98) -- http://mozilla.org/scriptable/typelib_file_v1_d5.html
- References to a given InterfaceDirectoryEntry's were changed from a 32-bit file offset to a 16-bit table offset.
Version 1.0, Draft 4 (1/14/98) -- http://mozilla.org/scriptable/typelib_file_v1_d4.html
- 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.
Version 1.0, Draft 3 (1/5/98) -- http://mozilla.org/scriptable/typelib_file_v1_d3.html
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.) Version 1.0, Draft 2 (12/16/98) -- http://mozilla.org/scriptable/typelib_file_v1_d2.html
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) Version 1.0, Draft 1 (12/13/98) -- http://mozilla.org/scriptable/typelib_file_v1_d1.html
Known Issues
- There is no support yet in the typelib for pointers to unions or structs. Also no support for array slices.
- The common string type(s) that will be passed around in XPCOM methods still seems to be up in the air. (nsString, nsIString, STL strings, ?) Until that's resolved, the TypeDescriptor just uses "string" to represent that type. Depending on what's decided, we may end up adding more than one string type.