1/***************************************************************************/
2/* */
3/* fterrors.h */
4/* */
5/* FreeType error code handling (specification). */
6/* */
7/* Copyright 1996-2018 by */
8/* David Turner, Robert Wilhelm, and Werner Lemberg. */
9/* */
10/* This file is part of the FreeType project, and may only be used, */
11/* modified, and distributed under the terms of the FreeType project */
12/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
13/* this file you indicate that you have read the license and */
14/* understand and accept it fully. */
15/* */
16/***************************************************************************/
17
18
19 /*************************************************************************/
20 /* */
21 /* <Section> */
22 /* error_enumerations */
23 /* */
24 /* <Title> */
25 /* Error Enumerations */
26 /* */
27 /* <Abstract> */
28 /* How to handle errors and error strings. */
29 /* */
30 /* <Description> */
31 /* The header file `fterrors.h' (which is automatically included by */
32 /* `freetype.h' defines the handling of FreeType's enumeration */
33 /* constants. It can also be used to generate error message strings */
34 /* with a small macro trick explained below. */
35 /* */
36 /* *Error* *Formats* */
37 /* */
38 /* The configuration macro FT_CONFIG_OPTION_USE_MODULE_ERRORS can be */
39 /* defined in `ftoption.h' in order to make the higher byte indicate */
40 /* the module where the error has happened (this is not compatible */
41 /* with standard builds of FreeType~2, however). See the file */
42 /* `ftmoderr.h' for more details. */
43 /* */
44 /* *Error* *Message* *Strings* */
45 /* */
46 /* Error definitions are set up with special macros that allow client */
47 /* applications to build a table of error message strings. The */
48 /* strings are not included in a normal build of FreeType~2 to save */
49 /* space (most client applications do not use them). */
50 /* */
51 /* To do so, you have to define the following macros before including */
52 /* this file. */
53 /* */
54 /* { */
55 /* FT_ERROR_START_LIST */
56 /* } */
57 /* */
58 /* This macro is called before anything else to define the start of */
59 /* the error list. It is followed by several FT_ERROR_DEF calls. */
60 /* */
61 /* { */
62 /* FT_ERROR_DEF( e, v, s ) */
63 /* } */
64 /* */
65 /* This macro is called to define one single error. `e' is the error */
66 /* code identifier (e.g., `Invalid_Argument'), `v' is the error's */
67 /* numerical value, and `s' is the corresponding error string. */
68 /* */
69 /* { */
70 /* FT_ERROR_END_LIST */
71 /* } */
72 /* */
73 /* This macro ends the list. */
74 /* */
75 /* Additionally, you have to undefine `FTERRORS_H_' before #including */
76 /* this file. */
77 /* */
78 /* Here is a simple example. */
79 /* */
80 /* { */
81 /* #undef FTERRORS_H_ */
82 /* #define FT_ERRORDEF( e, v, s ) { e, s }, */
83 /* #define FT_ERROR_START_LIST { */
84 /* #define FT_ERROR_END_LIST { 0, NULL } }; */
85 /* */
86 /* const struct */
87 /* { */
88 /* int err_code; */
89 /* const char* err_msg; */
90 /* } ft_errors[] = */
91 /* */
92 /* #include FT_ERRORS_H */
93 /* } */
94 /* */
95 /* Note that `FT_Err_Ok' is _not_ defined with `FT_ERRORDEF' but with */
96 /* `FT_NOERRORDEF'; it is always zero. */
97 /* */
98 /*************************************************************************/
99
100 /* */
101
102 /* In previous FreeType versions we used `__FTERRORS_H__'. However, */
103 /* using two successive underscores in a non-system symbol name */
104 /* violates the C (and C++) standard, so it was changed to the */
105 /* current form. In spite of this, we have to make */
106 /* */
107 /* #undefine __FTERRORS_H__ */
108 /* */
109 /* work for backward compatibility. */
110 /* */
111#if !( defined( FTERRORS_H_ ) && defined ( __FTERRORS_H__ ) )
112#define FTERRORS_H_
113#define __FTERRORS_H__
114
115
116 /* include module base error codes */
117#include FT_MODULE_ERRORS_H
118
119
120 /*******************************************************************/
121 /*******************************************************************/
122 /***** *****/
123 /***** SETUP MACROS *****/
124 /***** *****/
125 /*******************************************************************/
126 /*******************************************************************/
127
128
129#undef FT_NEED_EXTERN_C
130
131
132 /* FT_ERR_PREFIX is used as a prefix for error identifiers. */
133 /* By default, we use `FT_Err_'. */
134 /* */
135#ifndef FT_ERR_PREFIX
136#define FT_ERR_PREFIX FT_Err_
137#endif
138
139
140 /* FT_ERR_BASE is used as the base for module-specific errors. */
141 /* */
142#ifdef FT_CONFIG_OPTION_USE_MODULE_ERRORS
143
144#ifndef FT_ERR_BASE
145#define FT_ERR_BASE FT_Mod_Err_Base
146#endif
147
148#else
149
150#undef FT_ERR_BASE
151#define FT_ERR_BASE 0
152
153#endif /* FT_CONFIG_OPTION_USE_MODULE_ERRORS */
154
155
156 /* If FT_ERRORDEF is not defined, we need to define a simple */
157 /* enumeration type. */
158 /* */
159#ifndef FT_ERRORDEF
160
161#define FT_ERRORDEF( e, v, s ) e = v,
162#define FT_ERROR_START_LIST enum {
163#define FT_ERROR_END_LIST FT_ERR_CAT( FT_ERR_PREFIX, Max ) };
164
165#ifdef __cplusplus
166#define FT_NEED_EXTERN_C
167 extern "C" {
168#endif
169
170#endif /* !FT_ERRORDEF */
171
172
173 /* this macro is used to define an error */
174#define FT_ERRORDEF_( e, v, s ) \
175 FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v + FT_ERR_BASE, s )
176
177 /* this is only used for <module>_Err_Ok, which must be 0! */
178#define FT_NOERRORDEF_( e, v, s ) \
179 FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v, s )
180
181
182#ifdef FT_ERROR_START_LIST
183 FT_ERROR_START_LIST
184#endif
185
186
187 /* now include the error codes */
188#include FT_ERROR_DEFINITIONS_H
189
190
191#ifdef FT_ERROR_END_LIST
192 FT_ERROR_END_LIST
193#endif
194
195
196 /*******************************************************************/
197 /*******************************************************************/
198 /***** *****/
199 /***** SIMPLE CLEANUP *****/
200 /***** *****/
201 /*******************************************************************/
202 /*******************************************************************/
203
204#ifdef FT_NEED_EXTERN_C
205 }
206#endif
207
208#undef FT_ERROR_START_LIST
209#undef FT_ERROR_END_LIST
210
211#undef FT_ERRORDEF
212#undef FT_ERRORDEF_
213#undef FT_NOERRORDEF_
214
215#undef FT_NEED_EXTERN_C
216#undef FT_ERR_BASE
217
218 /* FT_ERR_PREFIX is needed internally */
219#ifndef FT2_BUILD_LIBRARY
220#undef FT_ERR_PREFIX
221#endif
222
223#endif /* !(FTERRORS_H_ && __FTERRORS_H__) */
224
225
226/* END */
227