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