-
Notifications
You must be signed in to change notification settings - Fork 2
API: Document
HPDF_Doc HPDF_New (HPDF_Error_Handler user_error_fn,
void *user_data);
HPDF_Doc HPDF_NewEx (HPDF_Error_Handler user_error_fn,
HPDF_Alloc_Func user_alloc_fn,
HPDF_Free_Func user_free_fn,
HPDF_UINT mem_pool_buf_size,
void *user_data);
Description
HPDF_New() and HPDF_NewEx() create an instance of a document object and initialize it.
Parameters
user_error_fn - User-defined error handler which is invoked when an error occurred.
user_alloc_fn - User-defined memory allocation function. If NULL is specified, malloc() is used.
user_free_fn - User-defined memory freeing function. If NULL is specified, free() is used.
mem_pool_buf_size - libHaru does not use memory pool by default. A memory allocation function is called on demand from an application. If this parameter set to non-zero value, memory management will be done as following.
- Memory is allocated per mem_pool_buf_size.
- Memory manager gives memory of requested size to an application, and pools remaining memory to use at next request.
- If the size of requested memory is larger than the remaining memory, a new memory block is allocated.
- Unused memory is not released immediately. It is released all together when HPDF_Free() is invoked.
Return Value
HPDF_New() and HPDF_NewEx() return a handle of document object on success and NULL on failure.
See Also
HPDF_Free()
void HPDF_Free (HPDF_Doc pdf);
Description
HPDF_Free() revokes a document object and all resources.
Parameters
pdf - The handle of a document object.
See Also
HDPF_New ()
HPDF_STATUS HPDF_NewDoc (HPDF_Doc pdf);
Description
HPDF_NewDoc() creates a new document. If HPDF_Doc object already has a document, the current document is revoked.
Parameters
pdf - The handle of a document object.
Return Value
HPDF_NewDoc () returns HPDF_OK on success. Otherwise, it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - Invalid document handle set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
HPDF_FreeDoc ()
void HPDF_FreeDoc (HPDF_Doc pdf); void HPDF_FreeDocAll (HPDF_Doc pdf);
Description
HPDF_FreeDoc() and HPDF_FreeDocAll() revoke the current document.
HPDF_FreeDoc() keeps and recycles loaded resources (such as fonts and encodings) when new document requires these resources.
HPDF_FreeDocAll() revokes the current document and all resources.
Parameters
pdf - The handle of a document object.
See Also
HDPF_NewDoc()
HPDF_STATUS HPDF_SaveToFile (HPDF_Doc pdf,
const char *file_name);
Description
HPDF_SaveToFile() saves the current document to a file.
Parameters
pdf - The handle of a document object.
file_name - The name of file to save.
Return Value
Returns HPDF_OK on success, otherwise it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_FILE_IO_ERROR - An error occurred while processing file I/O.
HPDF_STATUS HPDF_SaveToStream (HPDF_Doc pdf);
Description
HPDF_SaveToStream() saves the current document to a temporary stream of a document object.
Parameters
pdf - The handle of a document object.
Return Value
When HPDF_SaveToStream() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory Allocation Failed.
HPDF_UINT32 HPDF_GetStreamSize (HPDF_Doc pdf);
Description
HPDF_GetStreamSize() gets the size of the temporary stream of the document.
Parameters
pdf - The handle of a document object.
Return Value
When HPDF_GetStreamSize() succeeds, it returns the size of the temporary stream. Otherwise, it returns 0.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
HPDF_STATUS HPDF_ReadFromStream (HPDF_Doc pdf,
HPDF_BYTE *buf,
HPDF_UINT32 *size);
Description
HPDF_ReadFromStream() copies the data from the temporary stream of the document into buffer "buf".
Parameters
pdf - The handle of a document object.
buf - Pointer to the buffer.
size - The size of buffer.
After HPDF_ReadFromStream() is executed, the number of bytes read is set into "size".
Return Value
When HPDF_ReadFromStream() succeeds, it returns HPDF_OK or HPDF_STREAM_EOF. Otherwise, it returns error-code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
- HPDF_INVALID_OPERATION - No data is saved to the temporary stream of the document.
- HPDF_INVALID_PARAMETER - An invalid value was set to size parameter.
HPDF_STATUS HPDF_ResetStream (HPDF_Doc pdf);
Description
HPDF_ResetStream() rewinds the temporary stream of the document.
Parameters
pdf - The handle of a document object.
Return Value
When HPDF_ResetStream() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
- HPDF_INVALID_OPERATION - No data is saved to the temporary stream of the document.
HPDF_BOOL HPDF_HasDoc (HPDF_Doc pdf);
Description
Parameters
pdf - The handle of a document object.
Return Value
If the specified document handle is valid, it returns HPDF_TRUE. Otherwise, it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
HPDF_STATUS HPDF_SetErrorHandler (HPDF_Doc pdf,
HPDF_Error_Handler user_error_fn);
Description
HPDF_SetErrorHandler() sets a user-defined error handler. If a function call fails, the error handler is called.
Parameters
pdf - The handle of a document object.
user_error_fn - User-defined error handler. If NULL, the error-handler which has been set is revoked.
Return Value
When HPDF_SaveToFile() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
HPDF_STATUS HPDF_GetError (HPDF_Doc pdf);
Description
HPDF_GetError returns the last error code of specified document object.
Parameters
pdf - The handle of a document object.
Return Value
Returns the last error code of document object, or HPDF_OK if no last error.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
void HPDF_ResetError (HPDF_Doc pdf);
Description
Once an error code is set, IO processing functions cannot be invoked. In the case of executing a function after the cause of the error is fixed, an application have to invoke HPDF_ResetError to clear error-code before executing functions.
Parameters
pdf - The handle of a document object.
HPDF_STATUS HPDF_SetPagesConfiguration (HPDF_Doc pdf, HPDF_UINT page_per_pages);
Description
In the default setting, a HPDF_Doc object has one "Pages" object as root of pages. All "Page" objects are created as a kid of the "Pages" object. Since a "Pages" object can own only 8191 kids objects, the maximum number of pages are 8191 page. Additionally, the state that there are a lot of "Page" object under one "Pages" object is not good, because it causes performance degradation of a viewer application.
An application can change the setting of a pages tree by invoking HPDF_SetPagesConfiguration(). If page_per_pages parameter is set to more than zero, a two-tier pages tree is created. A root "Pages" object can own 8191 "Pages" object, and each lower "Pages" object can own page_per_pages "Page" objects. As a result, the maximum number of pages becomes 8191 * page_per_pages page. An application cannot invoke HPDF_SetPageConfiguration() after a page is added to document.
Parameters
pdf - The handle of a document object.
page_per_pages - Specify the numbers of pages that a "Pages" object can own.
Return Value
When HPDF_SetPageConfiguration() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
- HPDF_INVALID_DOCUMENT_STATE - A page object already exists in a document.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
HPDF_STATUS HPDF_SetPageLayout (HPDF_Doc pdf,
HPDF_PageLayout layout);
Description
HPDF_SetPageLayout() sets how the page should be displayed. If this attribute is not set, the setting of the viewer application is used.
Parameters
pdf - The handle of a document object.
layout - One of the following values:
- HPDF_PAGE_LAYOUT_SINGLE - Only one page is displayed.
- HPDF_PAGE_LAYOUT_ONE_COLUMN - Display the pages in one column.
- HPDF_PAGE_LAYOUT_TWO_COLUMN_LEFT - Display in two columns. Odd page number is displayed left.
- HPDF_PAGE_LAYOUT_TWO_COLUMN_RIGHT - Display in two columns. Odd page number is displayed right.
When HPDF_SetPageLayout() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_PAGE_LAYOUT_OUT_OF_RANGE - An invalid page layout is specified.
HPDF_PageLayout HPDF_GetPageLayout (HPDF_Doc pdf);
Description
HPDF_GetPageLayout() returns the current setting for page layout.
Parameters
pdf - The handle of a document object.
Return Value
When HPDF_GetPageLayout() succeeds, it returns the current setting for page layout. If page layout is not set, it returns HPDF_PAGE_LAYOUT_EOF.
HPDF_STATUS HPDF_SetPageMode (HPDF_Doc pdf,
HPDF_PageMode mode);
Description
HPDF_SetPageMode() sets how the document should be displayed.
Parameters
pdf - The handle of a document object.
mode - The following values are available.
- HPDF_PAGE_MODE_USE_NONE - Display the document with neither outline nor thumbnail.
- HPDF_PAGE_MODE_USE_OUTLINE - Display the document with outline pane.
- HPDF_PAGE_MODE_USE_THUMBS - Display the document with thumbnail pane.
- HPDF_PAGE_MODE_FULL_SCREEN - Display the document with full screen mode.
When HPDF_SetPageMode() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle is set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_PAGE_MODE_OUT_OF_RANGE - An invalid page mode is specified.
HPDF_PageMode HPDF_GetPageMode (HPDF_Doc pdf);
Description
HPDF_GetPageLayout() returns the current setting for page mode.
Parameters
pdf - The handle of a document object.
Return Value
When HPDF_GetPageMode() succeeds, it returns the current setting for page mode.
HPDF_STATUS HPDF_SetOpenAction (HPDF_Doc pdf,
HPDF_Destination open_action);
Description
HPDF_SetOpenAction() set the first page to appear when a document is opened.
Parameters
pdf - The handle of a document object.
open_action - Set a valid destination object.
Return Value
When HPDF_SetOpenAction() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_DESTINATION - An invalid destination object was set.
HPDF_Page HPDF_GetCurrentPage (HPDF_Doc pdf);
Description
HPDF_GetPageLayout() returns the handle of current page object.
Parameters
pdf - The handle of a document object.
Return Value
When HPDF_GetPageLayout() succeeds, it returns the handle of a current page object. Otherwise it returns NULL.
HPDF_Page HPDF_AddPage (HPDF_Doc pdf);
Description
HPDF_AddPage() creates a new page and adds it after the last page of a document.
Parameters
pdf - The handle of a document object.
Return Value
HPDF_AddPage() returns the handle of created page object on success. Otherwise, it returns error-code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
HPDF_Page HPDF_InsertPage (HPDF_Doc pdf, HPDF_Page target);
Description
HPDF_InsertPage() creates a new page and inserts it just before the specified page.
Parameters
pdf - The handle of a document object.
page - The handle of a page object. Insert new page just before.
Return Value
HPDF_InsertPage() returns the handle of created page object on success. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_PAGE - An invalid page handle was set.
HPDF_STATUS HPDF_AddPageLabel (HPDF_Doc pdf,
HPDF_UINT page_num,
HPDF_PageNumStyle style,
HPDF_UINT first_page,
const char *prefix);
Description
HPDF_AddPageLabel() adds a page labeling range for the document.
The page label is shown in the thumbnails view.
Parameters
pdf - The handle of a document object.
page_num - The first page that applies this labeling range.
style - One of the following numbering styles:
- HPDF_PAGE_NUM_STYLE_DECIMAL - Arabic numerals (1 2 3 4).
- HPDF_PAGE_NUM_STYLE_UPPER_ROMAN - Uppercase roman numerals (I II III IV).
- HPDF_PAGE_NUM_STYLE_LOWER_ROMAN - Lowercase roman numerals (i ii iii iv).
- HPDF_PAGE_NUM_STYLE_UPPER_LETTERS - Uppercase letters (A B C D).
- HPDF_PAGE_NUM_STYLE_LOWER_LETTERS - Lowercase letters (a b c d).
prefix - The prefix for the page label. (NULL is allowed.)
Return Value
When HPDF_AddPageLabel () succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_PAGE_NUM_STYLE_OUT_OF_RANGE - An invalid page numbering style is specified.
HPDF_AddPageLabel(pdf, 0, HPDF_PAGE_NUM_STYLE_LOWER_ROMAN, 1, ""); HPDF_AddPageLabel(pdf, 4, HPDF_PAGE_NUM_STYLE_DECIMAL, 1, ""); HPDF_AddPageLabel(pdf, 7, HPDF_PAGE_NUM_STYLE_DECIMAL, 8, "A-");
Result in a document with pages labeled :
i, ii, iii, iv, 1, 2, 3, A-8, A-9, ...
HPDF_Font HPDF_GetFont (HPDF_Doc pdf,
const char *font_name,
const char *encoding_name);
Description
HPDF_GetFont gets the handle of a requested font object.
Parameters
pdf - The handle of a document object.
font_name - A valid font name. (See "Fonts and Encodings")
encoding_name - A valid encoding name. (See "Fonts and Encodings")
Return Value
When HPDF_GetFont() succeeds, it returns the handle of a font object. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_INVALID_FONT_NAME - An invalid font name was set.
- HPDF_INVALID_ENCODING_NAME - An invalid encoding name was set.
- HPDF_UNSUPPORTED_FONT_TYPE - An unsupported font type was set.
const char* HPDF_LoadType1FontFromFile (HPDF_Doc pdf,
const char *afmfilename,
const char *pfmfilename);
Description
HPDF_LoadType1FontFromFile() loads a Type1 font from an external file and registers it in the document object. (See "Fonts and Encodings")
Parameters
pdf - The handle of a document object.
afm_file_name - A path of an AFM file.
data_file_name - A path of a PFA/PFB file. If NULL, the glyph data of font file is not embedded to a PDF file.
Return Value
When HPDF_LoadType1FontFromFile() succeeds, it returns the name of a font. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_FONT_EXISTS - The font of the same name has already been registered.
- HPDF_INVALID_AFM_HEADER, HPDF_INVALID_CHAR_MATRICS_DATA, HPDF_INVALID_N_DATA - Cannot recognize AFM file.
- HPDF_UNSUPPORTED_TYPE1_FONT - Cannot recognize PFA/PFB file.
const char* HPDF_LoadTTFontFromFile (HPDF_Doc pdf,
const char *file_name,
HPDF_BOOL embedding);
Description
HPDF_LoadTTFontFromFile() loads a TrueType font from an external file and register it to a document object. (See "Fonts and Encodings")
Parameters
pdf - The handle of a document object.
file_name - A path of a TrueType font file (.ttf).
embedding - If this parameter is set to HPDF_TRUE, the glyph data of the font is embedded, otherwise only the matrix data is included in PDF file.
Return Value
When HPDF_LoadTTFontFromFile() succeeds, it returns the name of a font. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_FONT_EXISTS - The font of the same name has already been registered.
- HPDF_INVALID_TTC_INDEX - Failed to load .ttf file.
- HPDF_INVALID_TTC_FILE - Failed to load .ttf file.
- HPDF_TTF_INVALID_CMAP - Failed to load .ttf file.
- HPDF_TTF_INVALID_FOMAT - Failed to load .ttf file.
- HPDF_TTF_MISSING_TABLE - Failed to load .ttf file.
- HPDF_TTF_CANNOT_EMBEDDING_FONT - The font is not allowed to embed.
HPDF_STATUS HPDF_LoadTTFontFromFile2 (HPDF_Doc pdf,
const char *file_name,
HPDF_UINT index,
HPDF_BOOL embedding);
Description
HPDF_LoadTTFontFromFile2() loads a TrueType font from an TrueType collection file and register it to a document object. (See "Fonts and Encodings")
Parameters
pdf - The handle of a document object.
file_name - A path of a TrueType font collection file (.ttc).
index - The index of font to be loaded.
embedding - If HPDF_TRUE, the font glyph data is embedded, otherwise only the matrix data is included in PDF file.
Return Value
When HPDF_LoadTTFontFromFile2() succeeds, it returns the name of a font. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_FONT_EXISTS - The font of the same name has already been registered.
- HPDF_INVALID_TTC_INDEX, HPDF_INVALID_TTC_FILE, HPDF_TTF_INVALID_CMAP, HPDF_TTF_INVALID_FOMAT, HPDF_TTF_MISSING_TABLE - Failed to load .ttf file.
- HPDF_TTF_CANNOT_EMBEDDING_FONT - The font is not allowed to embed.
- HPDF_INVALID_TTC_INDEX - The value specified at index parameter exceeds the number of fonts.
HPDF_STATUS HPDF_UseJPFonts (HPDF_Doc pdf);
Description
HPDF_UseJPFonts() enables Japanese fonts. After HPDF_UseJPFonts() is involed, an application can use the following Japanese fonts.
- MS-Mincyo
- MS-Mincyo,Bold
- MS-Mincyo,Italic
- MS-Mincyo,BoldItalic
- MS-Gothic
- MS-Gothic,Bold
- MS-Gothic,Italic
- MS-Gothic,BoldItalic
- MS-PMincyo
- MS-PMincyo,Bold
- MS-PMincyo,Italic
- MS-PMincyo,BoldItalic
- MS-PGothic
- MS-PGothic,Bold
- MS-PGothic,Italic
- MS-PGothic,BoldItalic
pdf - The handle of a document object.
Return Value
When HPDF_UseJPFonts() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_DUPLICATE_REGISTRATION - The font of the same name has already been registered.
HPDF_STATUS HPDF_UseKRFonts (HPDF_Doc pdf);
Description
HPDF_UseKRFonts() enables Korean fonts. After HPDF_UseKRFonts() is involed, an application can use the following Korean fonts.
- DotumChe
- DotumChe,Bold
- DotumChe,Italic
- DotumChe,BoldItalic
- Dotum
- Dotum,Bold
- Dotum,Italic
- Dotum,BoldItalic
- BatangChe
- BatangChe,Bold
- BatangChe,Italic
- BatangChe,BoldItalic
- Batang
- Batang,Bold
- Batang,Italic
- Batang,BoldItalic
pdf - The handle of a document object.
Return Value
When HPDF_UseKRFonts() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_DUPLICATE_REGISTRATION - The font of the same name has already been registered.
HPDF_STATUS HPDF_UseCNSFonts (HPDF_Doc pdf);
Description
HPDF_UseCNSFonts() enables simplified Chinese fonts. After HPDF_UseCNSFonts() is involed, an application can use the following simplified Chinese fonts.
- SimSun
- SimSun,Bold
- SimSun,Italic
- SimSun,BoldItalic
- SimHei
- SimHei,Bold
- SimHei,Italic
- SimHei,BoldItalic
pdf - The handle of a document object.
Return Value
When HPDF_UseCNSFonts() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_DUPLICATE_REGISTRATION - The font of the same name has already been registered.
HPDF_STATUS HPDF_UseCNTFonts (HPDF_Doc pdf);
Description
HPDF_UseCNTFonts() enables traditional Chinese fonts. After HPDF_UseCNTFonts() is involed, an application can use the following traditional Chinese fonts.
- MingLiU
- MingLiU,Bold
- MingLiU,Italic
- MingLiU,BoldItalic
pdf - The handle of a document object.
Return Value
When HPDF_UseCNSFonts() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_DUPLICATE_REGISTRATION - The font of the same name has already been registered.
HPDF_Encoder HPDF_GetEncoder (HPDF_Doc pdf,
const char *encoding_name);
Description
HPDF_GetEncoder() gets the handle of an encoder object by specified encoding name.
Parameters
pdf - The handle of a document object.
encoding_name - A valid encoding name. (See Documentation/Encodings)
Return Value
When HPDF_GetEncoder() succeeds, it returns the handle of an encoder object. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_ENCODING_NAME - An invalid encoding name was set.
HPDF_Encoder HPDF_GetCurrentEncoder (HPDF_Doc pdf);
Description
HPDF_GetCurrentEncoder() gets the handle of the current encoder of the document object. The current encoder is set by invoking HPDF_SetCurrentEncoder() and it is used to processing a text when an application invoks HPDF_Info_SetInfoAttr(). The default value of it is NULL.
Parameters
pdf - A handle of a document object.
Return Value
It returns a handle of an encoder object or NULL.
HPDF_STATUS HPDF_SetCurrentEncoder (HPDF_Doc pdf,
const char *encoding_name);
Description
HPDF_SetCurrentEncoder() sets the current encoder for the document.
Parameters
pdf - The handle of a document object.
encoding_name - The name of an encoding. (See Documentation/Encodings)
Return Value
When HPDF_SetCurrentEncoder() succeeds, it returns the handle of created outline object. Otherwise, it returns NULL and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_ENCODING_NAME - An invalid encoding name was set.
HPDF_STATUS HPDF_UseJPEncodings (HPDF_Doc pdf);
Description
HPDF_UseJPEncodings() enables Japanese encodings. After HPDF_UseJPEncodings() is invoked, an application can use the following Japanese encodings.
- 90ms-RKSJ-H
- 90ms-RKSJ-V
- 90msp-RKSJ-H
- EUC-H
- EUC-V
pdf - The handle of a document object.
Return Value
When HPDF_UseJPEncodings() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_DUPLICATE_REGISTRATION - The encoding of the same name has already been registered.
HPDF_STATUS HPDF_UseKREncodings (HPDF_Doc pdf);
Description
HPDF_UseKREncodings() enables Korean encodings. After HPDF_UseKREncodings() is involed, an application can use the following Korean encodings.
- KSC-EUC-H
- KSC-EUC-V
- KSCms-UHC-H
- KSCms-UHC-HW-H
- KSCms-UHC-HW-V
pdf - The handle of a document object.
Return Value
When HPDF_UseKREncodings() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_DUPLICATE_REGISTRATION - The encodingof the same name has already been registered.
HPDF_STATUS HPDF_UseCNSEncodings (HPDF_Doc pdf);
Description
HPDF_UseCNSEncodings() enables simplified Chinese encodings. After HPDF_UseCNSEncodings() is involed, an application can use the following simplified Chinese encodings.
- GB-EUC-H
- GB-EUC-V
- GBK-EUC-H
- GBK-EUC-V
pdf - The handle of a document object.
Return Value
When HPDF_UseCNSEncodings() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_DUPLICATE_REGISTRATION - The encoding of the same name has already been registered.
HPDF_STATUS HPDF_UseCNTEncodings (HPDF_Doc pdf);
Description
HPDF_UseCNTEncodings() enables traditional Chinese encodings. After HPDF_UseCNTEncodings() is involed, an application can use the following traditional Chinese encodings.
- GB-EUC-H
- GB-EUC-V
- GBK-EUC-H
- GBK-EUC-V
pdf - The handle of a document object.
Return Value
When HPDF_UseCNTEncodings() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_DUPLICATE_REGISTRATION - The encoding of the same name has already been registered.
HPDF_STATUS HPDF_UseUTFEncodings (HPDF_Doc pdf);
Description
HPDF_UseUTFEncodings() enables UTF-8 encodings. After HPDF_UseUTFEncodings() is invoked, an application can include UTF-8 encoded Unicode text (up to 3-byte UTF-8 sequences only). An application can use the following Unicode encodings (but only with TrueType fonts):
- UTF-8
pdf - The handle of a document object.
Return Value
When HPDF_UseUTFEncodings() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_DUPLICATE_REGISTRATION - The encoding of the same name has already been registered.
HPDF_Outline HPDF_CreateOutline (HPDF_Doc pdf,
HPDF_Outline parent,
const char *title,
HPDF_Encoder encoder);
Description
HPDF_CreateOutline() creates a new outline object.
Parameters
pdf - The handle of a document object.
parent - The handle of an outline object which comes to the parent of the created outline object.
If NULL, the outline is created as a root outline.
title - The caption of the outline object.
encoder - The handle of an encoding object applied to the title. If NULL, PDFDocEncoding is used.
Return Value
When HPDF_CreateOutline() succeeds, it returns the handle of created outline object. Otherwise, it returns NULL and error-handler is invoked.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_OUTLINE - An invalid parent outline is specified.
HPDF_Image HPDF_LoadPngImageFromFile (HPDF_Doc pdf,
const char *filename);
Description
HPDF_LoadPngImageFromFile() loads an external PNG image file.
Parameters
pdf - The handle of a document object.
filename - A path to a PNG image file.
Return Value
When HPDF_LoadPngImageFromFile() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_UNSUPPORTED_FUNC - The library is not configured to use PNGLIB.
- HPDF_LIBPNG_ERROR - Failed when invoking PNGLIB's function.
- HPDF_INVALID_PNG_IMAGE - Invalid PNG format.
HPDF_Image HPDF_LoadPngImageFromFile2 (HPDF_Doc pdf,
const char *filename);
Description
HPDF_LoadPngImageFromFile2() loads an external PNG image file. Unlike HPDF_LoadPngImageFromFile(), HPDF_LoadPngImageFromFile2() does not load all the data immediately (only size and color properties are loaded). The main data are loaded just before the image object is written to PDF, and the loaded data are deleted immediately.
Parameters
pdf - The handle of a document object.
filename - A path to a PNG image file.
Return Value
When HPDF_LoadPngImageFromFile2() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_UNSUPPORTED_FUNC - The library is not configured to use PNGLIB.
- HPDF_LIBPNG_ERROR - Failed when invoking PNGLIB's function.
- HPDF_INVALID_PNG_IMAGE - Invalid png format.
HPDF_Image HPDF_LoadRawImageFromFile (HPDF_Doc pdf,
const char *filename,
HPDF_UINT width,
HPDF_UINT height,
HPDF_ColorSpace color_space);
Description
HPDF_LoadRawImageFromFile() loads an image which has "raw" image format. This function loads the data without any conversion. So it is usually faster than the other functions.
Parameters
pdf - The handle of a document object.
filename - A path to a image file.
width - The width of an image file.
height - The height of an image file.
color_space - HPDF_CS_DEVICE_GRAY, HPDF_CS_DEVICE_RGB or HPDF_CS_DEVICE_CMYK.
- HPDF_CS_DEVICE_GRAY - 8 bit gray scale image
The sequence of bytes for an 8-pixel 8-bit image with 2 rows and 4 columns would be:
1 2 3 4 5 6 7 8
- HPDF_CS_DEVICE_RGB - 24 bit RGB color image
The sequence of bytes for an 8-pixel 24-bit image with 2 rows and 4 columns would be:
1R 1G 1B 2R 2G 2B 3R 3G 3B 4R 4G 4B 5R 5G 5B 6R 6G 6B 7R 7G 7B 8R 8G 8B
- HPDF_CS_DEVICE_CMYK - 32 bit CMYK color image.
The sequence of bytes for an 8-pixel 32-bit image with 2 rows and 4 columns would be:
1C 1M 1Y 1K 2C 2M 2Y 2K 3C 3M 3Y 3K 4C 4M 4Y 4K 5C 5M 5Y 5K 6C 6M 6Y 6K 7C 7M 7Y 7K 8C 8M 8Y 8K
Return Value
When HPDF_LoadRawImageFromFile() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_COLOR_SPACE - An invalid color_space value is specified.
- HPDF_INVALID_IMAGE - The size of an image data is invalid.
- HPDF_FILE_IO_ERROR - Cannot read data from the file.
HPDF_Image HPDF_LoadRawImageFromMem (HPDF_Doc pdf,
const HPDF_BYTE *buf,
HPDF_UINT width,
HPDF_UINT height,
HPDF_ColorSpace color_space,
HPDF_UINT bits_per_component);
Description
HPDF_LoadRawImageFromMem() loads an image which has "raw" image format from buffer. This function loads the data without any conversion. So it is usually faster than the other functions.
The formats that HPDF_LoadRawImageFromMem() can load is the same as HPDF_LoadRawImageFromFile().
Parameters
pdf - The handle of a document object.
buf - The pointer to the image data.
width - The width of an image file.
height - The height of an image file.
color_space - HPDF_CS_DEVICE_GRAY or HPDF_CS_DEVICE_RGB or HPDF_CS_DEVICE_CMYK is allowed.
bits_per_component - The bit size of each color component. The valid value is either 1, 2, 4, 8.
Return Value
When HPDF_LoadRawImageFromMem() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_COLOR_SPACE - An invalid color_space value is specified.
- HPDF_INVALID_IMAGE - The size of an image data is invalid.
HPDF_Image HPDF_LoadPngImageFromMem (HPDF_Doc pdf,
const HPDF_BYTE *buf,
HPDF_UINT size);
Description
HPDF_LoadPngImageFromMem() loads PNG image from a buffer.
Parameters
pdf - The handle of a document object.
buf - The pointer to the image data.
size - The size if the data buffer.
Return Value
When HPDF_LoadPngImageFromMem() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_PNG_IMAGE - Invalid PNG image was passed.
HPDF_Image HPDF_LoadJpegImageFromMem (HPDF_Doc pdf,
const HPDF_BYTE *buf,
HPDF_UINT size);
Description
HPDF_LoadJpegImageFromMem() loads JPEG image from a buffer.
Parameters
pdf - The handle of a document object.
buf - The pointer to the image data.
size - The size if the data buffer.
Return Value
When HPDF_LoadJpegImageFromMem() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_JPEG_DATA - Invalid JPEG image was passed.
- HPDF_UNSUPPORTED_JPEG_FORMAT - Invalid/unsupported JPEG image was passed.
HPDF_Image HPDF_LoadJpegImageFromFile (HPDF_Doc pdf,
const char *filename);
Description
HPDF_LoadJpegImageFromFile() loads an external JPEG image file.
Parameters
pdf - The handle of a document object.
filename - Path to a JPEG image file.
Return Value
When HPDF_LoadJpegImageFromFile() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_UNSUPPORTED_JPEG_FORMAT - Unsupported JPEG image format.
HPDF_STATUS HPDF_SetInfoAttr (HPDF_Doc pdf,
HPDF_InfoType type,
const char *value);
Description
HPDF_SetInfoAttr() sets the text of an info dictionary attribute, using current encoding of the document. If encoding is not set, PDFDocEncoding is used.
Parameters
pdf - The handle of a document object.
type - One of the following:
- HPDF_INFO_AUTHOR
- HPDF_INFO_CREATOR
- HPDF_INFO_TITLE
- HPDF_INFO_SUBJECT
- HPDF_INFO_KEYWORDS
Return Value
When HPDF_SetInfoAttr() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_PARAMETER - An invalid type parameter was set.
HPDF_GetInfoAttr(), HPDF_SetInfoDateAttr()
const char* HPDF_GetInfoAttr (HPDF_Doc pdf,
HPDF_InfoType type);
Description
HPDF_GetInfoAttr() gets an attribute value from info dictionary.
Parameters
pdf - The handle of a document object.
type - One of the following:
- HPDF_INFO_CREATION_DATE
- HPDF_INFO_MOD_DATE
- HPDF_INFO_AUTHOR
- HPDF_INFO_CREATOR
- HPDF_INFO_TITLE
- HPDF_INFO_SUBJECT
- HPDF_INFO_KEYWORDS
When HPDF_GetInfoAttr() succeeds, it returns the string value of the info dictionary. If the infomation has not been set or an error has occurred, it returns NULL
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_PARAMETER - An invalid type parameter was set.
HPDF_SetInfoAttr(), HPDF_SetInfoDateAttr()
typedef struct _HPDF_Date {
HPDF_INT year;
HPDF_INT month;
HPDF_INT day;
HPDF_INT hour;
HPDF_INT minutes;
HPDF_INT seconds;
char ind;
HPDF_INT off_hour;
HPDF_INT off_minutes;
} HPDF_Date;
HPDF_STATUS HPDF_SetInfoDateAttr (HPDF_Doc pdf,
HPDF_InfoType type,
HPDF_Date value);
Description
HPDF_SetInfoDateAttr() sets a datetime attribute in the info dictionary.
Parameters
pdf - The handle of a document object.
type - One of the following attributes:
- HPDF_INFO_CREATION_DATE
- HPDF_INFO_MOD_DATE
HPDF_Date struct
| Member | Effective values |
|---|---|
| year | |
| month | Between 1 and 12. |
| day | Between 1 and 28, 29, 30, or 31. (Depends on the month.) |
| hour | 0 to 23 |
| minutes | 0 to 59 |
| seconds | 0 to 59 |
| ind | Relationship of local time to Universal Time (" ", +, −, or Z). |
| off_hour | If "ind" is not space, 0 to 23 is valid. Otherwise, ignored. |
| off_minutes | If "ind" is not space, 0 to 59 is valid. Otherwise, ignored. |
Return Value
When HPDF_SetInfoDateAttr() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_PARAMETER - An invalid type parameter was set.
- HPDF_INVALID_DATE_TIME - An invalid datetime value was set.
HPDF_GetInfoAttr(), HPDF_SetInfoAttr()
HPDF_STATUS HPDF_SetPassword (HPDF_Doc pdf,
const char *owner_passwd,
const char *user_passwd);
Description
HPDF_SetPassword() sets a password for the document. If the password is set, document contents are encrypted.
Parameters
pdf - The handle of a document object.
owner_password - The password for the owner of the document.
The owner can change the permission of the document.
NULL, zero length string, and the same value as user password are not allowed.
user_password - The password for the user of the document.
The user_password may be set to NULL or zero length string.
Return Value
When HPDF_SetPassword() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
- HPDF_INVALID_PASSWORD - Owner password is NULL, zero length string, or same value as user password.
HPDF_STATUS HPDF_SetPermission (HPDF_Doc pdf,
HPDF_UINT permission);
Description
HPDF_SetPermission() set the permission flags for the document.
Parameters
pdf - The handle of a document object.
permission - One or more of the following, "ored" together:
- HPDF_ENABLE_READ - user can read the document.
- HPDF_ENABLE_PRINT - user can print the document.
- HPDF_ENABLE_EDIT_ALL - user can edit the contents of the document other than annotations, form fields.
- HPDF_ENABLE_COPY - user can copy the text and the graphics of the document.
- HPDF_ENABLE_EDIT - user can add or modify the annotations and form fields of the document.
When HPDF_SetPermission() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
HPDF_STATUS HPDF_SetEncryptionMode (HPDF_Doc pdf,
HPDF_EncryptMode mode,
HPDF_UINT key_len);
Description
HPDF_SetEncryptionMode() set the encryption mode. As the side effect, ups the version of PDF to 1.4 when the mode is set to HPDF_ENCRYPT_R3.
Parameters
pdf - The handle of a document object.
mode - One of the following:
- HPDF_ENCRYPT_R2 - Use "Revision 2" algorithm. "key_len" automatically set to 5 (40 bits).
- HPDF_ENCRYPT_R3 - Use "Revision 3" algorithm. "key_len" can be 5 (40 bits) to 16 (128bits).
Return Value
When HPDF_SetEncryptionMode() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_INVALID_ENCRYPT_KEY_LEN - An invalid key length was specified.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.
HPDF_STATUS HPDF_SetCompressionMode (HPDF_Doc pdf,
HPDF_UINT mode);
Description
HPDF_SetCompressionMode() set the mode of compression.
Parameters
pdf - The handle of a document object.
mode - One or more of the following or'ed together:
- HPDF_COMP_NONE - No compression.
- HPDF_COMP_TEXT - Compress the contents stream of the page.
- HPDF_COMP_IMAGE - Compress the streams of the image objects.
- HPDF_COMP_METADATA - Other stream datas (fonts, cmaps and so on) are compressed.
- HPDF_COMP_ALL - All stream datas are compressed (HPDF_COMP_TEXT | HPDF_COMP_IMAGE | HPDF_COMP_METADATA).
When HPDF_SetCompressionMode() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.
Error codes
- HPDF_INVALID_DOCUMENT - An invalid document handle was set.
- HPDF_INVALID_COMPRESSION_MODE - An invalid compression mode was specified.
- HPDF_FAILD_TO_ALLOC_MEM - Memory allocation failed.