path: root/src/images/fpdfemb.h

// FPDFEMB.H - Header file for FPDFEMB SDK
// Copyright (c) 2007-2008 Foxit Software Company, All Right Reserved.

// Date: 2008-04-07

// Embedded platforms have many different aspects from desktop platforms,
// among them, the followings are most important for PDF processing:
//
// 1.	Embedded platforms have only limited memory, and there is no virtual memory.
//		PDF is a very complicated format, processing PDF may consumes quite
//		large amount of memory, even for some smaller PDFs. And, in order to 
//		increase the performance of PDF parsing and rendering, cache memory
//		is often used. For some big PDFs with many pages, the cache may grow
//		while user browing through pages, eventually, for some PDFs, the memory
//		on the device may run out.
//
//		FPDFEMB SDK allows graceful out-of-memory (OOM) handling by returning 
//		OOM error code for all functions that may involve memory allocation. 
//		When an application detects OOM situation, it can do one of the followings:
//
//			a) Give user some prompt and quit the application or close the document;
//			b) Or better, try to recover from the error. Sometimes OOM can be caused
//				by ever-growing cache. For example, when user browses a 1000-page 
//				document, let's say OOM happen at page #300. In this case, the
//				application might close the whole document (cache will be gone with
//				it), reopen the document, then go directly to page #300. It's likely
//				the process will go through this time. This is called "OOM recovery".
//				If OOM happens again during a recovery, then, it's not possible to finish
//				the process, the application must quit of close the document.
//
// 2.	Embedded platforms has only limited computing power. Since some PDFs
//		can be very complicated and require a lot of processing to be displayed,
//		it may take a lot of time for the process to finish. This may cause
//		some problem with user experience, especially for devices like mobile
//		phones, when an application may need to be put on hold any time. Therefore, 
//		it's important to break lengthy process into small steps which can be 
//		stopped or resumed at any time. We call this kind of process as 
//		"progressive process".
//
//		FPDFEMB SDK allows progressive page parsing and rendering, the most time-
//		consuming part of PDF processing.
//
// IMPORTANT:
//		FPDFEMB module is not intended to run in multi-threaded environment.

// Components inside FPDFEMB:
//		* Library Memory Management
//		* Document Operations
//		* Page Basic Operations
//		* Page Parsing
//		* Page Rendering
//		* Coordination Conversion
//		* Text Search
//		* Text Information
//		* Device Independant Bitmap
//		* Custom Font Handler and CJK Support
//		* Bookmark Information
//		* Hyperlink Information
//		* Graphic Output

#ifndef _FPDFEMB_H_
#define _FPDFEMB_H_

#ifdef __cplusplus
extern "C" {
#endif

// Standard return type for many FPDFEMB functions: FPDFERR_SUCCESS for success, otherwise error code
typedef int FPDFEMB_RESULT;

// Standard boolean type: 0 for false, non-zero for true
typedef int FPDFEMB_BOOL;

// Unicode character. FPDFEMB uses UTF16LE format for unicode string.
typedef unsigned short FPDFEMB_WCHAR;

// Error codes
#define FPDFERR_SUCCESS		0
#define FPDFERR_MEMORY		1		// Out of memory
#define FPDFERR_ERROR		2		// Error of any kind, without specific reason
#define FPDFERR_PASSWORD	3		// Incorrect password
#define FPDFERR_FORMAT		4		// Not PDF format
#define FPDFERR_FILE		5		// File access error
#define FPDFERR_PARAM		6		// Parameter error
#define FPDFERR_STATUS		7		// Not in correct status
#define FPDFERR_TOBECONTINUED	8	// To be continued
#define FPDFERR_NOTFOUND	9		// Search result not found

/********************************************************************************************
****
****		Library Memory Management
****
********************************************************************************************/

// Structure: FPDFEMB_MEMMGR
//			Including interfaces implemented by host application, providing memory allocation
//			facilities. All members are required.
//			A memory manager structure is required to be valid during the entire period
//			when an application using FPDFEMB module.
//
//			IMPORTANT NOTE: using of this interface is strongly not recommended, because
//			FPDFEMB now internally use FPDFEMB_MEMMGR_EX interface, which allows more
//			advanced memory management. This interface is retained for backward compatibility
//			only, and maybe discontinued in the future.
//
struct FPDFEMB_MEMMGR {
	// Interface: Alloc
	//		Allocate a memory block
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	//		size		-	Number of bytes for the memory block.
	// Return Value:
	//		The pointer to allocated memory block. NULL if no memory available.
	// Comments:
	//		In order to handle OOM situation, application can use longjmp() inside 
	//		implementation of this function. If underlying memory manager fails to 
	//		allocate enough memory, then application can use longjmp() to jump to
	//		OOM handling codes.
	//
	void*	(*Alloc)(struct FPDFEMB_MEMMGR* pMgr, unsigned int size);

	// Interface: AllocNL
	//		Allocate a memory block, without leaving
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	//		size		-	Number of bytes for the memory block.
	// Return Value:
	//		The pointer to allocated memory block. NULL if no memory available.
	// Comments:
	//		Implementation MUST return NULL if no memory available, no exception
	//		or longjmp() can be used.
	//
	void*	(*AllocNL)(struct FPDFEMB_MEMMGR* pMgr, unsigned int size);

	// Interfce: Realloc
	//		Reallocate a memory block
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	//		pointer		-	An existing memory block, or NULL.
	//		new_size	-	New size (number of bytes) of the memory block. Can be zero.
	// Return value:
	//		The pointer of reallocated memory block, it could be a new block, or just
	//		the previous block with size modified.
	// Comments:
	//		If an existing memory block specified, the data in the memory block will
	//		be copied to the new block, if reallocated.
	//
	//		In order to handle OOM situation, application can use longjmp() inside 
	//		implementation of this function. If underlying memory manager fails to 
	//		allocate enough memory, then application can use longjmp() to jump to
	//		OOM handling codes.
	//
	void*	(*Realloc)(struct FPDFEMB_MEMMGR* pMgr, void* pointer, unsigned int new_size);

	// Interface: Free
	//		Free a memory block
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	//		pointer		-	An existing memory block.
	// Return Value:
	//		None.
	//
	void	(*Free)(struct FPDFEMB_MEMMGR* pMgr, void* pointer);
};

// Function: FPDFEMB_Init
//			Initialize the FPDFEMB module
// Parameters:
//			mem_mgr		-	Pointer to memory manager structure
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			This function will allocate necessary internal data structure for
//			the whole module to operate.
FPDFEMB_RESULT FPDFEMB_Init(FPDFEMB_MEMMGR* mem_mgr);

typedef void (*FPDFEMB_FIXED_OOM_HANDLER)(void* memory, int size);

// Function: FPDFEMB_InitFixedMemory
//			Initialize the FPDFEMB module, providing a fixed memory heap
// Parameters:
//			memory		-	Pointer to a pre-allocated memory block
//			size		-	Number of bytes in the memory block
//			oom_handler	-	Pointer to a function which will be called when OOM happens. Can be
//							NULL if application doesn't want to be notified om OOM.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			In many embedded system, memory usage are predetermined. The application
//			is assigned with fixed size of available memory, then it can pre-allocate
//			a memory block with maximum size and pass to this function to initialize
//			FPDFEMB module. In this case, FPDFEMB won't need any additional memory
//			allocation.
//
//			In case the pre-allocated memory has run out, the "oom_proc" callback
//			function will be called to notify the application that an OOM recovery
//			procedure needs to be performed.
//
FPDFEMB_RESULT FPDFEMB_InitFixedMemory(void* memory, int size, FPDFEMB_FIXED_OOM_HANDLER oom_handler);

// Memory Management Flags
#define FPDFEMB_NONLEAVE		1
#define FPDFEMB_MOVABLE			2
#define FPDFEMB_DISCARDABLE		4

// Structure: FPDFEMB_MEMMGR_EX
//			This is an extended version of memory manager interface, allowing advanced
//			memory management, including movable and discardable memory blocks.
//
//			Use this interface with FPDFEMB_InitExt function.
//
struct FPDFEMB_MEMMGR_EX {
	// Interface: Alloc
	//		Allocate a memory block
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	//		size		-	Number of bytes for the memory block.
	//		flags		-	A combination of flags defined above.
	// Return Value:
	//		The pointer to allocated memory block. NULL if no memory available.
	//		If FPDFEMB_MOVABLE flag is used, implementation should return a handle
	//		to the memory block, if it supports movable block allocation.
	// Comments:
	//		The implementation should not do any action if no memory available,
	//		just return NULL. OOM handling can be done in OOM_Handler interface.
	//
	void*	(*Alloc)(struct FPDFEMB_MEMMGR_EX* pMgr, unsigned int size, int flags);

	// Interface: OOM_Handler
	//		OOM (out-of-memory) situation handler
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	// Return Value:
	//		None.
	// Comments:
	//		In order to handle OOM situation, application can use longjmp() inside 
	//		implementation of this function.
	//
	void	(*OOM_Handler)(struct FPDFEMB_MEMMGR_EX* pMgr);

	// Interfce: Realloc
	//		Reallocate a memory block
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	//		pointer		-	Pointer to an existing memory block, or handle to a movable
	//						block. Can not be NULL.
	//		new_size	-	New size (number of bytes) of the memory block. Can not be zero.
	// Return value:
	//		The pointer of reallocated memory block, it could be a new block, or just
	//		the previous block with size modified.
	//		If FPDFEMB_MOVABLE flag is used, implementation should return a handle
	//		to the memory block, if it supports movable block allocation.
	// Comments:
	//		If an existing memory block specified, the data in the memory block should
	//		be copied to the new block, if reallocated.
	//
	//		The implementation should not do any action if no memory available,
	//		just return NULL. OOM handling can be done in OOM_Handler interface.
	//
	void*	(*Realloc)(struct FPDFEMB_MEMMGR_EX* pMgr, void* pointer, unsigned int new_size, int flags);

	// Interface: Lock
	//		Lock a movable memory block
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	//		handle		-	Handle to movable memory block, returned by Alloc or Realloc.
	// Return Value:
	//		The pointer of the memory block. NULL if the block was discarded.
	// Comments:
	//		This interface is optional, if implementation doesn't support movable memory
	//		block, then this interface can be set to NULL.
	//
	void*	(*Lock)(struct FPDFEMB_MEMMGR_EX* pMgr, void* handle);

	// Interface: Unlock
	//		Unlock a locked movable memory block
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	//		handle		-	Handle to movable memory block, returned by Alloc or Realloc.
	// Return Value:
	//		None.
	// Comments:
	//		This interface is optional, if implementation doesn't support movable memory
	//		block, then this interface can be set to NULL.
	//
	void	(*Unlock)(struct FPDFEMB_MEMMGR_EX* pMgr, void* handle);

	// Interface: Free
	//		Free a memory block
	// Parameters:
	//		pMgr		-	Pointer to the memory manager.
	//		pointer		-	Pointer to an existing memory block, or handle to a movable block.
	// Return Value:
	//		None.
	//
	void	(*Free)(struct FPDFEMB_MEMMGR_EX* pMgr, void* pointer, int flags);

	void*	user;		// A user pointer, used by the application
};

// Function: FPDFEMB_LoadJbig2Decoder
// Function: FPDFEMB_LoadJpeg2000Decoder
//			Enable JBIG2 or JPEG2000 image decoder 
// Parameters:
//			None.
// Return Value:
//			None.
// Comments:
//			If you want to display JBIG2 or JPEG2000 encoded images, you need to call 
//			these functions after FPDFEMB initialized.
//
//			Calling these functions will increase code size by about 200K-400K bytes.
//			Also JPEG2000 decoder may not be available on some platforms.
//
void FPDFEMB_LoadJbig2Decoder();
void FPDFEMB_LoadJpeg2000Decoder();

// Function: FPDFEMB_InitEx
//			Initialize the FPDFEMB module with the extended memory manager
// Parameters:
//			mem_mgr		-	Pointer to memory manager structure
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			This function will allocate necessary internal data structure for
//			the whole module to operate.
FPDFEMB_RESULT FPDFEMB_InitEx(FPDFEMB_MEMMGR_EX* mem_mgr);

// Function: FPDFEMB_Exit
//			Stop using FPDFEMB module and release all resources
// Parameters:
//			None.
// Return Value:
//			None.
// Comments:
//			All loaded documents and pages will become invalid after this call.
//
//			This function is useful for OOM recovery: when your application hits
//			an OOM situation, calling this function will clear all memory allocated
//			by FPDFEMB module, then you can call one of the initialization functions,
//			reopen the document and recovery from OOM.
//
void FPDFEMB_Exit();

// Function: FPDFEMB_AllocMemory
//			Allocate memory
// Parameters:
//			size		-	Number of bytes
// Return Value:
//			The allocated buffer pointer. NULL for out of memory.
//
void* FPDFEMB_AllocMemory(unsigned int size);

// Function: FPDFEMB_FreeMemory
//			Free allocated memory
// Parameters:
//			pointer		-	Pointer returned by FPDFEMB_AllocMemory
// Return Value:
//			None.
//
void FPDFEMB_FreeMemory(void* pointer);

// Function: FPDFEMB_FreeCaches
//			Free all expendable caches used by FPDFEMB in order to save memory
// Parameters:
//			None.
// Return Value:
//			None.
// Comments:
//			When an application memory manager runs out of memory, before an OOM situation 
//			is raised, the application can try this 
//
void FPDFEMB_FreeCaches();

/********************************************************************************************
****
****		Document Operations
****
********************************************************************************************/

// Structure: FPDFEMB_FILE_ACCESS
//		Describe the way to access a file (readonly).
struct FPDFEMB_FILE_ACCESS {
	// Inteface: GetSize
	//		Get total size of the file
	// Parameters:
	//		file		-	Pointer to this file access structure
	// Return Value:
	//		File size, in bytes. Implementation can return 0 for any error.
	// 
	unsigned int	(*GetSize)(struct FPDFEMB_FILE_ACCESS* file);

	// Interface: ReadBlock
	//		Read a data block from the file
	// Parameters:
	//		file		-	Pointer to this file access structure
	//		buffer		-	Pointer to a buffer receiving read data
	//		offset		-	Byte offset for the block, from beginning of the file
	//		size		-	Number of bytes for the block.
	// Return Value:
	//		Error code, or FPDFERR_SUCCESS for success.
	//
	FPDFEMB_RESULT	(*ReadBlock)(struct FPDFEMB_FILE_ACCESS* file, void* buffer, 
									unsigned int offset, unsigned int size);

	void*		user;		// A user pointer, used by the application
};

// Structure: FPDFEMB_PAUSE
//			An interface for pausing a progressive process.
struct FPDFEMB_PAUSE {
	// Interface: NeedPauseNow
	//		Check if we need to pause a progressive proccess now
	// Parameters:
	//		pause		-	Pointer to the pause structure
	// Return Value:
	//		Non-zero for pause now, 0 for continue.
	// Comments:
	//		Typically implementation of this interface compares the current system tick
	//		with the previous one, if the time elapsed exceeds certain threshold, then
	//		the implementation returns TRUE, indicating a pause is needed.
	//
	FPDFEMB_BOOL (*NeedPauseNow)(struct FPDFEMB_PAUSE* pause);

	void*		user;		// A user pointer, used by the application
};

typedef void* FPDFEMB_DOCUMENT;

// Function: FPDFEMB_StartLoadDocument
//			Start loading a PDF document
// Parameters:
//			file		-	Pointer to file access structure.
//							This structure must be kept valid as long as the document is open.
//			password	-	Pointer to a zero-terminated byte string, for the password.
//							Or NULL for no password.
//			document	-	Receiving the document handle
//			pause		-	A callback mechanism allowing the document loading process
//							to be paused before it's finished. This can be NULL if you
//							don't want to pause.
// Return Value:
//			FPDFERR_SUCCESS: document successfully loaded.
//			FPDFERR_TOBECONTINUED: The document loading can't be finished now.
//					See comments below.
//			FPDFERR_PASSWORD: incorrect password.
//			FPDFERR_FORMAT: not a PDF or corrupted PDF.
//			FPDFERR_FILE: file access error.
//			FPDFERR_MEMORY: out of memory.
// Comments:
//			Document loading is a progressive process. It might take a long time to
//			load a document, especiall when a file is corrupted, FPDFEMB will try to
//			recover the document contents by scanning the whole file. If "pause" parameter
//			is provided, this function may return FPDFERR_TOBECONTINUED any time during
//			the document loading.
//
//			When FPDFERR_TOBECONTINUED is returned, the "document" parameter will
//			still receive a valid document handle, however, no further operations can
//			be performed on the document, except the "FPDFEMB_ContineLoadDocument" function
//			call, which resume the document loading.
//
FPDFEMB_RESULT FPDFEMB_StartLoadDocument(FPDFEMB_FILE_ACCESS* file, const char* password, 
									FPDFEMB_DOCUMENT* document, FPDFEMB_PAUSE* pause);

// Function: FPDFEMB_ContinueLoadDocument
//			Continue loading a PDF document
// Parameters:
//			document	-	Document handle returned by FPDFEMB_StartLoadDocument function
//			pause		-	A callback mechanism allowing the document loading process
//							to be paused before it's finished. This can be NULL if you
//							don't want to pause.
// Return Value:
//			FPDFERR_SUCCESS: document successfully loaded.
//			FPDFERR_TOBECONTINUED: The document loading can't be finished now.
//					Further call to this function is needed.
//			FPDFERR_PASSWORD: incorrect password.
//			FPDFERR_FORMAT: not a PDF or corrupted PDF.
//			FPDFERR_FILE: file access error.
//			FPDFERR_MEMORY: out of memory.
//			FPDFERR_STATUS: document already loaded.
//			FPDFERR_PARAM: invalid parameter (like NULL document handle)
//
FPDFEMB_RESULT FPDFEMB_ContinueLoadDocument(FPDFEMB_DOCUMENT document, FPDFEMB_PAUSE* pause);

// Function: FPDFEMB_CloseDocument
//			Close a PDF document and free all associated resources
// Parameters:
//			document	-	Document handle
// Return Value:
//			Error code. FPDFERR_SUCCESS for success.
//
FPDFEMB_RESULT FPDFEMB_CloseDocument(FPDFEMB_DOCUMENT document);

// Function: Get page count
//			Get number of pages in the document
// Parameters:
//			document	-	Document handle
// Return Value:
//			Number of pages.
//
int FPDFEMB_GetPageCount(FPDFEMB_DOCUMENT document);

// Function: FPDFEMB_SetFileBufferSize
//			Set size of internal buffer used to read from source file.
// Parameters:
//			size		-	Number of bytes
// Return Value:
//			None.
// Comments:
//			Currently FPDFEMB uses 512 bytes as default buffer size. The new buffer size 
//			takes effect next time you call FPDFEMB_StartLoadDocument.
//
void FPDFEMB_SetFileBufferSize(int size);

/********************************************************************************************
****
****		Page Basic Operations
****
********************************************************************************************/

typedef void* FPDFEMB_PAGE;

// Function: FPDFEMB_LoadPage
//			Load a page
// Parameters:
//			document	-	Document handle
//			index		-	Page index, starting from zero
//			page		-	Receiving the loaded page handler
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//
FPDFEMB_RESULT FPDFEMB_LoadPage(FPDFEMB_DOCUMENT document, int index, FPDFEMB_PAGE* page);

// Function: FPDFEMB_ClosePage
//			Close a page and release all related resources
// Parameters:
//			page		-	Page handle
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//
FPDFEMB_RESULT FPDFEMB_ClosePage(FPDFEMB_PAGE page);

// Function: FPDFEMB_GetPageSize
//			Get size of a page
// Parameters:
//			page		-	Page handle
//			width		-	Receiving page width, in hundredth of points
//			height		-	Receiving page height, in hundredth of points
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
//
FPDFEMB_RESULT FPDFEMB_GetPageSize(FPDFEMB_PAGE page, int* width, int* height);

// Structure: FPDFEMB_RECT
//			Rectangle area in device or page coordination system
//
struct FPDFEMB_RECT
{
	// For device system, coordinations are measured in pixels;
	// For page system, coordinations are measured in hundredth of points.
	int		left;
	int		top;
	int		right;
	int		bottom;
};

// Function: FPDFEMB_GetPageBBox
//			Get displayable area (bounding box) of a page
// Parameters:
//			page		-	Page handle
//			rect		-	Pointer to a structure receiving the rectangle
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
//
FPDFEMB_RESULT FPDFEMB_GetPageBBox(FPDFEMB_PAGE page, FPDFEMB_RECT* rect);

/********************************************************************************************
****
****		Page Parsing
****
********************************************************************************************/

// Function: FPDFEMB_StartParse
//			Start parsing a page, so it can get rendered or searched
// Parameters:
//			page		-	Page handle
//			text_only	-	flag for parsing texts only (used for searching)
//			pause		-	A structure that can pause the parsing process.
//							Or NULL if you don't want to pause the process.
// Return Value:
//			FPDFERR_SUCCESS: parsing successfully finished;
//			FPDFERR_TOBECONTINUED: parsing started successfully, but not finished;
//			FPDFERR_STATUS: page already parsed, or parsing already started. 
//			Other return value: error code.
// Comments:
//			Parsing is a progressive process. This function starts the parsing process,
//			and may return before parsing is finished, if a pause structure is provided.
//
//			Application should call FPDFEMB_ContinueParse repeatedly to finish the parsing
//			when return value is FPDFERR_TOBECONTINUED.
//
//			There can be only one parsing procedure active for a page, and if a page
//			has already been parsed, you can't start a parsing again.
//
FPDFEMB_RESULT FPDFEMB_StartParse(FPDFEMB_PAGE page, FPDFEMB_BOOL text_only, 
												FPDFEMB_PAUSE* pause);

// Function: FPDFEMB_ContinueParse
//			Continue the page parsing
// Parameters:
//			page		-	Page handle
//			pause		-	A structure that can pause the parsing process.
//							Or NULL if you don't want to pause the process.
// Return Value:
//			FPDFERR_SUCCESS: parsing successfully finished;
//			FPDFERR_TOBECONTINUED: parsing performed successfully, but not finished;
//			FPDFERR_STATUS: page already parsed (or parsing not started). 
//			Other return value: error code.
// Comments:
//			FPDFEMB_StartParse should be called before on the page.
//
//			Application should call FPDFEMB_ContinueParse repeatedly to finish the parsing
//			when return value is FPDFERR_TOBECONTINUED.
//
FPDFEMB_RESULT FPDFEMB_ContinueParse(FPDFEMB_PAGE page, FPDFEMB_PAUSE* pause);

// Function: FPDFEMB_GetParseProgress
//			Get an estimated parsing progress in percentage
// Parameters:
//			page		-	Page handle
// Return Value:
//			An integer between 0 and 100 (inclusive) indicating the parsing progress.
//			The result is just a rough estimation.
//
int FPDFEMB_GetParseProgress(FPDFEMB_PAGE page);

/********************************************************************************************
****
****		Page Rendering
****
********************************************************************************************/

typedef void* FPDFEMB_BITMAP;

// Function: FPDFEMB_StartQuickDraw
//			Start drawing a quick preview of a page
// Parameters:
//			dib			-	DIB handle, as the rendering device
//			page		-	Page handle. The page has to be parsed first.
//			start_x		-	Left pixel position of the display area in the device coordination
//			start_y		-	Top pixel position of the display area in the device coordination
//			size_x		-	Horizontal size (in pixels) for displaying the page
//			size_y		-	Vertical size (in pixels) for displaying the page
//			rotate		-	Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
//								2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
//			flags		-	Reserved, must be zero.
//			pause		-	Pointer to a structure that can pause the rendering process.
//							Can be NULL if no pausing is needed.
// Return Value:
//			FPDFERR_SUCCESS: quickdraw successly finished;
//			FPDFERR_TOBECONTINUED: quickdraw started successfully, but not finished.
//							FPDFEMB_ContinueQuickDraw needs to be called to finish the quickdraw;
//			FPDFERR_STATUS: quickdraw already in progress, or page not parsed;
//			Other return value: error code.
// Comments:
//			It's often useful to present user a quick preview of a page, right after the
//			page is parsed. This preview renders only a limited set of easy features in the
//			page, so it'll be rather quick to finish this process.
//
FPDFEMB_RESULT FPDFEMB_StartQuickDraw(FPDFEMB_BITMAP dib, FPDFEMB_PAGE page,
							int start_x, int start_y, int size_x, int size_y, int rotate,
							int flags, FPDFEMB_PAUSE* pause);

// Function: FPDFEMB_ContinueQuickDraw
//			Continue a quick draw processing
// Parameters:
//			page		-	Page handle. The page has to be parsed first.
//			pause		-	Pointer to a structure that can pause the rendering process.
//							Can be NULL if no pausing is needed.
// Return Value:
//			FPDFERR_SUCCESS: quickdraw successly finished;
//			FPDFERR_TOBECONTINUED: quickdraw started successfully, but not finished.
//							more calls to this function needed to finish the quickdraw;
//			FPDFERR_STATUS: quickdraw not started yet; 
//			Other return value: error code.
//
FPDFEMB_RESULT FPDFEMB_ContinueQuickDraw(FPDFEMB_PAGE page, FPDFEMB_PAUSE* pause);

#define FPDFEMB_ANNOT			0x01		// Set if annotations are to be rendered
#define FPDFEMB_LCD_TEXT		0x02		// Set if using text rendering optimized for LCD display
#define FPDFEMB_BGR_STRIPE		0x04		// Set if the device is using BGR LCD stripe

// Function: FPDFEMB_StartRender
//			Start rendering of a page.
// Parameter:
//			dib			-	DIB handle, as the rendering device
//			page		-	Page handle. The page has to be parsed first.
//			start_x		-	Left pixel position of the display area in the device coordination
//			start_y		-	Top pixel position of the display area in the device coordination
//			size_x		-	Horizontal size (in pixels) for displaying the page
//			size_y		-	Vertical size (in pixels) for displaying the page
//			rotate		-	Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
//								2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
//			flags		-	0 for normal display, or combination of flags defined above
//			clip		-	Pointer to clip rectangle (in DIB device coordinations),
//							or NULL if no clipping needed.
//			pause		-	Pointer to a structure that can pause the rendering process.
//							Can be NULL if no pausing is needed.
// Return Value:
//			FPDFERR_SUCCESS: rendering successfully finished;
//			FPDFERR_TOBECONTINUED: rendering started successfully, but not finished;
//			Other return value: error code.
// Comments:
//			Rendering is a progressive process. This function starts the rendering process,
//			and may return before rendering is finished, if a pause structure is provided.
//
//			Application should call FPDFEMB_ContinueRender repeatedly to finish the rendering 
//			when return value is FPDFERR_TOBECONTINUED.
//
//			There can be only one rendering procedure for a page at any time. And rendering
//			can be started over and over again for the same page. If a page rendering is already
//			active, starting another one will cancel the previous rendering.
//
//			Rendering of a page doesn't draw the page background, therefore, you usually need
//			to draw the background in the DIB yourself.
//
FPDFEMB_RESULT FPDFEMB_StartRender(FPDFEMB_BITMAP dib, FPDFEMB_PAGE page,
						int start_x, int start_y, int size_x, int size_y, int rotate, int flags,
						FPDFEMB_RECT* clip, FPDFEMB_PAUSE* pause);

// Function: FPDFEMB_ContinueRender
//			Continue the page rendering
// Parameters:
//			page		-	Page handle
//			pause		-	Pointer to a structure that can pause the rendering process.
//							Can be NULL if no pausing is needed.
// Return Value:
//			FPDFERR_SUCCESS: rendering successfully finished.
//			FPDFERR_TOBECONTINUED: rendering needs to be continued;
//			Other return value: error code.
// Comments:
//			This function may return any time when the pause interface indicates 
//			a pause is needed. Application can call FPDFEMB_ContinueRender any number
//			of times, until FPDFERR_TOBECONTINUED is not returned.
//
FPDFEMB_RESULT FPDFEMB_ContinueRender(FPDFEMB_PAGE page, FPDFEMB_PAUSE* pause);

// Function: FPDFEMB_GetRenderProgress
//			Get an estimated rendering progress in percentage
// Parameters:
//			page		-	Page handle
// Return Value:
//			An integer between 0 and 100 (inclusive) indicating the rendering progress.
//			The result is just a rough estimation.
//			If the rendering just finished, this function will return 0.
//
int FPDFEMB_GetRenderProgress(FPDFEMB_PAGE page);

// Function: FPDFEMB_SetHalftoneLimit
//			Set pixel count limit for using halftone when display image
// Parameter:
//			limit		-	Number of pixels for the limit
// Return Value:
//			None.
// Comments:
//			By default, FPDFEMB displays all bitmaps using downsamping, which means
//			if the image is shrinked onto screen, only part of pixels will be picked
//			and displayed. This saves a lot of calculation, especially for big images
//			with millions of pixels. However the display quality can be bad. In order to
//			reach a balance between performance and quality, application can use this
//			function to set a limit, if number of pixels in an image is more than this
//			limit, then FPDFEMB will use downsampling for quick drawing, otherwise, if
//			the image has less pixels, FPDFEMB will use halftoning for better quality.
//
void FPDFEMB_SetHalftoneLimit(int limit);

/********************************************************************************************
****
****		Coordination Conversion
****
********************************************************************************************/

// Structure: FPDFEMB_POINT
//			A point in device or page coordination system
//
struct FPDFEMB_POINT
{
	// For device system, coordinations are measured in pixels;
	// For page system, coordinations are measured hundredth of points.
	int		x;
	int		y;
};

// Function: FPDFEMB_DeviceToPagePoint, FPDFEMB_DeviceToPageRect
//			Convert the device coordinations of a point or a rectangle to page coordinations.
// Parameters:
//			page		-	Handle to the page. Returned by FPDFEMB_LoadPage function.
//			start_x		-	Left pixel position of the display area in the device coordination
//			start_y		-	Top pixel position of the display area in the device coordination
//			size_x		-	Horizontal size (in pixels) for displaying the page
//			size_y		-	Vertical size (in pixels) for displaying the page
//			rotate		-	Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
//								2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
//			point		-	A point structure with device coordinations upon the call,
//							also receiving the result page coordinations.
//			rect		-	A rectangle structure with device coordinations upon the call,
//							also receiving the result page coordinations.
// Return value:
//			None.
// Comments:
//			The page coordination system has its origin at left-bottom corner of the page, 
//			with X axis goes along the bottom side to the right, and Y axis goes along the 
//			left side upward. No matter how you zoom, scroll, or rotate a page, a particular
//			element (like text or image) on the page should always have the same coordination 
//			values in the page coordination system. 
//
//			The device coordination system is device dependant. For bitmap device, its origin 
//			is at left-top corner of the window. You must make sure the start_x, start_y, size_x, 
//			size_y and rotate parameters have exactly same values as you used in 
//			FPDFEMB_StartRender() function call.
//
//			For rectangle conversion, the result rectangle is always "normalized", meaning for
//			page coordinations, left is always smaller than right, bottom is smaller than top.
//
void FPDFEMB_DeviceToPagePoint(FPDFEMB_PAGE page, 
						int start_x, int start_y, int size_x, int size_y, int rotate, 
						FPDFEMB_POINT* point);

void FPDFEMB_DeviceToPageRect(FPDFEMB_PAGE page, 
						int start_x, int start_y, int size_x, int size_y, int rotate, 
						FPDFEMB_RECT* rect);

// Function: FPDFEMB_PageToDevicePoint, FPDFEMB_PageToDeviceRect
//			Convert the page coordinations of a point or a rectangle to device coordinations.
// Parameters:
//			page		-	Handle to the page. Returned by FPDFEMB_LoadPage function.
//			start_x		-	Left pixel position of the display area in the device coordination
//			start_y		-	Top pixel position of the display area in the device coordination
//			size_x		-	Horizontal size (in pixels) for displaying the page
//			size_y		-	Vertical size (in pixels) for displaying the page
//			rotate		-	Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
//								2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
//			point		-	A point structure with page coordinations upon the call,
//							also receiving the result device coordinations.
//			rect		-	A rectangle structure with page coordinations upon the call,
//							also receiving the result device coordinations.
// Return value:
//			None
// Comments:
//			For rectangle conversion, the result rectangle is always "normalized", meaning for
//			device coordinations, left is always smaller than right, top is smaller than bottom.
//
void FPDFEMB_PageToDevicePoint(FPDFEMB_PAGE page, 
						int start_x, int start_y, int size_x, int size_y, int rotate, 
						FPDFEMB_POINT* point);

void FPDFEMB_PageToDeviceRect(FPDFEMB_PAGE page, 
						int start_x, int start_y, int size_x, int size_y, int rotate, 
						FPDFEMB_RECT* rect);

/********************************************************************************************
****
****		Text Search
****
********************************************************************************************/

// Search flags for FPDFEMB_FindFirst function
#define FPDFEMB_MATCHCASE		1		// whether matching case
#define FPDFEMB_MATCHWHOLEWORD	2		// whether matching whole word
#define FPDFEMB_CONSECUTIVE		4		// whether matching consecutively (for example, "CC" will
										// match twice in "CCC").

// Function: FPDFEMB_FindFirst
//			Find first occurance of a pattern string in a page
// Parameters:
//			page		-	Page handle.
//			pattern		-	A zero-terminated unicode string to be found. 
//			from_last	-	Whether we start from the end of page
//			flags		-	Search flags, see above defined constants
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//			Is not found, FPDFERR_NOTFOUND is returned.
// Comments:
//			A page must be parsed first before it can be searched.
//			There can be only one search in progress for a page. A new search will 
//			cancel the previous one.
//
//			IMPORTANT: this function is now obsolete and kept for back compatibility
//			only, please use FPDFEMB_FindFrom function below.
//
FPDFEMB_RESULT FPDFEMB_FindFirst(FPDFEMB_PAGE page, const FPDFEMB_WCHAR* pattern, 
								 FPDFEMB_BOOL from_last, unsigned int flags);

// Function: FPDFEMB_FindFrom
//			Find first occurance of a pattern string in a page, from a particular position
// Parameters:
//			page		-	Page handle.
//			pattern		-	A zero-terminated unicode string to be found. 
//			pos			-	The position, returned from FPDFEMB_GetSearchPos.
//							Or 0 from the beginning of page, -1 from the end of page.
//			flags		-	Search flags, see above defined constants
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//			Is not found, FPDFERR_NOTFOUND is returned.
// Comments:
//			A page must be parsed first before it can be searched.
//			There can be only one search in progress for a page. A new search will 
//			cancel the previous one.
//
FPDFEMB_RESULT FPDFEMB_FindFrom(FPDFEMB_PAGE page, const FPDFEMB_WCHAR* pattern, 
								 int pos, unsigned int flags);

// Function: FPDFEMB_FindNext
//			Find next occurance of a search
// Parameters:
//			page		-	Page handle. 
//							FPDFEMB_FindFirst must be called for this page first.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//			Is not found, FPDFERR_NOTFOUND is returned.
//
FPDFEMB_RESULT FPDFEMB_FindNext(FPDFEMB_PAGE page);

// Function: FPDFEMB_FindPrev
//			Find previous occurance of a search
// Parameters:
//			page		-	Page handle.
//							FPDFEMB_FindFirst must be called for this page first.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//			Is not found, FPDFERR_NOTFOUND is returned.
//
FPDFEMB_RESULT FPDFEMB_FindPrev(FPDFEMB_PAGE page);

// Function: FPDFEMB_CountFoundRects
//			Get number of rectangles for last found result
// Parameters:
//			page		-	Page handle.
// Return Value:
//			Number of rectangles for last found result. 0 for not found or failure.
//
int FPDFEMB_CountFoundRects(FPDFEMB_PAGE page);

// Function: FPDFEMB_GetFoundRect
//			Get a particular found rectangle
// Parameters:
//			page		-	Page handle.
//			index		-	Zero-based index for the rectangle.
//			rect		-	Receiving the result rectangle, in hundredth of points
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			Application should always call FPDFEMB_CountFoundRects first to get
//			number of rectangles, then use this function to get each rectangle.
//
//			The returned rectangle uses page coordination system.
//
FPDFEMB_RESULT FPDFEMB_GetFoundRect(FPDFEMB_PAGE page, int index, FPDFEMB_RECT* rect);

// Function: FPDFEMB_GetSearchPos
//			Return position of current search result
// Parameters:
//			page		-	Page handle.
// Return Value:
//			Zero based character index for the current search result. -1 if not found.
//
int FPDFEMB_GetSearchPos(FPDFEMB_PAGE page);

// Function: FPDFEMB_QuickSearch
//			Search a pattern in a page quickly, without the page to be parsed
// Parameters:
//			document	-	Document handle returned by FPDFEMB_StartLoadDocument function
//			page_index	-	Zero-based index of the page
//			pattern		-	A zero-terminated unicode string to be found. 
//			case_sensitive	-	Non-zero for case-sensitive searching, zero for case-insensitive
// Return Value:
//			FPDFERR_SUCCESS if pattern found, FPDFERR_NOTFOUND if pattern not found.
//			Otherwise error code is returned.
// Comments:
//			This function does a rough and quick search in a page, before the page is loaded. 
//			The quick search will not generate an exact result saying where the pattern is
//			found, and, it might be possible if a quick search result is "pattern found", and
//			a real search for the same pattern, in the same page, will result in "not found".
//
//			However, if quick search doesn't find a pattern in a page, then we can be sure the
//			pattern won't be found in this page when we do a real search. So, this function is 
//			very useful when we search in a multiple-page document, and we want to quickly skip
//			those pages in which the pattern can't possibly be found.
//
FPDFEMB_RESULT FPDFEMB_QuickSearch(FPDFEMB_DOCUMENT document, int page_index, 
								   const FPDFEMB_WCHAR* pattern, int case_sensitive);

/********************************************************************************************
****
****		Text Information
****
********************************************************************************************/

// Function: FPDFEMB_GetCharCount
//			Get number of characters in the page
// Parameters:
//			page		-	Page handle
//			count		-	Receiving number of characters
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//
FPDFEMB_RESULT FPDFEMB_GetCharCount(FPDFEMB_PAGE page, int* count);

// Structure: FPDFEMB_CHAR_INFO
//			Character information.
struct FPDFEMB_CHAR_INFO {
	int		unicode;		// Unicode for the character. 0 if not available.
							// Space and new line charcters (U+0020 and U+000A) may be generated
							// according to the text formatting.
	FPDFEMB_POINT	origin;	// X/Y position for the character origin, in hundredth of points
	FPDFEMB_RECT	bbox;	// Bounding box of the character, in hundredth of points
							// Maybe an empty box (left == right or top == bottom).
};

// Function: FPDFEMB_GetCharInfo
//			Get character information
// Parameters:
//			page		-	Page handle
//			index		-	Character index, starting from zero
//			char_info	-	Receiving the character info
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
// Comments:
//			Application must call FPDFEMB_GetCharCount first before it can call this function
//			for any particular characters.
//			
FPDFEMB_RESULT FPDFEMB_GetCharInfo(FPDFEMB_PAGE page, int index, FPDFEMB_CHAR_INFO* char_info);

// Function: FPDFEMB_GetCharIndexAtPos()
//			Get index of character nearest to a certain position on the page
// Parameters:
//			page		-	Page handle
//			x			-	X position in PDF page coordination system
//			y			-	Y position in PDF page coordination system
//			index		-	Pointer to an integer receiving zero-based character index.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
// Comments:
//			This function finds the character that's nearest to the particular page position.
//			If there is no character, the output index will be -1.
//			
FPDFEMB_RESULT FPDFEMB_GetCharIndexAtPos(FPDFEMB_PAGE page, double x, double y, int* index);

/********************************************************************************************
****
****		Device Independant Bitmap
****
********************************************************************************************/

#define FPDFDIB_BGR		1	// 3 bytes per pixel, byte order: Blue, Green, Red
#define FPDFDIB_BGRx	2	// 4 bytes per pixel, byte order: Blue, Green, Red, not used
#define FPDFDIB_BGRA	3	// 4 bytes per pixel, byte order: Blue, Green, Red, Alpha
#define FPDFDIB_GRAY	4	// 1 byte per pixel (grayscale)

// Function: FPDFEMB_CreateDIB
//			Create a DIB (Device Independant Bitmap)
// Parameters:
//			width		-	Width pixels;
//			height		-	Height pixels;
//			format		-	Format type. See FPDFDIB_xxx constants
//			buffer		-	External buffer provided for the DIB,
//							or NULL if new buffer is to be allocated.
//			stride		-	Number of bytes for each scan line, for external buffer only.
//							If not specified, 4-byte alignment assumed.
//			dib			-	Receiving the created DIB handle
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
// Comments:
//			If "buffer" parameter is not NULL, then the provided buffer must conform
//			to standard DIB format (see comments of FPDFEMB_GetDIBData function below).
//
//			This function doesn't initialize the pixels inside the DIB buffer. So if you
//			want to use the DIB to display a PDF page, you usually need to initialize
//			the DIB to white background by youself.
//
FPDFEMB_RESULT FPDFEMB_CreateDIB(int width, int height, int format, 
									   void* buffer, int stride, FPDFEMB_BITMAP* dib);

// Function: FPDFEMB_DestroyDIB
//			Destroy a DIB
// Parameters:
//			dib			-	DIB handle
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
// Comments:
//			If external buffer is used (specified in "buffer" parameter when calling
//			FPDFEMB_CreateDIB), the buffer will not be destroyed.
//
FPDFEMB_RESULT FPDFEMB_DestroyDIB(FPDFEMB_BITMAP dib);

// Function: FPDFEMB_GetDIBWidth
//			Get width (in pixels) of a DIB
// Parameters:
//			dib			-	DIB handle
// Return Value:
//			DIB width in pixels.
//
int FPDFEMB_GetDIBWidth(FPDFEMB_BITMAP dib);

// Function: FPDFEMB_GetDIBHeight
//			Get height (in pixels) of a DIB
// Parameters:
//			dib			-	DIB handle
// Return Value:
//			DIB height in pixels.
//
int FPDFEMB_GetDIBHeight(FPDFEMB_BITMAP dib);

// Function: FPDFEMB_GetDIBData
//			Get data pointer to a DIB
// Parameters:
//			dib			-	DIB handle
// Return Value:
//			Pointer to the DIB data.
// Comments:
//			DIB data are organized in scanlines, from top down.
//
void* FPDFEMB_GetDIBData(FPDFEMB_BITMAP dib);

// Function: FPDFEMB_GetDIBStride
//			Get scan line stride of a DIB
// Parameters:
//			dib			-	DIB handle
// Return Value:
//			Number of bytes occupied by a scanline
//
int FPDFEMB_GetDIBStride(FPDFEMB_BITMAP dib);

// Function: FPDFEMB_GetRotatedDIB
//			Swap X/Y dimensions of a DIB to generate a rotated new DIB
// Parameters:
//			dib			-	DIB handle
//			flip_x		-	Whether flip pixels on the destination X dimension (left/right)
//			flip_y		-	Whether flip pixels on the destination Y dimension (up/down)
//			result_dib	-	Receiving the result DIB handle
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
//
FPDFEMB_RESULT FPDFEMB_GetRotatedDIB(FPDFEMB_BITMAP dib, 
									 FPDFEMB_BOOL bFlipX, FPDFEMB_BOOL bFlipY,
									 FPDFEMB_BITMAP* result_dib);

// Function: FPDFEMB_StretchDIB
//			Stretch a source DIB into another destination DIB
// Parameters:
//			dest_dib	-	The destination DIB handle
//			dest_left	-	Left position in the destination DIB
//			dest_top	-	Top position in the destination DIB
//			dest_width	-	Destination width, in pixels. Can be negative for horizontal flipping
//			dest_height	-	Destination height, in pixels. Can be negative for vertical flipping
//			clip		-	Destination clipping rectangle, or NULL for no clipping.
//							The coordinations are measured in destination bitmap.
//			src_dib		-	Source DIB handle.
//			interpol	-	Whether we use interpolation to improve the result quality
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
//
FPDFEMB_RESULT FPDFEMB_StretchDIB(FPDFEMB_BITMAP dest_dib, int dest_left, int dest_top,
								  int dest_width, int dest_height, FPDFEMB_RECT* clip_rect, 
								  FPDFEMB_BITMAP src_dib, FPDFEMB_BOOL interpol);

// Function: FPDFEMB_TransformDIB
//			Transform a source DIB into another destination DIB
// Parameters:
//			dest_dib	-	The destination DIB handle
//			clip		-	Destination clipping rectangle, or NULL for no clipping.
//							The coordinations are measured in destination bitmap.
//			src_dib		-	Source DIB handle.
//			x			-	X coordination of the dest origin
//			y			-	Y coordination of the dest origin
//			xx			-	X distance of the dest X vector
//			yx			-	Y distance of the dest X vector
//			xy			-	X distance of the dest Y vector
//			yy			-	Y distance of the dest Y vector
//			interpol	-	Whether we use interpolation to improve the result quality
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
// Comments:
//			All coordinations and distances are measured in destination bitmap system.
//
//			This function places the bottom-left pixel of the image at the destination
//			origin, then the bottom sideline along the destination X vector, and left 
//			sideline along the destination Y vector.
//			
FPDFEMB_RESULT FPDFEMB_TransformDIB(FPDFEMB_BITMAP dest_dib, FPDFEMB_RECT* clip_rect, 
								  FPDFEMB_BITMAP src_dib, int x, int y, int xx, int yx,
								  int xy, int yy, FPDFEMB_BOOL interpol);

/********************************************************************************************
****
****		Custom Font Handler and CJK Support
****
********************************************************************************************/

// FPDFEMB comes with standard fonts for Latin characters. If your device is targeted to
// Eastern Asian markets, then system fonts must be provided and registered with FPDFEMB.
// Depending on your device configuration, those system fonts might be in TrueType or Type1
// format, or some other non-standard compact format. For the first case, you should register
// a font mapper so FPDFEMB can pick the right font file, and for the second case, you
// should register a glyph provider so FPDFEMB can get glyph bitmap for each character.

#define FPDFEMB_CHARSET_DEFAULT		0
#define FPDFEMB_CHARSET_GB			936
#define FPDFEMB_CHARSET_BIG5		950
#define FPDFEMB_CHARSET_JIS			932
#define FPDFEMB_CHARSET_KOREA		949
#define FPDFEMB_CHARSET_UNICODE		1200

#define FPDFEMB_FONT_FIXEDPITCH		1
#define FPDFEMB_FONT_SERIF			2
#define FPDFEMB_FONT_SYMBOLIC		4
#define FPDFEMB_FONT_SCRIPT			8
#define FPDFEMB_FONT_NONSYMBOLIC	32
#define FPDFEMB_FONT_ITALIC			64
#define FPDFEMB_FONT_ALLCAP			0x10000
#define FPDFEMB_FONT_SMALLCAP		0x20000
#define FPDFEMB_FONT_FORCEBOLD		0x40000

// Structure: FPDFEMB_FONT_MAPPER
//			Defines interface for system font mapper.
//
struct FPDFEMB_FONT_MAPPER
{
	// Interface: MapFont
	//		Find font file path for a particular PDF font
	// Parameters:
	//		mapper		-	Pointer to the FPDFEMB_FONT_MAPPER structure
	//		name		-	Font name
	//		charset		-	Charset ID (see above FPDFEMB_CHARSET_xxx constants)
	//		flags		-	Font flags (see above FPDFEMB_FONT_xxx constants)
	//		weight		-	Weight of the font. Range from 100 to 900. 400 is normal,
	//						700 is bold.
	//		path		-	Receiving the full file path. The buffer size is 512 bytes.
	//		face_index	-	Receiving an zero-based index value for the font face, if the 
	//						mapped font file is a "collection" (meaning a number of faces 
	//						are stored in the same file). If the font file is not a 
	//						collection, the index value should be zero.
	// Return Value:
	//		Non-zero for success, 0 for failure.
	//
	FPDFEMB_BOOL	(*MapFont)(struct FPDFEMB_FONT_MAPPER* mapper, const char* name, int charset,
									unsigned int flags,	int weight,
									char* path, int* face_index);

	void*		user;		// A user pointer, used by the application
};

// Function: FPDFEMB_SetFontMapper
//			Use a system font mapper (typically for Chinese/Japanese/Korean charsets)
// Parameters:
//			mapper		-	Pointer to FPDFEMB_FONT_MAPPER structure.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
// Comments:
//			This function is used with devices that come with one or more system fonts,
//			and those fonts are in standard TT or T1 format.
//
FPDFEMB_RESULT FPDFEMB_SetFontMapper(FPDFEMB_FONT_MAPPER* mapper);

// Structure: FPDFEMB_GLYPH_PROVIDER
//			Interface for providing glyph bitmap of non-latin characters.
//			This is usually used for embedded devices with Chinese/Japanese/Korean 
//			fonts installed, but those fonts are not in TrueType or Type1 format.
//
struct FPDFEMB_GLYPH_PROVIDER
{
	// Interface: MapFont
	//		Return an internal handle for a font
	// Parameters:
	//		provider	-	Pointer to this structure
	//		name		-	Font name
	//		charset		-	Charset ID (see above FPDFEMB_CHARSET_xxx constants)
	//		flags		-	Font flags (see above FPDFEMB_FONT_xxx constants)
	//		weight		-	Weight of the font. Range from 100 to 900. 400 is normal,
	//						700 is bold.
	// Return Value:
	//		An internal handle to the mapped font. If the embedded device supports
	//		multiple fonts, then this value can serve as an identifier to differentiate
	//		among them. If the device supports only one font, then implementation of
	//		this function can simply return NULL.
	//
	void*	(*MapFont)(struct FPDFEMB_GLYPH_PROVIDER* provider, const char* name, int charset,
									unsigned int flags,	int weight);
	// Interface: GetGlyphBBox
	//		Get glyph bounding box
	// Parameters:
	//		provider	-	Pointer to this structure
	//		font		-	Internal handle to the font. Returned by MapFont interface.
	//		unicode		-	Unicode of the character
	//		CID			-	Adobe CID for this character. Or zero if not available.
	//		bbox		-	Receiving the result bounding box. See comments below.
	// Return Value:
	//		None.
	// Comments:
	//		The bounding box is measure in a glyph coordination system, in which the
	//		origin is set to character origin, and unit is set to one-thousandth of
	//		"em size" (representing the font size).
	//
	//		In most CJK fonts, all CJK characters (except some symbols or western 
	//		characters) have same glyph bounding box:
	//		left = 0, right = 1000, bottom = -220, top = 780.
	//
	//		It's OK to return a box that's larger than the actual glyph box.
	//
	void	(*GetGlyphBBox)(struct FPDFEMB_GLYPH_PROVIDER* provider, void* font,
									FPDFEMB_WCHAR unicode, unsigned short CID,
									FPDFEMB_RECT* bbox);

	// Interface: GetGlyphBitmap
	//		Get bitmap of a glyph
	// Parameters:
	//		provider	-	Pointer to this structure
	//		font		-	Internal handle to the font. Returned by MapFont interface.
	//		unicode		-	Unicode of the character
	//		CID			-	Adobe CID for this character. Or zero if not available.
	//		font_width	-	Width of the font em square, measured in device units.
	//		font_height	-	Height of the font em square, measured in device units.
	//		left		-	Receiving the left offset, from the character origin, of the
	//						result glyph bitmap. Positive value will move the bitmap to
	//						the right side, negative to the left.
	//		top			-	Receiving the top offset, from the character origin, of the
	//						result glyph bitmap. Positive value will move the bitmap upward,
	//						negative downward.
	//		bitmap_width -	Receiving number of width pixels in the result bitmap
	//		bitmap_height -	Receiving number of height pixels in the result bitmap
	//		buffer		-	Receiving a data buffer pointer, allocated by the implementation.
	//						See comments below.
	//		stride		-	Receiving number of bytes per scanline, in the data buffer.
	//		pdf_width	-	Width of the character specified in PDF. It is measured in one-
	//						thousandth of the font width. It can be 0 if width not specified
	//						in PDF. See comments below.
	// Return Value:
	//		Non-zero for success. 0 for failure. In this case the glyph can not be displayed.
	// Comments:
	//		The buffer should be allocated by implemenation. And it must be allocated
	//		using FPDFEMB_AllocMemory function. The result buffer will be destroyed by
	//		FPDFEMB SDK, so implementation should not destroy it.
	//
	//		The implementation should write "coverage" data into allocated buffer, one byte 
	//		for each pixel, from top scanline to bottom scanline, within each scan line, 
	//		from left pixel to right. Coverage 0 means the pixel is outside the glyph, 
	//		coverage 255 means the pixel is inside the glyph.
	//
	//		The "pdf_width" parameter can be used to scale the character in system font
	//		horizontally to match the font width specified in PDF. For example, if we have
	//		a PDF file which requires a character in half-width (pdf_width is 500), but
	//		in the system font the character has full-width (1000), then the glyph provider
	//		implementation should scale the font horizontally to half of its original width.
	//
	FPDFEMB_BOOL (*GetGlyphBitmap)(struct FPDFEMB_GLYPH_PROVIDER* provider, void* font,
									FPDFEMB_WCHAR unicode, unsigned short CID,
									double font_width, double font_height, int* left, int* top,
									int* bitmap_width, int* bitmap_height, 
									void** buffer, int* stride, int pdf_width);

	void*		user;		// A user pointer, used by the application
};

// Function: FPDFEMB_SetGlyphProvider
//			Make use of a glyph provider: generating glyph bitmap for non-Latin characters
// Parameters:
//			provider	-	Pointer to the glyph provider structure.
//							This structure must stay valid throughout usage of FPDFEMB module.
// Return Value:
//			None.
// Comments:
//			FPDFEMB embeds some standard fonts for Latin characters and symbols, like
//			Times, Courier and Helvetica (Arial). For non-Latin characters, however,
//			FPDFEMB has to ask glyph provide for help.
//
//			If an embedded device carries fonts for non-Latin character sets, especially
//			those for CJK markets, then the application can implement a glyph provider,
//			allowing PDFs using non-embedded CJK fonts to be properly displayed.
//
void FPDFEMB_SetGlyphProvider(FPDFEMB_GLYPH_PROVIDER* provider);

// Function: FPDFEMB_LoadCMap_GB
// Function: FPDFEMB_LoadCMap_GB_Ext
// Function: FPDFEMB_LoadCMap_CNS
// Function: FPDFEMB_LoadCMap_Korean
// Function: FPDFEMB_LoadCMap_Japan
// Function: FPDFEMB_LoadCMap_Japan_Ext
//			Make use of character encoding maps embedded with FPDFEMB
// Parameters:
//			None.
// Return Value:
//			None.
// Comments:
//			These functions add character encoding data to your application. Each call
//			will increase the code size of your application. Total data size for all
//			character sets is 151K bytes.
void FPDFEMB_LoadCMap_GB();
void FPDFEMB_LoadCMap_GB_Ext();		// Load full code table for GB
void FPDFEMB_LoadCMap_CNS();
void FPDFEMB_LoadCMap_Korea();
void FPDFEMB_LoadCMap_Japan();
void FPDFEMB_LoadCMap_Japan_Ext();	// Load full code table for Japan

/********************************************************************************************
****
****		Document Information
****
********************************************************************************************/

// Function: PDFEMB_GetDocInfoString
//			Get information string about the document, like creator, modifcation date, etc.
// Parameters:
//			document	-	Handle to the document
//			key			-	A byte string for the information key. Currently can be one of the followings:
//							"Title", "Author", "Subject", "Keywords", "Creator", "Producer", "CreationDate",
//							"ModDate", or some custom information key, if supported by the PDF file.
//			buffer		-	A buffer allocated by the application, or NULL.
//			bufsize		-	[IN/OUT] A pointer to a number indicating the buffer size (number of bytes),
//							before this function call. After return, this place will store
//							number of bytes used by the output (including terminator).
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
// Comments:
//			The string is output in Unicode, using UTF-16LE format. It's terminated by
//			two consecutive zero bytes.
//
//			If the "buffer" parameter is NULL, then the "bufsize" parameter will receive
//			number of bytes required to store the string (including the two-byte terminator).
//
FPDFEMB_RESULT FPDFEMB_GetDocInfoString(FPDFEMB_DOCUMENT document, const char* key, void* buffer, unsigned int* bufsize);

/********************************************************************************************
****
****		Action (Destination) Information
****
********************************************************************************************/

typedef void* FPDFEMB_ACTION;

// Action types supported by FPDFEMB
#define FPDFEMB_DEST_NONE			0		// No or unsupported destination
#define FPDFEMB_DEST_PAGE			1		// A page inside the same document
#define FPDFEMB_DEST_DOC			2		// An external PDF document
#define FPDFEMB_DEST_URL			3		// An external URL
#define FPDFEMB_ACTION_LAUNCH		4		// Launch an external file or command

// Zoom mode for destination
#define FPDFEMB_ZOOM_NONE			0		// Zoom mode not specified
#define FPDFEMB_ZOOM_FACTOR			1		// Specific zoom factor is used
#define FPDFEMB_ZOOM_FITPAGE		2		// Fit the whole page on screen
#define FPDFEMB_ZOOM_FITWIDTH		3		// Fit width of the page on screen
#define FPDFEMB_ZOOM_FITHEIGHT		4		// Fit height of the page on screen
#define FPDFEMB_ZOOM_FITRECT		5		// Fit a particular rectangle on screen
#define FPDFEMB_ZOOM_FITCONTENT		6		// Fit whole content of page on screen
#define FPDFEMB_ZOOM_FITCONTENTW	7		// Fit content width of page on screen
#define FPDFEMB_ZOOM_FITCONTENTH	8		// Fit content height of page on screen

// Data structure for page destination
struct FPDFEMB_PAGEDEST
{
	int				page_index;		// Zero based index for the page
	int				zoom_mode;		// See FPDFEMB_ZOOM_xxx definition above
	int				zoom_factor;	// For FPDFEMB_ZOOM_FACTOR only: the zoom factor (in percentage)
	FPDFEMB_RECT	position;		// Specify position inside the page. Depends on the zoom mode,
									// different members of the rectangle are used:
									// FPDFEMB_ZOOM_NONE:			left, top
									// FPDFEMB_ZOOM_FACTOR:			left, top
									// FPDFEMB_ZOOM_FITPAGE:		none
									// FPDFEMB_ZOOM_FITWIDTH:		top
									// FPDFEMB_ZOOM_FITHEIGHT:		left
									// FPDFEMB_ZOOM_FITRECT:		left, top, bottom, right
									// FPDFEMB_ZOOM_FITCONTENT:		none
									// FPDFEMB_ZOOM_FITCONTENTW:	top
									// FPDFEMB_ZOOM_FITCONTENTH:	left
};

// Data structure for document destination
struct FPDFEMB_DOCDEST
{
	FPDFEMB_PAGEDEST	page_data;	// page data
	char*				file_name;	// The file name, encoded in original charset (maybe MBCS)
};

// Data structure for URL destination
struct FPDFEMB_URLDEST
{
	char*				url;		// URL encoded in 7-bit ASCII
};

// Data structure for Launch action
struct FPDFEMB_LAUNCHACTION
{
	int					new_window;	// Whether a new window should be opened
	char*				file_name;	// The file name, encoded in original charset (maybe MBCS)
};

// Function: FPDFEMB_Action_GetType
//			Get type of an action
// Parameters:
//			document	-	Handle to the document
//			action		-	Handle to the action
//			dest_type	-	Pointer to an integer receiving type of the destination. See the above
//							FPDFEMB_DEST_xxx definitions
//			data_size	-	Pointer to an integer receiving data block size for the destination.
//							If this parameter is NULL, then data size won't be retrieved.
// Comments:
//			Each different type of destination has different data structure. The "data_size" result
//			indicates how many bytes is required to hold the destination data structure. The application
//			can then allocate sufficient buffer and then call FPDFEMB_Bookmark_GetDest function to
//			get the real data.
//
FPDFEMB_RESULT FPDFEMB_Action_GetType(FPDFEMB_DOCUMENT document, FPDFEMB_ACTION action, int* dest_type, int* data_size);

// Function: FPDFEMB_Action_GetData
//			Get detailed data of a particular action
// Parameters:
//			document	-	Handle to the document
//			action		-	Handle to the action
//			buffer		-	Application allocated buffer receiving the destination data
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			See data structure definition for different action type above. Please note
//			the actual action data might use more space than the structure definition
//			shows, to store things like file name or URL. So you should always call
//			FPDFEMB_Action_GetType first to get data size then allocate enough buffer
//			for this call.
//
FPDFEMB_RESULT FPDFEMB_Action_GetData(FPDFEMB_DOCUMENT document, FPDFEMB_ACTION action, void* buffer);

// Function: FPDFEMB_Action_GetNext
//			Get next action in an action chain
// Parameters:
//			document	-	Handle to the document
//			action		-	Handle to current action
//			next		-	Receiving handle to next action.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			If there is no next action, the "next" parameter will be set to NULL after the function returns.
//
FPDFEMB_RESULT FPDFEMB_Action_GetNext(FPDFEMB_ACTION action, FPDFEMB_ACTION* next);

/********************************************************************************************
****
****		Bookmark Information
****
********************************************************************************************/

typedef void* FPDFEMB_BOOKMARK;

// Function: FPDFEMB_Bookmark_GetFirstChild
//			Get first child of a bookmark item, or first top level bookmark item
// Parameters: 
//			document	-	Handle to the document
//			parent		-	Handle to the parent bookmark. 
//							Can be NULL if you want to get the first top level item.
//			bookmark	-	Receiving handle to the first child or top level bookmark item. 
//							If result is NULL, then bookmark not found.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
//
FPDFEMB_RESULT FPDFEMB_Bookmark_GetFirstChild(FPDFEMB_DOCUMENT document, FPDFEMB_BOOKMARK parent,
											  FPDFEMB_BOOKMARK* bookmark);

// Function: FPDFEMB_Bookmark_GetFirstChild
//			Get next sibling of a bookmark item
// Parameters: 
//			document	-	Handle to the document
//			bookmark	-	Handle to the bookmark 
//			sibling		-	Receiving the handle of next sibling.
//							If result is NULL, then this is the last bookmark in this level.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
//
FPDFEMB_RESULT FPDFEMB_Bookmark_GetNextSibling(FPDFEMB_DOCUMENT document, FPDFEMB_BOOKMARK bookmark,
											  FPDFEMB_BOOKMARK* sibling);

// Function: FPDFEMB_Bookmark_GetTitle
//			Get title of a bookmark
// Parameters: 
//			bookmark	-	Handle to the bookmark 
//			buffer		-	A buffer allocated by the application, or NULL.
//			bufsize		-	[IN/OUT] A pointer to a number indicating the buffer size,
//							before this function call. After return, this place will store
//							number of bytes used by the output (including terminator).
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
// Comments:
//			The title is output in Unicode, using UTF-16LE format. It's terminated by
//			two consecutive zero bytes.
//
//			If the "buffer" parameter is NULL, then the "bufsize" parameter will receive
//			number of bytes required to store the bookmark title (including the two-
//			byte terminator).
//
//			If the buffer provided is smaller than the required size, then this function
//			will not copy any data, return FPDFEMB_PARAM, and the required buffer size will 
//			also be put in "bufsize" parameter.
//
FPDFEMB_RESULT FPDFEMB_Bookmark_GetTitle(FPDFEMB_BOOKMARK bookmark, void* buffer, unsigned int* bufsize);

// Function: FPDFEMB_Bookmark_GetPage
//			Get page number of a bookmark pointing to
// Parameters:
//			document	-	Handle to the document
//			bookmark	-	Handle to the bookmark 
//			page		-	Receiving the page number. -1 if this bookmark doesn't actually
//							point to a page inside the document.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success
// Comments:
//			Some bookmark might not point to a page, some bookmark might have more than one destination
//			(action), for detailed information about a bookmark, you should call FPDFEMB_Bookmark_GetAction.
//
FPDFEMB_RESULT FPDFEMB_Bookmark_GetPage(FPDFEMB_DOCUMENT document, FPDFEMB_BOOKMARK bookmark, int* page);

// Function: FPDFEMB_Bookmark_GetAction
//			Get action(s) associated with a particular bookmark
// Parameters:
//			document	-	Handle to the document
//			bookmark	-	Handle to the bookmark 
//			action		-	Receiving handle of first action
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//
FPDFEMB_RESULT FPDFEMB_Bookmark_GetAction(FPDFEMB_DOCUMENT document, FPDFEMB_BOOKMARK bookmark, FPDFEMB_ACTION* action);

/********************************************************************************************
****
****		Hyperlink Information
****
********************************************************************************************/

// Function: FPDFEMB_Link_GetCount
//			Get number of hyperlinks inside a page
// Parameters:
//			page		-	Page handle.
//			link_count	-	Pointer to an integer receiving the number of links
//			reserved	-	Must be zero now.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			This function must be called before any other link related function can
//			be called for the page.
//
FPDFEMB_RESULT FPDFEMB_Link_GetCount(FPDFEMB_PAGE page, int* link_count, int reserved);

// Function: FPDFEMB_Link_GetAction
//			Get action(s) associated with a particular hyperlink
// Parameters:
//			page		-	Page handle
//			link_index	-	Zero-based index for the link
//			action		-	Receiving handle of first action
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//
FPDFEMB_RESULT FPDFEMB_Link_GetAction(FPDFEMB_PAGE page, int link_index, FPDFEMB_ACTION* action);

// Function: FPDFEMB_Link_GetAreaCount
//			Get number of area (quadrilaterals) for a link
// Parameters:
//			page		-	Page handle
//			link_index	-	Zero-based index for the link
//			count		-	Pointer to an integer receiving number of quadrilaterals
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//
FPDFEMB_RESULT FPDFEMB_Link_GetAreaCount(FPDFEMB_PAGE page, int link_index, int* count);

// Function: FPDFEMB_Link_GetArea
//			Get a particular quadrilateral for a link
// Parameters:
//			page		-	Page handle
//			link_index	-	Zero-based index for the link
//			area_index	-	Zero-based index for the quadrilateral
//			points		-	Pointer to an array consists 4 points, receiving coordinations
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			The result in "points" array are the X/Y coordinations for the four vertices
//			of the quadrilateral. Vertices are in the following order: lower left, lower
//			right, upper right, upper left.
//
FPDFEMB_RESULT FPDFEMB_Link_GetArea(FPDFEMB_PAGE page, int link_index, int area_index, 
									FPDFEMB_POINT* points);

/********************************************************************************************
****
****		Graphic Output (onto DIB)
****
********************************************************************************************/

typedef void* FPDFEMB_FONT;

// Function: FPDFEMB_OpenStandardFont
//			Get ready to use a standard PDF font
// Parameters:
//			font_name	-	Name of the font. See a list of supported fonts below.
//			font_handle	-	Receiving the font handle.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			Currently supported standard fonts:
//			Courier, Courier-Bold, Courier-BoldOblique, Courier-Oblique,
//			Helvetica, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Oblique,
//			Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic,
//			Symbol, ZapfDingbats.
//
FPDFEMB_RESULT FPDFEMB_OpenStandardFont(const char* font_name, FPDFEMB_FONT* font_handle);

// Function: FPDFEMB_OpenSystemFont
//			Get ready to use a system font
// Parameters:
//			font_name	-	Font name
//			charset		-	Charset ID (see above FPDFEMB_CHARSET_xxx constants)
//			flags		-	Font flags (see above FPDFEMB_FONT_xxx constants)
//			weight		-	Weight of the font. Range from 100 to 900. 400 is normal,
//							700 is bold.
//			font_handle	-	Receiving the font handle.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
// Comments:
//			System font is supported only if either FPDFEMB_SetFontMapper or
//			FPDFEMB_SetGlyphProvider is called.
//			Font attributes (name, charset, flags and weight) can be all optional, if the
//			font mapper or glyph provider doesn't make use of them.
//
FPDFEMB_RESULT FPDFEMB_OpenSystemFont(const char* font_name, int charset, unsigned int flags, int weight,
									  FPDFEMB_FONT* font_handle);

// Function: FPDFEMB_CloseFont
//			Close a font handle.
// Parameters:
//			font_handle	-	Handle to the font.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//
FPDFEMB_RESULT FPDFEMB_CloseFont(FPDFEMB_FONT font_handle);

struct FPDFEMB_TEXTMATRIX
{
	double	a, b, c, d;
};

// Function: FPDFEMB_OutputText
//			Output text string onto a DIB device.
// Parameters:
//			dib			-	DIB handle, as the output device
//			x, y		-	DIB coordinations for the origin point of the first character.
//			font_handle	-	Handle to the font
//			font_size	-	Font size in pixels
//			matrix		-	Matrix for the text output. Can be NULL.
//			text		-	Zero-terminated unicode text string
//			argb		-	Color of the text, in 0xaarrggbb format.
// Return Value:
//			Error code, or FPDFERR_SUCCESS for success.
//
FPDFEMB_RESULT FPDFEMB_OutputText(FPDFEMB_BITMAP dib, int x, int y, FPDFEMB_FONT font_handle, double font_size,
								  FPDFEMB_TEXTMATRIX* matrix, const FPDFEMB_WCHAR* text, unsigned long argb);

#ifdef __cplusplus
};
#endif

#endif	// #ifdef _FPDFEMB_H_