# Documentation/API/Document

### From libHaru.org wiki

< Documentation | API

# Basic Functions

## HPDF_New()

    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.

user_data - User-defined void pointer. This pointer is used by error handling.

Return Value

HPDF_New() and HPDF_NewEx() return a handle of document object on success and NULL on failure.

See Also

HPDF_Free()

## 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_NewDoc()

    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.

See Also

HPDF_FreeDoc ()

## 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_SaveToFile()

    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_SaveToStream()

    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_GetStreamSize()

    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_ReadFromStream()

    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.

Note:
Even if the result of HPDF_ReadFromStream() is HPDF_EOF, if the value of size parameter is more than 0, data is read into the buffer.

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_ResetStream()

    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_HasDoc()

    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_SetErrorHandler()

    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_GetError()

    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.

## HPDF_ResetError()

    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.

# Pages Handling

## HPDF_SetPagesConfiguration()

    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_SetPageLayout()

    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.

Return Value

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_GetPageLayout()

    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_SetPageMode()

    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.

Return Value

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_GetPageMode()

    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_SetOpenAction()

    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_GetCurrentPage()

    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_AddPage()

    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_InsertPage()

    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.

# Font Handling

## HPDF_AddPageLabel()

    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.

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:

1. HPDF_PAGE_NUM_STYLE_DECIMAL - Arabic numerals (1 2 3 4).
2. HPDF_PAGE_NUM_STYLE_UPPER_ROMAN - Uppercase roman numerals (I II III IV).
3. HPDF_PAGE_NUM_STYLE_LOWER_ROMAN - Lowercase roman numerals (i ii iii iv).
4. HPDF_PAGE_NUM_STYLE_UPPER_LETTERS - Uppercase letters (A B C D).
5. HPDF_PAGE_NUM_STYLE_LOWER_LETTERS - Lowercase letters (a b c d).

first_page - The first page number to use.
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_GetFont()

    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.

## HPDF_LoadType1FontFromFile()

    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.

## HPDF_LoadTTFontFromFile()

    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_LoadTTFontFromFile2()

    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_UseJPFonts()

    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

Parameters

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_UseKRFonts()

    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

Parameters

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_UseCNSFonts()

    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

Parameters

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_UseCNTFonts()

    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

Parameters

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.

# Encodings

## HPDF_GetEncoder()

    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_GetCurrentEncoder()

    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_SetCurrentEncoder()

    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_UseJPEncodings()

    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

Parameters

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_UseKREncodings()

    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

Parameters

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_UseCNSEncodings()

    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

Parameters

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_UseCNTEncodings()

    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

Parameters

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.

# Other Functions

## HPDF_CreateOutline()

    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_LoadPngImageFromFile()

    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_LoadPngImageFromFile2()

    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_LoadRawImageFromFile()

    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 gray scale describes each pixel with one byte. For each byte, 0X00 is maximum dark, 0XFF maximum light. The size of the image data is (width * height) bytes.

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 24 bit RGB color image describes each pixel with three bytes (Red, Green, Blue). For each byte, 0X00 is maximum dark, 0XFF maximum light. The size of the image data is (width * height * 3) bytes.

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 32 bit CMYK color image describes each pixel with four bytes (Cyan, Magenta, Yellow, Black). The size of the image data is (width * height * 4) bytes. For each byte, 0X00 is maximum dark, 0XFF maximum light.

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_LoadRawImageFromMem()

    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_LoadJpegImageFromFile()

    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_SetInfoAttr()

    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

value - Text to use for setting the attribute.

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.

See Also

HPDF_GetInfoAttr(), HPDF_SetInfoDateAttr()

## HPDF_GetInfoAttr()

    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

Return Value

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.

See Also

HPDF_SetInfoAttr(), HPDF_SetInfoDateAttr()

## 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_Info_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

value - The new value for the attribute.

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.

See Also

HPDF_GetInfoAttr(), HPDF_SetInfoAttr()

## HPDF_SetPassword()

    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_SetPermission()

    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.

Return Value

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_SetEncryptionMode()

    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).

key_len - Specify the byte length of encryption key. Only valid for HPDF_ENCRYPT_R3. Between 5 (40 bits) and 16 (128 bits) can be specified.

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_SetCompressionMode()

    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).

Return Value

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.

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

##### Views

- Page
- Discussion
- View source
- History

##### Personal tools

- Log in

##### Search

##### Toolbox

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