pdfium/public/fpdf_structtree.h

// 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_