• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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>
11 
12 // NOLINTNEXTLINE(build/include)
13 #include "fpdfview.h"
14 
15 #define PDF_LINEARIZATION_UNKNOWN -1
16 #define PDF_NOT_LINEARIZED 0
17 #define PDF_LINEARIZED 1
18 
19 #define PDF_DATA_ERROR -1
20 #define PDF_DATA_NOTAVAIL 0
21 #define PDF_DATA_AVAIL 1
22 
23 #define PDF_FORM_ERROR -1
24 #define PDF_FORM_NOTAVAIL 0
25 #define PDF_FORM_AVAIL 1
26 #define PDF_FORM_NOTEXIST 2
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif  // __cplusplus
31 
32 // Interface for checking whether sections of the file are available.
33 typedef struct _FX_FILEAVAIL {
34   // Version number of the interface. Must be 1.
35   int version;
36 
37   // Reports if the specified data section is currently available. A section is
38   // available if all bytes in the section are available.
39   //
40   // Interface Version: 1
41   // Implementation Required: Yes
42   //
43   //   pThis  - pointer to the interface structure.
44   //   offset - the offset of the data section in the file.
45   //   size   - the size of the data section.
46   //
47   // Returns true if the specified data section at |offset| of |size|
48   // is available.
49   FPDF_BOOL (*IsDataAvail)(struct _FX_FILEAVAIL* pThis,
50                            size_t offset,
51                            size_t size);
52 } FX_FILEAVAIL;
53 typedef void* FPDF_AVAIL;
54 
55 // Create a document availability provider.
56 //
57 //   file_avail - pointer to file availability interface.
58 //   file       - pointer to a file access interface.
59 //
60 // Returns a handle to the document availability provider, or NULL on error.
61 //
62 // |FPDFAvail_Destroy| must be called when done with the availability provider.
63 DLLEXPORT FPDF_AVAIL STDCALL FPDFAvail_Create(FX_FILEAVAIL* file_avail,
64                                               FPDF_FILEACCESS* file);
65 
66 // Destroy the |avail| document availability provider.
67 //
68 //   avail - handle to document availability provider to be destroyed.
69 DLLEXPORT void STDCALL FPDFAvail_Destroy(FPDF_AVAIL avail);
70 
71 // Download hints interface. Used to receive hints for further downloading.
72 typedef struct _FX_DOWNLOADHINTS {
73   // Version number of the interface. Must be 1.
74   int version;
75 
76   // Add a section to be downloaded.
77   //
78   // Interface Version: 1
79   // Implementation Required: Yes
80   //
81   //   pThis  - pointer to the interface structure.
82   //   offset - the offset of the hint reported to be downloaded.
83   //   size   - the size of the hint reported to be downloaded.
84   //
85   // The |offset| and |size| of the section may not be unique. Part of the
86   // section might be already available. The download manager must deal with
87   // overlapping sections.
88   void (*AddSegment)(struct _FX_DOWNLOADHINTS* pThis,
89                      size_t offset,
90                      size_t size);
91 } FX_DOWNLOADHINTS;
92 
93 // Checks if the document is ready for loading, if not, gets download hints.
94 //
95 //   avail - handle to document availability provider.
96 //   hints - pointer to a download hints interface.
97 //
98 // Returns one of:
99 //   PDF_DATA_ERROR: A common error is returned. Data availability unknown.
100 //   PDF_DATA_NOTAVAIL: Data not yet available.
101 //   PDF_DATA_AVAIL: Data available.
102 //
103 // Applications should call this function whenever new data arrives, and process
104 // all the generated download hints, if any, until the function returns
105 // |PDF_DATA_ERROR| or |PDF_DATA_AVAIL|.
106 //
107 // Once all data is available, call |FPDFAvail_GetDocument| to get a document
108 // handle.
109 DLLEXPORT int STDCALL
110 FPDFAvail_IsDocAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);
111 
112 // Get document from the availability provider.
113 //
114 //   avail    - handle to document availability provider.
115 //   password - password for decrypting the PDF file. Optional.
116 //
117 // Returns a handle to the document.
118 //
119 // When |FPDFAvail_IsDocAvail| returns TRUE, call |FPDFAvail_GetDocument| to
120 // retrieve the document handle.
121 DLLEXPORT FPDF_DOCUMENT STDCALL FPDFAvail_GetDocument(FPDF_AVAIL avail,
122                                                       FPDF_BYTESTRING password);
123 
124 // Get the page number for the first available page in a linearized PDF.
125 //
126 //   doc - document handle.
127 //
128 // Returns the zero-based index for the first available page.
129 //
130 // For most linearized PDFs, the first available page will be the first page,
131 // however, some PDFs might make another page the first available page.
132 // For non-linearized PDFs, this function will always return zero.
133 DLLEXPORT int STDCALL FPDFAvail_GetFirstPageNum(FPDF_DOCUMENT doc);
134 
135 // Check if |page_index| is ready for loading, if not, get the
136 // |FX_DOWNLOADHINTS|.
137 //
138 //   avail      - handle to document availability provider.
139 //   page_index - index number of the page. Zero for the first page.
140 //   hints      - pointer to a download hints interface. Populated if
141 //                |page_index| is not available.
142 //
143 // Returns one of:
144 //   PDF_DATA_ERROR: A common error is returned. Data availability unknown.
145 //   PDF_DATA_NOTAVAIL: Data not yet available.
146 //   PDF_DATA_AVAIL: Data available.
147 //
148 // This function can be called only after |FPDFAvail_GetDocument| is called.
149 // Applications should call this function whenever new data arrives and process
150 // all the generated download |hints|, if any, until this function returns
151 // |PDF_DATA_ERROR| or |PDF_DATA_AVAIL|. Applications can then perform page
152 // loading.
153 DLLEXPORT int STDCALL FPDFAvail_IsPageAvail(FPDF_AVAIL avail,
154                                             int page_index,
155                                             FX_DOWNLOADHINTS* hints);
156 
157 // Check if form data is ready for initialization, if not, get the
158 // |FX_DOWNLOADHINTS|.
159 //
160 //   avail - handle to document availability provider.
161 //   hints - pointer to a download hints interface. Populated if form is not
162 //           ready for initialization.
163 //
164 // Returns one of:
165 //   PDF_FORM_ERROR: A common eror, in general incorrect parameters.
166 //   PDF_FORM_NOTAVAIL: Data not available.
167 //   PDF_FORM_AVAIL: Data available.
168 //   PDF_FORM_NOTEXIST: No form data.
169 //
170 // This function can be called only after |FPDFAvail_GetDocument| is called.
171 // The application should call this function whenever new data arrives and
172 // process all the generated download |hints|, if any, until the function
173 // |PDF_FORM_ERROR|, |PDF_FORM_AVAIL| or |PDF_FORM_NOTEXIST|.
174 // Applications can then perform page loading. It is recommend to call
175 // |FPDFDOC_InitFormFillEnvironment| when |PDF_FORM_AVAIL| is returned.
176 DLLEXPORT int STDCALL FPDFAvail_IsFormAvail(FPDF_AVAIL avail,
177                                             FX_DOWNLOADHINTS* hints);
178 
179 // Check whether a document is a linearized PDF.
180 //
181 //   avail - handle to document availability provider.
182 //
183 // Returns one of:
184 //   PDF_LINEARIZED
185 //   PDF_NOT_LINEARIZED
186 //   PDF_LINEARIZATION_UNKNOWN
187 //
188 // |FPDFAvail_IsLinearized| will return |PDF_LINEARIZED| or |PDF_NOT_LINEARIZED|
189 // when we have 1k  of data. If the files size less than 1k, it returns
190 // |PDF_LINEARIZATION_UNKNOWN| as there is insufficient information to determine
191 // if the PDF is linearlized.
192 DLLEXPORT int STDCALL FPDFAvail_IsLinearized(FPDF_AVAIL avail);
193 
194 #ifdef __cplusplus
195 }  // extern "C"
196 #endif  // __cplusplus
197 
198 #endif  // PUBLIC_FPDF_DATAAVAIL_H_
199