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