freetype2/freetype/fterrors.h

0001 /****************************************************************************
0002  *
0003  * fterrors.h
0004  *
0005  *   FreeType error code handling (specification).
0006  *
0007  * Copyright (C) 1996-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019   /**************************************************************************
0020    *
0021    * @section:
0022    *   error_enumerations
0023    *
0024    * @title:
0025    *   Error Enumerations
0026    *
0027    * @abstract:
0028    *   How to handle errors and error strings.
0029    *
0030    * @description:
0031    *   The header file `fterrors.h` (which is automatically included by
0032    *   `freetype.h`) defines the handling of FreeType's enumeration
0033    *   constants.  It can also be used to generate error message strings
0034    *   with a small macro trick explained below.
0035    *
0036    *   **Error Formats**
0037    *
0038    *   The configuration macro `FT_CONFIG_OPTION_USE_MODULE_ERRORS` can be
0039    *   defined in `ftoption.h` in order to make the higher byte indicate the
0040    *   module where the error has happened (this is not compatible with
0041    *   standard builds of FreeType~2, however).  See the file `ftmoderr.h`
0042    *   for more details.
0043    *
0044    *   **Error Message Strings**
0045    *
0046    *   Error definitions are set up with special macros that allow client
0047    *   applications to build a table of error message strings.  The strings
0048    *   are not included in a normal build of FreeType~2 to save space (most
0049    *   client applications do not use them).
0050    *
0051    *   To do so, you have to define the following macros before including
0052    *   this file.
0053    *
0054    *   ```
0055    *     FT_ERROR_START_LIST
0056    *   ```
0057    *
0058    *   This macro is called before anything else to define the start of the
0059    *   error list.  It is followed by several `FT_ERROR_DEF` calls.
0060    *
0061    *   ```
0062    *     FT_ERROR_DEF( e, v, s )
0063    *   ```
0064    *
0065    *   This macro is called to define one single error.  'e' is the error
0066    *   code identifier (e.g., `Invalid_Argument`), 'v' is the error's
0067    *   numerical value, and 's' is the corresponding error string.
0068    *
0069    *   ```
0070    *     FT_ERROR_END_LIST
0071    *   ```
0072    *
0073    *   This macro ends the list.
0074    *
0075    *   Additionally, you have to undefine `FTERRORS_H_` before #including
0076    *   this file.
0077    *
0078    *   Here is a simple example.
0079    *
0080    *   ```
0081    *     #undef FTERRORS_H_
0082    *     #define FT_ERRORDEF( e, v, s )  { e, s },
0083    *     #define FT_ERROR_START_LIST     {
0084    *     #define FT_ERROR_END_LIST       { 0, NULL } };
0085    *
0086    *     const struct
0087    *     {
0088    *       int          err_code;
0089    *       const char*  err_msg;
0090    *     } ft_errors[] =
0091    *
0092    *     #include <freetype/fterrors.h>
0093    *   ```
0094    *
0095    *   An alternative to using an array is a switch statement.
0096    *
0097    *   ```
0098    *     #undef FTERRORS_H_
0099    *     #define FT_ERROR_START_LIST     switch ( error_code ) {
0100    *     #define FT_ERRORDEF( e, v, s )    case v: return s;
0101    *     #define FT_ERROR_END_LIST       }
0102    *   ```
0103    *
0104    *   If you use `FT_CONFIG_OPTION_USE_MODULE_ERRORS`, `error_code` should
0105    *   be replaced with `FT_ERROR_BASE(error_code)` in the last example.
0106    */
0107
0108   /* */
0109
0110   /* In previous FreeType versions we used `__FTERRORS_H__`.  However, */
0111   /* using two successive underscores in a non-system symbol name      */
0112   /* violates the C (and C++) standard, so it was changed to the       */
0113   /* current form.  In spite of this, we have to make                  */
0114   /*                                                                   */
0115   /* ```                                                               */
0116   /*   #undefine __FTERRORS_H__                                        */
0117   /* ```                                                               */
0118   /*                                                                   */
0119   /* work for backward compatibility.                                  */
0120   /*                                                                   */
0121 #if !( defined( FTERRORS_H_ ) && defined ( __FTERRORS_H__ ) )
0122 #define FTERRORS_H_
0123 #define __FTERRORS_H__
0124
0125
0126   /* include module base error codes */
0127 #include <freetype/ftmoderr.h>
0128
0129
0130   /*******************************************************************/
0131   /*******************************************************************/
0132   /*****                                                         *****/
0133   /*****                       SETUP MACROS                      *****/
0134   /*****                                                         *****/
0135   /*******************************************************************/
0136   /*******************************************************************/
0137
0138
0139 #undef  FT_NEED_EXTERN_C
0140
0141
0142   /* FT_ERR_PREFIX is used as a prefix for error identifiers. */
0143   /* By default, we use `FT_Err_`.                            */
0144   /*                                                          */
0145 #ifndef FT_ERR_PREFIX
0146 #define FT_ERR_PREFIX  FT_Err_
0147 #endif
0148
0149
0150   /* FT_ERR_BASE is used as the base for module-specific errors. */
0151   /*                                                             */
0152 #ifdef FT_CONFIG_OPTION_USE_MODULE_ERRORS
0153
0154 #ifndef FT_ERR_BASE
0155 #define FT_ERR_BASE  FT_Mod_Err_Base
0156 #endif
0157
0158 #else
0159
0160 #undef FT_ERR_BASE
0161 #define FT_ERR_BASE  0
0162
0163 #endif /* FT_CONFIG_OPTION_USE_MODULE_ERRORS */
0164
0165
0166   /* If FT_ERRORDEF is not defined, we need to define a simple */
0167   /* enumeration type.                                         */
0168   /*                                                           */
0169 #ifndef FT_ERRORDEF
0170
0171 #define FT_INCLUDE_ERR_PROTOS
0172
0173 #define FT_ERRORDEF( e, v, s )  e = v,
0174 #define FT_ERROR_START_LIST     enum {
0175 #define FT_ERROR_END_LIST       FT_ERR_CAT( FT_ERR_PREFIX, Max ) };
0176
0177 #ifdef __cplusplus
0178 #define FT_NEED_EXTERN_C
0179   extern "C" {
0180 #endif
0181
0182 #endif /* !FT_ERRORDEF */
0183
0184
0185   /* this macro is used to define an error */
0186 #define FT_ERRORDEF_( e, v, s )                                             \
0187           FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v + FT_ERR_BASE, s )
0188
0189   /* this is only used for <module>_Err_Ok, which must be 0! */
0190 #define FT_NOERRORDEF_( e, v, s )                             \
0191           FT_ERRORDEF( FT_ERR_CAT( FT_ERR_PREFIX, e ), v, s )
0192
0193
0194 #ifdef FT_ERROR_START_LIST
0195   FT_ERROR_START_LIST
0196 #endif
0197
0198
0199   /* now include the error codes */
0200 #include <freetype/fterrdef.h>
0201
0202
0203 #ifdef FT_ERROR_END_LIST
0204   FT_ERROR_END_LIST
0205 #endif
0206
0207
0208   /*******************************************************************/
0209   /*******************************************************************/
0210   /*****                                                         *****/
0211   /*****                      SIMPLE CLEANUP                     *****/
0212   /*****                                                         *****/
0213   /*******************************************************************/
0214   /*******************************************************************/
0215
0216 #ifdef FT_NEED_EXTERN_C
0217   }
0218 #endif
0219
0220 #undef FT_ERROR_START_LIST
0221 #undef FT_ERROR_END_LIST
0222
0223 #undef FT_ERRORDEF
0224 #undef FT_ERRORDEF_
0225 #undef FT_NOERRORDEF_
0226
0227 #undef FT_NEED_EXTERN_C
0228 #undef FT_ERR_BASE
0229
0230   /* FT_ERR_PREFIX is needed internally */
0231 #ifndef FT2_BUILD_LIBRARY
0232 #undef FT_ERR_PREFIX
0233 #endif
0234
0235   /* FT_INCLUDE_ERR_PROTOS: Control whether function prototypes should be */
0236   /*                        included with                                 */
0237   /*                                                                      */
0238   /*                          #include <freetype/fterrors.h>              */
0239   /*                                                                      */
0240   /*                        This is only true where `FT_ERRORDEF` is      */
0241   /*                        undefined.                                    */
0242   /*                                                                      */
0243   /* FT_ERR_PROTOS_DEFINED: Actual multiple-inclusion protection of       */
0244   /*                        `fterrors.h`.                                 */
0245 #ifdef FT_INCLUDE_ERR_PROTOS
0246 #undef FT_INCLUDE_ERR_PROTOS
0247
0248 #ifndef FT_ERR_PROTOS_DEFINED
0249 #define FT_ERR_PROTOS_DEFINED
0250
0251
0252 FT_BEGIN_HEADER
0253
0254   /**************************************************************************
0255    *
0256    * @function:
0257    *   FT_Error_String
0258    *
0259    * @description:
0260    *   Retrieve the description of a valid FreeType error code.
0261    *
0262    * @input:
0263    *   error_code ::
0264    *     A valid FreeType error code.
0265    *
0266    * @return:
0267    *   A C~string or `NULL`, if any error occurred.
0268    *
0269    * @note:
0270    *   FreeType has to be compiled with `FT_CONFIG_OPTION_ERROR_STRINGS` or
0271    *   `FT_DEBUG_LEVEL_ERROR` to get meaningful descriptions.
0272    *   'error_string' will be `NULL` otherwise.
0273    *
0274    *   Module identification will be ignored:
0275    *
0276    *   ```c
0277    *     strcmp( FT_Error_String(  FT_Err_Unknown_File_Format ),
0278    *             FT_Error_String( BDF_Err_Unknown_File_Format ) ) == 0;
0279    *   ```
0280    */
0281   FT_EXPORT( const char* )
0282   FT_Error_String( FT_Error  error_code );
0283
0284   /* */
0285
0286 FT_END_HEADER
0287
0288
0289 #endif /* FT_ERR_PROTOS_DEFINED */
0290
0291 #endif /* FT_INCLUDE_ERR_PROTOS */
0292
0293 #endif /* !(FTERRORS_H_ && __FTERRORS_H__) */
0294
0295
0296 /* END */