Really fix tests broken at 9778206.
[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
191 //          can convert coordinates
192 //          from screen system to page system using FPDF_DeviceToPage functions.
193 //
194 DLLEXPORT FPDF_LINK STDCALL FPDFLink_GetLinkAtPoint(FPDF_PAGE page,
195                                                     double x,
196                                                     double y);
197
198 // Function: FPDFLink_GetDest
199 //          Get destination info of a link.
200 // Parameters:
201 //          document    -   Handle to the document.
202 //          link        -   Handle to the link. Returned by
203 //          FPDFLink_GetLinkAtPoint.
204 // Return value:
205 //          Handle to the destination. NULL if there is no destination
206 //          associated with the link, in this case
207 //          the application should try FPDFLink_GetAction.
208 //
209 DLLEXPORT FPDF_DEST STDCALL FPDFLink_GetDest(FPDF_DOCUMENT document,
210                                              FPDF_LINK link);
211
212 // Function: FPDFLink_GetAction
213 //          Get action info of a link.
214 // Parameters:
215 //          link        -   Handle to the link.
216 // Return value:
217 //          Handle to the action. NULL if there is no action associated with the
218 //          link.
219 //
220 DLLEXPORT FPDF_ACTION STDCALL FPDFLink_GetAction(FPDF_LINK link);
221
222 // Function: FPDFLink_Enumerate
223 //          This function would enumerate all the link annotations in a single
224 //          PDF page.
225 // Parameters:
226 //          page[in]            -   Handle to the page.
227 //          startPos[in,out]    -   The start position to enumerate the link
228 //          annotations, which should be specified to start from
229 //                              -   0 for the first call, and would receive the
230 //                              next position for enumerating to start from.
231 //          linkAnnot[out]      -   Receive the link handle.
232 // Return value:
233 //          TRUE if succceed, else False;
234 //
235 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_Enumerate(FPDF_PAGE page,
236                                                int* startPos,
237                                                FPDF_LINK* linkAnnot);
238
239 // Function: FPDFLink_GetAnnotRect
240 //          Get the annotation rectangle. (Specified by the ¡°Rect¡± entry of
241 //          annotation dictionary).
242 // Parameters:
243 //          linkAnnot[in]       -   Handle to the link annotation.
244 //          rect[out]           -   The annotation rect.
245 // Return value:
246 //          TRUE if succceed, else False;
247 //
248 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetAnnotRect(FPDF_LINK linkAnnot,
249                                                   FS_RECTF* rect);
250
251 // Function: FPDFLink_CountQuadPoints
252 //          Get the count of quadrilateral points to the link annotation.
253 // Parameters:
254 //          linkAnnot[in]       -   Handle to the link annotation.
255 // Return value:
256 //          The count of quadrilateral points.
257 //
258 DLLEXPORT int STDCALL FPDFLink_CountQuadPoints(FPDF_LINK linkAnnot);
259
260 /* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
261 #ifndef _FS_DEF_STRUCTURE_QUADPOINTSF_
262 #define _FS_DEF_STRUCTURE_QUADPOINTSF_
263 typedef struct _FS_QUADPOINTSF {
264   FS_FLOAT x1;
265   FS_FLOAT y1;
266   FS_FLOAT x2;
267   FS_FLOAT y2;
268   FS_FLOAT x3;
269   FS_FLOAT y3;
270   FS_FLOAT x4;
271   FS_FLOAT y4;
272 } FS_QUADPOINTSF;
273 #endif /* _FS_DEF_STRUCTURE_QUADPOINTSF_ */
274
275 // Function: FPDFLink_GetQuadPoints
276 //          Get the quadrilateral points for the specified index in the link
277 //          annotation.
278 // Parameters:
279 //          linkAnnot[in]       -   Handle to the link annotation.
280 //          quadIndex[in]       -   The specified quad points index.
281 //          quadPoints[out]     -   Receive the quadrilateral points.
282 // Return value:
283 //          True if succeed, else False.
284 //
285 DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetQuadPoints(FPDF_LINK linkAnnot,
286                                                    int quadIndex,
287                                                    FS_QUADPOINTSF* quadPoints);
288
289 // Function: FPDF_GetMetaText
290 //          Get a text from meta data of the document. Result is encoded in
291 //          UTF-16LE.
292 // Parameters:
293 //          doc         -   Handle to a document
294 //          tag         -   The tag for the meta data. Currently, It can be
295 //          "Title", "Author",
296 //                          "Subject", "Keywords", "Creator", "Producer",
297 //                          "CreationDate", or "ModDate".
298 //                          For detailed explanation of these tags and their
299 //                          respective values,
300 //                          please refer to PDF Reference 1.6, section 10.2.1,
301 //                          "Document Information Dictionary".
302 //          buffer      -   A buffer for output the title. Can be NULL.
303 //          buflen      -   The length of the buffer, number of bytes. Can be 0.
304 // Return value:
305 //          Number of bytes the title consumes, including trailing zeros.
306 // Comments:
307 //          No matter on what platform, the title is always output in UTF-16LE
308 //          encoding, which means the buffer
309 //          can be regarded as an array of WORD (on Intel and compatible CPUs),
310 //          each WORD represent the Unicode of
311 //          a character (some special Unicode may take 2 WORDs). The string is
312 //          followed by two bytes of zero
313 //          indicating end of the string.
314 //
315 //          The return value always indicated number of bytes required for the
316 //          buffer, even when there is
317 //          no buffer specified, or the buffer size is less then required. In
318 //          this case, the buffer will not
319 //          be modified.
320 //
321 DLLEXPORT unsigned long STDCALL FPDF_GetMetaText(FPDF_DOCUMENT doc,
322                                                  FPDF_BYTESTRING tag,
323                                                  void* buffer,
324                                                  unsigned long buflen);
325
326 #ifdef __cplusplus
327 }
328 #endif
329
330 #endif  // PUBLIC_FPDF_DOC_H_