home | download | documentation | examples | sourceforge | forums

## Document Handling Functions

### HPDF_New, HPDF_NewEX

#include "apdf.h"
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.

#### Parameter

user_error_fn
Specify user-defined error handler which is invoked when an error occurred.
user_alloc_fn
Specify user-defined memory allocation function. If NULL is specified, malloc() is used.
user_free_fn
Specify user-defined memory freeing function. If NULL is specified, free() is used.
mem_pool_buf_size
On default setting, Haru does not use memory pool. A memory allocation function is called on demand from an application. If this parameter set to non-zero value, a memory management will be done as following.

- A memory is allocated per mem_pool_buf_size.
- Memory manager gives a memory of requested size to an application. And pool the 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.
- The unused memory is not released immediately. It is released all together when HPDF_Free() is invoked.

user_data
Specify user-defind void pointer.This pointer is used by error handling.

#### Returns

HPDF_New() and HPDF_NewEX() returns a handle of document object. If it failed, it returns NULL.

### HPDF_Free

#include "apdf.h"
HPDF_Doc
HPDF_Free (HPDF_Doc pdf);

#### Description

HPDF_Free() revokes a document object and all resources.

#### Parameter

pdf
Specify the handle of a document object.

### HPDF_NewDoc

#include "apdf.h"
HPDF_STATUS
HPDF_NewDoc (HPDF_Doc pdf);

#### Description

HPDF_NewDoc() creates new document. If document object already has a document, the current document is revoked.

#### Parameter

pdf
Specify the handle of a document object.

#### Returns

When HPDF_NewDoc succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle is set.
HPDF_FAILD_TO_ALLOC_MEM
Memory Allocation Failed.

### HPDF_FreeDoc、 HPDF_FreeDocAll

#include <apdf.h>
void
HPDF_FreeDoc (HPDF_Doc pdf);
void
HPDF_FreeDocAll (HPDF_Doc pdf);

#### Description

HPDF_FreeDoc(), HPDF_FreeDocAll() revokes the current document. HPDF_FreeDoc() keeps loaded resource (such as fonts and encodings) and these resources are recycled when new document required these resources. HPDF_FreeDocAll() revokes the current document and all resources.

#### Parameter

pdf
Specify the handle of a document object.

### HPDF_SaveToFile

#include <apdf.h>
HPDF_STATUS
HPDF_SaveToFile (HPDF_Doc pdf,
const char *file_name);

#### Description

HPDF_SaveToFile() saves the current document to a file.

#### Parameter

pdf
Specify the handle of a document object.
file_name
Specify the name of file to save.

#### Returns

When HPDF_SaveToFile() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.

#### Error

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

#include <apdf.h>
HPDF_STATUS
HPDF_SaveToStream (HPDF_Doc pdf);

#### Description

HPDF_SaveToStream() saves the current document to a temporary stream of a document object.

#### Parameter

pdf
Specify the handle of a document object.

#### Returns

When HPDF_SaveToStream() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle is set.
HPDF_FAILD_TO_ALLOC_MEM
Memory Allocation Failed.

### HPDF_GetStreamSize

#include <apdf.h>
HPDF_UINT32
HPDF_GetStreamSize (HPDF_Doc pdf);

#### Description

HPDF_GetStreamSize() gets the size of the temporary stream of the document.

#### Parameter

pdf
Specify the handle of a document object.

#### Returns

When HPDF_GetStreamSize() succeeds, it returns the size of the temporary stream of the document. Otherwise, it returns 0.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle is set.

### HPDF_ReadFromStream

#include <apdf.h>
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 the buffer.

#### Parameter

pdf
Specify the handle of a document object.
buf
A pointer of the buffer.
size
Specifiy the size of buffer. After HPDF_ReadFromStream() is execute, the number of bytes that succeeds in reading is set.

#### Returns

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

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

#include <apdf.h>
HPDF_STATUS
HPDF_ResetStream (HPDF_Doc pdf);

#### Description

HPDF_ResetStream() rewinds the temporary stream of the document.

#### Parameter

pdf
Specify the handle of a document object.

#### Returns

When HPDF_ResetStream() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is invoked.

#### Error

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

#include <apdf.h>
HPDF_BOOL
HPDF_HasDoc (HPDF_Doc pdf);

#### Description

HPDF_SaveToFile() saves the current document to a file.

#### Parameter

pdf
Specify the handle of a document object.
file_name
Specify the name of file to save.

#### Returns

If the spacified document handle is valid, it returns HPDF_TRUE. Otherwise, it returns error-code and error-handler is called.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle is set.

### HPDF_SetErrorHandler

#include <apdf.h>
HPDF_STATUS
HPDF_SetErrorHandler (HPDF_Doc pdf,
HPDF_Error_Handler user_error_fn);

#### Description

HPDF_SetErrorHandler() sets an user-defined error handler. If a function call fails, the function this error handler is called.

#### Parameter

pdf
Specify the handle of a document object.
user_error_fn
Specify user-defined error handler which is invoked when an error occurred. If this parameter is set to NULL, the error-handler which has been set is revoked.

#### Returns

When HPDF_SaveToFile() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle is set.

### HPDF_GetError

#include <apdf.h>
HPDF_STATUS
HPDF_GetError (HPDF_Doc pdf);

#### Description

HPDF_GetError returns the last-error code of specified PdfDoc object.

#### Parameter

pdf
Specify the handle of a document object

#### Returns

HPDF_GetError returns the last-error code of specified PdfDoc object.
If there is no error, it returns HPDF_OK.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle is set.

### HPDF_ResetError

#include <apdf.h>
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.

#### Parameter

pdf
Specify the handle of a document object

### HPDF_SetPagesConfiguration

#include <apdf.h>
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.

#### Parameter

pdf
Specify the handle of a document object.
page_per_pages
Specify the numbers of pages that a "Pages" object can own.

#### Returns

When HPDF_SetPageConfiguration() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.

#### Error

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

#include <apdf.h>
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 a viewer application is used.

#### Parameter

pdf
Specify the handle of a document object.
layout
The following values are available.

Value | Description
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 the pages in two column. The page of the odd number is displayed left.
HPDF_PAGE_LAYOUT_TWO_COLUMN_RIGHT | Display the pages in two column. The page of the odd number is displayed right.

#### Returns

When HPDF_SetPageLayout() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.

#### Error

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

#include <apdf.h>
HPDF_PageLayout
HPDF_GetPageLayout (HPDF_Doc pdf);

#### Description

HPDF_GetPageLayout() returns the current setting for page layout.

#### Parameter

pdf
Specify the handle of a document object.

#### Returns

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

#include "apdf.h"
HPDF_STATUS
HPDF_SetPageMode (HPDF_Doc pdf,
HPDF_PageMode mode);

#### Description

HPDF_SetPageMode() sets how the document should be displayed.

#### Parameter

pdf
Specify the handle of a document object.
mode
The following values are available.

Value | Description
HPDF_PAGE_MODE_USE_NONE | Display the document with neither outline nor thumbnail.
HPDF_PAGE_MODE_USE_OUTLINE | Display the document with outline pain.
HPDF_PAGE_MODE_USE_THUMBS | Display the document with thumbnail pain.
HPDF_PAGE_MODE_FULL_SCREEN | Display the document with full screen mode.

#### Returns

When HPDF_SetPageMode() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.

#### Error

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

#include "apdf.h"
HPDF_PageMode
HPDF_GetPageMode (HPDF_Doc pdf);

#### Description

HPDF_GetPageLayout() returns the current setting for page mode.

#### Parameter

pdf
Specify the handle of a document object.

#### Returns

When HPDF_GetPageMode() succeeds, it returns the current setting for page mode.

### HPDF_SetOpenAction

#include <apdf.h>
HPDF_STATUS
HPDF_SetOpenAction (HPDF_Doc pdf,
HPDF_Destination open_action);

#### Description

HPDF_SetOpenAction() set the first page appears when a document is opened.

#### Parameter

pdf
Specify the handle of a document object.
open_action
Set a valid destination object.

#### Returns

When HPDF_SetOpenAction() succeeds, it returns HPDF_OK. Otherwise, it returns error-code and error-handler is called.

#### Error

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

#include <apdf.h>
HPDF_Page
HPDF_GetCurrentPage (HPDF_Doc pdf);

#### Description

HPDF_GetPageLayout() returns the handle of current page object.

#### Parameter

pdf
Specify the handle of a document object.

#### Returns

When HPDF_GetPageLayout() succeeds, it returns the handle of a current page object. Otherwise it returns NULL.

### HPDF_AddPage

#include <apdf.h>
HPDF_Page
HPDF_AddPage (HPDF_Doc pdf);

#### Description

HPDF_AddPage() creates a new page and adds it after the last page of a document.

#### Parameter

pdf
Specify the handle of a document object

#### Returns

When HPDF_AddPage() succeeds, it returns the handle of created page object. Otherwise, it returns error-code and error-handler is called.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle was set.
HPDF_FAILD_TO_ALLOC_MEM
Memory Allocation Failed.

### HPDF_InsertPage

#include <apdf.h>
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.

#### Parameter

pdf
Specify the handle of a document object.
page
Specify the handle of a page object which specifies the insertion place.

#### Returns

When HPDF_InsertPage() succeeds, it returns the handle of created page object. Otherwise, it returns NULL and error-handler is called.

#### Error

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_GetFont

#include "apdf.h"
HPDF_Font
HPDF_GetFont (HPDF_Doc pdf,
const char *font_name,
const char *encoding_name);

#### Description

HPDF_GetFont gets the handle of a corresponding font object by specified name and encoding.

#### Parameter

pdf
Specify the handle of a document object.
font_name
Specify a valid font name. (See "Fonts and Encodings")
encoding_name
Specify a valid encoding name. (See "Fonts and Encodings")

#### Returns

When HPDF_GetFont() succeeds, it returns the handle of a font object. Otherwise, it returns NULL and error-handler is called.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle was set.
HPDF_FAILD_TO_ALLOC_MEM
Memory Allocation Failed.
HPDF_INVALID_FONT_NAME, HPDF_UNSUPPORTED_FONT_TYPE
An invalid font name was set.
HPDF_INVALID_ENCODING_NAME
An invalid encoding name was set.

### HPDF_LoadType1FontFromFile

#include "apdf.h"
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 register it to a document object. (See "Fonts and Encodings")

#### Parameter

pdf
Specify 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 it is NULL, the gryph data of font file is not embedded to a PDF file.

#### Returns

When HPDF_LoadType1FontFromFile() succeeds, it returns the name of a font. Otherwise, it returns NULL and error-handler is called.

#### Error

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

#include "apdf.h"
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")

#### Parameter

pdf
Specify 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.

#### Returns

When HPDF_LoadTTFontFromFile() succeeds, it returns the name of a font. Otherwise, it returns NULL and error-handler is called.

#### Error

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_LoadTTFontFromFile2

#include "apdf.h"
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")

#### Parameter

pdf
Specify the handle of a document object.
file_name
A path of a TrueType font collection file (.ttc).
index
The index of font that wants to be loaded.
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.

#### Returns

When HPDF_LoadTTFontFromFile2() succeeds, it returns the name of a font. Otherwise, it returns NULL and error-handler is called.

#### Error

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_AddPageLabel

#include "apdf.h"
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.

#### Parameter

pdf
The handle of a document object.
page_num
The first page that applies this labeling range.
style
The numbering style.

| Value | Description
1 | HPDF_PAGE_NUM_STYLE_DECIMAL | Page label is displayed by Arabic numerals.
2 | HPDF_PAGE_NUM_STYLE_UPPER_ROMAN | Page label is displayed by Uppercase roman numerals.
3 | HPDF_PAGE_NUM_STYLE_LOWER_ROMAN | Page label is displayed by Lowercase roman numerals.
4 | HPDF_PAGE_NUM_STYLE_UPPER_LETTERS | Page label is displayed by Uppercase letters (using A to Z).
5 | HPDF_PAGE_NUM_STYLE_LOWER_LETTERS | Page label is displayed by Lowercase letters (using a to z).

first_page
The first page number in this range.
prefix
The prefix for the page label. (NULL is allowed.)

#### Returns

When HPDF_AddPageLabel () succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.

#### Error

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_UseJPFonts

#include "apdf.h"
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

#### Parameter

pdf
The handle of a document object.

#### Returns

When HPDF_UseJPFonts() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.

#### Error

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

#include "apdf.h"
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

#### Parameter

pdf
The handle of a document object.

#### Returns

When HPDF_UseKRFonts() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.

#### Error

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

#include "apdf.h"
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

#### Parameter

pdf
The handle of a document object.

#### Returns

When HPDF_UseCNSFonts() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.

#### Error

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

#include "apdf.h"
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

#### Parameter

pdf
The handle of a document object.

#### Returns

When HPDF_UseCNSFonts() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.

#### Error

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_CreateExtGstate

#include "apdf.h"
HPDF_ExtGState
HPDF_CreateExtGState (HPDF_Doc pdf);;

#### Description

HPDF_CreateExtGState() creates a new extended graphics state object.
As a side effect, HPDF_CreateExtGState() bumps up the version of PDF to 1.4.
NOTE:
In Acrobat Reader 5.0, when ExtGState object is used combined with HPDF_Page_Concat(), there is a case that cannot be correctly displayed.

#### Parameter

pdf
The handle of a document object.

#### Returns

When HPDF_CreateExtGState() succeeds, it returns the handle of created extended graphics stateobject. Otherwise, it returns NULL and error-handler is invoked.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle was set.
HPDF_FAILD_TO_ALLOC_MEM
Memory Allocation Failed.

### HPDF_CreateOutline

#include "apdf.h"
HPDF_Outline
HPDF_CreateOutline (HPDF_Doc pdf,
HPDF_Outline parent,
const char *title,
HPDF_Encoder encoder);

#### Description

HPDF_CreateOutline() creates a new outline object.

#### Parameter

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 this parameter is 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 is set, PDFDocEncoding is used.

#### Returns

When HPDF_CreateOutline() succeeds, it returns the handle of created outline object. Otherwise, it returns NULL and error-handler is invoked.

#### Error

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_GetEncoder

#include "apdf.h"
HPDF_Encoder
HPDF_GetEncoder (HPDF_Doc pdf,
const char *encoding_name);

#### Description

HPDF_GetEncoder() gets the handle of a corresponding encoder object by specified encoding name.

#### Parameter

pdf
Specify the handle of a document object.
encoding_name
Specify a valid encoding name. (See "Fonts and Encodings")

#### Returns

When HPDF_GetEncoder() succeeds, it returns the handle of an encoder object. Otherwise, it returns NULL and error-handler is called.

#### Error

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

#include "apdf.h"
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.

#### Parameter

pdf
A handle of a document object.

#### Returns

It returns a handle of an encoder object or NULL.

### HPDF_SetCurrentEncoder

#include "apdf.h"
HPDF_Outline
HPDF_SetCurrentEncoder (HPDF_Doc pdf,
const char *encoding_name);

#### Description

HPDF_SetCurrentEncoder() sets the current encoder for the document.

#### Parameter

pdf
The handle of a document object.
encoding_name
The name of an encoding. (See "Fonts and Encodings")

#### Returns

When HPDF_SetCurrentEncoder() succeeds, it returns the handle of created outline object. Otherwise, it returns NULL and error-handler is invoked.

#### Error

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

#include "apdf.h"
HPDF_STATUS
HPDF_UseJPEncodings (HPDF_Doc pdf);

#### Description

HPDF_UseJPEncodings() enables Japanese encodings. After HPDF_UseJPEncodings() is involed, an application can use the following Japanese encodings.

- 90ms-RKSJ-H
- 90ms-RKSJ-V
- 90msp-RKSJ-H
- EUC-H
- EUC-V

#### Parameter

pdf
The handle of a document object.

#### Returns

When HPDF_UseJPEncodings() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.

#### Error

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

#include "apdf.h"
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

#### Parameter

pdf
The handle of a document object.

#### Returns

When HPDF_UseKREncodings() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.

#### Error

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

#include "apdf.h"
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

#### Parameter

pdf
The handle of a document object.

#### Returns

When HPDF_UseCNSEncodings() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.

#### Error

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

#include "apdf.h"
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

#### Parameter

pdf
The handle of a document object.

#### Returns

When HPDF_UseCNTEncodings() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is invoked.

#### Error

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_LoadPngImageFromFile

#include "apdf.h"
HPDF_Image
HPDF_LoadPngImageFromFile (HPDF_Doc pdf,
const char *filename);

#### Description

HPDF_LoadPngImageFromFile() loads an external png image file.

#### Parameter

pdf
Specify the handle of a document object.
filename
A path to a PNG image file.

#### Returns

When HPDF_LoadPngImageFromFile() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.

#### Error

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

#include "apdf.h"
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 whole data immediately. (only size and color properties is loaded).
The main data is loaded just before the image object is written to PDF, and the loaded data is deleted immediately.

#### Parameter

pdf
Specify the handle of a document object.
filename
A path to a PNG image file.

#### Returns

When HPDF_LoadPngImageFromFile2() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.

#### Error

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

#include "apdf.h"
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.
HPDF_LoadRawImageFromFile() can load 3 types of format described below.
1. 8 bit gray scale image.
The gray scale describes one pixel by one byte. And the size of the image data is same as width * height.
The sequence of the data is as follows.

1 | 2 | 3 | 4
6 | 7 | 8 | 9
11 | 12 | 13 | 14

1. 24bit RGB color image.
The 24bit RGB color image describes one pixel by 3 byte (each one byte describes a value of either red, green or blue). And the size of the image is same as width * height * 3.
The sequence of the data is as follows.

1 | 1 | 1 | 2 | 2 | 2 | 3 | 3 | 3 | 4 | 4 | 4
6 | 6 | 6 | 7 | 7 | 7 | 8 | 8 | 8 | 9 | 9 | 9
11 | 11 | 11 | 12 | 12 | 12 | 13 | 13 | 13 | 14 | 14 | 14

1. 36bit CMYK color image.
The 36bit CMYK color image describes one pixel by 4 byte (each one byte describes a value of either Cyan Magenta Yellow Black). And the size of the image is same as width * height * 4.
The sequence of the data is as follows.

1 | 1 | 1 | 1 | 2 | 2 | 2 | 2 | 3 | 3 | 3 | 3 | 4 | 4 | 4 | 4
6 | 6 | 6 | 6 | 7 | 7 | 7 | 7 | 8 | 8 | 8 | 8 | 9 | 9 | 9 | 9
11 | 11 | 11 | 11 | 12 | 12 | 12 | 12 | 13 | 13 | 13 | 13 | 14 | 14 | 14 | 14

#### Parameter

pdf
Specify 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 or HPDF_CS_DEVICE_RGB or HPDF_CS_DEVICE_CMYK is allowed.

#### Returns

When HPDF_LoadRawImageFromFile() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.

#### Error

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

#include "apdf.h"
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().

#### Parameter

pdf
Specify 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.

#### Returns

When HPDF_LoadRawImageFromMem() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.

#### Error

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

#include "apdf.h"
HPDF_Image
HPDF_LoadJpegImageFromFile (HPDF_Doc pdf,
const char *filename);

#### Description

HPDF_LoadJpegImageFromFile() loads an external Jpeg image file.

#### Parameter

pdf
Specify the handle of a document object.
filename
A path to a Jpeg image file.

#### Returns

When HPDF_LoadJpegImageFromFile() succeeds, it returns the handle of an image object. Otherwise, it returns NULL and error-handler is called.

#### Error

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

#include "apdf.h"
HPDF_STATUS
HPDF_SetInfoAttr (HPDF_Doc pdf,
HPDF_InfoType type,
const char *value);

#### Description

HPDF_SetInfoAttr() sets the text of the info dictionary. HPDF_SetInfoAttr() uses the current encoding of the document. If it is not set, the PDFDocEncoding is used.

#### Parameter

pdf
Specify the handle of a document object.
type
The following values are available.

- HPDF_INFO_AUTHOR
- HPDF_INFO_CREATOR
- HPDF_INFO_TITLE
- HPDF_INFO_SUBJECT
- HPDF_INFO_KEYWORDS

value
A text to set the infomation.

#### Returns

When HPDF_SetInfoAttr() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.

#### Error

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

#include "apdf.h"
const char*
HPDF_GetInfoAttr (HPDF_Doc pdf,
HPDF_InfoType type);

#### Description

HPDF_GetInfoAttr() gets the string value fron info dictionary.

#### Parameter

pdf
Specify the handle of a document object.
type
The following values are available.

- HPDF_INFO_CREATION_DATE
- HPDF_INFO_MOD_DATE
- HPDF_INFO_AUTHOR
- HPDF_INFO_CREATOR
- HPDF_INFO_TITLE
- HPDF_INFO_SUBJECT
- HPDF_INFO_KEYWORDS

#### Returns

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

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_SetInfoDateAttr

#include "apdf.h"
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_Dict info,
HPDF_InfoType type,
HPDF_Date value);

#### Description

HPDF_SetInfoDateAttr() sets the datetime value to the info dictionary.

#### Parameter

pdf
Specify the handle of a document object.
type
The following values are available.

- HPDF_INFO_CREATION_DATE
- HPDF_INFO_MOD_DATE

value
A datetime value to set the infomation.
HPDF_Date struct

| name | effective values
1 | year |
2 | month | between 1 and 12.
3 | day | between 1 and ether of 28, 29, 30, 31. (It is different by the month.)
4 | hour | 0 to 23
5 | minutes | 0 to 59
6 | seconds | 0 to 59
7 | ind | the relationship of local time to Universal Time. " ", +, −, and Z are available.
8 | off_hour | if ind is not space, 0 to 23 is valid. Otherwise, this value is ignored.
9 | off_minutes | if ind is not space, 0 to 59 is valid. Otherwise, this value is ignored.

#### Returns

When HPDF_SetInfoDateAttr() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.

#### Error

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_SetPassword

#include "apdf.h"
HPDF_STATUS
HPDF_SetPassword (HPDF_Doc pdf,
const char *owner_passwd,
const char *user_passwd);

#### Description

HPDF_SetPassword() sets the pasword for the document.
If the password is set, contents in the document are encrypted.

#### Parameter

pdf
Specify 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 is allowed to be set to NULL or zero length string.

#### Returns

When HPDF_SetPassword() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle was set.
HPDF_FAILD_TO_ALLOC_MEM
Memory Allocation Failed.
HPDF_INVALID_PASSWORD
NULL, zero length string and the same value as user password are set to owner-password.

### HPDF_SetPermission

#include "apdf.h"
HPDF_STATUS
HPDF_SetPermission (HPDF_Doc pdf,
HPDF_UINT permission);

#### Description

HPDF_SetPermission() set the flags of the permission for the document.

#### Parameter

pdf
Specify the handle of a document object.
permission
The flags specifying which operations are permitted. This parameter is set by logical addition of the following values.

| value | description
1 | HPDF_ENABLE_READ | user can read the document.
2 | HPDF_ENABLE_PRINT | user can print the document.
3 | HPDF_ENABLE_EDIT_ALL | user can edit the contents of the document other than annotations, form fields.
4 | HPDF_ENABLE_COPY | user can copy the text and the graphics of the document.
5 | HPDF_ENABLE_EDIT | user can add or modify the annotations and form fields of the document.

#### Returns

When HPDF_SetPermission() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.

#### Error

HPDF_INVALID_DOCUMENT
An invalid document handle was set.
HPDF_FAILD_TO_ALLOC_MEM
Memory Allocation Failed.

### HPDF_SetEncryptionMode

#include "apdf.h"
HPDF_STATUS
HPDF_SetEncryptionMode (HPDF_Doc pdf,
HPDF_EncryptMode mode,
HPDF_UINT key_len);

#### Description

HPDF_SetEncryptionMode() set the type of encryption.
As the side effect, HPDF_SetEncryptionMode() ups the version of PDF to 1.4 when the mode is set to HPDF_ENCRYPT_R3.

#### Parameter

pdf
Specify the handle of a document object.
mode
The flags specifying which operations are permitted. This parameter is set by logical addition of the following values.

| value | description
1 | HPDF_ENCRYPT_R2 | Use "Revision 2" algorithm. The length of key is automatically set to 5(40bit).
2 | HPDF_ENCRYPT_R3 | Use "Revision 3" algorithm. Between 5(40bit) and 16(128bit) can be specified for length of the key.

key_len
Specify the byte length of an encryption key. This parameter is valid only when "mode" parameter is set to HPDF_ENCRYPT_R3.
Between 5(40bit) and 16(128bit) can be specified for length of the key.

#### Returns

When HPDF_SetEncryptionMode() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.

#### Error

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

#include "apdf.h"
HPDF_STATUS
HPDF_SetCompressionMode (HPDF_Doc pdf,
HPDF_UINT mode);

#### Description

HPDF_SetCompressionMode() set the mode of compression.

#### Parameter

pdf
Specify the handle of a document object.
mode
The flags specifying which type of contents should be compressed.

| value | description
1 | HPDF_COMP_NONE | All contents are not compressed.
2 | HPDF_COMP_TEXT | Compress the contents stream of the page.
3 | HPDF_COMP_IMAGE | Compress the streams of the image objects.
4 | HPDF_COMP_METADATA | Other stream datas (fonts, cmaps and so on) are compressed.
5 | HPDF_COMP_ALL | All stream datas are compressed. (The same as "HPDF_COMP_TEXT | HPDF_COMP_IMAGE | HPDF_COMP_METADATA")

#### Returns

When HPDF_SetCompressionMode() succeeds, it returns HPDF_OK. Otherwise, it returns error code and error-handler is called.

#### Error

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.