blob: a6c158a513488c3a482f18bc04d26ced89e86b02 [file] [log] [blame]
// 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.
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.
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.
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.
FPDF_EXPORT FPDF_STRUCTELEMENT FPDF_CALLCONV
FPDF_StructElement_GetChildAtIndex(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.
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_GetType
// Get the type of an attribute in a structure element attribute map.
// Parameters:
// struct_attribute - Handle to the struct element attribute.
// name - The attribute name.
// Return value:
// Returns the type of the value, or FPDF_OBJECT_UNKNOWN in case of
// failure.
FPDF_EXPORT FPDF_OBJECT_TYPE FPDF_CALLCONV
FPDF_StructElement_Attr_GetType(FPDF_STRUCTELEMENT_ATTR struct_attribute,
FPDF_BYTESTRING name);
// Experimental API.
// Function: FPDF_StructElement_Attr_GetBooleanValue
// Get the value of a boolean attribute in an attribute map by name as
// FPDF_BOOL. FPDF_StructElement_Attr_GetType() should have returned
// FPDF_OBJECT_BOOLEAN for this property.
// Parameters:
// struct_attribute - Handle to the struct element attribute.
// name - The attribute name.
// out_value - A pointer to variable that will receive the
// value. Not filled if false is returned.
// Return value:
// Returns TRUE if the name maps to a boolean value, FALSE otherwise.
FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV
FPDF_StructElement_Attr_GetBooleanValue(
FPDF_STRUCTELEMENT_ATTR struct_attribute,
FPDF_BYTESTRING name,
FPDF_BOOL* out_value);
// Experimental API.
// Function: FPDF_StructElement_Attr_GetNumberValue
// Get the value of a number attribute in an attribute map by name as
// float. FPDF_StructElement_Attr_GetType() should have returned
// FPDF_OBJECT_NUMBER for this property.
// Parameters:
// struct_attribute - Handle to the struct element attribute.
// name - The attribute name.
// out_value - A pointer to variable that will receive the
// value. Not filled if false is returned.
// Return value:
// Returns TRUE if the name maps to a number value, FALSE otherwise.
FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV
FPDF_StructElement_Attr_GetNumberValue(FPDF_STRUCTELEMENT_ATTR struct_attribute,
FPDF_BYTESTRING name,
float* out_value);
// Experimental API.
// Function: FPDF_StructElement_Attr_GetStringValue
// Get the value of a string attribute in an attribute map by name as
// string. FPDF_StructElement_Attr_GetType() should have returned
// FPDF_OBJECT_STRING or FPDF_OBJECT_NAME for this property.
// Parameters:
// struct_attribute - Handle to the struct element attribute.
// name - The attribute name.
// 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 name maps to a string value, FALSE otherwise.
FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV
FPDF_StructElement_Attr_GetStringValue(FPDF_STRUCTELEMENT_ATTR struct_attribute,
FPDF_BYTESTRING name,
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 by name as
// string.
// Parameters:
// struct_attribute - Handle to the struct element attribute.
// name - The attribute name.
// 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 name maps to a string value, FALSE otherwise.
FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV
FPDF_StructElement_Attr_GetBlobValue(FPDF_STRUCTELEMENT_ATTR struct_attribute,
FPDF_BYTESTRING name,
void* buffer,
unsigned long buflen,
unsigned long* out_buflen);
// 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.
FPDF_EXPORT int FPDF_CALLCONV
FPDF_StructElement_GetMarkedContentIdAtIndex(FPDF_STRUCTELEMENT struct_element,
int index);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // PUBLIC_FPDF_STRUCTTREE_H_