Haru Free PDF Library

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.