| /**************************************************************************** |
| * |
| * fterrors.h |
| * |
| * FreeType error code handling (specification). |
| * |
| * Copyright (C) 1996-2021 by |
| * David Turner, Robert Wilhelm, and Werner Lemberg. |
| * |
| * This file is part of the FreeType project, and may only be used, |
| * modified, and distributed under the terms of the FreeType project |
| * license, LICENSE.TXT. By continuing to use, modify, or distribute |
| * this file you indicate that you have read the license and |
| * understand and accept it fully. |
| * |
| */ |
| |
| |
| /************************************************************************** |
| * |
| * @section: |
| * error_enumerations |
| * |
| * @title: |
| * Error Enumerations |
| * |
| * @abstract: |
| * How to handle errors and error strings. |
| * |
| * @description: |
| * The header file `fterrors.h` (which is automatically included by |
| * `freetype.h` defines the handling of FreeType's enumeration |
| * constants. It can also be used to generate error message strings |
| * with a small macro trick explained below. |
| * |
| * **Error Formats** |
| * |
| * The configuration macro `FT_CONFIG_OPTION_USE_MODULE_ERRORS` can be |
| * defined in `ftoption.h` in order to make the higher byte indicate the |
| * module where the error has happened (this is not compatible with |
| * standard builds of FreeType~2, however). See the file `ftmoderr.h` |
| * for more details. |
| * |
| * **Error Message Strings** |
| * |
| * Error definitions are set up with special macros that allow client |
| * applications to build a table of error message strings. The strings |
| * are not included in a normal build of FreeType~2 to save space (most |
| * client applications do not use them). |
| * |
| * To do so, you have to define the following macros before including |
| * this file. |
| * |
| * ``` |
| * FT_ERROR_START_LIST |
| * ``` |
| * |
| * This macro is called before anything else to define the start of the |
| * error list. It is followed by several `FT_ERROR_DEF` calls. |
| * |
| * ``` |
| * FT_ERROR_DEF( e, v, s ) |
| * ``` |
| * |
| * This macro is called to define one single error. 'e' is the error |
| * code identifier (e.g., `Invalid_Argument`), 'v' is the error's |
| * numerical value, and 's' is the corresponding error string. |
| * |
| * ``` |
| * FT_ERROR_END_LIST |
| * ``` |
| * |
| * This macro ends the list. |
| * |
| * Additionally, you have to undefine `FTERRORS_H_` before #including |
| * this file. |
| * |
| * Here is a simple example. |
| * |
| * ``` |
| * #undef FTERRORS_H_ |
| * #define FT_ERRORDEF( e, v, s ) { e, s }, |
| * #define FT_ERROR_START_LIST { |
| * #define FT_ERROR_END_LIST { 0, NULL } }; |
| * |
| * const struct |
| * { |
| * int err_code; |
| * const char* err_msg; |
| * } ft_errors[] = |
| * |
| * #include <freetype/fterrors.h> |
| * ``` |
| * |
| * An alternative to using an array is a switch statement. |
| * |
| * ``` |
| * #undef FTERRORS_H_ |
| * #define FT_ERROR_START_LIST switch ( error_code ) { |
| * #define FT_ERRORDEF( e, v, s ) case v: return s; |
| * #define FT_ERROR_END_LIST } |
| * ``` |
| * |
| * If you use `FT_CONFIG_OPTION_USE_MODULE_ERRORS`, `error_code` should |
| * be replaced with `FT_ERROR_BASE(error_code)` in the last example. |
| */ |
| |
| /* */ |
| |
| /* In previous FreeType versions we used `__FTERRORS_H__`. However, */ |
| /* using two successive underscores in a non-system symbol name */ |
| /* violates the C (and C++) standard, so it was changed to the */ |
| /* current form. In spite of this, we have to make */ |
| /* */ |
| /* ``` */ |
| /* #undefine __FTERRORS_H__ */ |
| /* ``` */ |
| /* */ |
| /* work for backward compatibility. */ |
| /* */ |
| #if !( defined( FTERRORS_H_ ) && defined ( __FTERRORS_H__ ) ) |
| #define FTERRORS_H_ |
| #define __FTERRORS_H__ |
| |
| |
| /* include module base error codes */ |
| #include <freetype/ftmoderr.h> |
| |
| |
| /*******************************************************************/ |
| /*******************************************************************/ |
| /***** *****/ |
| /***** SETUP MACROS *****/ |
| /***** *****/ |
| /*******************************************************************/ |
| /*******************************************************************/ |
| |
| |
| #undef FT_NEED_EXTERN_C |
| |
| |
| /* FT_ERR_PREFIX is used as a prefix for error identifiers. */ |
| /* By default, we use `FT_Err_`. */ |
| /* */ |
| #ifndef FT_ERR_PREFIX |
| #define FT_ERR_PREFIX FT_Err_ |
| #endif |
| |
| |
| /* FT_ERR_BASE is used as the base for module-specific errors. */ |
| /* */ |
| #ifdef FT_CONFIG_OPTION_USE_MODULE_ERRORS |
| |
| #ifndef FT_ERR_BASE |
| #define FT_ERR_BASE FT_Mod_Err_Base |
| #endif |
| |
| #else |
| |
| #undef FT_ERR_BASE |
| #define FT_ERR_BASE 0 |
| |
| #endif /* FT_CONFIG_OPTION_USE_MODULE_ERRORS */ |
| |
| |
| /* If FT_ERRORDEF is not defined, we need to define a simple */ |
| /* enumeration type. */ |
| /* */ |
| #ifndef FT_ERRORDEF |
| |
| #define FT_INCLUDE_ERR_PROTOS |
| |
| #define FT_ERRORDEF( e, v, s ) e = v, |
| #define FT_ERROR_START_LIST enum { |
| #define FT_ERROR_END_LIST FT_ERR_CAT( FT_ERR_PREFIX, Max ) }; |
| |
| #ifdef __cplusplus |
| #define FT_NEED_EXTERN_C |
| extern "C" { |
| #endif |
| |
| #endif /* !FT_ERRORDEF */ |
| |
| |
| /* this macro is used to define an error */ |
| #define FT_ERRORDEF_( e, v, s ) \ |
| FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v + FT_ERR_BASE, s ) |
| |
| /* this is only used for <module>_Err_Ok, which must be 0! */ |
| #define FT_NOERRORDEF_( e, v, s ) \ |
| FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v, s ) |
| |
| |
| #ifdef FT_ERROR_START_LIST |
| FT_ERROR_START_LIST |
| #endif |
| |
| |
| /* now include the error codes */ |
| #include <freetype/fterrdef.h> |
| |
| |
| #ifdef FT_ERROR_END_LIST |
| FT_ERROR_END_LIST |
| #endif |
| |
| |
| /*******************************************************************/ |
| /*******************************************************************/ |
| /***** *****/ |
| /***** SIMPLE CLEANUP *****/ |
| /***** *****/ |
| /*******************************************************************/ |
| /*******************************************************************/ |
| |
| #ifdef FT_NEED_EXTERN_C |
| } |
| #endif |
| |
| #undef FT_ERROR_START_LIST |
| #undef FT_ERROR_END_LIST |
| |
| #undef FT_ERRORDEF |
| #undef FT_ERRORDEF_ |
| #undef FT_NOERRORDEF_ |
| |
| #undef FT_NEED_EXTERN_C |
| #undef FT_ERR_BASE |
| |
| /* FT_ERR_PREFIX is needed internally */ |
| #ifndef FT2_BUILD_LIBRARY |
| #undef FT_ERR_PREFIX |
| #endif |
| |
| /* FT_INCLUDE_ERR_PROTOS: Control whether function prototypes should be */ |
| /* included with */ |
| /* */ |
| /* #include <freetype/fterrors.h> */ |
| /* */ |
| /* This is only true where `FT_ERRORDEF` is */ |
| /* undefined. */ |
| /* */ |
| /* FT_ERR_PROTOS_DEFINED: Actual multiple-inclusion protection of */ |
| /* `fterrors.h`. */ |
| #ifdef FT_INCLUDE_ERR_PROTOS |
| #undef FT_INCLUDE_ERR_PROTOS |
| |
| #ifndef FT_ERR_PROTOS_DEFINED |
| #define FT_ERR_PROTOS_DEFINED |
| |
| |
| FT_BEGIN_HEADER |
| |
| /************************************************************************** |
| * |
| * @function: |
| * FT_Error_String |
| * |
| * @description: |
| * Retrieve the description of a valid FreeType error code. |
| * |
| * @input: |
| * error_code :: |
| * A valid FreeType error code. |
| * |
| * @return: |
| * A C~string or `NULL`, if any error occurred. |
| * |
| * @note: |
| * FreeType has to be compiled with `FT_CONFIG_OPTION_ERROR_STRINGS` or |
| * `FT_DEBUG_LEVEL_ERROR` to get meaningful descriptions. |
| * 'error_string' will be `NULL` otherwise. |
| * |
| * Module identification will be ignored: |
| * |
| * ```c |
| * strcmp( FT_Error_String( FT_Err_Unknown_File_Format ), |
| * FT_Error_String( BDF_Err_Unknown_File_Format ) ) == 0; |
| * ``` |
| */ |
| FT_EXPORT( const char* ) |
| FT_Error_String( FT_Error error_code ); |
| |
| FT_END_HEADER |
| |
| |
| #endif /* FT_ERR_PROTOS_DEFINED */ |
| |
| #endif /* FT_INCLUDE_ERR_PROTOS */ |
| |
| #endif /* !(FTERRORS_H_ && __FTERRORS_H__) */ |
| |
| |
| /* END */ |
