Haru Free PDF Library
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.

figure7.png
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.

figure8
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_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.