/src/compiler/android/jni/ftk/fpdfemb.h
C++ Header | 1590 lines | 241 code | 125 blank | 1224 comment | 0 complexity | 762a27e5ce56d87c4fc62011a1aa6b6e MD5 | raw file
Possible License(s): LGPL-3.0
- // 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