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 */