unoidl/README

   1 Support for the new UNOIDL types.rdb format
   2
   3 ...that replaces the old types.rdb format based on modules [[store]] and
   4 [[registry]].
   5
   6 Library_unoidl contains the unoidl::Manager and unoidl::Provider implementations
   7 for both the new and the old types.rdb formats (unoidl::loadProvider tries both
   8 implementations in turn for a given file, so the old format is still supported
   9 transparently for now).
  10
  11 Executable_reg2unoidl is a helper tool to convert from the old to the new
  12 types.rdb format.  It is currently used at build-time.  idlc still generates the
  13 old format, and any new-format files (used at build-time only, or included in
  14 installation sets in URE or program/types/ or as part of bundled extensions that
  15 are created during the build and not merely included as pre-built .oxt files)
  16 are explicitly generated via reg2unoidl.  The SDK is still designed to generate
  17 old-format files exclusively (especially, any non-bundled extensions will only
  18 contain old-format files for now; that allows to modify the new format further
  19 without having to worry about compatibility with multiple versions of that
  20 format).
  21
  22 == Specification of the new UNOIDL types.rdb format ==
  23
  24 The format uses byte-oriented, platform-independent, binary files.  Larger
  25 quantities are stored LSB first, without alignment requirements.  Offsets are
  26 32 bit, effectively limiting the overall file size to 4GB, but that is not
  27 considered a limitation in practice (and avoids unnecessary bloat compared to
  28 64 bit offsets).
  29
  30 Annotations can be added for (non-module) entities and certain parts of such
  31 entities (e.g., both for an interface type definition and for a direct method of
  32 an interface type definition; the idea is that it can be added for direct parts
  33 that forma a "many-to-one" relationship; there is a tradeoff between generality
  34 of concept and size of representation, esp. for the C++ representation types in
  35 namespace unoidl) and consist of arbitrary sequences of name/value strings.
  36 Each name/value string is encoded as a single UTF-8 string containing a name (an
  37 arbitrary sequence of Unicode code points not containing U+003D EQUALS SIGN),
  38 optionally followed by U+003D EQUALS SIGN and a value (an abritrary sequence of
  39 Unicode code points).  The only annotation name currently in use is "deprecated"
  40 (without a value).
  41
  42 The following definitions are used throughout:
  43
  44 * UInt16: 2-byte value, LSB first
  45 * UInt32: 4-byte value, LSB first
  46 * UInt64: 8-byte value, LSB first
  47 * Offset: UInt32 value, counting bytes from start of file
  48 * NUL-Name: zero or more non-NUL US-ASCII bytes followed by a NUL byte
  49 * Len-String: UInt32 number of characters, with 0x80000000 bit 0, followed by
  50    that many US-ASCII (for UNOIDL related names) resp. UTF-8 (for annotations)
  51    bytes
  52 * Idx-String: either an Offset (with 0x80000000 bit 1) of a Len-String, or a
  53    Len-String
  54 * Annotations: UInt32 number N of annotations followed by N * Idx-String
  55 * Entry: Offset of NUL-Name followed by Offset of payload
  56 * Map: zero or more Entries
  57
  58 The file starts with an 8 byte header, followed by information about the root
  59 map (reg2unoidl generates files in a single depth-first pass, so the root map
  60 itself is at the end of the file):
  61
  62 * 7 byte magic header "UNOIDL\xFF"
  63 * version byte 0
  64 * Offset of root Map
  65 * UInt32 number of entries of root Map
  66 ...
  67
  68 Files generated by reg2unoidl follow that by a
  69
  70   "\0** Created by LibreOffice " LIBO_VERSION_DOTTED " reg2unoidl **\0"
  71
  72 banner (cf. config_host/config_version.h.in), as a debugging aid.
  73
  74 Layout of per-entry payload in the root or a module Map:
  75
  76 * kind byte:
  77
  78 ** 0: module
  79 *** followed by:
  80 **** UInt32 number N1 of entries of Map
  81 **** N1 * Entry
  82
  83 ** otherwise:
  84 *** 0x80 bit: 1 if published
  85 *** 0x40 bit: 1 if annotated
  86 *** 0x20 bit: flag (may only be 1 for certain kinds, see below)
  87 *** remaining bits:
  88
  89 **** 1: enum type
  90 ***** followed by:
  91 ****** UInt32 number N1 of members
  92 ****** N1 * tuple of:
  93 ******* Idx-String
  94 ******* UInt32
  95 ******* if annotated: Annotations
  96
  97 **** 2: plain struct type (with base if flag is 1)
  98 ***** followed by:
  99 ****** if "with base": Idx-String
 100 ****** UInt32 number N1 of direct members
 101 ****** N1 * tuple of:
 102 ******* Idx-String name
 103 ******* Idx-String type
 104 ******* if annotated: Annotations
 105
 106 **** 3: polymorphic struct type template
 107 ***** followed by:
 108 ****** UInt32 number N1 of type parameters
 109 ****** N1 * Idx-String
 110 ****** UInt32 number N2 of members
 111 ****** N2 * tuple of:
 112 ******* kind byte: 0x01 bit is 1 if parameterized type
 113 ******* Idx-String name
 114 ******* Idx-String type
 115 ******* if annotated: Annotations
 116
 117 **** 4: exception type (with base if flag is 1)
 118 ***** followed by:
 119 ****** if "with base": Idx-String
 120 ****** UInt32 number N1 of direct members
 121 ****** N1 * tuple of:
 122 ******* Idx-String name
 123 ******* Idx-String type
 124 ******* if annotated: Annotations
 125
 126 **** 5: interface type
 127 ***** followed by:
 128 ****** UInt32 number N1 of direct mandatory bases
 129 ****** N1 * tuple of:
 130 ******* Idx-String
 131 ******* if annotated: Annotations
 132 ****** UInt32 number N2 of direct optional bases
 133 ****** N2 * tuple of:
 134 ******* Idx-String
 135 ******* if annotated: Annotations
 136 ****** UInt32 number N3 of direct attributes
 137 ****** N3 * tuple of:
 138 ******* kind byte:
 139 ******** 0x02 bit: 1 if read-only
 140 ******** 0x01 bit: 1 if bound
 141 ******* Idx-String name
 142 ******* Idx-String type
 143 ******* UInt32 number N4 of get exceptions
 144 ******* N4 * Idx-String
 145 ******* UInt32 number N5 of set exceptions
 146 ******* N5 * Idx-String
 147 ******* if annotated: Annotations
 148 ****** UInt32 number N6 of direct methods
 149 ****** N6 * tuple of:
 150 ******* Idx-String name
 151 ******* Idx-String return type
 152 ******* UInt32 number N7 of parameters
 153 ******* N7 * tuple of:
 154 ******** direction byte: 0 for in, 1 for out, 2 for in-out
 155 ******** Idx-String name
 156 ******** Idx-String type
 157 ******* UInt32 number N8 of exceptions
 158 ******* N8 * Idx-String
 159 ******* if annotated: Annotations
 160
 161 **** 6: typedef
 162 ***** followed by:
 163 ****** Idx-String
 164
 165 **** 7: constant group
 166 ***** followed by:
 167 ****** UInt32 number N1 of entries of Map
 168 ****** N1 * Entry
 169
 170 **** 8: single-interface--based service (with default constructor if flag is 1)
 171 ***** followed by:
 172 ****** Idx-String
 173 ****** if not "with default constructor":
 174 ******* UInt32 number N1 of constructors
 175 ******* N1 * tuple of:
 176 ******** Idx-String
 177 ******** UInt32 number N2 of parameters
 178 ******** N2 * tuple of
 179 ********* kind byte: 0x04 bit is 1 if rest parameter
 180 ********* Idx-String name
 181 ********* Idx-String type
 182 ******** UInt32 number N3 of exceptions
 183 ******** N3 * Idx-String
 184 ******** if annotated: Annotations
 185
 186 **** 9: accumulation-based service
 187 ***** followed by:
 188 ****** UInt32 number N1 of direct mandatory base services
 189 ****** N1 * tuple of:
 190 ******* Idx-String
 191 ******* if annotated: Annotations
 192 ****** UInt32 number N2 of direct optional base services
 193 ****** N2 * tuple of:
 194 ******* Idx-String
 195 ******* if annotated: Annotations
 196 ****** UInt32 number N3 of direct mandatory base interfaces
 197 ****** N3 * tuple of:
 198 ******* Idx-String
 199 ******* if annotated: Annotations
 200 ****** UInt32 number N4 of direct optional base interfaces
 201 ****** N4 * tuple of:
 202 ******* Idx-String
 203 ******* if annotated: Annotations
 204 ****** UInt32 number N5 of direct properties
 205 ****** N5 * tuple of:
 206 ******* UInt16 kind:
 207 ******** 0x0100 bit: 1 if optional
 208 ******** 0x0080 bit: 1 if removable
 209 ******** 0x0040 bit: 1 if maybedefault
 210 ******** 0x0020 bit: 1 if maybeambiguous
 211 ******** 0x0010 bit: 1 if readonly
 212 ******** 0x0008 bit: 1 if transient
 213 ******** 0x0004 bit: 1 if constrained
 214 ******** 0x0002 bit: 1 if bound
 215 ******** 0x0001 bit: 1 if maybevoid
 216 ******* Idx-String name
 217 ******* Idx-String type
 218 ******* if annotated: Annotations
 219
 220 **** 10: interface-based singleton
 221 ***** followed by:
 222 ****** Idx-String
 223
 224 **** 11: service-based singleton
 225 ***** followed by:
 226 ****** Idx-String
 227
 228 *** if annotated, followed by: Annotations
 229
 230 Layout of per-entry payload in a constant group Map:
 231
 232 * kind byte:
 233 ** 0x80 bit: 1 if annotated
 234 ** remaining bits:
 235
 236 *** 0: BOOLEAN
 237 **** followed by value byte, 0 represents false, 1 represents true
 238
 239 *** 1: BYTE
 240 **** followed by value byte, representing values with two's complement
 241
 242 *** 2: SHORT
 243 **** followed by UInt16 value, representing values with two's complement
 244
 245 *** 3: UNSIGNED SHORT
 246 **** followed by UInt16 value
 247
 248 *** 4: LONG
 249 **** followed by UInt32 value, representing values with two's complement
 250
 251 *** 5: UNSIGNED LONG
 252 **** followed by UInt32 value
 253
 254 *** 6: HYPER
 255 **** followed by UInt64 value, representing values with two's complement
 256
 257 *** 7: UNSIGNED HYPER
 258 **** followed by UInt64 value
 259
 260 *** 8: FLOAT
 261 **** followed by 4-byte value, representing values in ISO 60599 binary32 format,
 262       LSB first
 263
 264 *** 9: DOUBLE
 265 **** followed by 8-byte value, representing values in ISO 60599 binary64 format,
 266       LSB first
 267
 268 * if annotated, followed by: Annotations