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