Merge to XFA: Fix IWYU in formfiller/ directory.
[pdfium.git] / fpdfsdk / include / fpdfview.h
index a563762..d998263 100644 (file)
 #include <windows.h>
 #endif
 
+//  TODO: remove the #define when XFA is officially in pdfium
+#define PDF_USE_XFA
+
 // Data types
 typedef void*  FPDF_MODULEMGR;
 
 // PDF types
 typedef void*  FPDF_DOCUMENT;          
 typedef void*  FPDF_PAGE;                      
+typedef void*  FPDF_WIDGET;    
+typedef void*  FPDF_STRINGHANDLE;
 typedef void*  FPDF_PAGEOBJECT;        // Page object(text, path, etc)
 typedef void*  FPDF_PATH;
 typedef void*  FPDF_CLIPPATH;  
@@ -34,17 +39,30 @@ typedef void*       FPDF_BOOKMARK;
 typedef void*  FPDF_DEST;
 typedef void*  FPDF_ACTION;
 typedef void*  FPDF_LINK;
+typedef void*   FPDF_PAGERANGE;
 
 // Basic data types
+typedef void*                  FPDF_LPVOID;
+typedef void const*            FPDF_LPCVOID;
+typedef int                            FPDF_RESULT;
 typedef int                            FPDF_BOOL;
 typedef int                            FPDF_ERROR;     
 typedef unsigned long  FPDF_DWORD;
 
 typedef        float                   FS_FLOAT;
 
+// Duplex types
+typedef enum _FPDF_DUPLEXTYPE_ {
+    DuplexUndefined = 0,
+    Simplex,
+    DuplexFlipShortEdge,
+    DuplexFlipLongEdge
+} FPDF_DUPLEXTYPE;
+
 // String types
 typedef unsigned short                 FPDF_WCHAR;
 typedef unsigned char const*   FPDF_LPCBYTE;
+typedef char const*                            FPDF_LPCSTR;
 
 // FPDFSDK may use three types of strings: byte string, wide string (UTF-16LE encoded), and platform dependent string
 typedef const char*                            FPDF_BYTESTRING;
@@ -52,6 +70,26 @@ typedef const char*                          FPDF_BYTESTRING;
 typedef const unsigned short*  FPDF_WIDESTRING;                // Foxit PDF SDK always use UTF-16LE encoding wide string,
                                                                                                                // each character use 2 bytes (except surrogation), with low byte first.
 
+#ifndef _FPDF_DEF_STR_
+#define _FPDF_DEF_STR_
+/** @brief Structure for byte string.
+  *
+  * @note In SDK, a byte string commonly means a UTF-16LE format string.
+  */
+typedef struct _FPDF_BSTR
+{
+       /** 
+        * @brief String buffer.
+        */
+       char*   str;
+       /**
+        * @brief       Length of a string, in bytes.
+        */
+       int     len;
+} FPDF_BSTR;
+
+#endif
+
 // For Windows programmers: for most case it's OK to treat FPDF_WIDESTRING as Windows unicode string,
 //              however, special care needs to be taken if you expect to process Unicode larger than 0xffff.
 // For Linux/Unix programmers: most compiler/library environment uses 4 bytes for a Unicode character,
@@ -117,13 +155,13 @@ extern "C" {
 // Function: FPDF_InitLibrary
 //                     Initialize the FPDFSDK library 
 // Parameters:
-//                     hInstance       -       For WIN32 system only: the instance of the executable or DLL module.
+//                     None
 // Return value:
 //                     None.
 // Comments:
 //                     You have to call this function before you can call any PDF processing functions.
 
-DLLEXPORT void STDCALL FPDF_InitLibrary(void* hInstance);
+DLLEXPORT void STDCALL FPDF_InitLibrary();
 
 
 // Function: FPDF_DestroyLibary
@@ -157,6 +195,9 @@ DLLEXPORT void      STDCALL FPDF_SetSandBoxPolicy(FPDF_DWORD policy, FPDF_BOOL enable
 * @note                Loaded document can be closed by FPDF_CloseDocument.
 *                      If this function fails, you can use FPDF_GetLastError() to retrieve
 *                      the reason why it fails.
+*                      The application should call ::FPDF_LoadXFA function after PDF document loaded 
+*                      to support XFA fields in fpdfformfill.h file.
+*
 * @retval      A handle to the loaded document. If failed, NULL is returned.
 */
 DLLEXPORT FPDF_DOCUMENT        STDCALL FPDF_LoadDocument(FPDF_STRING file_path, 
@@ -176,6 +217,9 @@ DLLEXPORT FPDF_DOCUMENT     STDCALL FPDF_LoadDocument(FPDF_STRING file_path,
 //                     Loaded document can be closed by FPDF_CloseDocument.
 //                     If this function fails, you can use FPDF_GetLastError() to retrieve
 //                     the reason why it fails.
+// Notes:
+//                     The application should call ::FPDF_LoadXFA function after PDF document loaded 
+//                     to support XFA fields in fpdfformfill.h file.
 //
 DLLEXPORT FPDF_DOCUMENT        STDCALL FPDF_LoadMemDocument(const void* data_buf, 
                                                                                        int size, FPDF_BYTESTRING password);
@@ -197,6 +241,78 @@ typedef struct {
        void*                   m_Param;
 } FPDF_FILEACCESS;
 
+/**
+ * @brief Structure for file reading or writing (I/O).
+ *
+ * @note This is a handler and should be implemented by callers.
+ */
+typedef struct _FPDF_FILEHANDLER
+{
+       /**
+        * @brief User-defined data.
+        * @note Callers can use this field to track controls.
+        */
+       FPDF_LPVOID     clientData;
+       /**
+        * @brief Callback function to release the current file stream object.
+        *
+        * @param[in] clientData        Pointer to user-defined data.
+        *
+        * @return None.
+        */
+       void            (*Release)(FPDF_LPVOID clientData);
+       /**
+        * @brief Callback function to retrieve the current file stream size.
+        *
+        * @param[in] clientData        Pointer to user-defined data.
+        *
+        * @return Size of file stream.
+        */
+       FPDF_DWORD      (*GetSize)(FPDF_LPVOID clientData);
+       /**
+        * @brief Callback function to read data from the current file stream.
+        *
+        * @param[in]   clientData      Pointer to user-defined data.
+        * @param[in]   offset          Offset position starts from the beginning of file stream. This parameter indicates reading position.
+        * @param[in]   buffer          Memory buffer to store data which are read from file stream. This parameter should not be <b>NULL</b>.
+        * @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.
+        * 
+        * @return 0 for success, other value for failure.
+        */
+       FPDF_RESULT     (*ReadBlock)(FPDF_LPVOID clientData, FPDF_DWORD offset, FPDF_LPVOID buffer, FPDF_DWORD size);
+       /**
+        * @brief       Callback function to write data into the current file stream.
+        *
+        * @param[in]   clientData      Pointer to user-defined data.
+        * @param[in]   offset          Offset position starts from the beginning of file stream. This parameter indicates writing position.
+        * @param[in]   buffer          Memory buffer contains data which is written into file stream. This parameter should not be <b>NULL</b>.
+        * @param[in]   size            Size of data which should be written into file stream, in bytes.
+        *
+        * @return 0 for success, other value for failure.
+        */
+       FPDF_RESULT     (*WriteBlock)(FPDF_LPVOID clientData, FPDF_DWORD offset, FPDF_LPCVOID buffer, FPDF_DWORD size);
+       /**
+        * @brief       Callback function to flush all internal accessing buffers.
+        *
+        * @param[in]   clientData      Pointer to user-defined data.
+        *
+        * @return 0 for success, other value for failure.
+        */
+       FPDF_RESULT     (*Flush)(FPDF_LPVOID clientData);
+       /**
+        * @brief       Callback function to change file size.
+        *
+        * @details     This function is called under writing mode usually. Implementer can determine whether to realize it based on application requests.
+        *
+        * @param[in]   clientData      Pointer to user-defined data.
+        * @param[in]   size            New size of file stream, in bytes.
+        *
+        * @return 0 for success, other value for failure.
+        */
+       FPDF_RESULT     (*Truncate)(FPDF_LPVOID clientData, FPDF_DWORD size);
+
+} FPDF_FILEHANDLER, *FPDF_LPFILEHANDLER;
+
 // Function: FPDF_LoadCustomDocument
 //                     Load PDF document from a custom access descriptor.
 // Parameters:
@@ -207,6 +323,10 @@ typedef struct {
 // Comments:
 //                     The application should maintain the file resources being valid until the PDF document close.
 //                     Loaded document can be closed by FPDF_CloseDocument.
+// Notes:
+//                     The application should call ::FPDF_LoadXFA function after PDF document loaded 
+//                     to support XFA fields in fpdfformfill.h file.
+//
 DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_LoadCustomDocument(FPDF_FILEACCESS* pFileAccess, 
                                                                                                                FPDF_BYTESTRING password);
 
@@ -219,6 +339,7 @@ DLLEXPORT FPDF_DOCUMENT STDCALL FPDF_LoadCustomDocument(FPDF_FILEACCESS* pFileAc
 //                     TRUE if this call succeed, If failed, FALSE is returned.
 // Comments:
 //                     If the document is created by function ::FPDF_CreateNewDocument, then this function would always fail.
+//
 DLLEXPORT FPDF_BOOL STDCALL FPDF_GetFileVersion(FPDF_DOCUMENT doc, int* fileVersion);
 
 #define FPDF_ERR_SUCCESS               0               // No error.
@@ -228,6 +349,8 @@ DLLEXPORT FPDF_BOOL STDCALL FPDF_GetFileVersion(FPDF_DOCUMENT doc, int* fileVers
 #define FPDF_ERR_PASSWORD              4               // Password required or incorrect password.
 #define FPDF_ERR_SECURITY              5               // Unsupported security scheme.
 #define FPDF_ERR_PAGE                  6               // Page not found or content error.
+#define FPDF_ERR_XFALOAD               7               // Load XFA error.
+#define FPDF_ERR_XFALAYOUT             8       // Layout XFA error.
 
 // Function: FPDF_GetLastError
 //                     Get last error code when an SDK function failed.
@@ -251,6 +374,16 @@ DLLEXPORT unsigned long    STDCALL FPDF_GetLastError();
 //
 DLLEXPORT unsigned long        STDCALL FPDF_GetDocPermissions(FPDF_DOCUMENT document);
 
+// Function: FPDF_GetSecurityHandlerRevision
+//                     Get the revision for security handler.
+// Parameters:
+//                     document        -       Handle to document. Returned by FPDF_LoadDocument function.
+// Return value:
+//                     The security handler revision number. Please refer to PDF Reference for
+//                     detailed description. If the document is not protected, -1 will be returned.
+//
+DLLEXPORT int STDCALL FPDF_GetSecurityHandlerRevision(FPDF_DOCUMENT document);
+
 // Function: FPDF_GetPageCount
 //                     Get total number of pages in a document.
 // Parameters: 
@@ -335,6 +468,8 @@ DLLEXPORT int STDCALL FPDF_GetPageSizeByIndex(FPDF_DOCUMENT document, int page_i
 //                     flags           -       0 for normal display, or combination of flags defined above.
 // Return value:
 //                     None.
+// Notes:
+//                     The method can not support to render the page for the document consists of dynamic XFA fields. 
 //
 DLLEXPORT void STDCALL FPDF_RenderPage(HDC dc, FPDF_PAGE page, int start_x, int start_y, int size_x, int size_y,
                                                int rotate, int flags);
@@ -355,6 +490,8 @@ DLLEXPORT void STDCALL FPDF_RenderPage(HDC dc, FPDF_PAGE page, int start_x, int
 //                     flags           -       0 for normal display, or combination of flags defined above.
 // Return value:
 //                     None.
+// Notes:
+//                     The method can not support to render the page for the document consists of dynamic XFA fields. 
 //
 DLLEXPORT void STDCALL FPDF_RenderPageBitmap(FPDF_BITMAP bitmap, FPDF_PAGE page, int start_x, int start_y, 
                                                int size_x, int size_y, int rotate, int flags);
@@ -487,11 +624,7 @@ DLLEXPORT FPDF_BITMAP STDCALL FPDFBitmap_CreateEx(int width, int height, int for
 //                     top                     -       The top side position. Starting from 0 at the top-most scan line.
 //                     width           -       Number of pixels to be filled in each scan line.
 //                     height          -       Number of scan lines to be filled.
-//                     red                     -       A number from 0 to 255, identifying the red intensity.
-//                     green           -       A number from 0 to 255, identifying the green intensity.
-//                     blue            -       A number from 0 to 255, identifying the blue intensity.
-//                     alpha           -       (Only if the alpha channeled is used when bitmap created) A number from 0 to 255,
-//                                                     identifying the alpha value.
+//                     color           -       A 32-bit value specifing the color, in 8888 ARGB format.
 // Return value:
 //                     None.
 // Comments:
@@ -500,8 +633,7 @@ DLLEXPORT FPDF_BITMAP STDCALL FPDFBitmap_CreateEx(int width, int height, int for
 //                     instead the background will be replaced by the source color and alpha.
 //                     If alpha channel is not used, the "alpha" parameter is ignored.
 //
-DLLEXPORT void STDCALL FPDFBitmap_FillRect(FPDF_BITMAP bitmap, int left, int top, int width, int height, 
-                                                                       int red, int green, int blue, int alpha);
+DLLEXPORT void STDCALL FPDFBitmap_FillRect(FPDF_BITMAP bitmap, int left, int top, int width, int height, FPDF_DWORD color);
 
 // Function: FPDFBitmap_GetBuffer
 //                     Get data buffer of an FXDIB
@@ -561,6 +693,41 @@ DLLEXPORT void STDCALL FPDFBitmap_Destroy(FPDF_BITMAP bitmap);
 //
 DLLEXPORT FPDF_BOOL STDCALL FPDF_VIEWERREF_GetPrintScaling(FPDF_DOCUMENT document);
 
+// Function: FPDF_VIEWERREF_GetNumCopies
+//                     Returns the number of copies to be printed.
+// Parameters:
+//                     document        -       Handle to the loaded document.
+// Return value:
+//          The number of copies to be printed.
+//
+DLLEXPORT int STDCALL FPDF_VIEWERREF_GetNumCopies(FPDF_DOCUMENT document);
+
+// Function: FPDF_VIEWERREF_GetPrintPageRange
+//                     Page numbers to initialize print dialog box when file is printed.
+// Parameters:
+//                     document        -       Handle to the loaded document.
+// Return value:
+//          The print page range to be used for printing.
+//
+DLLEXPORT FPDF_PAGERANGE STDCALL FPDF_VIEWERREF_GetPrintPageRange(FPDF_DOCUMENT document);
+
+// Function: FPDF_VIEWERREF_GetDuplex
+//                     Returns the paper handling option to be used when printing from print dialog.
+// Parameters:
+//                     document        -       Handle to the loaded document.
+// Return value:
+//          The paper handling option to be used when printing.
+//
+DLLEXPORT FPDF_DUPLEXTYPE STDCALL FPDF_VIEWERREF_GetDuplex(FPDF_DOCUMENT document);
+
+// Function: FPDF_CountNamedDests
+//                     Get the count of named destinations in the PDF document.
+// Parameters:
+//                     document        -       Handle to a document
+// Return value:
+//                     The count of named destinations.
+DLLEXPORT FPDF_DWORD STDCALL FPDF_CountNamedDests(FPDF_DOCUMENT document);
+
 // Function: FPDF_GetNamedDestByName
 //                     get a special dest handle by the index.
 // Parameters: 
@@ -571,6 +738,35 @@ DLLEXPORT FPDF_BOOL STDCALL FPDF_VIEWERREF_GetPrintScaling(FPDF_DOCUMENT documen
 //
 DLLEXPORT FPDF_DEST STDCALL FPDF_GetNamedDestByName(FPDF_DOCUMENT document,FPDF_BYTESTRING name);
 
+// Function: FPDF_GetNamedDest
+//                     Get the specified named destinations of the PDF document by index.
+// Parameters:
+//                     document        -       Handle to a document
+//                     index           -       The index of named destination.
+//                     buffer          -       The buffer to obtain destination name, used as wchar_t*.
+//                     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.
+// Return value:
+//                     The destination handle of a named destination, or NULL if no named destination corresponding to |index|.
+// Comments:
+//                     Call this function twice to get the name of the named destination:
+//                     1) First time pass in |buffer| as NULL and get buflen.
+//                     2) Second time pass in allocated |buffer| and buflen to retrieve |buffer|, which should be used as wchar_t*.
+//                        If buflen is not sufficiently large, it will be set to -1 upon return.
+//
+DLLEXPORT FPDF_DEST STDCALL FPDF_GetNamedDest(FPDF_DOCUMENT document, int index, void* buffer, long& buflen);
+
+// Function: FPDF_BStr_Init    
+//                     Helper function to initialize a byte string.
+DLLEXPORT FPDF_RESULT STDCALL FPDF_BStr_Init(FPDF_BSTR* str);
+
+// Function: FPDF_BStr_Set     
+//                     Helper function to set string data.
+DLLEXPORT FPDF_RESULT STDCALL FPDF_BStr_Set(FPDF_BSTR* str, FPDF_LPCSTR bstr, int length);
+
+// Function: FPDF_BStr_Clear   
+//                     Helper function to clear a byte string.
+DLLEXPORT FPDF_RESULT STDCALL FPDF_BStr_Clear(FPDF_BSTR* str);
+
 #ifdef __cplusplus
 };
 #endif