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