FreeType » Docs » Error Codes » Error Enumerations
Error Enumerations¶
Synopsis¶
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 FT_ERRORS_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.
FT_Error_String¶
Defined in FT_ERRORS_H (freetype/fterrors.h).
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 */
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:
strcmp( FT_Error_String( FT_Err_Unknown_File_Format ),
FT_Error_String( BDF_Err_Unknown_File_Format ) ) == 0;