PageRenderTime 51ms CodeModel.GetById 18ms RepoModel.GetById 0ms app.codeStats 1ms

/src/compiler/android/jni/ftk/fpdfemb.h

http://ftk.googlecode.com/
C++ Header | 1590 lines | 241 code | 125 blank | 1224 comment | 0 complexity | 762a27e5ce56d87c4fc62011a1aa6b6e MD5 | raw file
Possible License(s): LGPL-3.0
  1. // FPDFEMB.H - Header file for FPDFEMB SDK
  2. // Copyright (c) 2007-2008 Foxit Software Company, All Right Reserved.
  3. // Date: 2008-04-07
  4. // Embedded platforms have many different aspects from desktop platforms,
  5. // among them, the followings are most important for PDF processing:
  6. //
  7. // 1. Embedded platforms have only limited memory, and there is no virtual memory.
  8. // PDF is a very complicated format, processing PDF may consumes quite
  9. // large amount of memory, even for some smaller PDFs. And, in order to
  10. // increase the performance of PDF parsing and rendering, cache memory
  11. // is often used. For some big PDFs with many pages, the cache may grow
  12. // while user browing through pages, eventually, for some PDFs, the memory
  13. // on the device may run out.
  14. //
  15. // FPDFEMB SDK allows graceful out-of-memory (OOM) handling by returning
  16. // OOM error code for all functions that may involve memory allocation.
  17. // When an application detects OOM situation, it can do one of the followings:
  18. //
  19. // a) Give user some prompt and quit the application or close the document;
  20. // b) Or better, try to recover from the error. Sometimes OOM can be caused
  21. // by ever-growing cache. For example, when user browses a 1000-page
  22. // document, let's say OOM happen at page #300. In this case, the
  23. // application might close the whole document (cache will be gone with
  24. // it), reopen the document, then go directly to page #300. It's likely
  25. // the process will go through this time. This is called "OOM recovery".
  26. // If OOM happens again during a recovery, then, it's not possible to finish
  27. // the process, the application must quit of close the document.
  28. //
  29. // 2. Embedded platforms has only limited computing power. Since some PDFs
  30. // can be very complicated and require a lot of processing to be displayed,
  31. // it may take a lot of time for the process to finish. This may cause
  32. // some problem with user experience, especially for devices like mobile
  33. // phones, when an application may need to be put on hold any time. Therefore,
  34. // it's important to break lengthy process into small steps which can be
  35. // stopped or resumed at any time. We call this kind of process as
  36. // "progressive process".
  37. //
  38. // FPDFEMB SDK allows progressive page parsing and rendering, the most time-
  39. // consuming part of PDF processing.
  40. //
  41. // IMPORTANT:
  42. // FPDFEMB module is not intended to run in multi-threaded environment.
  43. // Components inside FPDFEMB:
  44. // * Library Memory Management
  45. // * Document Operations
  46. // * Page Basic Operations
  47. // * Page Parsing
  48. // * Page Rendering
  49. // * Coordination Conversion
  50. // * Text Search
  51. // * Text Information
  52. // * Device Independant Bitmap
  53. // * Custom Font Handler and CJK Support
  54. // * Bookmark Information
  55. // * Hyperlink Information
  56. // * Graphic Output
  57. #ifndef _FPDFEMB_H_
  58. #define _FPDFEMB_H_
  59. #ifdef __cplusplus
  60. extern "C" {
  61. #endif
  62. // Standard return type for many FPDFEMB functions: FPDFERR_SUCCESS for success, otherwise error code
  63. typedef int FPDFEMB_RESULT;
  64. // Standard boolean type: 0 for false, non-zero for true
  65. typedef int FPDFEMB_BOOL;
  66. // Unicode character. FPDFEMB uses UTF16LE format for unicode string.
  67. typedef unsigned short FPDFEMB_WCHAR;
  68. // Error codes
  69. #define FPDFERR_SUCCESS 0
  70. #define FPDFERR_MEMORY 1 // Out of memory
  71. #define FPDFERR_ERROR 2 // Error of any kind, without specific reason
  72. #define FPDFERR_PASSWORD 3 // Incorrect password
  73. #define FPDFERR_FORMAT 4 // Not PDF format
  74. #define FPDFERR_FILE 5 // File access error
  75. #define FPDFERR_PARAM 6 // Parameter error
  76. #define FPDFERR_STATUS 7 // Not in correct status
  77. #define FPDFERR_TOBECONTINUED 8 // To be continued
  78. #define FPDFERR_NOTFOUND 9 // Search result not found
  79. /********************************************************************************************
  80. ****
  81. **** Library Memory Management
  82. ****
  83. ********************************************************************************************/
  84. // Structure: FPDFEMB_MEMMGR
  85. // Including interfaces implemented by host application, providing memory allocation
  86. // facilities. All members are required.
  87. // A memory manager structure is required to be valid during the entire period
  88. // when an application using FPDFEMB module.
  89. //
  90. // IMPORTANT NOTE: using of this interface is strongly not recommended, because
  91. // FPDFEMB now internally use FPDFEMB_MEMMGR_EX interface, which allows more
  92. // advanced memory management. This interface is retained for backward compatibility
  93. // only, and maybe discontinued in the future.
  94. //
  95. struct FPDFEMB_MEMMGR {
  96. // Interface: Alloc
  97. // Allocate a memory block
  98. // Parameters:
  99. // pMgr - Pointer to the memory manager.
  100. // size - Number of bytes for the memory block.
  101. // Return Value:
  102. // The pointer to allocated memory block. NULL if no memory available.
  103. // Comments:
  104. // In order to handle OOM situation, application can use longjmp() inside
  105. // implementation of this function. If underlying memory manager fails to
  106. // allocate enough memory, then application can use longjmp() to jump to
  107. // OOM handling codes.
  108. //
  109. void* (*Alloc)(struct FPDFEMB_MEMMGR* pMgr, unsigned int size);
  110. // Interface: AllocNL
  111. // Allocate a memory block, without leaving
  112. // Parameters:
  113. // pMgr - Pointer to the memory manager.
  114. // size - Number of bytes for the memory block.
  115. // Return Value:
  116. // The pointer to allocated memory block. NULL if no memory available.
  117. // Comments:
  118. // Implementation MUST return NULL if no memory available, no exception
  119. // or longjmp() can be used.
  120. //
  121. void* (*AllocNL)(struct FPDFEMB_MEMMGR* pMgr, unsigned int size);
  122. // Interfce: Realloc
  123. // Reallocate a memory block
  124. // Parameters:
  125. // pMgr - Pointer to the memory manager.
  126. // pointer - An existing memory block, or NULL.
  127. // new_size - New size (number of bytes) of the memory block. Can be zero.
  128. // Return value:
  129. // The pointer of reallocated memory block, it could be a new block, or just
  130. // the previous block with size modified.
  131. // Comments:
  132. // If an existing memory block specified, the data in the memory block will
  133. // be copied to the new block, if reallocated.
  134. //
  135. // In order to handle OOM situation, application can use longjmp() inside
  136. // implementation of this function. If underlying memory manager fails to
  137. // allocate enough memory, then application can use longjmp() to jump to
  138. // OOM handling codes.
  139. //
  140. void* (*Realloc)(struct FPDFEMB_MEMMGR* pMgr, void* pointer, unsigned int new_size);
  141. // Interface: Free
  142. // Free a memory block
  143. // Parameters:
  144. // pMgr - Pointer to the memory manager.
  145. // pointer - An existing memory block.
  146. // Return Value:
  147. // None.
  148. //
  149. void (*Free)(struct FPDFEMB_MEMMGR* pMgr, void* pointer);
  150. };
  151. // Function: FPDFEMB_Init
  152. // Initialize the FPDFEMB module
  153. // Parameters:
  154. // mem_mgr - Pointer to memory manager structure
  155. // Return Value:
  156. // Error code, or FPDFERR_SUCCESS for success.
  157. // Comments:
  158. // This function will allocate necessary internal data structure for
  159. // the whole module to operate.
  160. FPDFEMB_RESULT FPDFEMB_Init(FPDFEMB_MEMMGR* mem_mgr);
  161. typedef void (*FPDFEMB_FIXED_OOM_HANDLER)(void* memory, int size);
  162. // Function: FPDFEMB_InitFixedMemory
  163. // Initialize the FPDFEMB module, providing a fixed memory heap
  164. // Parameters:
  165. // memory - Pointer to a pre-allocated memory block
  166. // size - Number of bytes in the memory block
  167. // oom_handler - Pointer to a function which will be called when OOM happens. Can be
  168. // NULL if application doesn't want to be notified om OOM.
  169. // Return Value:
  170. // Error code, or FPDFERR_SUCCESS for success.
  171. // Comments:
  172. // In many embedded system, memory usage are predetermined. The application
  173. // is assigned with fixed size of available memory, then it can pre-allocate
  174. // a memory block with maximum size and pass to this function to initialize
  175. // FPDFEMB module. In this case, FPDFEMB won't need any additional memory
  176. // allocation.
  177. //
  178. // In case the pre-allocated memory has run out, the "oom_proc" callback
  179. // function will be called to notify the application that an OOM recovery
  180. // procedure needs to be performed.
  181. //
  182. FPDFEMB_RESULT FPDFEMB_InitFixedMemory(void* memory, int size, FPDFEMB_FIXED_OOM_HANDLER oom_handler);
  183. // Memory Management Flags
  184. #define FPDFEMB_NONLEAVE 1
  185. #define FPDFEMB_MOVABLE 2
  186. #define FPDFEMB_DISCARDABLE 4
  187. // Structure: FPDFEMB_MEMMGR_EX
  188. // This is an extended version of memory manager interface, allowing advanced
  189. // memory management, including movable and discardable memory blocks.
  190. //
  191. // Use this interface with FPDFEMB_InitExt function.
  192. //
  193. struct FPDFEMB_MEMMGR_EX {
  194. // Interface: Alloc
  195. // Allocate a memory block
  196. // Parameters:
  197. // pMgr - Pointer to the memory manager.
  198. // size - Number of bytes for the memory block.
  199. // flags - A combination of flags defined above.
  200. // Return Value:
  201. // The pointer to allocated memory block. NULL if no memory available.
  202. // If FPDFEMB_MOVABLE flag is used, implementation should return a handle
  203. // to the memory block, if it supports movable block allocation.
  204. // Comments:
  205. // The implementation should not do any action if no memory available,
  206. // just return NULL. OOM handling can be done in OOM_Handler interface.
  207. //
  208. void* (*Alloc)(struct FPDFEMB_MEMMGR_EX* pMgr, unsigned int size, int flags);
  209. // Interface: OOM_Handler
  210. // OOM (out-of-memory) situation handler
  211. // Parameters:
  212. // pMgr - Pointer to the memory manager.
  213. // Return Value:
  214. // None.
  215. // Comments:
  216. // In order to handle OOM situation, application can use longjmp() inside
  217. // implementation of this function.
  218. //
  219. void (*OOM_Handler)(struct FPDFEMB_MEMMGR_EX* pMgr);
  220. // Interfce: Realloc
  221. // Reallocate a memory block
  222. // Parameters:
  223. // pMgr - Pointer to the memory manager.
  224. // pointer - Pointer to an existing memory block, or handle to a movable
  225. // block. Can not be NULL.
  226. // new_size - New size (number of bytes) of the memory block. Can not be zero.
  227. // Return value:
  228. // The pointer of reallocated memory block, it could be a new block, or just
  229. // the previous block with size modified.
  230. // If FPDFEMB_MOVABLE flag is used, implementation should return a handle
  231. // to the memory block, if it supports movable block allocation.
  232. // Comments:
  233. // If an existing memory block specified, the data in the memory block should
  234. // be copied to the new block, if reallocated.
  235. //
  236. // The implementation should not do any action if no memory available,
  237. // just return NULL. OOM handling can be done in OOM_Handler interface.
  238. //
  239. void* (*Realloc)(struct FPDFEMB_MEMMGR_EX* pMgr, void* pointer, unsigned int new_size, int flags);
  240. // Interface: Lock
  241. // Lock a movable memory block
  242. // Parameters:
  243. // pMgr - Pointer to the memory manager.
  244. // handle - Handle to movable memory block, returned by Alloc or Realloc.
  245. // Return Value:
  246. // The pointer of the memory block. NULL if the block was discarded.
  247. // Comments:
  248. // This interface is optional, if implementation doesn't support movable memory
  249. // block, then this interface can be set to NULL.
  250. //
  251. void* (*Lock)(struct FPDFEMB_MEMMGR_EX* pMgr, void* handle);
  252. // Interface: Unlock
  253. // Unlock a locked movable memory block
  254. // Parameters:
  255. // pMgr - Pointer to the memory manager.
  256. // handle - Handle to movable memory block, returned by Alloc or Realloc.
  257. // Return Value:
  258. // None.
  259. // Comments:
  260. // This interface is optional, if implementation doesn't support movable memory
  261. // block, then this interface can be set to NULL.
  262. //
  263. void (*Unlock)(struct FPDFEMB_MEMMGR_EX* pMgr, void* handle);
  264. // Interface: Free
  265. // Free a memory block
  266. // Parameters:
  267. // pMgr - Pointer to the memory manager.
  268. // pointer - Pointer to an existing memory block, or handle to a movable block.
  269. // Return Value:
  270. // None.
  271. //
  272. void (*Free)(struct FPDFEMB_MEMMGR_EX* pMgr, void* pointer, int flags);
  273. void* user; // A user pointer, used by the application
  274. };
  275. // Function: FPDFEMB_LoadJbig2Decoder
  276. // Function: FPDFEMB_LoadJpeg2000Decoder
  277. // Enable JBIG2 or JPEG2000 image decoder
  278. // Parameters:
  279. // None.
  280. // Return Value:
  281. // None.
  282. // Comments:
  283. // If you want to display JBIG2 or JPEG2000 encoded images, you need to call
  284. // these functions after FPDFEMB initialized.
  285. //
  286. // Calling these functions will increase code size by about 200K-400K bytes.
  287. // Also JPEG2000 decoder may not be available on some platforms.
  288. //
  289. void FPDFEMB_LoadJbig2Decoder();
  290. void FPDFEMB_LoadJpeg2000Decoder();
  291. // Function: FPDFEMB_InitEx
  292. // Initialize the FPDFEMB module with the extended memory manager
  293. // Parameters:
  294. // mem_mgr - Pointer to memory manager structure
  295. // Return Value:
  296. // Error code, or FPDFERR_SUCCESS for success.
  297. // Comments:
  298. // This function will allocate necessary internal data structure for
  299. // the whole module to operate.
  300. FPDFEMB_RESULT FPDFEMB_InitEx(FPDFEMB_MEMMGR_EX* mem_mgr);
  301. // Function: FPDFEMB_Exit
  302. // Stop using FPDFEMB module and release all resources
  303. // Parameters:
  304. // None.
  305. // Return Value:
  306. // None.
  307. // Comments:
  308. // All loaded documents and pages will become invalid after this call.
  309. //
  310. // This function is useful for OOM recovery: when your application hits
  311. // an OOM situation, calling this function will clear all memory allocated
  312. // by FPDFEMB module, then you can call one of the initialization functions,
  313. // reopen the document and recovery from OOM.
  314. //
  315. void FPDFEMB_Exit();
  316. // Function: FPDFEMB_AllocMemory
  317. // Allocate memory
  318. // Parameters:
  319. // size - Number of bytes
  320. // Return Value:
  321. // The allocated buffer pointer. NULL for out of memory.
  322. //
  323. void* FPDFEMB_AllocMemory(unsigned int size);
  324. // Function: FPDFEMB_FreeMemory
  325. // Free allocated memory
  326. // Parameters:
  327. // pointer - Pointer returned by FPDFEMB_AllocMemory
  328. // Return Value:
  329. // None.
  330. //
  331. void FPDFEMB_FreeMemory(void* pointer);
  332. // Function: FPDFEMB_FreeCaches
  333. // Free all expendable caches used by FPDFEMB in order to save memory
  334. // Parameters:
  335. // None.
  336. // Return Value:
  337. // None.
  338. // Comments:
  339. // When an application memory manager runs out of memory, before an OOM situation
  340. // is raised, the application can try this
  341. //
  342. void FPDFEMB_FreeCaches();
  343. /********************************************************************************************
  344. ****
  345. **** Document Operations
  346. ****
  347. ********************************************************************************************/
  348. // Structure: FPDFEMB_FILE_ACCESS
  349. // Describe the way to access a file (readonly).
  350. struct FPDFEMB_FILE_ACCESS {
  351. // Inteface: GetSize
  352. // Get total size of the file
  353. // Parameters:
  354. // file - Pointer to this file access structure
  355. // Return Value:
  356. // File size, in bytes. Implementation can return 0 for any error.
  357. //
  358. unsigned int (*GetSize)(struct FPDFEMB_FILE_ACCESS* file);
  359. // Interface: ReadBlock
  360. // Read a data block from the file
  361. // Parameters:
  362. // file - Pointer to this file access structure
  363. // buffer - Pointer to a buffer receiving read data
  364. // offset - Byte offset for the block, from beginning of the file
  365. // size - Number of bytes for the block.
  366. // Return Value:
  367. // Error code, or FPDFERR_SUCCESS for success.
  368. //
  369. FPDFEMB_RESULT (*ReadBlock)(struct FPDFEMB_FILE_ACCESS* file, void* buffer,
  370. unsigned int offset, unsigned int size);
  371. void* user; // A user pointer, used by the application
  372. };
  373. // Structure: FPDFEMB_PAUSE
  374. // An interface for pausing a progressive process.
  375. struct FPDFEMB_PAUSE {
  376. // Interface: NeedPauseNow
  377. // Check if we need to pause a progressive proccess now
  378. // Parameters:
  379. // pause - Pointer to the pause structure
  380. // Return Value:
  381. // Non-zero for pause now, 0 for continue.
  382. // Comments:
  383. // Typically implementation of this interface compares the current system tick
  384. // with the previous one, if the time elapsed exceeds certain threshold, then
  385. // the implementation returns TRUE, indicating a pause is needed.
  386. //
  387. FPDFEMB_BOOL (*NeedPauseNow)(struct FPDFEMB_PAUSE* pause);
  388. void* user; // A user pointer, used by the application
  389. };
  390. typedef void* FPDFEMB_DOCUMENT;
  391. // Function: FPDFEMB_StartLoadDocument
  392. // Start loading a PDF document
  393. // Parameters:
  394. // file - Pointer to file access structure.
  395. // This structure must be kept valid as long as the document is open.
  396. // password - Pointer to a zero-terminated byte string, for the password.
  397. // Or NULL for no password.
  398. // document - Receiving the document handle
  399. // pause - A callback mechanism allowing the document loading process
  400. // to be paused before it's finished. This can be NULL if you
  401. // don't want to pause.
  402. // Return Value:
  403. // FPDFERR_SUCCESS: document successfully loaded.
  404. // FPDFERR_TOBECONTINUED: The document loading can't be finished now.
  405. // See comments below.
  406. // FPDFERR_PASSWORD: incorrect password.
  407. // FPDFERR_FORMAT: not a PDF or corrupted PDF.
  408. // FPDFERR_FILE: file access error.
  409. // FPDFERR_MEMORY: out of memory.
  410. // Comments:
  411. // Document loading is a progressive process. It might take a long time to
  412. // load a document, especiall when a file is corrupted, FPDFEMB will try to
  413. // recover the document contents by scanning the whole file. If "pause" parameter
  414. // is provided, this function may return FPDFERR_TOBECONTINUED any time during
  415. // the document loading.
  416. //
  417. // When FPDFERR_TOBECONTINUED is returned, the "document" parameter will
  418. // still receive a valid document handle, however, no further operations can
  419. // be performed on the document, except the "FPDFEMB_ContineLoadDocument" function
  420. // call, which resume the document loading.
  421. //
  422. FPDFEMB_RESULT FPDFEMB_StartLoadDocument(FPDFEMB_FILE_ACCESS* file, const char* password,
  423. FPDFEMB_DOCUMENT* document, FPDFEMB_PAUSE* pause);
  424. // Function: FPDFEMB_ContinueLoadDocument
  425. // Continue loading a PDF document
  426. // Parameters:
  427. // document - Document handle returned by FPDFEMB_StartLoadDocument function
  428. // pause - A callback mechanism allowing the document loading process
  429. // to be paused before it's finished. This can be NULL if you
  430. // don't want to pause.
  431. // Return Value:
  432. // FPDFERR_SUCCESS: document successfully loaded.
  433. // FPDFERR_TOBECONTINUED: The document loading can't be finished now.
  434. // Further call to this function is needed.
  435. // FPDFERR_PASSWORD: incorrect password.
  436. // FPDFERR_FORMAT: not a PDF or corrupted PDF.
  437. // FPDFERR_FILE: file access error.
  438. // FPDFERR_MEMORY: out of memory.
  439. // FPDFERR_STATUS: document already loaded.
  440. // FPDFERR_PARAM: invalid parameter (like NULL document handle)
  441. //
  442. FPDFEMB_RESULT FPDFEMB_ContinueLoadDocument(FPDFEMB_DOCUMENT document, FPDFEMB_PAUSE* pause);
  443. // Function: FPDFEMB_CloseDocument
  444. // Close a PDF document and free all associated resources
  445. // Parameters:
  446. // document - Document handle
  447. // Return Value:
  448. // Error code. FPDFERR_SUCCESS for success.
  449. //
  450. FPDFEMB_RESULT FPDFEMB_CloseDocument(FPDFEMB_DOCUMENT document);
  451. // Function: Get page count
  452. // Get number of pages in the document
  453. // Parameters:
  454. // document - Document handle
  455. // Return Value:
  456. // Number of pages.
  457. //
  458. int FPDFEMB_GetPageCount(FPDFEMB_DOCUMENT document);
  459. // Function: FPDFEMB_SetFileBufferSize
  460. // Set size of internal buffer used to read from source file.
  461. // Parameters:
  462. // size - Number of bytes
  463. // Return Value:
  464. // None.
  465. // Comments:
  466. // Currently FPDFEMB uses 512 bytes as default buffer size. The new buffer size
  467. // takes effect next time you call FPDFEMB_StartLoadDocument.
  468. //
  469. void FPDFEMB_SetFileBufferSize(int size);
  470. /********************************************************************************************
  471. ****
  472. **** Page Basic Operations
  473. ****
  474. ********************************************************************************************/
  475. typedef void* FPDFEMB_PAGE;
  476. // Function: FPDFEMB_LoadPage
  477. // Load a page
  478. // Parameters:
  479. // document - Document handle
  480. // index - Page index, starting from zero
  481. // page - Receiving the loaded page handler
  482. // Return Value:
  483. // Error code, or FPDFERR_SUCCESS for success.
  484. //
  485. FPDFEMB_RESULT FPDFEMB_LoadPage(FPDFEMB_DOCUMENT document, int index, FPDFEMB_PAGE* page);
  486. // Function: FPDFEMB_ClosePage
  487. // Close a page and release all related resources
  488. // Parameters:
  489. // page - Page handle
  490. // Return Value:
  491. // Error code, or FPDFERR_SUCCESS for success.
  492. //
  493. FPDFEMB_RESULT FPDFEMB_ClosePage(FPDFEMB_PAGE page);
  494. // Function: FPDFEMB_GetPageSize
  495. // Get size of a page
  496. // Parameters:
  497. // page - Page handle
  498. // width - Receiving page width, in hundredth of points
  499. // height - Receiving page height, in hundredth of points
  500. // Return Value:
  501. // Error code, or FPDFERR_SUCCESS for success
  502. //
  503. FPDFEMB_RESULT FPDFEMB_GetPageSize(FPDFEMB_PAGE page, int* width, int* height);
  504. // Structure: FPDFEMB_RECT
  505. // Rectangle area in device or page coordination system
  506. //
  507. struct FPDFEMB_RECT
  508. {
  509. // For device system, coordinations are measured in pixels;
  510. // For page system, coordinations are measured in hundredth of points.
  511. int left;
  512. int top;
  513. int right;
  514. int bottom;
  515. };
  516. // Function: FPDFEMB_GetPageBBox
  517. // Get displayable area (bounding box) of a page
  518. // Parameters:
  519. // page - Page handle
  520. // rect - Pointer to a structure receiving the rectangle
  521. // Return Value:
  522. // Error code, or FPDFERR_SUCCESS for success
  523. //
  524. FPDFEMB_RESULT FPDFEMB_GetPageBBox(FPDFEMB_PAGE page, FPDFEMB_RECT* rect);
  525. /********************************************************************************************
  526. ****
  527. **** Page Parsing
  528. ****
  529. ********************************************************************************************/
  530. // Function: FPDFEMB_StartParse
  531. // Start parsing a page, so it can get rendered or searched
  532. // Parameters:
  533. // page - Page handle
  534. // text_only - flag for parsing texts only (used for searching)
  535. // pause - A structure that can pause the parsing process.
  536. // Or NULL if you don't want to pause the process.
  537. // Return Value:
  538. // FPDFERR_SUCCESS: parsing successfully finished;
  539. // FPDFERR_TOBECONTINUED: parsing started successfully, but not finished;
  540. // FPDFERR_STATUS: page already parsed, or parsing already started.
  541. // Other return value: error code.
  542. // Comments:
  543. // Parsing is a progressive process. This function starts the parsing process,
  544. // and may return before parsing is finished, if a pause structure is provided.
  545. //
  546. // Application should call FPDFEMB_ContinueParse repeatedly to finish the parsing
  547. // when return value is FPDFERR_TOBECONTINUED.
  548. //
  549. // There can be only one parsing procedure active for a page, and if a page
  550. // has already been parsed, you can't start a parsing again.
  551. //
  552. FPDFEMB_RESULT FPDFEMB_StartParse(FPDFEMB_PAGE page, FPDFEMB_BOOL text_only,
  553. FPDFEMB_PAUSE* pause);
  554. // Function: FPDFEMB_ContinueParse
  555. // Continue the page parsing
  556. // Parameters:
  557. // page - Page handle
  558. // pause - A structure that can pause the parsing process.
  559. // Or NULL if you don't want to pause the process.
  560. // Return Value:
  561. // FPDFERR_SUCCESS: parsing successfully finished;
  562. // FPDFERR_TOBECONTINUED: parsing performed successfully, but not finished;
  563. // FPDFERR_STATUS: page already parsed (or parsing not started).
  564. // Other return value: error code.
  565. // Comments:
  566. // FPDFEMB_StartParse should be called before on the page.
  567. //
  568. // Application should call FPDFEMB_ContinueParse repeatedly to finish the parsing
  569. // when return value is FPDFERR_TOBECONTINUED.
  570. //
  571. FPDFEMB_RESULT FPDFEMB_ContinueParse(FPDFEMB_PAGE page, FPDFEMB_PAUSE* pause);
  572. // Function: FPDFEMB_GetParseProgress
  573. // Get an estimated parsing progress in percentage
  574. // Parameters:
  575. // page - Page handle
  576. // Return Value:
  577. // An integer between 0 and 100 (inclusive) indicating the parsing progress.
  578. // The result is just a rough estimation.
  579. //
  580. int FPDFEMB_GetParseProgress(FPDFEMB_PAGE page);
  581. /********************************************************************************************
  582. ****
  583. **** Page Rendering
  584. ****
  585. ********************************************************************************************/
  586. typedef void* FPDFEMB_BITMAP;
  587. // Function: FPDFEMB_StartQuickDraw
  588. // Start drawing a quick preview of a page
  589. // Parameters:
  590. // dib - DIB handle, as the rendering device
  591. // page - Page handle. The page has to be parsed first.
  592. // start_x - Left pixel position of the display area in the device coordination
  593. // start_y - Top pixel position of the display area in the device coordination
  594. // size_x - Horizontal size (in pixels) for displaying the page
  595. // size_y - Vertical size (in pixels) for displaying the page
  596. // rotate - Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
  597. // 2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
  598. // flags - Reserved, must be zero.
  599. // pause - Pointer to a structure that can pause the rendering process.
  600. // Can be NULL if no pausing is needed.
  601. // Return Value:
  602. // FPDFERR_SUCCESS: quickdraw successly finished;
  603. // FPDFERR_TOBECONTINUED: quickdraw started successfully, but not finished.
  604. // FPDFEMB_ContinueQuickDraw needs to be called to finish the quickdraw;
  605. // FPDFERR_STATUS: quickdraw already in progress, or page not parsed;
  606. // Other return value: error code.
  607. // Comments:
  608. // It's often useful to present user a quick preview of a page, right after the
  609. // page is parsed. This preview renders only a limited set of easy features in the
  610. // page, so it'll be rather quick to finish this process.
  611. //
  612. FPDFEMB_RESULT FPDFEMB_StartQuickDraw(FPDFEMB_BITMAP dib, FPDFEMB_PAGE page,
  613. int start_x, int start_y, int size_x, int size_y, int rotate,
  614. int flags, FPDFEMB_PAUSE* pause);
  615. // Function: FPDFEMB_ContinueQuickDraw
  616. // Continue a quick draw processing
  617. // Parameters:
  618. // page - Page handle. The page has to be parsed first.
  619. // pause - Pointer to a structure that can pause the rendering process.
  620. // Can be NULL if no pausing is needed.
  621. // Return Value:
  622. // FPDFERR_SUCCESS: quickdraw successly finished;
  623. // FPDFERR_TOBECONTINUED: quickdraw started successfully, but not finished.
  624. // more calls to this function needed to finish the quickdraw;
  625. // FPDFERR_STATUS: quickdraw not started yet;
  626. // Other return value: error code.
  627. //
  628. FPDFEMB_RESULT FPDFEMB_ContinueQuickDraw(FPDFEMB_PAGE page, FPDFEMB_PAUSE* pause);
  629. #define FPDFEMB_ANNOT 0x01 // Set if annotations are to be rendered
  630. #define FPDFEMB_LCD_TEXT 0x02 // Set if using text rendering optimized for LCD display
  631. #define FPDFEMB_BGR_STRIPE 0x04 // Set if the device is using BGR LCD stripe
  632. // Function: FPDFEMB_StartRender
  633. // Start rendering of a page.
  634. // Parameter:
  635. // dib - DIB handle, as the rendering device
  636. // page - Page handle. The page has to be parsed first.
  637. // start_x - Left pixel position of the display area in the device coordination
  638. // start_y - Top pixel position of the display area in the device coordination
  639. // size_x - Horizontal size (in pixels) for displaying the page
  640. // size_y - Vertical size (in pixels) for displaying the page
  641. // rotate - Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
  642. // 2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
  643. // flags - 0 for normal display, or combination of flags defined above
  644. // clip - Pointer to clip rectangle (in DIB device coordinations),
  645. // or NULL if no clipping needed.
  646. // pause - Pointer to a structure that can pause the rendering process.
  647. // Can be NULL if no pausing is needed.
  648. // Return Value:
  649. // FPDFERR_SUCCESS: rendering successfully finished;
  650. // FPDFERR_TOBECONTINUED: rendering started successfully, but not finished;
  651. // Other return value: error code.
  652. // Comments:
  653. // Rendering is a progressive process. This function starts the rendering process,
  654. // and may return before rendering is finished, if a pause structure is provided.
  655. //
  656. // Application should call FPDFEMB_ContinueRender repeatedly to finish the rendering
  657. // when return value is FPDFERR_TOBECONTINUED.
  658. //
  659. // There can be only one rendering procedure for a page at any time. And rendering
  660. // can be started over and over again for the same page. If a page rendering is already
  661. // active, starting another one will cancel the previous rendering.
  662. //
  663. // Rendering of a page doesn't draw the page background, therefore, you usually need
  664. // to draw the background in the DIB yourself.
  665. //
  666. FPDFEMB_RESULT FPDFEMB_StartRender(FPDFEMB_BITMAP dib, FPDFEMB_PAGE page,
  667. int start_x, int start_y, int size_x, int size_y, int rotate, int flags,
  668. FPDFEMB_RECT* clip, FPDFEMB_PAUSE* pause);
  669. // Function: FPDFEMB_ContinueRender
  670. // Continue the page rendering
  671. // Parameters:
  672. // page - Page handle
  673. // pause - Pointer to a structure that can pause the rendering process.
  674. // Can be NULL if no pausing is needed.
  675. // Return Value:
  676. // FPDFERR_SUCCESS: rendering successfully finished.
  677. // FPDFERR_TOBECONTINUED: rendering needs to be continued;
  678. // Other return value: error code.
  679. // Comments:
  680. // This function may return any time when the pause interface indicates
  681. // a pause is needed. Application can call FPDFEMB_ContinueRender any number
  682. // of times, until FPDFERR_TOBECONTINUED is not returned.
  683. //
  684. FPDFEMB_RESULT FPDFEMB_ContinueRender(FPDFEMB_PAGE page, FPDFEMB_PAUSE* pause);
  685. // Function: FPDFEMB_GetRenderProgress
  686. // Get an estimated rendering progress in percentage
  687. // Parameters:
  688. // page - Page handle
  689. // Return Value:
  690. // An integer between 0 and 100 (inclusive) indicating the rendering progress.
  691. // The result is just a rough estimation.
  692. // If the rendering just finished, this function will return 0.
  693. //
  694. int FPDFEMB_GetRenderProgress(FPDFEMB_PAGE page);
  695. // Function: FPDFEMB_SetHalftoneLimit
  696. // Set pixel count limit for using halftone when display image
  697. // Parameter:
  698. // limit - Number of pixels for the limit
  699. // Return Value:
  700. // None.
  701. // Comments:
  702. // By default, FPDFEMB displays all bitmaps using downsamping, which means
  703. // if the image is shrinked onto screen, only part of pixels will be picked
  704. // and displayed. This saves a lot of calculation, especially for big images
  705. // with millions of pixels. However the display quality can be bad. In order to
  706. // reach a balance between performance and quality, application can use this
  707. // function to set a limit, if number of pixels in an image is more than this
  708. // limit, then FPDFEMB will use downsampling for quick drawing, otherwise, if
  709. // the image has less pixels, FPDFEMB will use halftoning for better quality.
  710. //
  711. void FPDFEMB_SetHalftoneLimit(int limit);
  712. /********************************************************************************************
  713. ****
  714. **** Coordination Conversion
  715. ****
  716. ********************************************************************************************/
  717. // Structure: FPDFEMB_POINT
  718. // A point in device or page coordination system
  719. //
  720. struct FPDFEMB_POINT
  721. {
  722. // For device system, coordinations are measured in pixels;
  723. // For page system, coordinations are measured hundredth of points.
  724. int x;
  725. int y;
  726. };
  727. // Function: FPDFEMB_DeviceToPagePoint, FPDFEMB_DeviceToPageRect
  728. // Convert the device coordinations of a point or a rectangle to page coordinations.
  729. // Parameters:
  730. // page - Handle to the page. Returned by FPDFEMB_LoadPage function.
  731. // start_x - Left pixel position of the display area in the device coordination
  732. // start_y - Top pixel position of the display area in the device coordination
  733. // size_x - Horizontal size (in pixels) for displaying the page
  734. // size_y - Vertical size (in pixels) for displaying the page
  735. // rotate - Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
  736. // 2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
  737. // point - A point structure with device coordinations upon the call,
  738. // also receiving the result page coordinations.
  739. // rect - A rectangle structure with device coordinations upon the call,
  740. // also receiving the result page coordinations.
  741. // Return value:
  742. // None.
  743. // Comments:
  744. // The page coordination system has its origin at left-bottom corner of the page,
  745. // with X axis goes along the bottom side to the right, and Y axis goes along the
  746. // left side upward. No matter how you zoom, scroll, or rotate a page, a particular
  747. // element (like text or image) on the page should always have the same coordination
  748. // values in the page coordination system.
  749. //
  750. // The device coordination system is device dependant. For bitmap device, its origin
  751. // is at left-top corner of the window. You must make sure the start_x, start_y, size_x,
  752. // size_y and rotate parameters have exactly same values as you used in
  753. // FPDFEMB_StartRender() function call.
  754. //
  755. // For rectangle conversion, the result rectangle is always "normalized", meaning for
  756. // page coordinations, left is always smaller than right, bottom is smaller than top.
  757. //
  758. void FPDFEMB_DeviceToPagePoint(FPDFEMB_PAGE page,
  759. int start_x, int start_y, int size_x, int size_y, int rotate,
  760. FPDFEMB_POINT* point);
  761. void FPDFEMB_DeviceToPageRect(FPDFEMB_PAGE page,
  762. int start_x, int start_y, int size_x, int size_y, int rotate,
  763. FPDFEMB_RECT* rect);
  764. // Function: FPDFEMB_PageToDevicePoint, FPDFEMB_PageToDeviceRect
  765. // Convert the page coordinations of a point or a rectangle to device coordinations.
  766. // Parameters:
  767. // page - Handle to the page. Returned by FPDFEMB_LoadPage function.
  768. // start_x - Left pixel position of the display area in the device coordination
  769. // start_y - Top pixel position of the display area in the device coordination
  770. // size_x - Horizontal size (in pixels) for displaying the page
  771. // size_y - Vertical size (in pixels) for displaying the page
  772. // rotate - Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
  773. // 2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
  774. // point - A point structure with page coordinations upon the call,
  775. // also receiving the result device coordinations.
  776. // rect - A rectangle structure with page coordinations upon the call,
  777. // also receiving the result device coordinations.
  778. // Return value:
  779. // None
  780. // Comments:
  781. // For rectangle conversion, the result rectangle is always "normalized", meaning for
  782. // device coordinations, left is always smaller than right, top is smaller than bottom.
  783. //
  784. void FPDFEMB_PageToDevicePoint(FPDFEMB_PAGE page,
  785. int start_x, int start_y, int size_x, int size_y, int rotate,
  786. FPDFEMB_POINT* point);
  787. void FPDFEMB_PageToDeviceRect(FPDFEMB_PAGE page,
  788. int start_x, int start_y, int size_x, int size_y, int rotate,
  789. FPDFEMB_RECT* rect);
  790. /********************************************************************************************
  791. ****
  792. **** Text Search
  793. ****
  794. ********************************************************************************************/
  795. // Search flags for FPDFEMB_FindFirst function
  796. #define FPDFEMB_MATCHCASE 1 // whether matching case
  797. #define FPDFEMB_MATCHWHOLEWORD 2 // whether matching whole word
  798. #define FPDFEMB_CONSECUTIVE 4 // whether matching consecutively (for example, "CC" will
  799. // match twice in "CCC").
  800. // Function: FPDFEMB_FindFirst
  801. // Find first occurance of a pattern string in a page
  802. // Parameters:
  803. // page - Page handle.
  804. // pattern - A zero-terminated unicode string to be found.
  805. // from_last - Whether we start from the end of page
  806. // flags - Search flags, see above defined constants
  807. // Return Value:
  808. // Error code, or FPDFERR_SUCCESS for success.
  809. // Is not found, FPDFERR_NOTFOUND is returned.
  810. // Comments:
  811. // A page must be parsed first before it can be searched.
  812. // There can be only one search in progress for a page. A new search will
  813. // cancel the previous one.
  814. //
  815. // IMPORTANT: this function is now obsolete and kept for back compatibility
  816. // only, please use FPDFEMB_FindFrom function below.
  817. //
  818. FPDFEMB_RESULT FPDFEMB_FindFirst(FPDFEMB_PAGE page, const FPDFEMB_WCHAR* pattern,
  819. FPDFEMB_BOOL from_last, unsigned int flags);
  820. // Function: FPDFEMB_FindFrom
  821. // Find first occurance of a pattern string in a page, from a particular position
  822. // Parameters:
  823. // page - Page handle.
  824. // pattern - A zero-terminated unicode string to be found.
  825. // pos - The position, returned from FPDFEMB_GetSearchPos.
  826. // Or 0 from the beginning of page, -1 from the end of page.
  827. // flags - Search flags, see above defined constants
  828. // Return Value:
  829. // Error code, or FPDFERR_SUCCESS for success.
  830. // Is not found, FPDFERR_NOTFOUND is returned.
  831. // Comments:
  832. // A page must be parsed first before it can be searched.
  833. // There can be only one search in progress for a page. A new search will
  834. // cancel the previous one.
  835. //
  836. FPDFEMB_RESULT FPDFEMB_FindFrom(FPDFEMB_PAGE page, const FPDFEMB_WCHAR* pattern,
  837. int pos, unsigned int flags);
  838. // Function: FPDFEMB_FindNext
  839. // Find next occurance of a search
  840. // Parameters:
  841. // page - Page handle.
  842. // FPDFEMB_FindFirst must be called for this page first.
  843. // Return Value:
  844. // Error code, or FPDFERR_SUCCESS for success.
  845. // Is not found, FPDFERR_NOTFOUND is returned.
  846. //
  847. FPDFEMB_RESULT FPDFEMB_FindNext(FPDFEMB_PAGE page);
  848. // Function: FPDFEMB_FindPrev
  849. // Find previous occurance of a search
  850. // Parameters:
  851. // page - Page handle.
  852. // FPDFEMB_FindFirst must be called for this page first.
  853. // Return Value:
  854. // Error code, or FPDFERR_SUCCESS for success.
  855. // Is not found, FPDFERR_NOTFOUND is returned.
  856. //
  857. FPDFEMB_RESULT FPDFEMB_FindPrev(FPDFEMB_PAGE page);
  858. // Function: FPDFEMB_CountFoundRects
  859. // Get number of rectangles for last found result
  860. // Parameters:
  861. // page - Page handle.
  862. // Return Value:
  863. // Number of rectangles for last found result. 0 for not found or failure.
  864. //
  865. int FPDFEMB_CountFoundRects(FPDFEMB_PAGE page);
  866. // Function: FPDFEMB_GetFoundRect
  867. // Get a particular found rectangle
  868. // Parameters:
  869. // page - Page handle.
  870. // index - Zero-based index for the rectangle.
  871. // rect - Receiving the result rectangle, in hundredth of points
  872. // Return Value:
  873. // Error code, or FPDFERR_SUCCESS for success.
  874. // Comments:
  875. // Application should always call FPDFEMB_CountFoundRects first to get
  876. // number of rectangles, then use this function to get each rectangle.
  877. //
  878. // The returned rectangle uses page coordination system.
  879. //
  880. FPDFEMB_RESULT FPDFEMB_GetFoundRect(FPDFEMB_PAGE page, int index, FPDFEMB_RECT* rect);
  881. // Function: FPDFEMB_GetSearchPos
  882. // Return position of current search result
  883. // Parameters:
  884. // page - Page handle.
  885. // Return Value:
  886. // Zero based character index for the current search result. -1 if not found.
  887. //
  888. int FPDFEMB_GetSearchPos(FPDFEMB_PAGE page);
  889. // Function: FPDFEMB_QuickSearch
  890. // Search a pattern in a page quickly, without the page to be parsed
  891. // Parameters:
  892. // document - Document handle returned by FPDFEMB_StartLoadDocument function
  893. // page_index - Zero-based index of the page
  894. // pattern - A zero-terminated unicode string to be found.
  895. // case_sensitive - Non-zero for case-sensitive searching, zero for case-insensitive
  896. // Return Value:
  897. // FPDFERR_SUCCESS if pattern found, FPDFERR_NOTFOUND if pattern not found.
  898. // Otherwise error code is returned.
  899. // Comments:
  900. // This function does a rough and quick search in a page, before the page is loaded.
  901. // The quick search will not generate an exact result saying where the pattern is
  902. // found, and, it might be possible if a quick search result is "pattern found", and
  903. // a real search for the same pattern, in the same page, will result in "not found".
  904. //
  905. // However, if quick search doesn't find a pattern in a page, then we can be sure the
  906. // pattern won't be found in this page when we do a real search. So, this function is
  907. // very useful when we search in a multiple-page document, and we want to quickly skip
  908. // those pages in which the pattern can't possibly be found.
  909. //
  910. FPDFEMB_RESULT FPDFEMB_QuickSearch(FPDFEMB_DOCUMENT document, int page_index,
  911. const FPDFEMB_WCHAR* pattern, int case_sensitive);
  912. /********************************************************************************************
  913. ****
  914. **** Text Information
  915. ****
  916. ********************************************************************************************/
  917. // Function: FPDFEMB_GetCharCount
  918. // Get number of characters in the page
  919. // Parameters:
  920. // page - Page handle
  921. // count - Receiving number of characters
  922. // Return Value:
  923. // Error code, or FPDFERR_SUCCESS for success.
  924. //
  925. FPDFEMB_RESULT FPDFEMB_GetCharCount(FPDFEMB_PAGE page, int* count);
  926. // Structure: FPDFEMB_CHAR_INFO
  927. // Character information.
  928. struct FPDFEMB_CHAR_INFO {
  929. int unicode; // Unicode for the character. 0 if not available.
  930. // Space and new line charcters (U+0020 and U+000A) may be generated
  931. // according to the text formatting.
  932. FPDFEMB_POINT origin; // X/Y position for the character origin, in hundredth of points
  933. FPDFEMB_RECT bbox; // Bounding box of the character, in hundredth of points
  934. // Maybe an empty box (left == right or top == bottom).
  935. };
  936. // Function: FPDFEMB_GetCharInfo
  937. // Get character information
  938. // Parameters:
  939. // page - Page handle
  940. // index - Character index, starting from zero
  941. // char_info - Receiving the character info
  942. // Return Value:
  943. // Error code, or FPDFERR_SUCCESS for success
  944. // Comments:
  945. // Application must call FPDFEMB_GetCharCount first before it can call this function
  946. // for any particular characters.
  947. //
  948. FPDFEMB_RESULT FPDFEMB_GetCharInfo(FPDFEMB_PAGE page, int index, FPDFEMB_CHAR_INFO* char_info);
  949. // Function: FPDFEMB_GetCharIndexAtPos()
  950. // Get index of character nearest to a certain position on the page
  951. // Parameters:
  952. // page - Page handle
  953. // x - X position in PDF page coordination system
  954. // y - Y position in PDF page coordination system
  955. // index - Pointer to an integer receiving zero-based character index.
  956. // Return Value:
  957. // Error code, or FPDFERR_SUCCESS for success
  958. // Comments:
  959. // This function finds the character that's nearest to the particular page position.
  960. // If there is no character, the output index will be -1.
  961. //
  962. FPDFEMB_RESULT FPDFEMB_GetCharIndexAtPos(FPDFEMB_PAGE page, double x, double y, int* index);
  963. /********************************************************************************************
  964. ****
  965. **** Device Independant Bitmap
  966. ****
  967. ********************************************************************************************/
  968. #define FPDFDIB_BGR 1 // 3 bytes per pixel, byte order: Blue, Green, Red
  969. #define FPDFDIB_BGRx 2 // 4 bytes per pixel, byte order: Blue, Green, Red, not used
  970. #define FPDFDIB_BGRA 3 // 4 bytes per pixel, byte order: Blue, Green, Red, Alpha
  971. #define FPDFDIB_GRAY 4 // 1 byte per pixel (grayscale)
  972. // Function: FPDFEMB_CreateDIB
  973. // Create a DIB (Device Independant Bitmap)
  974. // Parameters:
  975. // width - Width pixels;
  976. // height - Height pixels;
  977. // format - Format type. See FPDFDIB_xxx constants
  978. // buffer - External buffer provided for the DIB,
  979. // or NULL if new buffer is to be allocated.
  980. // stride - Number of bytes for each scan line, for external buffer only.
  981. // If not specified, 4-byte alignment assumed.
  982. // dib - Receiving the created DIB handle
  983. // Return Value:
  984. // Error code, or FPDFERR_SUCCESS for success
  985. // Comments:
  986. // If "buffer" parameter is not NULL, then the provided buffer must conform
  987. // to standard DIB format (see comments of FPDFEMB_GetDIBData function below).
  988. //
  989. // This function doesn't initialize the pixels inside the DIB buffer. So if you
  990. // want to use the DIB to display a PDF page, you usually need to initialize
  991. // the DIB to white background by youself.
  992. //
  993. FPDFEMB_RESULT FPDFEMB_CreateDIB(int width, int height, int format,
  994. void* buffer, int stride, FPDFEMB_BITMAP* dib);
  995. // Function: FPDFEMB_DestroyDIB
  996. // Destroy a DIB
  997. // Parameters:
  998. // dib - DIB handle
  999. // Return Value:
  1000. // Error code, or FPDFERR_SUCCESS for success
  1001. // Comments:
  1002. // If external buffer is used (specified in "buffer" parameter when calling
  1003. // FPDFEMB_CreateDIB), the buffer will not be destroyed.
  1004. //
  1005. FPDFEMB_RESULT FPDFEMB_DestroyDIB(FPDFEMB_BITMAP dib);
  1006. // Function: FPDFEMB_GetDIBWidth
  1007. // Get width (in pixels) of a DIB
  1008. // Parameters:
  1009. // dib - DIB handle
  1010. // Return Value:
  1011. // DIB width in pixels.
  1012. //
  1013. int FPDFEMB_GetDIBWidth(FPDFEMB_BITMAP dib);
  1014. // Function: FPDFEMB_GetDIBHeight
  1015. // Get height (in pixels) of a DIB
  1016. // Parameters:
  1017. // dib - DIB handle
  1018. // Return Value:
  1019. // DIB height in pixels.
  1020. //
  1021. int FPDFEMB_GetDIBHeight(FPDFEMB_BITMAP dib);
  1022. // Function: FPDFEMB_GetDIBData
  1023. // Get data pointer to a DIB
  1024. // Parameters:
  1025. // dib - DIB handle
  1026. // Return Value:
  1027. // Pointer to the DIB data.
  1028. // Comments:
  1029. // DIB data are organized in scanlines, from top down.
  1030. //
  1031. void* FPDFEMB_GetDIBData(FPDFEMB_BITMAP dib);
  1032. // Function: FPDFEMB_GetDIBStride
  1033. // Get scan line stride of a DIB
  1034. // Parameters:
  1035. // dib - DIB handle
  1036. // Return Value:
  1037. // Number of bytes occupied by a scanline
  1038. //
  1039. int FPDFEMB_GetDIBStride(FPDFEMB_BITMAP dib);
  1040. // Function: FPDFEMB_GetRotatedDIB
  1041. // Swap X/Y dimensions of a DIB to generate a rotated new DIB
  1042. // Parameters:
  1043. // dib - DIB handle
  1044. // flip_x - Whether flip pixels on the destination X dimension (left/right)
  1045. // flip_y - Whether flip pixels on the destination Y dimension (up/down)
  1046. // result_dib - Receiving the result DIB handle
  1047. // Return Value:
  1048. // Error code, or FPDFERR_SUCCESS for success
  1049. //
  1050. FPDFEMB_RESULT FPDFEMB_GetRotatedDIB(FPDFEMB_BITMAP dib,
  1051. FPDFEMB_BOOL bFlipX, FPDFEMB_BOOL bFlipY,
  1052. FPDFEMB_BITMAP* result_dib);
  1053. // Function: FPDFEMB_StretchDIB
  1054. // Stretch a source DIB into another destination DIB
  1055. // Parameters:
  1056. // dest_dib - The destination DIB handle
  1057. // dest_left - Left position in the destination DIB
  1058. // dest_top - Top position in the destination DIB
  1059. // dest_width - Destination width, in pixels. Can be negative for horizontal flipping
  1060. // dest_height - Destination height, in pixels. Can be negative for vertical flipping
  1061. // clip - Destination clipping rectangle, or NULL for no clipping.
  1062. // The coordinations are measured in destination bitmap.
  1063. // src_dib - Source DIB handle.
  1064. // interpol - Whether we use interpolation to improve the result quality
  1065. // Return Value:
  1066. // Error code, or FPDFERR_SUCCESS for success
  1067. //
  1068. FPDFEMB_RESULT FPDFEMB_StretchDIB(FPDFEMB_BITMAP dest_dib, int dest_left, int dest_top,
  1069. int dest_width, int dest_height, FPDFEMB_RECT* clip_rect,
  1070. FPDFEMB_BITMAP src_dib, FPDFEMB_BOOL interpol);
  1071. // Function: FPDFEMB_TransformDIB
  1072. // Transform a source DIB into another destination DIB
  1073. // Parameters:
  1074. // dest_dib - The destination DIB handle
  1075. // clip - Destination clipping rectangle, or NULL for no clipping.
  1076. // The coordinations are measured in destination bitmap.
  1077. // src_dib - Source DIB handle.
  1078. // x - X coordination of the dest origin
  1079. // y - Y coordination of the dest origin
  1080. // xx - X distance of the dest X vector
  1081. // yx - Y distance of the dest X vector
  1082. // xy - X distance of the dest Y vector
  1083. // yy - Y distance of the dest Y vector
  1084. // interpol - Whether we use interpolation to improve the result quality
  1085. // Return Value:
  1086. // Error code, or FPDFERR_SUCCESS for success
  1087. // Comments:
  1088. // All coordinations and distances are measured in destination bitmap system.
  1089. //
  1090. // This function places the bottom-left pixel of the image at the destination
  1091. // origin, then the bottom sideline along the destination X vector, and left
  1092. // sideline along the destination Y vector.
  1093. //
  1094. FPDFEMB_RESULT FPDFEMB_TransformDIB(FPDFEMB_BITMAP dest_dib, FPDFEMB_RECT* clip_rect,
  1095. FPDFEMB_BITMAP src_dib, int x, int y, int xx, int yx,
  1096. int xy, int yy, FPDFEMB_BOOL interpol);
  1097. /********************************************************************************************
  1098. ****
  1099. **** Custom Font Handler and CJK Support
  1100. ****
  1101. ********************************************************************************************/
  1102. // FPDFEMB comes with standard fonts for Latin characters. If your device is targeted to
  1103. // Eastern Asian markets, then system fonts must be provided and registered with FPDFEMB.
  1104. // Depending on your device configuration, those system fonts might be in TrueType or Type1
  1105. // format, or some other non-standard compact format. For the first case, you should register
  1106. // a font mapper so FPDFEMB can pick the right font file, and for the second case, you
  1107. // should register a glyph provider so FPDFEMB can get glyph bitmap for each character.
  1108. #define FPDFEMB_CHARSET_DEFAULT 0
  1109. #define FPDFEMB_CHARSET_GB 936
  1110. #define FPDFEMB_CHARSET_BIG5 950
  1111. #define FPDFEMB_CHARSET_JIS 932
  1112. #define FPDFEMB_CHARSET_KOREA 949
  1113. #define FPDFEMB_CHARSET_UNICODE 1200
  1114. #define FPDFEMB_FONT_FIXEDPITCH 1
  1115. #define FPDFEMB_FONT_SERIF 2
  1116. #define FPDFEMB_FONT_SYMBOLIC 4
  1117. #define FPDFEMB_FONT_SCRIPT 8
  1118. #define FPDFEMB_FONT_NONSYMBOLIC 32
  1119. #define FPDFEMB_FONT_ITALIC 64
  1120. #define FPDFEMB_FONT_ALLCAP 0x10000
  1121. #define FPDFEMB_FONT_SMALLCAP 0x20000
  1122. #define FPDFEMB_FONT_FORCEBOLD 0x40000
  1123. // Structure: FPDFEMB_FONT_MAPPER
  1124. // Defines interface for system font mapper.
  1125. //
  1126. struct FPDFEMB_FONT_MAPPER
  1127. {
  1128. // Interface: MapFont
  1129. // Find font file path for a particular PDF font
  1130. // Parameters:
  1131. // mapper - Pointer to the FPDFEMB_FONT_MAPPER structure
  1132. // name - Font name
  1133. // charset - Charset ID (see above FPDFEMB_CHARSET_xxx constants)
  1134. // flags - Font flags (see above FPDFEMB_FONT_xxx constants)
  1135. // weight - Weight of the font. Range from 100 to 900. 400 is normal,
  1136. // 700 is bold.
  1137. // path - Receiving the full file path. The buffer size is 512 bytes.
  1138. // face_index - Receiving an zero-based index value for the font face, if the
  1139. // mapped font file is a "collection" (meaning a number of faces
  1140. // are stored in the same file). If the font file is not a
  1141. // collection, the index value should be zero.
  1142. // Return Value:
  1143. // Non-zero for success, 0 for failure.
  1144. //
  1145. FPDFEMB_BOOL (*MapFont)(struct FPDFEMB_FONT_MAPPER* mapper, const char* name, int charset,
  1146. unsigned int flags, int weight,
  1147. char* path, int* face_index);
  1148. void* user; // A user pointer, used by the application
  1149. };
  1150. // Function: FPDFEMB_SetFontMapper
  1151. // Use a system font mapper (typically for Chinese/Japanese/Korean charsets)
  1152. // Parameters:
  1153. // mapper - Pointer to FPDFEMB_FONT_MAPPER structure.
  1154. // Return Value:
  1155. // Error code, or FPDFERR_SUCCESS for success
  1156. // Comments:
  1157. // This function is used with devices that come with one or more system fonts,
  1158. // and those fonts are in standard TT or T1 format.
  1159. //
  1160. FPDFEMB_RESULT FPDFEMB_SetFontMapper(FPDFEMB_FONT_MAPPER* mapper);
  1161. // Structure: FPDFEMB_GLYPH_PROVIDER
  1162. // Interface for providing glyph bitmap of non-latin characters.
  1163. // This is usually used for embedded devices with Chinese/Japanese/Korean
  1164. // fonts installed, but those fonts are not in TrueType or Type1 format.
  1165. //
  1166. struct FPDFEMB_GLYPH_PROVIDER
  1167. {
  1168. // Interface: MapFont
  1169. // Return an internal handle for a font
  1170. // Parameters:
  1171. // provider - Pointer to this structure
  1172. // name - Font name
  1173. // charset - Charset ID (see above FPDFEMB_CHARSET_xxx constants)
  1174. // flags - Font flags (see above FPDFEMB_FONT_xxx constants)
  1175. // weight - Weight of the font. Range from 100 to 900. 400 is normal,
  1176. // 700 is bold.
  1177. // Return Value:
  1178. // An internal handle to the mapped font. If the embedded device supports
  1179. // multiple fonts, then this value can serve as an identifier to differentiate
  1180. // among them. If the device supports only one font, then implementation of
  1181. // this function can simply return NULL.
  1182. //
  1183. void* (*MapFont)(struct FPDFEMB_GLYPH_PROVIDER* provider, const char* name, int charset,
  1184. unsigned int flags, int weight);
  1185. // Interface: GetGlyphBBox
  1186. // Get glyph bounding box
  1187. // Parameters:
  1188. // provider - Pointer to this structure
  1189. // font - Internal handle to the font. Returned by MapFont interface.
  1190. // unicode - Unicode of the character
  1191. // CID - Adobe CID for this character. Or zero if not available.
  1192. // bbox - Receiving the result bounding box. See comments below.
  1193. // Return Value:
  1194. // None.
  1195. // Comments:
  1196. // The bounding box is measure in a glyph coordination system, in which the
  1197. // origin is set to character origin, and unit is set to one-thousandth of
  1198. // "em size" (representing the font size).
  1199. //
  1200. // In most CJK fonts, all CJK characters (except some symbols or western
  1201. // characters) have same glyph bounding box:
  1202. // left = 0, right = 1000, bottom = -220, top = 780.
  1203. //
  1204. // It's OK to return a box that's larger than the actual glyph box.
  1205. //
  1206. void (*GetGlyphBBox)(struct FPDFEMB_GLYPH_PROVIDER* provider, void* font,
  1207. FPDFEMB_WCHAR unicode, unsigned short CID,
  1208. FPDFEMB_RECT* bbox);
  1209. // Interface: GetGlyphBitmap
  1210. // Get bitmap of a glyph
  1211. // Parameters:
  1212. // provider - Pointer to this structure
  1213. // font - Internal handle to the font. Returned by MapFont interface.
  1214. // unicode - Unicode of the character
  1215. // CID - Adobe CID for this character. Or zero if not available.
  1216. // font_width - Width of the font em square, measured in device units.
  1217. // font_height - Height of the font em square, measured in device units.
  1218. // left - Receiving the left offset, from the character origin, of the
  1219. // result glyph bitmap. Positive value will move the bitmap to
  1220. // the right side, negative to the left.
  1221. // top - Receiving the top offset, from the character origin, of the
  1222. // result glyph bitmap. Positive value will move the bitmap upward,
  1223. // negative downward.
  1224. // bitmap_width - Receiving number of width pixels in the result bitmap
  1225. // bitmap_height - Receiving number of height pixels in the result bitmap
  1226. // buffer - Receiving a data buffer pointer, allocated by the implementation.
  1227. // See comments below.
  1228. // stride - Receiving number of bytes per scanline, in the data buffer.
  1229. // pdf_width - Width of the character specified in PDF. It is measured in one-
  1230. // thousandth of the font width. It can be 0 if width not specified
  1231. // in PDF. See comments below.
  1232. // Return Value:
  1233. // Non-zero for success. 0 for failure. In this case the glyph can not be displayed.
  1234. // Comments:
  1235. // The buffer should be allocated by implemenation. And it must be allocated
  1236. // using FPDFEMB_AllocMemory function. The result buffer will be destroyed by
  1237. // FPDFEMB SDK, so implementation should not destroy it.
  1238. //
  1239. // The implementation should write "coverage" data into allocated buffer, one byte
  1240. // for each pixel, from top scanline to bottom scanline, within each scan line,
  1241. // from left pixel to right. Coverage 0 means the pixel is outside the glyph,
  1242. // coverage 255 means the pixel is inside the glyph.
  1243. //
  1244. // The "pdf_width" parameter can be used to scale the character in system font
  1245. // horizontally to match the font width specified in PDF. For example, if we have
  1246. // a PDF file which requires a character in half-width (pdf_width is 500), but
  1247. // in the system font the character has full-width (1000), then the glyph provider
  1248. // implementation should scale the font horizontally to half of its original width.
  1249. //
  1250. FPDFEMB_BOOL (*GetGlyphBitmap)(struct FPDFEMB_GLYPH_PROVIDER* provider, void* font,
  1251. FPDFEMB_WCHAR unicode, unsigned short CID,
  1252. double font_width, double font_height, int* left, int* top,
  1253. int* bitmap_width, int* bitmap_height,
  1254. void** buffer, int* stride, int pdf_width);
  1255. void* user; // A user pointer, used by the application
  1256. };
  1257. // Function: FPDFEMB_SetGlyphProvider
  1258. // Make use of a glyph provider: generating glyph bitmap for non-Latin characters
  1259. // Parameters:
  1260. // provider - Pointer to the glyph provider structure.
  1261. // This structure must stay valid throughout usage of FPDFEMB module.
  1262. // Return Value:
  1263. // None.
  1264. // Comments:
  1265. // FPDFEMB embeds some standard fonts for Latin characters and symbols, like
  1266. // Times, Courier and Helvetica (Arial). For non-Latin characters, however,
  1267. // FPDFEMB has to ask glyph provide for help.
  1268. //
  1269. // If an embedded device carries fonts for non-Latin character sets, especially
  1270. // those for CJK markets, then the application can implement a glyph provider,
  1271. // allowing PDFs using non-embedded CJK fonts to be properly displayed.
  1272. //
  1273. void FPDFEMB_SetGlyphProvider(FPDFEMB_GLYPH_PROVIDER* provider);
  1274. // Function: FPDFEMB_LoadCMap_GB
  1275. // Function: FPDFEMB_LoadCMap_GB_Ext
  1276. // Function: FPDFEMB_LoadCMap_CNS
  1277. // Function: FPDFEMB_LoadCMap_Korean
  1278. // Function: FPDFEMB_LoadCMap_Japan
  1279. // Function: FPDFEMB_LoadCMap_Japan_Ext
  1280. // Make use of character encoding maps embedded with FPDFEMB
  1281. // Parameters:
  1282. // None.
  1283. // Return Value:
  1284. // None.
  1285. // Comments:
  1286. // These functions add character encoding data to your application. Each call
  1287. // will increase the code size of your application. Total data size for all
  1288. // character sets is 151K bytes.
  1289. void FPDFEMB_LoadCMap_GB();
  1290. void FPDFEMB_LoadCMap_GB_Ext(); // Load full code table for GB
  1291. void FPDFEMB_LoadCMap_CNS();
  1292. void FPDFEMB_LoadCMap_Korea();
  1293. void FPDFEMB_LoadCMap_Japan();
  1294. void FPDFEMB_LoadCMap_Japan_Ext(); // Load full code table for Japan
  1295. /********************************************************************************************
  1296. ****
  1297. **** Document Information
  1298. ****
  1299. ********************************************************************************************/
  1300. // Function: PDFEMB_GetDocInfoString
  1301. // Get information string about the document, like creator, modifcation date, etc.
  1302. // Parameters:
  1303. // document - Handle to the document
  1304. // key - A byte string for the information key. Currently can be one of the followings:
  1305. // "Title", "Author", "Subject", "Keywords", "Creator", "Producer", "CreationDate",
  1306. // "ModDate", or some custom information key, if supported by the PDF file.
  1307. // buffer - A buffer allocated by the application, or NULL.
  1308. // bufsize - [IN/OUT] A pointer to a number indicating the buffer size (number of bytes),
  1309. // before this function call. After return, this place will store
  1310. // number of bytes used by the output (including terminator).
  1311. // Return Value:
  1312. // Error code, or FPDFERR_SUCCESS for success
  1313. // Comments:
  1314. // The string is output in Unicode, using UTF-16LE format. It's terminated by
  1315. // two consecutive zero bytes.
  1316. //
  1317. // If the "buffer" parameter is NULL, then the "bufsize" parameter will receive
  1318. // number of bytes required to store the string (including the two-byte terminator).
  1319. //
  1320. FPDFEMB_RESULT FPDFEMB_GetDocInfoString(FPDFEMB_DOCUMENT document, const char* key, void* buffer, unsigned int* bufsize);
  1321. /********************************************************************************************
  1322. ****
  1323. **** Action (Destination) Information
  1324. ****
  1325. ********************************************************************************************/
  1326. typedef void* FPDFEMB_ACTION;
  1327. // Action types supported by FPDFEMB
  1328. #define FPDFEMB_DEST_NONE 0 // No or unsupported destination
  1329. #define FPDFEMB_DEST_PAGE 1 // A page inside the same document
  1330. #define FPDFEMB_DEST_DOC 2 // An external PDF document
  1331. #define FPDFEMB_DEST_URL 3 // An external URL
  1332. #define FPDFEMB_ACTION_LAUNCH 4 // Launch an external file or command
  1333. // Zoom mode for destination
  1334. #define FPDFEMB_ZOOM_NONE 0 // Zoom mode not specified
  1335. #define FPDFEMB_ZOOM_FACTOR 1 // Specific zoom factor is used
  1336. #define FPDFEMB_ZOOM_FITPAGE 2 // Fit the whole page on screen
  1337. #define FPDFEMB_ZOOM_FITWIDTH 3 // Fit width of the page on screen
  1338. #define FPDFEMB_ZOOM_FITHEIGHT 4 // Fit height of the page on screen
  1339. #define FPDFEMB_ZOOM_FITRECT 5 // Fit a particular rectangle on screen
  1340. #define FPDFEMB_ZOOM_FITCONTENT 6 // Fit whole content of page on screen
  1341. #define FPDFEMB_ZOOM_FITCONTENTW 7 // Fit content width of page on screen
  1342. #define FPDFEMB_ZOOM_FITCONTENTH 8 // Fit content height of page on screen
  1343. // Data structure for page destination
  1344. struct FPDFEMB_PAGEDEST
  1345. {
  1346. int page_index; // Zero based index for the page
  1347. int zoom_mode; // See FPDFEMB_ZOOM_xxx definition above
  1348. int zoom_factor; // For FPDFEMB_ZOOM_FACTOR only: the zoom factor (in percentage)
  1349. FPDFEMB_RECT position; // Specify position inside the page. Depends on the zoom mode,
  1350. // different members of the rectangle are used:
  1351. // FPDFEMB_ZOOM_NONE: left, top
  1352. // FPDFEMB_ZOOM_FACTOR: left, top
  1353. // FPDFEMB_ZOOM_FITPAGE: none
  1354. // FPDFEMB_ZOOM_FITWIDTH: top
  1355. // FPDFEMB_ZOOM_FITHEIGHT: left
  1356. // FPDFEMB_ZOOM_FITRECT: left, top, bottom, right
  1357. // FPDFEMB_ZOOM_FITCONTENT: none
  1358. // FPDFEMB_ZOOM_FITCONTENTW: top
  1359. // FPDFEMB_ZOOM_FITCONTENTH: left
  1360. };
  1361. // Data structure for document destination
  1362. struct FPDFEMB_DOCDEST
  1363. {
  1364. FPDFEMB_PAGEDEST page_data; // page data
  1365. char* file_name; // The file name, encoded in original charset (maybe MBCS)
  1366. };
  1367. // Data structure for URL destination
  1368. struct FPDFEMB_URLDEST
  1369. {
  1370. char* url; // URL encoded in 7-bit ASCII
  1371. };
  1372. // Data structure for Launch action
  1373. struct FPDFEMB_LAUNCHACTION
  1374. {
  1375. int new_window; // Whether a new window should be opened
  1376. char* file_name; // The file name, encoded in original charset (maybe MBCS)
  1377. };
  1378. // Function: FPDFEMB_Action_GetType
  1379. // Get type of an action
  1380. // Parameters:
  1381. // document - Handle to the document
  1382. // action - Handle to the action
  1383. // dest_type - Pointer to an integer receiving type of the destination. See the above
  1384. // FPDFEMB_DEST_xxx definitions
  1385. // data_size - Pointer to an integer receiving data block size for the destination.
  1386. // If this parameter is NULL, then data size won't be retrieved.
  1387. // Comments:
  1388. // Each different type of destination has different data structure. The "data_size" result
  1389. // indicates how many bytes is required to hold the destination data structure. The application
  1390. // can then allocate sufficient buffer and then call FPDFEMB_Bookmark_GetDest function to
  1391. // get the real data.
  1392. //
  1393. FPDFEMB_RESULT FPDFEMB_Action_GetType(FPDFEMB_DOCUMENT document, FPDFEMB_ACTION action, int* dest_type, int* data_size);
  1394. // Function: FPDFEMB_Action_GetData
  1395. // Get detailed data of a particular action
  1396. // Parameters:
  1397. // document - Handle to the document
  1398. // action - Handle to the action
  1399. // buffer - Application allocated buffer receiving the destination data
  1400. // Return Value:
  1401. // Error code, or FPDFERR_SUCCESS for success.
  1402. // Comments:
  1403. // See data structure definition for different action type above. Please note
  1404. // the actual action data might use more space than the structure definition
  1405. // shows, to store things like file name or URL. So you should always call
  1406. // FPDFEMB_Action_GetType first to get data size then allocate enough buffer
  1407. // for this call.
  1408. //
  1409. FPDFEMB_RESULT FPDFEMB_Action_GetData(FPDFEMB_DOCUMENT document, FPDFEMB_ACTION action, void* buffer);
  1410. // Function: FPDFEMB_Action_GetNext
  1411. // Get next action in an action chain
  1412. // Parameters:
  1413. // document - Handle to the document
  1414. // action - Handle to current action
  1415. // next - Receiving handle to next action.
  1416. // Return Value:
  1417. // Error code, or FPDFERR_SUCCESS for success.
  1418. // Comments:
  1419. // If there is no next action, the "next" parameter will be set to NULL after the function returns.
  1420. //
  1421. FPDFEMB_RESULT FPDFEMB_Action_GetNext(FPDFEMB_ACTION action, FPDFEMB_ACTION* next);
  1422. /********************************************************************************************
  1423. ****
  1424. **** Bookmark Information
  1425. ****
  1426. ********************************************************************************************/
  1427. typedef void* FPDFEMB_BOOKMARK;
  1428. // Function: FPDFEMB_Bookmark_GetFirstChild
  1429. // Get first child of a bookmark item, or first top level bookmark item
  1430. // Parameters:
  1431. // document - Handle to the document
  1432. // parent - Handle to the parent bookmark.
  1433. // Can be NULL if you want to get the first top level item.
  1434. // bookmark - Receiving handle to the first child or top level bookmark item.
  1435. // If result is NULL, then bookmark not found.
  1436. // Return Value:
  1437. // Error code, or FPDFERR_SUCCESS for success
  1438. //
  1439. FPDFEMB_RESULT FPDFEMB_Bookmark_GetFirstChild(FPDFEMB_DOCUMENT document, FPDFEMB_BOOKMARK parent,
  1440. FPDFEMB_BOOKMARK* bookmark);
  1441. // Function: FPDFEMB_Bookmark_GetFirstChild
  1442. // Get next sibling of a bookmark item
  1443. // Parameters:
  1444. // document - Handle to the document
  1445. // bookmark - Handle to the bookmark
  1446. // sibling - Receiving the handle of next sibling.
  1447. // If result is NULL, then this is the last bookmark in this level.
  1448. // Return Value:
  1449. // Error code, or FPDFERR_SUCCESS for success
  1450. //
  1451. FPDFEMB_RESULT FPDFEMB_Bookmark_GetNextSibling(FPDFEMB_DOCUMENT document, FPDFEMB_BOOKMARK bookmark,
  1452. FPDFEMB_BOOKMARK* sibling);
  1453. // Function: FPDFEMB_Bookmark_GetTitle
  1454. // Get title of a bookmark
  1455. // Parameters:
  1456. // bookmark - Handle to the bookmark
  1457. // buffer - A buffer allocated by the application, or NULL.
  1458. // bufsize - [IN/OUT] A pointer to a number indicating the buffer size,
  1459. // before this function call. After return, this place will store
  1460. // number of bytes used by the output (including terminator).
  1461. // Return Value:
  1462. // Error code, or FPDFERR_SUCCESS for success
  1463. // Comments:
  1464. // The title is output in Unicode, using UTF-16LE format. It's terminated by
  1465. // two