Merge XFA to PDFium master at 4dc95e7 on 10/28/2014
[pdfium.git] / fpdfsdk / include / fpdf_dataavail.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 #ifndef _FPDF_DATAAVAIL_H_
8 #define _FPDF_DATAAVAIL_H_
9
10 #ifndef _FPDFVIEW_H_
11 #include "fpdfview.h"
12 #endif
13
14
15 /** The result of the process which check linearized PDF. */
16 #define FSDK_IS_LINEARIZED                      1
17 #define FSDK_NOT_LINEARIZED                     0
18 #define FSDK_UNKNOW_LINEARIZED          -1
19
20
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24
25 /**
26  * Interface: FX_FILEAVAIL
27  *                      Interface for checking whether the section of the file is available. 
28  */
29 typedef struct _FX_FILEAVAIL {
30         /**
31          * Version number of the interface. Currently must be 1.
32          */
33         int version;
34
35         /**
36          * Method: IsDataAvail
37          *              Report whether the specified data section is available. A section is available only if all bytes in the section is available. 
38          * Interface Version:
39          *              1
40          * Implementation Required:
41          *              Yes
42          * Parameters:
43          *              pThis           -       Pointer to the interface structure itself.
44          *              offset          -       The offset of the data section in the file.
45          *              size            -       The size of the data section
46          * Return Value:
47          *              true means the specified data section is available.
48          * Comments:
49          *              Called by Foxit SDK to check whether the data section is ready.
50          */
51         bool (*IsDataAvail)(struct _FX_FILEAVAIL* pThis, size_t offset, size_t size);
52 } FX_FILEAVAIL;
53
54 typedef void* FPDF_AVAIL;
55
56 /**
57 * Function: FPDFAvail_Create
58 *                       Create a document availability provider.
59 *
60 * Parameters: 
61 *                       file_avail      -       Pointer to file availability interface to check availability of file data.
62 *                       file            -       Pointer to a file access interface for reading data from file.
63 * Return value:
64 *                       A handle to the document availability provider. NULL for error.
65 * Comments:
66 *                       Application must call FPDFAvail_Destroy when done with the availability provider.
67 * Notes:
68 *                       The method can not support to load a document which consists of dynamic XFA fields now.
69 */
70 DLLEXPORT FPDF_AVAIL STDCALL FPDFAvail_Create(FX_FILEAVAIL* file_avail, FPDF_FILEACCESS* file);
71
72 /**
73 * Function: FPDFAvail_Destroy
74 *                       Destroy a document availibity provider.
75 *
76 * Parameters: 
77 *                       avail           -       Handle to document availability provider returned by FPDFAvail_Create
78 * Return Value:
79 *                       None.
80 */
81 DLLEXPORT void STDCALL FPDFAvail_Destroy(FPDF_AVAIL avail);
82
83 /**
84  * Interface: FX_DOWNLOADHINTS
85  *                      Download hints interface. Used to receive hints for further downloading.
86  */
87 typedef struct _FX_DOWNLOADHINTS {
88         /**
89          * Version number of the interface. Currently must be 1.
90          */
91         int version;
92
93         /**
94          * Method: AddSegment
95          *              Add a section to be downloaded.
96          * Interface Version:
97          *              1
98          * Implementation Required:
99          *              Yes
100          * Parameters:
101          *              pThis           -       Pointer to the interface structure itself.
102          *              offset          -       The offset of the hint reported to be downloaded.
103          *              size            -       The size of the hint reported to be downloaded.
104          * Return Value:
105          *              None.
106          * Comments:
107          *              Called by Foxit SDK to report some downloading hints for download manager.
108          *              The position and size of section may be not accurate, part of the section might be already available. 
109          *              The download manager must deal with that to maximize download efficiency.
110          */
111         void (*AddSegment)(struct _FX_DOWNLOADHINTS* pThis, size_t offset, size_t size);
112 } FX_DOWNLOADHINTS;
113
114 /**
115 * Function: FPDFAvail_IsDocAvail
116 *                       Check whether the document is ready for loading, if not, get download hints.
117 *
118 * Parameters: 
119 *                       avail           -       Handle to document availability provider returned by FPDFAvail_Create
120 *                       hints           -       Pointer to a download hints interface, receiving generated hints
121 * Return value:
122 *                       Non-zero for page is fully available, 0 for page not yet available.
123 * Comments:
124 *                       The application should call this function whenever new data arrived, and process all the
125 *                       generated download hints if any, until the function returns non-zero value. Then the 
126 *                       application can call FPDFAvail_GetDocument() to get a document handle.
127 */
128 DLLEXPORT int STDCALL FPDFAvail_IsDocAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);
129
130 /**
131 * Function: FPDFAvail_GetDocument
132 *                       Get document from the availability provider.
133 *
134 * Parameters:
135 *                       avail           -       Handle to document availability provider returned by FPDFAvail_Create
136 *     password  -       Optional password for decrypting the PDF file.
137 * Return value:
138 *                       Handle to the document.
139 * Comments:
140 *                       After FPDFAvail_IsDocAvail() returns TRUE, the application should call this function to
141 *                       get the document handle. To close the document, use FPDF_CloseDocument function.
142 */
143 DLLEXPORT FPDF_DOCUMENT STDCALL FPDFAvail_GetDocument(FPDF_AVAIL avail,
144                                                       FPDF_BYTESTRING password);
145
146 /**
147 * Function: FPDFAvail_GetFirstPageNum
148 *                       Get page number for the first available page in a linearized PDF
149 *
150 * Parameters:
151 *                       doc                     -       A document handle returned by FPDFAvail_GetDocument
152 * Return Value:
153 *                       Zero-based index for the first available page.
154 * Comments:
155 *                       For most linearized PDFs, the first available page would be just the first page, however,
156 *                       some PDFs might make other page to be the first available page.
157 *                       For non-linearized PDF, this function will always return zero.
158 */
159 DLLEXPORT int STDCALL FPDFAvail_GetFirstPageNum(FPDF_DOCUMENT doc);
160
161 /**
162 * Function: FPDFAvail_IsPageAvail
163 *                       Check whether a page is ready for loading, if not, get download hints.
164 *
165 * Parameters: 
166 *                       avail           -       Handle to document availability provider returned by FPDFAvail_Create
167 *                       page_index      -       Index number of the page. 0 for the first page.
168 *                       hints           -       Pointer to a download hints interface, receiving generated hints
169 * Return value:
170 *                       Non-zero for page is fully available, 0 for page not yet available.
171 * Comments:
172 *                       This function call be called only after FPDFAvail_GetDocument if called.
173 *                       The application should call this function whenever new data arrived, and process all the
174 *                       generated download hints if any, until the function returns non-zero value. Then the 
175 *                       application can perform page loading.
176 */
177 DLLEXPORT int STDCALL FPDFAvail_IsPageAvail(FPDF_AVAIL avail, int page_index, FX_DOWNLOADHINTS* hints);
178
179 /**
180 * Function: FPDFAvail_ISFormAvail
181 *                       Check whether Form data is ready for init, if not, get download hints.
182 *
183 * Parameters: 
184 *                       avail           -       Handle to document availability provider returned by FPDFAvail_Create
185 *                       hints           -       Pointer to a download hints interface, receiving generated hints
186 * Return value:
187 *                       Non-zero for Form data is fully available, 0 for Form data not yet available.
188 *                       Details: -1 - error, the input parameter not correct, such as hints is null.
189 *                                        0  - data not available
190 *                                        1  - data available
191 *                                        2  - no form data.                             
192 * Comments:
193 *                       This function call be called only after FPDFAvail_GetDocument if called. 
194 *                       The application should call this function whenever new data arrived, and process all the
195 *                       generated download hints if any, until the function returns non-zero value. Then the 
196 *                       application can perform page loading. Recommend to call FPDFDOC_InitFormFillEnviroument
197 *                       after the function returns non-zero value.
198 */
199 DLLEXPORT int STDCALL FPDFAvail_IsFormAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);
200
201 /**
202 * Function: FPDFAvail_IsLinearized
203 *                       To check whether a document is Linearized PDF file.
204 *
205 * Parameters:
206 *                       avail           -       Handle to document availability provider returned by FPDFAvail_Create
207 * Return value:
208 *                       return TRUE means the document is linearized PDF else not.
209 *                       FSDK_IS_LINEARIZED is a linearize file.
210 *                       FSDK_NOT_LINEARIZED is not a linearize file.
211 *                       FSDK_UNKNOW_LINEARIZED don't know whether the file is a linearize file.
212 * Comments:
213 *                       It return TRUE/FALSE as soon as we have first 1K data.  If the file's size less than
214 *                       1K,we don't known whether the PDF is a linearized file.
215 *
216 */
217 DLLEXPORT FPDF_BOOL STDCALL FPDFAvail_IsLinearized(FPDF_AVAIL avail);
218
219 #ifdef __cplusplus
220 };
221 #endif
222
223 #endif
224