Fix a global buffer overflow issue in CXFA_ItemLayoutProcessor::CalculatePositionedCo...
[pdfium.git] / public / fpdfview.h
1 // Copyright 2014 PDFium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4  
5 // Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com
6
7 // NOTE: External docs refer to this file as "fpdfview.h", so do not rename
8 // despite lack of consitency with other public files.
9
10 #ifndef _FPDFVIEW_H_
11 #define _FPDFVIEW_H_
12
13 #if defined(_WIN32) && !defined(__WINDOWS__)
14 #include <windows.h>
15 #endif
16
17 //  TODO: remove the #define when XFA is officially in pdfium
18 #define PDF_USE_XFA
19
20 // Data types
21 typedef void*   FPDF_MODULEMGR;
22
23 // PDF types
24 typedef void*   FPDF_DOCUMENT;          
25 typedef void*   FPDF_PAGE;                      
26 typedef void*   FPDF_WIDGET;    
27 typedef void*   FPDF_STRINGHANDLE;
28 typedef void*   FPDF_PAGEOBJECT;        // Page object(text, path, etc)
29 typedef void*   FPDF_PATH;
30 typedef void*   FPDF_CLIPPATH;  
31 typedef void*   FPDF_BITMAP;    
32 typedef void*   FPDF_FONT;                      
33
34 typedef void*   FPDF_TEXTPAGE;
35 typedef void*   FPDF_SCHHANDLE;
36 typedef void*   FPDF_PAGELINK;
37 typedef void*   FPDF_HMODULE;
38 typedef void*   FPDF_DOCSCHHANDLE;
39
40 typedef void*   FPDF_BOOKMARK;
41 typedef void*   FPDF_DEST;
42 typedef void*   FPDF_ACTION;
43 typedef void*   FPDF_LINK;
44 typedef void*   FPDF_PAGERANGE;
45
46 // Basic data types
47 typedef void*                   FPDF_LPVOID;
48 typedef void const*             FPDF_LPCVOID;
49 typedef int                             FPDF_RESULT;
50 typedef int                             FPDF_BOOL;
51 typedef int                             FPDF_ERROR;     
52 typedef unsigned long   FPDF_DWORD;
53
54 typedef float                   FS_FLOAT;
55
56 // Duplex types
57 typedef enum _FPDF_DUPLEXTYPE_ {
58     DuplexUndefined = 0,
59     Simplex,
60     DuplexFlipShortEdge,
61     DuplexFlipLongEdge
62 } FPDF_DUPLEXTYPE;
63
64 // String types
65 typedef unsigned short                  FPDF_WCHAR;
66 typedef unsigned char const*    FPDF_LPCBYTE;
67 typedef char const*                             FPDF_LPCSTR;
68
69 // FPDFSDK may use three types of strings: byte string, wide string (UTF-16LE encoded), and platform dependent string
70 typedef const char*                             FPDF_BYTESTRING;
71
72 typedef const unsigned short*   FPDF_WIDESTRING;                // Foxit PDF SDK always use UTF-16LE encoding wide string,
73                                                                                                                 // each character use 2 bytes (except surrogation), with low byte first.
74
75 #ifndef _FPDF_DEF_STR_
76 #define _FPDF_DEF_STR_
77 /** @brief Structure for byte string.
78   *
79   * @note In SDK, a byte string commonly means a UTF-16LE format string.
80   */
81 typedef struct _FPDF_BSTR
82 {
83         /** 
84          * @brief String buffer.
85          */
86         char*   str;
87         /**
88          * @brief       Length of a string, in bytes.
89          */
90         int     len;
91 } FPDF_BSTR;
92
93 #endif
94
95 // For Windows programmers: for most case it's OK to treat FPDF_WIDESTRING as Windows unicode string,
96 //               however, special care needs to be taken if you expect to process Unicode larger than 0xffff.
97 // For Linux/Unix programmers: most compiler/library environment uses 4 bytes for a Unicode character,
98 //              you have to convert between FPDF_WIDESTRING and system wide string by yourself.
99
100 #ifdef _WIN32_WCE
101 typedef const unsigned short* FPDF_STRING;
102 #else
103 typedef const char* FPDF_STRING;
104 #endif
105
106 #ifndef _FS_DEF_MATRIX_
107 #define _FS_DEF_MATRIX_
108 /** @brief Matrix for transformation. */
109 typedef struct _FS_MATRIX_
110 {
111         float   a;      /**< @brief Coefficient a.*/
112         float   b;      /**< @brief Coefficient b.*/
113         float   c;      /**< @brief Coefficient c.*/
114         float   d;      /**< @brief Coefficient d.*/
115         float   e;      /**< @brief Coefficient e.*/
116         float   f;      /**< @brief Coefficient f.*/
117 } FS_MATRIX;
118 #endif
119
120 #ifndef _FS_DEF_RECTF_
121 #define _FS_DEF_RECTF_
122 /** @brief Rectangle area(float) in device or page coordination system. */
123 typedef struct _FS_RECTF_
124 {
125         /**@{*/
126         /** @brief The x-coordinate of the left-top corner. */
127         float   left;
128         /** @brief The y-coordinate of the left-top corner. */
129         float   top;
130         /** @brief The x-coordinate of the right-bottom corner. */
131         float   right;
132         /** @brief The y-coordinate of the right-bottom corner. */
133         float   bottom;
134         /**@}*/
135 }* FS_LPRECTF, FS_RECTF;
136 /** @brief Const Pointer to ::FS_RECTF structure.*/
137 typedef const FS_RECTF* FS_LPCRECTF;
138 #endif
139
140 #if defined(_WIN32) && defined(FPDFSDK_EXPORTS)
141 // On Windows system, functions are exported in a DLL
142 #define DLLEXPORT __declspec( dllexport )
143 #define STDCALL __stdcall
144 #else
145 #define DLLEXPORT
146 #define STDCALL
147 #endif
148
149 extern const char g_ExpireDate[];
150 extern const char g_ModuleCodes[];
151
152 // Exported Functions
153 #ifdef __cplusplus
154 extern "C" {
155 #endif
156
157 // Function: FPDF_InitLibrary
158 //                      Initialize the FPDFSDK library 
159 // Parameters:
160 //                      None
161 // Return value:
162 //                      None.
163 // Comments:
164 //                      You have to call this function before you can call any PDF processing functions.
165
166 DLLEXPORT void STDCALL FPDF_InitLibrary();
167
168
169 // Function: FPDF_DestroyLibary
170 //                      Release all resources allocated by the FPDFSDK library.
171 // Parameters:
172 //                      None.
173 // Return value:
174 //                      None.
175 // Comments:
176 //                      You can call this function to release all memory blocks allocated by the library. 
177 //                      After this function called, you should not call any PDF processing functions.
178 DLLEXPORT void STDCALL FPDF_DestroyLibrary();
179
180 //Policy for accessing the local machine time.
181 #define FPDF_POLICY_MACHINETIME_ACCESS  0
182
183 // Function: FPDF_SetSandBoxPolicy
184 //                      Set the policy for the sandbox environment.
185 // Parameters:  
186 //                      policy          -       The specified policy for setting, for example:FPDF_POLICY_MACHINETIME_ACCESS.
187 //                      enable          -       True for enable, False for disable the policy.
188 // Return value:
189 //                      None.
190 DLLEXPORT void  STDCALL FPDF_SetSandBoxPolicy(FPDF_DWORD policy, FPDF_BOOL enable);
191
192 /**
193 * Open and load a PDF document.
194 * @param[in] file_path  -       Path to the PDF file (including extension).
195 * @param[in] password   -       A string used as the password for PDF file. 
196 *                                                       If no password needed, empty or NULL can be used.
197 * @note         Loaded document can be closed by FPDF_CloseDocument.
198 *                       If this function fails, you can use FPDF_GetLastError() to retrieve
199 *                       the reason why it fails.
200 *                       The application should call ::FPDF_LoadXFA function after PDF document loaded 
201 *                       to support XFA fields in fpdfformfill.h file.
202 *
203 * @retval       A handle to the loaded document. If failed, NULL is returned.
204 */
205 DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_LoadDocument(FPDF_STRING file_path, 
206         FPDF_BYTESTRING password);
207
208 // Function: FPDF_LoadMemDocument
209 //                      Open and load a PDF document from memory.
210 // Parameters: 
211 //                      data_buf        -       Pointer to a buffer containing the PDF document.
212 //                      size            -       Number of bytes in the PDF document.
213 //                      password        -       A string used as the password for PDF file. 
214 //                                                      If no password needed, empty or NULL can be used.
215 // Return value:
216 //                      A handle to the loaded document. If failed, NULL is returned.
217 // Comments:
218 //                      The memory buffer must remain valid when the document is open.
219 //                      Loaded document can be closed by FPDF_CloseDocument.
220 //                      If this function fails, you can use FPDF_GetLastError() to retrieve
221 //                      the reason why it fails.
222 // Notes:
223 //                      The application should call ::FPDF_LoadXFA function after PDF document loaded 
224 //                      to support XFA fields in fpdfformfill.h file.
225 //
226 DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_LoadMemDocument(const void* data_buf, 
227                                                                                         int size, FPDF_BYTESTRING password);
228
229 // Structure for custom file access.
230 typedef struct {
231         // File length, in bytes.
232         unsigned long   m_FileLen;
233
234         // A function pointer for getting a block of data from specific position.
235         // Position is specified by byte offset from beginning of the file.
236         // The position and size will never go out range of file length.
237         // It may be possible for FPDFSDK to call this function multiple times for same position.
238         // Return value: should be non-zero if successful, zero for error.
239         int                             (*m_GetBlock)(void* param, unsigned long position, unsigned char* pBuf, unsigned long size);
240
241         // A custom pointer for all implementation specific data.
242         // This pointer will be used as the first parameter to m_GetBlock callback.
243         void*                   m_Param;
244 } FPDF_FILEACCESS;
245
246 /**
247  * @brief Structure for file reading or writing (I/O).
248  *
249  * @note This is a handler and should be implemented by callers.
250  */
251 typedef struct _FPDF_FILEHANDLER
252 {
253         /**
254          * @brief User-defined data.
255          * @note Callers can use this field to track controls.
256          */
257         FPDF_LPVOID     clientData;
258         /**
259          * @brief Callback function to release the current file stream object.
260          *
261          * @param[in] clientData        Pointer to user-defined data.
262          *
263          * @return None.
264          */
265         void            (*Release)(FPDF_LPVOID clientData);
266         /**
267          * @brief Callback function to retrieve the current file stream size.
268          *
269          * @param[in] clientData        Pointer to user-defined data.
270          *
271          * @return Size of file stream.
272          */
273         FPDF_DWORD      (*GetSize)(FPDF_LPVOID clientData);
274         /**
275          * @brief Callback function to read data from the current file stream.
276          *
277          * @param[in]   clientData      Pointer to user-defined data.
278          * @param[in]   offset          Offset position starts from the beginning of file stream. This parameter indicates reading position.
279          * @param[in]   buffer          Memory buffer to store data which are read from file stream. This parameter should not be <b>NULL</b>.
280          * @param[in]   size            Size of data which should be read from file stream, in bytes. The buffer indicated by the parameter <i>buffer</i> should be enough to store specified data.
281          * 
282          * @return 0 for success, other value for failure.
283          */
284         FPDF_RESULT     (*ReadBlock)(FPDF_LPVOID clientData, FPDF_DWORD offset, FPDF_LPVOID buffer, FPDF_DWORD size);
285         /**
286          * @brief       Callback function to write data into the current file stream.
287          *
288          * @param[in]   clientData      Pointer to user-defined data.
289          * @param[in]   offset          Offset position starts from the beginning of file stream. This parameter indicates writing position.
290          * @param[in]   buffer          Memory buffer contains data which is written into file stream. This parameter should not be <b>NULL</b>.
291          * @param[in]   size            Size of data which should be written into file stream, in bytes.
292          *
293          * @return 0 for success, other value for failure.
294          */
295         FPDF_RESULT     (*WriteBlock)(FPDF_LPVOID clientData, FPDF_DWORD offset, FPDF_LPCVOID buffer, FPDF_DWORD size);
296         /**
297          * @brief       Callback function to flush all internal accessing buffers.
298          *
299          * @param[in]   clientData      Pointer to user-defined data.
300          *
301          * @return 0 for success, other value for failure.
302          */
303         FPDF_RESULT     (*Flush)(FPDF_LPVOID clientData);
304         /**
305          * @brief       Callback function to change file size.
306          *
307          * @details     This function is called under writing mode usually. Implementer can determine whether to realize it based on application requests.
308          *
309          * @param[in]   clientData      Pointer to user-defined data.
310          * @param[in]   size            New size of file stream, in bytes.
311          *
312          * @return 0 for success, other value for failure.
313          */
314         FPDF_RESULT     (*Truncate)(FPDF_LPVOID clientData, FPDF_DWORD size);
315
316 } FPDF_FILEHANDLER, *FPDF_LPFILEHANDLER;
317
318 // Function: FPDF_LoadCustomDocument
319 //                      Load PDF document from a custom access descriptor.
320 // Parameters:
321 //                      pFileAccess     -       A structure for access the file.
322 //                      password        -       Optional password for decrypting the PDF file.
323 // Return value:
324 //                      A handle to the loaded document. If failed, NULL is returned.
325 // Comments:
326 //                      The application should maintain the file resources being valid until the PDF document close.
327 //                      Loaded document can be closed by FPDF_CloseDocument.
328 // Notes:
329 //                      The application should call ::FPDF_LoadXFA function after PDF document loaded 
330 //                      to support XFA fields in fpdfformfill.h file.
331 //
332 DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_LoadCustomDocument(FPDF_FILEACCESS* pFileAccess, 
333                                                                                                                 FPDF_BYTESTRING password);
334
335 // Function: FPDF_GetFileVersion
336 //                      Get the file version of the specific PDF document.
337 // Parameters:
338 //                      doc                     -       Handle to document.
339 //                      fileVersion     -       The PDF file version. File version: 14 for 1.4, 15 for 1.5, ...
340 // Return value:
341 //                      TRUE if this call succeed, If failed, FALSE is returned.
342 // Comments:
343 //                      If the document is created by function ::FPDF_CreateNewDocument, then this function would always fail.
344 //
345 DLLEXPORT FPDF_BOOL STDCALL FPDF_GetFileVersion(FPDF_DOCUMENT doc, int* fileVersion);
346
347 #define FPDF_ERR_SUCCESS                0               // No error.
348 #define FPDF_ERR_UNKNOWN                1               // Unknown error.
349 #define FPDF_ERR_FILE                   2               // File not found or could not be opened.
350 #define FPDF_ERR_FORMAT                 3               // File not in PDF format or corrupted.
351 #define FPDF_ERR_PASSWORD               4               // Password required or incorrect password.
352 #define FPDF_ERR_SECURITY               5               // Unsupported security scheme.
353 #define FPDF_ERR_PAGE                   6               // Page not found or content error.
354 #define FPDF_ERR_XFALOAD                7               // Load XFA error.
355 #define FPDF_ERR_XFALAYOUT              8       // Layout XFA error.
356
357 // Function: FPDF_GetLastError
358 //                      Get last error code when an SDK function failed.
359 // Parameters: 
360 //                      None.
361 // Return value:
362 //                      A 32-bit integer indicating error codes (defined above).
363 // Comments:
364 //                      If the previous SDK call succeeded, the return value of this function
365 //                      is not defined.
366 //
367 DLLEXPORT unsigned long STDCALL FPDF_GetLastError();
368
369 // Function: FPDF_GetDocPermission
370 //                      Get file permission flags of the document.
371 // Parameters: 
372 //                      document        -       Handle to document. Returned by FPDF_LoadDocument function.
373 // Return value:
374 //                      A 32-bit integer indicating permission flags. Please refer to PDF Reference for
375 //                      detailed description. If the document is not protected, 0xffffffff will be returned.
376 //
377 DLLEXPORT unsigned long STDCALL FPDF_GetDocPermissions(FPDF_DOCUMENT document);
378
379 // Function: FPDF_GetSecurityHandlerRevision
380 //                      Get the revision for security handler.
381 // Parameters:
382 //                      document        -       Handle to document. Returned by FPDF_LoadDocument function.
383 // Return value:
384 //                      The security handler revision number. Please refer to PDF Reference for
385 //                      detailed description. If the document is not protected, -1 will be returned.
386 //
387 DLLEXPORT int STDCALL FPDF_GetSecurityHandlerRevision(FPDF_DOCUMENT document);
388
389 // Function: FPDF_GetPageCount
390 //                      Get total number of pages in a document.
391 // Parameters: 
392 //                      document        -       Handle to document. Returned by FPDF_LoadDocument function.
393 // Return value:
394 //                      Total number of pages in the document.
395 //
396 DLLEXPORT int STDCALL FPDF_GetPageCount(FPDF_DOCUMENT document);
397
398 // Function: FPDF_LoadPage
399 //                      Load a page inside a document.
400 // Parameters: 
401 //                      document        -       Handle to document. Returned by FPDF_LoadDocument function.
402 //                      page_index      -       Index number of the page. 0 for the first page.
403 // Return value:
404 //                      A handle to the loaded page. If failed, NULL is returned.
405 // Comments:
406 //                      Loaded page can be rendered to devices using FPDF_RenderPage function.
407 //                      Loaded page can be closed by FPDF_ClosePage.
408 //
409 DLLEXPORT FPDF_PAGE     STDCALL FPDF_LoadPage(FPDF_DOCUMENT document, int page_index);
410
411 // Function: FPDF_GetPageWidth
412 //                      Get page width.
413 // Parameters:
414 //                      page            -       Handle to the page. Returned by FPDF_LoadPage function.
415 // Return value:
416 //                      Page width (excluding non-displayable area) measured in points.
417 //                      One point is 1/72 inch (around 0.3528 mm).
418 //
419 DLLEXPORT double STDCALL FPDF_GetPageWidth(FPDF_PAGE page);
420
421 // Function: FPDF_GetPageHeight
422 //                      Get page height.
423 // Parameters:
424 //                      page            -       Handle to the page. Returned by FPDF_LoadPage function.
425 // Return value:
426 //                      Page height (excluding non-displayable area) measured in points.
427 //                      One point is 1/72 inch (around 0.3528 mm)
428 //
429 DLLEXPORT double STDCALL FPDF_GetPageHeight(FPDF_PAGE page);
430
431 // Function: FPDF_GetPageSizeByIndex
432 //                      Get the size of a page by index.
433 // Parameters:
434 //                      document        -       Handle to document. Returned by FPDF_LoadDocument function.
435 //                      page_index      -       Page index, zero for the first page.
436 //                      width           -       Pointer to a double value receiving the page width (in points).
437 //                      height          -       Pointer to a double value receiving the page height (in points).
438 // Return value:
439 //                      Non-zero for success. 0 for error (document or page not found).
440 //
441 DLLEXPORT int STDCALL FPDF_GetPageSizeByIndex(FPDF_DOCUMENT document, int page_index, double* width, double* height);
442
443
444 // Page rendering flags. They can be combined with bit OR.
445 #define FPDF_ANNOT                      0x01            // Set if annotations are to be rendered.
446 #define FPDF_LCD_TEXT           0x02            // Set if using text rendering optimized for LCD display.
447 #define FPDF_NO_NATIVETEXT      0x04            // Don't use the native text output available on some platforms
448 #define FPDF_GRAYSCALE          0x08            // Grayscale output.
449 #define FPDF_DEBUG_INFO         0x80            // Set if you want to get some debug info. 
450                                                                                 // Please discuss with Foxit first if you need to collect debug info.
451 #define FPDF_NO_CATCH           0x100           // Set if you don't want to catch exception.
452 #define FPDF_RENDER_LIMITEDIMAGECACHE   0x200   // Limit image cache size. 
453 #define FPDF_RENDER_FORCEHALFTONE               0x400   // Always use halftone for image stretching.
454 #define FPDF_PRINTING           0x800   // Render for printing.
455 #define FPDF_REVERSE_BYTE_ORDER         0x10            //set whether render in a reverse Byte order, this flag only 
456                                                                                                 //enable when render to a bitmap.
457 #ifdef _WIN32
458 // Function: FPDF_RenderPage
459 //                      Render contents in a page to a device (screen, bitmap, or printer).
460 //                      This function is only supported on Windows system.
461 // Parameters: 
462 //                      dc                      -       Handle to device context.
463 //                      page            -       Handle to the page. Returned by FPDF_LoadPage function.
464 //                      start_x         -       Left pixel position of the display area in the device coordinate.
465 //                      start_y         -       Top pixel position of the display area in the device coordinate.
466 //                      size_x          -       Horizontal size (in pixels) for displaying the page.
467 //                      size_y          -       Vertical size (in pixels) for displaying the page.
468 //                      rotate          -       Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
469 //                                                              2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
470 //                      flags           -       0 for normal display, or combination of flags defined above.
471 // Return value:
472 //                      None.
473 // Notes:
474 //                      The method can not support to render the page for the document consists of dynamic XFA fields. 
475 //
476 DLLEXPORT void STDCALL FPDF_RenderPage(HDC dc, FPDF_PAGE page, int start_x, int start_y, int size_x, int size_y,
477                                                 int rotate, int flags);
478 #endif
479
480 // Function: FPDF_RenderPageBitmap
481 //                      Render contents in a page to a device independent bitmap
482 // Parameters: 
483 //                      bitmap          -       Handle to the device independent bitmap (as the output buffer).
484 //                                                      Bitmap handle can be created by FPDFBitmap_Create function.
485 //                      page            -       Handle to the page. Returned by FPDF_LoadPage function.
486 //                      start_x         -       Left pixel position of the display area in the bitmap coordinate.
487 //                      start_y         -       Top pixel position of the display area in the bitmap coordinate.
488 //                      size_x          -       Horizontal size (in pixels) for displaying the page.
489 //                      size_y          -       Vertical size (in pixels) for displaying the page.
490 //                      rotate          -       Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
491 //                                                              2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
492 //                      flags           -       0 for normal display, or combination of flags defined above.
493 // Return value:
494 //                      None.
495 // Notes:
496 //                      The method can not support to render the page for the document consists of dynamic XFA fields. 
497 //
498 DLLEXPORT void STDCALL FPDF_RenderPageBitmap(FPDF_BITMAP bitmap, FPDF_PAGE page, int start_x, int start_y, 
499                                                 int size_x, int size_y, int rotate, int flags);
500
501 // Function: FPDF_ClosePage
502 //                      Close a loaded PDF page.
503 // Parameters: 
504 //                      page            -       Handle to the loaded page.
505 // Return value:
506 //                      None.
507 //
508 DLLEXPORT void STDCALL FPDF_ClosePage(FPDF_PAGE page);
509
510 // Function: FPDF_CloseDocument
511 //                      Close a loaded PDF document.
512 // Parameters: 
513 //                      document        -       Handle to the loaded document.
514 // Return value:
515 //                      None.
516 //
517 DLLEXPORT void STDCALL FPDF_CloseDocument(FPDF_DOCUMENT document);
518
519 // Function: FPDF_DeviceToPage
520 //                      Convert the screen coordinate of a point to page coordinate.
521 // Parameters:
522 //                      page            -       Handle to the page. Returned by FPDF_LoadPage function.
523 //                      start_x         -       Left pixel position of the display area in the device coordinate.
524 //                      start_y         -       Top pixel position of the display area in the device coordinate.
525 //                      size_x          -       Horizontal size (in pixels) for displaying the page.
526 //                      size_y          -       Vertical size (in pixels) for displaying the page.
527 //                      rotate          -       Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
528 //                                                              2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
529 //                      device_x        -       X value in device coordinate, for the point to be converted.
530 //                      device_y        -       Y value in device coordinate, for the point to be converted.
531 //                      page_x          -       A Pointer to a double receiving the converted X value in page coordinate.
532 //                      page_y          -       A Pointer to a double receiving the converted Y value in page coordinate.
533 // Return value:
534 //                      None.
535 // Comments:
536 //                      The page coordinate system has its origin at left-bottom corner of the page, with X axis goes along
537 //                      the bottom side to the right, and Y axis goes along the left side upward. NOTE: this coordinate system 
538 //                      can be altered when you zoom, scroll, or rotate a page, however, a point on the page should always have 
539 //                      the same coordinate values in the page coordinate system. 
540 //
541 //                      The device coordinate system is device dependent. For screen device, its origin is at left-top
542 //                      corner of the window. However this origin can be altered by Windows coordinate transformation
543 //                      utilities. You must make sure the start_x, start_y, size_x, size_y and rotate parameters have exactly
544 //                      same values as you used in FPDF_RenderPage() function call.
545 //
546 DLLEXPORT void STDCALL FPDF_DeviceToPage(FPDF_PAGE page, int start_x, int start_y, int size_x, int size_y,
547                                                 int rotate, int device_x, int device_y, double* page_x, double* page_y);
548
549 // Function: FPDF_PageToDevice
550 //                      Convert the page coordinate of a point to screen coordinate.
551 // Parameters:
552 //                      page            -       Handle to the page. Returned by FPDF_LoadPage function.
553 //                      start_x         -       Left pixel position of the display area in the device coordinate.
554 //                      start_y         -       Top pixel position of the display area in the device coordinate.
555 //                      size_x          -       Horizontal size (in pixels) for displaying the page.
556 //                      size_y          -       Vertical size (in pixels) for displaying the page.
557 //                      rotate          -       Page orientation: 0 (normal), 1 (rotated 90 degrees clockwise),
558 //                                                              2 (rotated 180 degrees), 3 (rotated 90 degrees counter-clockwise).
559 //                      page_x          -       X value in page coordinate, for the point to be converted.
560 //                      page_y          -       Y value in page coordinate, for the point to be converted.
561 //                      device_x        -       A pointer to an integer receiving the result X value in device coordinate.
562 //                      device_y        -       A pointer to an integer receiving the result Y value in device coordinate.
563 // Return value:
564 //                      None.
565 // Comments:
566 //                      See comments of FPDF_DeviceToPage() function.
567 //
568 DLLEXPORT void STDCALL FPDF_PageToDevice(FPDF_PAGE page, int start_x, int start_y, int size_x, int size_y,
569                                                 int rotate, double page_x, double page_y, int* device_x, int* device_y);
570
571 // Function: FPDFBitmap_Create
572 //                      Create a Foxit Device Independent Bitmap (FXDIB).
573 // Parameters:
574 //                      width           -       Number of pixels in a horizontal line of the bitmap. Must be greater than 0.
575 //                      height          -       Number of pixels in a vertical line of the bitmap. Must be greater than 0.
576 //                      alpha           -       A flag indicating whether alpha channel is used. Non-zero for using alpha, zero for not using.
577 // Return value:
578 //                      The created bitmap handle, or NULL if parameter error or out of memory.
579 // Comments:
580 //                      An FXDIB always use 4 byte per pixel. The first byte of a pixel is always double word aligned.
581 //                      Each pixel contains red (R), green (G), blue (B) and optionally alpha (A) values.
582 //                      The byte order is BGRx (the last byte unused if no alpha channel) or BGRA.
583 //                      
584 //                      The pixels in a horizontal line (also called scan line) are stored side by side, with left most
585 //                      pixel stored first (with lower memory address). Each scan line uses width*4 bytes.
586 //
587 //                      Scan lines are stored one after another, with top most scan line stored first. There is no gap
588 //                      between adjacent scan lines.
589 //
590 //                      This function allocates enough memory for holding all pixels in the bitmap, but it doesn't 
591 //                      initialize the buffer. Applications can use FPDFBitmap_FillRect to fill the bitmap using any color.
592 DLLEXPORT FPDF_BITMAP STDCALL FPDFBitmap_Create(int width, int height, int alpha);
593
594 // More DIB formats
595 #define FPDFBitmap_Gray         1               // Gray scale bitmap, one byte per pixel.
596 #define FPDFBitmap_BGR          2               // 3 bytes per pixel, byte order: blue, green, red.
597 #define FPDFBitmap_BGRx         3               // 4 bytes per pixel, byte order: blue, green, red, unused.
598 #define FPDFBitmap_BGRA         4               // 4 bytes per pixel, byte order: blue, green, red, alpha.
599
600 // Function: FPDFBitmap_CreateEx
601 //                      Create a Foxit Device Independent Bitmap (FXDIB)
602 // Parameters:
603 //                      width           -       Number of pixels in a horizontal line of the bitmap. Must be greater than 0.
604 //                      height          -       Number of pixels in a vertical line of the bitmap. Must be greater than 0.
605 //                      format          -       A number indicating for bitmap format, as defined above.
606 //                      first_scan      -       A pointer to the first byte of first scan line, for external buffer
607 //                                                      only. If this parameter is NULL, then the SDK will create its own buffer.
608 //                      stride          -       Number of bytes for each scan line, for external buffer only..
609 // Return value:
610 //                      The created bitmap handle, or NULL if parameter error or out of memory.
611 // Comments:
612 //                      Similar to FPDFBitmap_Create function, with more formats and external buffer supported. 
613 //                      Bitmap created by this function can be used in any place that a FPDF_BITMAP handle is 
614 //                      required. 
615 //
616 //                      If external scanline buffer is used, then the application should destroy the buffer
617 //                      by itself. FPDFBitmap_Destroy function will not destroy the buffer.
618 //
619 DLLEXPORT FPDF_BITMAP STDCALL FPDFBitmap_CreateEx(int width, int height, int format, void* first_scan, int stride);
620
621 // Function: FPDFBitmap_FillRect
622 //                      Fill a rectangle area in an FXDIB.
623 // Parameters:
624 //                      bitmap          -       The handle to the bitmap. Returned by FPDFBitmap_Create function.
625 //                      left            -       The left side position. Starting from 0 at the left-most pixel.
626 //                      top                     -       The top side position. Starting from 0 at the top-most scan line.
627 //                      width           -       Number of pixels to be filled in each scan line.
628 //                      height          -       Number of scan lines to be filled.
629 //                      color           -       A 32-bit value specifing the color, in 8888 ARGB format.
630 // Return value:
631 //                      None.
632 // Comments:
633 //                      This function set the color and (optionally) alpha value in specified region of the bitmap.
634 //                      NOTE: If alpha channel is used, this function does NOT composite the background with the source color,
635 //                      instead the background will be replaced by the source color and alpha.
636 //                      If alpha channel is not used, the "alpha" parameter is ignored.
637 //
638 DLLEXPORT void STDCALL FPDFBitmap_FillRect(FPDF_BITMAP bitmap, int left, int top, int width, int height, FPDF_DWORD color);
639
640 // Function: FPDFBitmap_GetBuffer
641 //                      Get data buffer of an FXDIB
642 // Parameters:
643 //                      bitmap          -       Handle to the bitmap. Returned by FPDFBitmap_Create function.
644 // Return value:
645 //                      The pointer to the first byte of the bitmap buffer.
646 // Comments:
647 //                      The stride may be more than width * number of bytes per pixel
648 //                      Applications can use this function to get the bitmap buffer pointer, then manipulate any color
649 //                      and/or alpha values for any pixels in the bitmap.
650 DLLEXPORT void* STDCALL FPDFBitmap_GetBuffer(FPDF_BITMAP bitmap);
651
652 // Function: FPDFBitmap_GetWidth
653 //                      Get width of an FXDIB.
654 // Parameters:
655 //                      bitmap          -       Handle to the bitmap. Returned by FPDFBitmap_Create function.
656 // Return value:
657 //                      The number of pixels in a horizontal line of the bitmap.
658 DLLEXPORT int STDCALL FPDFBitmap_GetWidth(FPDF_BITMAP bitmap);
659
660 // Function: FPDFBitmap_GetHeight
661 //                      Get height of an FXDIB.
662 // Parameters:
663 //                      bitmap          -       Handle to the bitmap. Returned by FPDFBitmap_Create function.
664 // Return value:
665 //                      The number of pixels in a vertical line of the bitmap.
666 DLLEXPORT int STDCALL FPDFBitmap_GetHeight(FPDF_BITMAP bitmap);
667
668 // Function: FPDFBitmap_GetStride
669 //                      Get number of bytes for each scan line in the bitmap buffer.
670 // Parameters:
671 //                      bitmap          -       Handle to the bitmap. Returned by FPDFBitmap_Create function.
672 // Return value:
673 //                      The number of bytes for each scan line in the bitmap buffer.
674 // Comments:
675 //                      The stride may be more than width * number of bytes per pixel
676 DLLEXPORT int STDCALL FPDFBitmap_GetStride(FPDF_BITMAP bitmap);
677
678 // Function: FPDFBitmap_Destroy
679 //                      Destroy an FXDIB and release all related buffers. 
680 // Parameters:
681 //                      bitmap          -       Handle to the bitmap. Returned by FPDFBitmap_Create function.
682 // Return value:
683 //                      None.
684 // Comments:
685 //                      This function will not destroy any external buffer.
686 //
687 DLLEXPORT void STDCALL FPDFBitmap_Destroy(FPDF_BITMAP bitmap);
688
689 // Function: FPDF_VIEWERREF_GetPrintScaling
690 //                      Whether the PDF document prefers to be scaled or not.
691 // Parameters: 
692 //                      document        -       Handle to the loaded document.
693 // Return value:
694 //                      None.
695 //
696 DLLEXPORT FPDF_BOOL STDCALL FPDF_VIEWERREF_GetPrintScaling(FPDF_DOCUMENT document);
697
698 // Function: FPDF_VIEWERREF_GetNumCopies
699 //                      Returns the number of copies to be printed.
700 // Parameters:
701 //                      document        -       Handle to the loaded document.
702 // Return value:
703 //          The number of copies to be printed.
704 //
705 DLLEXPORT int STDCALL FPDF_VIEWERREF_GetNumCopies(FPDF_DOCUMENT document);
706
707 // Function: FPDF_VIEWERREF_GetPrintPageRange
708 //                      Page numbers to initialize print dialog box when file is printed.
709 // Parameters:
710 //                      document        -       Handle to the loaded document.
711 // Return value:
712 //          The print page range to be used for printing.
713 //
714 DLLEXPORT FPDF_PAGERANGE STDCALL FPDF_VIEWERREF_GetPrintPageRange(FPDF_DOCUMENT document);
715
716 // Function: FPDF_VIEWERREF_GetDuplex
717 //                      Returns the paper handling option to be used when printing from print dialog.
718 // Parameters:
719 //                      document        -       Handle to the loaded document.
720 // Return value:
721 //          The paper handling option to be used when printing.
722 //
723 DLLEXPORT FPDF_DUPLEXTYPE STDCALL FPDF_VIEWERREF_GetDuplex(FPDF_DOCUMENT document);
724
725 // Function: FPDF_CountNamedDests
726 //                      Get the count of named destinations in the PDF document.
727 // Parameters:
728 //                      document        -       Handle to a document
729 // Return value:
730 //                      The count of named destinations.
731 DLLEXPORT FPDF_DWORD STDCALL FPDF_CountNamedDests(FPDF_DOCUMENT document);
732
733 // Function: FPDF_GetNamedDestByName
734 //                      get a special dest handle by the index.
735 // Parameters: 
736 //                      document        -       Handle to the loaded document.
737 //                      name            -       The name of a special named dest.
738 // Return value:
739 //                      The handle of the dest.
740 //
741 DLLEXPORT FPDF_DEST STDCALL FPDF_GetNamedDestByName(FPDF_DOCUMENT document, FPDF_BYTESTRING name);
742
743 // Function: FPDF_GetNamedDest
744 //                      Get the specified named destinations of the PDF document by index.
745 // Parameters:
746 //                      document        -       Handle to a document
747 //                      index           -       The index of named destination.
748 //                      buffer          -       The buffer to obtain destination name, used as wchar_t*.
749 //                      buflen [in/out] -       Size of the buffer in bytes on input, length of the result in bytes on output or -1 if the buffer is too small.
750 // Return value:
751 //                      The destination handle of a named destination, or NULL if no named destination corresponding to |index|.
752 // Comments:
753 //                      Call this function twice to get the name of the named destination:
754 //                      1) First time pass in |buffer| as NULL and get buflen.
755 //                      2) Second time pass in allocated |buffer| and buflen to retrieve |buffer|, which should be used as wchar_t*.
756 //                         If buflen is not sufficiently large, it will be set to -1 upon return.
757 //
758 DLLEXPORT FPDF_DEST STDCALL FPDF_GetNamedDest(FPDF_DOCUMENT document, int index, void* buffer, long* buflen);
759
760 // Function: FPDF_BStr_Init     
761 //                      Helper function to initialize a byte string.
762 DLLEXPORT FPDF_RESULT STDCALL FPDF_BStr_Init(FPDF_BSTR* str);
763
764 // Function: FPDF_BStr_Set      
765 //                      Helper function to set string data.
766 DLLEXPORT FPDF_RESULT STDCALL FPDF_BStr_Set(FPDF_BSTR* str, FPDF_LPCSTR bstr, int length);
767
768 // Function: FPDF_BStr_Clear    
769 //                      Helper function to clear a byte string.
770 DLLEXPORT FPDF_RESULT STDCALL FPDF_BStr_Clear(FPDF_BSTR* str);
771
772 #ifdef __cplusplus
773 };
774 #endif
775
776 #endif // _FPDFVIEW_H_