1 // Copyright 2014 The PDFium Authors 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 54 // Create a document availability provider. 55 // 56 // file_avail - pointer to file availability interface. 57 // file - pointer to a file access interface. 58 // 59 // Returns a handle to the document availability provider, or NULL on error. 60 // 61 // FPDFAvail_Destroy() must be called when done with the availability provider. 62 FPDF_EXPORT FPDF_AVAIL FPDF_CALLCONV FPDFAvail_Create(FX_FILEAVAIL* file_avail, 63 FPDF_FILEACCESS* file); 64 65 // Destroy the |avail| document availability provider. 66 // 67 // avail - handle to document availability provider to be destroyed. 68 FPDF_EXPORT void FPDF_CALLCONV FPDFAvail_Destroy(FPDF_AVAIL avail); 69 70 // Download hints interface. Used to receive hints for further downloading. 71 typedef struct _FX_DOWNLOADHINTS { 72 // Version number of the interface. Must be 1. 73 int version; 74 75 // Add a section to be downloaded. 76 // 77 // Interface Version: 1 78 // Implementation Required: Yes 79 // 80 // pThis - pointer to the interface structure. 81 // offset - the offset of the hint reported to be downloaded. 82 // size - the size of the hint reported to be downloaded. 83 // 84 // The |offset| and |size| of the section may not be unique. Part of the 85 // section might be already available. The download manager must deal with 86 // overlapping sections. 87 void (*AddSegment)(struct _FX_DOWNLOADHINTS* pThis, 88 size_t offset, 89 size_t size); 90 } FX_DOWNLOADHINTS; 91 92 // Checks if the document is ready for loading, if not, gets download hints. 93 // 94 // avail - handle to document availability provider. 95 // hints - pointer to a download hints interface. 96 // 97 // Returns one of: 98 // PDF_DATA_ERROR: A common error is returned. Data availability unknown. 99 // PDF_DATA_NOTAVAIL: Data not yet available. 100 // PDF_DATA_AVAIL: Data available. 101 // 102 // Applications should call this function whenever new data arrives, and process 103 // all the generated download hints, if any, until the function returns 104 // |PDF_DATA_ERROR| or |PDF_DATA_AVAIL|. 105 // if hints is nullptr, the function just check current document availability. 106 // 107 // Once all data is available, call FPDFAvail_GetDocument() to get a document 108 // handle. 109 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_IsDocAvail(FPDF_AVAIL avail, 110 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 // See the comments for FPDF_LoadDocument() regarding the encoding for 122 // |password|. 123 FPDF_EXPORT FPDF_DOCUMENT FPDF_CALLCONV 124 FPDFAvail_GetDocument(FPDF_AVAIL avail, FPDF_BYTESTRING password); 125 126 // Get the page number for the first available page in a linearized PDF. 127 // 128 // doc - document handle. 129 // 130 // Returns the zero-based index for the first available page. 131 // 132 // For most linearized PDFs, the first available page will be the first page, 133 // however, some PDFs might make another page the first available page. 134 // For non-linearized PDFs, this function will always return zero. 135 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_GetFirstPageNum(FPDF_DOCUMENT doc); 136 137 // Check if |page_index| is ready for loading, if not, get the 138 // |FX_DOWNLOADHINTS|. 139 // 140 // avail - handle to document availability provider. 141 // page_index - index number of the page. Zero for the first page. 142 // hints - pointer to a download hints interface. Populated if 143 // |page_index| is not available. 144 // 145 // Returns one of: 146 // PDF_DATA_ERROR: A common error is returned. Data availability unknown. 147 // PDF_DATA_NOTAVAIL: Data not yet available. 148 // PDF_DATA_AVAIL: Data available. 149 // 150 // This function can be called only after FPDFAvail_GetDocument() is called. 151 // Applications should call this function whenever new data arrives and process 152 // all the generated download |hints|, if any, until this function returns 153 // |PDF_DATA_ERROR| or |PDF_DATA_AVAIL|. Applications can then perform page 154 // loading. 155 // if hints is nullptr, the function just check current availability of 156 // specified page. 157 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_IsPageAvail(FPDF_AVAIL avail, 158 int page_index, 159 FX_DOWNLOADHINTS* hints); 160 161 // Check if form data is ready for initialization, if not, get the 162 // |FX_DOWNLOADHINTS|. 163 // 164 // avail - handle to document availability provider. 165 // hints - pointer to a download hints interface. Populated if form is not 166 // ready for initialization. 167 // 168 // Returns one of: 169 // PDF_FORM_ERROR: A common eror, in general incorrect parameters. 170 // PDF_FORM_NOTAVAIL: Data not available. 171 // PDF_FORM_AVAIL: Data available. 172 // PDF_FORM_NOTEXIST: No form data. 173 // 174 // This function can be called only after FPDFAvail_GetDocument() is called. 175 // The application should call this function whenever new data arrives and 176 // process all the generated download |hints|, if any, until the function 177 // |PDF_FORM_ERROR|, |PDF_FORM_AVAIL| or |PDF_FORM_NOTEXIST|. 178 // if hints is nullptr, the function just check current form availability. 179 // 180 // Applications can then perform page loading. It is recommend to call 181 // FPDFDOC_InitFormFillEnvironment() when |PDF_FORM_AVAIL| is returned. 182 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_IsFormAvail(FPDF_AVAIL avail, 183 FX_DOWNLOADHINTS* hints); 184 185 // Check whether a document is a linearized PDF. 186 // 187 // avail - handle to document availability provider. 188 // 189 // Returns one of: 190 // PDF_LINEARIZED 191 // PDF_NOT_LINEARIZED 192 // PDF_LINEARIZATION_UNKNOWN 193 // 194 // FPDFAvail_IsLinearized() will return |PDF_LINEARIZED| or |PDF_NOT_LINEARIZED| 195 // when we have 1k of data. If the files size less than 1k, it returns 196 // |PDF_LINEARIZATION_UNKNOWN| as there is insufficient information to determine 197 // if the PDF is linearlized. 198 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_IsLinearized(FPDF_AVAIL avail); 199 200 #ifdef __cplusplus 201 } // extern "C" 202 #endif // __cplusplus 203 204 #endif // PUBLIC_FPDF_DATAAVAIL_H_ 205