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