# Documentation/Error handling

### From libHaru.org wiki

< Documentation

# Function types

Related to return value on error, there are three kinds of functions in Haru.

Function type | Return value when error occurs
--- | ---
1. Functions returning HPDF_STATUS | Error code
2. Functions returning object handle | NULL
3. Functions returning other values | Initial value

When an error occurs, first the return value is returned, then an error code is stored in the document object, and finally the user-defined error function (if defined) is invoked.

HPDF_GetError() returns the error code. However, when the first parameter of a function is invalid, the error code is not set (and so cannot be retrieved). This is because the failing function cannot find the document object for storing the error code.

In addition, some functions also set a detailed error code. HPDF_GetErrorDetail() returns the detailed error code.

NOTE: Once an error code is set, some IO processing functions are blocked. Therefore, HPDF_ResetError() must be invoked to resume program.

# User-defined error handler

You can define a user-defined error handler which is invoked when an error occurs. The definition of an error handler is as follows:

    #include "hpdf_types.h"

    typedef void (*HPDF_Error_Handler)  (HPDF_STATUS   error_no,
                                         HPDF_STATUS   detail_no,
                                         void         *user_data);

When you build Haru as a shared library in Windows environment, the definition of an error handler is as follows:

    #include "hpdf_types.h"

    typedef void (__stdcall *HPDF_Error_Handler) (HPDF_STATUS  error_no,
                                                  HPDF_STATUS  detail_no,
                                                  void        *user_data);

# Effective usage of a user-defined error handler

You can perform error processing effectively by using an error handler.

## The typical usage of error handler with C

C language does not directly support exception handling, but by emulating exception handling with setjmp / longjmp, error handling becomes simple.

    void error_handler (HPDF_STATUS error_no, HPDF_STATUS detail_no, void *user_data)
    {
        printf ("ERROR: error_no=%04X, detail_no=%d\n",
          (unsigned int) error_no, (int) detail_no);
        longjmp (env, 1); /* invoke longjmp() on error */
    }

    int main ()
    {
        HPDF_Doc pdf;

        pdf = HPDF_New (error_handler, NULL); /* set error-handler */
        if (!pdf) {
            printf ("error: cannot create PdfDoc object\n");
            return 1;
        }

        if (setjmp(env)) {
            HPDF_Free (pdf);
            return 1;
        }

        /* do page description processes (do not have to check function return codes) */

        HPDF_SaveToFile (pdf, fname);
        HPDF_Free (pdf);
        return 0;
    }

## The typical usage of error handler with C++

C++ directly supports an exception handling. Error processing becomes simple by throwing an exception when an error has occurred.

    void error_handler (HPDF_STATUS error_no, HPDF_STATUS detail_no, void *user_data)
    {
        printf ("ERROR: error_no=%04X, detail_no=%d\n",
          (unsigned int) error_no, (int) detail_no);
        throw std::exception (); /* throw exception on error */
    }

    int main ()
    {
        HPDF_Doc pdf = HPDF_New (error_handler, NULL); /* set error-handler */
        if (!pdf) {
            printf ("error: cannot create PdfDoc object\n");
            return 1;
        }

        try {
            /* do page description processes (do not have to check function return codes) */
            HPDF_SaveToFile (pdf, fname);
            } catch (...) {
            HPDF_Free (pdf);
            return 1;
            }

        HPDF_Free (pdf);
        return 0;
        }
    }

## Other programing languages

For languages supporting exception handling, you can handle errors in a similar way. For languages lacking exception handling, you have to check return code after invoking functions. There are wrapper programs for Ruby, Delphi and C# in "if" directory. Refer to their source code.

# List of error codes

Name | Value | Description
--- | --- | ---
HPDF_ARRAY_COUNT_ERR | 0x1001 | Internal error. Data consistency was lost.
HPDF_ARRAY_ITEM_NOT_FOUND | 0x1002 | Internal error. Data consistency was lost.
HPDF_ARRAY_ITEM_UNEXPECTED_TYPE | 0x1003 | Internal error. Data consistency was lost.
HPDF_BINARY_LENGTH_ERR | 0x1004 | Data length > HPDF_LIMIT_MAX_STRING_LEN.
HPDF_CANNOT_GET_PALLET | 0x1005 | Cannot get pallet data from PNG image.
*** | 0x1006 | ***
HPDF_DICT_COUNT_ERR | 0x1007 | Dictionary elements > HPDF_LIMIT_MAX_DICT_ELEMENT
HPDF_DICT_ITEM_NOT_FOUND | 0x1008 | Internal error. Data consistency was lost.
HPDF_DICT_ITEM_UNEXPECTED_TYPE | 0x1009 | Internal error. Data consistency was lost.
HPDF_DICT_STREAM_LENGTH_NOT_FOUND | 0x100A | Internal error. Data consistency was lost.
HPDF_DOC_ENCRYPTDICT_NOT_FOUND | 0x100B | HPDF_SetEncryptMode() or HPDF_SetPermission() called before password set.
HPDF_DOC_INVALID_OBJECT | 0x100C | Internal error. Data consistency was lost.
*** | 0x100D | ***
HPDF_DUPLICATE_REGISTRATION | 0x100E | Tried to re-register a registered font.
HPDF_EXCEED_JWW_CODE_NUM_LIMIT | 0x100F | Cannot register a character to the Japanese word wrap characters list.
*** | 0x1010 | ***
HPDF_ENCRYPT_INVALID_PASSWORD | 0x1011 | 1. Tried to set the owner password to NULL. 2. Owner and user password are the same.
*** | 0x1012 | ***
HPDF_ERR_UNKNOWN_CLASS | 0x1013 | Internal error. Data consistency was lost.
HPDF_EXCEED_GSTATE_LIMIT | 0x1014 | Stack depth > HPDF_LIMIT_MAX_GSTATE.
HPDF_FAILD_TO_ALLOC_MEM | 0x1015 | Memory allocation failed.
HPDF_FILE_IO_ERROR | 0x1016 | File processing failed. (Detailed code is set.)
HPDF_FILE_OPEN_ERROR | 0x1017 | Cannot open a file. (Detailed code is set.)
*** | 0x1018 | ***
HPDF_FONT_EXISTS | 0x1019 | Tried to load a font that has been registered.
HPDF_FONT_INVALID_WIDTHS_TABLE | 0x101A | 1. Font-file format is invalid. 2. Internal error. Data consistency was lost.
HPDF_INVALID_AFM_HEADER | 0x101B | Cannot recognize header of afm file.
HPDF_INVALID_ANNOTATION | 0x101C | Specified annotation handle is invalid.
*** | 0x101D | ***
HPDF_INVALID_BIT_PER_COMPONENT | 0x101E | Bit-per-component of a image which was set as mask-image is invalid.
HPDF_INVALID_CHAR_MATRICS_DATA | 0x101F | Cannot recognize char-matrics-data of afm file.
HPDF_INVALID_COLOR_SPACE | 0x1020 | 1. Invalid color_space parameter of HPDF_LoadRawImage. 2. Color-space of a image which was set as mask-image is invalid. 3. Invoked function invalid in present color-space.
HPDF_INVALID_COMPRESSION_MODE | 0x1021 | Invalid value set when invoking HPDF_SetCommpressionMode().
HPDF_INVALID_DATE_TIME | 0x1022 | An invalid date-time value was set.
HPDF_INVALID_DESTINATION | 0x1023 | An invalid destination handle was set.
*** | 0x1024 | ***
HPDF_INVALID_DOCUMENT | 0x1025 | An invalid document handle was set.
HPDF_INVALID_DOCUMENT_STATE | 0x1026 | Function invalid in the present state was invoked.
HPDF_INVALID_ENCODER | 0x1027 | An invalid encoder handle was set.
HPDF_INVALID_ENCODER_TYPE | 0x1028 | Combination between font and encoder is wrong.
*** | 0x1029 | ***
*** | 0x102A | ***
HPDF_INVALID_ENCODING_NAME | 0x102B | An Invalid encoding name is specified.
HPDF_INVALID_ENCRYPT_KEY_LEN | 0x102C | Encryption key length is invalid.
HPDF_INVALID_FONTDEF_DATA | 0x102D | 1. An invalid font handle was set. 2. Unsupported font format.
HPDF_INVALID_FONTDEF_TYPE | 0x102E | Internal error. Data consistency was lost.
HPDF_INVALID_FONT_NAME | 0x102F | Font with the specified name is not found.
HPDF_INVALID_IMAGE | 0x1030 | Unsupported image format.
HPDF_INVALID_JPEG_DATA | 0x1031 | Unsupported image format.
HPDF_INVALID_N_DATA | 0x1032 | Cannot read a postscript-name from an afm file.
HPDF_INVALID_OBJECT | 0x1033 | 1. An invalid object is set. 2. Internal error. Data consistency was lost.
HPDF_INVALID_OBJ_ID | 0x1034 | Internal error. Data consistency was lost.
HPDF_INVALID_OPERATION | 0x1035 | Invoked HPDF_Image_SetColorMask() against the image-object which was set a mask-image.
HPDF_INVALID_OUTLINE | 0x1036 | An invalid outline-handle was specified.
HPDF_INVALID_PAGE | 0x1037 | An invalid page-handle was specified.
HPDF_INVALID_PAGES | 0x1038 | An invalid pages-handle was specified. (internal error)
HPDF_INVALID_PARAMETER | 0x1039 | An invalid value is set.
*** | 0x103A | ***
HPDF_INVALID_PNG_IMAGE | 0x103B | Invalid PNG image format.
HPDF_INVALID_STREAM | 0x103C | Internal error. Data consistency was lost.
HPDF_MISSING_FILE_NAME_ENTRY | 0x103D | Internal error. "_FILE_NAME" entry for delayed loading is missing.
*** | 0x103E | ***
HPDF_INVALID_TTC_FILE | 0x103F | Invalid .TTC file format.
HPDF_INVALID_TTC_INDEX | 0x1040 | Index parameter > number of included fonts.
HPDF_INVALID_WX_DATA | 0x1041 | Cannot read a width-data from an afm file.
HPDF_ITEM_NOT_FOUND | 0x1042 | Internal error. Data consistency was lost.
HPDF_LIBPNG_ERROR | 0x1043 | Error returned from PNGLIB while loading image.
HPDF_NAME_INVALID_VALUE | 0x1044 | Internal error. Data consistency was lost.
HPDF_NAME_OUT_OF_RANGE | 0x1045 | Internal error. Data consistency was lost.
*** | 0x1046 | ***
*** | 0x1047 | ***
*** | 0x1048 | ***
HPDF_PAGES_MISSING_KIDS_ENTRY | 0x1049 | Internal error. Data consistency was lost.
HPDF_PAGE_CANNOT_FIND_OBJECT | 0x104A | Internal error. Data consistency was lost.
HPDF_PAGE_CANNOT_GET_ROOT_PAGES | 0x104B | Internal error. Data consistency was lost.
HPDF_PAGE_CANNOT_RESTORE_GSTATE | 0x104C | There are no graphics-states to be restored.
HPDF_PAGE_CANNOT_SET_PARENT | 0x104D | Internal error. Data consistency was lost.
HPDF_PAGE_FONT_NOT_FOUND | 0x104E | The current font is not set.
HPDF_PAGE_INVALID_FONT | 0x104F | An invalid font-handle was specified.
HPDF_PAGE_INVALID_FONT_SIZE | 0x1050 | An invalid font-size was set.
HPDF_PAGE_INVALID_GMODE | 0x1051 | See Graphics mode.
HPDF_PAGE_INVALID_INDEX | 0x1052 | Internal error. Data consistency was lost.
HPDF_PAGE_INVALID_ROTATE_VALUE | 0x1053 | Specified value is not multiple of 90.
HPDF_PAGE_INVALID_SIZE | 0x1054 | An invalid page-size was set.
HPDF_PAGE_INVALID_XOBJECT | 0x1055 | An invalid image-handle was set.
HPDF_PAGE_OUT_OF_RANGE | 0x1056 | The specified value is out of range.
HPDF_REAL_OUT_OF_RANGE | 0x1057 | The specified value is out of range.
HPDF_STREAM_EOF | 0x1058 | Unexpected EOF marker was detected.
HPDF_STREAM_READLN_CONTINUE | 0x1059 | Internal error. Data consistency was lost.
*** | 0x105A | ***
HPDF_STRING_OUT_OF_RANGE | 0x105B | The length of the text is too long.
HPDF_THIS_FUNC_WAS_SKIPPED | 0x105C | Function not executed because of other errors.
HPDF_TTF_CANNOT_EMBEDDING_FONT | 0x105D | Font cannot be embedded. (license restriction)
HPDF_TTF_INVALID_CMAP | 0x105E | Unsupported ttf format. (cannot find unicode cmap)
HPDF_TTF_INVALID_FOMAT | 0x105F | Unsupported ttf format.
HPDF_TTF_MISSING_TABLE | 0x1060 | Unsupported ttf format. (cannot find a necessary table)
HPDF_UNSUPPORTED_FONT_TYPE | 0x1061 | Internal error. Data consistency was lost.
HPDF_UNSUPPORTED_FUNC | 0x1062 | 1. Library not configured to use PNGLIB. 2. Internal error. Data consistency was lost.
HPDF_UNSUPPORTED_JPEG_FORMAT | 0x1063 | Unsupported JPEG format.
HPDF_UNSUPPORTED_TYPE1_FONT | 0x1064 | Failed to parse .PFB file.
HPDF_XREF_COUNT_ERR | 0x1065 | Internal error. Data consistency was lost.
HPDF_ZLIB_ERROR | 0x1066 | Error while executing ZLIB function.
HPDF_INVALID_PAGE_INDEX | 0x1067 | An invalid page index was passed.
HPDF_INVALID_URI | 0x1068 | An invalid URI was set.
HPDF_PAGELAYOUT_OUT_OF_RANGE | 0x1069 | An invalid page-layout was set.
*** | 0x106A | ***
*** | 0x106B | ***
*** | 0x106C | ***
*** | 0x106D | ***
*** | 0x106E | ***
*** | 0x106F | ***
HPDF_PAGEMODE_OUT_OF_RANGE | 0x1070 | An invalid page-mode was set.
HPDF_PAGENUM_STYLE_OUT_OF_RANGE | 0x1071 | An invalid page-num-style was set.
HPDF_ANNOT_INVALID_ICON | 0x1072 | An invalid icon was set.
HPDF_ANNOT_INVALID_BORDER_STYLE | 0x1073 | An invalid border-style was set.
HPDF_PAGE_INVALID_DIRECTION | 0x1074 | An invalid page-direction was set.
HPDF_INVALID_FONT | 0x1075 | An invalid font-handle was specified.

Retrieved from "http://daylessday../../../../articles/d/o/c/Documentation_Error_handling_b6cd.html"

##### Views

- Page
- Discussion
- View source
- History

##### Personal tools

- Log in

##### Search

##### Toolbox

- What links here
- Related changes
- Special pages
- Printable version
- Permanent link