• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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