1 /***************************************************************************/ 2 /* */ 3 /* fterrors.h */ 4 /* */ 5 /* FreeType error code handling (specification). */ 6 /* */ 7 /* Copyright 1996-2017 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 */ 49 /* save 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 backwards 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