| // Copyright 2016 The PDFium Authors |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| // Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com |
| |
| #ifndef PUBLIC_FPDF_STRUCTTREE_H_ |
| #define PUBLIC_FPDF_STRUCTTREE_H_ |
| |
| // clang-format off |
| // NOLINTNEXTLINE(build/include) |
| #include "fpdfview.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| // Function: FPDF_StructTree_GetForPage |
| // Get the structure tree for a page. |
| // Parameters: |
| // page - Handle to the page, as returned by FPDF_LoadPage(). |
| // Return value: |
| // A handle to the structure tree or NULL on error. The caller owns the |
| // returned handle and must use FPDF_StructTree_Close() to release it. |
| // The handle should be released before |page| gets released. |
| FPDF_EXPORT FPDF_STRUCTTREE FPDF_CALLCONV |
| FPDF_StructTree_GetForPage(FPDF_PAGE page); |
| |
| // Function: FPDF_StructTree_Close |
| // Release a resource allocated by FPDF_StructTree_GetForPage(). |
| // Parameters: |
| // struct_tree - Handle to the structure tree, as returned by |
| // FPDF_StructTree_LoadPage(). |
| // Return value: |
| // None. |
| FPDF_EXPORT void FPDF_CALLCONV |
| FPDF_StructTree_Close(FPDF_STRUCTTREE struct_tree); |
| |
| // Function: FPDF_StructTree_CountChildren |
| // Count the number of children for the structure tree. |
| // Parameters: |
| // struct_tree - Handle to the structure tree, as returned by |
| // FPDF_StructTree_LoadPage(). |
| // Return value: |
| // The number of children, or -1 on error. |
| FPDF_EXPORT int FPDF_CALLCONV |
| FPDF_StructTree_CountChildren(FPDF_STRUCTTREE struct_tree); |
| |
| // Function: FPDF_StructTree_GetChildAtIndex |
| // Get a child in the structure tree. |
| // Parameters: |
| // struct_tree - Handle to the structure tree, as returned by |
| // FPDF_StructTree_LoadPage(). |
| // index - The index for the child, 0-based. |
| // Return value: |
| // The child at the n-th index or NULL on error. The caller does not |
| // own the handle. The handle remains valid as long as |struct_tree| |
| // remains valid. |
| // Comments: |
| // The |index| must be less than the FPDF_StructTree_CountChildren() |
| // return value. |
| FPDF_EXPORT FPDF_STRUCTELEMENT FPDF_CALLCONV |
| FPDF_StructTree_GetChildAtIndex(FPDF_STRUCTTREE struct_tree, int index); |
| |
| // Function: FPDF_StructElement_GetAltText |
| // Get the alt text for a given element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // buffer - A buffer for output the alt text. May be NULL. |
| // buflen - The length of the buffer, in bytes. May be 0. |
| // Return value: |
| // The number of bytes in the alt text, including the terminating NUL |
| // character. The number of bytes is returned regardless of the |
| // |buffer| and |buflen| parameters. |
| // Comments: |
| // Regardless of the platform, the |buffer| is always in UTF-16LE |
| // encoding. The string is terminated by a UTF16 NUL character. If |
| // |buflen| is less than the required length, or |buffer| is NULL, |
| // |buffer| will not be modified. |
| FPDF_EXPORT unsigned long FPDF_CALLCONV |
| FPDF_StructElement_GetAltText(FPDF_STRUCTELEMENT struct_element, |
| void* buffer, |
| unsigned long buflen); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_GetActualText |
| // Get the actual text for a given element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // buffer - A buffer for output the actual text. May be NULL. |
| // buflen - The length of the buffer, in bytes. May be 0. |
| // Return value: |
| // The number of bytes in the actual text, including the terminating |
| // NUL character. The number of bytes is returned regardless of the |
| // |buffer| and |buflen| parameters. |
| // Comments: |
| // Regardless of the platform, the |buffer| is always in UTF-16LE |
| // encoding. The string is terminated by a UTF16 NUL character. If |
| // |buflen| is less than the required length, or |buffer| is NULL, |
| // |buffer| will not be modified. |
| FPDF_EXPORT unsigned long FPDF_CALLCONV |
| FPDF_StructElement_GetActualText(FPDF_STRUCTELEMENT struct_element, |
| void* buffer, |
| unsigned long buflen); |
| |
| // Function: FPDF_StructElement_GetID |
| // Get the ID for a given element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // buffer - A buffer for output the ID string. May be NULL. |
| // buflen - The length of the buffer, in bytes. May be 0. |
| // Return value: |
| // The number of bytes in the ID string, including the terminating NUL |
| // character. The number of bytes is returned regardless of the |
| // |buffer| and |buflen| parameters. |
| // Comments: |
| // Regardless of the platform, the |buffer| is always in UTF-16LE |
| // encoding. The string is terminated by a UTF16 NUL character. If |
| // |buflen| is less than the required length, or |buffer| is NULL, |
| // |buffer| will not be modified. |
| FPDF_EXPORT unsigned long FPDF_CALLCONV |
| FPDF_StructElement_GetID(FPDF_STRUCTELEMENT struct_element, |
| void* buffer, |
| unsigned long buflen); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_GetLang |
| // Get the case-insensitive IETF BCP 47 language code for an element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // buffer - A buffer for output the lang string. May be NULL. |
| // buflen - The length of the buffer, in bytes. May be 0. |
| // Return value: |
| // The number of bytes in the ID string, including the terminating NUL |
| // character. The number of bytes is returned regardless of the |
| // |buffer| and |buflen| parameters. |
| // Comments: |
| // Regardless of the platform, the |buffer| is always in UTF-16LE |
| // encoding. The string is terminated by a UTF16 NUL character. If |
| // |buflen| is less than the required length, or |buffer| is NULL, |
| // |buffer| will not be modified. |
| FPDF_EXPORT unsigned long FPDF_CALLCONV |
| FPDF_StructElement_GetLang(FPDF_STRUCTELEMENT struct_element, |
| void* buffer, |
| unsigned long buflen); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_GetStringAttribute |
| // Get a struct element attribute of type "name" or "string". |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // attr_name - The name of the attribute to retrieve. |
| // buffer - A buffer for output. May be NULL. |
| // buflen - The length of the buffer, in bytes. May be 0. |
| // Return value: |
| // The number of bytes in the attribute value, including the |
| // terminating NUL character. The number of bytes is returned |
| // regardless of the |buffer| and |buflen| parameters. |
| // Comments: |
| // Regardless of the platform, the |buffer| is always in UTF-16LE |
| // encoding. The string is terminated by a UTF16 NUL character. If |
| // |buflen| is less than the required length, or |buffer| is NULL, |
| // |buffer| will not be modified. |
| FPDF_EXPORT unsigned long FPDF_CALLCONV |
| FPDF_StructElement_GetStringAttribute(FPDF_STRUCTELEMENT struct_element, |
| FPDF_BYTESTRING attr_name, |
| void* buffer, |
| unsigned long buflen); |
| |
| // Function: FPDF_StructElement_GetMarkedContentID |
| // Get the marked content ID for a given element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // Return value: |
| // The marked content ID of the element. If no ID exists, returns |
| // -1. |
| // Comments: |
| // FPDF_StructElement_GetMarkedContentIdAtIndex() may be able to |
| // extract more marked content IDs out of |struct_element|. This API |
| // may be deprecated in the future. |
| FPDF_EXPORT int FPDF_CALLCONV |
| FPDF_StructElement_GetMarkedContentID(FPDF_STRUCTELEMENT struct_element); |
| |
| // Function: FPDF_StructElement_GetType |
| // Get the type (/S) for a given element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // buffer - A buffer for output. May be NULL. |
| // buflen - The length of the buffer, in bytes. May be 0. |
| // Return value: |
| // The number of bytes in the type, including the terminating NUL |
| // character. The number of bytes is returned regardless of the |
| // |buffer| and |buflen| parameters. |
| // Comments: |
| // Regardless of the platform, the |buffer| is always in UTF-16LE |
| // encoding. The string is terminated by a UTF16 NUL character. If |
| // |buflen| is less than the required length, or |buffer| is NULL, |
| // |buffer| will not be modified. |
| FPDF_EXPORT unsigned long FPDF_CALLCONV |
| FPDF_StructElement_GetType(FPDF_STRUCTELEMENT struct_element, |
| void* buffer, |
| unsigned long buflen); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_GetObjType |
| // Get the object type (/Type) for a given element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // buffer - A buffer for output. May be NULL. |
| // buflen - The length of the buffer, in bytes. May be 0. |
| // Return value: |
| // The number of bytes in the object type, including the terminating |
| // NUL character. The number of bytes is returned regardless of the |
| // |buffer| and |buflen| parameters. |
| // Comments: |
| // Regardless of the platform, the |buffer| is always in UTF-16LE |
| // encoding. The string is terminated by a UTF16 NUL character. If |
| // |buflen| is less than the required length, or |buffer| is NULL, |
| // |buffer| will not be modified. |
| FPDF_EXPORT unsigned long FPDF_CALLCONV |
| FPDF_StructElement_GetObjType(FPDF_STRUCTELEMENT struct_element, |
| void* buffer, |
| unsigned long buflen); |
| |
| // Function: FPDF_StructElement_GetTitle |
| // Get the title (/T) for a given element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // buffer - A buffer for output. May be NULL. |
| // buflen - The length of the buffer, in bytes. May be 0. |
| // Return value: |
| // The number of bytes in the title, including the terminating NUL |
| // character. The number of bytes is returned regardless of the |
| // |buffer| and |buflen| parameters. |
| // Comments: |
| // Regardless of the platform, the |buffer| is always in UTF-16LE |
| // encoding. The string is terminated by a UTF16 NUL character. If |
| // |buflen| is less than the required length, or |buffer| is NULL, |
| // |buffer| will not be modified. |
| FPDF_EXPORT unsigned long FPDF_CALLCONV |
| FPDF_StructElement_GetTitle(FPDF_STRUCTELEMENT struct_element, |
| void* buffer, |
| unsigned long buflen); |
| |
| // Function: FPDF_StructElement_CountChildren |
| // Count the number of children for the structure element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // Return value: |
| // The number of children, or -1 on error. |
| FPDF_EXPORT int FPDF_CALLCONV |
| FPDF_StructElement_CountChildren(FPDF_STRUCTELEMENT struct_element); |
| |
| // Function: FPDF_StructElement_GetChildAtIndex |
| // Get a child in the structure element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // index - The index for the child, 0-based. |
| // Return value: |
| // The child at the n-th index or NULL on error. |
| // Comments: |
| // If the child exists but is not an element, then this function will |
| // return NULL. This will also return NULL for out of bounds indices. |
| // The |index| must be less than the FPDF_StructElement_CountChildren() |
| // return value. |
| FPDF_EXPORT FPDF_STRUCTELEMENT FPDF_CALLCONV |
| FPDF_StructElement_GetChildAtIndex(FPDF_STRUCTELEMENT struct_element, |
| int index); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_GetChildMarkedContentID |
| // Get the child's content id |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // index - The index for the child, 0-based. |
| // Return value: |
| // The marked content ID of the child. If no ID exists, returns -1. |
| // Comments: |
| // If the child exists but is not a stream or object, then this |
| // function will return -1. This will also return -1 for out of bounds |
| // indices. Compared to FPDF_StructElement_GetMarkedContentIdAtIndex, |
| // it is scoped to the current page. |
| // The |index| must be less than the FPDF_StructElement_CountChildren() |
| // return value. |
| FPDF_EXPORT int FPDF_CALLCONV |
| FPDF_StructElement_GetChildMarkedContentID(FPDF_STRUCTELEMENT struct_element, |
| int index); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_GetParent |
| // Get the parent of the structure element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // Return value: |
| // The parent structure element or NULL on error. |
| // Comments: |
| // If structure element is StructTreeRoot, then this function will |
| // return NULL. |
| FPDF_EXPORT FPDF_STRUCTELEMENT FPDF_CALLCONV |
| FPDF_StructElement_GetParent(FPDF_STRUCTELEMENT struct_element); |
| |
| // Function: FPDF_StructElement_GetAttributeCount |
| // Count the number of attributes for the structure element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // Return value: |
| // The number of attributes, or -1 on error. |
| FPDF_EXPORT int FPDF_CALLCONV |
| FPDF_StructElement_GetAttributeCount(FPDF_STRUCTELEMENT struct_element); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_GetAttributeAtIndex |
| // Get an attribute object in the structure element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // index - The index for the attribute object, 0-based. |
| // Return value: |
| // The attribute object at the n-th index or NULL on error. |
| // Comments: |
| // If the attribute object exists but is not a dict, then this |
| // function will return NULL. This will also return NULL for out of |
| // bounds indices. The caller does not own the handle. The handle |
| // remains valid as long as |struct_element| remains valid. |
| // The |index| must be less than the |
| // FPDF_StructElement_GetAttributeCount() return value. |
| FPDF_EXPORT FPDF_STRUCTELEMENT_ATTR FPDF_CALLCONV |
| FPDF_StructElement_GetAttributeAtIndex(FPDF_STRUCTELEMENT struct_element, int index); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_GetCount |
| // Count the number of attributes in a structure element attribute map. |
| // Parameters: |
| // struct_attribute - Handle to the struct element attribute. |
| // Return value: |
| // The number of attributes, or -1 on error. |
| FPDF_EXPORT int FPDF_CALLCONV |
| FPDF_StructElement_Attr_GetCount(FPDF_STRUCTELEMENT_ATTR struct_attribute); |
| |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_GetName |
| // Get the name of an attribute in a structure element attribute map. |
| // Parameters: |
| // struct_attribute - Handle to the struct element attribute. |
| // index - The index of attribute in the map. |
| // buffer - A buffer for output. May be NULL. This is only |
| // modified if |buflen| is longer than the length |
| // of the key. Optional, pass null to just |
| // retrieve the size of the buffer needed. |
| // buflen - The length of the buffer. |
| // out_buflen - A pointer to variable that will receive the |
| // minimum buffer size to contain the key. Not |
| // filled if FALSE is returned. |
| // Return value: |
| // TRUE if the operation was successful, FALSE otherwise. |
| FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV |
| FPDF_StructElement_Attr_GetName(FPDF_STRUCTELEMENT_ATTR struct_attribute, |
| int index, |
| void* buffer, |
| unsigned long buflen, |
| unsigned long* out_buflen); |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_GetValue |
| // Get a handle to a value for an attribute in a structure element |
| // attribute map. |
| // Parameters: |
| // struct_attribute - Handle to the struct element attribute. |
| // name - The attribute name. |
| // Return value: |
| // Returns a handle to the value associated with the input, if any. |
| // Returns NULL on failure. The caller does not own the handle. |
| // The handle remains valid as long as |struct_attribute| remains |
| // valid. |
| FPDF_EXPORT FPDF_STRUCTELEMENT_ATTR_VALUE FPDF_CALLCONV |
| FPDF_StructElement_Attr_GetValue(FPDF_STRUCTELEMENT_ATTR struct_attribute, |
| FPDF_BYTESTRING name); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_GetType |
| // Get the type of an attribute in a structure element attribute map. |
| // Parameters: |
| // value - Handle to the value. |
| // Return value: |
| // Returns the type of the value, or FPDF_OBJECT_UNKNOWN in case of |
| // failure. Note that this will never return FPDF_OBJECT_REFERENCE, as |
| // references are always dereferenced. |
| FPDF_EXPORT FPDF_OBJECT_TYPE FPDF_CALLCONV |
| FPDF_StructElement_Attr_GetType(FPDF_STRUCTELEMENT_ATTR_VALUE value); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_GetBooleanValue |
| // Get the value of a boolean attribute in an attribute map as |
| // FPDF_BOOL. FPDF_StructElement_Attr_GetType() should have returned |
| // FPDF_OBJECT_BOOLEAN for this property. |
| // Parameters: |
| // value - Handle to the value. |
| // out_value - A pointer to variable that will receive the value. Not |
| // filled if false is returned. |
| // Return value: |
| // Returns TRUE if the attribute maps to a boolean value, FALSE |
| // otherwise. |
| FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV |
| FPDF_StructElement_Attr_GetBooleanValue(FPDF_STRUCTELEMENT_ATTR_VALUE value, |
| FPDF_BOOL* out_value); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_GetNumberValue |
| // Get the value of a number attribute in an attribute map as float. |
| // FPDF_StructElement_Attr_GetType() should have returned |
| // FPDF_OBJECT_NUMBER for this property. |
| // Parameters: |
| // value - Handle to the value. |
| // out_value - A pointer to variable that will receive the value. Not |
| // filled if false is returned. |
| // Return value: |
| // Returns TRUE if the attribute maps to a number value, FALSE |
| // otherwise. |
| FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV |
| FPDF_StructElement_Attr_GetNumberValue(FPDF_STRUCTELEMENT_ATTR_VALUE value, |
| float* out_value); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_GetStringValue |
| // Get the value of a string attribute in an attribute map as string. |
| // FPDF_StructElement_Attr_GetType() should have returned |
| // FPDF_OBJECT_STRING or FPDF_OBJECT_NAME for this property. |
| // Parameters: |
| // value - Handle to the value. |
| // buffer - A buffer for holding the returned key in UTF-16LE. |
| // This is only modified if |buflen| is longer than the |
| // length of the key. Optional, pass null to just |
| // retrieve the size of the buffer needed. |
| // buflen - The length of the buffer. |
| // out_buflen - A pointer to variable that will receive the minimum |
| // buffer size to contain the key. Not filled if FALSE is |
| // returned. |
| // Return value: |
| // Returns TRUE if the attribute maps to a string value, FALSE |
| // otherwise. |
| FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV |
| FPDF_StructElement_Attr_GetStringValue(FPDF_STRUCTELEMENT_ATTR_VALUE value, |
| void* buffer, |
| unsigned long buflen, |
| unsigned long* out_buflen); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_GetBlobValue |
| // Get the value of a blob attribute in an attribute map as string. |
| // Parameters: |
| // value - Handle to the value. |
| // buffer - A buffer for holding the returned value. This is only |
| // modified if |buflen| is at least as long as the length |
| // of the value. Optional, pass null to just retrieve the |
| // size of the buffer needed. |
| // buflen - The length of the buffer. |
| // out_buflen - A pointer to variable that will receive the minimum |
| // buffer size to contain the key. Not filled if FALSE is |
| // returned. |
| // Return value: |
| // Returns TRUE if the attribute maps to a string value, FALSE |
| // otherwise. |
| FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV |
| FPDF_StructElement_Attr_GetBlobValue(FPDF_STRUCTELEMENT_ATTR_VALUE value, |
| void* buffer, |
| unsigned long buflen, |
| unsigned long* out_buflen); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_CountChildren |
| // Count the number of children values in an attribute. |
| // Parameters: |
| // value - Handle to the value. |
| // Return value: |
| // The number of children, or -1 on error. |
| FPDF_EXPORT int FPDF_CALLCONV |
| FPDF_StructElement_Attr_CountChildren(FPDF_STRUCTELEMENT_ATTR_VALUE value); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_Attr_GetChildAtIndex |
| // Get a child from an attribute. |
| // Parameters: |
| // value - Handle to the value. |
| // index - The index for the child, 0-based. |
| // Return value: |
| // The child at the n-th index or NULL on error. |
| // Comments: |
| // The |index| must be less than the |
| // FPDF_StructElement_Attr_CountChildren() return value. |
| FPDF_EXPORT FPDF_STRUCTELEMENT_ATTR_VALUE FPDF_CALLCONV |
| FPDF_StructElement_Attr_GetChildAtIndex(FPDF_STRUCTELEMENT_ATTR_VALUE value, |
| int index); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_GetMarkedContentIdCount |
| // Get the count of marked content ids for a given element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // Return value: |
| // The count of marked content ids or -1 if none exists. |
| FPDF_EXPORT int FPDF_CALLCONV |
| FPDF_StructElement_GetMarkedContentIdCount(FPDF_STRUCTELEMENT struct_element); |
| |
| // Experimental API. |
| // Function: FPDF_StructElement_GetMarkedContentIdAtIndex |
| // Get the marked content id at a given index for a given element. |
| // Parameters: |
| // struct_element - Handle to the struct element. |
| // index - The index of the marked content id, 0-based. |
| // Return value: |
| // The marked content ID of the element. If no ID exists, returns |
| // -1. |
| // Comments: |
| // The |index| must be less than the |
| // FPDF_StructElement_GetMarkedContentIdCount() return value. |
| // This will likely supersede FPDF_StructElement_GetMarkedContentID(). |
| FPDF_EXPORT int FPDF_CALLCONV |
| FPDF_StructElement_GetMarkedContentIdAtIndex(FPDF_STRUCTELEMENT struct_element, |
| int index); |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif // PUBLIC_FPDF_STRUCTTREE_H_ |