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