Fix mac build breakage at ce4ffb8.
[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 \
114   3  // Universal Resource Identifier, including web pages and
115      // other Internet based resources.
116 #define PDFACTION_LAUNCH 4  // Launch an application or open a file.
117
118 // Function: FPDFAction_GetType
119 //          Get type of an action.
120 // Parameters:
121 //          action      -   Handle to the action.
122 // Return value:
123 //          A type number as defined above.
124 //
125 DLLEXPORT unsigned long STDCALL FPDFAction_GetType(FPDF_ACTION action);
126
127 // Function: FPDFAction_GetDest
128 //          Get destination of an action.
129 // Parameters:
130 //          document    -   Handle to the document.
131 //          action      -   Handle to the action. It must be a GOTO or
132 //          REMOTEGOTO action.
133 // Return value:
134 //          Handle to the destination data.
135 // Comments:
136 //          In case of remote goto action, the application should first use
137 //          FPDFAction_GetFilePath to
138 //          get file path, then load that particular document, and use its
139 //          document handle to call this
140 //          function.
141 //
142 DLLEXPORT FPDF_DEST STDCALL FPDFAction_GetDest(FPDF_DOCUMENT document,
143                                                FPDF_ACTION action);
144
145 // Function: FPDFAction_GetURIPath
146 //          Get URI path of a URI action.
147 // Parameters:
148 //          document    -   Handle to the document.
149 //          action      -   Handle to the action. Must be a URI action.
150 //          buffer      -   A buffer for output the path string. Can be NULL.
151 //          buflen      -   The length of the buffer, number of bytes. Can be 0.
152 // Return value:
153 //          Number of bytes the URI path consumes, including trailing zeros.
154 // Comments:
155 //          The URI path is always encoded in 7-bit ASCII.
156 //
157 //          The return value always indicated number of bytes required for the
158 //          buffer, even when there is
159 //          no buffer specified, or the buffer size is less then required. In
160 //          this case, the buffer will not
161 //          be modified.
162 //
163 DLLEXPORT unsigned long STDCALL FPDFAction_GetURIPath(FPDF_DOCUMENT document,
164                                                       FPDF_ACTION action,
165                                                       void* buffer,
166                                                       unsigned long buflen);
167
168 // Function: FPDFDest_GetPageIndex
169 //          Get page index of a destination.
170 // Parameters:
171 //          document    -   Handle to the document.
172 //          dest        -   Handle to the destination.
173 // Return value:
174 //          The page index. Starting from 0 for the first page.
175 //
176 DLLEXPORT unsigned long STDCALL FPDFDest_GetPageIndex(FPDF_DOCUMENT document,
177                                                       FPDF_DEST dest);
178
179 // Function: FPDFLink_GetLinkAtPoint
180 //     Find a link at specified point on a document page.
181 // Parameters:
182 //     page        -   Handle to the document page.
183 //     x           -   The x coordinate of the point, specified in page
184 //                     coordinate system.
185 //     y           -   The y coordinate of the point, specified in page
186 //                     coordinate system.
187 // Return value:
188 //     Handle to the link. NULL if no link found at that point.
189 // Comments:
190 //     The point coordinates are specified in page coordinate system. You can
191 //     convert coordinates from screen system to page system using
192 //     FPDF_DeviceToPage().
193 //
194 DLLEXPORT FPDF_LINK STDCALL FPDFLink_GetLinkAtPoint(FPDF_PAGE page,
195                                                     double x,
196                                                     double y);
197
198 // Function: FPDFLink_GetLinkZOrderAtPoint
199 //     Find the z-order of a link at specified point on a document page.
200 // Parameters:
201 //     page        -   Handle to the document page.
202 //     x           -   The x coordinate of the point, specified in page
203 //                     coordinate system.
204 //     y           -   The y coordinate of the point, specified in page
205 //                     coordinate system.
206 // Return value:
207 //     Z-order of the link, or -1 if no link found at that point.
208 //     Higher numbers are closer to the front.
209 // Comments:
210 //     The point coordinates are specified in page coordinate system. You can
211 //     convert coordinates from screen system to page system using
212 //     FPDF_DeviceToPage().
213 //
214 DLLEXPORT int STDCALL
215 FPDFLink_GetLinkZOrderAtPoint(FPDF_PAGE page, double x, double y);
216
217 // Function: FPDFLink_GetDest
218 //          Get destination info of a link.
219 // Parameters:
220 //          document    -   Handle to the document.
221 //          link        -   Handle to the link. Returned by
222 //          FPDFLink_GetLinkAtPoint.
223 // Return value:
224 //          Handle to the destination. NULL if there is no destination
225 //          associated with the link, in this case
226 //          the application should try FPDFLink_GetAction.
227 //
228 DLLEXPORT FPDF_DEST STDCALL FPDFLink_GetDest(FPDF_DOCUMENT document,
229                                              FPDF_LINK link);
230
231 // Function: FPDFLink_GetAction
232 //          Get action info of a link.
233 // Parameters:
234 //          link        -   Handle to the link.
235 // Return value:
236 //          Handle to the action. NULL if there is no action associated with the
237 //          link.
238 //
239 DLLEXPORT FPDF_ACTION STDCALL FPDFLink_GetAction(FPDF_LINK link);
240
241 // Function: FPDFLink_Enumerate
242 //          This function would enumerate all the link annotations in a single
243 //          PDF page.
244 // Parameters:
245 //          page[in]            -   Handle to the page.
246 //          startPos[in,out]    -   The start position to enumerate the link
247 //          annotations, which should be specified to start from
248 //                              -   0 for the first call, and would receive the
249 //                              next position for enumerating to start from.
250 //          linkAnnot[out]      -   Receive the link handle.
251 // Return value:
252 //          TRUE if succceed, else False;
253 //
254 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_Enumerate(FPDF_PAGE page,
255                                                int* startPos,
256                                                FPDF_LINK* linkAnnot);
257
258 // Function: FPDFLink_GetAnnotRect
259 //          Get the annotation rectangle. (Specified by the ¡°Rect¡± entry of
260 //          annotation dictionary).
261 // Parameters:
262 //          linkAnnot[in]       -   Handle to the link annotation.
263 //          rect[out]           -   The annotation rect.
264 // Return value:
265 //          TRUE if succceed, else False;
266 //
267 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetAnnotRect(FPDF_LINK linkAnnot,
268                                                   FS_RECTF* rect);
269
270 // Function: FPDFLink_CountQuadPoints
271 //          Get the count of quadrilateral points to the link annotation.
272 // Parameters:
273 //          linkAnnot[in]       -   Handle to the link annotation.
274 // Return value:
275 //          The count of quadrilateral points.
276 //
277 DLLEXPORT int STDCALL FPDFLink_CountQuadPoints(FPDF_LINK linkAnnot);
278
279 /* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
280 #ifndef _FS_DEF_STRUCTURE_QUADPOINTSF_
281 #define _FS_DEF_STRUCTURE_QUADPOINTSF_
282 typedef struct _FS_QUADPOINTSF {
283   FS_FLOAT x1;
284   FS_FLOAT y1;
285   FS_FLOAT x2;
286   FS_FLOAT y2;
287   FS_FLOAT x3;
288   FS_FLOAT y3;
289   FS_FLOAT x4;
290   FS_FLOAT y4;
291 } FS_QUADPOINTSF;
292 #endif /* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
293
294 // Function: FPDFLink_GetQuadPoints
295 //          Get the quadrilateral points for the specified index in the link
296 //          annotation.
297 // Parameters:
298 //          linkAnnot[in]       -   Handle to the link annotation.
299 //          quadIndex[in]       -   The specified quad points index.
300 //          quadPoints[out]     -   Receive the quadrilateral points.
301 // Return value:
302 //          True if succeed, else False.
303 //
304 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetQuadPoints(FPDF_LINK linkAnnot,
305                                                    int quadIndex,
306                                                    FS_QUADPOINTSF* quadPoints);
307
308 // Function: FPDF_GetMetaText
309 //          Get a text from meta data of the document. Result is encoded in
310 //          UTF-16LE.
311 // Parameters:
312 //          doc         -   Handle to a document
313 //          tag         -   The tag for the meta data. Currently, It can be
314 //          "Title", "Author",
315 //                          "Subject", "Keywords", "Creator", "Producer",
316 //                          "CreationDate", or "ModDate".
317 //                          For detailed explanation of these tags and their
318 //                          respective values,
319 //                          please refer to PDF Reference 1.6, section 10.2.1,
320 //                          "Document Information Dictionary".
321 //          buffer      -   A buffer for output the title. Can be NULL.
322 //          buflen      -   The length of the buffer, number of bytes. Can be 0.
323 // Return value:
324 //          Number of bytes the title consumes, including trailing zeros.
325 // Comments:
326 //          No matter on what platform, the title is always output in UTF-16LE
327 //          encoding, which means the buffer
328 //          can be regarded as an array of WORD (on Intel and compatible CPUs),
329 //          each WORD represent the Unicode of
330 //          a character (some special Unicode may take 2 WORDs). The string is
331 //          followed by two bytes of zero
332 //          indicating end of the string.
333 //
334 //          The return value always indicated number of bytes required for the
335 //          buffer, even when there is
336 //          no buffer specified, or the buffer size is less then required. In
337 //          this case, the buffer will not
338 //          be modified.
339 //
340 DLLEXPORT unsigned long STDCALL FPDF_GetMetaText(FPDF_DOCUMENT doc,
341                                                  FPDF_BYTESTRING tag,
342                                                  void* buffer,
343                                                  unsigned long buflen);
344
345 #ifdef __cplusplus
346 }
347 #endif
348
349 #endif  // PUBLIC_FPDF_DOC_H_