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 28 extern "C" { 29 #endif 30 31 /** 32 * Interface: FX_FILEAVAIL 33 * Interface for checking whether the section of the file is available. 34 */ 35 typedef 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 61 typedef 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 */ 78 DLLEXPORT 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 */ 91 DLLEXPORT 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 */ 98 typedef 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 */ 152 DLLEXPORT int STDCALL 153 FPDFAvail_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 */ 171 DLLEXPORT 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 */ 188 DLLEXPORT 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 */ 213 DLLEXPORT 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 */ 244 DLLEXPORT 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 */ 267 DLLEXPORT int STDCALL FPDFAvail_IsLinearized(FPDF_AVAIL avail); 268 269 #ifdef __cplusplus 270 } 271 #endif 272 273 #endif // PUBLIC_FPDF_DATAAVAIL_H_ 274