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