// 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_
Codebase Browser
chromium