Document routines

Functions
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)
	Create an instance of a document object and initialize it. More...
HPDF_Doc	HPDF_New (HPDF_Error_Handler user_error_fn, void *user_data)
	Create an instance of a document object and initialize it. More...
HPDF_STATUS	HPDF_SetErrorHandler (HPDF_Doc pdf, HPDF_Error_Handler user_error_fn)
	Set a user-defined error handler for document. If subsequent function calls fail, the error handler is called. More...
void	HPDF_Free (HPDF_Doc pdf)
	Revoke a document object and all resources. More...
HPDF_STATUS	HPDF_NewDoc (HPDF_Doc pdf)
	Create a new document. If doc object already has a document, the current document is revoked. More...
void	HPDF_FreeDoc (HPDF_Doc pdf)
	Revoke the current document. More...
HPDF_BOOL	HPDF_HasDoc (HPDF_Doc pdf)
	Check if document handle is valid. More...
void	HPDF_FreeDocAll (HPDF_Doc pdf)
	Revoke the current document. More...
HPDF_STATUS	HPDF_SaveToStream (HPDF_Doc pdf)
	Saves the current document to a temporary stream of a document object. More...
HPDF_UINT32	HPDF_GetStreamSize (HPDF_Doc pdf)
	Gets the size of the temporary stream of the document. More...
HPDF_STATUS	HPDF_ReadFromStream (HPDF_Doc pdf, HPDF_BYTE *buf, HPDF_UINT32 *size)
	Copies the data from the temporary stream of the document into buffer buf. More...
HPDF_STATUS	HPDF_ResetStream (HPDF_Doc pdf)
	Rewind temporary stream of the document. More...
HPDF_STATUS	HPDF_SaveToFile (HPDF_Doc pdf, const char *filename)
	Saves the current document to file. More...
HPDF_STATUS	HPDF_SetPagesConfiguration (HPDF_Doc pdf, HPDF_UINT page_per_pages)
	Specify number of pages Pages object can own. More...

Detailed Description

Document routines are functions for document creation, freeing, substitution and reading/saving.

Function Documentation

HPDF_Free()

void HPDF_Free

(

HPDF_Doc

pdf

)

Revoke a document object and all resources.

Parameters

pdf	Document object handle.

See also

HPDF_New() HPDF_NewEx()

Examples

arc_demo.c, attach.c, character_map.c, chfont_demo.c, clip_hatch.c, clip_hatch2.c, encoding_list.c, encryption.c, ext_gstate_demo.c, font_demo.c, grid_demo.c, image_demo.c, jpeg_demo.c, jpfont_demo.c, line_demo.c, link_annotation.c, make_rawimage.c, matrix.c, minimal.c, outline_demo.c, outline_demo_jp.c, page_sizes_demo.c, pattern.c, pattern2.c, permission.c, png_demo.c, raw_image_demo.c, slide_show_demo.c, text_annotation.c, text_demo.c, text_demo2.c, transforms.c, ttfont_demo.c, ttfont_demo_jp.c, and utf8.c.

HPDF_FreeDoc()

void HPDF_FreeDoc

(

HPDF_Doc

pdf

)

Revoke the current document.

HPDF_FreeDoc() keeps and recycles loaded resources (such as fonts and encodings) when new document requires these resources.

Parameters

pdf	Document object handle.

See also

HPDF_NewDoc() HPDF_FreeDocAll()

HPDF_FreeDocAll()

void HPDF_FreeDocAll

(

HPDF_Doc

pdf

)

Revoke the current document.

HPDF_FreeDocAll() revokes the current document and all resources.

Parameters

pdf	Document object handle.

See also

HPDF_NewDoc() HPDF_FreeDoc()

HPDF_GetStreamSize()

HPDF_UINT32 HPDF_GetStreamSize

(

HPDF_Doc

pdf

)

Gets the size of the temporary stream of the document.

Parameters

pdf	Document object handle.

Returns

One of the values:

• Size of the temporary stream on success.
• HPDF_FALSE if temporary stream is invalid or document is invalid
• HPDF_INVALID_DOCUMENT

See also

HPDF_HasDoc() HPDF_Stream_Validate()

HPDF_HasDoc()

HPDF_BOOL HPDF_HasDoc

(

HPDF_Doc

pdf

)

Check if document handle is valid.

Parameters

pdf	Document object handle.

Returns

HPDF_TRUE if the specified document handle is valid. Otherwise return HPDF_FALSE, set error code and call error handler.

Error codes

• HPDF_INVALID_DOCUMENT

See also

HPDF_NewDoc()

HPDF_New()

HPDF_Doc HPDF_New	(	HPDF_Error_Handler	user_error_fn,
		void *	user_data
	)

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_data	User-defined void pointer. This pointer is used by error handling.

Returns

A handle of document object on success and NULL on failure.

See also

HPDF_NewEx() HPDF_Free()

Note

Same as

HPDF_NewEx(user_error_fn, NULL, NULL, 0, user_data)

Examples

arc_demo.c, attach.c, character_map.c, chfont_demo.c, clip_hatch.c, clip_hatch2.c, encryption.c, ext_gstate_demo.c, font_demo.c, grid_demo.c, image_demo.c, jpeg_demo.c, jpfont_demo.c, line_demo.c, link_annotation.c, make_rawimage.c, matrix.c, minimal.c, outline_demo.c, outline_demo_jp.c, pattern.c, pattern2.c, permission.c, png_demo.c, raw_image_demo.c, slide_show_demo.c, text_annotation.c, text_demo.c, text_demo2.c, transforms.c, ttfont_demo.c, ttfont_demo_jp.c, and utf8.c.

HPDF_NewDoc()

HPDF_STATUS HPDF_NewDoc

(

HPDF_Doc

pdf

)

Create a new document. If doc object already has a document, the current document is revoked.

Parameters

pdf	Document object handle.

Returns

HPDF_OK on success, otherwise returns error code and calls error handler.

Error codes

• HPDF_INVALID_DOCUMENT
• HPDF_FAILD_TO_ALLOC_MEM

See also

HPDF_FreeDoc()

HPDF_NewEx()

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
	)

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.

Returns

A handle of document object on success and NULL on failure.

See also

HPDF_New() HPDF_Free()

Examples

encoding_list.c, and page_sizes_demo.c.

HPDF_ReadFromStream()

HPDF_STATUS HPDF_ReadFromStream	(	HPDF_Doc	pdf,
		HPDF_BYTE *	buf,
		HPDF_UINT32 *	size
	)

Copies the data from the temporary stream of the document into buffer buf.

Parameters

pdf	Document object handle.
buf	Pointer to the buffer.
size	The size of buffer. After HPDF_ReadFromStream() is executed, the number of bytes read is set into size.

Returns

HPDF_OK or HPDF_STREAM_EOF on success, otherwise, it returns error-code and error-handler is invoked.

Error codes

• HPDF_INVALID_DOCUMENT
• HPDF_INVALID_OPERATION
• HPDF_INVALID_PARAMETER

Note

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

HPDF_ResetStream()

HPDF_STATUS HPDF_ResetStream

(

HPDF_Doc

pdf

)

Rewind temporary stream of the document.

Parameters

pdf	Document object handle.

Returns

HPDF_OK on success, otherwise returns error code and calls error handler.

Error codes

• HPDF_INVALID_DOCUMENT
• HPDF_INVALID_OPERATION

HPDF_SaveToFile()

HPDF_STATUS HPDF_SaveToFile	(	HPDF_Doc	pdf,
		const char *	filename
	)

Saves the current document to file.

Parameters

pdf	Document object handle.
filename	The name of file to save.

Returns

HPDF_OK on success, otherwise returns error code and calls error handler.

Error codes

• HPDF_INVALID_DOCUMENT
• HPDF_FAILD_TO_ALLOC_MEM
• HPDF_FILE_IO_ERROR

Examples

arc_demo.c, attach.c, character_map.c, chfont_demo.c, clip_hatch.c, clip_hatch2.c, encoding_list.c, encryption.c, ext_gstate_demo.c, font_demo.c, grid_demo.c, image_demo.c, jpeg_demo.c, jpfont_demo.c, line_demo.c, link_annotation.c, matrix.c, minimal.c, outline_demo.c, outline_demo_jp.c, page_sizes_demo.c, pattern.c, pattern2.c, permission.c, png_demo.c, raw_image_demo.c, slide_show_demo.c, text_annotation.c, text_demo.c, text_demo2.c, transforms.c, ttfont_demo.c, ttfont_demo_jp.c, and utf8.c.

HPDF_SaveToStream()

HPDF_STATUS HPDF_SaveToStream

(

HPDF_Doc

pdf

)

Saves the current document to a temporary stream of a document object.

Parameters

pdf	Document object handle.

Returns

HPDF_OK on success, otherwise returns error code and calls error handler.

Error codes

• HPDF_INVALID_DOCUMENT
• HPDF_FAILD_TO_ALLOC_MEM

HPDF_SetErrorHandler()

HPDF_STATUS HPDF_SetErrorHandler	(	HPDF_Doc	pdf,
		HPDF_Error_Handler	user_error_fn
	)

Set a user-defined error handler for document. If subsequent function calls fail, the error handler is called.

Parameters

pdf	Document object handle.
user_error_fn	User-defined error handler. If NULL, previous error handler is revoked.

Returns

HPDF_OK on success, otherwise returns HPDF_INVALID_DOCUMENT.

HPDF_SetPagesConfiguration()

HPDF_STATUS HPDF_SetPagesConfiguration	(	HPDF_Doc	pdf,
		HPDF_UINT	page_per_pages
	)

Specify number of pages Pages object can own.

In the default setting, a HPDF_Doc object has one Pages object as root of pages. All Page objects are created as a child of Pages object. Since Pages object can own only 8191 child objects, the maximum number of pages are 8191 pages. Additionally, the case when there are a lot of "Page" object under one "Pages" object is not good, since 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 pages. An application cannot invoke HPDF_SetPageConfiguration() after a page is added to document.

Parameters

pdf	Document object handle.
page_per_pages	Numbers of pages Pages object can own.

Returns

HPDF_OK on success, otherwise returns error code and calls error handler.

Error codes

• HPDF_INVALID_DOCUMENT
• HPDF_INVALID_PARAMETER
• HPDF_INVALID_DOCUMENT_STATE
• HPDF_FAILD_TO_ALLOC_MEM

Examples

character_map.c.