public/fpdf_dataavail.h

   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 /** The result of the process which check linearized PDF. */
  15 #define FSDK_IS_LINEARIZED          1
  16 #define FSDK_NOT_LINEARIZED         0
  17 #define FSDK_UNKNOW_LINEARIZED      -1
  18
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /**
  25  * Interface: FX_FILEAVAIL
  26  *          Interface for checking whether the section of the file is available.
  27  */
  28 typedef struct _FX_FILEAVAIL {
  29     /**
  30      * Version number of the interface. Currently must be 1.
  31      */
  32     int version;
  33
  34     /**
  35      * Method: IsDataAvail
  36      *      Report whether the specified data section is available. A section is available only if all bytes in the section is available.
  37      * Interface Version:
  38      *      1
  39      * Implementation Required:
  40      *      Yes
  41      * Parameters:
  42      *      pThis       -   Pointer to the interface structure itself.
  43      *      offset      -   The offset of the data section in the file.
  44      *      size        -   The size of the data section
  45      * Return Value:
  46      *      true means the specified data section is available.
  47      * Comments:
  48      *      Called by Foxit SDK to check whether the data section is ready.
  49      */
  50     FPDF_BOOL (*IsDataAvail)(struct _FX_FILEAVAIL* pThis, size_t offset, size_t size);
  51 } FX_FILEAVAIL;
  52
  53 typedef void* FPDF_AVAIL;
  54
  55 /**
  56 * Function: FPDFAvail_Create
  57 *           Create a document availability provider.
  58 *
  59 * Parameters:
  60 *           file_avail  -   Pointer to file availability interface to check availability of file data.
  61 *           file        -   Pointer to a file access interface for reading data from file.
  62 * Return value:
  63 *           A handle to the document availability provider. NULL for error.
  64 * Comments:
  65 *           Application must call FPDFAvail_Destroy when done with the availability provider.
  66 * Notes:
  67 *           The method can not support to load a document which consists of dynamic XFA fields now.
  68 */
  69 DLLEXPORT FPDF_AVAIL STDCALL FPDFAvail_Create(FX_FILEAVAIL* file_avail, FPDF_FILEACCESS* file);
  70
  71 /**
  72 * Function: FPDFAvail_Destroy
  73 *           Destroy a document availibity provider.
  74 *
  75 * Parameters:
  76 *           avail       -   Handle to document availability provider returned by FPDFAvail_Create
  77 * Return Value:
  78 *           None.
  79 */
  80 DLLEXPORT void STDCALL FPDFAvail_Destroy(FPDF_AVAIL avail);
  81
  82 /**
  83  * Interface: FX_DOWNLOADHINTS
  84  *          Download hints interface. Used to receive hints for further downloading.
  85  */
  86 typedef struct _FX_DOWNLOADHINTS {
  87     /**
  88      * Version number of the interface. Currently must be 1.
  89      */
  90     int version;
  91
  92     /**
  93      * Method: AddSegment
  94      *      Add a section to be downloaded.
  95      * Interface Version:
  96      *      1
  97      * Implementation Required:
  98      *      Yes
  99      * Parameters:
 100      *      pThis       -   Pointer to the interface structure itself.
 101      *      offset      -   The offset of the hint reported to be downloaded.
 102      *      size        -   The size of the hint reported to be downloaded.
 103      * Return Value:
 104      *      None.
 105      * Comments:
 106      *      Called by Foxit SDK to report some downloading hints for download manager.
 107      *      The position and size of section may be not accurate, part of the section might be already available.
 108      *      The download manager must deal with that to maximize download efficiency.
 109      */
 110     void (*AddSegment)(struct _FX_DOWNLOADHINTS* pThis, size_t offset, size_t size);
 111 } FX_DOWNLOADHINTS;
 112
 113 /**
 114 * Function: FPDFAvail_IsDocAvail
 115 *           Check whether the document is ready for loading, if not, get download hints.
 116 *
 117 * Parameters:
 118 *           avail       -   Handle to document availability provider returned by FPDFAvail_Create
 119 *           hints       -   Pointer to a download hints interface, receiving generated hints
 120 * Return value:
 121 *           Non-zero for page is fully available, 0 for page not yet available.
 122 * Comments:
 123 *           The application should call this function whenever new data arrived, and process all the
 124 *           generated download hints if any, until the function returns non-zero value. Then the
 125 *           application can call FPDFAvail_GetDocument() to get a document handle.
 126 */
 127 DLLEXPORT int STDCALL FPDFAvail_IsDocAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);
 128
 129 /**
 130 * Function: FPDFAvail_GetDocument
 131 *           Get document from the availability provider.
 132 *
 133 * Parameters:
 134 *           avail       -   Handle to document availability provider returned by FPDFAvail_Create
 135 *     password  -   Optional password for decrypting the PDF file.
 136 * Return value:
 137 *           Handle to the document.
 138 * Comments:
 139 *           After FPDFAvail_IsDocAvail() returns TRUE, the application should call this function to
 140 *           get the document handle. To close the document, use FPDF_CloseDocument function.
 141 */
 142 DLLEXPORT FPDF_DOCUMENT STDCALL FPDFAvail_GetDocument(FPDF_AVAIL avail,
 143                                                       FPDF_BYTESTRING password);
 144
 145 /**
 146 * Function: FPDFAvail_GetFirstPageNum
 147 *           Get page number for the first available page in a linearized PDF
 148 *
 149 * Parameters:
 150 *           doc         -   A document handle returned by FPDFAvail_GetDocument
 151 * Return Value:
 152 *           Zero-based index for the first available page.
 153 * Comments:
 154 *           For most linearized PDFs, the first available page would be just the first page, however,
 155 *           some PDFs might make other page to be the first available page.
 156 *           For non-linearized PDF, this function will always return zero.
 157 */
 158 DLLEXPORT int STDCALL FPDFAvail_GetFirstPageNum(FPDF_DOCUMENT doc);
 159
 160 /**
 161 * Function: FPDFAvail_IsPageAvail
 162 *           Check whether a page is ready for loading, if not, get download hints.
 163 *
 164 * Parameters:
 165 *           avail       -   Handle to document availability provider returned by FPDFAvail_Create
 166 *           page_index  -   Index number of the page. 0 for the first page.
 167 *           hints       -   Pointer to a download hints interface, receiving generated hints
 168 * Return value:
 169 *           Non-zero for page is fully available, 0 for page not yet available.
 170 * Comments:
 171 *           This function call be called only after FPDFAvail_GetDocument if called.
 172 *           The application should call this function whenever new data arrived, and process all the
 173 *           generated download hints if any, until the function returns non-zero value. Then the
 174 *           application can perform page loading.
 175 */
 176 DLLEXPORT int STDCALL FPDFAvail_IsPageAvail(FPDF_AVAIL avail, int page_index, FX_DOWNLOADHINTS* hints);
 177
 178 /**
 179 * Function: FPDFAvail_ISFormAvail
 180 *           Check whether Form data is ready for init, if not, get download hints.
 181 *
 182 * Parameters:
 183 *           avail       -   Handle to document availability provider returned by FPDFAvail_Create
 184 *           hints       -   Pointer to a download hints interface, receiving generated hints
 185 * Return value:
 186 *           Non-zero for Form data is fully available, 0 for Form data not yet available.
 187 *           Details: -1 - error, the input parameter not correct, such as hints is null.
 188 *                    0  - data not available
 189 *                    1  - data available
 190 *                    2  - no form data.
 191 * Comments:
 192 *           This function call be called only after FPDFAvail_GetDocument if called.
 193 *           The application should call this function whenever new data arrived, and process all the
 194 *           generated download hints if any, until the function returns non-zero value. Then the
 195 *           application can perform page loading. Recommend to call FPDFDOC_InitFormFillEnvironment
 196 *           after the function returns non-zero value.
 197 */
 198 DLLEXPORT int STDCALL FPDFAvail_IsFormAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints);
 199
 200 /**
 201 * Function: FPDFAvail_IsLinearized
 202 *           To check whether a document is Linearized PDF file.
 203 *
 204 * Parameters:
 205 *           avail       -   Handle to document availability provider returned by FPDFAvail_Create
 206 * Return value:
 207 *           return TRUE means the document is linearized PDF else not.
 208 *           FSDK_IS_LINEARIZED is a linearize file.
 209 *           FSDK_NOT_LINEARIZED is not a linearize file.
 210 *           FSDK_UNKNOW_LINEARIZED don't know whether the file is a linearize file.
 211 * Comments:
 212 *           It return TRUE/FALSE as soon as we have first 1K data.  If the file's size less than
 213 *           1K,we don't known whether the PDF is a linearized file.
 214 *
 215 */
 216 DLLEXPORT FPDF_BOOL STDCALL FPDFAvail_IsLinearized(FPDF_AVAIL avail);
 217
 218 #ifdef __cplusplus
 219 }
 220 #endif
 221
 222 #endif  // PUBLIC_FPDF_DATAAVAIL_H_