1 // Copyright 2014 The PDFium Authors 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 // NOLINTNEXTLINE(build/include) 11 #include "fpdfview.h" 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif // __cplusplus 16 17 // Unsupported action type. 18 #define PDFACTION_UNSUPPORTED 0 19 // Go to a destination within current document. 20 #define PDFACTION_GOTO 1 21 // Go to a destination within another document. 22 #define PDFACTION_REMOTEGOTO 2 23 // URI, including web pages and other Internet resources. 24 #define PDFACTION_URI 3 25 // Launch an application or open a file. 26 #define PDFACTION_LAUNCH 4 27 // Go to a destination in an embedded file. 28 #define PDFACTION_EMBEDDEDGOTO 5 29 30 // View destination fit types. See pdfmark reference v9, page 48. 31 #define PDFDEST_VIEW_UNKNOWN_MODE 0 32 #define PDFDEST_VIEW_XYZ 1 33 #define PDFDEST_VIEW_FIT 2 34 #define PDFDEST_VIEW_FITH 3 35 #define PDFDEST_VIEW_FITV 4 36 #define PDFDEST_VIEW_FITR 5 37 #define PDFDEST_VIEW_FITB 6 38 #define PDFDEST_VIEW_FITBH 7 39 #define PDFDEST_VIEW_FITBV 8 40 41 // The file identifier entry type. See section 14.4 "File Identifiers" of the 42 // ISO 32000-1:2008 spec. 43 typedef enum { 44 FILEIDTYPE_PERMANENT = 0, 45 FILEIDTYPE_CHANGING = 1 46 } FPDF_FILEIDTYPE; 47 48 // Get the first child of |bookmark|, or the first top-level bookmark item. 49 // 50 // document - handle to the document. 51 // bookmark - handle to the current bookmark. Pass NULL for the first top 52 // level item. 53 // 54 // Returns a handle to the first child of |bookmark| or the first top-level 55 // bookmark item. NULL if no child or top-level bookmark found. 56 // Note that another name for the bookmarks is the document outline, as 57 // described in ISO 32000-1:2008, section 12.3.3. 58 FPDF_EXPORT FPDF_BOOKMARK FPDF_CALLCONV 59 FPDFBookmark_GetFirstChild(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark); 60 61 // Get the next sibling of |bookmark|. 62 // 63 // document - handle to the document. 64 // bookmark - handle to the current bookmark. 65 // 66 // Returns a handle to the next sibling of |bookmark|, or NULL if this is the 67 // last bookmark at this level. 68 // 69 // Note that the caller is responsible for handling circular bookmark 70 // references, as may arise from malformed documents. 71 FPDF_EXPORT FPDF_BOOKMARK FPDF_CALLCONV 72 FPDFBookmark_GetNextSibling(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark); 73 74 // Get the title of |bookmark|. 75 // 76 // bookmark - handle to the bookmark. 77 // buffer - buffer for the title. May be NULL. 78 // buflen - the length of the buffer in bytes. May be 0. 79 // 80 // Returns the number of bytes in the title, including the terminating NUL 81 // character. The number of bytes is returned regardless of the |buffer| and 82 // |buflen| parameters. 83 // 84 // Regardless of the platform, the |buffer| is always in UTF-16LE encoding. The 85 // string is terminated by a UTF16 NUL character. If |buflen| is less than the 86 // required length, or |buffer| is NULL, |buffer| will not be modified. 87 FPDF_EXPORT unsigned long FPDF_CALLCONV 88 FPDFBookmark_GetTitle(FPDF_BOOKMARK bookmark, 89 void* buffer, 90 unsigned long buflen); 91 92 // Experimental API. 93 // Get the number of chlidren of |bookmark|. 94 // 95 // bookmark - handle to the bookmark. 96 // 97 // Returns a signed integer that represents the number of sub-items the given 98 // bookmark has. If the value is positive, child items shall be shown by default 99 // (open state). If the value is negative, child items shall be hidden by 100 // default (closed state). Please refer to PDF 32000-1:2008, Table 153. 101 // Returns 0 if the bookmark has no children or is invalid. 102 FPDF_EXPORT int FPDF_CALLCONV FPDFBookmark_GetCount(FPDF_BOOKMARK bookmark); 103 104 // Find the bookmark with |title| in |document|. 105 // 106 // document - handle to the document. 107 // title - the UTF-16LE encoded Unicode title for which to search. 108 // 109 // Returns the handle to the bookmark, or NULL if |title| can't be found. 110 // 111 // FPDFBookmark_Find() will always return the first bookmark found even if 112 // multiple bookmarks have the same |title|. 113 FPDF_EXPORT FPDF_BOOKMARK FPDF_CALLCONV 114 FPDFBookmark_Find(FPDF_DOCUMENT document, FPDF_WIDESTRING title); 115 116 // Get the destination associated with |bookmark|. 117 // 118 // document - handle to the document. 119 // bookmark - handle to the bookmark. 120 // 121 // Returns the handle to the destination data, or NULL if no destination is 122 // associated with |bookmark|. 123 FPDF_EXPORT FPDF_DEST FPDF_CALLCONV 124 FPDFBookmark_GetDest(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark); 125 126 // Get the action associated with |bookmark|. 127 // 128 // bookmark - handle to the bookmark. 129 // 130 // Returns the handle to the action data, or NULL if no action is associated 131 // with |bookmark|. 132 // If this function returns a valid handle, it is valid as long as |bookmark| is 133 // valid. 134 // If this function returns NULL, FPDFBookmark_GetDest() should be called to get 135 // the |bookmark| destination data. 136 FPDF_EXPORT FPDF_ACTION FPDF_CALLCONV 137 FPDFBookmark_GetAction(FPDF_BOOKMARK bookmark); 138 139 // Get the type of |action|. 140 // 141 // action - handle to the action. 142 // 143 // Returns one of: 144 // PDFACTION_UNSUPPORTED 145 // PDFACTION_GOTO 146 // PDFACTION_REMOTEGOTO 147 // PDFACTION_URI 148 // PDFACTION_LAUNCH 149 FPDF_EXPORT unsigned long FPDF_CALLCONV FPDFAction_GetType(FPDF_ACTION action); 150 151 // Get the destination of |action|. 152 // 153 // document - handle to the document. 154 // action - handle to the action. |action| must be a |PDFACTION_GOTO| or 155 // |PDFACTION_REMOTEGOTO|. 156 // 157 // Returns a handle to the destination data, or NULL on error, typically 158 // because the arguments were bad or the action was of the wrong type. 159 // 160 // In the case of |PDFACTION_REMOTEGOTO|, you must first call 161 // FPDFAction_GetFilePath(), then load the document at that path, then pass 162 // the document handle from that document as |document| to FPDFAction_GetDest(). 163 FPDF_EXPORT FPDF_DEST FPDF_CALLCONV FPDFAction_GetDest(FPDF_DOCUMENT document, 164 FPDF_ACTION action); 165 166 // Get the file path of |action|. 167 // 168 // action - handle to the action. |action| must be a |PDFACTION_LAUNCH| or 169 // |PDFACTION_REMOTEGOTO|. 170 // buffer - a buffer for output the path string. May be NULL. 171 // buflen - the length of the buffer, in bytes. May be 0. 172 // 173 // Returns the number of bytes in the file path, including the trailing NUL 174 // character, or 0 on error, typically because the arguments were bad or the 175 // action was of the wrong type. 176 // 177 // Regardless of the platform, the |buffer| is always in UTF-8 encoding. 178 // If |buflen| is less than the returned length, or |buffer| is NULL, |buffer| 179 // will not be modified. 180 FPDF_EXPORT unsigned long FPDF_CALLCONV 181 FPDFAction_GetFilePath(FPDF_ACTION action, void* buffer, unsigned long buflen); 182 183 // Get the URI path of |action|. 184 // 185 // document - handle to the document. 186 // action - handle to the action. Must be a |PDFACTION_URI|. 187 // buffer - a buffer for the path string. May be NULL. 188 // buflen - the length of the buffer, in bytes. May be 0. 189 // 190 // Returns the number of bytes in the URI path, including the trailing NUL 191 // character, or 0 on error, typically because the arguments were bad or the 192 // action was of the wrong type. 193 // 194 // The |buffer| may contain badly encoded data. The caller should validate the 195 // output. e.g. Check to see if it is UTF-8. 196 // 197 // If |buflen| is less than the returned length, or |buffer| is NULL, |buffer| 198 // will not be modified. 199 // 200 // Historically, the documentation for this API claimed |buffer| is always 201 // encoded in 7-bit ASCII, but did not actually enforce it. 202 // https://pdfium.googlesource.com/pdfium.git/+/d609e84cee2e14a18333247485af91df48a40592 203 // added that enforcement, but that did not work well for real world PDFs that 204 // used UTF-8. As of this writing, this API reverted back to its original 205 // behavior prior to commit d609e84cee. 206 FPDF_EXPORT unsigned long FPDF_CALLCONV 207 FPDFAction_GetURIPath(FPDF_DOCUMENT document, 208 FPDF_ACTION action, 209 void* buffer, 210 unsigned long buflen); 211 212 // Get the page index of |dest|. 213 // 214 // document - handle to the document. 215 // dest - handle to the destination. 216 // 217 // Returns the 0-based page index containing |dest|. Returns -1 on error. 218 FPDF_EXPORT int FPDF_CALLCONV FPDFDest_GetDestPageIndex(FPDF_DOCUMENT document, 219 FPDF_DEST dest); 220 221 // Experimental API. 222 // Get the view (fit type) specified by |dest|. 223 // 224 // dest - handle to the destination. 225 // pNumParams - receives the number of view parameters, which is at most 4. 226 // pParams - buffer to write the view parameters. Must be at least 4 227 // FS_FLOATs long. 228 // Returns one of the PDFDEST_VIEW_* constants, PDFDEST_VIEW_UNKNOWN_MODE if 229 // |dest| does not specify a view. 230 FPDF_EXPORT unsigned long FPDF_CALLCONV 231 FPDFDest_GetView(FPDF_DEST dest, unsigned long* pNumParams, FS_FLOAT* pParams); 232 233 // Get the (x, y, zoom) location of |dest| in the destination page, if the 234 // destination is in [page /XYZ x y zoom] syntax. 235 // 236 // dest - handle to the destination. 237 // hasXVal - out parameter; true if the x value is not null 238 // hasYVal - out parameter; true if the y value is not null 239 // hasZoomVal - out parameter; true if the zoom value is not null 240 // x - out parameter; the x coordinate, in page coordinates. 241 // y - out parameter; the y coordinate, in page coordinates. 242 // zoom - out parameter; the zoom value. 243 // Returns TRUE on successfully reading the /XYZ value. 244 // 245 // Note the [x, y, zoom] values are only set if the corresponding hasXVal, 246 // hasYVal or hasZoomVal flags are true. 247 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 248 FPDFDest_GetLocationInPage(FPDF_DEST dest, 249 FPDF_BOOL* hasXVal, 250 FPDF_BOOL* hasYVal, 251 FPDF_BOOL* hasZoomVal, 252 FS_FLOAT* x, 253 FS_FLOAT* y, 254 FS_FLOAT* zoom); 255 256 // Find a link at point (|x|,|y|) on |page|. 257 // 258 // page - handle to the document page. 259 // x - the x coordinate, in the page coordinate system. 260 // y - the y coordinate, in the page coordinate system. 261 // 262 // Returns a handle to the link, or NULL if no link found at the given point. 263 // 264 // You can convert coordinates from screen coordinates to page coordinates using 265 // FPDF_DeviceToPage(). 266 FPDF_EXPORT FPDF_LINK FPDF_CALLCONV FPDFLink_GetLinkAtPoint(FPDF_PAGE page, 267 double x, 268 double y); 269 270 // Find the Z-order of link at point (|x|,|y|) on |page|. 271 // 272 // page - handle to the document page. 273 // x - the x coordinate, in the page coordinate system. 274 // y - the y coordinate, in the page coordinate system. 275 // 276 // Returns the Z-order of the link, or -1 if no link found at the given point. 277 // Larger Z-order numbers are closer to the front. 278 // 279 // You can convert coordinates from screen coordinates to page coordinates using 280 // FPDF_DeviceToPage(). 281 FPDF_EXPORT int FPDF_CALLCONV FPDFLink_GetLinkZOrderAtPoint(FPDF_PAGE page, 282 double x, 283 double y); 284 285 // Get destination info for |link|. 286 // 287 // document - handle to the document. 288 // link - handle to the link. 289 // 290 // Returns a handle to the destination, or NULL if there is no destination 291 // associated with the link. In this case, you should call FPDFLink_GetAction() 292 // to retrieve the action associated with |link|. 293 FPDF_EXPORT FPDF_DEST FPDF_CALLCONV FPDFLink_GetDest(FPDF_DOCUMENT document, 294 FPDF_LINK link); 295 296 // Get action info for |link|. 297 // 298 // link - handle to the link. 299 // 300 // Returns a handle to the action associated to |link|, or NULL if no action. 301 // If this function returns a valid handle, it is valid as long as |link| is 302 // valid. 303 FPDF_EXPORT FPDF_ACTION FPDF_CALLCONV FPDFLink_GetAction(FPDF_LINK link); 304 305 // Enumerates all the link annotations in |page|. 306 // 307 // page - handle to the page. 308 // start_pos - the start position, should initially be 0 and is updated with 309 // the next start position on return. 310 // link_annot - the link handle for |startPos|. 311 // 312 // Returns TRUE on success. 313 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFLink_Enumerate(FPDF_PAGE page, 314 int* start_pos, 315 FPDF_LINK* link_annot); 316 317 // Experimental API. 318 // Gets FPDF_ANNOTATION object for |link_annot|. 319 // 320 // page - handle to the page in which FPDF_LINK object is present. 321 // link_annot - handle to link annotation. 322 // 323 // Returns FPDF_ANNOTATION from the FPDF_LINK and NULL on failure, 324 // if the input link annot or page is NULL. 325 FPDF_EXPORT FPDF_ANNOTATION FPDF_CALLCONV 326 FPDFLink_GetAnnot(FPDF_PAGE page, FPDF_LINK link_annot); 327 328 // Get the rectangle for |link_annot|. 329 // 330 // link_annot - handle to the link annotation. 331 // rect - the annotation rectangle. 332 // 333 // Returns true on success. 334 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDFLink_GetAnnotRect(FPDF_LINK link_annot, 335 FS_RECTF* rect); 336 337 // Get the count of quadrilateral points to the |link_annot|. 338 // 339 // link_annot - handle to the link annotation. 340 // 341 // Returns the count of quadrilateral points. 342 FPDF_EXPORT int FPDF_CALLCONV FPDFLink_CountQuadPoints(FPDF_LINK link_annot); 343 344 // Get the quadrilateral points for the specified |quad_index| in |link_annot|. 345 // 346 // link_annot - handle to the link annotation. 347 // quad_index - the specified quad point index. 348 // quad_points - receives the quadrilateral points. 349 // 350 // Returns true on success. 351 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 352 FPDFLink_GetQuadPoints(FPDF_LINK link_annot, 353 int quad_index, 354 FS_QUADPOINTSF* quad_points); 355 356 // Experimental API 357 // Gets an additional-action from |page|. 358 // 359 // page - handle to the page, as returned by FPDF_LoadPage(). 360 // aa_type - the type of the page object's addtional-action, defined 361 // in public/fpdf_formfill.h 362 // 363 // Returns the handle to the action data, or NULL if there is no 364 // additional-action of type |aa_type|. 365 // If this function returns a valid handle, it is valid as long as |page| is 366 // valid. 367 FPDF_EXPORT FPDF_ACTION FPDF_CALLCONV FPDF_GetPageAAction(FPDF_PAGE page, 368 int aa_type); 369 370 // Experimental API. 371 // Get the file identifer defined in the trailer of |document|. 372 // 373 // document - handle to the document. 374 // id_type - the file identifier type to retrieve. 375 // buffer - a buffer for the file identifier. May be NULL. 376 // buflen - the length of the buffer, in bytes. May be 0. 377 // 378 // Returns the number of bytes in the file identifier, including the NUL 379 // terminator. 380 // 381 // The |buffer| is always a byte string. The |buffer| is followed by a NUL 382 // terminator. If |buflen| is less than the returned length, or |buffer| is 383 // NULL, |buffer| will not be modified. 384 FPDF_EXPORT unsigned long FPDF_CALLCONV 385 FPDF_GetFileIdentifier(FPDF_DOCUMENT document, 386 FPDF_FILEIDTYPE id_type, 387 void* buffer, 388 unsigned long buflen); 389 390 // Get meta-data |tag| content from |document|. 391 // 392 // document - handle to the document. 393 // tag - the tag to retrieve. The tag can be one of: 394 // Title, Author, Subject, Keywords, Creator, Producer, 395 // CreationDate, or ModDate. 396 // For detailed explanations of these tags and their respective 397 // values, please refer to PDF Reference 1.6, section 10.2.1, 398 // 'Document Information Dictionary'. 399 // buffer - a buffer for the tag. May be NULL. 400 // buflen - the length of the buffer, in bytes. May be 0. 401 // 402 // Returns the number of bytes in the tag, including trailing zeros. 403 // 404 // The |buffer| is always encoded in UTF-16LE. The |buffer| is followed by two 405 // bytes of zeros indicating the end of the string. If |buflen| is less than 406 // the returned length, or |buffer| is NULL, |buffer| will not be modified. 407 // 408 // For linearized files, FPDFAvail_IsFormAvail must be called before this, and 409 // it must have returned PDF_FORM_AVAIL or PDF_FORM_NOTEXIST. Before that, there 410 // is no guarantee the metadata has been loaded. 411 FPDF_EXPORT unsigned long FPDF_CALLCONV FPDF_GetMetaText(FPDF_DOCUMENT document, 412 FPDF_BYTESTRING tag, 413 void* buffer, 414 unsigned long buflen); 415 416 // Get the page label for |page_index| from |document|. 417 // 418 // document - handle to the document. 419 // page_index - the 0-based index of the page. 420 // buffer - a buffer for the page label. May be NULL. 421 // buflen - the length of the buffer, in bytes. May be 0. 422 // 423 // Returns the number of bytes in the page label, including trailing zeros. 424 // 425 // The |buffer| is always encoded in UTF-16LE. The |buffer| is followed by two 426 // bytes of zeros indicating the end of the string. If |buflen| is less than 427 // the returned length, or |buffer| is NULL, |buffer| will not be modified. 428 FPDF_EXPORT unsigned long FPDF_CALLCONV 429 FPDF_GetPageLabel(FPDF_DOCUMENT document, 430 int page_index, 431 void* buffer, 432 unsigned long buflen); 433 434 #ifdef __cplusplus 435 } // extern "C" 436 #endif // __cplusplus 437 438 #endif // PUBLIC_FPDF_DOC_H_ 439