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 FPDF_EXPORT FPDF_AVAIL FPDF_CALLCONV 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 FPDF_EXPORT void FPDF_CALLCONV 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 // if hints is nullptr, the function just check current document availability. 107 // 108 // Once all data is available, call FPDFAvail_GetDocument() to get a document 109 // handle. 110 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_IsDocAvail(FPDF_AVAIL avail, 111 FX_DOWNLOADHINTS* hints); 112 113 // Get document from the availability provider. 114 // 115 // avail - handle to document availability provider. 116 // password - password for decrypting the PDF file. Optional. 117 // 118 // Returns a handle to the document. 119 // 120 // When FPDFAvail_IsDocAvail() returns TRUE, call FPDFAvail_GetDocument() to 121 // retrieve the document handle. 122 // See the comments for FPDF_LoadDocument() regarding the encoding for 123 // |password|. 124 FPDF_EXPORT FPDF_DOCUMENT FPDF_CALLCONV 125 FPDFAvail_GetDocument(FPDF_AVAIL avail, FPDF_BYTESTRING password); 126 127 // Get the page number for the first available page in a linearized PDF. 128 // 129 // doc - document handle. 130 // 131 // Returns the zero-based index for the first available page. 132 // 133 // For most linearized PDFs, the first available page will be the first page, 134 // however, some PDFs might make another page the first available page. 135 // For non-linearized PDFs, this function will always return zero. 136 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_GetFirstPageNum(FPDF_DOCUMENT doc); 137 138 // Check if |page_index| is ready for loading, if not, get the 139 // |FX_DOWNLOADHINTS|. 140 // 141 // avail - handle to document availability provider. 142 // page_index - index number of the page. Zero for the first page. 143 // hints - pointer to a download hints interface. Populated if 144 // |page_index| is not available. 145 // 146 // Returns one of: 147 // PDF_DATA_ERROR: A common error is returned. Data availability unknown. 148 // PDF_DATA_NOTAVAIL: Data not yet available. 149 // PDF_DATA_AVAIL: Data available. 150 // 151 // This function can be called only after FPDFAvail_GetDocument() is called. 152 // Applications should call this function whenever new data arrives and process 153 // all the generated download |hints|, if any, until this function returns 154 // |PDF_DATA_ERROR| or |PDF_DATA_AVAIL|. Applications can then perform page 155 // loading. 156 // if hints is nullptr, the function just check current availability of 157 // specified page. 158 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_IsPageAvail(FPDF_AVAIL avail, 159 int page_index, 160 FX_DOWNLOADHINTS* hints); 161 162 // Check if form data is ready for initialization, if not, get the 163 // |FX_DOWNLOADHINTS|. 164 // 165 // avail - handle to document availability provider. 166 // hints - pointer to a download hints interface. Populated if form is not 167 // ready for initialization. 168 // 169 // Returns one of: 170 // PDF_FORM_ERROR: A common eror, in general incorrect parameters. 171 // PDF_FORM_NOTAVAIL: Data not available. 172 // PDF_FORM_AVAIL: Data available. 173 // PDF_FORM_NOTEXIST: No form data. 174 // 175 // This function can be called only after FPDFAvail_GetDocument() is called. 176 // The application should call this function whenever new data arrives and 177 // process all the generated download |hints|, if any, until the function 178 // |PDF_FORM_ERROR|, |PDF_FORM_AVAIL| or |PDF_FORM_NOTEXIST|. 179 // if hints is nullptr, the function just check current form availability. 180 // 181 // Applications can then perform page loading. It is recommend to call 182 // FPDFDOC_InitFormFillEnvironment() when |PDF_FORM_AVAIL| is returned. 183 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_IsFormAvail(FPDF_AVAIL avail, 184 FX_DOWNLOADHINTS* hints); 185 186 // Check whether a document is a linearized PDF. 187 // 188 // avail - handle to document availability provider. 189 // 190 // Returns one of: 191 // PDF_LINEARIZED 192 // PDF_NOT_LINEARIZED 193 // PDF_LINEARIZATION_UNKNOWN 194 // 195 // FPDFAvail_IsLinearized() will return |PDF_LINEARIZED| or |PDF_NOT_LINEARIZED| 196 // when we have 1k of data. If the files size less than 1k, it returns 197 // |PDF_LINEARIZATION_UNKNOWN| as there is insufficient information to determine 198 // if the PDF is linearlized. 199 FPDF_EXPORT int FPDF_CALLCONV FPDFAvail_IsLinearized(FPDF_AVAIL avail); 200 201 #ifdef __cplusplus 202 } // extern "C" 203 #endif // __cplusplus 204 205 #endif // PUBLIC_FPDF_DATAAVAIL_H_ 206