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