1 // Copyright 2016 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_STRUCTTREE_H_ 8 #define PUBLIC_FPDF_STRUCTTREE_H_ 9 10 // clang-format off 11 // NOLINTNEXTLINE(build/include) 12 #include "fpdfview.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 // Function: FPDF_StructTree_GetForPage 19 // Get the structure tree for a page. 20 // Parameters: 21 // page - Handle to the page, as returned by FPDF_LoadPage(). 22 // Return value: 23 // A handle to the structure tree or NULL on error. 24 FPDF_EXPORT FPDF_STRUCTTREE FPDF_CALLCONV 25 FPDF_StructTree_GetForPage(FPDF_PAGE page); 26 27 // Function: FPDF_StructTree_Close 28 // Release a resource allocated by FPDF_StructTree_GetForPage(). 29 // Parameters: 30 // struct_tree - Handle to the structure tree, as returned by 31 // FPDF_StructTree_LoadPage(). 32 // Return value: 33 // None. 34 FPDF_EXPORT void FPDF_CALLCONV 35 FPDF_StructTree_Close(FPDF_STRUCTTREE struct_tree); 36 37 // Function: FPDF_StructTree_CountChildren 38 // Count the number of children for the structure tree. 39 // Parameters: 40 // struct_tree - Handle to the structure tree, as returned by 41 // FPDF_StructTree_LoadPage(). 42 // Return value: 43 // The number of children, or -1 on error. 44 FPDF_EXPORT int FPDF_CALLCONV 45 FPDF_StructTree_CountChildren(FPDF_STRUCTTREE struct_tree); 46 47 // Function: FPDF_StructTree_GetChildAtIndex 48 // Get a child in the structure tree. 49 // Parameters: 50 // struct_tree - Handle to the structure tree, as returned by 51 // FPDF_StructTree_LoadPage(). 52 // index - The index for the child, 0-based. 53 // Return value: 54 // The child at the n-th index or NULL on error. 55 FPDF_EXPORT FPDF_STRUCTELEMENT FPDF_CALLCONV 56 FPDF_StructTree_GetChildAtIndex(FPDF_STRUCTTREE struct_tree, int index); 57 58 // Function: FPDF_StructElement_GetAltText 59 // Get the alt text for a given element. 60 // Parameters: 61 // struct_element - Handle to the struct element. 62 // buffer - A buffer for output the alt text. May be NULL. 63 // buflen - The length of the buffer, in bytes. May be 0. 64 // Return value: 65 // The number of bytes in the alt text, including the terminating NUL 66 // character. The number of bytes is returned regardless of the 67 // |buffer| and |buflen| parameters. 68 // Comments: 69 // Regardless of the platform, the |buffer| is always in UTF-16LE 70 // encoding. The string is terminated by a UTF16 NUL character. If 71 // |buflen| is less than the required length, or |buffer| is NULL, 72 // |buffer| will not be modified. 73 FPDF_EXPORT unsigned long FPDF_CALLCONV 74 FPDF_StructElement_GetAltText(FPDF_STRUCTELEMENT struct_element, 75 void* buffer, 76 unsigned long buflen); 77 78 // Experimental API. 79 // Function: FPDF_StructElement_GetActualText 80 // Get the actual text for a given element. 81 // Parameters: 82 // struct_element - Handle to the struct element. 83 // buffer - A buffer for output the actual text. May be NULL. 84 // buflen - The length of the buffer, in bytes. May be 0. 85 // Return value: 86 // The number of bytes in the actual text, including the terminating 87 // NUL character. The number of bytes is returned regardless of the 88 // |buffer| and |buflen| parameters. 89 // Comments: 90 // Regardless of the platform, the |buffer| is always in UTF-16LE 91 // encoding. The string is terminated by a UTF16 NUL character. If 92 // |buflen| is less than the required length, or |buffer| is NULL, 93 // |buffer| will not be modified. 94 FPDF_EXPORT unsigned long FPDF_CALLCONV 95 FPDF_StructElement_GetActualText(FPDF_STRUCTELEMENT struct_element, 96 void* buffer, 97 unsigned long buflen); 98 99 // Function: FPDF_StructElement_GetID 100 // Get the ID for a given element. 101 // Parameters: 102 // struct_element - Handle to the struct element. 103 // buffer - A buffer for output the ID string. May be NULL. 104 // buflen - The length of the buffer, in bytes. May be 0. 105 // Return value: 106 // The number of bytes in the ID string, including the terminating NUL 107 // character. The number of bytes is returned regardless of the 108 // |buffer| and |buflen| parameters. 109 // Comments: 110 // Regardless of the platform, the |buffer| is always in UTF-16LE 111 // encoding. The string is terminated by a UTF16 NUL character. If 112 // |buflen| is less than the required length, or |buffer| is NULL, 113 // |buffer| will not be modified. 114 FPDF_EXPORT unsigned long FPDF_CALLCONV 115 FPDF_StructElement_GetID(FPDF_STRUCTELEMENT struct_element, 116 void* buffer, 117 unsigned long buflen); 118 119 // Experimental API. 120 // Function: FPDF_StructElement_GetLang 121 // Get the case-insensitive IETF BCP 47 language code for an element. 122 // Parameters: 123 // struct_element - Handle to the struct element. 124 // buffer - A buffer for output the lang string. May be NULL. 125 // buflen - The length of the buffer, in bytes. May be 0. 126 // Return value: 127 // The number of bytes in the ID string, including the terminating NUL 128 // character. The number of bytes is returned regardless of the 129 // |buffer| and |buflen| parameters. 130 // Comments: 131 // Regardless of the platform, the |buffer| is always in UTF-16LE 132 // encoding. The string is terminated by a UTF16 NUL character. If 133 // |buflen| is less than the required length, or |buffer| is NULL, 134 // |buffer| will not be modified. 135 FPDF_EXPORT unsigned long FPDF_CALLCONV 136 FPDF_StructElement_GetLang(FPDF_STRUCTELEMENT struct_element, 137 void* buffer, 138 unsigned long buflen); 139 140 // Experimental API. 141 // Function: FPDF_StructElement_GetStringAttribute 142 // Get a struct element attribute of type "name" or "string". 143 // Parameters: 144 // struct_element - Handle to the struct element. 145 // attr_name - The name of the attribute to retrieve. 146 // buffer - A buffer for output. May be NULL. 147 // buflen - The length of the buffer, in bytes. May be 0. 148 // Return value: 149 // The number of bytes in the attribute value, including the 150 // terminating NUL character. The number of bytes is returned 151 // regardless of the |buffer| and |buflen| parameters. 152 // Comments: 153 // Regardless of the platform, the |buffer| is always in UTF-16LE 154 // encoding. The string is terminated by a UTF16 NUL character. If 155 // |buflen| is less than the required length, or |buffer| is NULL, 156 // |buffer| will not be modified. 157 FPDF_EXPORT unsigned long FPDF_CALLCONV 158 FPDF_StructElement_GetStringAttribute(FPDF_STRUCTELEMENT struct_element, 159 FPDF_BYTESTRING attr_name, 160 void* buffer, 161 unsigned long buflen); 162 163 // Function: FPDF_StructElement_GetMarkedContentID 164 // Get the marked content ID for a given element. 165 // Parameters: 166 // struct_element - Handle to the struct element. 167 // Return value: 168 // The marked content ID of the element. If no ID exists, returns 169 // -1. 170 FPDF_EXPORT int FPDF_CALLCONV 171 FPDF_StructElement_GetMarkedContentID(FPDF_STRUCTELEMENT struct_element); 172 173 // Function: FPDF_StructElement_GetType 174 // Get the type (/S) for a given element. 175 // Parameters: 176 // struct_element - Handle to the struct element. 177 // buffer - A buffer for output. May be NULL. 178 // buflen - The length of the buffer, in bytes. May be 0. 179 // Return value: 180 // The number of bytes in the type, including the terminating NUL 181 // character. The number of bytes is returned regardless of the 182 // |buffer| and |buflen| parameters. 183 // Comments: 184 // Regardless of the platform, the |buffer| is always in UTF-16LE 185 // encoding. The string is terminated by a UTF16 NUL character. If 186 // |buflen| is less than the required length, or |buffer| is NULL, 187 // |buffer| will not be modified. 188 FPDF_EXPORT unsigned long FPDF_CALLCONV 189 FPDF_StructElement_GetType(FPDF_STRUCTELEMENT struct_element, 190 void* buffer, 191 unsigned long buflen); 192 193 // Experimental API. 194 // Function: FPDF_StructElement_GetObjType 195 // Get the object type (/Type) for a given element. 196 // Parameters: 197 // struct_element - Handle to the struct element. 198 // buffer - A buffer for output. May be NULL. 199 // buflen - The length of the buffer, in bytes. May be 0. 200 // Return value: 201 // The number of bytes in the object type, including the terminating 202 // NUL character. The number of bytes is returned regardless of the 203 // |buffer| and |buflen| parameters. 204 // Comments: 205 // Regardless of the platform, the |buffer| is always in UTF-16LE 206 // encoding. The string is terminated by a UTF16 NUL character. If 207 // |buflen| is less than the required length, or |buffer| is NULL, 208 // |buffer| will not be modified. 209 FPDF_EXPORT unsigned long FPDF_CALLCONV 210 FPDF_StructElement_GetObjType(FPDF_STRUCTELEMENT struct_element, 211 void* buffer, 212 unsigned long buflen); 213 214 // Function: FPDF_StructElement_GetTitle 215 // Get the title (/T) for a given element. 216 // Parameters: 217 // struct_element - Handle to the struct element. 218 // buffer - A buffer for output. May be NULL. 219 // buflen - The length of the buffer, in bytes. May be 0. 220 // Return value: 221 // The number of bytes in the title, including the terminating NUL 222 // character. The number of bytes is returned regardless of the 223 // |buffer| and |buflen| parameters. 224 // Comments: 225 // Regardless of the platform, the |buffer| is always in UTF-16LE 226 // encoding. The string is terminated by a UTF16 NUL character. If 227 // |buflen| is less than the required length, or |buffer| is NULL, 228 // |buffer| will not be modified. 229 FPDF_EXPORT unsigned long FPDF_CALLCONV 230 FPDF_StructElement_GetTitle(FPDF_STRUCTELEMENT struct_element, 231 void* buffer, 232 unsigned long buflen); 233 234 // Function: FPDF_StructElement_CountChildren 235 // Count the number of children for the structure element. 236 // Parameters: 237 // struct_element - Handle to the struct element. 238 // Return value: 239 // The number of children, or -1 on error. 240 FPDF_EXPORT int FPDF_CALLCONV 241 FPDF_StructElement_CountChildren(FPDF_STRUCTELEMENT struct_element); 242 243 // Function: FPDF_StructElement_GetChildAtIndex 244 // Get a child in the structure element. 245 // Parameters: 246 // struct_element - Handle to the struct element. 247 // index - The index for the child, 0-based. 248 // Return value: 249 // The child at the n-th index or NULL on error. 250 // Comments: 251 // If the child exists but is not an element, then this function will 252 // return NULL. This will also return NULL for out of bounds indices. 253 FPDF_EXPORT FPDF_STRUCTELEMENT FPDF_CALLCONV 254 FPDF_StructElement_GetChildAtIndex(FPDF_STRUCTELEMENT struct_element, 255 int index); 256 257 // Experimental API. 258 // Function: FPDF_StructElement_GetParent 259 // Get the parent of the structure element. 260 // Parameters: 261 // struct_element - Handle to the struct element. 262 // Return value: 263 // The parent structure element or NULL on error. 264 // Comments: 265 // If structure element is StructTreeRoot, then this function will 266 // return NULL. 267 FPDF_EXPORT FPDF_STRUCTELEMENT FPDF_CALLCONV 268 FPDF_StructElement_GetParent(FPDF_STRUCTELEMENT struct_element); 269 270 // Function: FPDF_StructElement_GetAttributeCount 271 // Count the number of attributes for the structure element. 272 // Parameters: 273 // struct_element - Handle to the struct element. 274 // Return value: 275 // The number of attributes, or -1 on error. 276 FPDF_EXPORT int FPDF_CALLCONV 277 FPDF_StructElement_GetAttributeCount(FPDF_STRUCTELEMENT struct_element); 278 279 // Experimental API. 280 // Function: FPDF_StructElement_GetAttributeAtIndex 281 // Get an attribute object in the structure element. 282 // Parameters: 283 // struct_element - Handle to the struct element. 284 // index - The index for the attribute object, 0-based. 285 // Return value: 286 // The attribute object at the n-th index or NULL on error. 287 // Comments: 288 // If the attribute object exists but is not a dict, then this 289 // function will return NULL. This will also return NULL for out of 290 // bounds indices. 291 FPDF_EXPORT FPDF_STRUCTELEMENT_ATTR FPDF_CALLCONV 292 FPDF_StructElement_GetAttributeAtIndex(FPDF_STRUCTELEMENT struct_element, int index); 293 294 // Experimental API. 295 // Function: FPDF_StructElement_Attr_GetCount 296 // Count the number of attributes in a structure element attribute map. 297 // Parameters: 298 // struct_attribute - Handle to the struct element attribute. 299 // Return value: 300 // The number of attributes, or -1 on error. 301 FPDF_EXPORT int FPDF_CALLCONV 302 FPDF_StructElement_Attr_GetCount(FPDF_STRUCTELEMENT_ATTR struct_attribute); 303 304 305 // Experimental API. 306 // Function: FPDF_StructElement_Attr_GetName 307 // Get the name of an attribute in a structure element attribute map. 308 // Parameters: 309 // struct_attribute - Handle to the struct element attribute. 310 // index - The index of attribute in the map. 311 // buffer - A buffer for output. May be NULL. This is only 312 // modified if |buflen| is longer than the length 313 // of the key. Optional, pass null to just 314 // retrieve the size of the buffer needed. 315 // buflen - The length of the buffer. 316 // out_buflen - A pointer to variable that will receive the 317 // minimum buffer size to contain the key. Not 318 // filled if FALSE is returned. 319 // Return value: 320 // TRUE if the operation was successful, FALSE otherwise. 321 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 322 FPDF_StructElement_Attr_GetName(FPDF_STRUCTELEMENT_ATTR struct_attribute, 323 int index, 324 void* buffer, 325 unsigned long buflen, 326 unsigned long* out_buflen); 327 328 // Experimental API. 329 // Function: FPDF_StructElement_Attr_GetType 330 // Get the type of an attribute in a structure element attribute map. 331 // Parameters: 332 // struct_attribute - Handle to the struct element attribute. 333 // name - The attribute name. 334 // Return value: 335 // Returns the type of the value, or FPDF_OBJECT_UNKNOWN in case of 336 // failure. 337 FPDF_EXPORT FPDF_OBJECT_TYPE FPDF_CALLCONV 338 FPDF_StructElement_Attr_GetType(FPDF_STRUCTELEMENT_ATTR struct_attribute, 339 FPDF_BYTESTRING name); 340 341 // Experimental API. 342 // Function: FPDF_StructElement_Attr_GetBooleanValue 343 // Get the value of a boolean attribute in an attribute map by name as 344 // FPDF_BOOL. FPDF_StructElement_Attr_GetType() should have returned 345 // FPDF_OBJECT_BOOLEAN for this property. 346 // Parameters: 347 // struct_attribute - Handle to the struct element attribute. 348 // name - The attribute name. 349 // out_value - A pointer to variable that will receive the 350 // value. Not filled if false is returned. 351 // Return value: 352 // Returns TRUE if the name maps to a boolean value, FALSE otherwise. 353 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 354 FPDF_StructElement_Attr_GetBooleanValue( 355 FPDF_STRUCTELEMENT_ATTR struct_attribute, 356 FPDF_BYTESTRING name, 357 FPDF_BOOL* out_value); 358 359 // Experimental API. 360 // Function: FPDF_StructElement_Attr_GetNumberValue 361 // Get the value of a number attribute in an attribute map by name as 362 // float. FPDF_StructElement_Attr_GetType() should have returned 363 // FPDF_OBJECT_NUMBER for this property. 364 // Parameters: 365 // struct_attribute - Handle to the struct element attribute. 366 // name - The attribute name. 367 // out_value - A pointer to variable that will receive the 368 // value. Not filled if false is returned. 369 // Return value: 370 // Returns TRUE if the name maps to a number value, FALSE otherwise. 371 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 372 FPDF_StructElement_Attr_GetNumberValue(FPDF_STRUCTELEMENT_ATTR struct_attribute, 373 FPDF_BYTESTRING name, 374 float* out_value); 375 376 // Experimental API. 377 // Function: FPDF_StructElement_Attr_GetStringValue 378 // Get the value of a string attribute in an attribute map by name as 379 // string. FPDF_StructElement_Attr_GetType() should have returned 380 // FPDF_OBJECT_STRING or FPDF_OBJECT_NAME for this property. 381 // Parameters: 382 // struct_attribute - Handle to the struct element attribute. 383 // name - The attribute name. 384 // buffer - A buffer for holding the returned key in 385 // UTF-16LE. This is only modified if |buflen| is 386 // longer than the length of the key. Optional, 387 // pass null to just retrieve the size of the 388 // buffer needed. 389 // buflen - The length of the buffer. 390 // out_buflen - A pointer to variable that will receive the 391 // minimum buffer size to contain the key. Not 392 // filled if FALSE is returned. 393 // Return value: 394 // Returns TRUE if the name maps to a string value, FALSE otherwise. 395 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 396 FPDF_StructElement_Attr_GetStringValue(FPDF_STRUCTELEMENT_ATTR struct_attribute, 397 FPDF_BYTESTRING name, 398 void* buffer, 399 unsigned long buflen, 400 unsigned long* out_buflen); 401 402 // Experimental API. 403 // Function: FPDF_StructElement_Attr_GetBlobValue 404 // Get the value of a blob attribute in an attribute map by name as 405 // string. 406 // Parameters: 407 // struct_attribute - Handle to the struct element attribute. 408 // name - The attribute name. 409 // buffer - A buffer for holding the returned value. This 410 // is only modified if |buflen| is at least as 411 // long as the length of the value. Optional, pass 412 // null to just retrieve the size of the buffer 413 // needed. 414 // buflen - The length of the buffer. 415 // out_buflen - A pointer to variable that will receive the 416 // minimum buffer size to contain the key. Not 417 // filled if FALSE is returned. 418 // Return value: 419 // Returns TRUE if the name maps to a string value, FALSE otherwise. 420 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 421 FPDF_StructElement_Attr_GetBlobValue(FPDF_STRUCTELEMENT_ATTR struct_attribute, 422 FPDF_BYTESTRING name, 423 void* buffer, 424 unsigned long buflen, 425 unsigned long* out_buflen); 426 427 // Experimental API. 428 // Function: FPDF_StructElement_GetMarkedContentIdCount 429 // Get the count of marked content ids for a given element. 430 // Parameters: 431 // struct_element - Handle to the struct element. 432 // Return value: 433 // The count of marked content ids or -1 if none exists. 434 FPDF_EXPORT int FPDF_CALLCONV 435 FPDF_StructElement_GetMarkedContentIdCount(FPDF_STRUCTELEMENT struct_element); 436 437 // Experimental API. 438 // Function: FPDF_StructElement_GetMarkedContentIdAtIndex 439 // Get the marked content id at a given index for a given element. 440 // Parameters: 441 // struct_element - Handle to the struct element. 442 // index - The index of the marked content id, 0-based. 443 // Return value: 444 // The marked content ID of the element. If no ID exists, returns 445 // -1. 446 FPDF_EXPORT int FPDF_CALLCONV 447 FPDF_StructElement_GetMarkedContentIdAtIndex(FPDF_STRUCTELEMENT struct_element, 448 int index); 449 450 #ifdef __cplusplus 451 } // extern "C" 452 #endif 453 454 #endif // PUBLIC_FPDF_STRUCTTREE_H_ 455