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