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