mirror/yacreader
1
0
Fork 0
mirror of https://github.com/YACReader/yacreader synced 2025-05-28 03:10:27 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity
442307cc65
yacreader/dependencies/pdfium/win/public/fpdf_structtree.h
Luis Ángel San Martín 442307cc65 Update pdfium for windows
2024-10-12 10:15:43 +02:00

525 lines
24 KiB
C
Raw Blame History

// 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_
Reference in New Issue View Git Blame Copy Permalink