Add signatures to FXJS_V8.
[pdfium.git] / public / fpdf_doc.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_DOC_H_
8 #define PUBLIC_FPDF_DOC_H_
9
10 #include "fpdfview.h"
11
12 // Exported Functions
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16
17 // Function: FPDFBookmark_GetFirstChild
18 //          Get the first child of a bookmark item, or the first top level
19 //          bookmark item.
20 // Parameters:
21 //          document    -   Handle to the document. Returned by
22 //          FPDF_LoadDocument or FPDF_LoadMemDocument.
23 //          bookmark    -   Handle to the current bookmark. Can be NULL if you
24 //          want to get the first top level item.
25 // Return value:
26 //          Handle to the first child or top level bookmark item. NULL if no
27 //          child or top level bookmark found.
28 //
29 DLLEXPORT FPDF_BOOKMARK STDCALL
30 FPDFBookmark_GetFirstChild(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark);
31
32 // Function: FPDFBookmark_GetNextSibling
33 //          Get next bookmark item at the same level.
34 // Parameters:
35 //          document    -   Handle to the document. Returned by
36 //          FPDF_LoadDocument or FPDF_LoadMemDocument.
37 //          bookmark    -   Handle to the current bookmark. Cannot be NULL.
38 // Return value:
39 //          Handle to the next bookmark item at the same level. NULL if this is
40 //          the last bookmark at this level.
41 //
42 DLLEXPORT FPDF_BOOKMARK STDCALL
43 FPDFBookmark_GetNextSibling(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark);
44
45 // Function: FPDFBookmark_GetTitle
46 //          Get title of a bookmark.
47 // Parameters:
48 //          bookmark    -   Handle to the bookmark.
49 //          buffer      -   Buffer for the title. Can be NULL.
50 //          buflen      -   The length of the buffer in bytes. Can be 0.
51 // Return value:
52 //          Number of bytes the title consumes, including trailing zeros.
53 // Comments:
54 //          Regardless of the platform, the title is always in UTF-16LE
55 //          encoding. That means the buffer
56 //          can be treated as an array of WORD (on Intel and compatible CPUs),
57 //          each WORD representing the Unicode of
58 //          a character(some special Unicode may take 2 WORDs).The string is
59 //          followed by two bytes of zero
60 //          indicating the end of the string.
61 //
62 //          The return value always indicates the number of bytes required for
63 //          the buffer, even if no buffer is specified
64 //          or the buffer size is less then required. In these cases, the buffer
65 //          will not be modified.
66 //
67 DLLEXPORT unsigned long STDCALL FPDFBookmark_GetTitle(FPDF_BOOKMARK bookmark,
68                                                       void* buffer,
69                                                       unsigned long buflen);
70
71 // Function: FPDFBookmark_Find
72 //          Find a bookmark in the document, using the bookmark title.
73 // Parameters:
74 //          document    -   Handle to the document. Returned by
75 //          FPDF_LoadDocument or FPDF_LoadMemDocument.
76 //          title       -   The UTF-16LE encoded Unicode string for the bookmark
77 //          title to be searched. Can't be NULL.
78 // Return value:
79 //          Handle to the found bookmark item. NULL if the title can't be found.
80 // Comments:
81 //          It always returns the first found bookmark if more than one
82 //          bookmarks have the same title.
83 //
84 DLLEXPORT FPDF_BOOKMARK STDCALL FPDFBookmark_Find(FPDF_DOCUMENT document,
85                                                   FPDF_WIDESTRING title);
86
87 // Function: FPDFBookmark_GetDest
88 //          Get the destination associated with a bookmark item.
89 // Parameters:
90 //          document    -   Handle to the document.
91 //          bookmark    -   Handle to the bookmark.
92 // Return value:
93 //          Handle to the destination data. NULL if no destination is associated
94 //          with this bookmark.
95 //
96 DLLEXPORT FPDF_DEST STDCALL FPDFBookmark_GetDest(FPDF_DOCUMENT document,
97                                                  FPDF_BOOKMARK bookmark);
98
99 // Function: FPDFBookmark_GetAction
100 //          Get the action associated with a bookmark item.
101 // Parameters:
102 //          bookmark    -   Handle to the bookmark.
103 // Return value:
104 //          Handle to the action data. NULL if no action is associated with this
105 //          bookmark. In this case, the
106 //          application should try FPDFBookmark_GetDest.
107 //
108 DLLEXPORT FPDF_ACTION STDCALL FPDFBookmark_GetAction(FPDF_BOOKMARK bookmark);
109
110 #define PDFACTION_UNSUPPORTED 0  // Unsupported action type.
111 #define PDFACTION_GOTO 1         // Go to a destination within current document.
112 #define PDFACTION_REMOTEGOTO 2   // Go to a destination within another document.
113 #define PDFACTION_URI 3          // Universal Resource Identifier, including web
114                                  // pages and other Internet based resources.
115 #define PDFACTION_LAUNCH 4       // Launch an application or open a file.
116
117 // Function: FPDFAction_GetType
118 //          Get type of an action.
119 // Parameters:
120 //          action      -   Handle to the action.
121 // Return value:
122 //          A type number as defined above.
123 //
124 DLLEXPORT unsigned long STDCALL FPDFAction_GetType(FPDF_ACTION action);
125
126 // Function: FPDFAction_GetDest
127 //          Get destination of an action.
128 // Parameters:
129 //          document    -   Handle to the document.
130 //          action      -   Handle to the action. It must be a GOTO or
131 //          REMOTEGOTO action.
132 // Return value:
133 //          Handle to the destination data.
134 // Comments:
135 //          In case of remote goto action, the application should first use
136 //          FPDFAction_GetFilePath to
137 //          get file path, then load that particular document, and use its
138 //          document handle to call this
139 //          function.
140 //
141 DLLEXPORT FPDF_DEST STDCALL FPDFAction_GetDest(FPDF_DOCUMENT document,
142                                                FPDF_ACTION action);
143
144 // Function: FPDFAction_GetFilePath
145 //          Get file path of a remote goto action.
146 // Parameters:
147 //          action    -   Handle to the action. Must be a REMOTEGOTO or
148 //                        LAUNCH action.
149 //          buffer    -   A buffer for output the path string. Can be NULL.
150 //          buflen    -   The length of the buffer, number of bytes. Can be 0.
151 // Return value:
152 //          Number of bytes the file path consumes, including trailing zero.
153 //
154 // Comments:
155 //          The file path is UTF-8 encoded. The return value is the number of
156 //          bytes required for the buffer, even when there is no buffer
157 //          specified, or the buffer size is less then required. In this case,
158 //          the buffer will not be modified.
159 //
160 DLLEXPORT unsigned long STDCALL
161 FPDFAction_GetFilePath(FPDF_ACTION action, void* buffer, unsigned long buflen);
162
163 // Function: FPDFAction_GetURIPath
164 //          Get URI path of a URI action.
165 // Parameters:
166 //          document    -   Handle to the document.
167 //          action      -   Handle to the action. Must be a URI action.
168 //          buffer      -   A buffer for output the path string. Can be NULL.
169 //          buflen      -   The length of the buffer, number of bytes. Can be 0.
170 // Return value:
171 //          Number of bytes the URI path consumes, including trailing zeros.
172 // Comments:
173 //          The URI path is always encoded in 7-bit ASCII.
174 //
175 //          The return value is the number of bytes required for the buffer,
176 //          even when there is no buffer specified, or the buffer size is less
177 //          then required. In this case, the buffer will not be modified.
178 //
179 DLLEXPORT unsigned long STDCALL FPDFAction_GetURIPath(FPDF_DOCUMENT document,
180                                                       FPDF_ACTION action,
181                                                       void* buffer,
182                                                       unsigned long buflen);
183
184 // Function: FPDFDest_GetPageIndex
185 //          Get page index of a destination.
186 // Parameters:
187 //          document    -   Handle to the document.
188 //          dest        -   Handle to the destination.
189 // Return value:
190 //          The page index. Starting from 0 for the first page.
191 //
192 DLLEXPORT unsigned long STDCALL FPDFDest_GetPageIndex(FPDF_DOCUMENT document,
193                                                       FPDF_DEST dest);
194
195 // Function: FPDFLink_GetLinkAtPoint
196 //     Find a link at specified point on a document page.
197 // Parameters:
198 //     page        -   Handle to the document page.
199 //     x           -   The x coordinate of the point, specified in page
200 //                     coordinate system.
201 //     y           -   The y coordinate of the point, specified in page
202 //                     coordinate system.
203 // Return value:
204 //     Handle to the link. NULL if no link found at that point.
205 // Comments:
206 //     The point coordinates are specified in page coordinate system. You can
207 //     convert coordinates from screen system to page system using
208 //     FPDF_DeviceToPage().
209 //
210 DLLEXPORT FPDF_LINK STDCALL FPDFLink_GetLinkAtPoint(FPDF_PAGE page,
211                                                     double x,
212                                                     double y);
213
214 // Function: FPDFLink_GetLinkZOrderAtPoint
215 //     Find the z-order of a link at specified point on a document page.
216 // Parameters:
217 //     page        -   Handle to the document page.
218 //     x           -   The x coordinate of the point, specified in page
219 //                     coordinate system.
220 //     y           -   The y coordinate of the point, specified in page
221 //                     coordinate system.
222 // Return value:
223 //     Z-order of the link, or -1 if no link found at that point.
224 //     Higher numbers are closer to the front.
225 // Comments:
226 //     The point coordinates are specified in page coordinate system. You can
227 //     convert coordinates from screen system to page system using
228 //     FPDF_DeviceToPage().
229 //
230 DLLEXPORT int STDCALL
231 FPDFLink_GetLinkZOrderAtPoint(FPDF_PAGE page, double x, double y);
232
233 // Function: FPDFLink_GetDest
234 //          Get destination info of a link.
235 // Parameters:
236 //          document    -   Handle to the document.
237 //          link        -   Handle to the link. Returned by
238 //          FPDFLink_GetLinkAtPoint.
239 // Return value:
240 //          Handle to the destination. NULL if there is no destination
241 //          associated with the link, in this case
242 //          the application should try FPDFLink_GetAction.
243 //
244 DLLEXPORT FPDF_DEST STDCALL FPDFLink_GetDest(FPDF_DOCUMENT document,
245                                              FPDF_LINK link);
246
247 // Function: FPDFLink_GetAction
248 //          Get action info of a link.
249 // Parameters:
250 //          link        -   Handle to the link.
251 // Return value:
252 //          Handle to the action. NULL if there is no action associated with the
253 //          link.
254 //
255 DLLEXPORT FPDF_ACTION STDCALL FPDFLink_GetAction(FPDF_LINK link);
256
257 // Function: FPDFLink_Enumerate
258 //          This function would enumerate all the link annotations in a single
259 //          PDF page.
260 // Parameters:
261 //          page[in]            -   Handle to the page.
262 //          startPos[in,out]    -   The start position to enumerate the link
263 //          annotations, which should be specified to start from
264 //                              -   0 for the first call, and would receive the
265 //                              next position for enumerating to start from.
266 //          linkAnnot[out]      -   Receive the link handle.
267 // Return value:
268 //          TRUE if succceed, else False;
269 //
270 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_Enumerate(FPDF_PAGE page,
271                                                int* startPos,
272                                                FPDF_LINK* linkAnnot);
273
274 // Function: FPDFLink_GetAnnotRect
275 //          Get the annotation rectangle. (Specified by the ¡°Rect¡± entry of
276 //          annotation dictionary).
277 // Parameters:
278 //          linkAnnot[in]       -   Handle to the link annotation.
279 //          rect[out]           -   The annotation rect.
280 // Return value:
281 //          TRUE if succceed, else False;
282 //
283 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetAnnotRect(FPDF_LINK linkAnnot,
284                                                   FS_RECTF* rect);
285
286 // Function: FPDFLink_CountQuadPoints
287 //          Get the count of quadrilateral points to the link annotation.
288 // Parameters:
289 //          linkAnnot[in]       -   Handle to the link annotation.
290 // Return value:
291 //          The count of quadrilateral points.
292 //
293 DLLEXPORT int STDCALL FPDFLink_CountQuadPoints(FPDF_LINK linkAnnot);
294
295 /* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
296 #ifndef _FS_DEF_STRUCTURE_QUADPOINTSF_
297 #define _FS_DEF_STRUCTURE_QUADPOINTSF_
298 typedef struct _FS_QUADPOINTSF {
299   FS_FLOAT x1;
300   FS_FLOAT y1;
301   FS_FLOAT x2;
302   FS_FLOAT y2;
303   FS_FLOAT x3;
304   FS_FLOAT y3;
305   FS_FLOAT x4;
306   FS_FLOAT y4;
307 } FS_QUADPOINTSF;
308 #endif /* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
309
310 // Function: FPDFLink_GetQuadPoints
311 //          Get the quadrilateral points for the specified index in the link
312 //          annotation.
313 // Parameters:
314 //          linkAnnot[in]       -   Handle to the link annotation.
315 //          quadIndex[in]       -   The specified quad points index.
316 //          quadPoints[out]     -   Receive the quadrilateral points.
317 // Return value:
318 //          True if succeed, else False.
319 //
320 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetQuadPoints(FPDF_LINK linkAnnot,
321                                                    int quadIndex,
322                                                    FS_QUADPOINTSF* quadPoints);
323
324 // Function: FPDF_GetMetaText
325 //          Get a text from meta data of the document. Result is encoded in
326 //          UTF-16LE.
327 // Parameters:
328 //          doc         -   Handle to a document
329 //          tag         -   The tag for the meta data. Currently, It can be
330 //          "Title", "Author",
331 //                          "Subject", "Keywords", "Creator", "Producer",
332 //                          "CreationDate", or "ModDate".
333 //                          For detailed explanation of these tags and their
334 //                          respective values,
335 //                          please refer to PDF Reference 1.6, section 10.2.1,
336 //                          "Document Information Dictionary".
337 //          buffer      -   A buffer for output the title. Can be NULL.
338 //          buflen      -   The length of the buffer, number of bytes. Can be 0.
339 // Return value:
340 //          Number of bytes the title consumes, including trailing zeros.
341 // Comments:
342 //          No matter on what platform, the title is always output in UTF-16LE
343 //          encoding, which means the buffer
344 //          can be regarded as an array of WORD (on Intel and compatible CPUs),
345 //          each WORD represent the Unicode of
346 //          a character (some special Unicode may take 2 WORDs). The string is
347 //          followed by two bytes of zero
348 //          indicating end of the string.
349 //
350 //          The return value always indicated number of bytes required for the
351 //          buffer, even when there is
352 //          no buffer specified, or the buffer size is less then required. In
353 //          this case, the buffer will not
354 //          be modified.
355 //
356 DLLEXPORT unsigned long STDCALL FPDF_GetMetaText(FPDF_DOCUMENT doc,
357                                                  FPDF_BYTESTRING tag,
358                                                  void* buffer,
359                                                  unsigned long buflen);
360
361 #ifdef __cplusplus
362 }
363 #endif
364
365 #endif  // PUBLIC_FPDF_DOC_H_