Академический Документы
Профессиональный Документы
Культура Документы
Table of Contents
1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Base Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.2 Error Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.2.1 Status types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.2.2 Error Reporting procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2.3 Debugging procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3 Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4 Basic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4.1 Boolean Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4.2 Numeric Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4.3 Big Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4.4 Memory Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.4.5 Progress Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.4.6 Universal Unique Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.5 Hash Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.5.1 Hash Table Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.5.2 Creating and Destroying Hash Tables . . . . . . . . . . . . . . . . . . . . . 28
2.5.3 Hash Table properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.5.4 Working with keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.5.5 Adding and removing elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.5.6 Searching elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.5.7 Working with iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.5.8 Basic dispose functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.5.9 Hash helper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.6 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
2.6.1 List Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
2.6.2 Creating and Destroying Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
2.6.3 Managing List Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
2.6.4 Searching for List Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
2.6.5 Setting and Getting List Elements . . . . . . . . . . . . . . . . . . . . . . . . 56
2.6.6 Adding and Removing List Elements . . . . . . . . . . . . . . . . . . . . . 59
2.6.7 Working with sorted lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
2.6.8 Working with Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
2.7 Filtered Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
2.7.1 Stream Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
2.7.2 Creating and Destroying Streams . . . . . . . . . . . . . . . . . . . . . . . . . 69
2.7.3 Getting and Setting Stream Properties . . . . . . . . . . . . . . . . . . . 70
2.7.4 Managing the Filter Chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
2.7.5 Reading and Writing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
2.7.6 Stream Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
2.8 Floating Point Maths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
ii
1 Overview
Chapter 2: Base Layer 2
2 Base Layer
2.1 Overview
The base layer of the GNU PDF Library provides system-independent access to several
facilities.
The implemented facilities are organized into modules. Each module exports an API to
be used by the client application or other layers of the library. Some modules make use of
the facilities implemented in other modules (such as allocation or error functions).
The following constants define the valid values to be held in a pdf_status_t variable:
PDF_OK [Constant]
Success
PDF_ERROR [Constant]
A serious error
PDF_EBADDATA [Constant]
Invalid or bad arguments
PDF_ENOMEM [Constant]
Insufficient memory
PDF_EEOF [Constant]
End of file
PDF_EDIVBYZERO [Constant]
Divison by zero
PDF_ENONODE [Constant]
No node found
PDF_EINVRANGE [Constant]
Invalid range
PDF_ETEXTENC [Constant]
Error in text encoding
Chapter 2: Base Layer 3
PDF_ENOMATCH [Constant]
No matching found
if (st != PDF_OK)
{
pdf_perror (st, "Couldn’t do i64 addition");
}
void pdf_error (const pdf status t status, FILE *fd, const char [Function]
*format, ... )
Prints a message with ‘fprintf (fd, format, ...)’; if status is nonzero, also prints the
corresponding message.
Parameters
status status code
fd file descriptor open for writing
format string format for the message
... format’s arguments
Returns nothing
Usage example
pdf_status_t st;
if (st != PDF_OK)
{
pdf_error (st, logfd, "couldn’t do i64 addition");
}
Chapter 2: Base Layer 4
Output format
The output format for these macros is,
GNU PDF:***DEBUG <layer>***:<file-name>:<line-number>: <message>.
For example,
GNU PDF:***DEBUG BASE***:pdf-fp-func.c:344: division by zero.
void* pdf_realloc (const void *pointer, const pdf size t size ) [Function]
Reallocates memory.
Parameters
pointer A pointer to previously allocated memory.
The memory to reallocate should have been allocated using
pdf_alloc or pdf_realloc.
size The new size of the allocated memory chunk.
If the requested size is shorter than the original size of the
allocated memory then it is truncated. Any previous contents
in the memory will be lost.
If the requested size is larger or equal than the original size
of the allocated memory then the previous contents of the
allocated memory remains. The contents of newly allocated
memory are undetermined.
If there is not enough available memory to satisfy the request,
then a fatal error is signaled killing the current process. An
error status is returned to the operating system.
Returns A pointer to the reallocated memory.
Usage Example
char *p;
Chapter 2: Base Layer 6
pdf_dealloc (p);
The following constants define the valid values to be held in a pdf_bool_t variable:
PDF_TRUE [Constant]
Logical true.
PDF_FALSE [Constant]
Logical false.
The following constants specify the valid ranges for these data types:
PDF_I32_MAX [Constant]
Maximum value able to be stored in a pdf_i32_t variable.
PDF_I32_MIN [Constant]
Minimum value able to be stored in a pdf_i32_t variable.
PDF_U32_MAX [Constant]
Maximum value able to be stored in a pdf_u32_t variable.
Chapter 2: Base Layer 7
PDF_U32_MIN [Constant]
Minimum value able to be stored in a pdf_u32_t variable.
pdf_i64_t pdf_i64_new (const pdf i32 t high, const pdf u32 t low ) [Function]
Create a new i64 variable from one 32 bit signed integer and a 32 bit unsigned integer.
Parameters
high The high (signed) part of the 64 bit integer.
low The low (unsigned) part of the 64 bit integer.
Returns The newly created i64 object.
Usage example
pdf_i64_t bignum;
void pdf_i64_assign (pdf i64 t *bignum, const pdf i32 t high, const [Function]
pdf u32 t low, pdf status t *p_status )
Assign a value based on a 32 bit signed integer and a 32 bit unsigned integer to a 64
bit integer.
Parameters
bignum Variable that stores a 64 bit integer
high The high (signed) part of the 64 bit integer.
low The low (unsigned) part of the 64 bit integer.
p status Pointer to a pdf status t variable to hold the status of the
operation. If it is NULL then this parameter is ignored.
Returns A pdf status value:
PDF_OK Operation successful
PDF_EBADDATA
NULL value in bignum.
Usage example
pdf_i64_t *bignum;
pdf_i64_t result;
pdf_status_t *p_status;
result = pdf_i64_new(0, 0);
bignum = &result;
Chapter 2: Base Layer 8
PDF_EBADDATA
NULL value in bignum.
Usage example
pdf_i64_t orig;
pdf_i64_t *copy;
pdf_status_t *p_status;
orig = pdf_i64_new(0, 10);
pdf_i64_copy(orig, copy, p_status)
if ( *p_status != PDF_OK) /*Now copy is also 10*/
{
/* Error code */
}
void pdf_i64_add (pdf i64 t *dest, const pdf i64 t addend1, const [Function]
pdf i64 t addend2, pdf status t *p_status )
Adds two 64 bit numbers
Parameters
addend1 First addend of the sum
addend2 Second addend of the sum
dest Where 64 bit result is stored
p status Pointer to a pdf status t variable to hold the status of the
operation. If it is NULL then this parameter is ignored.
Returns A pdf status value:
PDF_OK Operation successful
PDF_EBADDATA
NULL value in bignum.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t addend_1;
pdf_i64_t addend_2;
pdf_status_t *p_status;
addend_1 = pdf_i64_new(0, 25);
addend_2 = pdf_i64_new(0, 35);
result = pdf_i64_new(0, 0);
dest = &result;
pdf_i64_add (dest, addend_1, addend_2, &p_status);
if (*p_status != PDF_OK) /* Now dest is 60 */
{
/* Error code */
}
void pdf_i64_add_i32 (pdf i64 t *dest, const pdf i64 t addend1, [Function]
const pdf i32 t addend2, pdf status t *p_status )
Adds a 64bit number and a 32bit number.
Chapter 2: Base Layer 10
Parameters
addend1 First addend of the sum (64bit type)
addend2 Second addend of the sum (32 bit)
dest Where 64 bit result is stored
p status Pointer to a pdf status t variable to hold the status of the
operation. If it is NULL then this parameter is ignored.
Returns A pdf status value:
PDF_OK Operation successful
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t addend_1;
pdf_status_t *p_status;
addend_1 = pdf_i64_new(0, 25);
result = pdf_i64_new(0, 0);
dest = &result;
pdf_i64_add (dest, addend_1, 35,p_status)
if (*p_status != PDF_OK) /* Now dest is 60 */
{
/* Error code */
}
pdf_i64_t result;
pdf_i64_t minuend;
pdf_i64_t subtrahend;
pdf_status_t *p_status;
minuend = pdf_i64_new(0, 25);
subtrahend = pdf_i64_new(0, 35);
result = pdf_i64_new(0, 0);
dest = &result;
pdf_i64_subtraction (dest, minuend, subtrahend,p_status)
if (*p_status != PDF_OK) /* Now dest is -10 */
{
/* Error code */
}
void pdf_i64_subtraction_i32_min (pdf i64 t *dest, const [Function]
pdf i32 t minuend, const pdf i64 t subtrahend, pdf status t *p_status )
Finds the difference between a 32 bit number and a 64 bit number
Parameters
minuend The minuend of the subtraction (32 bits)
subtrahend
The subtrahend of the subtraction (64 bits type)
dest Where 64 bit result is stored
p status Pointer to a pdf status t variable to hold the status of the
operation. If it is NULL then this parameter is ignored.
Returns A pdf status value:
PDF_OK Operation successful
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t subtrahend;
pdf_status_t *p_status;
subtrahend = pdf_i64_new(0, 35);
result = pdf_i64_new(0, 0);
dest = &result;
pdf_i64_subtraction (dest, 25, subtrahend, p_status)
if (*p_status != PDF_OK) /* Now dest is -10 */
{
/* Error code */
}
void pdf_i64_subtraction_i32_sub (pdf i64 t *dest, const [Function]
pdf i64 t minuend, const pdf i32 t subtrahend, pdf status t *p_status )
Finds the difference between a 64 bit number and a 32 bit number
Chapter 2: Base Layer 12
Parameters
minuend The minuend of the subtraction (64 bits type)
subtrahend
The subtrahend of the subtraction (32 bits)
dest Where 64 bit result is stored
p status Pointer to a pdf status t variable to hold the status of the
operation. If it is NULL then this parameter is ignored.
Returns A pdf status value:
PDF_OK Operation successful
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t minuend;
pdf_status_t *p_status;
minuend = pdf_i64_new(0, 25);
result = pdf_i64_new(0, 0);
dest = &result;
pdf_i64_subtraction (dest, minuend, 35, p_status);
if ( != PDF_OK) /* Now dest is -10 */
{
/* Error code */
}
void pdf_i64_mult (pdf i64 t *dest, const pdf i64 t factor_1, const [Function]
pdf i64 t factor_2, pdf status t *p_status )
Multiplication of two 64 bit numbers
Parameters
factor 1 First factor in the multiplication
factor 2 Second factor in the multiplication
dest Where 64 bit result is stored
p status Pointer to a pdf status t variable to hold the status of the
operation. If it is NULL then this parameter is ignored.
Returns A pdf status value:
PDF_OK Operation successful
PDF_EBADDATA
NULL value in bignum.
Usage example
pdf_i64_t *dest;
Chapter 2: Base Layer 13
pdf_i64_t result;
pdf_i64_t factor_1;
pdf_i64_t factor_2;
pdf_status_t *p_status;
factor_1 = pdf_i64_new (0, 10);
factor_2 = pdf_i64_new (0, 100);
result = pdf_i64_new (0, 0);
dest = &result;
pdf_i64_mult (dest, factor_1, factor_2,p_status);
if ( *p_status != PDF_OK) /* Now dest is 1000 */
{
/* Error code */
}
void pdf_i64_mult_i32 (pdf i64 t *dest, const pdf i64 t factor_1, [Function]
const pdf i32 t factor_2, pdf status t *p_status )
Multiplication of a 64 bit number and a 32 bit number
Parameters
factor 1 First factor in the multiplication (64 bits)
factor 2 Second factor in the multiplication (32bits)
dest Where 64 bit result is stored
p status Pointer to a pdf status t variable to hold the status of the
operation. If it is NULL then this parameter is ignored.
Returns A pdf status value:
PDF_OK Operation successful
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t factor_1;
Parameters
dividend The dividend in the division
divisor The divisor in the division
dest Where 64 bit result is stored
Returns PDF OK Operation successful
PDF EDIVBYZERO
Division by zero.
PDF EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t dividend;
pdf_i64_t divisor;
pdf_i64_t divisor;
void pdf_i64_mod (pdf i64 t *dest, const pdf i64 t dividend, const [Function]
pdf i64 t divisor, pdf status t *p_status )
Returns the remainder of the division between two 64 bit numbers
Parameters
dividend The dividend in the division
Chapter 2: Base Layer 16
num = pdf_i64_to_i32(bignum);
pdf_buffer_destroy (my_buffer);
PDF_FALSE
The buffer is not in an end-of-buffer state.
Usage example
pdf_buffer_t my_buffer;
pdf_char_t my_char;
/* Create a string */
my_string_size = 10;
my_string = pdf_alloc (my_string_size);
strncpy (my_string, "0123456789", 10);
my_string[10] = 0;
my_buffer->data[my_buffer->wp] = my_string[my_buffer->wp];
my_buffer->wp++;
}
pdf_pm_begin_operation_fn_t begin_operation_fn
pdf_pm_end_operation_fn_t end_operation_fn
pdf_pm_get_duration_fn_t get_duration_fn
pdf_pm_set_duration_fn_t set_duration_fn
pdf_pm_get_current_value_fn_t get_current_value_fn_t
pdf_pm_set_current_value_fn_t set_current_value_fn_t
pdf_pm_set_text_fn_t set_text_fn
The type definitions for the callbacks follows.
Parameters
client data
User supplied data.
duration A pointer to a time span variable containing the new duration
for the progress monitor.
Returns This callback should return PDF_OK to the caller.
Parameters
type The type of UUID to generate.
Returns The generated UUID.
Usage example
pdf_uuid_t uuid;
void (*pdf hash element dispose fn t) (const void *elt) [Data Type]
A function type for disposing hash elements.
void (*pdf hash key dispose fn t) (const void *key) [Data Type]
A function type for disposing hash keys.
Usage example
pdf_hash_t hash;
{
/* Add an element to the hash */
pdf_hash_add (hash, "a-key", "a-value", NULL);
/* And remove it */
pdf_hash_remove (hash, "a-key");
}
elem pointer
A pointer where to store the element.
Returns A pdf status value:
PDF_OK The operation succeeded.
PDF_EBADDATA
Either elem pointer is NULL, key or the table is invalid.
PDF_ERROR
The key wasn’t found.
Usage example
pdf_hash_t hash;
char *elem;
{
/* Add some elements to the hash */
pdf_hash_add (hash, "first-key", "first-value", NULL);
pdf_hash_add (hash, "second-key", "second-value", NULL);
pdf_hash_add (hash, "third-key", "third-key", NULL);
Parameters
iterator A Hash Table iterator pointer.
key A pointer where to save the key.
Returns A pdf status value:
PDF_OK The operation succeeded.
PDF_EBADDATA
Either iterator is invalid or key is NULL.
PDF_ERROR
There are no more keys to traverse over.
Usage example
pdf_hash_t hash;
pdf_hash_iterator_t hash_iter;
pdf_char_t *key;
NOTE: If you are going to use the element after the table containing the element is
destroyed, in that case don’t use these functions.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Either table, key or elt is invalid.
Usage example
pdf_hash_t hash;
pdf_list_t elem;
PDF_EBADDATA
Either elt is NULL, key or the table is invalid.
PDF_ERROR
The key wasn’t found.
Usage example
pdf_hash_t hash;
pdf_hash_t table;
Parameters
table The hash table to get the value from.
key The key associated with the desired value.
elt A pointer to the string variable to hold the value.
Returns A PDF status variable:
PDF_OK The value was successfully stored into elt.
PDF_EBADDATA
Either elt is NULL, key or the table is invalid.
PDF_ERROR
The key wasn’t found.
Usage example
pdf_char_t *string;
pdf_hash_t table;
2.6 Lists
This section describes how to work with unsorted and sorted lists. In case you’re going to
work with a sorted list, you should use the sorted version of each function if it’s available.
See Section 2.6.7 [Working with sorted lists], page 63.
pdf_bool_t (*pdf list element equals fn t) (const void *elt1, const void [Data Type]
*elt2)
A function type for comparing list elements equality. Should return PDF TRUE in
case they are equal and PDF FALSE otherwise.
void (*pdf list element dispose fn t) (const void *elt) [Data Type]
A function type for disposing list elements.
Chapter 2: Base Layer 47
int (*pdf list element compar fn t) (const void *elt1, const void *elt2) [Data Type]
A function type for comparing list elements. Should return an integer less than, equal
to, or greater than zero corresponding to whether the first element is considered less
than, equal to, or greater than the second element.
pdf_size_t (*pdf list element hashcode fn t) (const void *elt) [Data Type]
A function type for calculating a Hash code given a list element. Should return the
corresponding hash code.
/* ...create ‘mylist’... */
pdf_list_destroy (mylist);
int elem;
if (pdf_list_new (list_element_equal_p,
list_element_destroy,
Chapter 2: Base Layer 50
Usage example
pdf_list_t list;
pdf_list_node_t node;
int elem1;
int elem2;
int elem3;
int elem4;
if (pdf_list_new (list_element_equal_p,
list_element_destroy,
PDF_FALSE, /* Allow duplicates */
&list) == PDF_OK)
{
/* Insert several elements into the list */
pdf_list_add_last (list, (void *) &elem1, NULL);
pdf_list_add_last (list, (void *) &elem2, NULL);
pdf_list_add_last (list, (void *) &elem3, NULL);
pdf_list_add_last (list, (void *) &elem4, NULL);
Usage example
pdf_list_t list;
pdf_list_node_t node_first;
pdf_list_node_t node_second;
int elem1;
int elem2;
if (pdf_list_new (list_element_equal_p,
list_element_destroy,
PDF_FALSE, /* Allow duplicates */
&list) == PDF_OK)
{
/* Insert several elements into the list */
pdf_list_add_last (list, (void *) &elem1, NULL);
pdf_list_add_last (list, (void *) &elem2, NULL);
int elem2;
if (pdf_list_new (list_element_equal_p,
list_element_destroy,
PDF_FALSE, /* Allow duplicates */
&list) == PDF_OK)
{
/* Insert several elements into the list */
pdf_list_add_last (list, (void *) &elem1, NULL);
pdf_list_add_last (list, (void *) &elem2, NULL);
if (pdf_list_new (list_element_equal_p,
list_element_destroy,
Chapter 2: Base Layer 54
if (pdf_list_new (list_element_equal_p,
list_element_destroy,
Chapter 2: Base Layer 55
Usage example
pdf_list_t list;
pdf_list_node_t node_first;
pdf_list_node_t node_second;
int elem1;
int elem2;
int elem3;
int elem4;
pdf_size_t index_of_elem4;
if (pdf_list_new (list_element_equal_p,
list_element_destroy,
PDF_FALSE, /* Allow duplicates */
&list) == PDF_OK)
{
/* Insert several elements into the list */
pdf_list_add_last (list, (void *) &elem1, NULL);
pdf_list_add_last (list, (void *) &elem2, NULL);
pdf_list_add_last (list, (void *) &elem3, NULL);
pdf_list_add_last (list, (void *) &elem4, NULL);
int *pointer_to_elem1;
if (pdf_list_new (list_element_equal_p,
list_element_destroy,
PDF_FALSE, /* Allow duplicates */
&list) == PDF_OK)
{
/* Insert an element into the list */
pdf_list_add_last (list, (void *) &elem1, NULL);
if (pdf_list_new (list_element_equal_p,
list_element_destroy,
PDF_FALSE, /* Allow duplicates */
&list) == PDF_OK)
{
/* Insert an element into the list */
pdf_list_add_last (list, (void *) &elem1, NULL);
Chapter 2: Base Layer 58
Parameters
list A list.
element A pointer to the user data to be stored as a list element.
node If non NULL, a list node variable used to contain the added
element.
Returns A PDF status value:
PDF_OK The element was inserted successfully.
PDF_EBADDATA
The list does not allow duplicated values and already contain
element.
PDF_ENOMEM
Not enough memory to perform the operation.
Usage example
pdf_list_t list;
my_t my_var;
PDF_ENOMEM
Not enough memory to perform the operation.
Usage example
pdf_list_t list;
int a, b, c;
Usage example
pdf_list_t list;
int elem1;
int elem2;
int elem3;
Parameters
list A list.
compar fn A comparision function.
start index
Index to the first list position to be searched.
end index Index to the last list position to be searched.
element The element to search for.
node The seached node if it was found.
Returns A pdf status value:
PDF_OK The operation succeeded.
PDF_ENONODE
element not found.
PDF_EBADDATA
Invalid node pointer or compar fn.
PDF_EINVRANGE
start index or end index is greater than the list size or less
than 0.
Usage example
XXX
Usage example
XXX
pdf_status_t pdf_list_iterator_from_to (const pdf list t list, [Function]
const pdf size t start_index, const pdf size t end_index, pdf list iterator t
*itr )
Create an iterator traversing the element with indices i, start_index <= i < end_
index, of a list.
The list contents must not be modified while the iterator is in use, except for replacing
or removing the last returned element.
Parameters
list A list.
start index
A position in list.
end index A position in list.
itr A pointer to an iterator where the new one will be saved.
Returns A status variable:
PDF_OK itr contains a new iterator for list pointing to start index.
PDF_EINVRANGE
start index or end index is greater than the list size or less
than 0.
PDF_EBADDATA
itr points to NULL.
Usage example
XXX
pdf_status_t pdf_list_iterator_next (pdf list iterator t [Function]
*iterator, const void **element_pointer, pdf list node t
*node_pointer )
If there is a next element, store the next element in *element pointer, store its node
in *node pointer if it is non-NULL, and advance the iterator.
Parameters
iterator A list iterator.
element pointer
A pointer to a pointer to user data.
node pointer
A pointer to a list node.
Returns A pdf status value:
PDF_OK There is a next element.
PDF_ERROR
There is not a next element.
Chapter 2: Base Layer 68
Usage example
XXX
PDF_STM_FILTER_AHEX_ENC
ASCII Hex encoder.
PDF_STM_FILTER_AHEX_DEC
ASCII Hex decoder.
PDF_STM_FILTER_RL_ENC
Run-Length encoder.
PDF_STM_FILTER_RL_DEC
Run-Length decoder.
PDF_STM_FILTER_FLATE_ENC
Flate (zlib) encoder.
PDF_STM_FILTER_FLATE_DEC
Flate (zlib) decoder.
PDF_STM_FILTER_JBIG2_DEC
JBIG2 decoder.
PDF_STM_FILTER_AESV2_ENC
AESV2 encoder.
PDF_STM_FILTER_AESV2_DEC
AESV2 decoder.
PDF_STM_FILTER_V2_ENC
V2 encoder.
PDF_STM_FILTER_V2_ENC
V2 decoder.
PDF_STM_FILTER_MD5_ENC
MD5 encoder.
Usage example
pdf_stm_t stm;
pdf_stm_mem_new (buffer,
2048,
0, /* Use the default cache size */
PDF_STM_WRITE,
&stm);
pdf_status_t pdf_stm_write (pdf stm t stm, const pdf char t *buf, [Function]
pdf size t bytes, pdf size t *written_bytes )
Write a chunk of data into a given stream.
Parameters
stm A stream.
buf The buffer containing the written information.
bytes The number of bytes to write into the stream.
written bytes
A pointer to a PDF size containing the number of octects
actually written. If the returned value is less than bytes
then a disk full condition has occured.
Returns A PDF status value:
PDF_OK All the requested bytes were successfully written into stm.
PDF_EEOF A disk full condition occurred.
PDF_EINVOP
Writting was requested in a read stream.
PDF_ERROR
An error prevented to write the bytes.
Usage example
XXX
PDF_ERROR
An error prevented to write the bytes.
Usage example
XXX
Parameters
stm A stream.
Returns The new position of the stream read/write pointer. If it is equal to the
current position then there was an error.
Usage example
XXX
Parameters
stm A stream.
Returns The current position (measured in octets from the beginning of the back-
end media) of the read/write pointer.
Usage example
XXX
Parameters
stm A stream.
Usage example
XXX
pdf_real_t left
x coordinate for the left points.
pdf_real_t top
y coordinate for the upper points.
pdf_real_t right
x coordinate for the right points.
pdf_real_t bottom
y coordinate for the bottom points.
number = 1.2;
rounded = pdf_fp_floor (number);
Chapter 2: Base Layer 77
/* rounded equals 1 */
number = 1.6;
rounded = pdf_fp_floor (number);
/* rounded equals 1 */
number = 2;
rounded = pdf_fp_floor (number);
/* rounded equals 2 */
number = 1.2;
rounded = pdf_fp_ceil (number);
/* rounded equals 2 */
number = 1.6;
rounded = pdf_fp_ceil (number);
/* rounded equals 2 */
number = 2;
rounded = pdf_fp_ceil (number);
/* rounded equals 2 */
Parameters
op A real operand.
Returns The natural logarithm of op.
Usage example
XXX
real = 1.123456;
Parameters
result A pointer to a rectangle to hold the result. This can be a
copy of rect.
matrix A pointer to the matrix used to perform the transformation.
point A pointer to the rectangle to transform.
Returns A PDF status value:
PDF_OK The operation suceeded.
PDF_ERROR
An error prevented the operation to finish.
Usage example
XXX
stack_size
Size of the stack.
stack Array of elements in the stack when the error ocurred. The
first element is the last pushed one. Each element is a double
value or a boolean one.
Parameters
function The function to evaluate.
out Array containing the output values from the function evalu-
ation.
PDF_ERROR
Error while evaluating the function.
PDF_TYPE0
Error in a type0 function. The debug structure will contain
more information.
PDF_TYPE2
Error in a type2 function. The debug structure will contain
more information.
PDF_TYPE3
Error in a type3 function. The debug structure will contain
more information.
PDF_TYPE4
Error in a type4 function. The debug structure will contain
more information.
Usage example
XXX
PDF_TEXT_FILTER_UPPER_CASE
Makes all text upper case.
PDF_TEXT_FILTER_LOWER_CASE
Makes all text lower case.
PDF_TEXT_FILTER_TITLE_CASE
Makes all text title case.
PDF_TEXT_FILTER_REMOVE_AMP
Remove all single ampersands. This filter transform && into &.
PDF_TEXT_FILTER_NORM_WITH_FULL_WIDTH
Normalize with full width ASCII variants filter.
PDF_TEXT_FILTER_REMOVE_LINE_ENDINGS
Replace line endings with space characters.
pdf_text_new (&mytext);
Chapter 2: Base Layer 90
PDF_EBADDATA
Invalid parameters.
Usage Example
pdf_text_t text;
pdf_char_t *he_string;
pdf_size_t he_string_size;
pdf_text_host_encoding_t encoding;
pdf_status_t ret_code;
PDF_ENOMEM
Out of memory condition.
PDF_EBADCONTEXT
The global context for the text module is not initialized.
PDF_ETEXTENC
Invalid data in the input string (encoding error).
PDF_EBADDATA
Invalid parameters.
Usage Example
pdf_text_t text;
pdf_char_t *pdf_string;
pdf_size_t pdf_string_size;
pdf_char_t *remaining_str;
pdf_size_t remaining_size;
pdf_status_t ret_code;
pdf_text_destroy(text);
}
while((ret_code == PDF_OK) && (remaining_length > 0));
Parameters
str A Unicode string.
size The length of str in bytes.
enc The Unicode encoding used by str.
text A pointer to the newly created text object.
Returns A pdf status value:
PDF OK The operation succeeded.
PDF ENOMEM
Out of memory condition.
PDF EBADCONTEXT
The global context for the text module is not initialized.
PDF ETEXTENC
Invalid data in the input string (encoding error).
PDF EBADDATA
Invalid parameters.
Usage Example
pdf_text_t text;
pdf_char_t *unicode_string;
pdf_size_t unicode_string_size;
pdf_status_t ret_code;
number = 24;
ret_code = pdf_text_new_from_u32 (number, &text);
if(ret_code != PDF_OK)
{
/* Something bad happened */
}
Parameters
text A text variable.
Returns The code of the language associated with text.
Usage Example
pdf_text_t text;
pdf_char_t *code;
if (pdf_text_empty_p (text))
{
/* ‘text’ contains no text */
}
pdf_dealloc(str);
Chapter 2: Base Layer 97
pdf_dealloc(str);
pdf_dealloc(str);
pdf_dealloc(str);
Usage Example
pdf_text_t text;
pdf_text_host_encoding_t encoding;
pdf_char_t *str;
pdf_size_t length;
Usage Example
pdf_text_t text1;
pdf_char_t * str;
Usage Example
pdf_text_t text;
const pdf_char_t *new_pattern = "GNU/Linux";
const pdf_char_t *old_pattern = "Linux";
/* ...initialize ‘text’... */
if (pdf_text_replace_ascii (text, new_pattern, old_pattern) != PDF_OK)
{
/* Manage the error */
}
pdf_status_t pdf_text_filter (pdf text t text, const pdf u32 t [Function]
filter )
Filter the contents of a text variable.
Parameters
text A text variable.
filter Filter to be run in text, in the way: FILTER 1 | FILTER 2
| FILTER 3. (see pdf_text_filter_type_e data type).
Warning!! At most one case-related filter can be applied at
a time.
Returns The status of the operation
Usage Example
pdf_text_t text;
/* ...initialize ‘text’... */
p ret code
Pointer to store the status of the comparison (an internal
error could happen). NULL can be passed, so that the return
status is not considered.
Returns An integer:
-1 If text1 < text2
0 If text1 = text2
+1 If text1 > text2
Usage Example
pdf_text_t text1;
pdf_text_t text2;
enc = pdf_text_get_host_encoding();
Chapter 2: Base Layer 104
if (new_time == NULL)
{
/* Error */
}
pdf_status_t pdf_time_destroy (pdf time t time_var ) [Function]
Destroy time var and free all used memory.
Parameters
time var The time variable to be destroyed. Should be a properly
created time variable.
Returns A status value:
PDF_OK The operation succeeded.
Usage example
pdf_time_t mytime;
/* ...manipulate ‘mytime’... */
pdf_time_clear (mytime);
pdf_time_set_from_u32(mytime, 1217009657);
pdf_time_set_from_i64(mytime, epoch);
cal_span.year = 30;
cal_span.month = 7;
cal_span.day = 20;
cal_span.hour = 21;
cal_span.minute = 0;
cal_span.second = 0;
Parameters
time var A properly created time variable.
p cal span
A pointer to a calendar span with valid values.
PDF_EBADDATA
The data in cal span is invalid.
Usage example
pdf_time_t mytime;
struct pdf_time_cal_span_s cal_span;
cal_span.year = 30;
cal_span.month = 7;
cal_span.day = 20;
cal_span.hour = 21;
cal_span.minute = 0;
cal_span.second = 0;
p local cal
A pointer to the time calendar structure that will hold the
local time of time var.
Returns A status value:
PDF_OK The operation successfully finished.
Usage example
pdf_time_t mytime;
struct pdf_time_cal_s cal;
Usage example
pdf_time_t mytime;
struct pdf_time_cal_s mycaltime;
mycaltime.year = 2000;
mycaltime.month = 8;
mycaltime.day = 10;
mycaltime.dow = 0; /* This field is ignored by ‘pdf_time_from_cal’ */
mycaltime.hour = 0;
mycaltime.minute = 0;
mycaltime.sec = 0;
mycaltime.gmt_offset = 1;
Parameters
time var A properly created time variable.
time format
The format to use when creating the string representation of
time.
Chapter 2: Base Layer 116
pdf_dealloc(mytime_str);
if (pdf_time_from_string (mytime,
time_str,
PDF_TIME_FORMAT_PDF) == PDF_EBADDATA)
{
/* Error while parsing ‘time_str’ according to ‘PDF_TIME_FORMAT_PDF’ *
}
pdf_time_set_to_current_local_time (mytime);
pdf_status_t pdf_time_set_to_current_utc_time (pdf time t [Function]
time_var )
Set the value of time var to the current UTC time used by the operating system.
Parameters
time var A properly created time variable.
Returns A status value:
PDF_OK The operation successfully finished.
Usage example
pdf_time_t mytime;
pdf_time_set_to_current_utc_time (mytime);
Returns The newly created time span variable or NULL if there is an error.
Usage example
pdf_time_span_t span;
pdf_time_span_destroy (span);
low value The low (unsigned) part of the time span value.
Returns A status value:
PDF_OK The operation successfully finished.
Usage exaple
pdf_time_span_t span;
pdf_time_span_negate (span);
pdf_status_t pdf_time_span_add (const pdf time span t span1, [Function]
const pdf time span t span2, pdf time span t *p_result )
Add two time spans and store the result in another time span.
Parameters
span1 The first time span to add.
Chapter 2: Base Layer 120
p result The result of the diff operation. Any previous value of the
time span is lost.
Returns A status value:
PDF_OK The operation successfully finished.
PDF_EBADDATA
p result is not a valid pointer.
Usage example
pdf_time_span_t span1;
pdf_time_span_t span2;
pdf_time_span_t span_diff;
Usage example
pdf_time_span_t span1;
pdf_time_span_t span2;
if (pdf_time_add_cal_span_with_base (&cal_span1,
&cal_span2,
mytime,
&cal_result) == PDF_EBADDATA)
{
/* Invalid data in ‘cal_span1’ or ‘cal_span2’ */
}
case -1:
{
/* The length of ‘span1’ is shorter than the length of ‘span2’ */
break;
}
case 0:
{
/* The length of ‘span1’ is equal than the length of ‘span2’ */
break;
}
case 1:
{
/* The length of ‘span1’ is greater than the length of ‘span2’ */
break;
}
}
if (pdf_time_cal_span_diff (&span1,
Chapter 2: Base Layer 125
&span2,
mytime,
&result) == PDF_EBADDATA)
{
/* Invalid data in ‘span1’ or ‘span2’ */
}
pdf_time_w32_set_from_filetime(mytime, &filetime);
the contents of a PDF file from a file stored in the local filesystem, from a network webdav
based filesystem, an http server or a compressed image.
The GNU PDF Library provides the default disk filesystem implementation for each
supported plattform.
Conceptually speaking a filesystem contain a tree (or several trees in some filesystem
implementations supporting several volumes) of filesystem items.
Each time has a type and several properties. The client can ask the filesystem for the
properties of a given item identified by a path name.
An open file object (of type pdf_fsys_file_t) represent a readable and/or writable
file in a filesystem. Open files are associated with a given filesystem and any filesystem
can maintain an arbitrary number of open files (this may depend on the specific filesystem
implementation).
The client can read and write data from/to an open file using the pdf_fsys_file_*
functions. The implementation of the open files then call to the appropriate functionality
of the filesystem managing the file.
The client should close any opened file calling the appropriate function on the underlying
filesystem.
There is not an explicit data type for an open folder in the GNU PDF Library. Instead,
folders are referred using path names.
The Filesystem Interface provides functions to create, delete and rename folders.
Both files and folders in a filesystem can be referred using a string locator: a path name.
Path names are implemented using PDF strings. Several path names can refer to the same
file or folder.
Both the encoding and the format of the contents of a path name depends on the specific
filesystem implementation. The default disk filesystem provided by the GNU PDF Library
uses the textual device idependent file specifications described in the PDF Reference (section
3.10). The interpretation of those path names depend in the specific plattform where the
library is running. See XXX for more information about the disk filesystem path names.
Note that not all the filesystem implementations support these operations. Read In
Advance capabilities, for example, are usually implemented in slow file system devices such
as network filesystems. When a specific filesystem implementation does not support a
functionality in the Filesystem Interface then the specific call becomes a no-op.
pdf_bool_t is_hidden
pdf_bool_t is_readable
pdf_bool_t is_writable
pdf_time_t creation_date
pdf_time_t modification_date
pdf_u32_t file_size_high
pdf_u32_t file_size_low
pdf_u32_t folder_size
Parameters
file system
A filesystem. If NULL then the default filesystem is used.
path name
A path name.
Returns A 64-bit value containing the remaining free space in the volume contain-
ing path name.
Usage example
XXX
Chapter 2: Base Layer 128
creationDate
Text value containing a PDF style date string.
modDate Text value containing a PDF style date string.
fileSizeHigh
32bit unsigned integer value.
fileSizeLow
32bit unsigned integer value.
folderSize
32bit unsigned integer value.
creatorCode
32bit unsigned integer value.
versionMajor
32bit unsigned integer value.
versionMinor
32bit unsigned integer value.
isCheckedOut
Boolean value.
isPublished
Boolean value.
Parameters
item props
A filesystem item properties structure.
props hash
A PDF hash variable. It will be filled with the properties of
the item.
Returns A PDF status value:
PDF_OK The operation succeeded and the properties were stored in
the hash variable.
Usage example
XXX
Note that open file variables (pdf_fsys_file_t) contain a reference to its underlying
filesystem implementation, so the client should only provide a correctly initialized (opened)
file variable to the pdf_fsys_file_* functions.
The functionality covered by the File Interface includes:
• Synchronous Input/Output.
• Asynchronoous Input/Output (not to be confused with RIA. See above).
• File-level flush operations.
• File positioning management.
• File size management.
• File flags (status) management.
path name
A path name that identifies the file to be opened. The format
and encoding of this text variable depends on the underlying
filesystem implementation.
mode The open mode to use to open the file.
file The output file variable.
Returns A PDF status value:
PDF_OK The file was successfully opened and stored in the file vari-
able.
PDF_EBADNAME
The path name specified in path name does not identify an
existing file in the filesystem.
PDF_EBADPERMS
The client does not have permission to open the specified file
using the specified mode.
PDF_ENOMEM
Not enough memory.
Usage example
XXX
Usage example
pdf_fsys_file_t tmpfile;
pdf_size_t written;
12, PDF_TEXT_UTF8,
&path);
ret = pdf_fsys_file_open (NULL, path, PDF_FSYS_OPEN_MODE_READ, file);
Usage example
pdf_status_t ret;
pdf_fsys_file_t file = pdf_alloc(sizeof(pdf_fsys_file_s));
pdf_status_t status;
pdf_text_t path;
Parameters
file An open file.
PDF_EBADDATA
Invalid new position.
PDF_EBADPERMS
The client does not have enough permissions to change the
current file position.
Usage example
pdf_status_t ret;
pdf_fsys_file_t file = pdf_alloc(sizeof(pdf_fsys_file_s));
pdf_status_t status;
pdf_text_t path;
PDF_EAGAIN
Try again.
PDF_ERROR
There was an error flushing the open file.
Usage example
XXX
The following callbacks are defined to provide folder management: creation, deletion and
modification of folders in the filesystem and retrieval of folder contents.
Chapter 2: Base Layer 145
typedef pdf status t (*pdf fsys build path fn t) (void * data, pdf text t * output,
pdf text t first element, pdf list t rest);
Usage example
XXX
pdf_status_t pdf_fsys_destroy (pdf fsys t filesystem ) [Function]
Destroy a filesystem freein all used resources.
Parameters
filesystem A filesystem variable.
Returns A PDF status value:
PDF_OK The filesystem was successfully destroyed.
Usage example
XXX
PDF_TOKEN_ARRAY_START
The “[” operator, which marks the beginning of an array.
PDF_TOKEN_ARRAY_END
The “]” operator, which marks the end of an array.
PDF_TOKEN_PROC_START
The “{” operator, which marks the beginning of a procedure.
PDF_TOKEN_PROC_END
The “}” operator, which marks the end of a procedure.
case PDF_BADDATA:
{
/* STREAM is not a valid reading stream */
break;
}
case PDF_ENOMEM:
{
/* Not enough memory to create the reader */
break;
}
case PDF_ERROR:
{
/* Some other error prevented the creation of
the reader */
break;
}
default:
{
/* Success */
break;
}
}
Parameters
reader The reader to destroy.
Returns A PDF status value:
PDF_OK The token reader was destroyed.
PDF_EBADDATA
reader was NULL.
Usage example
pdf_token_reader_t reader;
/* Create a reader */
XXX
/* Destroy the reader */
pdf_token_reader_destroy (reader);
Chapter 2: Base Layer 154
/* Create a writer */
XXX
/* Destroy the writer */
pdf_token_writer_destroy (writer);
PDF_EAGAIN
It’s not possible to read a full token now. Since one may
have been partially read, the operation should be repeated
with the same flags when data becomes available.
PDF_EEOF Reached the end of the input stream (at a valid position).
PDF_EBADFILE
The stream violates the PDF specifications.
PDF_EIMPLLIMIT
It’s not possible to read the next token without exceeding an
implementation limit (e.g., the token is too long).
PDF_ERROR
An unspecified error occurred.
Usage example
XXX
Parameters
old The token to copy.
new A pointer to the newly created token.
Returns A PDF status value:
PDF_OK The operation succeeded.
PDF_ENOMEM
Not enough memory.
pdf_status_t pdf_token_destroy (pdf token t token ) [Function]
Destroy the given token, freeing any memory it used.
Parameters
old The token to copy.
new A pointer to the newly created token.
Returns A PDF status value:
PDF_OK The operation succeeded.
/* ... */
/* Read a name */
if (pdf_token_read (reader, &token) != PDF_OK)
{
/* Error */
}
if (pdf_token_get_type (token) != PDF_TOKEN_NAME)
{
/* We were expecting a name */
}
pdf_bool_t pdf_token_equal_p (const pdf token t token1, const [Function]
pdf token t token2 )
Determines whether the given tokens are equivalent.
Chapter 2: Base Layer 160
Parameters
token1 A token.
token2 Another token.
Returns A boolean value:
PDF_TRUE The given tokens are equal.
PDF_FALSE
The tokens are not equal.
const pdf_char_t *pdf token get string data (const pdf token t [Function]
token )
Returns a pointer to the data associated with a given string token.
Parameters
token A token of type PDF TOKEN STRING.
Returns A pointer to the data, which will be valid until the token is destroyed.
The data is not null-terminated.
const pdf_char_t *pdf token get name data (const pdf token t token ) [Function]
Returns a pointer to the data associated with a given name token.
Parameters
token A token of type PDF TOKEN NAME.
Returns A pointer to the name data, which will be valid until the token is de-
stroyed. The data is null-terminated.
Chapter 2: Base Layer 161
Parameters
token A token of type PDF TOKEN NAME.
Returns The name’s size, in octets (excluding the terminating null byte).
const pdf_char_t *pdf token get keyword data (const pdf token t [Function]
token )
Returns a pointer to the data associated with a given keyword token.
Parameters
token A token of type PDF TOKEN KEYWORD.
Returns A pointer to the data, which will be valid until the token is destroyed.
The data is null-terminated.
Parameters
token A token of type PDF TOKEN KEYWORD.
Returns The keyword’s size, in octets (excluding the terminating null byte).
const pdf_char_t *pdf token get comment data (const pdf token t [Function]
token )
Returns a pointer to the data associated with a given comment token.
Parameters
token A token of type PDF TOKEN COMMENT.
Returns A pointer to the data, which will be valid until the token is destroyed.
The data is not null-terminated.
Parameters
token A token of type PDF TOKEN COMMENT.
2.13 Encryption
This section describes related to encryption functions.
Chapter 2: Base Layer 162
if (st != PDF_OK)
{
/* Error */
}
/* ... */
st = pdf_crypt_cipher_setkey (&cipher, key, sizeof(key));
if (st != PDF_OK)
{
/* Error */
}
pdf_status_t pdf_crypt_cipher_encrypt (pdf crypt cipher t [Function]
cipher, pdf char t *out, pdf size t out_size, pdf char t *in, pdf size t
in_size, pdf size t *result_size )
Encrypt a buffer. The ciphered text will be put in out.
Chapter 2: Base Layer 164
Parameters
cipher A cipher.
out A pointer to the output buffer.
out size Size reserved for the output buffer in bytes. The function will
fail if it is not too large to contain the output.
in A pointer to input buffer.
in size The length of the input buffer in bytes. I must be greater
than zero. Some algorithms requires than IN SIZE to be
multiple of a fixed integer.
result size A pointer where it will put the real size of the output buffer.
This size will be lesser or equal than out size.
Returns
PDF_OK Operation successful
PDF_ERROR
An error ocurred.
Usage example
pdf_crypt_cipher_t cipher;
pdf_status_t st;
pdf_char_t *out;
pdf_char_t *in;
pdf_size_t out_size;
pdf_size_t in_size;
/* ... */
out_size = pdf_crypt_cipher_encrypt_size (cipher, in, in_size);
out = pdf_alloc (out_size);
if (st != PDF_OK)
{
/* Error*/
}
out size Size reserved for the output buffer in bytes. The function will
fail if it is not too large to contain the output.
in A pointer to input buffer.
in size The length of the input buffer in bytes. It must be greater
than zero.
result size A pointer where it will put the real size of the output buffer.
This size will be lesser or equal than out size.
Returns
PDF_OK Operation successful
PDF_ERROR
An error ocurred.
Usage example
pdf_crypt_cipher_t cipher;
pdf_status_t st;
pdf_char_t *out;
pdf_char_t *in;
pdf_size_t out_size;
pdf_size_t in_size;
/* ... */
out_size = pdf_crypt_cipher_decrypt_size (cipher, in, in_size);
out = pdf_alloc (out_size);
if (st != PDF_OK)
{
/* Error*/
}
Parameters
md A pointer to the pdf crypt md t.
algo Algorithm which be used to hashing.
Returns A PDF status value:
PDF_OK Operation successful
PDF_ERROR
An error ocurred.
Usage example
pdf_status_t st;
pdf_crypt_md_t md;
if (st != PDF_OK)
{
/* Error /*
}
if (st != PDF_OK)
{
/* Error */
}
pdf_crypt_md_destroy (md);
if (st != PDF_OK)
{
/* Error */
}
pdf_crypt_md_destroy (md);
Usage example
pdf_status_t st;
pdf_crypt_md_t md;
/* ... /*
pdf_crypt_md_destroy (md);
2.13.4 Utilities
pdf_status_t pdf_crypt_nonce (pdf char t *buffer, pdf size t [Function]
size )
Fill a buffer with random bytes.
Parameters
buffer Buffer which be filled.
size Size of the buffer in bytes.
Returns A PDF status value:
PDF_OK Operation successful
Usage example
pdf_char_t buffer[16];
3 Object Layer
3.1 Overview
In its more fundamental structure, a PDF document is conformed by a collection of PDF
objects organized in a certain way. PDF objects can be of several data types:
Scalars Scalar values are integer and real numbers and booleans (true, false).
Names Name objects are atoms made out of a sequence of printable characters. They
are finished by a null octet.
The characters of the string making up the name do not contribute to the
meaning of the name.
Strings Strings are sequences of octects. Note that the octects contained in a PDF
string are not restricted to the printable ASCII subset. In particular the null
octet (00H) can be part of a string and it is not used to to finalize it like in
some programming languages.
The interpretation of the contents of a string depends of the selected encoding
and other factors. Usually the UTF-8 encoding of ISO-16000 is used.
Arrays Arrays are collections of objects that are arranged sequentially. Unlike the
arrays in most programming languages, PDF arrays does not need to be homo-
geneous: the same array can contain objects of several types including other
arrays.
Dictionaries
Dictionaries are a set of key-value pairs. Like arrays, they are heterogeneous.
Unlike arrays, the objects contained in dictionaries are usually accessed using
the value of a key. They are like the associative arrays of some programming
languages.
Both arrays and dictionaries are containers, meaning that they can contain
other objects.
Streams Streams are like strings, but they are unrestrained (no limitation on its size)
and are accompanied by a descriptor dictionary. The descriptor contains infor-
mation about the stream, like its size and how its contents should be filtered
when read.
Indirect References
An indirect reference is a way to refer to some indirect object (XXX: xref).
By using container objects it is possible to build arbitrary structures made out of objects.
A PDF document is a hierarchy of objects arranged following some conventions.
Chapter 3: Object Layer 170
The dictionary at the top of the hierarchy is known as the root dictionary. Any other
object in the document shall be accessible from the root dictionary. The only exception
is the optional information dictionary. If it exists it contains meta-information about the
document: software that made the document, author, etc.
Note: The use of this layer can lead to non-well conformed PDF documents:
not every PDF object document define a document. The client should be
careful when using this layer. In contrast the Chapter 4 [Document Layer],
page 229 provides a convenient API to manipulate PDF files while maintaining
its structural integrity.
Chapter 3: Object Layer 171
PDF_OBJ_NULL
The Null object has a type and a value that are unequal to those of any
other object.
See Section 3.2.14 [Null Object], page 217.
...
...
...
...
/* Compare integers */
pdf_obj_integer_new (doc, PDF_TRUE, 10, &obj1);
pdf_obj_integer_new (doc, PDF_FALSE, 20, &obj2);
pdf_obj_equal_p (obj1, obj2); /* Returns PDF_FALSE */
pdf_obj_destroy (obj1);
pdf_obj_destroy (obj2);
pdf_status_t pdf_obj_get_doc (pdf obj t obj, pdf obj doc t *doc ) [Function]
Gets the object document associated with a given PDF object obj.
This is a nop for direct scalar objects, since they are not associated with an object
document.
Parameters
obj A PDF object.
doc A pointer to a pdf obj doc t variable.
Returns A PDF status value:
PDF_OK The object document was stored in doc.
PDF_EINVOBJ
The specified object obj is a scalar object.
PDF_ERROR
An error prevented the operation to complete. The value of
doc is now undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t obj;
...
Chapter 3: Object Layer 177
...
...
...
...
...
pdf_obj_acquire (obj);
...
...
An example is the collection of objects containing the contents of a page: you need to read
them all to render the page.
It is possible to pack several PDF objects in a compressed stream in the object document
on disk. An object collection can be translated into one or several of such compressed
streams.
An object can be declared as part of one (and just one) object collection. Only com-
pressible objects can be added to a collection.
pdf_status_t pdf_obj_col_new (pdf obj doc t doc, pdf obj col t [Function]
*col )
Create a new object collection in the specified object document doc.
Parameters
doc An object document.
col A pointer to a pdf obj col t variable that will contain the
new object collection.
Returns A PDF status value:
PDF_OK The object collection was created and a reference to it was
stored in col.
PDF_ERROR
An error prevented the operation to complete. The value of
col is undefined and shall not be used.
Usage example
pdf_obj_doc_t doc;
pdf_obj_col_t col1;
pdf_obj_col_t col2;
...
Usage example
/* Callback function */
pdf_bool_t
my_enum_callback (pdf_obj_t obj,
pdf_obj_t value,
void *client_data)
{
/* Process the callback... */
}
...
pdf_bool_t pdf_obj_col_equal_p (pdf obj col t col1, pdf obj col t [Function]
col2 )
Test whether two PDF object collections are the same collection.
Parameters
col1 The first collection to compare.
col2 The second collection to compare.
Returns A boolean value:
PDF_TRUE The collections are the same.
PDF_FALSE
The collections are not the same.
Usage example
pdf_obj_doc_t doc;
pdf_obj_col_t col1;
pdf_obj_col_t col2;
...
...
...
...
pdf_status_t pdf_obj_get_col (pdf obj t obj, pdf obj col t *col ) [Function]
Get the containing object collection containing a given PDF object obj.
Parameters
obj A PDF object.
col A pointer to a pdf_obj_col_t value containing the returned
object collection.
Returns A PDF status value:
PDF_OK The object collection containing obj, or NULL if there is no
one, was stored in col.
PDF_EINVOBJ
obj is not a compressible object. The value in col is undefined
and shall not be used.
Chapter 3: Object Layer 187
Usage example
pdf_obj_doc_t doc;
pdf_obj_col_t col;
pdf_obj_t obj;
...
Usage example
pdf_obj_doc_t doc;
pdf_obj_t boolean_obj;
pdf_bool_t result;
Parameters
doc A document object.
indirect p A boolean value indicating whether to create an indirect ob-
ject.
value The null-terminated string value for the object.
obj A pointer to a pdf_obj_t variable to store the newly created
object.
Returns A PDF status value:
PDF_OK A new name object was successfully created in doc and stored
in obj.
PDF_EBADDATA
Invalid value in value.
Chapter 3: Object Layer 193
PDF_ERROR
An error prevented the operation to complete. The value in
doc shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t name_obj_1;
pdf_obj_t name_obj_2;
...
Chapter 3: Object Layer 194
...
{
str = malloc (pdf_obj_string_size (str_obj));
if (pdf_obj_string_hex_p (str))
{
/* The hex flag of ’str’ is set */
}
else
{
/* The hex flag of ’str’ is not set */
}
pdf_status_t pdf_obj_string_hex_set (pdf obj t obj, pdf bool t [Function]
hex_p )
Set the hex flag of the String object obj. A String object with the hex flag set to true
is saved in an hexadecimal form.
Parameters
obj A PDF String object.
hex p The new value of the hex flag for obj.
Returns A PDF status value:
Chapter 3: Object Layer 198
...
...
The previous object occupying the indexth position is no longer referenced by the
array.
Parameters
array A PDF array.
index An index into the array.
obj A PDF object.
Returns A PDF status value:
PDF_OK The element was inserted at the specified position.
PDF_EINVOBJ
The object obj is a non-scalar direct object already contained
in another object or the object belongs to other document.
PDF_EBADDATA
The specified index is invalid.
PDF_ERROR
Usage example
pdf_obj_doc_t doc;
pdf_obj_t array;
pdf_obj_t elem;
pdf_size_t index;
...
...
...
Chapter 3: Object Layer 202
...
...
PDF_EINVOBJ
array is not an array object.
PDF_EBADDATA
The specified index is invalid.
PDF_ERROR
Some error prevented to complete the operation.
Usage example
pdf_obj_t array;
...
...
Chapter 3: Object Layer 205
...
Parameters
dict A PDF dictionary object.
key A string containing the name of the key, without the preced-
ing slash character.
obj A pointer to pdf_obj_t to store the value associated with
key.
Returns A PDF status value:
PDF_OK A copy of the value associated with key was stored in obj.
PDF_EBADDATA
key is not in the dictionary.
PDF_ERROR
An error prevented the operation to complete. The value in
obj shall be considered undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t value;
...
PDF_ERROR
Some error prevented the operation to complete. The value
in val is undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t key;
pdf_obj_t value;
...
...
...
...
pdf_obj_t value;
...
...
PDF_FALSE
key is not a weak reference into dict, or key does not exist
in the dictionary, or dict is not a dictionary object, or key is
not a name object.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t key;
...
...
...
...
PDF_ERROR
Some error prevented the creation of the stream object. The
reference stored obj shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t stream;
pdf_obj_t filter_array;
pdf_string_t data_file_path;
pdf_fsys_file_t data_file;
pdf_stm_t stm;
...
Usage example
pdf_obj_t stream;
pdf_off_t stream_length;
...
...
The configuration of the filter chain in stm depends on the opening mode in mode.
The client is responsible to close the stream stm.
Parameters
stream A Stream object.
mode Mode used to open the stream. See Section 3.2.1 [Object
Data Types], page 171.
stm A pointer to a pdf stm t variable holding the returned base
layer stream.
Returns A PDF status value:
PDF_OK A filtered stream was opened to read the contents of stream.
PDF_EINVOBJ
stream is not a stream object.
PDF_ENOMEM
Not enough memory to perform the operation.
PDF_ERROR
An error prevented the operation to complete. The value of
stm shall be considered invalid.
Usage example
pdf_obj_t stream;
pdf_stm_t stm;
...
PDF_OK
Usage example
XXX
Parameters
doc A pointer to a pdf_obj_doc_t variable.
flags An integer value containing the ORed value of zero or more
flags. Valid flags are:
PDF_OBJ_DOC_CREATE_INFO_DIR
Create an empty Document Information Dictio-
nary in the object document as an indirect dic-
tionary. The Info dictionary will be referenced in
the document trailer.
Returns A PDF status value:
PDF_OK The object document was successfully created.
PDF_ERROR
Error creating the object document. The reference stored in
doc becomes invalid.
Usage example
pdf_obj_doc_t mydoc;
if (pdf_obj_doc_new (PDF_OBJ_DOC_CREATE_INFO_DIR,
&mydoc) == PDF_ERROR)
{
/* Error creating the object document */
}
pdf_status_t pdf_obj_doc_open (pdf fsys t filesystem, pdf text t [Function]
path, pdf char t *header_string, pdf obj doc ctx s *ctx, pdf obj doc t
*doc )
Open a document object from a file.
Parameters
filesystem A filesystem implementation. If this parameter is NULL then
the default disk filesystem is used. See Section 2.11 [The
Filesystem Module], page 125.
path The path to the file containing the object document.
header string
A string like "%PDF-". The string should appear as the first
content of the specified file. The string can be empty.
ctx Pointer to a pdf_obj_doc_ctx_s structure that will contain
the localization of an error in the document if some arises. If
it is NULL then it won’t be used.
doc A pointer to a pdf_obj_doc_t variable.
Returns A PDF status value:
PDF_OK The object document was correctly loaded from path and
stored in doc.
Chapter 3: Object Layer 220
PDF_ENOMEM
Not enough memory to perform the operation.
PDF_EBADNAME
The path specified in path is not correct.
PDF_EBADPERMS
The file in path could not be read due to a lack of permissions.
PDF_EBADFILE
Parser error while interpreting the contents of the file in path.
Information about the location of the error can be found in
ctx if it was specified.
PDF_EIMPLLIMIT
Some implementation limit was exceeded. For example, there
is a limit in the number of PDF objects that can be contained
in an object document. See Chapter 6 [Implementation Lim-
its], page 231.
PDF_ERROR
Some error prevented the operation to complete. The value
of doc is undefined and should not be used.
Usage example
pdf_text_t file_path;
pdf_obj_doc_t doc;
pdf_status_t pdf_obj_doc_save (pdf obj doc t doc, pdf fsys file t [Function]
file, pdf u32 t flags, struct pdf obj doc save params s params )
Save a document to a file.
Parameters
doc An object document.
file A fsys open file (opened for write) used to write the document
data into.
If this parameter is NULL then the file associated with doc is
used for the save operation.
flags An ORed value of the following defined flags:
PDF_OBJ_DOC_SAVE_DONT_CREATE_CR
Do not create a cross reference table (or stream)
when saving the document.
PDF_OBJ_DOC_SAVE_FULL
Do a “full save”, writing all the objects instead of
just the modified ones. This option recreates the
whole file with all the objects with a generation
number of 0.
params A pdf_obj_doc_save_params_s structure containing the pa-
rameters of the save operation.
Returns A PDF status value:
PDF_OK The object document was saved properly.
PDF_ERROR
An error prevented the document to be saved. The value of
doc is still valid.
Chapter 3: Object Layer 222
Usage example
struct pdf_obj_doc_save_params_s save_params;
pdf_obj_doc_t doc;
Usage example
pdf_obj_doc_t doc;
pdf_obj_t instance_id;
pdf_obj_t permanent_id;
if (pdf_obj_doc_get_id (doc,
&instance_id,
&permanent_id) != PDF_ERROR)
{
if (pdf_obj_get_type (instance_id)
!= PDF_OBJ_NULL)
{
/* ’instance_id’ is a PDF string object containing the
instance ID of the document */
}
if (pdf_obj_get_type (permanent_id)
!= PDF_OBJ_NULL)
{
/* ’permanent_id’ is a PDF string object containing the
permanent ID of the document */
}
}
if (pdf_obj_doc_set_id (doc,
instance_id,
permanent_id) != PDF_ERROR)
{
/* The instance Id and permanent Id of the document were set. */
}
pdf_status_t pdf_obj_doc_set_dirty (pdf obj doc t doc, [Function]
pdf bool t dirty_p )
Explicitly set the dirty flag of the object document doc to dirty p.
If the dirty flag of a document is set then its contents are saved before the document
is closed. Note that if the dirty flag of the document is cleared using this function
then any modified data will be lost upon closing.
Parameters
doc An object document.
dirty p Boolean value.
Returns A PDF status value:
PDF_OK The dirty flag was properly set.
Usage example
pdf_obj_doc_t doc;
pdf_text_t file_path;
pdf_obj_t catalog;
pdf_obj_t foo_value;
{
/* The object document does not feature an info
dictionary. */
}
}
Parameters
doc An object document.
obj A pointer to a pdf_obj_t variable.
Returns A PDF status value:
PDF_OK The root object has been stored in root dict.
PDF_ERROR
Error while getting the root object of the document. The
value of root dict is invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t root_dict;
4 Document Layer
Chapter 5: Page Contents Layer 230
6 Implementation Limits
The limits documented in this chapter are not imposed by neither of the supported PDF
specifications, but by this specific implementation.
In no case the implementation limits are violating the PDF specifications.
under this License. If a section does not fit the above definition of Secondary then it is
not allowed to be designated as Invariant. The Document may contain zero Invariant
Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover
Texts or Back-Cover Texts, in the notice that says that the Document is released under
this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented
in a format whose specification is available to the general public, that is suitable for
revising the document straightforwardly with generic text editors or (for images com-
posed of pixels) generic paint programs or (for drawings) some widely available drawing
editor, and that is suitable for input to text formatters or for automatic translation to
a variety of formats suitable for input to text formatters. A copy made in an otherwise
Transparent file format whose markup, or absence of markup, has been arranged to
thwart or discourage subsequent modification by readers is not Transparent. An image
format is not Transparent if used for any substantial amount of text. A copy that is
not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ascii without
markup, Texinfo input format, LaTEX input format, SGML or XML using a publicly
available DTD, and standard-conforming simple HTML, PostScript or PDF designed
for human modification. Examples of transparent image formats include PNG, XCF
and JPG. Opaque formats include proprietary formats that can be read and edited
only by proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the machine-generated HTML,
PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following
pages as are needed to hold, legibly, the material this License requires to appear in the
title page. For works in formats which do not have any title page as such, “Title Page”
means the text near the most prominent appearance of the work’s title, preceding the
beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either
is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in
another language. (Here XYZ stands for a specific section name mentioned below, such
as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve
the Title” of such a section when you modify the Document means that it remains a
section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that
this License applies to the Document. These Warranty Disclaimers are considered to
be included by reference in this License, but only as regards disclaiming warranties:
any other implication that these Warranty Disclaimers may have is void and has no
effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or
noncommercially, provided that this License, the copyright notices, and the license
notice saying this License applies to the Document are reproduced in all copies, and
Appendix A: GNU Free Documentation License 234
that you add no other conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further copying of the copies
you make or distribute. However, you may accept compensation in exchange for copies.
If you distribute a large enough number of copies you must also follow the conditions
in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly
display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of
the Document, numbering more than 100, and the Document’s license notice requires
Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify you as the publisher
of these copies. The front cover must present the full title with all words of the title
equally prominent and visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve the title of the
Document and satisfy these conditions, can be treated as verbatim copying in other
respects.
If the required texts for either cover are too voluminous to fit legibly, you should put
the first ones listed (as many as fit reasonably) on the actual cover, and continue the
rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100,
you must either include a machine-readable Transparent copy along with each Opaque
copy, or state in or with each Opaque copy a computer-network location from which
the general network-using public has access to download using public-standard network
protocols a complete Transparent copy of the Document, free of added material. If
you use the latter option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this Transparent copy will
remain thus accessible at the stated location until at least one year after the last time
you distribute an Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the Document well
before redistributing any large number of copies, to give them a chance to provide you
with an updated version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions
of sections 2 and 3 above, provided that you release the Modified Version under precisely
this License, with the Modified Version filling the role of the Document, thus licensing
distribution and modification of the Modified Version to whoever possesses a copy of
it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct from that of the
Document, and from those of previous versions (which should, if there were any,
be listed in the History section of the Document). You may use the same title as
a previous version if the original publisher of that version gives permission.
Appendix A: GNU Free Documentation License 235
B. List on the Title Page, as authors, one or more persons or entities responsible for
authorship of the modifications in the Modified Version, together with at least five
of the principal authors of the Document (all of its principal authors, if it has fewer
than five), unless they release you from this requirement.
C. State on the Title page the name of the publisher of the Modified Version, as the
publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other
copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public
permission to use the Modified Version under the terms of this License, in the form
shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover
Texts given in the Document’s license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item
stating at least the title, year, new authors, and publisher of the Modified Version
as given on the Title Page. If there is no section Entitled “History” in the Docu-
ment, create one stating the title, year, authors, and publisher of the Document
as given on its Title Page, then add an item describing the Modified Version as
stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to
a Transparent copy of the Document, and likewise the network locations given in
the Document for previous versions it was based on. These may be placed in the
“History” section. You may omit a network location for a work that was published
at least four years before the Document itself, or if the original publisher of the
version it refers to gives permission.
K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title
of the section, and preserve in the section all the substance and tone of each of the
contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and
in their titles. Section numbers or the equivalent are not considered part of the
section titles.
M. Delete any section Entitled “Endorsements”. Such a section may not be included
in the Modified Version.
N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in
title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify
as Secondary Sections and contain no material copied from the Document, you may at
your option designate some or all of these sections as invariant. To do this, add their
titles to the list of Invariant Sections in the Modified Version’s license notice. These
titles must be distinct from any other section titles.
Appendix A: GNU Free Documentation License 236
You may add a section Entitled “Endorsements”, provided it contains nothing but
endorsements of your Modified Version by various parties—for example, statements of
peer review or that the text has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up
to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified
Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or by arrangement
made by the same entity you are acting on behalf of, you may not add another; but
you may replace the old one, on explicit permission from the previous publisher that
added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission
to use their names for publicity for or to assert or imply endorsement of any Modified
Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this License,
under the terms defined in section 4 above for modified versions, provided that you
include in the combination all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your combined work in its license
notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical
Invariant Sections may be replaced with a single copy. If there are multiple Invariant
Sections with the same name but different contents, make the title of each such section
unique by adding at the end of it, in parentheses, the name of the original author or
publisher of that section if known, or else a unique number. Make the same adjustment
to the section titles in the list of Invariant Sections in the license notice of the combined
work.
In the combination, you must combine any sections Entitled “History” in the vari-
ous original documents, forming one section Entitled “History”; likewise combine any
sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You
must delete all sections Entitled “Endorsements.”
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released
under this License, and replace the individual copies of this License in the various
documents with a single copy that is included in the collection, provided that you
follow the rules of this License for verbatim copying of each of the documents in all
other respects.
You may extract a single document from such a collection, and distribute it individu-
ally under this License, provided you insert a copy of this License into the extracted
document, and follow this License in all other respects regarding verbatim copying of
that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent
documents or works, in or on a volume of a storage or distribution medium, is called
Appendix A: GNU Free Documentation License 237
an “aggregate” if the copyright resulting from the compilation is not used to limit the
legal rights of the compilation’s users beyond what the individual works permit. When
the Document is included in an aggregate, this License does not apply to the other
works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document,
then if the Document is less than one half of the entire aggregate, the Document’s Cover
Texts may be placed on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form. Otherwise they
must appear on printed covers that bracket the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may distribute translations
of the Document under the terms of section 4. Replacing Invariant Sections with
translations requires special permission from their copyright holders, but you may
include translations of some or all Invariant Sections in addition to the original versions
of these Invariant Sections. You may include a translation of this License, and all the
license notices in the Document, and any Warranty Disclaimers, provided that you
also include the original English version of this License and the original versions of
those notices and disclaimers. In case of a disagreement between the translation and
the original version of this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “His-
tory”, the requirement (section 4) to Preserve its Title (section 1) will typically require
changing the actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly
provided for under this License. Any other attempt to copy, modify, sublicense or
distribute the Document is void, and will automatically terminate your rights under
this License. However, parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such parties remain in full
compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free
Documentation License from time to time. Such new versions will be similar in spirit
to the present version, but may differ in detail to address new problems or concerns.
See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document
specifies that a particular numbered version of this License “or any later version”
applies to it, you have the option of following the terms and conditions either of that
specified version or of any later version that has been published (not as a draft) by
the Free Software Foundation. If the Document does not specify a version number of
this License, you may choose any version ever published (not as a draft) by the Free
Software Foundation.
Appendix A: GNU Free Documentation License 238
(Index is nonexistent)
Data type index 240
E PDF_ETEXTENC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
enum pdf_crypt_cipher_algo_e . . . . . . . . . . . . . . 162 PDF_FALSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
enum pdf_crypt_md_algo_e . . . . . . . . . . . . . . . . . . . 165 pdf_fp_func_debug_t . . . . . . . . . . . . . . . . . . . . . . . . . 86
enum pdf_fsys_file_mode_e . . . . . . . . . . . . . . . . . . 134 pdf_fp_func_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
enum pdf_fsys_file_mode_e PDF_FP_FUNC_TYPE4_FALSE . . . . . . . . . . . . . . . . . . . . . 86
(*pdf_fsys_file_get_mode_fn_t) PDF_FP_FUNC_TYPE4_TRUE . . . . . . . . . . . . . . . . . . . . . . 86
(pdf_fsys_file_t file ) . . . . . . . . . . . . . . . . 147 pdf_fsys_file_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
enum pdf_obj_stm_open_mode_e . . . . . . . . . . . . . . 172 pdf_fsys_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
enum pdf_obj_type_e . . . . . . . . . . . . . . . . . . . . . . . . 171 pdf_hash_iterator_t . . . . . . . . . . . . . . . . . . . . . . . . . 28
enum pdf_stm_filter_type_e . . . . . . . . . . . . . . . . . . 68 pdf_hash_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
enum pdf_stm_mode_e . . . . . . . . . . . . . . . . . . . . . . . . . . 68 PDF_I32_MAX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
enum pdf_text_filter_type_e . . . . . . . . . . . . . . . . 88 PDF_I32_MIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
enum pdf_text_unicode_encoding_e . . . . . . . . . . . 88
pdf_i32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
enum pdf_time_format_e . . . . . . . . . . . . . . . . . . . . . 106
pdf_i64_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
enum pdf_token_type_e . . . . . . . . . . . . . . . . . . . . . . 150
enum pdf_uuid_type_e . . . . . . . . . . . . . . . . . . . . . . . . 26 pdf_list_iterator_t . . . . . . . . . . . . . . . . . . . . . . . . . 46
pdf_list_node_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
pdf_list_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
I pdf_matrix_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
int . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 pdf_obj_col_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
pdf_obj_doc_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
pdf_obj_gen_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
P pdf_obj_id_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
pdf_bool_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 46 pdf_obj_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
pdf_bool_t PDF_OK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
(*pdf_fsys_file_can_set_size_fn_t) PDF_PI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
(pdf_fsys_file_t file, pdf_size_t pos ) pdf_point_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 pdf_quad_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
pdf_bool_t (*pdf_fsys_file_has_ria_fn_t) PDF_REAL_MAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
(pdf_fsys_file_t file ) . . . . . . . . . . . . . . . . 148 PDF_REAL_MIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
pdf_bool_t (*pdf_fsys_file_same_p_fn_t) pdf_real_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
(pdf_fsys_file_t file, pdf_text_t pdf_rect_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
path_name ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
pdf_size_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
pdf_bool_t (*pdf_fsys_item_p_fn_t)
pdf_size_t (*pdf_fsys_get_free_space_fn_t)
(pdf_text_t path_name ) . . . . . . . . . . . . . . . . 146
(pdf_text_t path_name ) . . . . . . . . . . . . . . . . 146
pdf_bool_t (*pdf_fsys_item_readable_p_fn_t)
(pdf_text_t path_name ) . . . . . . . . . . . . . . . . 146 pdf_status_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
pdf_bool_t (*pdf_fsys_item_writable_p_fn_t) pdf_status_t (*pdf_fsys_build_path_fn_t)
(pdf_fsys_t filename, pdf_text_t (void * data, pdf_text_t *output,
path_name ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 pdf_text_t first_name, pdf_list_t rest )
pdf_bool_t (*pdf_obj_enum_fn_t) (pdf_obj_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
obj, pdf_obj_t value, void *client_data ) pdf_status_t (*pdf_fsys_cleanup_fn_t) (void
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 *data ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
pdf_buffer_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 pdf_status_t (*pdf_fsys_close_fn_t)
pdf_crypt_cipher_t . . . . . . . . . . . . . . . . . . . . . . . . . 162 (pdf_fsys_file_t file ) . . . . . . . . . . . . . . . . 144
pdf_crypt_md_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 pdf_status_t (*pdf_fsys_create_folder_fn_t)
PDF_EBADDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 (pdf_text_t path_name ) . . . . . . . . . . . . . . . . 145
PDF_EDIVBYZERO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 pdf_status_t
PDF_EEOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 (*pdf_fsys_file_cancel_ria_fn_t)
PDF_EINVRANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 (pdf_fsys_file_t file ) . . . . . . . . . . . . . . . . 148
PDF_ENOMATCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 pdf_status_t (*pdf_fsys_file_close_fn_t)
PDF_ENOMEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 (pdf_fsys_file_t file ) . . . . . . . . . . . . . . . . 148
PDF_ENONODE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 pdf_status_t (*pdf_fsys_file_flush_fn_t)
PDF_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 (pdf_fsys_file_t file ) . . . . . . . . . . . . . . . . 145
Data type index 241
Function index
( pdf_fp_string_to_real . . . . . . . . . . . . . . . . . . . . . . . 78
(pdf_real_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 pdf_fsys_build_path . . . . . . . . . . . . . . . . . . . . . . . . 133
(pdf_stm_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 pdf_fsys_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
pdf_fsys_create_folder . . . . . . . . . . . . . . . . . . . . . 128
pdf_fsys_destroy. . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
P pdf_fsys_file_can_set_size_p . . . . . . . . . . . . . . 140
pdf_fsys_file_cancel_ria . . . . . . . . . . . . . . . . . . 143
pdf_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pdf_fsys_file_close . . . . . . . . . . . . . . . . . . . . . . . . 143
PDF_ASSERT_BASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pdf_fsys_file_flush . . . . . . . . . . . . . . . . . . . . . . . . 141
PDF_ASSERT_DOCUMENT . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pdf_fsys_file_get_filesystem . . . . . . . . . . . . . . 136
PDF_ASSERT_OBJECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pdf_fsys_file_get_mode . . . . . . . . . . . . . . . . . . . . . 136
PDF_ASSERT_PAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pdf_fsys_file_get_pos . . . . . . . . . . . . . . . . . . . . . . 138
pdf_buffer_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . 20 pdf_fsys_file_get_size . . . . . . . . . . . . . . . . . . . . . 136
pdf_buffer_eob_p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 pdf_fsys_file_get_url . . . . . . . . . . . . . . . . . . . . . . 137
pdf_buffer_full_p. . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 pdf_fsys_file_has_ria . . . . . . . . . . . . . . . . . . . . . . 142
pdf_buffer_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 pdf_fsys_file_open . . . . . . . . . . . . . . . . . . . . . . . . . 134
pdf_buffer_resize. . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 pdf_fsys_file_open_tmp . . . . . . . . . . . . . . . . . . . . . 135
pdf_buffer_rewind. . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 pdf_fsys_file_read . . . . . . . . . . . . . . . . . . . . . . . . . 140
pdf_char_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160, 161 pdf_fsys_file_reopen . . . . . . . . . . . . . . . . . . . . . . . 143
pdf_crypt_cipher_decrypt . . . . . . . . . . . . . . . . . . 164 pdf_fsys_file_request_ria . . . . . . . . . . . . . . . . . 142
pdf_crypt_cipher_destroy . . . . . . . . . . . . . . . . . . 162 pdf_fsys_file_same_p . . . . . . . . . . . . . . . . . . . . . . . 138
pdf_crypt_cipher_encrypt . . . . . . . . . . . . . . . . . . 163 pdf_fsys_file_set_mode . . . . . . . . . . . . . . . . . . . . . 137
pdf_crypt_cipher_new . . . . . . . . . . . . . . . . . . . . . . . 162 pdf_fsys_file_set_pos . . . . . . . . . . . . . . . . . . . . . . 139
pdf_crypt_cipher_setkey . . . . . . . . . . . . . . . . . . . 163 pdf_fsys_file_set_size . . . . . . . . . . . . . . . . . . . . . 140
pdf_crypt_md_destroy . . . . . . . . . . . . . . . . . . . . . . . 167 pdf_fsys_file_write . . . . . . . . . . . . . . . . . . . . . . . . 141
pdf_crypt_md_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 pdf_fsys_get_folder_contents . . . . . . . . . . . . . . 128
pdf_crypt_md_read . . . . . . . . . . . . . . . . . . . . . . . . . . 167 pdf_fsys_get_free_space . . . . . . . . . . . . . . . . . . . 127
pdf_crypt_md_write . . . . . . . . . . . . . . . . . . . . . . . . . 166 pdf_fsys_get_item_props . . . . . . . . . . . . . . . . . . . 130
pdf_crypt_nonce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 pdf_fsys_get_parent . . . . . . . . . . . . . . . . . . . . . . . . 129
pdf_dealloc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 pdf_fsys_item_p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
PDF_DEBUG_BASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pdf_fsys_item_props_to_hash . . . . . . . . . . . . . . . 130
PDF_DEBUG_DOCUMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pdf_fsys_item_readable_p . . . . . . . . . . . . . . . . . . 132
PDF_DEBUG_OBJECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pdf_fsys_item_writable_p . . . . . . . . . . . . . . . . . . 132
PDF_DEBUG_PAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pdf_fsys_remove_folder . . . . . . . . . . . . . . . . . . . . . 129
pdf_error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 pdf_hash_add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
pdf_fp_atan2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 pdf_hash_add_hash. . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
pdf_fp_ceil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 pdf_hash_add_list. . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
pdf_fp_cos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 pdf_hash_add_size. . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
pdf_fp_exp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 pdf_hash_add_stm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
pdf_fp_floor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 pdf_hash_add_string . . . . . . . . . . . . . . . . . . . . . . . . . 45
pdf_fp_func_0_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 pdf_hash_add_text. . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
pdf_fp_func_2_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 pdf_hash_add_time. . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
pdf_fp_func_3_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 pdf_hash_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
pdf_fp_func_4_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 pdf_hash_element_dealloc_fn . . . . . . . . . . . . . . . . 35
pdf_fp_func_destroy . . . . . . . . . . . . . . . . . . . . . . . . . 85 pdf_hash_get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
pdf_fp_func_eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 pdf_hash_get_hash. . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
pdf_fp_func_get_bounds . . . . . . . . . . . . . . . . . . . . . . 86 pdf_hash_get_list. . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
pdf_fp_log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 pdf_hash_get_size. . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
pdf_fp_log10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 pdf_hash_get_stm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
pdf_fp_matrix_concat . . . . . . . . . . . . . . . . . . . . . . . . 80 pdf_hash_get_string . . . . . . . . . . . . . . . . . . . . . . . . . 45
pdf_fp_matrix_invert . . . . . . . . . . . . . . . . . . . . . . . . 81 pdf_hash_get_text. . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
pdf_fp_matrix_transform . . . . . . . . . . . . . . . . . . . . . 81 pdf_hash_get_time. . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
pdf_fp_matrix_transform_rect . . . . . . . . . . . . . . . 81 pdf_hash_iterator_destroy . . . . . . . . . . . . . . . . . . 35
pdf_fp_real_to_string . . . . . . . . . . . . . . . . . . . . . . . 79 pdf_hash_iterator_new . . . . . . . . . . . . . . . . . . . . . . . 33
pdf_fp_sin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 pdf_hash_iterator_next . . . . . . . . . . . . . . . . . . . . . . 34
Function index 243