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