Keep the declaration of FPDF_HasXFAField consistent with other XFA APIs
[pdfium.git] / fpdfsdk / include / fpdf_dataavail.h
index 9d373fc..04f632a 100644 (file)
-// Copyright 2014 PDFium Authors. All rights reserved.\r
-// Use of this source code is governed by a BSD-style license that can be\r
-// found in the LICENSE file.\r
\r
-// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com\r
-\r
-#ifndef _FPDF_DATAAVAIL_H_\r
-#define _FPDF_DATAAVAIL_H_\r
-\r
-#ifndef _FPDFVIEW_H_\r
-#include "fpdfview.h"\r
-#endif\r
-\r
-\r
-/** The result of the process which check linearized PDF. */\r
-#define FSDK_IS_LINEARIZED                     1\r
-#define FSDK_NOT_LINEARIZED                    0\r
-#define FSDK_UNKNOW_LINEARIZED         -1\r
-\r
-\r
-#ifdef __cplusplus\r
-extern "C" {\r
-#endif\r
-\r
-/**\r
- * Interface: FX_FILEAVAIL\r
- *                     Interface for checking whether the section of the file is available. \r
- */\r
-typedef struct _FX_FILEAVAIL {\r
-       /**\r
-        * Version number of the interface. Currently must be 1.\r
-        */\r
-       int version;\r
-\r
-       /**\r
-        * Method: IsDataAvail\r
-        *              Report whether the specified data section is available. A section is available only if all bytes in the section is available. \r
-        * Interface Version:\r
-        *              1\r
-        * Implementation Required:\r
-        *              Yes\r
-        * Parameters:\r
-        *              pThis           -       Pointer to the interface structure itself.\r
-        *              offset          -       The offset of the data section in the file.\r
-        *              size            -       The size of the data section\r
-        * Return Value:\r
-        *              true means the specified data section is available.\r
-        * Comments:\r
-        *              Called by Foxit SDK to check whether the data section is ready.\r
-        */\r
-       bool (*IsDataAvail)(struct _FX_FILEAVAIL* pThis, size_t offset, size_t size);\r
-} FX_FILEAVAIL;\r
-\r
-typedef void* FPDF_AVAIL;\r
-\r
-/**\r
-* Function: FPDFAvail_Create\r
-*                      Create a document availability provider.\r
-*\r
-* Parameters: \r
-*                      file_avail      -       Pointer to file availability interface to check availability of file data.\r
-*                      file            -       Pointer to a file access interface for reading data from file.\r
-* Return value:\r
-*                      A handle to the document availability provider. NULL for error.\r
-* Comments:\r
-*                      Application must call FPDFAvail_Destroy when done with the availability provider.\r
-*/\r
-DLLEXPORT FPDF_AVAIL STDCALL FPDFAvail_Create(FX_FILEAVAIL* file_avail, FPDF_FILEACCESS* file);\r
-\r
-/**\r
-* Function: FPDFAvail_Destroy\r
-*                      Destroy a document availibity provider.\r
-*\r
-* Parameters: \r
-*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create\r
-* Return Value:\r
-*                      None.\r
-*/\r
-DLLEXPORT void STDCALL FPDFAvail_Destroy(FPDF_AVAIL avail);\r
-\r
-/**\r
- * Interface: FX_DOWNLOADHINTS\r
- *                     Download hints interface. Used to receive hints for further downloading.\r
- */\r
-typedef struct _FX_DOWNLOADHINTS {\r
-       /**\r
-        * Version number of the interface. Currently must be 1.\r
-        */\r
-       int version;\r
-\r
-       /**\r
-        * Method: AddSegment\r
-        *              Add a section to be downloaded.\r
-        * Interface Version:\r
-        *              1\r
-        * Implementation Required:\r
-        *              Yes\r
-        * Parameters:\r
-        *              pThis           -       Pointer to the interface structure itself.\r
-        *              offset          -       The offset of the hint reported to be downloaded.\r
-        *              size            -       The size of the hint reported to be downloaded.\r
-        * Return Value:\r
-        *              None.\r
-        * Comments:\r
-        *              Called by Foxit SDK to report some downloading hints for download manager.\r
-        *              The position and size of section may be not accurate, part of the section might be already available. \r
-        *              The download manager must deal with that to maximize download efficiency.\r
-        */\r
-       void (*AddSegment)(struct _FX_DOWNLOADHINTS* pThis, size_t offset, size_t size);\r
-} FX_DOWNLOADHINTS;\r
-\r
-/**\r
-* Function: FPDFAvail_IsDocAvail\r
-*                      Check whether the document is ready for loading, if not, get download hints.\r
-*\r
-* Parameters: \r
-*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create\r
-*                      hints           -       Pointer to a download hints interface, receiving generated hints\r
-* Return value:\r
-*                      Non-zero for page is fully available, 0 for page not yet available.\r
-* Comments:\r
-*                      The application should call this function whenever new data arrived, and process all the\r
-*                      generated download hints if any, until the function returns non-zero value. Then the \r
-*                      application can call FPDFAvail_GetDocument() to get a document handle.\r
-*/\r
-DLLEXPORT int STDCALL FPDFAvail_IsDocAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);\r
-\r
-/**\r
-* Function: FPDFAvail_GetDocument\r
-*                      Get document from the availability provider.\r
-*\r
-* Parameters:\r
-*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create\r
-*     password -       Optional password for decrypting the PDF file.\r
-* Return value:\r
-*                      Handle to the document.\r
-* Comments:\r
-*                      After FPDFAvail_IsDocAvail() returns TRUE, the application should call this function to\r
-*                      get the document handle. To close the document, use FPDF_CloseDocument function.\r
-*/\r
-DLLEXPORT FPDF_DOCUMENT STDCALL FPDFAvail_GetDocument(FPDF_AVAIL avail,\r
-                                                      FPDF_BYTESTRING password);\r
-\r
-/**\r
-* Function: FPDFAvail_GetFirstPageNum\r
-*                      Get page number for the first available page in a linearized PDF\r
-*\r
-* Parameters:\r
-*                      doc                     -       A document handle returned by FPDFAvail_GetDocument\r
-* Return Value:\r
-*                      Zero-based index for the first available page.\r
-* Comments:\r
-*                      For most linearized PDFs, the first available page would be just the first page, however,\r
-*                      some PDFs might make other page to be the first available page.\r
-*                      For non-linearized PDF, this function will always return zero.\r
-*/\r
-DLLEXPORT int STDCALL FPDFAvail_GetFirstPageNum(FPDF_DOCUMENT doc);\r
-\r
-/**\r
-* Function: FPDFAvail_IsPageAvail\r
-*                      Check whether a page is ready for loading, if not, get download hints.\r
-*\r
-* Parameters: \r
-*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create\r
-*                      page_index      -       Index number of the page. 0 for the first page.\r
-*                      hints           -       Pointer to a download hints interface, receiving generated hints\r
-* Return value:\r
-*                      Non-zero for page is fully available, 0 for page not yet available.\r
-* Comments:\r
-*                      This function call be called only after FPDFAvail_GetDocument if called.\r
-*                      The application should call this function whenever new data arrived, and process all the\r
-*                      generated download hints if any, until the function returns non-zero value. Then the \r
-*                      application can perform page loading.\r
-*/\r
-DLLEXPORT int STDCALL FPDFAvail_IsPageAvail(FPDF_AVAIL avail, int page_index, FX_DOWNLOADHINTS* hints);\r
-\r
-/**\r
-* Function: FPDFAvail_ISFormAvail\r
-*                      Check whether Form data is ready for init, if not, get download hints.\r
-*\r
-* Parameters: \r
-*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create\r
-*                      hints           -       Pointer to a download hints interface, receiving generated hints\r
-* Return value:\r
-*                      Non-zero for Form data is fully available, 0 for Form data not yet available.\r
-*                      Details: -1 - error, the input parameter not correct, such as hints is null.\r
-*                                       0  - data not available\r
-*                                       1  - data available\r
-*                                       2  - no form data.                             \r
-* Comments:\r
-*                      This function call be called only after FPDFAvail_GetDocument if called. \r
-*                      The application should call this function whenever new data arrived, and process all the\r
-*                      generated download hints if any, until the function returns non-zero value. Then the \r
-*                      application can perform page loading. Recommend to call FPDFDOC_InitFormFillEnviroument\r
-*                      after the function returns non-zero value.\r
-*/\r
-DLLEXPORT int STDCALL FPDFAvail_IsFormAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);\r
-\r
-/**\r
-* Function: FPDFAvail_IsLinearized\r
-*                      To check whether a document is Linearized PDF file.\r
-*\r
-* Parameters:\r
-*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create\r
-* Return value:\r
-*                      return TRUE means the document is linearized PDF else not.\r
-*                      FSDK_IS_LINEARIZED is a linearize file.\r
-*                      FSDK_NOT_LINEARIZED is not a linearize file.\r
-*                      FSDK_UNKNOW_LINEARIZED don't know whether the file is a linearize file.\r
-* Comments:\r
-*                      It return TRUE/FALSE as soon as we have first 1K data.  If the file's size less than\r
-*                      1K,we don't known whether the PDF is a linearized file.\r
-*\r
-*/\r
-DLLEXPORT FPDF_BOOL STDCALL FPDFAvail_IsLinearized(FPDF_AVAIL avail);\r
-\r
-#ifdef __cplusplus\r
-};\r
-#endif\r
-\r
-#endif\r
-\r
+// Copyright 2014 PDFium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com
+
+#ifndef _FPDF_DATAAVAIL_H_
+#define _FPDF_DATAAVAIL_H_
+
+#ifndef _FPDFVIEW_H_
+#include "fpdfview.h"
+#endif
+
+
+/** The result of the process which check linearized PDF. */
+#define FSDK_IS_LINEARIZED                     1
+#define FSDK_NOT_LINEARIZED                    0
+#define FSDK_UNKNOW_LINEARIZED         -1
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Interface: FX_FILEAVAIL
+ *                     Interface for checking whether the section of the file is available. 
+ */
+typedef struct _FX_FILEAVAIL {
+       /**
+        * Version number of the interface. Currently must be 1.
+        */
+       int version;
+
+       /**
+        * Method: IsDataAvail
+        *              Report whether the specified data section is available. A section is available only if all bytes in the section is available. 
+        * Interface Version:
+        *              1
+        * Implementation Required:
+        *              Yes
+        * Parameters:
+        *              pThis           -       Pointer to the interface structure itself.
+        *              offset          -       The offset of the data section in the file.
+        *              size            -       The size of the data section
+        * Return Value:
+        *              true means the specified data section is available.
+        * Comments:
+        *              Called by Foxit SDK to check whether the data section is ready.
+        */
+       bool (*IsDataAvail)(struct _FX_FILEAVAIL* pThis, size_t offset, size_t size);
+} FX_FILEAVAIL;
+
+typedef void* FPDF_AVAIL;
+
+/**
+* Function: FPDFAvail_Create
+*                      Create a document availability provider.
+*
+* Parameters: 
+*                      file_avail      -       Pointer to file availability interface to check availability of file data.
+*                      file            -       Pointer to a file access interface for reading data from file.
+* Return value:
+*                      A handle to the document availability provider. NULL for error.
+* Comments:
+*                      Application must call FPDFAvail_Destroy when done with the availability provider.
+* Notes:
+*                      The method can not support to load a document which consists of dynamic XFA fields now.
+*/
+DLLEXPORT FPDF_AVAIL STDCALL FPDFAvail_Create(FX_FILEAVAIL* file_avail, FPDF_FILEACCESS* file);
+
+/**
+* Function: FPDFAvail_Destroy
+*                      Destroy a document availibity provider.
+*
+* Parameters: 
+*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create
+* Return Value:
+*                      None.
+*/
+DLLEXPORT void STDCALL FPDFAvail_Destroy(FPDF_AVAIL avail);
+
+/**
+ * Interface: FX_DOWNLOADHINTS
+ *                     Download hints interface. Used to receive hints for further downloading.
+ */
+typedef struct _FX_DOWNLOADHINTS {
+       /**
+        * Version number of the interface. Currently must be 1.
+        */
+       int version;
+
+       /**
+        * Method: AddSegment
+        *              Add a section to be downloaded.
+        * Interface Version:
+        *              1
+        * Implementation Required:
+        *              Yes
+        * Parameters:
+        *              pThis           -       Pointer to the interface structure itself.
+        *              offset          -       The offset of the hint reported to be downloaded.
+        *              size            -       The size of the hint reported to be downloaded.
+        * Return Value:
+        *              None.
+        * Comments:
+        *              Called by Foxit SDK to report some downloading hints for download manager.
+        *              The position and size of section may be not accurate, part of the section might be already available. 
+        *              The download manager must deal with that to maximize download efficiency.
+        */
+       void (*AddSegment)(struct _FX_DOWNLOADHINTS* pThis, size_t offset, size_t size);
+} FX_DOWNLOADHINTS;
+
+/**
+* Function: FPDFAvail_IsDocAvail
+*                      Check whether the document is ready for loading, if not, get download hints.
+*
+* Parameters: 
+*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create
+*                      hints           -       Pointer to a download hints interface, receiving generated hints
+* Return value:
+*                      Non-zero for page is fully available, 0 for page not yet available.
+* Comments:
+*                      The application should call this function whenever new data arrived, and process all the
+*                      generated download hints if any, until the function returns non-zero value. Then the 
+*                      application can call FPDFAvail_GetDocument() to get a document handle.
+*/
+DLLEXPORT int STDCALL FPDFAvail_IsDocAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);
+
+/**
+* Function: FPDFAvail_GetDocument
+*                      Get document from the availability provider.
+*
+* Parameters:
+*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create
+*     password -       Optional password for decrypting the PDF file.
+* Return value:
+*                      Handle to the document.
+* Comments:
+*                      After FPDFAvail_IsDocAvail() returns TRUE, the application should call this function to
+*                      get the document handle. To close the document, use FPDF_CloseDocument function.
+*/
+DLLEXPORT FPDF_DOCUMENT STDCALL FPDFAvail_GetDocument(FPDF_AVAIL avail,
+                                                      FPDF_BYTESTRING password);
+
+/**
+* Function: FPDFAvail_GetFirstPageNum
+*                      Get page number for the first available page in a linearized PDF
+*
+* Parameters:
+*                      doc                     -       A document handle returned by FPDFAvail_GetDocument
+* Return Value:
+*                      Zero-based index for the first available page.
+* Comments:
+*                      For most linearized PDFs, the first available page would be just the first page, however,
+*                      some PDFs might make other page to be the first available page.
+*                      For non-linearized PDF, this function will always return zero.
+*/
+DLLEXPORT int STDCALL FPDFAvail_GetFirstPageNum(FPDF_DOCUMENT doc);
+
+/**
+* Function: FPDFAvail_IsPageAvail
+*                      Check whether a page is ready for loading, if not, get download hints.
+*
+* Parameters: 
+*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create
+*                      page_index      -       Index number of the page. 0 for the first page.
+*                      hints           -       Pointer to a download hints interface, receiving generated hints
+* Return value:
+*                      Non-zero for page is fully available, 0 for page not yet available.
+* Comments:
+*                      This function call be called only after FPDFAvail_GetDocument if called.
+*                      The application should call this function whenever new data arrived, and process all the
+*                      generated download hints if any, until the function returns non-zero value. Then the 
+*                      application can perform page loading.
+*/
+DLLEXPORT int STDCALL FPDFAvail_IsPageAvail(FPDF_AVAIL avail, int page_index, FX_DOWNLOADHINTS* hints);
+
+/**
+* Function: FPDFAvail_ISFormAvail
+*                      Check whether Form data is ready for init, if not, get download hints.
+*
+* Parameters: 
+*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create
+*                      hints           -       Pointer to a download hints interface, receiving generated hints
+* Return value:
+*                      Non-zero for Form data is fully available, 0 for Form data not yet available.
+*                      Details: -1 - error, the input parameter not correct, such as hints is null.
+*                                       0  - data not available
+*                                       1  - data available
+*                                       2  - no form data.                             
+* Comments:
+*                      This function call be called only after FPDFAvail_GetDocument if called. 
+*                      The application should call this function whenever new data arrived, and process all the
+*                      generated download hints if any, until the function returns non-zero value. Then the 
+*                      application can perform page loading. Recommend to call FPDFDOC_InitFormFillEnvironment
+*                      after the function returns non-zero value.
+*/
+DLLEXPORT int STDCALL FPDFAvail_IsFormAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);
+
+/**
+* Function: FPDFAvail_IsLinearized
+*                      To check whether a document is Linearized PDF file.
+*
+* Parameters:
+*                      avail           -       Handle to document availability provider returned by FPDFAvail_Create
+* Return value:
+*                      return TRUE means the document is linearized PDF else not.
+*                      FSDK_IS_LINEARIZED is a linearize file.
+*                      FSDK_NOT_LINEARIZED is not a linearize file.
+*                      FSDK_UNKNOW_LINEARIZED don't know whether the file is a linearize file.
+* Comments:
+*                      It return TRUE/FALSE as soon as we have first 1K data.  If the file's size less than
+*                      1K,we don't known whether the PDF is a linearized file.
+*
+*/
+DLLEXPORT FPDF_BOOL STDCALL FPDFAvail_IsLinearized(FPDF_AVAIL avail);
+
+#ifdef __cplusplus
+};
+#endif
+
+#endif
+