home | download | documentation | examples | sourceforge | forums

## Error Handling

### The type of functions

There are three kind of functions in Haru.

| The type of function | Retuen value when an error occurred
1 | The function whose type of return parameter is HPDF_STATUS | It returns the code of error
2 | The function which returns the value | It returns the initial value
3 | The function which retruns the handle of object | It return NULL

When an error has occurred, an above return value is returned, and an error code is set to the document object.
You can get an error code by invoking HPDF_GetError().
In addition, there are some functions which set a detailed error-code with an error-code. The detailed error-code can be refered by invoking HPDF_GetErrorDetail().
However, when the first parameter of a function is invalid, the error-code is not set (because the function cannot find a document object that the error-code should be set).
When a user-defined error function was set, the function is invoked after an error-code is set.
Note:
Once an error code is set, invoking some IO processing functions are blocked. An application have to invoke HPDF_ResetError() to resume program.

### User-defined error handler

You can use user-defined error handler which is invoked when an error occurred.
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 shared library in Windows environment, The definition 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.
1. The typical usage of error handler on C
C language does not support an exception feature, but with emulating an exception handling by using setjmp/longjmp macro, the error handling becomes simple.
void
error_handler (HPDF_STATUS error_no,
HPDF_STATUS detail_no,
void *user_data)
{
/* invoke longjmp() when an error has occurred */
printf ("ERROR: error_no=%04X, detail_no=%d\n", (unsigned int)error_no,
(int)detail_no);
longjmp(env, 1);
}
int main ()
{
/* set error-handler when creating a PDF_Doc object */
HPDF_Doc pdf;
pdf = HPDF_New (error_handler, NULL);
if (!pdf) {
printf ("error: cannot create PdfDoc object\n");
return 1;
}
if (setjmp(env)) {
HPDF_Free (pdf);
return 1;
}
/* do page description processes
* (we do not have to check the return code of functions)
*/
/* save the document to a file */
HPDF_SaveToFile (pdf, fname);
/* clean up */
HPDF_Free (pdf);
return 0;
}
2. The typical usage of error handler on C++
C++ supports an exception feature. 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)
{
/* throw exception when an error has occured */
printf ("ERROR: error_no=%04X, detail_no=%d\n", (unsigned int)error_no,
(int)detail_no);
throw std::exception ();
}
int main ()
{
/* set error-handler when creating a PDF_Doc object */
HPDF_Doc pdf = HPDF_New (error_handler, NULL);
if (!pdf) {
printf ("error: cannot create PdfDoc object\n");
return 1;
}
try {
/* do page description processes
* (we do not have to check the return code of functions)
*/
/* save the document to a file */
HPDF_SaveToFile (pdf, fname);
} catch (...) {
HPDF_Free (pdf);
return 1;
}
/* clean up */
HPDF_Free (pdf);
return 0;
}
}
3. Other programing languages
In the case of languages supporting an exception handling, you can handle an error in a similar way. In the case of the languages which does not support an exception handling, you have to check return code after invoking functions.
There are wrapper programs for Ruby,Delphi and C# in "if" directory. Refer these source-code.

### Finalization and cleanup

Do not forget to invoke HPDF_Free() in any case.
As a result, it is guaranteed that the allocated memory is surely freed.

### List of error code

| Name | Value | Description
1 | HPDF_ARRAY_COUNT_ERR | 0x1001 | Internal error. The consistency of the data was lost.
2 | HPDF_ARRAY_ITEM_NOT_FOUND | 0x1002 | Internal error. The consistency of the data was lost.
3 | HPDF_ARRAY_ITEM_UNEXPECTED_TYPE | 0x1003 | Internal error. The consistency of the data was lost.
4 | HPDF_BINARY_LENGTH_ERR | 0x1004 | The length of the data exceeds HPDF_LIMIT_MAX_STRING_LEN.
5 | HPDF_CANNOT_GET_PALLET | 0x1005 | Cannot get a pallet data from PNG image.
6 |  | 0x1006 |
7 | HPDF_DICT_COUNT_ERR | 0x1007 | The count of elements of a dictionary exceeds HPDF_LIMIT_MAX_DICT_ELEMENT
8 | HPDF_DICT_ITEM_NOT_FOUND | 0x1008 | Internal error. The consistency of the data was lost.
9 | HPDF_DICT_ITEM_UNEXPECTED_TYPE | 0x1009 | Internal error. The consistency of the data was lost.
10 | HPDF_DICT_STREAM_LENGTH_NOT_FOUND | 0x100A | Internal error. The consistency of the data was lost.
11 | HPDF_DOC_ENCRYPTDICT_NOT_FOUND | 0x100B | HPDF_SetPermission() OR HPDF_SetEncryptMode() was called before a password is set.
12 | HPDF_DOC_INVALID_OBJECT | 0x100C | Internal error. The consistency of the data was lost.
13 |  | 0x100D |
14 | HPDF_DUPLICATE_REGISTRATION | 0x100E | Tried to register a font that has been registered.
15 | HPDF_EXCEED_JWW_CODE_NUM_LIMIT | 0x100F | Cannot register a character to the japanese word wrap characters list.
16 |  | 0x1010 |
17 | HPDF_ENCRYPT_INVALID_PASSWORD | 0x1011 | Tried to set the owner password to NULL. The owner password and user password is the same.
18 | HPDF_ERR_UNKNOWN_CLASS | 0x1013 | Internal error. The consistency of the data was lost.
19 | HPDF_EXCEED_GSTATE_LIMIT | 0x1014 | The depth of the stack exceeded HPDF_LIMIT_MAX_GSTATE.
20 | HPDF_FAILD_TO_ALLOC_MEM | 0x1015 | Memory allocation failed.
21 | HPDF_FILE_IO_ERROR | 0x1016 | File processing failed. (A detailed code is set.)
22 | HPDF_FILE_OPEN_ERROR | 0x1017 | Cannot open a file. (A detailed code is set.)
23 |  | 0x1018 |
24 | HPDF_FONT_EXISTS | 0x1019 | Tried to load a font that has been registered.
25 | HPDF_FONT_INVALID_WIDTHS_TABLE | 0x101A | The format of a font-file is invalid . Internal error. The consistency of the data was lost.
26 | HPDF_INVALID_AFM_HEADER | 0x101B | Cannot recognize a header of an afm file.
27 | HPDF_INVALID_ANNOTATION | 0x101C | The specified annotation handle is invalid.
28 |  | 0x101D |
29 | HPDF_INVALID_BIT_PER_COMPONENT | 0x101E | Bit-per-component of a image which was set as mask-image is invalid.
30 | HPDF_INVALID_CHAR_MATRICS_DATA | 0x101F | Cannot recognize char-matrics-data of an afm file.
31 | HPDF_INVALID_COLOR_SPACE | 0x1020 | 1. The color_space parameter of HPDF_LoadRawImage is invalid. 2. Color-space of a image which was set as mask-image is invalid. 3. The function which is invalid in the present color-space was invoked.
32 | HPDF_INVALID_COMPRESSION_MODE | 0x1021 | Invalid value was set when invoking HPDF_SetCommpressionMode().
33 | HPDF_INVALID_DATE_TIME | 0x1022 | An invalid date-time value was set.
34 | HPDF_INVALID_DESTINATION | 0x1023 | An invalid destination handle was set.
35 |  | 0x1024 |
36 | HPDF_INVALID_DOCUMENT | 0x1025 | An invalid document handle is set.
37 | HPDF_INVALID_DOCUMENT_STATE | 0x1026 | The function which is invalid in the present state was invoked.
38 | HPDF_INVALID_ENCODER | 0x1027 | An invalid encoder handle is set.
39 | HPDF_INVALID_ENCODER_TYPE | 0x1028 | A combination between font and encoder is wrong.
40 |  | 0x1029 |
41 |  | 0x102A |
42 | HPDF_INVALID_ENCODING_NAME | 0x102B | An Invalid encoding name is specified.
43 | HPDF_INVALID_ENCRYPT_KEY_LEN | 0x102C | The lengh of the key of encryption is invalid.
44 | HPDF_INVALID_FONTDEF_DATA | 0x102D | 1. An invalid font handle was set. 2. Unsupported font format.
45 | HPDF_INVALID_FONTDEF_TYPE | 0x102E | Internal error. The consistency of the data was lost.
46 | HPDF_INVALID_FONT_NAME | 0x102F | A font which has the specified name is not found.
47 | HPDF_INVALID_IMAGE | 0x1030 | Unsupported image format.
48 | HPDF_INVALID_JPEG_DATA | 0x1031 | Unsupported image format.
49 | HPDF_INVALID_N_DATA | 0x1032 | Cannot read a postscript-name from an afm file.
50 | HPDF_INVALID_OBJECT | 0x1033 | 1. An invalid object is set. 2. Internal error. The consistency of the data was lost.
51 | HPDF_INVALID_OBJ_ID | 0x1034 | Internal error. The consistency of the data was lost.
52 | HPDF_INVALID_OPERATION | 0x1035 | 1. Invoked HPDF_Image_SetColorMask() against the image-object which was set a mask-image.
53 | HPDF_INVALID_OUTLINE | 0x1036 | An invalid outline-handle was specified.
54 | HPDF_INVALID_PAGE | 0x1037 | An invalid page-handle was specified.
55 | HPDF_INVALID_PAGES | 0x1038 | An invalid pages-handle was specified. (internel error)
56 | HPDF_INVALID_PARAMETER | 0x1039 | An invalid value is set.
57 |  | 0x103A |
58 | HPDF_INVALID_PNG_IMAGE | 0x103B | Invalid PNG image format.
59 | HPDF_INVALID_STREAM | 0x103C | Internal error. The consistency of the data was lost.
60 | HPDF_MISSING_FILE_NAME_ENTRY | 0x103D | Internal error. The "_FILE_NAME" entry for delayed loading is missing.
61 |  | 0x103E |
62 | HPDF_INVALID_TTC_FILE | 0x103F | Invalid .TTC file format.
63 | HPDF_INVALID_TTC_INDEX | 0x1040 | The index parameter was exceed the number of included fonts
64 | HPDF_INVALID_WX_DATA | 0x1041 | Cannot read a width-data from an afm file.
65 | HPDF_ITEM_NOT_FOUND | 0x1042 | Internal error. The consistency of the data was lost.
66 | HPDF_LIBPNG_ERROR | 0x1043 | An error has returned from PNGLIB while loading an image.
67 | HPDF_NAME_INVALID_VALUE | 0x1044 | Internal error. The consistency of the data was lost.
68 | HPDF_NAME_OUT_OF_RANGE | 0x1045 | Internal error. The consistency of the data was lost.
69 |  | 0x1046 |
70 |  | 0x1047 |
71 |  | 0x1048 |
72 | HPDF_PAGES_MISSING_KIDS_ENTRY | 0x1049 | Internal error. The consistency of the data was lost.
73 | HPDF_PAGE_CANNOT_FIND_OBJECT | 0x104A | Internal error. The consistency of the data was lost.
74 | HPDF_PAGE_CANNOT_GET_ROOT_PAGES | 0x104B | Internal error. The consistency of the data was lost.
75 | HPDF_PAGE_CANNOT_RESTORE_GSTATE | 0x104C | There are no graphics-states to be restored.
76 | HPDF_PAGE_CANNOT_SET_PARENT | 0x104D | Internal error. The consistency of the data was lost.
77 | HPDF_PAGE_FONT_NOT_FOUND | 0x104E | The current font is not set.
78 | HPDF_PAGE_INVALID_FONT | 0x104F | An invalid font-handle was spacified.
79 | HPDF_PAGE_INVALID_FONT_SIZE | 0x1050 | An invalid font-size was set.
80 | HPDF_PAGE_INVALID_GMODE | 0x1051 | See Graphics mode.
81 | HPDF_PAGE_INVALID_INDEX | 0x1052 | Internal error. The consistency of the data was lost.
82 | HPDF_PAGE_INVALID_ROTATE_VALUE | 0x1053 | The specified value is not a multiple of 90.
83 | HPDF_PAGE_INVALID_SIZE | 0x1054 | An invalid page-size was set.
84 | HPDF_PAGE_INVALID_XOBJECT | 0x1055 | An invalid image-handle was set.
85 | HPDF_PAGE_OUT_OF_RANGE | 0x1056 | The specified value is out of range.
86 | HPDF_REAL_OUT_OF_RANGE | 0x1057 | The specified value is out of range.
87 | HPDF_STREAM_EOF | 0x1058 | Unexpected EOF marker was detected.
88 | HPDF_STREAM_READLN_CONTINUE | 0x1059 | Internal error. The consistency of the data was lost.
89 |  | 0x105A |
90 | HPDF_STRING_OUT_OF_RANGE | 0x105B | The length of the specified text is too long.
91 | HPDF_THIS_FUNC_WAS_SKIPPED | 0x105C | The execution of a function was skipped because of other errors.
92 | HPDF_TTF_CANNOT_EMBEDDING_FONT | 0x105D | This font cannot be embedded. (restricted by license)
93 | HPDF_TTF_INVALID_CMAP | 0x105E | Unsupported ttf format. (cannot find unicode cmap.)
94 | HPDF_TTF_INVALID_FOMAT | 0x105F | Unsupported ttf format.
95 | HPDF_TTF_MISSING_TABLE | 0x1060 | Unsupported ttf format. (cannot find a necessary table)
96 | HPDF_UNSUPPORTED_FONT_TYPE | 0x1061 | Internal error. The consistency of the data was lost.
97 | HPDF_UNSUPPORTED_FUNC | 0x1062 | 1. The library is not configured to use PNGLIB. 2. Internal error. The consistency of the data was lost.
98 | HPDF_UNSUPPORTED_JPEG_FORMAT | 0x1063 | Unsupported Jpeg format.
99 | HPDF_UNSUPPORTED_TYPE1_FONT | 0x1064 | Failed to parse .PFB file.
100 | HPDF_XREF_COUNT_ERR | 0x1065 | Internal error. The consistency of the data was lost.
101 | HPDF_ZLIB_ERROR | 0x1066 | An error has occurred while executing a function of Zlib.
102 | HPDF_INVALID_PAGE_INDEX | 0x1067 | An error returned from Zlib.
103 | HPDF_INVALID_URI | 0x1068 | An invalid URI was set.
104 | HPDF_PAGELAYOUT_OUT_OF_RANGE | 0x1069 | An invalid page-layout was set.
105 | HPDF_PAGEMODE_OUT_OF_RANGE | 0x1070 | An invalid page-mode was set.
106 | HPDF_PAGENUM_STYLE_OUT_OF_RANGE | 0x1071 | An invalid page-num-style was set.
107 | HPDF_ANNOT_INVALID_ICON | 0x1072 | An invalid icon was set.
108 | HPDF_ANNOT_INVALID_BORDER_STYLE | 0x1073 | An invalid border-style was set.
109 | HPDF_PAGE_INVALID_DIRECTION | 0x1074 | An invalid page-direction was set.
110 | HPDF_INVALID_FONT | 0x1075 | An invalid font-handle was specified.