Logo Search packages:      
Sourcecode: chromium-browser version File versions  Download package

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_

Generated by  Doxygen 1.6.0   Back to index