Debian Codegraph @

podofo/3rdparty/adobe/afdko/include/ctlshare.h

raw
1 /* Copyright 2014 Adobe Systems Incorporated (http://www.adobe.com/). All Rights Reserved.
2 This software is licensed as OpenSource, under the Apache License, Version 2.0.
3 This license is available at: http://opensource.org/licenses/Apache-2.0. */
4
5 #ifndef CTLSHARE_H
6 #define CTLSHARE_H
7
8 #ifdef __EPOC32__
9 /* The Symbian platform does not define NULL in stddef.h (an is therefore
10 non-standard) so we use an alternative definition that is available
11 stdlib.h. */
12 #include <stdlib.h>
13 #else
14 #include <stddef.h> /* For size_t and NULL */
15 #endif
16 #include <stdint.h>
17
18 #include <libxml/tree.h>
19 #include <libxml/parser.h>
20
21 /* CoreType Library Shared Definitions
22 ===================================
23 This library supplies definitions that are shared between members of the
24 CoreType library suite. */
25
26 /* ---------------------------- Version Numbers ---------------------------- */
27
28 /* A version number is a long value that encodes minor, branch, and major
29 numbers into bytes of increasing significance, starting with the least
30 significant byte, respectively. The most significant byte is unused and
31 should be set to 0. */
32
33 #define CTL_MAKE_VERSION(major, branch, minor) \
34 ((long)major << 16 | branch << 8 | minor)
35
36 /* CTL_MAKE_VERSION combines the "major", "branch", and "minor" parameters into
37 a single value of type long. */
38
39 char *CTL_SPLIT_VERSION(char *version_buf, int version);
40
41 /* CTL_SPLIT_VERSION splits the "version" parameter into its comma-separated
42 major, branch, and minor component values that may be passed to printf,
43 and prints this to version_buf */
44
45 /* --------------------------------- CDECL --------------------------------- */
46
47 #ifndef CTL_CDECL
48 #define CTL_CDECL
49 #endif /* CTL_CDECL */
50
51 /* C code in the Microsoft environment may be sped up if compiled using Pascal
52 calling conventions (/Gr compiler option). However, standard library
53 callback functions such as those used by qsort(), bsearch(), main(), and
54 varargs functions must still use the C calling conventions. In these cases
55 the affected functions can be indicated to the compiler by using the
56 non-standard __cdecl keyword before function name.
57
58 The CoreType libraries have been written so that the affected functions
59 include the CTL_CDECL macro before their function names. Therefore, clients
60 wishing to compile on the Microsoft platform using Pascal calling
61 conventions can simply define CTL_CDECL as __cdecl to obtain the correct
62 behavior when the code is compiled with the /Gr compiler option. This may be
63 simply achieved with the /D CTL_CDECL=__cdecl compiler option. */
64
65 /* ---------------------------- Memory Callbacks --------------------------- */
66
67 typedef struct ctlMemoryCallbacks_ ctlMemoryCallbacks;
68 struct ctlMemoryCallbacks_ {
69 void *ctx;
70 void *(*manage)(ctlMemoryCallbacks *cb, void *old, size_t size);
71 };
72
73 /* The ctlMemoryCallbacks structure specifies a single memory management
74 callback function and a context.
75
76 [optional] The "ctx" field can be used to specify a client context. Set to
77 NULL if not used.
78
79 [required] The manage() callback manages memory in a similar manner to the
80 realloc() ISO C Standard library function. Its operation is defined (in
81 standard library function terms) as follows:
82
83 old size action return
84 --- ---- ------ ------
85 ==NULL ==0 none NULL
86 ==NULL !=0 malloc allocation, or NULL if allocation failed
87 !=NULL ==0 free NULL
88 !=NULL !=0 realloc reallocation, or NULL if reallocation failed
89
90 The "cb" parameter is the address of the ctlMemoryCallbacks structure
91 containing the function being called. This parameter can be used by the
92 client to access the ctx field.
93
94 This function must observe the alignment requirements imposed by the C
95 Standard for memory allocators.
96
97 If the client has access to a conformant ISO C realloc() function a possible
98 implementation is as follows:
99
100 void *manage(ctlMemoryCallbacks *cb, void *old, size_t size)
101 {
102 return (old == NULL && size == 0)? NULL: realloc(old, size);
103 }
104
105 The condition is required because the ISO C Standard doesn't define a single
106 behavior for that case and the CoreType libraries rely on NULL being
107 returned.
108
109 If a client is unsure about compliance with the ISO C standard a safer
110 implementation is as follows:
111
112 void *manage(ctlMemoryCallbacks *cb, void *old, size_t size)
113 {
114 if (size > 0)
115 {
116 if (old == NULL)
117 return malloc(size);
118 else
119 return realloc(old, size);
120 }
121 else
122 {
123 if (old == NULL)
124 return NULL;
125 else
126 {
127 free(old);
128 return NULL;
129 }
130 }
131 }
132 */
133
134 /* --------------------------- Stream Callbacks ---------------------------- */
135
136 typedef struct ctlStreamCallbacks_ ctlStreamCallbacks;
137 struct ctlStreamCallbacks_ {
138 void *direct_ctx;
139 void *indirect_ctx;
140 char *clientFileName; // set by clients which need to open private files.
141 void *(*open)(ctlStreamCallbacks *cb, int id, size_t size);
142 int (*seek)(ctlStreamCallbacks *cb, void *stream, long offset);
143 long (*tell)(ctlStreamCallbacks *cb, void *stream);
144 size_t (*read)(ctlStreamCallbacks *cb, void *stream, char **ptr);
145 size_t (*xml_read)(ctlStreamCallbacks *cb, void *stream, xmlDocPtr *doc);
146 size_t (*write)(ctlStreamCallbacks *cb,
147 void *stream, size_t count, char *ptr);
148 int (*status)(ctlStreamCallbacks *cb, void *stream);
149 int (*close)(ctlStreamCallbacks *cb, void *stream);
150 };
151
152 /* The ctlStreamCallbacks structure specifies a standard set of functions that
153 perform I/O on abstract data streams. They are modeled on the Standard C
154 library functions of the same name but do not need to be implemented using
155 files. A client, for example, could choose to keep the data in memory
156 buffers.
157
158 A stream is identified by a unique "id" parameter that is provided by the
159 open() call. The client turns this into a client-specific pointer that is
160 returned by open(). This value is associated by the library with that stream
161 and is passed as the "stream" parameter in subsequent calls. When a library
162 has finished using a stream it calls the close() function.
163
164 Each library API file will specify the purpose and id for each stream it
165 uses. The direction of data movement is encoded in the stream id's
166 enumeration constant: _SRC_ meaning that the library is reading on that
167 stream, _DST_ meaning that the library is writing on that stream, and _TMP_
168 meaning a write/read temporary stream.
169
170 [optional] The "direct_ctx" field can be used to specify a client context.
171 Set to NULL if not used.
172
173 [not used by clients] The "indirect_ctx" field is be used internally by
174 libraries that act as a bridge between the client and another library that
175 is hidden from the client. Clients must set this field to NULL.
176
177 [required] open() is called in order for the client to initialize for a
178 stream. The stream being opened is identified by the "id" parameter using an
179 enumeration constants defined in the API. The client performs the necessary
180 initialization for the stream and returns a pointer to a client object that
181 represents the stream, e.g. a file pointer, or NULL if the stream couldn't
182 be opened. The "size" parameter when set to a non-0 value specifies the
183 total size (in bytes) of output data that will be written to this stream
184 (when known). It permits a memory-based client to allocate the exact amount
185 of space for the embedding font in memory, for example.
186
187 [required] seek() is called in order to seek to an absolute byte position in
188 a stream specified by the "offset" parameter. It returns 0 on success and
189 non-0 otherwise.
190
191 [required] tell() returns the absolute byte position of a stream. It returns
192 -1 if the operation couldn't be performed on the stream.
193
194 [required] read() is called in order to read bytes from a stream. It returns
195 the number of bytes read and a pointer to a buffer, via the "ptr" parameter,
196 that contains those bytes. The client should return a count of 0 in the
197 event of an end-of-stream condition or if the stream cannot be read. A
198 library distinguishes these conditions by calling status(). The client must
199 arrange that successive calls to read() return consecutive blocks of data
200 from the source stream. (Note, this scheme allows a client to choose a
201 buffer size for input that is optimized for the client's implementation.
202 However, very small buffer sizes are likely to be inefficient and should be
203 avoided.)
204
205 [required] write() is called in order to write data to a stream. The "ptr"
206 parameter points to a buffer of data to be written and the "count" parameter
207 specifies the number of bytes available. The function returns the count
208 parameter on success and 0 otherwise.
209
210 [required] close() is called to close a previously opened stream. The
211 function returns 0 on success and -1 on failure.
212
213 [required] status() returns the status of a stream. The returns values are
214 specified by the enumerations: */
215
216 enum /* Stream status */
217 {
218 CTL_STREAM_OK, /* Functioning normally */
219 CTL_STREAM_ERROR, /* Error occurred */
220 CTL_STREAM_END /* At end-of-stream */
221 };
222
223 /* status() is normally called after the read() callback returned 0 in order to
224 distinguish end-of-stream from a read error.
225
226 [required] close() is called to tear down the client's implementation of a
227 stream. Typically, a client would release any resources associated with the
228 stream. The function returns 0 on success and -1 otherwise. */
229
230 enum {
231 T1R_SRC_STREAM_ID, /* t1read */
232 T1R_TMP_STREAM_ID,
233 T1R_DBG_STREAM_ID,
234
235 TTR_SRC_STREAM_ID, /* ttread */
236 TTR_DBG_STREAM_ID,
237
238 CFR_SRC_STREAM_ID, /* cffread */
239 CFR_DBG_STREAM_ID,
240
241 SFR_SRC_STREAM_ID, /* sfntread (default) */
242
243 T1W_DST_STREAM_ID, /* t1write */
244 T1W_TMP_STREAM_ID,
245 T1W_DBG_STREAM_ID,
246
247 CFW_DST_STREAM_ID, /* cffwrite */
248 CFW_TMP_STREAM_ID,
249 CFW_DBG_STREAM_ID,
250
251 PDW_DST_STREAM_ID, /* pdfwrite */
252
253 SFW_DST_STREAM_ID, /* sfntwrite */
254
255 SVW_DST_STREAM_ID, /* svgwrite */
256 SVW_TMP_STREAM_ID,
257 SVW_DBG_STREAM_ID,
258
259 CEF_SRC_STREAM_ID, /* cfembed */
260 CEF_DST_STREAM_ID,
261 CEF_TMP0_STREAM_ID,
262 CEF_TMP1_STREAM_ID,
263
264 T1C_SRC_STREAM_ID, /* t1cstr */
265
266 T2C_SRC_STREAM_ID, /* t2cstr */
267
268 BZR_SRC_STREAM_ID, /* bezread */
269 BZR_DBG_STREAM_ID,
270
271 SVR_SRC_STREAM_ID, /* svgread */
272 SVR_TMP_STREAM_ID,
273 SVR_DBG_STREAM_ID,
274
275 UFO_SRC_STREAM_ID, /* ufo read format */
276 UFO_DBG_STREAM_ID,
277
278 UFW_DST_STREAM_ID, /* ufowrite */
279 UFW_TMP_STREAM_ID,
280 UFW_DBG_STREAM_ID,
281
282 CTL_SRC_STREAM_ID, /* ctlshare source stream */
283
284 CTL_STREAM_CNT
285 };
286
287 /* These enumeration constants are used by each library API file to establish a
288 unique stream ids. A library client will use these to identify which stream
289 is being opened by the stream open() callback. */
290
291 /* -------------------------- Stream Data Access -------------------------- */
292
293 typedef struct
294 {
295 long cnt;
296 long *offset; /* [cnt] */
297 } ctlSubrs;
298
299 /* The t1cstr and t2cstr libraries obtain charstring data via the stream
300 interface described above. Consequently, character and subroutine
301 charstrings are specified by a stream offset. A set of subroutines is
302 specified with the ctlSubrs data structure as an array of offsets via the
303 "cnt" and "offset" fields. If there are no subroutines the "cnt" and
304 "offset" field must be set to 0.
305
306 The cffread library guarantees that the offsets in the "offset" array are in
307 increasing order but no such guarantee
308 is made by the t1read library. */
309
310 typedef struct
311 {
312 long begin;
313 long end;
314 } ctlRegion;
315
316 /* A ctlRegion struct specifies a set of consecutive bytes within a stream. The
317 "begin" field is the offset of the first byte in the set and the "end" field
318 is one past the last byte in the set. Several of the libraries return
319 ctlRegion's so that clients may access objects in the stream data directly.
320 An empty region is indicated by setting both fields to -1. */
321
322 typedef struct ctlSharedStmCallbacks_ ctlSharedStmCallbacks;
323 struct ctlSharedStmCallbacks_ {
324 void *direct_ctx; /* host library context */
325
326 struct dnaCtx_ *dna; /* dynarr context */
327
328 /* Allocate memory. */
329 void *(*memNew)(ctlSharedStmCallbacks *h, size_t size);
330
331 /* Free memory. */
332 void (*memFree)(ctlSharedStmCallbacks *h, void *ptr);
333
334 /* Seek to an offset in a source stream. */
335 void (*seek)(ctlSharedStmCallbacks *h, long offset);
336
337 /* Return absolute byte position in stream. */
338 long (*tell)(ctlSharedStmCallbacks *h);
339
340 /* Copy count bytes from source stream. */
341 void (*read)(ctlSharedStmCallbacks *h, size_t count, char *ptr);
342
343 /* Read 1-byte unsigned number. */
344 uint8_t (*read1)(ctlSharedStmCallbacks *h);
345
346 /* Read 2-byte number. */
347 uint16_t (*read2)(ctlSharedStmCallbacks *h);
348
349 /* Read 4-byte unsigned number. */
350 uint32_t (*read4)(ctlSharedStmCallbacks *h);
351
352 /* Error message. */
353 void (*message)(ctlSharedStmCallbacks *h, char *msg, ...);
354 };
355
356 /* ctlSharedStmCallbacks is used for reading SFNT tables shared by multiple font formats.
357 * Unlike other font reading libraries, none of stream data and stream reading functions are
358 * implemented in this library. Instead they are implemented by each host library as callbacks.
359 */
360
361 /* ----------------------------- Tag Constants ----------------------------- */
362
363 /* Several Apple data structures use the concept of a tag which is simply a
364 32-bit big endian integer constant that is expressed as four 8-bit
365 characters. Macintosh compilers normally provide a C language extension for
366 creating tag constants, e.g. 'sfnt'. This is convenient but non-portable.
367 The following definition, while a little more awkward to use, is portable
368 and creates an integer constant so can be used anywhere a constant is
369 required, e.g. as an enumeration value. Example usage:
370 CTL_TAG('s','f','n','t') . */
371
372 typedef unsigned long ctlTag;
373 #define CTL_TAG(a, b, c, d) \
374 ((ctlTag)(a) << 24 | (ctlTag)(b) << 16 | (ctlTag)(c) << 8 | (ctlTag)(d))
375
376 #define CTL_SPLIT_TAG(tag) \
377 (int)((tag) >> 24 & 0xff), \
378 (int)((tag) >> 16 & 0xff), \
379 (int)((tag) >> 8 & 0xff), \
380 (int)((tag)&0xff)
381
382 /* CTL_SPLIT_TAG splits the "tag" parameter into its 4 comma-separated
383 characters so that it may be passed to printf and printed using a %c%c%c%c
384 format. */
385
386 /* ------------------------ Error Codes and Strings ------------------------ */
387
388 /* All the library functions return either 0 (afbSuccess) to indicate success
389 or a positive non-zero error code that is defined by a set of enumeration
390 constants. Each library also provides a function to map the error code to a
391 null-terminated error string.
392
393 In order to keep the error code and error string definitions in sync they
394 are defined in a separate include file by a macro called CTL_DCL_ERR that
395 takes a name and a string parameter.
396
397 By defining the CTL_DCL_ERR macro to select only one of its two parameters
398 it is possible to build either an enumeration of the error codes or an
399 initializer for an error strings array.
400
401 If the macro is defined as:
402
403 #define CTL_DCL_ERR(name,string) name,
404
405 before the file is included an enumeration may be built. If the macro is
406 defined as:
407
408 #define CTL_DCL_ERR(name,string) string,
409
410 before the file is included an initializer may be built. */
411
412 /* ---------------------- Client/Library Compatibility ---------------------- */
413
414 struct ctlPadStruct {
415 char c;
416 short s;
417 long l;
418 void *p;
419 float f;
420 double d;
421 };
422
423 #define CTL_CHECK_ARGS_DCL \
424 long version_arg, \
425 size_t size_short, size_t size_long, size_t size_ptr, \
426 size_t size_float, size_t size_double, size_t size_struct
427
428 #define CTL_CHECK_ARGS_CALL(version) \
429 version, \
430 sizeof(short), sizeof(long), sizeof(void *), sizeof(float), sizeof(double), \
431 sizeof(struct ctlPadStruct)
432
433 #define CTL_CHECK_ARGS_TEST(version) \
434 version != version_arg || \
435 sizeof(short) != size_short || \
436 sizeof(long) != size_long || \
437 sizeof(void *) != size_ptr || \
438 sizeof(float) != size_float || \
439 sizeof(double) != size_double || \
440 sizeof(struct ctlPadStruct) != size_struct
441
442 /* It is possible to compile library code and client code using different and
443 incompatible options that will not be detected by the compiler or linker.
444 This can lead to strange runtime errors that are hard to diagnose. The above
445 structure and macros are used to implement a compatibility check between the
446 client and the library when the library is initialized.
447
448 CTL_CHECK_ARGS_DCL macro is used to declare the compatibility checking args
449 in the library initialization function usually call <lib-prefix>New(). The
450 CTL_CHECK_ARGS_CALL macro is used to pass the compatibility checking args to
451 the called library initialization function. The CTL_CHECK_ARGS_TEST macro is
452 used within the library to perform the validation test.
453
454 The following incompatibilities are checked with this mechanism:
455
456 o APIs have different versions
457 o basic C types have different sizes
458 o structure padding differs
459 */
460
461 /* ---------------------- Library Version Information ---------------------- */
462
463 /* There are complicated dependencies between the CoreType library components
464 so it becomes important to track the component versions are linked into an
465 application. The interface described below addresses this requirement by
466 defining a recursive version callback function and an enumeration that
467 uniquely identifies library components. */
468
469 typedef struct ctlVersionCallbacks_ ctlVersionCallbacks;
470 struct ctlVersionCallbacks_ {
471 void *ctx;
472 unsigned long called;
473 void (*getversion)(ctlVersionCallbacks *cb, int version, char *libname);
474 };
475
476 enum {
477 DNA_LIB_ID,
478 PST_LIB_ID,
479 CTU_LIB_ID,
480 ABF_LIB_ID,
481 T1R_LIB_ID,
482 CFR_LIB_ID,
483 TTR_LIB_ID,
484 T1C_LIB_ID,
485 T2C_LIB_ID,
486 CFW_LIB_ID,
487 CEF_LIB_ID,
488 PDW_LIB_ID,
489 T1W_LIB_ID,
490 SFR_LIB_ID,
491 SFW_LIB_ID,
492 BZR_LIB_ID,
493 SVR_LIB_ID,
494 SVW_LIB_ID,
495 UFR_LIB_ID,
496 UFW_LIB_ID,
497 VAR_LIB_ID,
498 CTL_LIB_ID,
499 CTL_LIB_ID_CNT
500 };
501
502 /* Each library component provides a function to obtain both the component's
503 own version and also the versions of all the components it is dependent
504 upon. The function is defined as follows (where xxx is replaced by the
505 components unique prefix):
506
507 void xxxGetVersion(ctlVersionCallbacks *cb);
508
509 A client passes a callback set via the "cb" parameter. This structure
510 contains an optional client "ctx" field. It also contains a
511 "called"-component flags field. This must be initialized to 0 before making
512 the first xxxGetVersion() call. As each component's version is called back a
513 unique bit representing the component is set in the "called" field which is
514 subsequently used to ensure that that only one callback is made per
515 component.
516
517 The "getversion" callback returns the library name and its version number to
518 the client via the "libname" and "version" parameters. The callback set is
519 also available via the "cb" parameter so that the client may access the
520 "ctx" field if necessary. */
521
522 /* ---------------------- Security Functions ---------------------- */
523
524 #ifdef _MSC_VER
525 #define FPRINTF_S fprintf_s
526 #define VFPRINTF_S vfprintf_s
527 #define SPRINTF_S sprintf_s
528 #define VSPRINTF_S vsprintf_s
529 #define SSCANF_S sscanf_s
530 #define STRCPY_S(d, ds, s) strcpy_s(d, ds, s)
531 #define STRNCPY_S(d, ds, s, n) strncpy_s(d, ds, s, n)
532 #define STRCAT_S(d, ds, s) strcat_s(d, ds, s)
533 #else
534 #ifndef FPRINTF_S
535 #define FPRINTF_S fprintf
536 #endif
537 #ifndef VFPRINTF_S
538 #define VFPRINTF_S vfprintf
539 #endif
540 #ifndef SPRINTF_S
541 #define SPRINTF_S(b, l, f, ...) sprintf(b, f, ##__VA_ARGS__)
542 #endif
543 #ifndef VSPRINTF_S
544 #define VSPRINTF_S vsnprintf
545 #endif
546 #ifndef SSCANF_S
547 #define SSCANF_S sscanf
548 #endif
549 #ifndef STRCPY_S
550 #define STRCPY_S(d, ds, s) strcpy(d, s)
551 #endif
552 #ifndef STRNCPY_S
553 #define STRNCPY_S(d, ds, s, n) strncpy(d, s, n)
554 #endif
555 #ifndef STRCAT_S
556 #define STRCAT_S(d, ds, s) strcat(d, s)
557 #endif
558 #endif
559
560 #endif /* CTLSHARE_H */