Gnu PDF

GNU PDF Library Reference
first Edition, Updated for version trunk.
Free Software Foundation

This is the first edition of the GNU PDF Library Reference, updated for libgnupdf version
trunk.
Copyright c 2007, 2008, 2009 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the
terms of the GNU Free Documentation License, Version 1.3 or any later version
published by the Free Software Foundation; with no Invariant Sections, no
Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included
in the section entitled “GNU Free Documentation License”.
i
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
2.8.1 Floating Point Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

2.8.2 Floating Point Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
2.8.3 Rounding Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
2.8.4 Exponential and Logarithmic Routines . . . . . . . . . . . . . . . . . . . 77
2.8.5 Number Conversion Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
2.8.6 Trigonometric Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
2.8.7 Geometry Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
2.8.8 Other Maths Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
2.8.9 Creation and Destruction of Functions . . . . . . . . . . . . . . . . . . . . 82
2.8.10 Evaluation of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
2.9 Encoded Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
2.9.1 Text Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
2.9.2 Creating and Destroying Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
2.9.3 Managing Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
2.9.4 Managing Text Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
2.9.5 Comparing Text Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
2.9.6 Managing Host Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
2.10 Time Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
2.10.1 Time Related Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
2.10.2 Time Creation and Destruction . . . . . . . . . . . . . . . . . . . . . . . . 106
2.10.3 Managing Time Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
2.10.4 Getting Time Intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
2.10.5 Time Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
2.10.6 Time Printing and Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
2.10.7 Getting the Current Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
2.10.8 Time Span Creation and Destruction . . . . . . . . . . . . . . . . . . . 117
2.10.9 Managing Time Span Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
2.10.10 Time Span Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
2.10.11 Calendar Spans Management. . . . . . . . . . . . . . . . . . . . . . . . . . 122
2.10.12 Platform-specific functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
2.11 The Filesystem Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
2.11.1 Filesystem Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
2.11.2 Filesystem Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
2.11.3 The Filesystem Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
2.11.3.1 Filesystem Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
2.11.3.2 Getting File System Properties . . . . . . . . . . . . . . . . . . . . 127
2.11.3.3 Folder Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
2.11.3.4 Getting File System Item Properties . . . . . . . . . . . . . . . 130
2.11.4 The File Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
2.11.4.1 File Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
2.11.4.2 Opening Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
2.11.4.3 File Properties Management . . . . . . . . . . . . . . . . . . . . . . . 136
2.11.4.4 Comparing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
2.11.4.5 Managing File Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
2.11.4.6 Changing the Size of a File . . . . . . . . . . . . . . . . . . . . . . . . 140
2.11.4.7 Synchronous Input/Output . . . . . . . . . . . . . . . . . . . . . . . . 140
2.11.4.8 Read in Advance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
2.11.4.9 Closing and Reopening Files. . . . . . . . . . . . . . . . . . . . . . . 143
iii
2.11.5 The Filesystem Implementation Interface . . . . . . . . . . . . . . . 144

2.11.5.1 File System Interface Implementation. . . . . . . . . . . . . . 144
2.11.5.2 File Interface Implementation . . . . . . . . . . . . . . . . . . . . . 146
2.11.6 The Filesystem Definition Interface . . . . . . . . . . . . . . . . . . . . . 148
2.11.6.1 File System Definition Data Types . . . . . . . . . . . . . . . . 149
2.11.6.2 File System Definition Functions . . . . . . . . . . . . . . . . . . 149
2.12 The Tokeniser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
2.12.1 Tokeniser data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
2.12.2 Creation and destruction of tokenisers . . . . . . . . . . . . . . . . . . 151
2.12.3 Reading tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
2.12.4 Writing tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
2.12.5 Creating and destroying tokens . . . . . . . . . . . . . . . . . . . . . . . . . 156
2.12.6 Accessing token attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
2.13 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
2.13.1 Creating and destroying Ciphers . . . . . . . . . . . . . . . . . . . . . . . 162
2.13.2 Encryption and decryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
2.13.3 Message digest functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
2.13.4 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
3 Object Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
3.2 PDF Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
3.2.1 Object Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
3.2.2 Generic Functions to Manipulate Objects . . . . . . . . . . . . . . . . 173
3.2.3 Object Strong References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
3.2.4 Compressibility of Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
3.2.5 Object Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
3.2.6 Real Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
3.2.7 Integer Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
3.2.8 Boolean Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
3.2.9 Name Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
3.2.10 String Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
3.2.11 Array Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
3.2.12 Dictionary Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
3.2.13 Stream Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
3.2.14 Null Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
3.3 Object Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
3.3.1 Object Document Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
3.3.2 Opening and Closing Object Documents . . . . . . . . . . . . . . . . . 218
3.3.3 Managing Object Document Properties . . . . . . . . . . . . . . . . . . 222
3.3.4 Retrieving and Storing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 225
3.3.5 Garbage collection in object documents . . . . . . . . . . . . . . . . . . 228
4 Document Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
5 Page Contents Layer . . . . . . . . . . . . . . . . . . . . . . . . . 230

iv
6 Implementation Limits . . . . . . . . . . . . . . . . . . . . . . 231

6.1 Architectural limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
6.2 Memory limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Appendix A GNU Free Documentation License

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Global variable index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Data type index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Function index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Chapter 1: Overview 1
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).
2.2 Error Management

The Error module provides procedures for error reporting to the client as well as for error
tracing (via debug messages) to developers. Here we also define status types returned by
most procedures (there are exceptions though).
2.2.1 Status types

pdf_status_t [Data Type]
A status variable. This type of variable is returned by many library functions in order
to communicate the status of the performed operation.
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
PDF_ENOMATCH [Constant]
No matching found
This list will grow as we get closer to a mature state of development.
2.2.2 Error Reporting procedures

void pdf_perror (const pdf status t status, const char *str ) [Function]
Prints the message corresponding to status to stderr followed by str.
Parameters
status status code
str a user-defined message
Returns nothing
Usage example
pdf_status_t st;
pdf_i64_add (dest, addend_1, addend_2, &st);
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;
pdf_i64_add (dest, addend_1, addend_2, &st);
if (st != PDF_OK)
{
pdf_error (st, logfd, "couldn’t do i64 addition");
}
2.2.3 Debugging procedures

For each layer there is a macro procedure defined. The file name and the line number at
which the error ocurred is printed to stderr followed by message.
PDF_DEBUG_BASE (message, ...) [Macro]
PDF_DEBUG_OBJECT (message, ...) [Macro]
PDF_DEBUG_DOCUMENT (message, ...) [Macro]
PDF_DEBUG_PAGE (message, ...) [Macro]
Parameters
message a ’const char*’ string
... message’s arguments
Returns nothing
Usage example
PDF_DEBUG_BASE("Testing macro ’%s’ ’%d’ ’%lf’", "string", 7, 10.1);
In addition, this module provides a assert macro for each layer.
PDF_ASSERT_BASE (condition) [Macro]
PDF_ASSERT_OBJECT (condition) [Macro]
PDF_ASSERT_DOCUMENT (condition) [Macro]
PDF_ASSERT_PAGE (condition) [Macro]
Parameters
condition a C expression.
Usage example
PDF_ASSERT_BASE (1 == 1);
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.
2.3 Memory Allocation

The memory allocation module provides system-independent heap memory allocation and
deallocation. The usual malloc/free/realloc schema is used to provide this service.
void* pdf_alloc (const pdf size t size ) [Function]
Allocates heap memory.
Parameters
size The requested number of octects to allocate. If this value is
0 then no memory is allocated and NULL is returned.
Returns A pointer to the newly allocated memory.

If there is not enough available memory to satisfy the petition then NULL
is returned.
Usage example
int *p;
p = (int *) pdf_alloc (sizeof(int));

*p = 666;
void pdf_dealloc (const void *pointer ) [Function]

Deallocates heap memory.
Parameters
pointer A pointer pointing to the memory we want to deallocate. The
memory to deallocate should have been previously allocated
using pdf_alloc.
Returns None.
Usage Example
char *p;
p = (char *) pdf_alloc (21);

pdf_dealloc (p);
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;
p = (char *) pdf_alloc (4);

strncpy (p, "abcd", 4);
/* p now points to "abcd" */
p = (char *) pdf_realloc (5);

p[4] = ’e’;
/* p now points to "abcde" */
p = (char *) pdf_realloc (4);
/* p now points to "abcd" */
pdf_dealloc (p);
2.4 Basic Types

2.4.1 Boolean Types
pdf_bool_t [Data Type]
A boolean value.
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.
2.4.2 Numeric Types

pdf_i32_t [Data Type]
Signed 32 bits integer.
pdf_u32_t [Data Type]

Unsigned 32 bits integer.
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.
PDF_U32_MIN [Constant]
Minimum value able to be stored in a pdf_u32_t variable.
2.4.3 Big Numbers

An implementation of big numbers (64 bit) is also provided. This data type can be used in
machines not providing true 64 bit integers.
pdf_i64_t [Data Type]

A variable of type pdf i64 t is capable of representing a 64 bit signed integer.
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;
bignum = pdf_i64_new((1 << 31),10); /*bignum is now -10*/
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;
pdf_i64_assign(bignum, (1 << 31), 10, p_status);

if (*p_status != PDF_OK) /*bignum is now -10*/
{
/* Error code */
}
void pdf_i64_assign_quick (pdf i64 t *bignum, const pdf i32 t [Function]
value, pdf status t *p_status )
Assign a value coming from one 32 bit signed integer to a 64 bit signed integer.
Note that if the client is in a system supporting true 64 bit scalar types, pdf_i64_
assign_quick will be a macro that will also accept a 64 bit value.
Parameters
value A signed 32 bit integer
bignum Variable that stores 64 bit integer
PDF_EBADDATA
Usage example
pdf_i64_t *bignum;
pdf_i64_t result;
bignum = &result;
pdf_i64_assign_quick(bignum, -10, p_status);
if (*p_status != PDF_OK) /*bignum is now -10*/
{
/* Error code */
}
void pdf_i64_copy (const pdf i64 t orig, pdf i64 t *copy, pdf status t [Function]
*p_status )
Copies the data from orig to copy.
Parameters
orig Original variable whose data is to be copied.
copy Variable where data is copied to.
PDF_EBADDATA
Usage example
pdf_i64_t orig;
pdf_i64_t *copy;
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
PDF_EBADDATA
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t addend_1;
pdf_i64_t addend_2;
addend_1 = pdf_i64_new(0, 25);
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.
Parameters
addend1 First addend of the sum (64bit type)
addend2 Second addend of the sum (32 bit)
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t addend_1;
dest = &result;
pdf_i64_add (dest, addend_1, 35,p_status)
{
/* Error code */
}
void pdf_i64_subtraction (pdf i64 t *dest, const pdf i64 t [Function]

minuend, const pdf i64 t subtrahend, pdf status t *p_status )
Finds the difference between two 64 bit numbers
Parameters
minuend The minuend of the subtraction
subtrahend
The subtrahend of the subtraction
PDF_EBADDATA
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t minuend;
pdf_i64_t subtrahend;
minuend = pdf_i64_new(0, 25);
subtrahend = pdf_i64_new(0, 35);
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)
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t subtrahend;
subtrahend = pdf_i64_new(0, 35);
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
Parameters
minuend The minuend of the subtraction (64 bits type)
subtrahend
The subtrahend of the subtraction (32 bits)
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t minuend;
minuend = pdf_i64_new(0, 25);
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
PDF_EBADDATA
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t factor_1;
pdf_i64_t factor_2;
factor_1 = pdf_i64_new (0, 10);
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)
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t factor_1;

dest = &result;
pdf_i64_mult (dest, factor_1, 100,p_status)
{
/* Error code */
}
void pdf_i64_div (pdf i64 t *dest, const pdf i64 t dividend, const [Function]
pdf i64 t divisor, pdf status t *p_status )
Division of two 64 bit numbers
Parameters
dividend The dividend in the division
divisor The divisor in the division
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;
dividend = pdf_i64_new(0, 200);

divisor = pdf_i64_new(0, 10);
dest = &result;
pdf_i64_div (dest, dividend, divisor,p_status);
if(*p_status != PDF_OK) /* Now dest is 20 */
{
/* Error code */
}
void pdf_i64_div_i32_dividend (pdf i64 t *dest, const pdf i32 t [Function]
dividend, const pdf i64 t divisor, pdf status t *p_status )
Division of a 32bit number and a 64bit number
Parameters
dividend The dividend in the division (64 bits)
divisor The divisor in the division (32 bits)
Returns A PDF status value:
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t divisor;

dest = &result;
if (pdf_i64_div (dest, 200, divisor) != PDF_OK) /* Now dest is 20 */

{
/* Error code */
}
void pdf_i64_div_i32_divisor (pdf i64 t *dest, const pdf i64 t [Function]

Division of a 64bit number and a 32bit number
Parameters
PDF_OK Operation successful.
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t dividend;

dest = &result;
if (pdf_i64_div (dest, dividend, 10) != PDF_OK) /* Now dest is 20 */

{
/* Error code */
}
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
divisor The divisor in the division

PDF_EBADDATA
dest is null
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t dividend;
pdf_i64_t divisor;
dest = &result;
pdf_i64_mod (dest, dividend, divisor,p_status);
if ( *p_status != PDF_OK) /* Now dest is 5 */
{
/* Error code */
}
void pdf_i64_mod_i32_dividend (pdf i64 t *dest, const pdf i32 t [Function]
Returns the remainder of the division between a 32 bit number and a 64 bit number
Parameters
dividend The dividend in the division (32bits)
divisor The divisor in the division (64bits)
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t divisor;

dest = &result;
if (pdf_i64_mod (dest, 105, divisor) != PDF_OK) /* Now dest is 5 */

{
/* Error code */
}
void pdf_i64_mod_i32_divisor (pdf i64 t *dest, const pdf i64 t [Function]
Returns the remainder of the division between a 64 bit number and a 32 bit number
Parameters
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t dividend;

dest = &result;
if (pdf_i64_mod (dest, dividend, 10) != PDF_OK) /* Now dest is 5 */

{
/* Error code */
}
void pdf_i64_abs (pdf i64 t *dest, const pdf i64 t number, [Function]
pdf status t *p_status )
Returns the absolute value
Parameters
number pdf i64 t type variable

PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t number;
number = pdf_i64_new ((1 << 31), 105); /*number is -105*/
dest = &result;
pdf_i64_abs (dest, number,p_status)
if ( *p_status != PDF_OK) /* now dest stores 105 */
{
/* Error code */
}
int pdf_i64_cmp (const pdf i64 t number_1, const pdf i64 t number_2 ) [Function]
Compares two 64 bit integers
Parameters
number 1 pdf i64 t type variable
Returns An integer:
0 If numbers are equal
1 If number 1 is greater than number 2
-1 If number 2 is greater than number 1
Usage example
pdf_i64_t number_1;
pdf_i64_t number_2;
int result;
number_1 = pdf_i64_new ((1 << 31), 10); /* number_1 is -10 */

number_2 = pdf_i64_new (0, 10); /* number_2 is 10 */
result = pdf_i64_cmp (number_1, number_2); /* Now result is -1 */
int pdf_i64_cmp_i32 (const pdf i64 t number_1, const pdf i32 t [Function]
number_2 )
Compares a 64 bit number and a 32 bit number
Parameters

Returns An integer:
0 If numbers are equal
1 If number 1 is greater than number 2
-1 If number 2 is greater than number 1
Usage example
pdf_i64_t number_1;
int result;
number_1 = pdf_i64_new ((1 << 31), 10); /* number_1 is -10 */

result = pdf_i64_cmp (number_1, 10); /* Now result is -1 */
void pdf_i64_neg (pdf i64 t *dest, const pdf i64 t number, [Function]
pdf status t *p_status )
Changes sign of 64 bit integer
Parameters
number pdf i64 t type variable
PDF_EBADDATA
NULL value in dest.
Usage example
pdf_i64_t *dest;
pdf_i64_t result;
pdf_i64_t number;
number = pdf_i64_new (0, 10);
dest = &result;
pdf_i64_neg (dest, number,p_status)
if ( *p_status != PDF_OK) /* now dest stores -10 */
{
/* Error code */
}
pdf_i32_t pdf_i64_to_i32 (const pdf i64 t bignum ) [Function]
Converts a pdf i64 t to a 32 bit value. If number can’t be represented in 32 bits the
result is undefined, so should be used with caution.
Parameters
bignum pdf i64 t type variable

Usage example
pdf_i32_t num;
pdf_i64_t bignum;
bignum = pdf_i64_new (0, 10);
num = pdf_i64_to_i32(bignum);
2.4.4 Memory Buffers

struct pdf_buffer_s [Data Type]
This structure contains the data associated to a simple memory buffer.
data Pointer to the buffer contents.
size Number of octects allocated in data.
rp Current read pointer.
wp Current write pointer.
pdf_buffer_t [Data Type]

Pointer to a pdf_buffer_s structure.
pdf_buffer_t pdf_buffer_new (pdf size t size ) [Function]

Create a new memory buffer.
Parameters
size The size of the new buffer, in octects.
Returns A pointer to a pdf_buffer_s structure, or NULL if there is not enough
memory to serve the petition.
Usage example
pdf_buffer_t my_buffer;
my_buffer = pdf_buffer_new (1024);

if (my_buffer == NULL)
{
/* Not enough memory */
}
pdf_status_t pdf_buffer_destroy (pdf buffer t buffer ) [Function]

Destroy a memory buffer.
Parameters
buffer A pointer to the buffer that will be destroyed.
PDF_OK The operation suceeded.

Usage example

pdf_buffer_destroy (my_buffer);
pdf_bool_t pdf_buffer_full_p (pdf buffer t buffer ) [Function]

Determine whether a memory buffer is full.
Parameters
buffer A pointer to a buffer.
Returns A PDF boolean value:
PDF_OK The buffer is full.
PDF_FALSE
The buffer is not full.
Usage example
int i;
/* Create a new buffer */

/* Fill the entire buffer */

for (i = 0; i < 1024; i++)
{
my_buffer->data[my_buffer->wp++] = ’a’;
}
/* The buffer should be full now */

if (pdf_buffer_full_p (my_buffer))
{
/* Buffer full */
}
pdf_buffer_destroy (my_buffer);
pdf_bool_t pdf_buffer_eob_p (pdf buffer t buffer ) [Function]

Determine whether a memory buffer is in an end-of-buffer state.
Parameters
buffer A pointer to a memory buffer.
PDF_TRUE The buffer is in an end-of-buffer state.
PDF_FALSE
The buffer is not in an end-of-buffer state.
Usage example
pdf_char_t my_char;

/* Copy some contents into the buffer, filling it entirely */

strncpy (my_buffer->data, "abc", 3);
my_buffer->wp += 3;
/* Read data from the buffer until an eob condition */

while (!pdf_buffer_eob_p (my_buffer))
{
my_char = my_buffer->data[my_buffer->rp++];
}
pdf_status_t pdf_buffer_resize (pdf buffer t buffer, pdf size t [Function]

newsize )
Resize a memory buffer.
Parameters
newsize The new size (in octects) for the buffer.
Returns A PDF status variable:
PDF_OK The operation succeeded.
PDF_ENOMEM
Not enough memory to perform the operation.
Usage example
pdf_char_t my_char;
pdf_char_t *my_string;
pdf_size_t my_string_size;
pdf_size_t written_bytes;
/* Create a string */
my_string_size = 10;
my_string = pdf_alloc (my_string_size);
strncpy (my_string, "0123456789", 10);
my_string[10] = 0;

/* Copy the contents of my_string into my_buffer making it larger in

chunks of 4 bytes */
written_bytes = 0;
while (written_bytes < my_string_size)
{
if (pdf_buffer_full_p (my_buffer))
{
/* Grow the buffer */
pdf_buffer_resize (my_buffer,
my_buffer->wp + 5);
}
my_buffer->data[my_buffer->wp] = my_string[my_buffer->wp];
my_buffer->wp++;
}
/* Adjust the buffer size */

pdf_buffer_resize (my_buffer, my_string_size);
pdf_status_t pdf_buffer_rewind (pdf buffer t buffer ) [Function]
Rewind a memory buffer.
Parameters
Usage example
/* Create a new buffer and initialize its contents */

strncpy (my_buffer->data, "abc", 3);
my_buffer->wp += 3;
/* Replace the contents */

pdf_buffer_rewind (my_buffer);
strncpy (my_buffer->data, "ABC", 3);
my_buffer->wp += 3;
2.4.5 Progress Monitors

The client application of the library may want to monitor the progress of some operations,
such as the saving of a document. The struct pdf_pm_s structure provides a way for the
client application to specify callbacks implemented by a progress monitor.
struct pdf_pm_s [Data Type]
Structure containing several callbacks to be called as an operation progress.
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.
pdf_status_t (*pdf_pm_begin_operation_fn_t) (void [Data Type]

*client_data )
Callback implemented by a progress monitor that initializes it to a current value of
0.
Parameters
client data
User supplied data.
Returns This callback should return PDF_OK to the caller.
pdf_status_t (*pdf_pm_end_operation_fn_t) (void [Data Type]

*client_data )
Callback implemented by a progress monitor. This callback is called at the end of
the operation.
Parameters
client data
User supplied data.
pdf_status_t (*pdf_pm_get_duration_fn_t) (void [Data Type]

*client_data, void *duration )
Callback implemented by a progress monitor.
This callback is called to get the current value of the progress monitor duration.
Parameters
client data
User supplied data.
duration A pointer to a pdf time span t variable to store the current
duration of the progress monitor.
pdf_status_t (*pdf_pm_set_duration_fn_t) (void [Data Type]

This callback is called to set the current value of the progress monitor duration.
Parameters
client data
User supplied data.
duration A pointer to a time span variable containing the new duration
for the progress monitor.
pdf_status_t (*pdf_pm_get_current_value_fn_t) (void [Data Type]

This callback is called to get the current value of the progress monitor duration.
Parameters
client data
User supplied data.
duration A pointer to a pdf time span t variable to store the current
duration of the progress monitor.
pdf_status_t (*pdf_pm_set_current_value_fn_t) (void [Data Type]

This callback is called to set the current value of the progress monitor duration.
Parameters
client data
User supplied data.
duration A time span variable containing the new duration for the
progress monitor.
pdf_status_t (*pdf_pm_set_text_fn_t) (void *client_data, [Data Type]

void *text )
This callback is called to set the description of the current status of the operation to
the progress monitor.
Parameters
client data
User supplied data.
text A text variable containing the new description.
2.4.6 Universal Unique Identifiers

The basic types module provides an implementation of the ITU X.667 Recommendation for
the generation of Universal Unique Identifiers, also known as Globally Unique Identifiers or
GUIDs.
Each UUID is a hexadecimal-coded ascii sequence composed by the following fields, sepa-
rated by the ascii hyphen-minus, 45 character, except between the VariantAndClockSeqHigh
and ClockSeqLow:
− TimeLow (4 bytes => 8 hexadecimal digits)
− TimeMid (2 bytes => 4 hexadecimal digits)
− VersionAndTimeHigh (2 bytes => 4 hexadecimal digits)
− VariantAndClockSeqHigh (1 byte => 2 hexadecimal digits)
− ClockSeqLow (1 octect => 2 hexadecimal digits)
− Node (6 octects => 12 hexadecimal digits)
An example of an UUID would be:
00000000-0000-0000-0000-000000000000
There are three standardized ways to generate the values of those fields:
− time-based
− random-based
− name-based
Note that, according to the ITU recommendation, uuid generators should produce lower-
case letters in hexadecimal encoding. On the other hand, it is recommended for uuid
consumers to be case-insensitive regarding alphabetic characters in hexadecimal strings.
This implementation follows both recommendations.
Note also that the time-based method makes use of the MAC address of the primary
network card installed in the system. If the library is running in a system where no such
information is available then a standardized alternative random method is used.
pdf_uuid_t [Data Type]

Opaque type representing an Universally Unique Identifier.
enum pdf_uuid_type_e [Data Type]

Type of an UUID:
PDF_UUID_TIME
Time-based UUID as defined by ITU X.667.
PDF_UUID_RANDOM
Random-based UUID as defined by ITU X.667.
PDF_UUID_NAME
Name-based UUID as defined by ITU X.667.
pdf_uuid_t pdf_uuid_generate (enum pdf uuid type e type ) [Function]

Generate a new UUID of the specified type.
Parameters
type The type of UUID to generate.
Returns The generated UUID.
Usage example
pdf_uuid_t uuid;
/* Generate a name-based UUID. */

uuid = uuid_generate (PDF_UUID_NAME);
const char * pdf_uuid_string (pdf uuid t uuid ) [Function]
Return an ASCII string with the printed representation of uuid.
Parameters
uuid A previously generated UUID.
Returns A null-terminated buffer containing the printed representation of uuid.
Usage example
pdf uuid t uuid;
uuid = pdf uuid generate (PDF UUID TIME); printf ("The generated
UUID: %s\n", pdf uuid string (uuid));
pdf_bool_t pdf_uuid_equal_p (pdf uuid t uuid1, pdf uuid t uuid2 ) [Function]
Determine if two given UUIDs are equal.
Parameters
uuid1 The first UUID to compare.
uuid2 The second UUID to compare.
Returns A PDF boolean indicating whether both UUIDs are equal.
Usage example
pdf_uuid_t uuid1;
pdf_uuid_t uuid2;
uuid1 = pdf_uuid_generate (PDF_TIME);

uuid2 = pdf_uuid_generate (PDF_TIME);
if (pdf_uuid_equal_p (uuid1, uuid2))

{
/* Extremely unlikely! */
}
2.5 Hash Tables

2.5.1 Hash Table Types
pdf_hash_t [Data Type]
A Hash Table able to store key/value pairs. A key may be any NULL-terminated
string.
pdf_hash_iterator_t [Data Type]

An iterator over the keys of a Hash Table.
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.
2.5.2 Creating and Destroying Hash Tables

pdf_status_t pdf_hash_new (pdf hash key dispose fn t [Function]
dispose_key_fn, pdf hash t *table )
Create a new empty hash table. When some element is removed dispose key fn are
called, can be NULL.
Parameters
dispose key fn
A pointer to a hash table element key dispose function or
NULL.
table A pointer to a hash table.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Invalid table pointer.
Usage example
pdf_hash_t hash;
/* Create an instance of a hash without a disposal function */

if (pdf_hash_new (NULL, &hash) != PDF_OK)
{
/* Error creating the hash table */
}
pdf_status_t pdf_hash_destroy (pdf hash t table ) [Function]

Destroy a hash table. The elements of the table are disposed first.
Parameters
table A hash table.
Usage example
pdf_hash_t hash;
if (pdf_hash_new (NULL, &hash) == PDF_OK)

{
/* Destroy the hash */
pdf_hash_destroy (hash);
}
else
{
/* Error creating the hash table */
}
2.5.3 Hash Table properties

pdf_size_t pdf_hash_size (const pdf hash t table ) [Function]
Returns the number of entries in table.
Parameters
table A hash table.
Returns The number of entries.
Usage example
pdf_hash_t hash;
/* Create a new hash */

{
/* 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);
/* This call should return 3 */

pdf_hash_size (hash);
}
2.5.4 Working with keys

pdf_bool_t pdf_hash_key_p (const pdf hash t table, const char [Function]
*key )
Returns a boolean value indicating whether an element with key key exists in table.
Parameters
table A hash table.
key A valid key string.
Returns A pdf boolean value:
PDF_TRUE An element associated with key exists.

PDF_FALSE
There is no element associated with key.
Usage example
pdf_hash_t hash;

{
pdf_hash_add (hash, "a-key", "a-value", NULL);
if (pdf_hash_key_p (hash, "a-key"))

{
/* The program enters here */
}
if (pdf_hash_key_p (hash, "x-key"))
{
/* The program doesnt reach this */
}
}
pdf_status_t pdf_hash_rename (pdf hash t table, const char *key, [Function]

const char *new_key )
Renames the key key to new key in table.
Parameters
table A hash table.
new key A valid key string.
PDF_OK The operation succeded.
PDF_ERROR
The key is not associated with any element in table.
PDF_EBADDATA
Either table or a key string is invalid or NULL.
PDF_ENOMEM
Usage example
pdf_hash_t hash;

{
/* Add an element to the hash */

{
}
/* Rename the key */

pdf_hash_rename (hash, "a-key", "b-key");

{
/* The program doesnt enter here */
}
if (pdf_hash_key_p (hash, "b-key"))

{
}
}
2.5.5 Adding and removing elements

pdf_status_t pdf_hash_add (pdf hash t table, const char *key, [Function]
const void *element, pdf hash element dispose fn t disp_fn )
Adds the element element with the associated key key to table. If key already exists
nothing is done.
Parameters
table A hash table.
element A pointer to the element being added.
disp fn A function called when element is removed. If NULL is given
nothing is done.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Either table, key or element is invalid.
Usage example
pdf_hash_t hash;

{
}
pdf_status_t pdf_hash_remove (pdf hash t table, const char *key ) [Function]

Removes the element associated with key from table. The element is disposed first.
Parameters
table A hash table.
PDF_EBADDATA
Invalid table or key.
PDF_ERROR
The key wasn’t found.
Usage example
pdf_hash_t hash;

{
/* Add an element to the hash... */
/* And remove it */
pdf_hash_remove (hash, "a-key");
}
2.5.6 Searching elements

pdf_status_t pdf_hash_get (const pdf hash t table, const char [Function]
*key, const void **elem_pointer )
Searches for the element associated with the given key in table and store it in
elem pointer.
Parameters
table A hash table.
key A valid null-terminated string key.
elem pointer
A pointer where to store the element.
PDF_EBADDATA
Either elem pointer is NULL, key or the table is invalid.
PDF_ERROR
Usage example
pdf_hash_t hash;
char *elem;

{
/* Add an element to the hash... */
/* Get the element from the hash */

pdf_hash_search (hash, "a-key", (void **) &elem);
}
2.5.7 Working with iterators

pdf_status_t pdf_hash_iterator_new (const pdf hash t table, [Function]
pdf hash iterator t *iterator )
Creates an iterator over the keys of table and saves it in iterator. Keys composed only
by numbers are returned first followed by keys in the order imposed by the “strcmp()”
function.
Parameters
table A hash table.
iterator A pointer to an iterator.
PDF_EBADDATA
Either iterator is NULL or table is invalid.
Usage example
pdf_hash_t hash;
pdf_hash_iterator_t hash_iter;

{
/* Get an iterator to the first element of the hash */

pdf_hash_iterator_new (hash, &hash_iter);
}
pdf_status_t pdf_hash_iterator_next (pdf hash iterator t [Function]

iterator, const char **key )
Retrieves the next key from iterator.
Parameters
iterator A Hash Table iterator pointer.
key A pointer where to save the key.
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_char_t *key;

{
/* Traverse all the values of the hash with an iterator */

while (pdf_hash_iterator_next (hash_iter, &key) != PDF_ERROR)
{
/* key contains the next key */
}
}
pdf_status_t pdf_hash_iterator_destroy (pdf hash iterator t [Function]

iterator )
Free all resources used by iterator.
Parameters
iterator A Hash Table iterator pointer.
Usage example
pdf_hash_t hash;

{
/* Get an iterator to the first element of the hash */

/* Destroy the iterator */

pdf_hash_iterator_destroy (hash_iter);
}
2.5.8 Basic dispose functions

These are the basic function implementations to free elements and keys. They should only
be used if you allocated elements/keys with pdf alloc() and don’t need to free any other
resource.
void pdf_hash_element_dealloc_fn (const void * elt ) [Function]

Deallocates elt with pdf dealloc().
Parameters
elt A pointer to the element being freed.
Returns Nothing.
Usage example
pdf_hash_t hash;
pdf_char_t *elem;

{
/* Allocate memory for a value to be inserted into the hash */

elem = pdf_alloc (sizeof(pdf_char_t) * 4);
strcpy ((char *) elem, "abc");
/* Add an element to the hash, specifying

pdf_hash_element_dealloc_fn as its disposal
function */
pdf_hash_add (hash,
"a-key",
(void *) elem,
pdf_hash_element_dealloc_fn);
/* Destroy the hash (the disposal function invokes pdf_dealloc

in the allocated string */
}
void pdf_hash_key_dealloc_fn (const void * elt ) [Function]

Deallocates elt with pdf dealloc().
Parameters
elt A pointer to the element being freed.
Returns Nothing.
Usage example
pdf_hash_t hash;
pdf_char_t *key;

if (pdf_hash_new (pdf_hash_key_dealloc_fn, &hash) == PDF_OK)
{
/* Allocate memory for a key to be used into the hash */
key = pdf_alloc (sizeof(pdf_char_t) * 4);
strcpy ((char *) elem, "abc");
/* Add an element to the hash, using the key */

pdf_hash_add (hash, key, "abc", NULL);
/* Destroy the hash (the key disposal function invokes pdf_dealloc

in the allocated string */
}
2.5.9 Hash helper functions

These are specific functions for adding and getting different types of elements (types defined
by the library). They guarantee that when an element of one of these types is removed from
a hash table the correct disposal function is called.
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_status_t pdf_hash_add_text (pdf hash t table, const char [Function]

*key, const pdf text t *elt )
Adds the text elt with the associated key key to table. If key already exists nothing
is done.
Parameters
table A hash table.
elt A pointer to the element being added.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Either table, key or elt is invalid.
Usage example
pdf_hash_t hash;
pdf_text_t elem;

{
/* Create the element for the hash */
pdf_text_new_from_unicode ("abc", 3,
PDF_TEXT_UTF8,
&hash);
/* Add an element to the hash, specifying

pdf_hash_element_dealloc_fn as its disposal
function */
pdf_hash_add_text (hash, "a-key", &elem);

}
pdf_status_t pdf_hash_get_text (pdf hash t table, const char [Function]

*key, pdf text t *elt )
Get a text variable from a hash table.
Parameters
table The hash table to get the value from.
key The key associated with the desired value.

elt A pointer to the text variable to hold the value.
PDF_OK The value was successfully stored into elt.
PDF_EBADDATA
Either elt is NULL, key or the table is invalid.
PDF_ERROR
Usage example
pdf_text_t text;
pdf_hash_t table;
/* ... insert a text variable into the hash ... */

if (pdf_hash_get_text (table, "a text", &text) != PDF_OK)
{
/* Error */
}
pdf_status_t pdf_hash_add_time (pdf hash t table, const char [Function]
*key, const pdf time t *elt )
Adds the time elt with the associated key key to table. If key already exists nothing
is done.
Parameters
table A hash table.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Usage example
pdf_hash_t hash;
pdf_time_t elem;

{
pdf_time_new (&elem);

pdf_hash_add_time (hash, "a-key", &elem);

}
pdf_status_t pdf_hash_get_time (pdf hash t table, const char [Function]

*key, pdf time t *elt )
Get a time variable from a hash table.
Parameters
elt A pointer to the time variable to hold the value.
PDF_EBADDATA
PDF_ERROR
Usage example
pdf_time_t time;
pdf_hash_t table;
/* ... insert a time variable into the hash ... */

if (pdf_hash_get_time (table, "a time", &time) != PDF_OK)
{
/* Error */
}
pdf_status_t pdf_hash_add_list (pdf hash t table, const char [Function]

*key, const pdf list t *elt )
Adds the list elt with the associated key key to table. If key already exists nothing
is done.
Parameters
table A hash table.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Usage example
pdf_hash_t hash;
pdf_list_t elem;

{
pdf_list_new (&elem);

pdf_hash_add_list (hash, "a-key", &elem);

}
pdf_status_t pdf_hash_get_list (pdf hash t table, const char [Function]
*key, pdf list t *elt )
Get a list variable from a hash table.
Parameters
elt A pointer to the list variable to hold the value.
PDF_EBADDATA
PDF_ERROR
Usage example
pdf_list_t list;
pdf_hash_t table;
/* ... insert a list variable into the hash ... */

if (pdf_hash_get_list (table, "a list", &list) != PDF_OK)
{
/* Error */
}
pdf_status_t pdf_hash_add_hash (pdf hash t table, const char [Function]

*key, const pdf hash t *elt )
Adds the hash table elt with the associated key key to table. If key already exists
nothing is done.
Parameters
table A hash table.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Usage example
pdf_hash_t hash;
pdf_hash_t elem;

{
pdf_hash_new (&elem);

pdf_hash_add_hash (hash, "a-key", &elem);

}
pdf_status_t pdf_hash_get_hash (pdf hash t table, const char [Function]

*key, pdf hash t *elt )
Get a hash variable from a hash table.
Parameters
elt A pointer to the hash variable to hold the value.
PDF_EBADDATA
PDF_ERROR
Usage example
pdf_hash_t hash;
pdf_hash_t table;
/* ... insert a hash variable into the hash ... */

if (pdf_hash_get_hash (table, "a hash", &hash) != PDF_OK)
{
/* Error */
}
pdf_status_t pdf_hash_add_stm (pdf hash t table, const char *key, [Function]
const pdf stm t *elt )
Adds the stream elt with the associated key key to table. If key already exists nothing
is done.
Parameters
table A hash table.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Usage example
pdf_hash_t hash;
pdf_stm_t elem;
pdf_char_t *buf;

{
buf = pdf_alloc (10);
pdf_stm_mem_new (buf,
10,
0, /* Use default cache size */
PDF_STM_READ,
&stm);
/* Add the element to the hash */

pdf_hash_add_hash (hash, "a-key", &elem);

/* Destroy the memory buffer */

pdf_dealloc (buf);
}
pdf_status_t pdf_hash_get_stm (pdf hash t table, const char *key, [Function]

pdf stm t *elt )
Get a stm variable from a hash table.
Parameters
elt A pointer to the stm variable to hold the value.
PDF_EBADDATA
PDF_ERROR
Usage example
pdf_stm_t stm;
pdf_hash_t table;
/* ... insert a stm variable into the hash ... */

if (pdf_hash_get_stm (table, "a stm", &stm) != PDF_OK)
{
/* Error */
}
pdf_status_t pdf_hash_add_size (pdf hash t table, const char [Function]

*key, const pdf size t elt )
Adds the pdf_size_t value elt with the associated key key to table. If key already
exists nothing is done.
Parameters
table A hash table.
elt A pdf_size_t value.

PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Usage example
pdf_hash_t hash;
pdf_size_t elem;

{
elem = 10;

pdf_hash_add_size (hash, "a-key", elem);


pdf_dealloc (buf);
}
pdf_status_t pdf_hash_get_size (pdf hash t table, const char [Function]
*key, pdf size t *elt )
Get a size variable from a hash table.
Parameters
elt A pointer to the size variable to hold the value.
PDF_EBADDATA
PDF_ERROR
Usage example
pdf_size_t size;
pdf_hash_t table;
/* ... insert a size variable into the hash ... */

if (pdf_hash_get_size (table, "a size", &size) != PDF_OK)
{
/* Error */
}
pdf_status_t pdf_hash_add_string (pdf hash t table, const char [Function]
*key, const pdf char t *elt )
Adds the *pdf_char_t value elt with the associated key key to table. If key already
exists nothing is done.
Parameters
table A hash table.
elt A * pdf_char_t value.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
Usage example
pdf_hash_t hash;
pdf_char_t *elem;

{
elem = pdf_alloc(4);
strncpy (elem, "abc", 4);

pdf_hash_add_size (hash, "a-key", elem);


pdf_dealloc (buf);
}
pdf_status_t pdf_hash_get_string (pdf hash t table, const char [Function]
*key, pdf char t **elt )
Get a string variable from a hash table.
Parameters
elt A pointer to the string variable to hold the value.
PDF_EBADDATA
PDF_ERROR
Usage example
pdf_char_t *string;
pdf_hash_t table;
/* ... insert a string variable into the hash ... */

if (pdf_hash_get_string (table, "a string", &string) != PDF_OK)
{
/* Error */
}
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.
2.6.1 List Data Types

pdf_list_t [Data Type]
A list composed by zero or more nodes.
pdf_list_node_t [Data Type]

A list node. Each node is able to contain a data structure via a void npointer.
pdf_list_iterator_t [Data Type]

A list iterator.
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.
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.
2.6.2 Creating and Destroying Lists

pdf_status_t pdf_list_new (pdf list element equals fn t equals_fn, [Function]
pdf list element dispose fn t dispose_fn, const pdf bool t
allow_duplicates, pdf list t *list )
Create a new list containing no elements.
Parameters
equals fn A function to compare list elements. It is used in sort oper-
ations.
dispose fn A function to dispose list elements. It is used when destroying
list elements.
allow duplicates
This parameter indicate if the list is allowed to contain du-
plicate elements (elements for which equals fn evaluate to
PDF_TRUE).
list A pointer to a list where the new one will be saved.
Returns A status variable:
PDF_OK list contains a new empty list.
PDF_EBADDATA
list points to NULL.
PDF_ENOMEM
Not enough memory to create the list.
Usage example
pdf_list_t mylist;
if (pdf_list_new (list_element_equal_p, list_element_destroy, PDF_FALSE

&mylist) != PDF_OK)
{
/* manage the error... */
}
pdf_status_t pdf_list_destroy (pdf list t list ) [Function]
Destroy a list freeing all used resources. The elements of the list are disposed first.
Parameters
list The list to be destroyed.

Usage example
pdf_list_t mylist;
/* ...create ‘mylist’... */
pdf_list_destroy (mylist);
2.6.3 Managing List Properties

pdf_size_t pdf_list_size (const pdf list t list ) [Function]
Get the number of elements contained into a given list.
Parameters
list A list.
Returns The number of elements inside list.
Usage example
pdf_list_t mylist;
pdf_size_t num_elm;
/* ...insert some elements into ‘mylist’... */

num_elm = pdf_list_size (mylist);
2.6.4 Searching for List Elements

pdf_status_t pdf_list_search (const pdf list t list, const void* [Function]
element, pdf list node t *node )
Search whether an element is already in the list.
Parameters
list A list.
element The element to search for.
node The searched node if it was found.
PDF_ENONODE
element not found.
PDF_EBADDATA
Invalid node pointer.
Usage example
pdf_list_t list;
pdf_list_node_t node;
int elem;
/* Create the list */

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_first (list, (void *) &elem, NULL);
/* Search for that element into the list */

if (pdf_list_search (list, (void *) &elem, &node) == PDF_OK)
{
/* The program should reach this place */
}
}
pdf_status_t pdf_list_search_from (const pdf list t list, const [Function]

pdf size t start_index, const void* element, pdf list node t *node )
Search whether an element is already in the list, at a position >= start index.
Parameters
list A list.
start index
Index indicating the begin of the search.
PDF_ENONODE
element not found.
PDF_EBADDATA
PDF_EINVRANGE
start index is greater than the list size or less than 0.
Usage example
pdf_list_t list;
int elem1;
int elem2;
int elem3;

&list) == PDF_OK)
{
/* Insert several elements into the list */
pdf_list_add_last (list, (void *) &elem1, NULL);
/* Search for an element into the list */

if (pdf_list_search_from (list,
(void *) &elem1,
1,
&node) == PDF_OK)
{
/* The program should never reach this place, since
elem1 occupies the first position (0) in the list */
}
}
pdf_status_t pdf_list_search_from_to (const pdf list t list, [Function]

const pdf size t start_index, const pdf size t end_index, const void*
Search whether an element is already in the list, at a position >= start index and <
end index.
Parameters
list A list.
start index
Index to the first list position to be searched.
end index Index to the last list position to be searched.
node The seached node if it was found.
PDF_ENONODE
element not found.
PDF_EBADDATA
PDF_EINVRANGE
start index or end index is greater than the list size or less
than 0.
Usage example
pdf_list_t list;
int elem1;
int elem2;
int elem3;
int elem4;
&list) == PDF_OK)
{
/* Search for an element into the list */

if (pdf_list_search_from_to (list,
(void *) &elem4,
1, 3,
&node) == PDF_OK)
{
/* The program should never reach this place, since
elem4 occupies the last position (3) in the list */
}
}
pdf_status_t pdf_list_next_node (const pdf list t list, const [Function]

pdf list node t node, pdf list node t *next )
Return the node immediately after the given node in the list.
Parameters
list A list.
node A node contained in list.
prev A pointer where the next node will be saved.
PDF_ENONODE
Next node not found.
PDF_EBADDATA
Invalid next pointer.
Usage example
pdf_list_t list;
pdf_list_node_t node_first;
pdf_list_node_t node_second;
int elem1;
int elem2;
&list) == PDF_OK)
{
/* Get the node containing "elem1" */

pdf_list_search (list, (void *) &elem1, &node_first);
/* Get the next node in the list */

pdf_list_next_node (list, first_node, &node_second);
/* Now node_second is the node containing elem2 */

}
pdf_status_t pdf_list_previous_node (const pdf list t list, const [Function]

pdf list node t node, pdf list node t *prev )
Return the node immediately before the given node in the list.
Parameters
list A list.
node A node contained in list.
prev A pointer where the previous node will be saved.
PDF_ENONODE
Previous node not found.
PDF_EBADDATA
Invalid prev pointer.
Usage example
pdf_list_t list;
int elem1;
int elem2;
&list) == PDF_OK)
{
/* Get the node containing "elem2" */

pdf_list_search (list, (void *) &elem2, &node_second);
/* Get the previous node in the list */

pdf_list_previous_node (list, second_node, &node_first);
/* Now node_first is the node containing elem2 */

}
pdf_status_t pdf_list_indexof (const pdf list t list, const void* [Function]

element, pdf size t *position )
Parameters
list A list.
element A pointer to user data.
position A pointer where the element position will be saved.
PDF_ENONODE
element not found.
PDF_EBADDATA
Invalid or NULL pointers.
Usage Example
pdf_list_t list;
int elem1;
int elem2;
pdf_size_t index_of_elem2;

&list) == PDF_OK)
{
/* Get the index of elem2 */

pdf_list_indexof (list, (void *) &elem2, &size_of_elem2);
/* Now size_of_elem2 contains 1 */

}
pdf_status_t pdf_list_indexof_from (const pdf list t list, const [Function]
pdf size t start_index, const void* element, pdf size t *position )
Search whether an element is already in the list, at a position >= start index.
Parameters
list A list.
start index
An index to a position in list.
PDF_ENONODE
element not found.
PDF_EBADDATA
PDF_EINVRANGE
than 0.
Usage example
pdf_list_t list;
int elem1;
int elem2;
int elem3;
int elem4;

&list) == PDF_OK)
{

if (pdf_list_indexof_from (list,
1,
(void *) &elem1,
&size_of_elem1) == PDF_ENONODE)
{
/* The program reaches this point, since elem1 occupies
the first position into the list */
}
}
pdf_status_t pdf_list_indexof_from_to (const pdf list t list, [Function]

const pdf size t start_index, const pdf size t end_index, const void*
element, pdf size t *position )
end index.
Parameters
list A list.
start index
A position in list.
end index A position in list.
element A pointer to some user data.
PDF_ENONODE
element not found.
PDF_EBADDATA
PDF_EINVRANGE
than 0.
Usage example
pdf_list_t list;
int elem1;
int elem2;
int elem3;
int elem4;
&list) == PDF_OK)
{

if (pdf_list_indexof_from_to (list,
1, 3,
(void *) &elem1,
&size_of_elem4) == PDF_ENONODE)
{
/* The program reaches this point, since elem4 occupies
the last position (3) into the list */
}
}
2.6.5 Setting and Getting List Elements

void * pdf_list_node_value (const pdf list t list, const [Function]
pdf list node t node )
Get the element value represented by a list node.
Parameters
list A list.
node A node of list.
Returns The element value represented by node.
Usage example
pdf_list_t list;
int elem1;
int *pointer_to_elem1;
&list) == PDF_OK)
{
/* Get the node of the element of the list */

pdf_list_search (list, (void *) &elem1, &node);
/* Get the value out of the node */

pointer_to_elem1 = (int *) pdf_list_node_value (list, node);
}
pdf_status_t pdf_list_get_at (const pdf list t list, const [Function]

pdf size t position, const void **value )
Get the element at a given position in the list.
Parameters
list A list.
position A position in list. Must be >= 0 and < pdf_list_size
(list).
value A pointer to which the element will be saved.
PDF_EINVRANGE
Invalid position
PDF_EBADDATA
Invalid value pointer.
Usage example
pdf_list_t list;
int elem1;
int *pointer_to_elem1;
&list) == PDF_OK)
{
/* Get the first element of the list */

pdf_list_get_at (list, 0, &pointer_to_elem_1);
}
pdf_status_t pdf_list_set_at (pdf list t list, const pdf size t [Function]
position, const void* element, pdf list node t *node )
Replace the element at a given position in a list.
Parameters
list A list.
(list).
element The new element.
node A pointer to save the node containing the replaced element
or NULL.
PDF_EINVRANGE
Invalid position range.
PDF_BADDATA
The list does not allow duplicated values and already contain
element.
PDF_ENOMEM
Usage example
pdf_list_t list;
pdf_u32_t a;
pdf_u32_t b;
pdf_u32_t c;
pdf_u32_t x;
/* Create a list of integers */

if (pdf_list_new (NULL,
NULL,
&list) == PDF_OK)
{
/* Insert the elements into the list */
pdf_list_add_last (list, (void *) &a, NULL);
pdf_list_add_last (list, (void *) &b, NULL);
pdf_list_add_last (list, (void *) &c, NULL);
/* Now the list contains abc */

pdf_list_set_at (list, 1, (void *) &x, NULL);
/* Now the list contains axc */

}
2.6.6 Adding and Removing List Elements

pdf_status_t pdf_list_add_first (pdf list t list, const void* [Function]
Add an element as the first element of the list. If node is not NULL then a reference
to the newly created node is copied to it.
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.
PDF_OK The element was inserted successfully.
PDF_EBADDATA
element.
PDF_ENOMEM
Usage example
pdf_list_t list;
pdf_list_t sublist;
/* Create empty lists. */

pdf_list_new (NULL, NULL, PDF_FALSE, &list);
pdf_list_new (NULL, NULL, PDF_FALSE, &sublist);
/* Set the sublist as the first element of the list. */

if (pdf_list_add_first (list, (void *) &sublist, NULL)
!= PDF_OK)
{
/* Error adding the element to the list. */
}
pdf_status_t pdf_list_add_last (pdf list t list, const void* [Function]

Add an element as the last element of the list. If node is not NULL then a reference
to the newly created node is copied to it.
Parameters
list A list.
node If non NULL, a list node variable used to contain the added
element.
PDF_OK The element was inserted successfully.
PDF_EBADDATA
element.
PDF_ENOMEM
Usage example
pdf_list_t list;
my_t my_var;
/* Append my_var to ’list’. */

if (pdf_list_add_last (list, (void *) &my_var, NULL)
!= PDF_OK)
{
/* Error appending the element to the list. */
}
pdf_status_t pdf_list_add_at (pdf list t list, const pdf size t [Function]

position, const void* element, pdf list node t *node )
Add an element at a given position in the list.
Parameters
list A list.
position A position in the list. Should be >= 0 and <= pdf_list_size
(list).
node A pointer to the node where the given element was stored or
NULL.
PDF_EINVRANGE
Invalid range of given position.
PDF_BADDATA
element.
PDF_ENOMEM
Usage example
pdf_list_t list;
int a, b, c;
/* Create the list and add some elements to it... */

pdf_list_new (NULL, NULL, PDF_FALSE, &list);
pdf_list_add_at (list, 0, (void *) &a); /* (a) */

pdf_list_add_at (list, 1, (void *) &c); /* (a c) */
pdf_list_add_at (list, 1, (void *) &b); /* (a b c) */
pdf_status_t pdf_list_remove_node (pdf list t list, const [Function]

pdf list node t node )
Remove an element from the list.
Parameters
list A list.
node The node to be removed.
PDF_OK
Usage example
pdf_list_t list;
int elem1;
int elem2;
int elem3;
if (pdf_list_new (NULL, NULL,

PDF_FALSE, /* Allow duplicates. */
&list) == PDF_OK)
{
/* Add some elements to the list. */
/* Remove the element containing ’elem2’ from ’list’. */

pdf_list_search (list, (void *) &elem2, &node);
if (pdf_list_remove_node (list, node) != PDF_OK)
{
/* Error removing the node from the list. */
}
}
pdf_status_t pdf_list_remove_at (pdf list t list, const pdf size t [Function]

position )
Remove an element at a given position from the list.
Parameters
list A list.
(list).
PDF_EINVRANGE
Invalid position range.
Usage example
pdf_list_t list;
int elem1;
int elem2;
int elem3;

&list) == PDF_OK)
{

if (pdf_list_remove_at (list, 1) != PDF_OK)
{
}
}
pdf_status_t pdf_list_remove (pdf list t list, const void * [Function]
element )
Search and remove an element from the lsit.
Parameters
list A list.
element The element to be removed.
PDF_OK element was found in the list and was removed.
PDF_EBADDATA
element was not found in the list.
Usage example
pdf_list_t list;
int elem1;
int elem2;
int elem3;

&list) == PDF_OK)
{

if (pdf_list_remove (list, (void *) &elem2) != PDF_OK)
{
}
}
2.6.7 Working with sorted lists

pdf_status_t pdf_list_sorted_add (pdf list t list, [Function]
pdf list element compar fn t compar_fn, const void* element,
pdf list node t * element_node )
Add an element to the list.
Parameters
list A list.
compar fn A comparision function.
element node
A pointer where the added element node will be saved. Can
be NULL.
PDF_EBADDATA
Invalid compar fn pointer.
PDF_ENOMEM
Usage example
XXX
pdf_status_t pdf_list_sorted_remove (pdf list t list, [Function]

pdf list element compar fn t compar_fn, const void * element )
Search and remove an element from the list.
Parameters
list A list.
element The element to be removed.
PDF_OK element was found in the list and was removed.
PDF_ENONODE
element was not found in the list.
PDF_EBADDATA
Invalid compar fn.
Usage example
XXX
pdf_status_t pdf_list_sorted_search (const pdf list t list, [Function]
pdf list element compar fn t compar_fn, const void* element,
pdf list node t *node )
Parameters
list A list.
PDF_ENONODE
element not found.
PDF_EBADDATA
Invalid node pointer or compar fn.
Usage example
XXX
pdf_status_t pdf_list_sorted_search_from_to (const pdf list t [Function]
list, pdf list element compar fn t compar_fn, const pdf size t
start_index, const pdf size t end_index, const void* element,
pdf list node t *node )
end index.
Parameters
list A list.
start index
Index to the first list position to be searched.
end index Index to the last list position to be searched.
node The seached node if it was found.
PDF_ENONODE
element not found.
PDF_EBADDATA
Invalid node pointer or compar fn.
PDF_EINVRANGE
than 0.
Usage example
XXX
pdf_status_t pdf_list_sorted_indexof (const pdf list t list, [Function]

pdf list element compar fn t compar_fn, const void* element, pdf size t
*position )
Parameters
list A list.
element A pointer to user data.
PDF_ENONODE
element not found.
PDF_EBADDATA
Usage Example
XXX
pdf_status_t pdf_list_sorted_indexof_from_to (const pdf list t [Function]

list, pdf list element compar fn t compar_fn, const pdf size t
start_index, const pdf size t end_index, const void* element, pdf size t
*position )
end index.
Parameters
list A list.
start index
A position in list.
element A pointer to some user data.
PDF_ENONODE
element not found.
PDF_EBADDATA
PDF_EINVRANGE
than 0.
Usage example
XXX
2.6.8 Working with Iterators

pdf_status_t pdf_list_iterator (const pdf list t list, [Function]
pdf list iterator t *itr )
Create an iterator traversing 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.
itr A pointer to where the new iterator will be saved.
PDF_OK itr contains a new iterator for list.
PDF_EBADDATA
itr points to NULL.
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.
itr A pointer to an iterator where the new one will be saved.
PDF_OK itr contains a new iterator for list pointing to start index.
PDF_EINVRANGE
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.
PDF_OK There is a next element.
PDF_ERROR
There is not a next element.
Usage example
XXX
pdf_status_t pdf_list_iterator_free (pdf list iterator t [Function]

*iterator )
Free an iterator releasing any used resource.
Parameters
iterator A list iterator.
PDF_OK
Usage example
XXX
2.7 Filtered Streams

This module provides read/write streams of data to memory buffers and open files adding
the following functionality:
− Filtering.
− Buffering.
Several streams can be created to operate in the same open file. This provides a conve-
nient access to files with several parts requiring different filters to read or write its contents.
Filters (such as the PDF standard ones) are supported for both reading and writing.
Many filters may be used in a single stream (those filters are applied in an order when
writing and in the inverse order when reading).
The file streams maintain a buffer for both reading and writing. The size of the buffer
is specified by the client in creation time. This is used, for example, to provide efficient
character-based I/O.
Note that the streams operating in memory buffers do not provide buffering.
2.7.1 Stream Types

pdf_stm_t [Data Type]
A stm variable.
enum pdf_stm_mode_e [Data Type]

The operation mode of a stm object.
PDF_STM_READ
The stm will be used to read data from the open file or memory buffer.
PDF_STM_WRITE
The stm will be used to write data into the open file or memory buffer.
enum pdf_stm_filter_type_e [Data Type]

The several types of supported stream filters.
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.
2.7.2 Creating and Destroying Streams

pdf_status_t pdf_stm_file_new (pdf fsys file t file, pdf off t [Function]
offset, pdf size t cache_size, enum pdf stm mode e mode, pdf stm t
*stm )
Create a new stream operating in a given open file.
Parameters
file An open file.
offset Position into the file.
cache size The desired size for the stream cache, measured in octects.
If it is 0 then the default size (4kb) is used.
mode The operation mode for the stream.
stm A pointer to the stm to be created.
PDF_OK The stream object was successfully created.

PDF_ERROR
There was an error and the stream was not created.
Usage example
XXX
pdf_status_t pdf_stm_mem_new (pdf char t *buffer, pdf size t [Function]

size, pdf size t cache_size, enum pdf stm mode e mode, pdf stm t *stm )
Create a new stream operating in a memory buffer.
Parameters
buffer Memory buffer where the information will be written-to or
readed-from.
size The desired size for the memory buffer, measured in octects.
cache size The desired size for the stream cache, measured in octects.
If it is 0 then the default size (4kb) is used.
mode The operation mode for the stream.
stm A pointer to the stm to be created.
PDF_OK The stream was successfully created.
PDF_ERROR
There was an error and the stream was not created.
Usage example
XXX
pdf_status_t pdf_stm_destroy (pdf stm t stm ) [Function]

Destroy a stream freeing all the used resources.
Parameters
stm A stream.
Returns A PDF status value. This is PDF_OK unless the closed stream is a writing
stream. In that case the return code of pdf_stm_flush is returned.
Usage example
XXX
2.7.3 Getting and Setting Stream Properties

pdf_stm_get_mode (pdf_stm_t stm ) [Function]
Return the mode of a given stream stm.
Parameters
stm A stream.
Returns The mode of the stream.
Usage example
pdf_stm_t stm;
pdf_stm_mem_new (buffer,
2048,
0, /* Use the default cache size */
PDF_STM_WRITE,
&stm);
pdf_stm_get_mode (stm); /* Returns PDF_STM_WRITE */
2.7.4 Managing the Filter Chain

The following functions can be used to build the filter chain of a given stream.
pdf_status_t pdf_stm_install_filter (pdf stm t stm, enum [Function]
pdf stm filter type e filter_type, pdf hash t filter_params )
Install a fiter in the filter chain of a stream.
Parameters
stm A stream.
filter type The type of the filter to be installed.
filter params
Hash table containing a set of key-value pairs with the pa-
rameters for the filter.
PDF_OK The filter was successfully installed in the stream.
PDF_ERROR
There was an error and the filter was not installed in the
stream.
Usage example
XXX
2.7.5 Reading and Writing Data

pdf_status_t pdf_stm_read (pdf stm t stm, pdf char t *buf, [Function]
pdf size t bytes, pdf size t *read_bytes )
Read a chunk of data from a given stream.
Parameters
stm A stream.
buf The buffer to hold the read data.
bytes The number of octects to read.
read bytes
The number of octects actually read. If this value is less than
bytes then an end of file condition occurred.

PDF_OK All the requested bytes were successfully read into buf.
PDF_EEOF An end of file condition occurred.
PDF_EINVOP
Reading was requested in a writing stream.
PDF_ERROR
An error prevented to read the bytes.
Usage example
XXX
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.
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_status_t pdf_stm_read_char (pdf stm t stm, pdf char t *c ) [Function]

Read a character from a given stream.
Parameters
stm A stream.
c The address of a character.
PDF_OK A character was successfully read into c.
PDF_EEOF End of file.

PDF_EINVOP
Reading was requested in a writing stream.
PDF_ERROR
An error prevented to read the character.
Usage example
XXX
pdf_status_t pdf_stm_peek_char (pdf stm t stm, pdf char t *c ) [Function]

Peek a character from a given stream.
Parameters
stm A stream.
c The address of a character.
PDF_OK A character was successfully peek into c.
PDF_EEOF End of file.
PDF_EINVOP
Peeking was requested in a writing stream.
PDF_ERROR
An error prevented to peek the character.
Usage example
XXX
pdf_status_t pdf_stm_flush (pdf stm t stm, pdf bool t finish_p, [Function]

pdf size t *flushed_bytes )
Flush any pending writing data in a given stream.
If finish p equals to PDF_TRUE then the filters in the stream’s filter chain are tell to
generate any remaining output.
Parameters
stm A stream.
finish p A boolean value indicating whether to finalize the filter chain.
flushed bytes
A pointer to a pdf_size_t variable to hold the number of
flushed bytes. May be 0.
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
Usage example
XXX
2.7.6 Stream Positioning
pdf_off_t pdf_stm_bseek (pdf stm t stm, pdf off t pos ) [Function]

Seek into the backend of a given stream.
Parameters
stm A stream.
pos The position to seek, measured in octects from the beginning

of the backend media.
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
pdf_off_t pdf_stm_btell (pdf stm t stm ) [Function]

Get the current position of the read/write pointer of the backend of a stream.
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
pdf_off_t pdf_stm_tell (pdf stm t stm ) [Function]

Get the number of octects read/written from/to the stream since either the last pdf_
stm_bseek operation or the creation of the stream, if no bseek was made.
Parameters
stm A stream.
Returns The current position (measured in octets) of the read/write pointer.
Usage example
XXX
2.8 Floating Point Maths

2.8.1 Floating Point Constants

PDF_PI [Constant]
The value of PI.
PDF_REAL_MAX [Constant]
Maximum value able to be stored in a pdf_real_t variable.
PDF_REAL_MIN [Constant]
Minimum value able to be stored in a pdf_real_t variable.
2.8.2 Floating Point Types

pdf_real_t [Data Type]
An opaque type representing a floating-point number.
The following constants specify the valid ranges for this data type:
struct pdf_point_s [Data Type]
This structure represents a single point. The coordinates of the point are made using
floating point numbers.
pdf_real_t h
Horizontal coordinate.
pdf_real_t v
Vertical coordinate.
pdf_point_t [Data Type]
A pointer to a pdf_point_s structure.
struct pdf_matrix_s [Data Type]
This structure represents a 3x3 matrix representing an affine transformation.
pdf_real_t a
pdf_real_t b
The first row of the matrix is a b 0.
pdf_real_t c
pdf_real_t d
The second row of the matrix is c d 0.
pdf_real_t h
pdf_real_t v
The third row of the matrix is h v 1.
pdf_matrix_t [Data Type]
A pointer to a pdf_matrix_s structure.
struct pdf_rect_s [Data Type]
This structure represents a rectangle. It is composed by the coordinates for its four
sides.
The rectangle sides should be horizontal and vertical and opposite sides should be
parallel.
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.
pdf_rect_t [Data Type]

A pointer to a pdf_rect_s structure.
struct pdf_quad_s [Data Type]

This structure represents a quadrilateral. It is composed by four corners (floating-
point points).
pdf_point_t tl
Top-left point.
pdf_point_t tr
Top-right point.
pdf_point_t bl
Bottom-left point.
pdf_point_t br
Bottom-right point.
pdf_quad_t [Data Type]

A pointer to a pdf_quad_t structure.
pdf_fp_func_t [Data Type]

Opaque type representing a Floating Point function.
2.8.3 Rounding Routines

pdf_real_t pdf_fp_floor (pdf real t op ) [Function]
Round op down to the nearest integer.
Parameters
op A real operand.
Returns The rounded integer value. If op is integral or infinite, op itself is re-
turned.
Usage example
pdf_real_t number;
pdf_u32_t rounded;
number = 1.2;
rounded = pdf_fp_floor (number);
/* rounded equals 1 */
number = 1.6;
number = 2;
pdf_real_t pdf_fp_ceil (pdf real t op ) [Function]

Round op up to the nearest integer.
Parameters
op A real operand.
Returns The rounded integer value. If op is integral or infinite, op itself is re-
turned.
Usage example
pdf_real_t number;
pdf_u32_t rounded;
number = 1.2;
rounded = pdf_fp_ceil (number);
number = 1.6;
number = 2;
2.8.4 Exponential and Logarithmic Routines

pdf_real_t pdf_fp_exp (pdf real t op ) [Function]
Return the value of e (the base of natural logarithms) raised to the power of op.
Parameters
op A real operand.
Returns The value of e raised to the power of op.
Usage example
XXX
pdf_real_t pdf_fp_log (pdf real t op ) [Function]

Return the natural logarithm of op.
Parameters
op A real operand.
Returns The natural logarithm of op.
Usage example
XXX
pdf_real_t pdf_fp_log10 (pdf real t op ) [Function]

Return the base 10 logarithm of op.
Parameters
op A real operand.
Returns The base 10 logarithm of op.
Usage example
XXX
2.8.5 Number Conversion Routines

pdf_status_t pdf_fp_string_to_real (const pdf char t *string, [Function]
pdf real t *result )
Convert a numeric string representation to a pdf_real_t value. The string is scanned
from left to right, taking into account the data before the first invalid character.
Parameters
string A NULL terminated string.
result The real variable where the result is stored.
PDF_OK The conversion was successful.
PDF_ERROR
No recognizable real value was found in the string.
Usage example
pdf_real_t real;
pdf_char_t str[5];
strcpy (str, "1");

str[1] = 0;
pdf_fp_string_to_real (str, &real);
/* real now contains 1.0 */
strcpy (str, "1.0");

str[3] = 0;
strcpy (str, "1.0X");

str[4] = 0;
strcpy (str, "foo");

str[3] = 0;
if (pdf_fp_string_to_real (str, &real) == PDF_ERROR)
{
/* The code reach this point */
}
pdf_status_t pdf_fp_real_to_string (pdf real t real, pdf char t [Function]

*buffer, pdf size t size, pdf u32 t precision )
Get a textual representation of a pdf_real_t value.
Parameters
real The number to convert.
buffer The buffer where to store the textual representation of real.
Note that this function adds a ’\0’ to the end of the textual
representation.
size The maximum number of characteres that may be stored in
buffer.
precision The number of decimal digits to include in the textual rep-
resentation. If it is 0 then the maximum precision is used.
PDF_OK A textual representation of real was successfully written in s.
PDF_ERROR
An error prevented to perform the conversion.
Usage example
pdf_real_t real;
pdf_char_t s[9];
real = 1.123456;
pdf_fp_real_to_string (real, s, 9, 6);

/* s contains "1.123456" */
pdf_fp_real_to_string (real, s, 9, 3);

/* s contains "1.123" */
if (pdf_fp_real_to_string (real, s, 4, 3) == PDF_ERROR)

{
/* The code reach this point: not enough space in the string
to hold the textual representation of the number with

the specified precision */
}
2.8.6 Trigonometric Routines

pdf_real_t pdf_fp_sin (pdf real t op ) [Function]
Return the sine of op, where op is given in radians.
Parameters
op A real operand.
Returns A real value between -1 and 1.
Usage example
XXX
pdf_real_t pdf_fp_cos (pdf real t op ) [Function]

Return the cosine of op, where op is given in radians.
Parameters
op A real operand.
Returns A real value between -1 and 1.
Usage example
XXX
pdf_real_t pdf_fp_atan2 (pdf real t op1, pdf real t op2 ) [Function]

Return the arc tangent of the two values op1 and op2. It is similar to calculating
the arc tangent of op1 / op2 except that the signs of both arguments are used to
determine the quadrant of the result.
Parameters
op A real operand.
Returns The result in radians, wichi is between -PDF_PI and PDF_PI (inclusive).
Usage example
XXX
2.8.7 Geometry Routines

pdf_status_t pdf_fp_matrix_concat (pdf matrix t result, [Function]
pdf matrix t matrix_1, pdf matrix t matrix_2 )
Multiplies two matrices.
Parameters
result Pointer to the matrix that will be filled with the result. It may be a copy
of matrix 1 or matrix 2.
matrix 1 The first matrix to multiply.
matrix 2 The second matrix to multiply.
Returns A PDF status code:

PDF_ERROR
There was an error performing the execution.
Usage example
XXX
pdf_status_t pdf_fp_matrix_invert (pdf matrix t result, [Function]

pdf matrix t matrix )
Calculate the inverse of a matrix.
Parameters
result A pointer to a matrix that will store the inverted matrix.
This parameters can be a copy of matrix.
matrix A pointer to a matrix used to calculate the inverse.
PDF_ERROR
An error prevented the operation to finish.
Usage example
XXX
pdf_status_t pdf_fp_matrix_transform (pdf point t result, const [Function]

pdf matrix t matrix, const pdf point t point )
Transform a point through a matrix.
Parameters
result A pointer to a point to hold the result. This can be a copy
of point.
matrix A pointer to the matrix used to perform the transformation.
point A pointer to the point to transform.
PDF_ERROR
Usage example
XXX
pdf_status_t pdf_fp_matrix_transform_rect (pdf rect t result, [Function]

const pdf matrix t matrix, const pdf rect t rect )
Transform a rectangle through a matrix.
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.
PDF_ERROR
Usage example
XXX
2.8.8 Other Maths Routines

pdf_fp_abs (pdf_real_t op ) [Function]
Return the absolute value of the real number op.
Parameters
op A real operand.
Returns The absolute value of the operand.
Usage example
XXX
pdf_fp_sqrt (pdf_real_t op ) [Function]

Return the non-negative square root of op.
Parameters
op A real operand.
Returns The square root of op.
Usage example
XXX
2.8.9 Creation and Destruction of Functions

pdf_status_t pdf_fp_func_0_new (pdf u32 t m, pdf u32 t n, const [Function]
pdf real t domain [], const pdf real t range [], pdf u32 t size [], pdf u32 t
bps, pdf u32 t order, const pdf real t encode [], const pdf real t decode [],
pdf char t *samples, pdf size t samples_size, pdf fp func t *function )
Create a new type 0 (sampled) function.
Parameters
m Number of input values.
n Number of output values.
domain Array of 2 * m numbers. Each pair of consecutive numbers

defines the domain of an input variable.
range Array of 2 * n numbers. Each pair of consecutive numbers
defines the range of an output variable. Output values out-
side these ranges will be clipped to the appropriate range.
size Array of m positive integers containing the number of samples
in each input dimension in the samples table.
bps The number of bits used to represent a sample in the samples
table. Valid values shall be 1, 2, 4, 8, 12, 16, 24 and 32.
order Order of interpolation between samples. Valid values shall
be 1 and 3.
encode Array of 2 * m numbers specifying the linear mapping of input
values into the domain of the function’s sample table.
decode Array of 2 * n numbers specifying the linear mapping of sam-
ple values into the range appropriate for the function’s output
values.
samples Buffer containing the samples table for the function.
samples size
Size of the samples table.
function A pointer to the variable holding the new function.
PDF_OK The function was successfully created.
PDF_ERROR
Error while creating the function.
Usage example
XXX

pdf real t domain [], const pdf real t range [], pdf real t N, pdf real t c0 [],
pdf real t c1 [], pdf fp func t *function )
Create a new type 2 (exponential interpolation) function.
Parameters
N The interpolation exponent.

c0 An array of n numbers that shall define the function result
when x = 0.0.
c1 An array of n numbers that shall define the function return
when x = 1.0.
function Pointer to a variable holding the new function.
PDF_ERROR
Usage example
XXX
pdf real t domain [], const pdf real t range [], pdf u32 t k, pdf fp func t
*functions, pdf real t bounds [], const pdf u32 t encode [], pdf fp func t
*function )
Create a new type 3 (stitching) function.
Parameters
k Number of stitching functions.
functions An array of k 1-input functions that shall make up the stitch-
ing function. The output dimensionality of all functions shall
be the same, and compatible with the value of range.
bounds An array of k - 1 numbers that, in combination with domain,
shall define the intervals to which each function from the
functions parameter shall apply. bounds elements shall be in
order of increasing value, and each value shall be within the
domain defined by domain.
encode An array of 2 * k numbers that, taken in pairs, shall map
each subset of the domain defined by domain and the bounds
parameter to the domain of the corresponding function.
function A pointer to a variable holding the new function.

PDF_ERROR
Usage example
XXX
pdf_status_t pdf_fp_func_4_new (pdf u32 t m, pdf u32 t n, [Function]

pdf real t domain [], pdf real t range [], pdf char t *code, pdf size t
code_size, pdf size t *error_at, pdf fp func t *function )
Create a new type 4 (postscript calculator) function.
Parameters
code Memory buffer containing the postscript code to execute.
code size Size of code.
error at Pointer to a variable where it will put the current offset on
error.
function Pointer to a variable holding the new function.
PDF_ERROR
Usage example
XXX
pdf_status_t pdf_fp_func_destroy (pdf fp func t function ) [Function]

Destroy a function.
Parameters
function A pointer to an initialized function.
PDF_OK The function was successfully destroyed.
Usage example
XXX
2.8.10 Evaluation of Functions

pdf_status_t pdf_fp_func_get_bounds (const pdf fp func t [Function]
function, pdf i32 t *in_dimensions, pdf i32 t *out_dimensions )
Return the bounds of a given function.
Parameters
function An initialized function.
in dimensions
Variable to hold the input dimensions of function.
out dimensions
Variable to hold the output dimensions of function.
PDF_OK The operation was successfully performed.
Usage example
XXX
PDF_FP_FUNC_TYPE4_TRUE [Constant]
Stand for true value in the debugging information structure.
PDF_FP_FUNC_TYPE4_FALSE [Constant]
Stand for false value in the debugging information structure.
pdf_fp_func_debug_t [Data Type]
This structure contains debugging data associated to the evaluation of a function.
type0 No information for type0 functions.
type4
status A PDF status value:
PDF_ERROR
An unknown error ocurred.
PDF_EINVRANGE
Invalid range operand for the current operator..
PDF_EUNDERFLOW
Try to fetch an element from an empty stack.
PDF_EOVERFLOW
Overflow of stack.
PDF_EBADTYPE
Invalid type data for the current operator.
PDF_EMATH
Math error.
op Offset in the source code in which the error ocurred.
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.
pdf_status_t pdf_fp_func_eval (pdf fp func t function, const [Function]

pdf real t in [], pdf real t out [], pdf fp func debug t *debug )
Evaluate a function.
Parameters
function The function to evaluate.
in Array containing the input values for the function.
out Array containing the output values from the function evalu-
ation.
debug A pointer to the structure will contain debug information.
PDF_OK The evaluation was successfully performed.
PDF_ERROR
Error while evaluating the function.
PDF_TYPE0
Error in a type0 function. The debug structure will contain
more information.
PDF_TYPE2
more information.
PDF_TYPE3
more information.
PDF_TYPE4
more information.
Usage example
XXX
2.9 Encoded Text

2.9.1 Text Data Types

enum pdf_text_unicode_encoding_e [Data Type]
Enumeration of supported Unicode encodings.
PDF_TEXT_UTF8
UTF-8 encoding.
PDF_TEXT_UTF16_BE
Big Endian UTF-16 encoding.
PDF_TEXT_UTF16_LE
Little Endian UTF-16 encoding.
PDF_TEXT_UTF16_HE
Host Endian UTF-16 encoding (may be little-endian or big-endian).
PDF_TEXT_UTF32_BE
Big Endian UTF-32 encoding.
PDF_TEXT_UTF32_LE
Little Endian UTF-32 encoding.
PDF_TEXT_UTF32_HE
Host Endian UTF-32 encoding (may be little-endian or big-endian).
pdf_text_unicode_options_e [Data Type]

Enumeration of extra options to get the contents of a pdf text t in a given UNICODE
encoding (see function ‘pdf text get unicode’).
PDF_TEXT_UNICODE_NO_OPTION (= 0)
No specific option
PDF_TEXT_UNICODE_WITH_BOM
Prepend Byte Order Marker to the UNICODE string.
PDF_TEXT_UTF16BE_WITH_LANGCODE
Insert language/country code information between the BOM (if required)
and the data. This option is ONLY applicable to UTF16BE. If specified
in any other encoding, the function will fail.
PDF_TEXT_UNICODE_WITH_NUL_SUFFIX
Append a NUL suffix to the Unicode string (1-byte NUL for UTF-8,
2-byte NUL for UTF-16 and 4-byte NUL for UTF-32).
enum pdf_text_filter_type_e [Data Type]

Enumeration of supported filters in encoded text objects (see function
‘pdf text filter’).
PDF_TEXT_FILTER_IDENTITY
Do not perform any transformation in the encoded text. It is a no-op.
PDF_TEXT_FILTER_LINE_ENDINGS
Normalize line endings.
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_t [Data Type]

A Unicode string, which must be considered as an opaque type. It contains the data
in UTF-32BE encoding, as well as any ‘ISO-639-1’ country code and/or ‘ISO-3166-1
alpha-2’ language code applied. It also contains an internal list of word boundaries.
This data type must be initialized before being used, and destroyed afterwards.
pdf_text_host_encoding_t [Data Type]

This data type identifies an encoding used in a host (all the possible values are host-
dependent). There is no initialization/destruction requirement for this data type.
2.9.2 Creating and Destroying Text

pdf_status_t pdf_text_new (pdf text t *text) [Function]
Create a new text object containing no text.
Parameters
text A pointer to the new instance of text object.
PDF_OK The text object was successfully created.
PDF_ENOMEM
Not enough memory to create the text object.
PDF_EBADCONTEXT
The global context of the text module was not initialized.
PDF_ERROR
Other error.
Usage Example
pdf_text_t mytext;
pdf_text_new (&mytext);
pdf_status_t pdf_text_destroy (pdf text t text) [Function]

Destroy a text object and its contents.
Parameters
text A properly created text object.
Returns The status of the destruction
Usage Example
pdf_text_t mytext;
mytext = pdf_text_new ();

pdf_text_destroy(mytext);
pdf_text_t pdf_text_dup (const pdf text t text ) [Function]

Dup a new text object from a existing one.
Parameters
text A properly created text object.
Returns A pointer to the newly created text object.
Usage Example
pdf_text_t text1;
pdf_text_t text2;
text1 = pdf_text_new ();

text2 = pdf_text_dup (text1);
pdf_status_t pdf_text_new_from_host (const pdf char t *str, [Function]

const pdf size t size, const pdf text host encoding t enc, pdf text t *text )
Create a new text object and initialize it with a given host encoded string.
Parameters
str A multybyte string in some host encoding.
size The length of str, in bytes.
enc The host encoding with which str is encoded.
text A pointer to the output text object
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 *he_string;
pdf_size_t he_string_size;
pdf_text_host_encoding_t encoding;
pdf_status_t ret_code;
/* Obtain host encoding and text... */
/* And create text object with those contents */

ret_code = pdf_text_new_from_host(he_string, he_string_size,
encoding,
&text);
if(ret_code != PDF_OK)
{
/* Something bad happened */
}
pdf_status_t pdf_text_new_from_pdf_string (const pdf char t [Function]

*str, const pdf size t size, pdf char t **remaining_str, pdf size t
*remaining_length, pdf text t *text )
Create a new text object and initialize it with a given ‘PDF string’ text representation.
This ‘PDF string’ can be either encoded in UTF-16BE, with BOM and optional
Country/Language code information, or in PDF Doc Encoding.
The Country/Language code marker is treated as end-of-text marker, so that a text
object handles only a given pair of country and language codes. This function must
be used inside a loop, so that the input string of data is splitted in chunks if more
than one language/code is available in the text (only if PDF string is encoded in
UTF-16BE).
Parameters
str A text representation of a PDF string.
size The length of str in bytes
remaining str
Returned pointer to the next chunk of data to process, if any.
remaining length
Length of remaining str in bytes
text A pointer to the newly created text object.
PDF_ENOMEM
PDF_EBADCONTEXT
PDF_ETEXTENC
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;
/* Obtain PDF string... */

remaining_str = pdf_string;
remaining_length = pdf_string_size;
do
{
ret_code = pdf_text_new_from_host(remaining_str, remaining_length,
&remaining_str, &remaining_length,
&text);
/* Do something with the chunk of string */
pdf_text_destroy(text);
}
while((ret_code == PDF_OK) && (remaining_length > 0));
pdf_status_t pdf_text_new_from_unicode (const pdf char t *str, [Function]

const pdf size t size, const enum pdf text unicode encoding e enc,
pdf text t *text )
Create a new text object from a string of Unicode characters in a given unicode
encoding. The Unicode string can be given with or without BOM, and there mustn’t
be any language/code information embedded in the string.
Note that for UTF-16BE strings two options are possible to create the pdf text t
object: treating it as a PDF string (so BOM is mandatory and Language/Country
code are optional) or treating it as a general Unicode string (so BOM is optional and
Language/Country code is not allowed).
Parameters
str A Unicode string.
size The length of str in bytes.
enc The Unicode encoding used by str.
PDF OK The operation succeeded.
PDF ENOMEM
PDF EBADCONTEXT
PDF ETEXTENC
PDF EBADDATA
Invalid parameters.
Usage Example
pdf_text_t text;
pdf_char_t *unicode_string;
pdf_size_t unicode_string_size;
/* Obtain unicode text... */

ret_code = pdf_text_new_from_unicode(unicode_string, unicode_string_size
PDF_TEXT_UTF16_BE,
&text);
{
}
pdf_status_t pdf_text_new_from_u32 (const pdf u32 t number, [Function]

pdf text t *text)
Create a new text variable containing the textual representation of a given integer.
Parameters
number An unsigned 32 bit number.

PDF_ENOMEM
PDF_EBADCONTEXT
PDF_ETEXTENC
PDF_EBADDATA
Invalid parameters.
Usage Example
pdf_text_t text;
pdf_u32_t number;
number = 24;
ret_code = pdf_text_new_from_u32 (number, &text);
{
}
2.9.3 Managing Text Properties

const pdf_char_t * pdf_text_get_country (const pdf text t text ) [Function]
Return the ‘ISO-3166-1 alpha-2’ country code associated with a text variable, as a
NUL-terminated string. The returned string should not be modified, as it is managed
by the ‘pdf text t’ data type.
Parameters
text A text variable.
Returns The code of the country associated with text.
Usage Example
pdf_text_t text;
pdf_char_t *code;
/* ...create and manipulate ‘text’ */
code = pdf_text_get_country (text);

const pdf_char_t * pdf_text_get_language (const pdf text t [Function]
text )
Return the ‘ISO-639-1’ language code associated with a text variable, as a NUL-
terminated string. The returned string should not be modified, as it is managed by
the ‘pdf text t’ data type.
Parameters
Returns The code of the language associated with text.
Usage Example
pdf_text_t text;
pdf_char_t *code;
code = pdf_text_get_language (text);
pdf_status_t pdf_text_set_country (pdf text t text, const [Function]

pdf char t *code )
Associate a text variable with a ‘ISO-3166-1 alpha-2’ country code.
Parameters
code A country code.
Returns The status of the assignment.
Usage Example
pdf_text_t text;
ret_code = pdf_text_set_country (text, "27");
pdf_status_t pdf_text_set_language (pdf text t text, const [Function]

pdf char t *code )
Associate a text variable with a ‘ISO-639-1’ language code.
Parameters
code A language code.
Returns The status of the assignment.
Usage Example
pdf_text_t text;
ret_code = pdf_text_set_language (text, "10");

pdf_bool_t pdf_text_empty_p (const pdf text t text ) [Function]

Determine if a given text variable is empty (contains no text).
Parameters
Returns A boolean value:
PDF_TRUE The text variable contain no text.
PDF_FALSE
The text variable contain some text.
Usage Example
pdf_text_t text;
/* ...initialize and manipulate ‘text’... */
if (pdf_text_empty_p (text))
{
/* ‘text’ contains no text */
}
2.9.4 Managing Text Contents

pdf_status_t pdf_text_get_host (pdf char t **contents, pdf size t [Function]
*length, const pdf text t text, const pdf text host encoding t enc )
Get the contents of a text variable encoded in a given host encoding.
Parameters
contents Output array of bytes (May contain NUL bytes). Must be
freed afterwards.
length Output length of contents
enc A host encoding supported by the host.
Returns The status of the conversion.
Usage Example
pdf_text_t text;
pdf_char_t *str;
pdf_size_t str_length;
ret_code = pdf_text_get_host (&str, &str_length, text, encoding);
pdf_dealloc(str);
pdf_status_t pdf_text_get_pdfdocenc (pdf char t **contents, [Function]

const pdf text t text )
Get the contents of a text variable encoded in PDF Doc Encoding, and
NUL-terminated.
Parameters
contents Output array of bytes (Can’t contain NUL bytes). Must be
freed afterwards.
Usage Example
pdf_text_t text;
pdf_char_t *str;
ret_code = pdf_text_get_pdfdocenc (&str, text);
pdf_dealloc(str);
pdf_status_t pdf_text_get_unicode (pdf char t **contents, [Function]

pdf size t *length, const pdf text t text, const enum
pdf text unicode encoding e enc, const pdf u32 t options )
Get the contents of a text variable encoded in the specified Unicode encoding. Addi-
tional options can be set in the request.
Parameters
contents Output array of bytes (May contain NUL bytes). Must be
freed afterwards.
length Output length of contents
enc A given UNICODE encoding, specifying requested endian-
ness.
options Additional options that can be set, in the way: OPTION 1
| OPTION 2 | OPTION 3. (see pdf_text_unicode_
options_e data type)
Usage Example
pdf_text_t text;
pdf_char_t *str;
pdf_size_t str_length;
ret_code = pdf_text_get_unicode (&str, &str_length,

text,
PDF_TEXT_UTF16_BE,
(PDF_TEXT_UNICODE_WITH_BOM | PDF_TEXT_U
pdf_dealloc(str);
pdf_char_t * pdf_text_get_hex (const pdf text t text, const [Function]

pdf char t delimiter )
Get the contents of a text variable encoded in ASCII format and represented in
Hexadecimal format, separated by the character given in delimiter (usually ’:’).
Parameters
text A text variable
delimiter A single ASCII char used as delimiter
Returns A NUL-terminated string with the contents of the text object in hexadec-
imal representation. The string must be deallocated by the caller.
Usage Example
pdf_text_t text;
pdf_char_t *str;
str = pdf_text_get_hex (text, ’:’);
PDF_DEBUG_BASE("Internal representation of the string is: ’%s’",str);
pdf_dealloc(str);
pdf_status_t pdf_text_set_host (pdf text t text, const pdf char t [Function]

*str, const pdf size t size, const pdf text host encoding t enc )
Set a string encoded with some host encoding as the value of a text variable.
Parameters
str A string encoded with some host encoding.
enc The length of str, in bytes.
enc The host encoding used to encode str.
Usage Example
pdf_text_t text;
pdf_char_t *str;
pdf_size_t length;
/* ...initialize and manipulate ‘text’, ‘encoding’ and ‘str’... */

if (pdf_text_set_host (text, str, length, enc) != PDF_OK)
{
/* ‘str’ contains bad data */
}
pdf_status_t pdf_text_set_pdfdocenc (pdf text t text, const [Function]
pdf char t *str )
Set a PDF Doc Encoding encoded string as the value of a text variable.
Parameters
str A string encoded with PDF Doc Encoding, NUL terminated.
Usage Example
pdf_text_t text;
pdf_char_t *str;
/* ...initialize and manipulate ‘text’ and ‘str’... */

if (pdf_text_set_pdfdocenc (text, str) != PDF_OK)
{
}
pdf_status_t pdf_text_set_unicode (pdf text t text, const [Function]
pdf char t *str, const pdf size t size, const enum
pdf text unicode encoding e enc )
Set a Unicode encoded string as the value of a text variable.
Parameters
str A Unicode string without country/language data embedded.
size The length of str, in bytes.
enc The used Unicode encoding in str.
Usage Example
pdf_text_t text;
pdf_char_t *str;
pdf_size_t length;
enum pdf_text_unicode_encoding_e enc;
/* ...initialize and manipulate ‘text’, ‘str’ and ‘enc’... */

if (pdf_text_set_unicode (text, str, length, enc) != PDF_OK)
{
}
pdf_status_t pdf_text_concat (pdf text t text1, const pdf text t [Function]
text2, const pdf bool t override_langinfo )
Concatenate the contents of two text variables (text1 first, then text2) and store the
result in text.
Warning! override langinfo is not set and different country/language codes are found
within the text variables an error will be returned (concatenation not possible). If
override langinfo is set, the country and language information is not checked.
Parameters
text1 The first text variable to concatenate. The contents of this
variable are modified with the output of the concatenation.
text2 The second text variable to concatenate. The contents of this
variable are left unchanged.
override langinfo
Flag to indicate if the language and country information must
be checked before performing the concatenation.
Returns The status of the operation.
Usage Example
pdf_text_t text1;
pdf_text_t text2;
/* ...initialize ‘text1’ and ‘text2’... */

if (pdf_text_concat (text1, text2, PDF_FALSE) != PDF_OK)
{
/* Manage the error */
}
pdf_status_t pdf_text_concat_ascii (pdf text t text1, const [Function]
pdf char t * ascii_str )
Concatenate the contents of text variable text1 with ASCII string ascii str, and store
the result in text1.
Parameters
text1 The first text variable to concatenate. The contents of this
variable are modified with the output of the concatenation.
ascii str The ascii string to concatenate. The contents of this variable
are left unchanged.
Returns The status of the operation.
Usage Example
pdf_text_t text1;
pdf_char_t * str;
/* ...initialize ‘text1’ and ‘str... */

if (pdf_text_concat_ascii (text1, str) != PDF_OK)
{
}
pdf_status_t pdf_text_replace (pdf text t text, const pdf text t [Function]

new_pattern, const pdf text t old_pattern )
Replace a fixed pattern in the content of a given text variable.
Parameters
new pattern
The replacement text.
old pattern
The text to be replaced. Any occurrence of this text is re-
placed with new pattern.
Returns The status of the operation
Usage Example
pdf_text_t text;
pdf_text_t new_pattern;
pdf_text_t old_pattern;
/* ...initialize ‘text’, ‘new_pattern’ and ‘old_pattern’... */

if (pdf_text_replace (text, new_pattern, new_pattern) != PDF_OK)
{
}
pdf_status_t pdf_text_replace_ascii (pdf text t text, const [Function]

pdf char t *new_pattern, const pdf char t *old_pattern )
Replace a fixed ASCII pattern in the content of a given text variable.
Parameters
new pattern
The replacement ASCII string.
old pattern
The text to be replaced. Any occurrence of this text is re-
placed with new pattern.
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)
{
}
pdf_status_t pdf_text_filter (pdf text t text, const pdf u32 t [Function]
filter )
Filter the contents of a text variable.
Parameters
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.
Usage Example
pdf_text_t text;
/* ...initialize ‘text’... */
if (pdf_text_filter (text, (PDF_TEXT_FILTER_LOWER_CASE | PDF_TEXT_FILTER

{
/* Manage error */
}
2.9.5 Comparing Text Variables

pdf_i32_t pdf_text_cmp (const pdf text t text1, const pdf text t [Function]
text2, const pdf bool t case_sensitive, pdf status t *p_ret_code )
Compare the contents of two text variables.
Parameters
text1 A text variable.
text2 A text variable.
case sensitive
A boolean value indicating if the comparison is case-sensitive:
PDF_TRUE Case sensitive.
PDF_FALSE
Case insensitive.
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;
/* ...initialize ‘text1’ and ‘text2’... */
switch (pdf_text_cmp (text1, text2, PDF_FALSE))

{
case -1:
{
/* XXX */
break;
}
case 0:
{
/* XXX */
break;
}
case +1:
{
/* XXX */
break;
}
}
2.9.6 Managing Host Encodings

pdf_text_host_encoding_t pdf_text_get_host_encoding (void) [Function]
Return the host encoding configured by the user/system in the locale.
Parameters
None
Returns The host encoding configured in the user’s locale.
Usage Example
pdf_text_host_encoding enc;
enc = pdf_text_get_host_encoding();
pdf_status_t pdf_text_check_host_encoding (const pdf char t [Function]

*encoding_name, pdf text host encoding t *p_encoding )
Check if a given encoding is available in the system as a host-encoding. If available,
it will return PDF OK and will fill in the pdf text host encoding t variable passed
by reference.
Parameters
encoding name
Name of the encoding to check for.
p encoding
Pointer to a pdf text host encoding t variable.
Returns Returns PDF OK if the encoding is available in the system as a host-
encoding.
Usage Example
if(pdf_text_check_host_encoding((pdf_char_t *)"ascii-us",&enc) == PDF_OK

{
/* XXX */
}
pdf_text_host_encoding_t pdf_text_get_best_encoding (const [Function]

pdf text t text, const pdf text host encoding t preferred_encoding )
Return the best available host encoding to encode the contents of a given text variable.
A specified preferred encoding is selected if there is no clear best encoding.
The “best” encoding is an encoding able to encode the bigger number of characters of
the unicode content of the given text variable, so the function will check for Unicode
encodings supported in the system.
Parameters
preferred encoding
A text encoding supported by the host.
Returns The best host encoding available to encode the contents of text.
Usage Example
pdf_text_t text;
pdf_text_host_encoding pref;
/* ...create and manipulate ‘text’... */
enc = pdf_text_get_best_encoding (text, pref);

2.10 Time Management

2.10.1 Time Related Data Types
pdf_time_t [Data Type]
A variable of type pdf_time_t contains information about a particular date and time.
Note that leap seconds are not considered.
pdf_time_span_t [Data Type]
A variable of type pdf_time_span_t represents a span of time.
struct pdf time cal s [Data Type]
This structure holds information about a specific time represented in calendar items:
years, months, days, day of week, hours, minutes, seconds and the relative offset with
GMT.
The calendar can be represented in both UTC and local time. If the given GMT
offset is zero, the calendar fields come in UTC; if not zero, the calendar fields come
in a given local time.
pdf_i32_t year
A year number. Negative values may be supported in some systems.
pdf_u32_t month
A month number. The valid range is 1..12.
pdf_u32_t day
A day number. The valid range is 1..31.
pdf_u32_t dow
Day of the week. The valid range is 1..7 (Monday to Sunday).
pdf_u32_t hour
An hour. The valid range is 0..23.
pdf_u32_t minute
A minute. The valid range is 0..59.
pdf_u32_t sec
A second. The valid range is 0..59.
pdf_i32_t gmt_offset
A GMT offset, in seconds west of GMT.
struct pdf time cal span s [Data Type]
This structure holds information about a time span represented in calendar items:
years, months, days, hours, minutes and seconds.
pdf_u32_t years
pdf_u32_t months
pdf_u32_t days
pdf_u32_t hours
pdf_u32_t minutes
pdf_u32_t seconds
enum pdf_time_format_e [Data Type]

Enumeration containing the several supported time formats used to convert a time
to a string representation or to parse a time from a string representation.
PDF_TIME_FORMAT_PDF
PDF date strings.
PDF_TIME_FORMAT_ISO_8601
ISO 8601 date and time strings.
PDF_TIME_FORMAT_UTC_ASN1
UTC ASN1 date.
PDF_TIME_FORMAT_GENERALIZED_ASN1
Generalized ASN1 date.
2.10.2 Time Creation and Destruction

pdf_status_t pdf_time_new (pdf time t *time ) [Function]
Create a new time and set it to the Epoch: Jan 1 1970-01-01 00:00:00 UTC
Parameters
time The time object that will contain the newly created instance.
PDF_OK The time object was successfully instantiated.
PDF_ENOMEM
Not enough memory to perform the requested operation.
Usage example
pdf_time_t mytime;
if (pdf_time_new (&mytime) != PDF_OK)

{
/* Error */
}
pdf_time_t pdf_time_dup (const pdf time t orig ) [Function]

Dup a new time variable from a given one, allocating memory.
Parameters
orig The time variable to be dupped. Should be a properly created
time variable.
Returns A new time variable containing a copy of orig values. NULL if there is an
error.
Usage example
pdf_time_t orig;
pdf_time_t new_time;
orig = pdf_time_new ();

new_time = pdf_time_dup (orig);
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:
Usage example
pdf_time_t mytime;
mytime = pdf_time_new ();

pdf_time_destroy (mytime);
2.10.3 Managing Time Values

pdf_status_t pdf_time_copy (const pdf time t orig, pdf time t [Function]
copy )
Copies the data from orig to copy.
Parameters
orig The time whose data is to be copied. Should be a properly
copy The time to receive the data from orig. Should be a properly
Note that any previous data is destroyed.
Usage example
pdf_time_t orig;
pdf_time_t copy;
orig = pdf_time_new ();

copy = pdf_time_new ();
if (!pdf_time_copy (orig, copy))

{
/* Error */
}
pdf_status_t pdf_time_clear (pdf time t time_var ) [Function]

Reset time var to the newly created state. After this call time var will contain the
same date as if returned by pdf_time_new.
Parameters
time var The time variable to clear. Should be a properly create time
variable.
Usage example
pdf_time_t mytime;
/* ...manipulate ‘mytime’... */
pdf_time_clear (mytime);
pdf_status_t pdf_time_set_from_u32 (pdf time t time_var, [Function]

pdf u32 t seconds )
This function will initialize time var to the given Unix time (seconds since January
1st 1970) in UTC timescale. The time is represented as a 32-bit unsigned integer.
Parameters
time var The time variable to set. Should be a properly create time
variable.
seconds Seconds since January 1st 1970, 32-bit unsigned value.
Usage example
pdf_time_t mytime;
pdf_time_set_from_u32(mytime, 1217009657);
pdf_status_t pdf_time_set_from_i64 (pdf time t time_var, [Function]

pdf i64 t seconds )
This function will initialize time var to the given Unix time (seconds since January
1st 1970) in UTC timescale. The time is represented as a pdf i64 t integer.
Parameters
variable.
seconds Seconds since January 1st 1970, pdf i64 t variable.

Usage example
pdf_time_t mytime;
pdf_i64_t epoch = pdf_i64_new(0,1217009657);
pdf_time_set_from_i64(mytime, epoch);
pdf_status_t pdf_time_add_cal_span (pdf time t time_var, const [Function]

struct pdf time cal span s *p_cal_span )
Add the time span represented by the calendar span under the address in p cal span
to time var.
Parameters
time var A properly created time variable.
p cal span
A pointer to a calendar span with valid values.
PDF_OK The operation successfully finished.
PDF_EBADDATA
The data in *p cal span is invalid.
Usage example
pdf_time_t mytime;
struct pdf_time_cal_span_s cal_span;
mytime = pdf_time_new (); /* Initialized to Jan 1 1970-01-01 00:00:00 */
cal_span.year = 30;
cal_span.month = 7;
cal_span.day = 20;
cal_span.hour = 21;
cal_span.minute = 0;
cal_span.second = 0;
if (pdf_time_add_cal_span (mytime, &cal_span) == PDF_EBADDATA)

{
/* Bad data in ‘cal_span’ */
}
else
{
/* ‘time’ now contains Aug 21 2000-08-21 21:00:00 */
}
pdf_status_t pdf_time_sub_cal_span (pdf time t time_var, const [Function]

struct pdf time cal span s *p_cal_span )
Subtract the time span represented by the calendar span under the address in
p cal span to time var.
Parameters
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;
mytime = pdf_time_new (); /* Initialized to Jan 1 1970-01-01 00:00:00 */
cal_span.year = 30;
cal_span.month = 7;
cal_span.day = 20;
cal_span.hour = 21;
cal_span.minute = 0;
cal_span.second = 0;
if (pdf_time_add_cal_span (mytime, &cal_span) == PDF_EBADDATA)

{
}
else
{
/* ‘time’ now contains Aug 21 2000-08-21 21:00:00 */
}
if (pdf_time_sub_cal_span (mytime, cal_span) == PDF_EBADDATA)

{
}
else
{
/* ‘time’ now contains Jan 1 1970-01-01 00:00:00 */
}
pdf_status_t pdf_time_add_span (pdf time t time_var, const [Function]

pdf time span t time_span )
Add the time span contained in time span to time var.
Parameters
time span A properly created time span.
Usage example
pdf_time_t mytime;
pdf_time_span_t myspan;
/* ...create and initialize ‘myspan’... */
pdf_time_add_span (mytime, myspan);
pdf_status_t pdf_time_sub_span (pdf time t time_var, const [Function]

pdf time span t time_span )
Subtract the time span contained in time span to time var.
Parameters
time span A properly created time span.
Usage example
pdf_time_t mytime;
pdf_time_span_t myspan;
/* ...create and initialize ‘myspan’... */
pdf_time_sub_span (mytime, myspan);
pdf_status_t pdf_time_get_local_cal (const pdf time t time_var, [Function]

struct pdf time cal s *p_local_cal )
Fill p local cal with the local calendar time of time var.
Parameters
p local cal
A pointer to the time calendar structure that will hold the
local time of time var.
Usage example
pdf_time_t mytime;
struct pdf_time_cal_s cal;
/* ...create and manipulate ‘mytime’... */
pdf_time_get_local_cal (mytime, &cal);

pdf_status_t pdf_time_get_utc_cal (const pdf time t time_var, [Function]
struct pdf time cal s *p_utc_cal )
Get the UTC calendar time of a given time variable.
Parameters
p cal time
A pointer to the calendar time structure that will hold the
UTC time of time var.
Usage example
pdf_time_t mytime;
sruct pdf_time_cal_s cal_time;
pdf_time_get_utc_cal (mytime, &cal_time);

pdf_status_t pdf_time_from_cal (pdf time t time_var, const struct [Function]
pdf time cal s *p_cal_time )
Set the value of a time variable to a given calendar time.
Parameters
time var A properl created time variable.
p cal time
A pointer to a calendar time structure.
PDF_EBADDATA
There is invalid data in the calendar structure cal time.
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;
if (pdf_time_from_cal (mytime, &mycaltime) == PDF_EBADDATA)

{
/* Bad data in ‘mycaltime’ */
}
pdf_status_t pdf_time_set_local_offset (pdf time t time_var ) [Function]

Set the local time offset of time var to the one used by the operating system.
Parameters
time A properly created time variable.
Usage example
pdf_time_t mytime;

pdf_time_set_local_offset (time);
2.10.4 Getting Time Intervals

pdf_status_t pdf_time_diff_cal (const pdf time t time1, const [Function]
pdf time t time2, struct pdf time cal span s *p_cal_span )
Calculate the time span that goes from time1 to time2 and store it in p cal span.
Note that the highest possible distribution inside p cal span is used.
Parameters
time1 The beginning of the time interval (inclusive).
time2 The end of the time interval (exclusive).
p cal span
Pointer to the calendar time span structure that will hold the
time span that goes between time1 and time2.

Usage example
pdf_time_t time_begin;
pdf_time_t time_end;
/* ...create and manipulate ‘time_begin’ and ‘time_end’ */
pdf_time_diff (time_begin, time_end, &cal_span);

pdf_status_t pdf_time_diff (const pdf time t time1, const [Function]
pdf time t time2, pdf time span t *p_time_span )
Calculate the time span between two dates.
Parameters
time1 The beginning time. Should be a properly created time.
time2 The ending time. Should be a properly created time.
p time span
The pointer to the time span variable that will hold the differ-
ence between time1 and time2. Should be a properly created
time span. Any previous content of *p time span will be
destroyed.
Usage example
pdf_time_t time1;
pdf_time_t time2;
pdf_time_span_t time_span;
/* ...create and manipulate ‘time1’, ‘time2’ and ‘time_span’... */
pdf_time_diff (time1, time2, &time_span);
2.10.5 Time Comparison

pdf_i32_t pdf_time_cmp (const pdf time t time1, const pdf time t [Function]
time2 )
Compares two times.
Parameters
time1 The first time to compare. Should be a properly created time
variable.
time2 The second time to compare. Should be a properly created
time variable.

-1 If time1 precedes time2.
0 If time1 and time2 contain the same time.
1 If time2 precedes time1.
Usage example
pdf_time_t time1;
pdf_time_t time2;
time1 = pdf_time_new ();

time2 = pdf_time_new ();
/* ...manipulate ‘time1’ and ‘time2’... */
switch (pdf_time_cmp (time1, time2))

{
case -1:
{
/* ‘time1’ precedes ‘time2’ */
break;
}
case 0:
{
/* ‘time1’ contain the same time than ‘time2’ */
break;
}
case 1:
{
/* ‘time2’ precedes ‘time1’ */
break;
}
}
2.10.6 Time Printing and Parsing

pdf_char_t* pdf_time_to_string (const pdf time t time_var, const [Function]
enum pdf time format e time_format, pdf bool t
include_trailing_apostrophe )
Create a string representation of a given time.
Parameters
time format
The format to use when creating the string representation of
time.
include trailing apostrophe

Append an apostrophe after the GMT offset minutes field, if
present. Note that this parameter is ignored if time format
is not PDF_TIME_FORMAT_PDF.
Returns The string representation of time. Must be deallocated by the caller of
the function explicitly with pdf dealloc(). NULL if there is an error.
Usage example
pdf_time_t mytime;
pdf_char_t *mytime_str;
mytime_str = pdf_time_to_string (mytime, PDF_TIME_FORMAT_PDF);
pdf_dealloc(mytime_str);
pdf_status_t pdf_time_from_string (pdf time t time_var, const [Function]

pdf char t *time_str, const enum pdf time format e time_format,
pdf bool t require_trailing_apostrophe )
Get a string containing a time specification in some format and fill a time variable
with the parsed values.
Parameters
time str A null-terminated string representation of a time.
time format
The format indicating how to parse time str.
require trailing apostrophe
If this argument is PDF_TRUE a PDF date specification con-
taining minutes should be followed by an APOSTROPHE
character (’).
If time format is not PDF_TIME_FORMAT_PDF then this argu-
ment is ignored.
PDF_EBADDATA
Error while parsing time str according to time format.
Usage example
pdf_time_t mytime;
char time_str[] = "D:20090813210000+00’00"; /* 13-August-2009, 21:00
GMT 0 */

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’ *
}
2.10.7 Getting the Current Time

pdf_status_t pdf_time_set_to_current_local_time (pdf time t [Function]
time_var )
Set the value of time var to the current local time used by the operating system.
Parameters
Usage example
pdf_time_t mytime;
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
Usage example
pdf_time_t mytime;
pdf_time_set_to_current_utc_time (mytime);
2.10.8 Time Span Creation and Destruction

pdf_time_span_t pdf_time_span_new (void) [Function]
Allocate and return a new time span variable. The time span is initialized with a
zero value (zero seconds).
Parameters
None.
Returns The newly created time span variable or NULL if there is an error.
Usage example
pdf_time_span_t span;
span = pdf_time_span_new ();
pdf_time_span_t pdf_time_span_dup (const pdf time span t span ) [Function]

Allocate and dup a new time span from an existing one. The new time span has the
same value as the base time span.
Parameters
span A properly created time span variable.
Returns The newly created time span variable.
Usage example
pdf_time_span_t new_span;
/* ...create and manipulate ‘span’... */
new_span = pdf_time_span_dup (span);
pdf_status_t pdf_time_span_destroy (pdf time span t *p_span ) [Function]

Destroy a time span variable freeing all used memory.
Parameters
p span The pointer to the time span variable to be destroyed.
Usage example
pdf_time_span_destroy (span);
2.10.9 Managing Time Span Values

pdf_status_t pdf_time_span_set (pdf time span t *p_span, const [Function]
pdf i32 t high_value, const pdf u32 t low_value )
Set the value of a time span. The internal representation of the time span is 64 bits
long (signed).
Parameters
p span A pointer to a properly created time span variable.
high value
The high (signed) part of the time span value.
low value The low (unsigned) part of the time span value.
Usage exaple
span = pdf_time_span_new ();

pdf_time_span_set (&span, (1 << 31), 10); /* The span is -10 seconds lon
pdf_status_t pdf_time_span_set_from_i32 (pdf time span t [Function]
*p_span, const pdf i32 t seconds )
Set the value of a time span from a 32 bits signed number.
Parameters
p span A pointer to a properly created time span variable.
seconds A signed 32 bits number.
Usage example
span = pdf_time_span_create ();

pdf_time_span_set_from_i32 (&span, -10); /* The span is -10 seconds long
pdf_status_t pdf_time_span_negate (pdf time span t *p_span ) [Function]
Make a positive time span into a negative one or make a negative time span into a
positive one.
Parameters
span A pointer to a properly created time span variable.
Usage example
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.
span2 The second time span to add.

p result The pointer to the time span holding the result of the add
operation. Any previous content is lost.
PDF_EBADDATA
p result is not a valid pointer.
Usage example
pdf_time_span_t span1;
pdf_time_span_t result;
/* ...create and manipulate ‘span1’, ‘span2’ and ‘result’... */

pdf_time_span_add (span1, span2, &result);
pdf_status_t pdf_time_span_copy (const pdf time span t orig, [Function]

pdf time span t *p_dest )
Copy the value of a time span into another time span.
Parameters
orig The origin time span.
p dest The pointer to the time span variable that will hold the value
of orig. Any previous value is lost.
PDF_EBADDATA
p dest is not a valid pointer.
Usage example
pdf_time_span_t span_orig;
pdf_time_span_t span_dest;
/* ...create and manipulate ‘span_orig’ and ‘span_dest’... */
pdf_time_span_copy (span_orig, span_dest);
pdf_status_t pdf_time_span_diff (const pdf time span t span1, [Function]

const pdf time span t span2, pdf time span t *p_result )
Difference two time spans and store the result (maybe negative) into another time
span.
Parameters
span1 The first time span to diff.
span2 The second time span to diff.
p result The result of the diff operation. Any previous value of the
time span is lost.
PDF_EBADDATA
p result is not a valid pointer.
Usage example
pdf_time_span_t span_diff;
/* ...create and manipulate ‘span1’, ‘span2’ and ‘span3’ */
pdf_time_span_diff (span1, span2, span_diff);
pdf_i64_t pdf_time_span_to_secs (const pdf time span t span ) [Function]

Get the value of a time span in seconds.
Parameters
span A properly created time span variable.
Returns The value of the time span in seconds. A negative value is returned if the
time span is negative.
Usage example
pdf_i32_t num_seconds;
num_seconds = pdf_time_span_to_secs (span);
2.10.10 Time Span Comparison

pdf_i32_t pdf_time_span_cmp (const pdf time span t span1, const [Function]
pdf time span t span2 )
Compare the length two time spans.
Parameters
span1 The first time span to compare.
span2 The second time span to compare.
-1 The length of span1 is shorter than the length of span2.
0 The lengts of span1 and span2 are equal.
+1 The length of span1 is greater than the length of span2.
Usage example
/* ...create and manipulate ‘span1’ and ‘span2’... */

switch (pdf_time_span_cmp (span1, span2))
{
case -1:
{
/* The length of ‘span1’ is shorter than the length of ‘span2’ */
break;
}
case 0:
{
/* The length of ‘span1’ is equal to the length of ‘span2’ */
break;
}
case 1:
{
/* The length of ‘span1’ is greater than the length of ‘span2’ */
break;
}
}
2.10.11 Calendar Spans Management

pdf_status_t pdf_time_add_cal_span_with_base (const struct [Function]
pdf time cal span s *p_span1, const struct pdf time cal span s *p_span2,
const pdf time t base_time, struct pdf time cal span s *p_result )
Add two calendar spans. Since the calendar spans are relative (some years has more
days than another) the calendar spans are first resolved from a base time.
Parameters
p span1 The pointer to the first calendar span to add.
p span2 The pointer to the second calendar span to add.
base time The base time to use.
p result Pointer to the calendar span to store the result of the add
operation.
PDF_EBADDATA
There is invalid data in span1 or span2.
Usage example
pdf_time_t mytime;
struct pdf_time_cal_span_s cal_span1;
struct pdf_time_cal_span_s cal_span2;

struct pdf_time_cal_span_s cal_result;
/* ...create and initialize ‘mytime’, ‘cal_span1’

* and ‘cal_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’ */
}
pdf_i32_t pdf_time_cal_span_cmp (const struct pdf time cal span s [Function]

*p_span1, const struct pdf time cal span s *p_span2, const pdf time t
base_time, pdf status t *p ret code)
Compare two calendar spans previously resolved with a given base time.
Parameters
p span1 The pointer to the first calendar span to be compared.
p span2 The pointer to the second calendar span to be compared.
base time The used base time. Should be a correctly created time vari-
able.
p ret code
Pointer to a status variable to store any error happened in
the function.
Returns
-1 Given the base time, the time interval defined by p span2 is
greater in length than the time interval defined by p span1.
0 Given the base time, the time inveral defined by p span1 is
equal in length than the time interval defined by p span2.
+1 Given the base time, the time interval defined by p span1 is
greater in length than the time interval defined by p span2.
Usage example
pdf_time_t mytime;
struct pdf_time_cal_span_s span1;
/* ...create and manipulate ‘mytime’, ‘span1’ and ‘span2’... */
switch (pdf_time_cal_span_cmp (&span1, &span2, mytime))

{
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;
}
}
pdf_status_t pdf_time_cal_span_diff (const struct [Function]

pdf time cal span s *p_span1, const struct pdf time cal span s *p_span2,
const pdf time t base_time, struct pdf time cal span s *p_result )
Compute the difference between two calendar spans relative to a given base time and
store it in a given calendar span.
Parameters
p span1 The pointer to the first calendar span to diff.
p span2 The pointer to the second calendar span to diff.
base time The base time. Should be a correctly created time variable.
p result Pointer to the calendar structure holding the result of the
difference.
PDF_EBADDATA
There is invalid data in span1 or span2.
Usage example
pdf_time_t mytime;
struct pdf_time_cal_span_s result;
/* ...create and manipulate ‘span1’, ‘span2’ and

* ‘result’...
*/
if (pdf_time_cal_span_diff (&span1,
&span2,
mytime,
&result) == PDF_EBADDATA)
{
/* Invalid data in ‘span1’ or ‘span2’ */
}
2.10.12 Platform-specific functions

pdf_status_t pdf_time_w32_set_from_filetime (pdf time t [Function]
time_var, const FILETIME *p_filetime )
This function will initialize time var to the given Filetime epoch in UTC timescale.
This function is only available in Windows OS.
Parameters
variable.
p filetime Pointer to a valid FILETIME structure, containing
100-nanosecond intervals since 1 January 1601.
Usage example
pdf_time_t mytime;
FILETIME filetime;
/* do stuff to get the FILETIME */
pdf_time_w32_set_from_filetime(mytime, &filetime);
2.11 The Filesystem Module

2.11.1 Filesystem Concepts
Filesystem objects provides access to file system services in an abstract way, letting the
library client to define filesystems for other classes of devices. Open files are readable or
writeable file items in a filesystem. Path names are named locations identifying files or
folders.
In the GNU PDF Library a filesystem object (of type pdf_fsys_t) is an implementation
of the file system services for a specific class of devices. The filesystem object provides the
functionality to open files, read and write data from/to open files, create and delete folders,
rename files, manage file and folder permissions, etc.
By implementing the functions defined in the Filesystem Implementation Interface the
client can define and use its own filesystems. In this way a high level of abstraction is
achieved in the library code that uses the filesystem services: the library is able to read
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.
2.11.2 Filesystem Interfaces

This section describes several interfaces that can be found in the Filesystem module. There
is an internal interface filesystem implementors can implement to define a new filesystem. It
is called the Filesystem Implementation Interface. A Filesystem Definition Interface allow
users to register the implementation functions into a filesystem variable. There are also
two interfaces implemented by the Filesystem module allowing clients to access the module
functionality: the Filesystem Interface, used to manage several filesystem aspects, and the
File Interface, that provides functionalities related to open files, such as reading and writing
information.
2.11.3 The Filesystem Interface

The Filesystem Interface is implemented by the Filesystem module and provides access to
some filesystem functionalities in a filesystem implementation independent way.
The functionality covered by the Filesystem Interface includes:
• Folder management.
• Folder contents management.

• Volume-level flush operations.
• Read In Advance (RIA) capabilities.
• Storage properties management (free space, etc).
• Management of filesystem items (rename, remove, flags, etc).
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.
2.11.3.1 Filesystem Data Types

The following data types are defined and provided to the client by the Filesystem Module.
pdf_fsys_t [Data Type]

An opaque type representing a filesystem.
struct pdf fsys item props s [Data Type]

This structure holds information about a filesystem item (a file or a directory).
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
2.11.3.2 Getting File System Properties
pdf_i64_t pdf_fsys_get_free_space (pdf fsys t filesystem, [Function]

pdf text t path_name )
Get the free storage space in the volume containing path name.
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
2.11.3.3 Folder Management

pdf_status_t pdf_fsys_create_folder (const pdf fsys t [Function]
filesystem, const pdf text t path_name )
Create a folder named path name.
Parameters
filesystem A filesystem. If NULL the default filesystem is used.
path name
The path name of the folder to be created.
PDF_OK The folder was successfully created.
PDF_EBADNAME
The specified path name is incorrect.
PDF_EBADPERMS
The client does not have permissions to create the folder.
PDF_ERROR
Any other error condition.
Usage example
XXX
pdf_status_t pdf_fsys_get_folder_contents (const pdf fsys t [Function]
filesystem, const pdf text t path_name, pdf list t item_list )
Get a list with the path names of the items contained in a given folder.
Parameters
path name
The path name of a folder.
item list An output list variable to hold the path names of the items
contained in the folder.
PDF_EBADNAME
path name does not name a folder in the filesystem.
PDF_EBADPERMS
The client does not have permissions to read the contents of
the folder.
PDF_ERROR
Any other error condition.
Usage example
XXX
pdf_status_t pdf_fsys_get_parent (const pdf fsys t filesystem, [Function]

const pdf text t path_name, pdf text t parent_path )
Get the path name of the father of a given item in the filesystem.
Parameters
path name
The path name of an item in the filesystem.
parent path
Output text variable to hold the path of the parent of the item
identified by path name. If path name is the root directory
then NULL is returned in parent path.
PDF_OK The path name of the parent of the item was successfully
stored in parent path.
PDF_EBADNAME
path name does not name a valid item in the filesystem.
PDF_EBADPERMS
The client does not have permissions to get the parent of the
specified item.
Usage example
XXX
pdf_status_t pdf_fsys_remove_folder (const pdf fsys t [Function]

filesystem, const pdf text t path_name )
Remove an empty folder from the filesystem.
Parameters
path name
A path name of an empty folder in the filesystem.
PDF_OK The folder was successfully removed.
PDF_EBADNAME
path name does not name a folder in the filesystem.
PDF_EBADPERMS
The client does not have permissions to remove the folder.
PDF_ERROR
Any other error.
Usage example
XXX
2.11.3.4 Getting File System Item Properties

The following functions provides access to generic properties of filesystem items (both files
and directories).
pdf_status_t pdf_fsys_get_item_props (pdf fsys t filesystem, [Function]

pdf text t path_name, struct pdf fsys item props s *item_props )
Get the properties of a filesystem item identified by a path name.
Parameters
path name
A pdf string containing the path name of the filesystem item.
item props
The address of a structure to hold the properties of the filesys-
tem item.
PDF_EBADDATA
Invalid path name.
PDF_EBADPERMS
The client does not have enough permissions to read the re-
quested item.
Usage example
struct pdf_fsys_item_props_s item_props;
pdf_status_t ret;
pdf_text_t path;
ret = pdf_text_new_from_unicode ("/path/to/foo",

12, PDF_TEXT_UTF8,
&path);
/* Get the properties for the item */
pdf_status_t ret = pdf_fsys_get_item_props (NULL, path, &item_props);
pdf_status_t pdf_fsys_item_props_to_hash (const struct [Function]

pdf fsys item props s item_props, pdf hash t props_hash )
Get a PDF hash variable containing the properties of a filesystem item.
The key-value pairs returned in the hash variable are the following:
isHidden Boolean value.
isReadable
Boolean value.
isWritable
Boolean value.
creationDate
Text value containing a PDF style date string.
modDate Text value containing a PDF style date string.
fileSizeHigh
32bit unsigned integer value.
fileSizeLow
folderSize
creatorCode
versionMajor
versionMinor
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.
PDF_OK The operation succeeded and the properties were stored in
the hash variable.
Usage example
XXX
pdf_bool_t pdf_fsys_item_p (pdf fsys t filesystem, pdf text t [Function]

path_name )
Determine if a given item, identified by a path name, exists in a given filesystem.
Parameters
path name
A path name.
PDF_TRUE The specified item exists in the filesystem.

PDF_FALSE
The specified item does not exist in the filesystem or the
client does not have enough permissions to be able to read it.
Usage example
pdf_bool_t ret;
pdf_status_t status;
pdf_text_t path;
status = pdf_text_new_from_unicode ("/path/to/foo",

12, PDF_TEXT_UTF8,
&path);
/* Test whether the path to /path/to/foo is a valid path to foo */
pdf_bool_t ret = pdf_fsys_item_p (NULL, path);
pdf_bool_t pdf_fsys_item_readable_p (pdf fsys t filesystem, [Function]
Determine if a given filesystem item, identified by a path name, is readable.
Parameters
path name
A valid path name of an existing filesytem item.
PDF_TRUE The filesystem item is readable.
PDF_FALSE
The filesystem item is not readable.
Usage example
pdf_text_t path;

12, PDF_TEXT_UTF8,
&path);
/* Determine if the item is readable */
pdf_bool_t ret = pdf_fsys_item_readable_p (NULL, path);
pdf_bool_t pdf_fsys_item_writable_p (pdf fsys t filesystem, [Function]
Determine if a given filesystem item, identified by a path name, is writable.
Parameters
path name
A valid path name of an existing filesystem item.

PDF_TRUE The filesystem item is writable.
PDF_FALSE
The filesystem item is not writable.
Usage example
pdf_text_t path;

12, PDF_TEXT_UTF8,
&path);
/* Determine if the item is writable */
pdf_bool_t ret = pdf_fsys_item_writable_p (NULL, path);
pdf_status_t pdf_fsys_build_path (pdf fsys t filesystem, [Function]
pdf text t *output, pdf text t first_name, ...)
Build a file path by concatenating first name with the following variable-length list
of pdf_text_t objects, store resulting path in output.
Parameters
output A pdf text t pointer where the resulting path name will be
stored.
first name First text path component.
... Variable-length pdf text t object list, last element must be
NULL.
Returns Returns PDF OK if operation succeeded and output points to built path.
Usage example
pdf_status_t st;
pdf_text_t full_path = NULL;
pdf_text_t filename = NULL;
pdf_text_t parent_path = get_current_dir_as_text (); /* example */
pdf_text_new_from_from_unicode ("filename.txt", strlen ("filename.txt"),

PDF_TEXT_UTF8, &filename);
st = pdf_fsys_build_path (NULL, &full_path, parent_dir, filename);
if (st != PDF_OK)
{
/* ... */
}
2.11.4 The File Interface

The File Interface is implemented by the filesystem module and provides access to filesystem
functionality related with open files, such as writing and reading data to/from a specific
file.
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.
2.11.4.1 File Data Types

The following file-related data types are defined and provided to the client by the Filesystem
Module.
pdf_fsys_file_t [Data Type]

An opaque type representing an open file. The client can perform several operations
in the file using the pdf_fsys_file_t as a reference.
enum pdf_fsys_file_mode_e [Data Type]

The mode used when opening a file in a filesystem. The available modes are described
in the following list.
PDF_FSYS_OPEN_MODE_READ
The file is opened in read-only mode. The file should exist in the filesys-
tem.
PDF_FSYS_OPEN_MODE_WRITE
The file is opened in write-only mode. The file is truncated to 0 size (any
previous contents are lost) if the file exists and it is created if it does not
exist.
PDF_FSYS_OPEN_MODE_RW
The file is opened in read/write mode. The file should exist in the filesys-
tem.
2.11.4.2 Opening Files

pdf_status_t pdf_fsys_file_open (const pdf fsys t filesystem, [Function]
const pdf text t path_name, const enum pdf fsys file mode e mode,
pdf fsys file t *file )
Open a file in filesystem identified by path name using the specified mode and store
a new open file variable in file.
Parameters
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.
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
pdf_status_t pdf_fsys_file_open_tmp (const pdf fsys t [Function]

filesystem, pdf fsys file t *file )
Create a temporary file in filesystem and open it.
The temporary file is opened with mode PDF_FSYS_OPEN_MODE_RW and stored in file.
The file will be automatically deleted with it is closed.
Note that while the filesystem implementation may also delete the file when the client
application exits, it is not guaranteed.
Parameters
file The output file variable.
PDF_OK The file was successfully opened and stored in the file vari-
able. If the filesystem implementation does not support this
functionality then NULL is stored in file.
PDF_ENOMEM
Not enough memory.
PDF_ERROR
It was not possible to create the temporary file.
Usage example
pdf_fsys_file_t tmpfile;
pdf_size_t written;
/* Open a temporary file and write some contents to it. */

pdf_fsys_file_open_tmp (NULL, &tmpfile);
pdf_fsys_file_write (tmpfile, "Temporary data", 14, &written);
/* Close the file. This deletes it from the filesystem. */

pdf_fsys_file_close (tmpfile);
2.11.4.3 File Properties Management

The following functions provides access to several properties of open files.
pdf_size_t pdf_fsys_file_get_size (pdf fsys file t file ) [Function]

Get the size (in number of octects) of a given open file.
Parameters
file An open file.
Returns The size of the file in octects.
Usage example
XXX
pdf_fsys_t pdf_fsys_file_get_filesystem (pdf fsys file t file ) [Function]

Get the filesystem associated with a given open file.
Parameters
file An open fiile.
Returns The filesystem associated with file.
Usage example
XXX
enum pdf_fsys_file_mode_e pdf_fsys_file_get_mode [Function]

(pdf fsys file t file )
Return the access mode used to open a given file.
Parameters
file An open file.
Returns A mode value if successful, otherwise returns -1.
Usage example
pdf_status_t ret;
pdf_fsys_file_t file = pdf_alloc(sizeof(pdf_fsys_file_s));
pdf_text_t path;

12, PDF_TEXT_UTF8,
&path);
ret = pdf_fsys_file_open (NULL, path, PDF_FSYS_OPEN_MODE_READ, file);
enum pdf_fsys_file_mode_e mode;

mode = pdf_fsys_file_get_mode(file);
pdf_text_t pdf_fsys_file_get_url (pdf fsys file t file ) [Function]
Get a text variable containing a valid URL to refer to a given open file. Note that
for some filesystems could be not possible to build a valid URL.
Parameters
file An open file.
Returns A PDF text variable containing a valid URL that can be used to refer to
the open file.
If the filesystem does not support URLs then an empty string is returned.
Usage example
XXX
pdf_status_t pdf_fsys_file_set_mode (pdf fsys file t file, enum [Function]
pdf fsys file mode e new_mode )
Update the mode of a given open file.
Parameters
file An open file.
new mode The new mode to set for the file.
Returns Returns PDF OK if the mode is set to the new mode, otherwise returns
an appropriate pdf status t error. A PDF status value:
PDF_EBADDATA
The mode provided was invalid.
PDF_ERROR
General failure, most applicable to Win32.
Usage example
pdf_status_t ret;
pdf_text_t path;

12, PDF_TEXT_UTF8,
&path);
ret = pdf_fsys_file_open (NULL, path, PDF_FSYS_OPEN_MODE_WRITE, file);
enum pdf_fsys_file_mode_e mode = PDF_FSYS_OPEN_MODE_READ;

ret = pdf_fsys_file_set_mode(file, mode);
2.11.4.4 Comparing Files

The following functions allow to compare files.
pdf_bool_t pdf_fsys_file_same_p (pdf fsys file t file, pdf text t [Function]

path )
Determine whether a given open file is the same file as a given file identified by a file
path.
Parameters
file An open file.
path A file path.
PDF_TRUE Both files are the same file.
PDF_FALSE
The files are not the same file, or the given pathname does
not identify a file in the underlying filesystem.
Usage example
pdf_bool_t ret;
pdf_fsys_file_t file; /* some pre-initialized file variable */
pdf_text_t other_path;
status = pdf_text_new_from_unicode ("/path/to/baz",

12, PDF_TEXT_UTF8,
&other_path);
ret = pdf_fsys_file_same_p (file, other_path);
2.11.4.5 Managing File Positions

The following functions allow to move the input/output pointer of a buffer file (its “current
position”).
pdf_status_t pdf_fsys_file_get_pos (pdf fsys file t file, [Function]

pdf size t *pos )
Get the current position (in octects) in a given open file.
Parameters
file An open file.
pos The address of a pdf_size_t variable.
PDF_ERROR
The function call failed due to an error.
Usage example
pdf_status_t ret;
pdf_text_t path;

12, PDF_TEXT_UTF8,
&path);
pdf_size_t pos = 20;

ret = pdf_fsys_file_get_pos(file, pos);
pdf_status_t pdf_fsys_file_set_pos (pdf fsys file t file, [Function]

pdf size t new_pos )
Set the current position in a given open file.
Parameters
file An open file.
new pos The new position of the 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_text_t path;

12, PDF_TEXT_UTF8,
&path);
pdf_size_t pos = 20;

ret = pdf_fsys_file_set_pos(file, pos);
2.11.4.6 Changing the Size of a File

pdf_bool_t pdf_fsys_file_can_set_size_p (pdf fsys file t file, [Function]
pdf size t size )
Determine if a given open file is resizeable to a given size.
Parameters
file An open file.
size The new size for the file in octects.
PDF_TRUE The file can be resized to the given size.
PDF_FALSE
The file cannot be resized to the given size.
Usage example
XXX
pdf_status_t pdf_fsys_file_set_size (pdf fsys file t file, [Function]

pdf size t size )
Resize a given file to a given new size measured in octects.
Parameters
file An open file.
new size The new size for the file. If it is bigger than the previous size
then the file is augmented to that size. If it is shorter than
the previous size then the file gets truncated.
Returns A PDF size value indicating the new size of the file. It should match the
requested new size, or is 0 if there is an error.
Usage example
XXX
2.11.4.7 Synchronous Input/Output

The following functions provides synchronous input/output for open files.
pdf_status_t pdf_fsys_file_read (pdf fsys file t file, pdf char t [Function]

*buf, pdf size t bytes, pdf size t *read_bytes )
Synchronously read data from an open file item.
Parameters
file An open file.
buf The buffer to hold the read data.
bytes The number of octects to read.
read bytes
The number of octects actually read.

PDF_OK All the requested bytes were successfully read into buf.
PDF_EBADDATA
The file element or a given pointer is invalid.
PDF_EEOF An end of file condition occurred.
PDF_ERROR
An error prevented to read the bytes.
Usage example
XXX
pdf_status_t pdf_fsys_file_write (pdf fsys file t file, pdf char t [Function]
*buf, pdf size t bytes, pdf size t *written_bytes )
Synchronously write data to an open file item.
Parameters
file An open file.
buf A pointer to memory containing the data to write into the
file.
bytes The number of octects to write.
written bytes
The number of octects actually written.
PDF_OK All the requested bytes were successfully written to file.
PDF_EBADDATA
The file element or a given pointer is invalid.
PDF_ENOMEM
A disk full condition ocurred.
PDF_ERROR
Usage example
XXX
pdf_status_t pdf_fsys_file_flush (pdf fsys file t file ) [Function]
Flush all the written data for the specified file.
Parameters
file An open file variable.
PDF_OK The open file was flushed successfully.
PDF_EBADDATA
Bad function parameters to underlying write().
PDF_EAGAIN
Try again.
PDF_ERROR
There was an error flushing the open file.
Usage example
XXX
2.11.4.8 Read in Advance

When working with slow filesystems (such as network filesystems) it is useful to be able to
request parts of the file in advance.
pdf_status_t pdf_fsys_file_request_ria (pdf fsys file t file, [Function]
pdf size t offset, pdf size t count )
Request a Read-In-Advance operation in a given open file.
Note that it is up to the underlying filesystem to honour the operation. If the filesys-
tem does not implement RIA capabilities then this function is a no-op.
Parameters
file An open file.
offset The beginning of the requested block.
count The size (in octects) of the requested block.
PDF_ERROR
An error occurred.
Usage example
XXX
pdf_bool_t pdf_fsys_file_has_ria (pdf fsys file t file ) [Function]
Determine whether the filesystem is performing some RIA operation for the given
open file.
tem does not implement RIA capabilities then this function always return PDF_FALSE.
Parameters
file An open file.
PDF_TRUE The filesystem is performing some RIA operation in the given
file.
PDF_FALSE
There is not an outstanding RIA operation in the given file.
Usage example
XXX
pdf_status_t pdf_fsys_file_cancel_ria (pdf fsys file t file ) [Function]

Cancel any pending RIA operation in a given open file.
tem does not implement RIA capabilities then this function is a no-op.
Parameters
file An open file.
PDF_OK Any pending RIA operation was cancelled.
Usage example
XXX
2.11.4.9 Closing and Reopening Files

The following functions allow to close an open file or to reopen it using another file mode.
pdf_status_t pdf_fsys_file_close (pdf fsys file t file ) [Function]

Close a given open file. Any pending output data is flushed before to close the file.
Parameters
file An open file.
PDF_OK The file was successfully closed.
PDF_ERROR
There was an error closing the file.
Usage example
XXX
pdf_status_t pdf_fsys_file_reopen (pdf fsys file t file, enum [Function]

pdf fsys file mode e mode )
Reopen a given open file with a given mode.
Parameters
file An open file.
mode A file mode.
PDF_OK The file was successfully reopened using the new mode.
PDF_EBADPERMS
The client does not have enough permissions to open the file
using the specified mode. The open file is now closed.
Usage example
XXX
2.11.5 The Filesystem Implementation Interface

The filesystem implementation interface is a set of functions that are installed in a pdf_
fsys_t variable in order to provide its functionality. By implementing those functions
the client can provide a filesystem for some (physical or logical) storage device: a webdav
directory, a read-only http filesystem, etc.
Note that the functions conforming the Implementation Interface are not intended to be
directly invoked by clients. Clients can access to the functionality of the filesystem using
indirect ways:
• Making calls to the Filesystem Interface.
• Making calls to the File Interface.
The implementation of both interfaces then makes use of the Filesystem Implementation
Interface in order to honour the petition.
2.11.5.1 File System Interface Implementation

pdf_status_t (*pdf_fsys_init_fn_t) (void **data ) [Data Type]
Filesystem callback called to initialize the filesystem internal state, if any.
This callback is called by the pdf_fsys_create function.
pdf_status_t (*pdf_fsys_cleanup_fn_t) (void *data ) [Data Type]

Filesystem callback called to cleanup the filesystem internal state, if any.
This callback is called by the pdf_fsys_destroy function.
pdf_status_t (*pdf_fsys_file_open_fn_t) (pdf_text_t [Data Type]

path_name, enum pdf_fsys_file_mode_e mode, pdf_fsys_file_t
*file )
Filesystem callback called to open a file identified by the path path name in the mode
specified by mode. A new pdf_fsys_file_t is created and stored in file.
This callback is called by the pdf_file_fsys_open filesystem interface function.
pdf_status_t (*pdf_fsys_file_open_tmp_fn_t) [Data Type]

(pdf_fsys_file_t *file )
Filesystem callback called to create a temporary file, to open it in read/write mode
and to store it in file.
This callback is called by the pdf_fsys_file_open_tmp filesystem interface function.
pdf_status_t (*pdf_fsys_close_fn_t) (pdf_fsys_file_t [Data Type]

file )
Filesystem callback used to close a given file identified by the open file variable file.
The output buffers of the file are flushed before to close it.
This callback is called by the pdf_fsys_close filesystem interface function.
The following callbacks are defined to provide folder management: creation, deletion and
modification of folders in the filesystem and retrieval of folder contents.
pdf_status_t (*pdf_fsys_create_folder_fn_t) (pdf_text_t [Data Type]

path_name )
Filesystem callback used to create a folder identified by the path name path name.
This callback is called by the pdf_fsys_create_folder filesystem interface function.
pdf_status_t (*pdf_fsys_get_folder_contents_fn_t) [Data Type]
(pdf_text_t path_name, pdf_list_t item_list )
Filesystem callback used to get the contents of a specified folder as a list of path
names.
This callback is called by the pdf_fsys_get_folder_contents filesystem interface
function.
pdf_status_t (*pdf_fsys_get_parent_fn_t) (pdf_text_t [Data Type]
path_name, pdf_text_t parent_path )
Filesystem callback used to get the path name of the father of a given item in a
filesystem. If path name is the root directory then NULL is returned in parent path.
This callback is called by the pdf_fsys_get_parent filesystem interface function.
pdf_status_t (*pdf_fsys_remove_folder_fn_t) (pdf_text_t [Data Type]
path_name )
Filesystem callback used to remove an empty folder identified by path name.
This callback is called by the pdf_fsys_remove_folder filesystem interface function.
The following callbacks are defined to provide synchronous input/output in open files.
pdf_status_t (*pdf_fsys_file_read_fn_t) (pdf_fsys_file_t [Data Type]
file, pdf_char_t*buf, pdf_size_t bytes,
pdf_size_t*read_bytes )
Filesystem callback used to synchronously read data from an open file item.
This callback is called by the pdf_fsys_file_read file interface function.
pdf_status_t (*pdf_fsys_file_write_fn_t) [Data Type]
(pdf_fsys_file_t file, pdf_char_t*buf, pdf_size_t bytes,
pdf_size_t*written_bytes )
Filesystem callback used to synchronously write data to an open file item.
This callback is called by the pdf_fsys_file_write file interface function.
pdf_status_t (*pdf_fsys_file_flush_fn_t) [Data Type]
(pdf_fsys_file_t file )
Filesystem callback used to flush all the written data for the specified file.
This callback is called by the pdf_fsys_file_flush file interface function.
The following callbacks are defined to provide access to several filesystem item properties.
The file system items are addressed using path names.
pdf_status_t (*pdf_fsys_get_item_props_fn_t) (pdf_text_t [Data Type]
path_name, struct pdf_fsys_item_props_s *props )
Filesystem callback used to get the properties of a named filesystem item.
This callback is called by the pdf_fsys_get_item_props filesystem interface func-
tion.
pdf_size_t (*pdf_fsys_get_free_space_fn_t) (pdf_text_t [Data Type]

path_name )
Filesystem callback used to get the free storage space in the volume containing
path name.
This callback is called by the pdf_fsys_get_free_space file system interface func-
tion.
pdf_bool_t (*pdf_fsys_item_p_fn_t) (pdf_text_t [Data Type]

path_name )
Filesystem callback used to determine whether a given item, identified by a path
name, exists in a given filesystem.
This callback is called by the pdf_fsys_item_p file system interface function.
pdf_bool_t (*pdf_fsys_item_readable_p_fn_t) (pdf_text_t [Data Type]

path_name )
Filesystem callback used to determine whether a given filesystem item, identified by
a path name, is readable.
This callback is called by the pdf_fsys_item_readable_p file system interface func-
tion.
pdf_bool_t (*pdf_fsys_item_writable_p_fn_t) (pdf_fsys_t [Data Type]

filename, pdf_text_t path_name )
Filesystem callback used to determine whether a given filesystem item, identified by
a path name, is writeable.
This callback is called by the pdf_fsys_item_writeable_p file system interface func-
tion.
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);
pdf_status_t (*pdf_fsys_build_path_fn_t) (void * data, [Data Type]

pdf_text_t *output, pdf_text_t first_name, pdf_list_t rest )
Filesystem callback used to concatenate and build a file path. Where rest is a list of
pdf text t objects.
This callback is called by the pdf_fsys_build_path file system interface function.
2.11.5.2 File Interface Implementation

The following callbacks are defined to provide access to several file properties.
pdf_bool_t (*pdf_fsys_file_can_set_size_fn_t) [Data Type]

(pdf_fsys_file_t file, pdf_size_t pos )
Filesystem callback used to determine if it is possible to set the size of a given file to
an especified value.
The callback should return a PDF bool value specifying if it is possible to perform
the operation.
pdf_status_t (*pdf_fsys_file_get_size_fn_t) [Data Type]

Filesystem callback used to get the logical size of a file (in octects).
The callback should return a PDF status value:
PDF_OK The operation was successfully performed and the logical size of the file
was stored in pos.
PDF_BADPERMS
The client does not have enough permissions to get the logical size of file.
pdf_status_t (*pdf_fsys_file_set_size_fn_t) [Data Type]
Filesystem callback used to set the logical size of a file (in octects).
The callback should return a PDF status value:
PDF_OK The operation was successfully performed and the logical size of the file
was changed.
PDF_BADPERMS
The client does not have enough permissions to set the logical size of file.
pdf_status_t (*pdf_fsys_file_get_pos_fn_t) [Data Type]
(pdf_fsys_file_t file, pdf_size_t *pos )
Filesystem callback used to get the current position in a given file.
The callback should return a PDF status variable:
PDF_OK The operation was successfully performed and the current position in file
was stored in pos.
This callback is called by the pdf_fsys_file_get_pos file interface function.
pdf_status_t (*pdf_fsys_file_set_pos_fn_t) [Data Type]
Filesystem callback used to set the current position in a given file.
The callback should return a PDF status variable:
PDF_OK The operation was successfully performed and the current position in nfile
was set to pos.
This callback is called by the pdf_fsys_file_set_pos file interface function.
enum pdf_fsys_file_mode_e (*pdf_fsys_file_get_mode_fn_t) [Data Type]
Filesystem callback used to get the open mode of a given open file.
This callback is called by the pdf_fsys_file_get_mode file interface function.
pdf_status_t (*pdf_fsys_file_set_mode_fn_t) [Data Type]
(pdf_fsys_file_t file, enum pdf_fsys_file_mode_e new_mode )
Filesystem callback used to update the mode of a given open file with a given set of
file modes.
This callback is called by the pdf_fsys_file_set_mode file interface function.
pdf_text_t (*pdf_fsys_file_get_url_fn_t) [Data Type]

Filesystem callback used to get a URL pointing to a given open file.
This callback is called by the pdf_fsys_file_get_url file interface function.
pdf_bool_t (*pdf_fsys_file_same_p_fn_t) (pdf_fsys_file_t [Data Type]

file, pdf_text_t path_name )
Filesystem callback used to determine whether a given open file is the same file as a
given file identified by a file path.
This callback is called by the pdf_fsys_file_same_p file interface function.
pdf_status_t (*pdf_fsys_file_request_ria_fn_t) [Data Type]

(pdf_fsys_file_t file, pdf_size_t offset, pdf_size_t count )
Filesystem callback used to request a Read-In-Advance operation in a given open file.
This callback is called by the pdf_fsys_file_request_ria file interface function.
pdf_bool_t (*pdf_fsys_file_has_ria_fn_t) [Data Type]

Filesystem callback used to determine whether the filesystem is performing some RIA
operation for the given open file.
This callback is called by the pdf_fsys_file_has_ria file interface function.
pdf_status_t (*pdf_fsys_file_cancel_ria_fn_t) [Data Type]

Filesystem callback used to cancel any pending RIA operation in a given open file.
This callback is called by the pdf_fsys_file_cancel_ria file interface function.
pdf_status_t (*pdf_fsys_file_close_fn_t) [Data Type]

Filesystem callback used to close a given open file.
This callback is called by the pdf_fsys_file_close file interface function.
pdf_status_t (*pdf_fsys_file_reopen_fn_t) [Data Type]

(pdf_fsys_file_t file, enum pdf_fsys_file_mode_e mode )
Filesystem callback used to reopen a given open file with a given mode.
This callback is called by the pdf_fsys_file_reopen file interface function.
2.11.6 The Filesystem Definition Interface

The Filesystem Definition Interface is implemented by the Filesystem module and pro-
vides functionality to provide an implementation of a filesystem. A pdf_fsys_t should be
properly defined before to use it.
The Filesystem Definition Interface defines the following elements:
• The function types conforming the Filesystem Implementation Interface.
• Installation functions to register implementation functions into a filesystem variable.
2.11.6.1 File System Definition Data Types

struct pdf fsys impl s [Data Type]
Structure containing the callbacks to a concrete file system implementation.
The members of the structure are the following:
pdf_fsys_init_fn init_fn
pdf_fsys_cleanup_fn cleanup_fn
pdf_fsys_open_fn_t open_fn
pdf_fsys_close_fn_t c close_fn
pdf_fsys_create_folder_fn_t create_folder_fn
pdf_fsys_get_folder_contents_fn_t get_folder_contents_fn
pdf_fsys_get_parent_fn_t get_parent_fn
pdf_fsys_remove_folder_fn_t remove_folder_fn
pdf_fsys_file_read_fn_t file_read_fn
pdf_fsys_file_write_fn_t file_write_fn
pdf_fsys_file_flush_fn_t fiile_flush_fn
pdf_fsys_get_item_props_fn_t get_item_props_fn
pdf_fsys_get_free_space_fn_t get_free_space_fn
pdf_fsys_item_p_fn_t item_p_fn
pdf_fsys_item_readable_p_fn_t item_readable_p_fn
pdf_fsys_item_writable_p_fn_t item_writable_p_fn
pdf_fsys_get_temp_path_name_fn_t get_temp_path_name_fn
pdf_fsys_file_can_set_size_fn_t file_can_set_size_fn
pdf_fsys_file_get_size_fn_t file_get_size_fn
pdf_fsys_file_set_size_fn_t file_set_size_fn
pdf_fsys_file_get_pos_fn_t file_get_pos_fn
pdf_fsys_file_set_pos_fn_t file_set_pos_fn
pdf_fsys_file_get_mode_fn_t file_get_mode_fn
pdf_fsys_file_set_mode_fn_t file_set_mode_fn
pdf_fsys_file_get_url_fn_t file_get_url_fn
pdf_fsys_file_same_p_fn_t file_same_p_fn
pdf_fsys_file_request_ria_fn_t file_request_ria_fn
pdf_fsys_file_has_ria_fn_t file_has_ria_fn
pdf_fsys_file_cancel_ria_fn_t file_cancel_ria_fn
pdf_fsys_file_close_fn_t file_close_fn
pdf_fsys_file_reopen_fn_t file_reopen_fn
2.11.6.2 File System Definition Functions
pdf_fsys_t pdf_fsys_create (struct pdf fsys impl s [Function]
implementation )
Create and return a new filesystem variable that will use a given implementation.
Parameters
implementation
A filesystem implementation.
Returns A fileystem variable.
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.
PDF_OK The filesystem was successfully destroyed.
Usage example
XXX
2.12 The Tokeniser

The tokeniser module provides functions to:
− Read PDF lexical tokens from a base layer stream
− Write PDF lexical tokens into a base layer stream
2.12.1 Tokeniser data types

pdf_token_t [Data Type]
A PDF token.
enum pdf_token_type_e [Data Type]
The type of a PDF token.
Valid values are:
PDF_TOKEN_INTEGER
A PDF integer value.
PDF_TOKEN_REAL
A PDF real value (a floating-point number).
PDF_TOKEN_STRING
A PDF string.
PDF_TOKEN_NAME
A PDF name.
PDF_TOKEN_COMMENT
A PDF comment.
PDF_TOKEN_KEYWORD
A keyword, i.e., any string of regular characters such as “null” or “R”
that is not matched as another type.
PDF_TOKEN_DICT_START
The “<<” operator, which marks the beginning of a dictionary.
PDF_TOKEN_DICT_END
The “>>” operator, which marks the end of a dictionary.
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.
pdf_token_reader_t [Data Type]

A token reader that operates on a reading base layer stream and provides a stream
of PDF tokens.
pdf_token_writer_t [Data Type]

A token writer that operates on a writing base layer stream, generating the textual
representation of a PDF token.
2.12.2 Creation and destruction of tokenisers

pdf_status_t pdf_token_reader_new (pdf stm t stm, [Function]
pdf token reader t *reader )
Create a new token reader operating a given reading stream.
Parameters
stm A reading stream.
reader A pointer to a token reader.
PDF_OK The reader was successfully created.
PDF_EBADDATA
stm is not a reading stream.
PDF_ENOMEM
Not enough memory to create the reader.
PDF_ERROR
An error prevented to perform the operation.
Usage example
pdf_stm_t stream;
pdf_token_reader_t reader;
/* Open a file stream */

XXX
/* Create the token reader */

switch (pdf_token_reader_new (stream, &reader))
{
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;
}
}
pdf_status_t pdf_token_writer_new (pdf stm t stm, [Function]

pdf token writer t *writer )
Create a new token writer operating a given reading stream.
Parameters
stm A writing stream.
writer A pointer to a token writer.
PDF_OK The writer was successfully created.
PDF_EBADDATA
stm is not a writing stream.
PDF_ENOMEM
Not enough memory to create the writer.
PDF_ERROR
An error prevented to perform the operation.
Usage example
pdf_stm_t stream;
pdf_token_writer_t writer;
/* Open a file stream */

XXX
/* Create the token writer */

switch (pdf_token_writer_new (stream, &writer))
{
case PDF_BADDATA:
{
/* STREAM is not a valid writing stream */
break;
}
case PDF_ENOMEM:
{
/* Not enough memory to create the writer */
break;
}
case PDF_ERROR:
{
/* Any other error prevented the creation of
the writer */
break;
}
default:
{
/* Success */
break;
}
}
pdf_status_t pdf_token_reader_destroy (pdf token reader t [Function]

reader )
Destroy a token reader freeing any used resources.
Parameters
reader The reader to destroy.
PDF_OK The token reader was destroyed.
PDF_EBADDATA
reader was NULL.
Usage example
/* Create a reader */
XXX
/* Destroy the reader */
pdf_token_reader_destroy (reader);
pdf_status_t pdf_token_writer_destroy (pdf token writer t [Function]

writer )
Destroy a token writer, freeing any used resources.
Parameters
writer The writer to destroy.
PDF_OK The token writer was destroyed.
PDF_EBADDATA
writer was NULL.
Usage example
pdf_token_writer_t writer;
/* Create a writer */
XXX
/* Destroy the writer */
pdf_token_writer_destroy (writer);
2.12.3 Reading tokens

pdf_status_t pdf_token_read (pdf token reader t reader, pdf u32 t [Function]
flags, pdf token t *token )
Read a token from a token reader.
Parameters
reader A token reader.
flags A bitmask specifying a combination of these flags:
PDF_TOKEN_NO_NAME_ESCAPES
Don’t treat “#” as a special character when read-
ing name tokens (this flag should be used when
reading PDF 1.1 files).
PDF_TOKEN_RET_COMMENTS
Return comments as tokens (rather than ignoring
them).
PDF_TOKEN_END_AT_STREAM
Assume that a “stream” keyword token was just
read, find the beginning of the corresponding
stream, and return PDF EEOF when successful
(i.e., when the input stream is positioned after
the first line feed).
token A pointer to a pdf token t that will hold the read token.
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
pdf_status_t pdf_token_reader_reset (pdf token reader t [Function]

reader )
Reset the state of the token reader.
Parameters
reader A token reader.
2.12.4 Writing tokens

pdf_status_t pdf_token_write (pdf token writer t writer, [Function]
pdf u32 t flags, pdf token t token )
Write a given token using a given token writer.
Parameters
writer A token writer.
flags A bitmask specifying a combination of these flags:
PDF_TOKEN_NO_NAME_ESCAPES
Don’t escape special characters using “#” when
writing name tokens (this flag should be used
when writing PDF 1.1 files).
PDF_TOKEN_HEX_STRINGS
Write strings in hexadecimal encoding.
PDF_TOKEN_READABLE_STRINGS
Encode strings in a human-readable way (i.e., in
hexadecimal or with special characters escaped).
token A PDF token.

PDF_EAGAIN
It’s not possible to write a full token now. Since it may have
been partially written, the operation must be repeated with
the same arguments when the stream becomes writable.
PDF_EBADDATA
One of the arguments is invalid. This may be caused by an
invalid token (e.g., one that contains unrepresentable charac-
ters).
PDF_ERROR
An unspecified error occurred.
Usage example
XXX
pdf_status_t pdf_token_writer_reset (pdf token writer t writer ) [Function]
Reset the state of the token writer.
Parameters
reader A token writer.
2.12.5 Creating and destroying tokens

pdf_status_t pdf_token_integer_new (pdf i32 t value, pdf token t [Function]
*token )
Create an integer token.
Parameters
value The numeric value for the token.
token A pointer to the newly created token.
PDF_ENOMEM
Not enough memory.
pdf_status_t pdf_token_real_new (pdf real t value, pdf token t [Function]
*token )
Create a real (floating-point number) token.
Parameters
value The numeric value for the token.

PDF_EBADDATA
The given value is invalid.
PDF_ENOMEM
Not enough memory.
pdf_status_t pdf_token_string_new (const pdf char t *value, [Function]

pdf size t size, pdf token t *token )
Create a string token containing a copy of the given data.
Parameters
value A pointer to the binary data that will make up the string.
size The amount of data to copy, in octets.
PDF_ENOMEM
Not enough memory.
pdf_status_t pdf_token_name_new (const pdf char t *value, [Function]

Create a name token containing a copy of the given data.
Parameters
value A pointer to the binary data that will make up the name.
PDF_EBADDATA
PDF_ENOMEM
Not enough memory.
pdf_status_t pdf_token_keyword_new (const pdf char t *value, [Function]

Create a keyword token containing a copy of the given data.
Parameters
value A pointer to the binary data that will make up the keyword.

PDF_EBADDATA
PDF_ENOMEM
Not enough memory.
pdf_status_t pdf_token_comment_new (const pdf char t *value, [Function]

Create a comment token containing a copy of the given data.
Parameters
value A pointer to the binary data that will make up the keyword.
PDF_EBADDATA
PDF_ENOMEM
Not enough memory.
pdf_status_t pdf_token_valueless_new (enum pdf token type e [Function]

type, pdf token t *token )
Create a token of one of the valueless types (PDF TOKEN DICT START,
PDF TOKEN DICT END, PDF TOKEN ARRAY START, PDF TOKEN ARRAY END,
PDF TOKEN PROC START, or PDF TOKEN PROC END).
Parameters
type The type of token to create.
PDF_ENOMEM
Not enough memory.
PDF_EBADDATA
The given type is not valid for this constructor.
pdf_status_t pdf_token_dup (const pdf token t token, pdf token t [Function]

*new )
Create a copy of the given token.
Parameters
old The token to copy.
new A pointer to the newly created token.
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.
2.12.6 Accessing token attributes

enum pdf_token_type_e pdf_token_get_type (const pdf token t [Function]
token )
Get the type of a given token.
Parameters
token A token.
Returns The type of the given token.
Usage example
pdf_token_t token;
/* ... */
/* 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.
Parameters
token1 A token.
token2 Another token.
PDF_TRUE The given tokens are equal.
PDF_FALSE
The tokens are not equal.
pdf_i32_t pdf_token_get_integer_value (const pdf token t token ) [Function]

Returns the value associated with a given integer token.
Parameters
token A token of type PDF TOKEN INTEGER.
Returns The token’s value.
pdf_real_t pdf_token_get_real_value (const pdf token t token ) [Function]

Returns the value associated with a given real token.
Parameters
token A token of type PDF TOKEN REAL.
Returns The token’s value.
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.
pdf_size_t pdf_token_get_string_size (const pdf token t token ) [Function]

Returns the amount of data associated with a given string token.
Parameters
token A token of type PDF TOKEN STRING.
Returns The string’s size, in octets.
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.
pdf_size_t pdf_token_get_name_size (const pdf token t token ) [Function]

Returns the amount of data associated with a given name token.
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.
The data is null-terminated.
pdf_size_t pdf_token_get_keyword_size (const pdf token t token ) [Function]

Returns the amount of data associated with a given keyword token.
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.
The data is not null-terminated.
pdf_size_t pdf_token_get_comment_size (const pdf token t token ) [Function]

Returns the amount of data associated with a given comment token.
Parameters
token A token of type PDF TOKEN COMMENT.
Returns The comment’s size, in octets.
2.13 Encryption
This section describes related to encryption functions.
2.13.1 Creating and destroying Ciphers

enum pdf_crypt_cipher_algo_e [Data Type]
An algorithm provided. It contains low level functions of the algorithm implementa-
tion.
PDF_CRYPT_CIPHER_ALGO_AESV2
Use AES algorithm with a key of 128 bits to encrypt the data.
PDF_CRYPT_CIPHER_ALGO_V2
Use ARC4 algorithm.
pdf_crypt_cipher_t [Data Type]

A cipher. It contains data which is required between several calls to functions.
pdf_status_t pdf_crypt_cipher_new (enum pdf crypt cipher algo e [Function]

algorithm, pdf crypt cipher t *cipher )
Create a new cipher.
Parameters
algorithm The algorithm the cipher will use in order to encrypt or de-
crypt data.
cipher A pointer to pdf_crypt_cipher_t variable where it will put
the cipher.
PDF_ERROR
A error ocurred when trying to create the cipher.
Usage example
pdf_status_t st;
pdf_crypt_cipher_t cipher;
st = pdf_crypt_cipher_new (PDF_CRYPT_CIPHER_ALG_AESV2, &cipher);
if (st != PDF_OK)
{
/* Error */
}
pdf_status_t pdf_crypt_cipher_destroy (pdf crypt cipher t [Function]

cipher )
Destroy a cipher.
Parameters
cipher The cipher you want destroy. It must have been created with
pdf_crypt_cipher_new functions previously.
Returns
A PDF status value:

PDF_ERROR
A error ocurred when trying to destroy the cipher.
Usage example
pdf_crypt_cipher_new (PDF_CRYPT_CIPHER_ALG_AESV2, &cipher);
pdf_crypt_cipher_destroy (cipher);
2.13.2 Encryption and decryption

pdf_status_t pdf_crypt_cipher_setkey (pdf crypt cipher t [Function]
cipher, pdf char t *key, pdf size t size )
Set the key which will be used to encrypt and decrypt data.
Parameters
cipher A pointer to a cipher created previously.
key A pointer to memory where the key is stored.
size The length of the key in bytes. Note that some algorithms
could require a fixed length of key.
PDF_EBADDATA
Invalid argument. The size parameter is not supported by
the cipher.
PDF_ERROR
A error ocurred while trying to set the key.
Usage example
pdf_status_t st;
pdf_char_t key[16];
/* ... */
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.
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_ERROR
An error ocurred.
Usage example
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);
st = pdf_crypt_cipher_encrypt (cipher, out, out_size, in, in_size, &out_
if (st != PDF_OK)
{
/* Error*/
}
pdf_status_t pdf_crypt_cipher_decrypt (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 )
Decrypt a buffer. The plain text will be put in out.
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. 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_ERROR
An error ocurred.
Usage example
pdf_status_t st;
pdf_char_t *out;
pdf_char_t *in;
pdf_size_t in_size;
/* ... */
out_size = pdf_crypt_cipher_decrypt_size (cipher, in, in_size);
out = pdf_alloc (out_size);
st = pdf_crypt_crypt_decrypt (cipher, out, out_size, in, in_size, &out_s
if (st != PDF_OK)
{
/* Error*/
}
2.13.3 Message digest functions

enum pdf_crypt_md_algo_e [Data Type]
An algorithm provided. It contains low level functions of the algorithm implementa-
tion.
PDF_CRYPT_MD_MD5
Use the md5 algorithm.
pdf_crypt_md_t [Data Type]

A message-digest descriptor.
pdf_status_t pdf_crypt_md_new (enum pdf crypt md algo e algo, [Function]

pdf crypt md t *md )
Create a message-digest descriptor for an algorithm.
Parameters
md A pointer to the pdf crypt md t.
algo Algorithm which be used to hashing.
PDF_ERROR
An error ocurred.
Usage example
pdf_status_t st;
pdf_crypt_md_t md;
st = pdf_crypt_md_new (&md, PDF_CRYPT_MD_MD5);
if (st != PDF_OK)
{
/* Error /*
}
pdf_status_t pdf_crypt_md_write (pdf crypt md t md, pdf char t [Function]

*in, pdf size t in_size )
Pass a buffer to the message-digest handler in order to compute its digest.
Parameters
md A message-digest descriptor.
in A pointer to the input buffer.
in size Size of the input buffer in bytes.
PDF_EBADDATA
Bad parameter. The size of the output buffer is wrong.
Usage example
pdf_crypt_md_t md;
pdf_char_t *in;
pdf_size_t in_size;
pdf_status_t st;
/* ...Prepare IN and IN_SIZE variables */
pdf_crypt_md_new (&md, PDF_CRYPT_MD_MD5);
st = pdf_crypt_md_hash (md, in, in_size);

if (st != PDF_OK)
{
/* Error */
}
pdf_crypt_md_destroy (md);
pdf_status_t pdf_crypt_md_read (pdf crypt md t md, pdf char t [Function]

*out, pdf size t out_size )
Read the computed digest value from a message-digest descriptor.
Parameters
md A message-digest descriptor.
PDF_EBADDATA
Bad parameter. The size of the output buffer is wrong.
Usage example
pdf_crypt_md_t md;
pdf_char_t *out;
pdf_status_t st;
pdf_crypt_md_new (&md, PDF_CRYPT_MD_MD5);
/* ...Write the buffer into descriptor here... */
st = pdf_crypt_md_read (md, out, out_size);
if (st != PDF_OK)
{
/* Error */
}
pdf_status_t pdf_crypt_md_destroy (pdf crypt md t md ) [Function]

Destroy a message-digest descriptor.
Parameters
md An message-digest descriptor.
PDF_ERROR
An error ocurred.
Usage example
pdf_status_t st;
pdf_crypt_md_t md;
st = pdf_crypt_md_new (&md, PDF_CRYPT_MD_MD5);
/* ... /*
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.
Usage example
pdf_char_t buffer[16];
pdf_crypt_nonce (buffer, sizeof(buffer));

Chapter 3: Object Layer 169
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.
Figure 3.1: Hierarchy of objects in a PDF document.
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.
3.2 PDF Objects

PDF objects are the fundamental bricks used in PDF documents. This section describes
data types and functions to create, destroy and manipulate all kind of PDF objects: num-
bers, booleans, names, strings, streams and the null object.
3.2.1 Object Data Types

pdf_obj_t [Data Type]
Opaque type representing a PDF Object.
Despite being opaque, the user shall be aware that a pdf_obj_t variable containing
a direct scalar object shall be considered as the object itself (its value). Otherwise
the variable shall be considered as a “reference”.
enum pdf_obj_type_e [Data Type]

Enumeration of the supported types of PDF objects:
PDF_OBJ_REAL
Real objects denote quantities in the real domain, such as 3,14 and
1,00000.
See Section 3.2.6 [Real Objects], page 187.
PDF_OBJ_INTEGER
Integer objects denote quantities in the integer domain, such as 3 and 1.
See Section 3.2.7 [Integer Objects], page 189.
PDF_OBJ_BOOLEAN
Possible values are true and false.
See Section 3.2.8 [Boolean Objects], page 190.
PDF_OBJ_NAME
A PDF name is an atomic symbol uniquely defined by a sequence of
regular characters. It does not have internal structure.
See Section 3.2.9 [Name Objects], page 192.
PDF_OBJ_STRING
A PDF string is a sequence of bytes whose values are in the range 0-255.
See Section 3.2.10 [String Objects], page 195.
PDF_OBJ_ARRAY
A heterogeneous array of PDF objects.
See Section 3.2.11 [Array Objects], page 198.
PDF_OBJ_DICT
A dictionary is a collection of key-value pairs. Unlike the postscript dic-
tionaries the key should be a Name Object, while the value is a PDF
object of any type.
See Section 3.2.12 [Dictionary Objects], page 204.
PDF_OBJ_STREAM
See Section 3.2.13 [Stream Objects], page 213.
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.
pdf_obj_id_t [Data Type]

A positive integer representing the identification number of a PDF object. An object
ID uniquely represents an object into an object document.
pdf_obj_gen_t [Data Type]

A non-negative number representing the generation number of a PDF object.
pdf_bool_t (*pdf_obj_enum_fn_t) (pdf_obj_t obj, [Data Type]

pdf_obj_t value, void *client_data )
Callback used in pdf_obj_enum that is called for every directly contained object in a
composite PDF object (array, dictionary, stream).
Parameters
obj The meaning of this parameter depends on the type of obj:
Array An array element.
Dictionary
A key.
Stream The stream’s dictionary.
value The meaning of this parameter depends on the type of obj:
Array The Null object.
Dictionary
A value.
Stream The Null object.
Returns A PDF status value.
pdf_obj_col_t [Data Type]

Opaque type representing an object collection into an object document.
See Section 3.2.5 [Object Collections], page 182.
enum pdf_obj_stm_open_mode_e [Data Type]

Open modes for PDF stream objects.
PDF_OBJ_STM_OPEN_MODE_RAW
The data will be decrypted but not filtered.
PDF_OBJ_STM_OPEN_MODE_UNFILTERED
The data wont be filtered nor decrypted.
PDF_OBJ_STM_OPEN_MODE_FILTERED
The data will be both decrypted and filtered.
3.2.2 Generic Functions to Manipulate Objects

The following functions can be called on any pdf_obj_t variable regardless its type. But
note that the effects of the call may vary depending on the object type.
pdf_status_t pdf_obj_copy (pdf obj t source, pdf obj doc t [Function]
dest_doc, pdf bool t copy_indirect, pdf obj t *dest )
Copy a PDF object from one document to another. The destination document can
be the same than the document associated with source.
This operation sets the dirty flag of dest doc if the copied object is not a direct scalar.
Parameters
source The PDF object to copy.
dest doc The object document that will hold the copied object.
copy indirect
A boolean value:
PDF_TRUE All indirectly referenced objects in source are
copied to dest doc.
PDF_FALSE
The indirectly referenced objects in source are
not copied to dest doc. The corresponding en-
tries in source will be missing in dest.
dest A PDF object to hold the copied object.
Returns A PDF status value
PDF_OK The copy was successfully performed.
PDF_ENOMEM
Not enough memory to perform the copy.
PDF_ERROR
Some error prevented the operation to complete. The value
of dest is undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t obj1;
pdf_obj_t obj2;
...
/* Make a copy of ’obj1’ in ’obj2’ in the same object document

’doc’ */
if (pdf_obj_copy (obj1, doc, PDF_TRUE, &obj2)
!= PDF_ERROR_)
{
/* ’obj2’ now contains a copy of ’obj1’. */
}
pdf_status_t pdf_obj_destroy (pdf obj t obj ) [Function]

Destroy a PDF object obj.
This function is a nop if obj is a direct scalar type or the Null object.
If obj is a composite object (array, dictionary, stream) then any directly referenced
object is also destroyed. The indirectly referenced objects are not destroyed. Note
that this is a recursive rule: a string directly contained in a dictionary that is in turn
directly contained in an array will be destroyed if the top-level array is destroyed.
The root dictionary of an object document can not be destroyed.
This operation sets the dirty flag of the document containing the object.
Parameters
obj The PDF object to destroy.
PDF_OK The object was successfully destroyed. The value of obj is
now undefined and shall not be used.
PDF_ERROR
An error prevented to complete the operation. The value of
obj is now undefined and shall not be used.
PDF_EINVOP
The user requested to destroy the root dictionary of the ob-
ject document.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t info_dict;
...
/* Destroy the info dictionary of an object document */

pdf_obj_doc_get_info_dict (doc, &info_dict);
pdf_obj_destroy (info_dict);
pdf_status_t pdf_obj_enum (pdf obj t obj, pdf obj enum fn t [Function]
enum_cb, void *client_data )
Enumerate all the elements of a PDF object by calling a client-provided callback
function.
Parameters
obj The PDF object whose elements are going to be enumerated.
The specific semantics of pdf_obj_enum depend on the type
of this object:
Scalar or a string
The function does nothing and returns PDF_OK.
Dictionary
enum cb is called for every key-value, passing the
key as the first argument and the value as the
second argument. The enumeration order is un-

defined.
Array enum cb is called for every element contained in
the array, passing the value as the first argument
and the Null object as the second argument.
The enumeration order is ascending with the in-
dex of the array.
Stream enum cb is called once with the stream dictio-
nary as the first parameter and the Null object
as the second parameter.
Returns A PDF status value, that is the AND logical value of the values returned
by the enumeration procedure, considering PDF_OK as true and <> PDF_OK
as false.
Usage example
/* Callback function */
pdf_bool_t
my_enum_callback (pdf_obj_t obj,
pdf_obj_t value,
void *client_data)
{
/* Process the callback... */
}
...
/* Perform an enumeration of the elements of some

object */
if (pdf_obj_enum (obj, my_enum_callback, NULL))
{
/* All the calls to ’my_enum_callback’ returned PDF_OK */
}
else
{
/* Some call to ’my_enum_callback’ returned <> PDF_OK */
}
pdf_bool_t pdf_obj_equal_p (pdf obj t obj1, pdf obj t obj2 ) [Function]

Test whether two PDF objects are equal.
Two PDF objects are equal when all the following conditions are satisfied:
− They are both direct objects or indirect objects.
− They have the same type.
− If they are indirect, they share the same generation number and has the same
object number.
− If they are scalars, they have the same value.
− If they are non-scalar, they reference the same value.

Parameters
obj1 The first PDF object to compare.
obj2 The second PDF object to compare.
PDF_TRUE The PDF objects are equal.
PDF_FALSE
The PDF objects are not equal.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t obj1;
pdf_obj_t obj2;
...
/* 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.
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;
...
if (pdf_obj_get_doc (obj, &doc)

!= PDF_ERROR)
{
/* ’doc’ contains a reference to the object document containing
’obj’. */
}
pdf_status_t pdf_obj_get_generation (pdf obj t obj, [Function]

pdf obj gen t *gen_number )
Get the generation number of a given indirect PDF object obj.
Parameters
obj An indirect PDF object.
gen number
A pointer to a pdf_obj_gen_t variable to hold the generation
number.
PDF_OK The generation number was stored in gen number.
PDF_EINVOBJ
obj is not an indirect object. Any previous contents of
gen number are left untouched.
PDF_ERROR
An error prevented to complete the operation. The value of
gen number is invalid and shall not be used.
Usage example
pdf_obj_t obj;
pdf_obj_gen_t gen_number;
...
if (pdf_obj_get_generation (obj, &gen_number)

== PDF_OK)
{
/* ’gen_number’ contains the generation number of ’obj’. */
}
pdf_status_t pdf_obj_get_id (pdf obj t obj, pdf obj id t [Function]

*id_number )
Get the identification number of a given indirect PDF object obj.
Parameters
obj An indirect PDF object.
id number
A pointer to a pdf_obj_id_t variable to hold the id number.

PDF_OK The identification number of obj was stored in id number.
PDF_EINVOBJ
obj is not an indirect object. The previous value of id number
remains.
PDF_ERROR
of id number is invalid and shall not be used.
Usage example
pdf_obj_t obj;
pdf_obj_id_t id_number;
...
if (pdf_obj_get_id (obj, &id_number)

== PDF_OK)
{
/* ’id_number’ contains the identification
number of ’obj’. */
}
enum pdf_obj_type_e pdf obj get type (pdf obj t obj ) [Function]
Get the type of a given PDF object obj.
Parameters
obj A PDF object.
Returns The type of obj.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t obj;
...
/* Create an integer object */

pdf_obj_integer_new (doc, PDF_FALSE, 10, &obj);
/* Get its type */

pdf_obj_get_type (obj); /* Returns PDF_OBJ_INTEGER */
pdf_bool_t pdf_obj_compressed_p (pdf obj t obj ) [Function]
Determine if a given PDF object obj is compressed (i.e. it is contained in an object
collection).
See Section 3.2.5 [Object Collections], page 182.
Parameters
obj A PDF object.

PDF_TRUE The object obj is compressed.
PDF_FALSE
The object obj is not compressed.
Usage example
pdf_obj_t obj;
pdf_obj_col_t objcol;
...
/* Add ’obj’ to an object collection. */

pdf_obj_col_add_obj (objcol, obj);
/* The following call returns PDF_TRUE */

pdf_obj_compressed_p (obj);
pdf_bool_t pdf_obj_indirect_p (pdf obj t obj ) [Function]
Determine if a given PDF object obj is indirect.
Parameters
obj A PDF object.
PDF_TRUE The object obj is indirect.
PDF_FALSE
The object obj is direct.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t obj_direct;
pdf_obj_t obj_indirect;
...
/* Create an indirect object */

pdf_obj_integer_new (doc, PDF_TRUE, 10, &obj_indirect);
pdf_obj_indirect_p (obj_indirect); /* Returns PDF_TRUE */
/* Create a direct object */

pdf_obj_integer_new (doc, PDF_FALSE, 10, &obj_direct);
pdf_obj_indirect_p (obj_direct); /* Returns PDF_FALSE */
3.2.3 Object Strong References

Every PDF object (but direct scalars) contained in an object document features an acquire
counter whose value is initially 0. The garbage collector (see Section 3.3.5 [Garbage col-
lection in object documents], page 228) never destroys unmarked objects with an acquire
counter of 1 or more.
pdf_status_t pdf_obj_acquire (pdf obj t obj ) [Function]

Create a strong reference for obj in its container document by incrementing its acquire
counter by one. For direct scalars this operation is a nop.
Figure 3.2: Acquire counters in PDF objects.

The above figure shows a container object A containing two objects B and C. The
acquire counter of B is 1, meaning that someone acquired the object via the pdf_obj_
t variable. If the object A is garbage collected then C will be also collected, but B
won’t.
Parameters
obj A PDF object.
PDF_OK The strong reference was created or the request was ignored.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t obj;
/* Get an object from a document */

pdf_obj_doc_get_obj (doc, 10, 0, &obj);
/* Create a strong reference for the object in ‘doc’ */

pdf_obj_acquire (obj);
pdf_status_t pdf_obj_release (pdf obj t obj ) [Function]

Remove a strong reference from the PDF object obj by decreasing its acquire counter
by one.
For direct scalars this operation is a nop.
Parameters
obj A PDF object.
PDF_OK The strong reference was destroyed or the operation was ig-
nored.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t obj;
/* Get an object from a document */

pdf_obj_doc_get_obj (doc, 10, 0, &obj);
/* Create a strong reference for the object in ‘doc’. Its acquire

counter is increased to 1. */
pdf_obj_acquire (obj);
/* Remove a strong reference for the object in ‘doc’. Its acquire

counter is decreased to 0. */
pdf_obj_release (obj);
3.2.4 Compressibility of Objects

A PDF object is compressible if any of the following conditions are true:
− It is an indirect object.
− It has a generation number of zero.
− It is not a stream.
− It has not been explicitly marked as incompressible with pdf_obj_set_
compressibility.
A compressible object is suitable to be contained in an object collection. See Section 3.2.5
[Object Collections], page 182.
pdf_bool_t pdf_obj_get_compressibility (pdf obj t obj ) [Function]

Test if a given PDF object obj is compressible. Only compressible objects can be
added to an object collection.
Parameters
obj A PDF object.
PDF_TRUE The object is compressible.

PDF_FALSE
The object is not compressible.
Usage example
pdf_obj_t obj;
...
/* Check the compressibility of a PDF object */

if (pdf_obj_get_compressibility (obj))
{
/* The object ’obj’ is compressible. */
}
pdf_bool_t pdf_obj_set_compressibility (pdf obj t obj, [Function]

pdf bool t compressible_p )
Set the compressibility attribute of the PDF object obj.
Parameters
obj A PDF object.
compressible p
A boolean value.
PDF_OK The compressibility of obj was set according to compress-
ible p.
PDF_EINVOBJ
obj cannot be compressed.
PDF_ERROR
Some error prevented the operation to complete.
Usage example
pdf_obj_t obj;
...
/* Set the compressibility of ’obj’ to true */

pdf_obj_set_compressibility (obj, PDF_TRUE);
/* Set it back to false */

pdf_obj_set_compressibility (obj, PDF_FALSE);
3.2.5 Object Collections

Sometimes a group of objects are related in a way they acquire “locality”, meaning that
if one of those objects is read it is very likely that the other objects will be read as well.
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.
PDF_OK The object collection was created and a reference to it was
stored in col.
PDF_ERROR
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;
...
/* Create some object collections */

pdf_obj_col_new (doc, &col1);
pdf_status_t pdf_obj_col_enum (pdf obj col t col, [Function]
pdf obj enum fn t enum_cb, void *client_data )
Enumerate all the PDF objects contained in the given object collection col.
Parameters
col An object collection.
enum cb The callback function.
client data
Pointer passed to the callback function.
Returns A PDF status value, that is the AND logical value of the values returned
by the enumeration procedure, considering PDF_OK as true and <> PDF_OK
as false.
Usage example
/* Callback function */
pdf_bool_t
my_enum_callback (pdf_obj_t obj,
pdf_obj_t value,
void *client_data)
{
/* Process the callback... */
}
...
/* Perform an enumeration of the objects contained in some object

collection ’col’. */
if (pdf_obj_col_enum (col, my_enum_callback, NULL)
== PDF_OK)
{
/* All the calls to ’my_enum_callback’ returned PDF_OK */
}
else
{
/* Some call to ’my_enum_callback’ returned <> PDF_OK */
}
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.
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;
...
/* Create two object collections and compare them */

pdf_obj_col_equal_p (col1, col2); /* Returns PDF_FALSE */

pdf_obj_col_equal_p (col1, col1); /* Returns PDF_TRUE */
pdf_u32_t pdf_obj_col_size (pdf obj col t col ) [Function]

Get the number of PDF objects contained in the object collection col.
Parameters
Returns The number of objects contained in col.
Usage example
pdf_obj_doc_t doc;
pdf_obj_col_t col;
pdf_obj_t obj1;
pdf_obj_t obj2;
...
/* Create an object collection and put some objects in it. */

pdf_obj_col_new (doc, &col);
pdf_obj_col_add_obj (objcol, obj1);
pdf_obj_col_add_obj (objcol, obj2);
/* Get the number of objects */

pdf_obj_col_size (objcol); /* Should return 2 */
pdf_status_t pdf_obj_col_add_obj (pdf obj col t col, pdf obj t [Function]

obj )
Add an object obj to a collection col. The given object should be compressible.
This operation sets the dirty flag of the document containing the object collection.
Parameters
obj A PDF object.
PDF_OK The object obj was successfully added into the object collec-
tion col.
PDF_EINVOBJ
The object obj is not compressible.
PDF_ERROR
An error prevented the operation to complete.
Usage example
pdf_obj_col_t col;
pdf_obj_t obj;
...
/* Add an object into an object collection */

pdf_obj_col_add_obj (col, obj);
pdf_status_t pdf_obj_col_remove_obj (pdf obj t obj ) [Function]

Remove a given PDF object obj from its containing object collection. If the object
is not contained in an object collection then this operation is a nop.
This operation sets the dirty flag of the document containing the object collection.
Parameters
obj A PDF object.
PDF_OK The object was successfully dissociated from any containing
object collection.
PDF_ERROR
Usage example
pdf_obj_t obj;
pdf_obj_col_t col;
...
/* After the next sentence ’obj’ won’t be associated with ’col’

anymore */
pdf_obj_col_remove_obj (obj);
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.
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.
Usage example
pdf_obj_doc_t doc;
pdf_obj_col_t col;
pdf_obj_t obj;
...
pdf_obj_col_new (doc, &col);

pdf_obj_get_col (obj); /* Returns ’col’ */

pdf_obj_col_remove_obj (obj);
pdf_obj_get_col (obj); /* Returns NULL */
3.2.6 Real Objects

PDF real objects are quantities in the real domain. They are defined by range and precision.
Usually represented in fixed point rather than floating point.
pdf_status_t pdf_obj_real_new (pdf obj doc t doc, pdf bool t [Function]

indirect_p, pdf real t value, pdf obj t *obj )
Create a new Real object in the given document doc and store it in obj.
Parameters
doc A document object.
indirect p A boolean value indicating whether to create an indirect ob-
ject.
value The initial value for the object.
obj A pointer to a pdf_obj_t variable to store the newly created
object.
PDF_OK A new object of type real was created in doc and stored in
obj.
PDF_ERROR
An error prevented the operation to complete. The value in
obj shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t real_obj_1;
pdf_obj_t real_obj_2;
/* Create some real objects */

if (pdf_obj_real_new (doc, PDF_FALSE, 3.14, &real_obj_1)
!= PDF_OK)
{
/* Error creating real object */

}
if (pdf_obj_real_new (doc, PDF_FALSE, 2.7182, &real_obj_2)

!= PDF_OK)
{
/* Error creating real object */
}
pdf_status_t pdf_obj_real_value (pdf obj t obj, pdf real t [Function]
*value )
Get the value of a PDF Real object.
Parameters
obj A PDF object.
value A pointer to a pdf real t variable to store the result.
PDF_OK The real value stored in obj was successfully stored in value.
PDF_EINVOBJ
The object obj is not a Real object.
PDF_ERROR
in value shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t real_obj;
pdf_real_t result;
if (pdf_obj_real_new (doc, PDF_FALSE, 3.14, &real_obj)

!= PDF_OK)
{
/* Error creating Real object */
}
else
{
if (pdf_obj_real_value (real_obj, &result)
!= PDF_OK)
{
/* Error getting the Real value */
}
else
{
/* result equals to 3.14 */
}
}
3.2.7 Integer Objects

The PDF integer objects are quantities in the integer domain. They are limited by an
implementation limit (see Chapter 6 [Implementation Limits], page 231).
pdf_status_t pdf_obj_integer_new (pdf obj doc t doc, pdf bool t [Function]
indirect_p, pdf i32 t value, pdf obj t *obj )
Create a new Integer object in the given document doc and store it in obj.
Parameters
ject.
object.
PDF_OK A new integer object was successfully created in doc and
stored in obj.
PDF_ERROR
in obj shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t integer_obj_1;
pdf_obj_t integer_obj_2;
/* Create some integer objects */

if (pdf_obj_integer_new (doc, PDF_FALSE, 10, &integer_obj_1)
!= PDF_OK)
{
/* Error creating integer object */
}
if (pdf_obj_integer_new (doc, PDF_FALSE, -10, &integer_obj_2)

!= PDF_OK)
{
/* Error creating integer object */
}
pdf_status_t pdf_obj_integer_value (pdf obj t obj, pdf i32 t [Function]
*value )
Get the value of a PDF Integer object.
Parameters
obj A PDF object.
value A pointer to a pdf i32 t variable to store the result.

PDF_OK The integer value of obj was stored in value.
PDF_EINVOBJ
The object obj is not an Integer object.
PDF_ERROR
of value shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t integer_obj;
pdf_i32_t result;
if (pdf_obj_integer_new (doc, PDF_FALSE, 10, &integer_obj)

!= PDF_OK)
{
/* Error creating Integer object */
}
else
{
if (pdf_obj_integer_value (integer_obj, &result)
!= PDF_OK)
{
/* Error getting the Integer value */
}
else
{
/* result equals to 10 */
}
}
3.2.8 Boolean Objects

Boolean objects can hold just two values:
− true
− false
Can be used as values of array elements, values of dictionary entries and as operators in
the postscript calculator functions (type 4 functions).
pdf_status_t pdf_obj_boolean_new (pdf obj doc t doc, pdf bool t [Function]

indirect_p, pdf bool t value, pdf obj t *obj )
Create a new Boolean object in the given document doc and store it in obj.
Parameters

ject.
object.
PDF_OK A new boolean object was created in doc and stored in obj.
PDF_ERROR
Usage example
pdf_obj_doc_t doc;
pdf_obj_t boolean_obj_1;
pdf_obj_t boolean_obj_2;
/* Create some Boolean objects */

if (pdf_obj_boolean_new (doc, PDF_FALSE, PDF_TRUE, &boolean_obj_1)
!= PDF_OK)
{
/* Error creating boolean object */
}
if (pdf_obj_boolean_new (doc, PDF_FALSE, PDF_FALSE, &boolean_obj_2)

!= PDF_OK)
{
/* Error creating boolean object */
}
pdf_status_t pdf_obj_boolean_value (pdf obj t obj, pdf bool t [Function]

*value )
Get the value of a PDF boolean object.
Parameters
obj A PDF object.
value A pointer to a pdf bool t variable to store the result.
PDF_OK The boolean value of obj was successfully stored in value.
PDF_EINVOBJ
The object obj is not a boolean object.
PDF_ERROR
of value shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t boolean_obj;
pdf_bool_t result;
if (pdf_obj_boolean_new (doc, PDF_FALSE, PDF_TRUE, &boolean_obj)

!= PDF_OK)
{
/* Error creating Boolean object */
}
else
{
if (pdf_obj_boolean_value (boolean_obj, &result)
!= PDF_OK)
{
/* Error getting the Boolean value */
}
else
{
/* result equals to PDF_TRUE */
}
}
3.2.9 Name Objects

A PDF name object is an atomic symbol uniquely defined by a sequence of regular charac-
ters. It does not have internal structure.
pdf_status_t pdf_obj_name_new (pdf obj doc t doc, pdf bool t [Function]

indirect_p, pdf char t *value, pdf obj t *obj )
Create a new Name object in the given document doc and store it in obj.
Parameters
ject.
value The null-terminated string value for the object.
object.
PDF_OK A new name object was successfully created in doc and stored
in obj.
PDF_EBADDATA
Invalid value in value.
PDF_ERROR
doc shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t name_obj_1;
pdf_obj_t name_obj_2;
/* Create some Name objects */

if (pdf_obj_name_new (doc, PDF_FALSE, "FooBar", &name_obj_1)
!= PDF_OK)
{
/* Error creating name object */
}
if (pdf_obj_name_new (doc, PDF_FALSE, "BazFoo", &name_obj_2)

!= PDF_OK)
{
/* Error creating name object */
}
pdf_status_t pdf_obj_name_size (pdf obj t obj, pdf size t *size ) [Function]

Return the size of the PDF name obj (i.e. the number of characters composing it).
Note that the initial slash character (/) is not included in the count.
The size of the / name (without any character after the slash) is 0.
Parameters
obj A PDF name object.
size A pointer to a pdf size t variable to hold the size of obj in
octects.
PDF_OK The size of obj was stored in size.
PDF_EINVOBJ
obj is not a name object. The value in size is unchenged.
PDF_ERROR
in size shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t name;
...
pdf_obj_name_new (doc, PDF_FALSE, "Foo", &name);

pdf_obj_name_size (name); /* Should return 3 */
pdf_status_t pdf_obj_name_value (pdf obj t obj, pdf char t *buf ) [Function]

Get the value of a PDF Name object in the buffer pointed by buf. There should be
enough space in buf to hold the value (the user can get the size of the name object
using pdf_obj_name_size).
The value of the name object does not include the “/” prefix.
Parameters
obj A PDF name object.
buf A memory buffer to store the result.
PDF_OK The string representing the name value of obj was successfully
stored in value.
PDF_EINVOBJ
The object obj is not a name object.
PDF_ERROR
in buf shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t name_obj;
pdf_char_t *name;
if (pdf_obj_name_new (doc, PDF_FALSE, "FooBar", &name_obj)

!= PDF_OK)
{
/* Error creating Name object */
}
else
{
name = malloc (pdf_obj_name_size (name_obj));
if (pdf_obj_name_value (name_obj, name)

!= PDF_OK)
{
/* Error getting the Name value */
}
else
{
/* ’name’ equals to "FooBar" */
}
}
3.2.10 String Objects

A PDF string object is a sequence of bytes in the range 0-255. They are not NULL-
terminated.
pdf_status_t pdf_obj_string_new (pdf obj doc t doc, pdf bool t [Function]

indirect_p, pdf char t *str, pdf size t str_size, pdf obj t *obj )
Create a new String object in the given document doc and store it in obj.
Parameters
ject.
str The string value. Note that this is not a NULL terminated
string, since PDF strings can held arbitrary binary data. The
data pointed by str is copied internally.
str size The size of str, in bytes.
object.
PDF_OK A new string object was successfully created in doc and stored
in obj.
PDF_ERROR
Usage example
pdf_obj_doc_t doc;
pdf_obj_t str;
/* Create a new String PDF object */

if (pdf_obj_string_new (doc, PDF_FALSE, "f\233o", 3, &str)
!= PDF_OK)
{
/* Error creating the String object */
}
pdf_status_t pdf_obj_string_size (pdf obj t obj, pdf size t [Function]

*size )
Return the size of the PDF string obj (i.e. the number of octects composing it).
Parameters
obj A PDF string object.
size A pointer to a pdf size t variable to hold the size of obj.
PDF_OK The size of obj in octects was stored in size.

PDF_EINVOBJ
obj is not a string object.
PDF_ERROR
size is undefined and shall not be used.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t str_obj;
...
pdf_obj_string_new (doc, PDF_FALSE, "foo", 3, &str_obj);

pdf_obj_string_size (str_obj); /* Returns 3 */
pdf_status_t pdf_obj_string_value (pdf obj t obj, pdf char t [Function]

*buf )
Get the value of a PDF String object in the buffer pointed by buf. There should be
enough space in buf to hold the value (the user can get the size of the string using
pdf_obj_string_size).
Parameters
obj A PDF string object.
buf A memory buffer to store the result.

PDF_OK The value of the string object was successfully stored in buf.
PDF_EINVOBJ
The object obj is not a String object.
PDF_ERROR
in buf shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t str_obj;
pdf_char_t *str;
if (pdf_obj_string_new (doc, PDF_FALSE, "foo bar baz", 11, &name_obj)

!= PDF_OK)
{
/* Error creating the String object */
}
else
{
str = malloc (pdf_obj_string_size (str_obj));
if (pdf_obj_string_value (str_obj, str)

!= PDF_OK)
{
/* Error getting the String value */
}
else
{
/* ’str’ contains "foo bar baz" */
}
}
pdf_bool_t pdf_obj_string_hex_p (pdf obj t obj ) [Function]
Return the hex flag of the String object obj. A String object with the hex flag set to
true is saved in an hexadecimal form.
If obj is not a string object then PDF_FALSE is returned.
Parameters
obj A PDF String object.
PDF_TRUE The string will be saved in hexadecimal form.
PDF_FALSE
The string won’t be saved in hexadecimal form.
Usage example
pdf_obj_t str;
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.
PDF_OK The hex flag of obj was set to hex p.

PDF_EINVOBJ
obj is not a string object.
PDF_ERROR
An error prevented the operation to complete. The hex flag
of the document shall be considered unchanged.
Usage example
pdf_obj_t str;
/* Reverse the hex flag of ’str’ */

pdf_obj_string_hex_set (!pdf_obj_string_hex_p (str));
3.2.11 Array Objects

A PDF array is a one-dimensional collection of objects arranged sequentially. The objects
can be of any type.
pdf_status_t pdf_obj_array_new (pdf obj doc t doc, pdf bool t [Function]
indirect_p, pdf size t array_size, pdf obj t *obj )
Create a new Array object in the given object document doc and store it in obj.
Parameters
ject.
array size The number of elements of the new array.
object.
PDF_OK The array object was created and stored into obj.
PDF_ENOMEM
Not enough memory. The value of obj shall be considered
invalid.
PDF_ERROR
of obj shall be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t array;
...
/* Create an indirect array object to initially

held 10 elements */
if (pdf_obj_array_new (doc, PDF_TRUE, 10, &array)

== PDF_OK)
{
/* The object was successfully created */
}
pdf_status_t pdf_obj_array_get (pdf obj t array, pdf size t [Function]

index, pdf obj t *obj )
Get the indexth element of the given array and store it into obj.
Parameters
array A PDF array.
index An index into the array.
obj A pointer to a pdf_obj_t variable to store the result.
PDF_OK The indexth object was stored into obj.
PDF_EBADDATA
The specified index is invalid. The value of obj is untouched.
PDF_ERROR
of obj shall be considered invalid.
Usage example
pdf_obj_t array;
pdf_obj_t elem;
pdf_size_t index;
...
/* Iterate through the first 5 objects of ’array’ */

for (index = 0; index < 5; index++)
{
if (pdf_obj_array_get (array, index, &elem)
== PDF_OK)
{
/* Use ’elem’ */
}
}
pdf_status_t pdf_obj_array_set (pdf obj t array, pdf size t [Function]

index, pdf obj t obj )
Set the indexth element of the array to the given object obj. The object obj and the
array array should be associated with the same object document. A non-scalar direct
object cannot be inserted in more than one container.
If index equals to the array size then the object is inserted at the end.
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.
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;
...
/* Insert numbers as the first 10 elements of the array */

for (index = 0; index < 10; index++)
{
pdf_obj_integer_new (doc,
PDF_FALSE,
(pdf_u32_t) index,
&elem);
if (pdf_obj_array_set (array, index, elem) == PDF_OK)

{
/* Element inserted into the array. */
}
}
pdf_status_t pdf_obj_array_size (pdf obj t array, pdf size t [Function]
*size )
Get the number of elements contained in array.
Parameters
array A PDF array.
size A pointer to a PDF size variable to hold the number of objects
contained in array.

PDF_OK The size of array was stored in size.
PDF_EINVOBJ
array is not an array object. The value in size is left un-
touched.
PDF_ERROR
in size is undefined.
Usage example
pdf_obj_t array;
pdf_size_t array_size;
pdf_size_t index;
...
/* Iterate through the element of the array */

pdf_obj_array_size (array, &array_size);
for (index = 0; index < array_size; index++)
{
/* Do something */
}
pdf_bool_t pdf_obj_array_weak_p (pdf obj t array, pdf size t [Function]

index )
Determine if the indexth element of array is a weak reference.
A weak reference changes the way the garbage collection works. See Section 3.3.5
[Garbage collection in object documents], page 228.
This function returns PDF_FALSE if array is not an array object and if index is out of
bounds.
Parameters
array A PDF array.
index An index into array.
PDF_TRUE The element at index is a weak reference.
PDF_FALSE
The element at index is not a weak reference.
Usage example
pdf_obj_t array;
pdf_size_t index;
...
/* Determine if some element of array has a weak reference */

{
if (pdf_obj_array_weak_p (array, index))
{
/* The index-th element has a weak reference */
}
}
pdf_bool_t pdf_obj_array_weak_set (pdf obj t array, pdf size t [Function]
index, pdf bool t weak_p )
Set if the indexth element of array is a weak reference.
The effect of this call when weak p is PDF_FALSE is to remove the effect of a previous
call with weak p set to PDF_TRUE. In particular it does not set a strong reference to
the object occupying the indexth position in the array.
Parameters
array A PDF array.
index An index into array.
weak p A boolean value.
PDF_OK The weak reference was (un)set in the element occupying the
indexth position into array.
PDF_EINVOBJ
array is not an array object.
PDF_EBADDATA
The specified index is out of bounds.
PDF_ERROR
Usage example
pdf_obj_t array;
pdf_size_t index;
...
/* Remove any weak reference in ’array’ */

{
pdf_obj_array_weak_set (array, index, PDF_FALSE);
}
pdf_status_t pdf_obj_array_remove (pdf obj t array, pdf obj t [Function]

obj )
Find the first element equal to obj and remove it from the array.
Note that it is not safe to call pdf_obj_array_remove while executing a pdf_obj_
enum.
Parameters
array A PDF array.
obj The PDF object to remove from the array.
PDF_OK obj was found and removed from the array.
PDF_EINVOBJ
PDF_EBADDATA
obj was not contained in the array.
PDF_ERROR
Some error prevented to complete the operation.
Usage example
pdf_obj_t array;
pdf_obj_t elem;
...
/* Remove the third element of the array */

pdf_obj_array_get (array, 2, &elem);
if (pdf_obj_array_remove (array, elem) == PDF_OK)
{
/* The element was removed from the array */
}
pdf_status_t pdf_obj_array_remove_at (pdf obj t array, [Function]

pdf size t index )
Find the indexth element and remove it from the array.
Note that it not safe to call pdf_obj_array_remove_at while executing a pdf_obj_
enum.
Parameters
array A PDF array.
index The index of the element to remove from the array.
PDF_OK The requested element was found and removed from the ar-
ray.
PDF_EINVOBJ
PDF_EBADDATA
The specified index is invalid.
PDF_ERROR
Some error prevented to complete the operation.
Usage example
pdf_obj_t array;
...
/* Remove the third element of the array */

if (pdf_obj_array_remove_at (array, 3) == PDF_OK)
{
/* The element was removed */
}
3.2.12 Dictionary Objects

A PDF dictionary is an associative table containing pairs of objects. The first object of
each pair is a name object. The type of the second object in the pair is unrestricted.
A dictionary entry whose value is null is equivalent to an absent entry.
pdf_status_t pdf_obj_dict_new (pdf obj doc t doc, pdf bool t [Function]

indirect_p, pdf obj t *obj )
Create a new PDF Dictionary object.
ject.
object.
PDF_OK An empty dictionary object was created and stored in obj.
PDF_ENOMEM
Not enough memory to create the object.
PDF_ERROR
of obj shall be considered undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
...
/* Create an empty dictionary object */

if (pdf_obj_dict_new (doc, PDF_TRUE, &dict)
== PDF_OK)
{
/* Dictionary object created and stored in ’dict’. */
}
pdf_status_t pdf_obj_dict_get (pdf obj t dict, pdf obj t key, [Function]
pdf obj t *obj )
Get the value associated with key in dict and store it in obj.
Parameters
dict A PDF dictionary object.
key A PDF name object.
obj A pointer to pdf_obj_t to store the value associated with
key.
PDF_OK A copy of the value associated with key was stored in obj.
PDF_EINVOBJ
key is not a name object or dict is not a dictionary object.
PDF_EBADDATA
key is not in the dictionary or it is not a name object.
PDF_ERROR
obj shall be considered undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t key;
pdf_obj_t value;
...
/* Get the value associated with "/Foo" */

pdf_obj_name_new (doc, PDF_FALSE, "Foo", &key);
if (pdf_obj_dict_get (dict, key, &value) == PDF_OK)
{
/* The object associated with "/Foo" in the dictionary is
now in ’foo’. */
}
pdf_status_t pdf_obj_dict_get_str (pdf obj t dict, pdf char t [Function]
*key, pdf obj t *obj )
Get the value associated with key in dict and store it in obj.
Parameters
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.
PDF_OK A copy of the value associated with key was stored in obj.
PDF_EBADDATA
key is not in the dictionary.
PDF_ERROR
obj shall be considered undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t value;
...
/* Get the value associated with "/Foo" */

if (pdf_obj_dict_get (dict, "Foo", &value) == PDF_OK)
{
/* The object associated with "/Foo" in the dictionary is
now in ’foo’. */
}
pdf_status_t pdf_obj_dict_set (pdf obj t dict, pdf obj t key, [Function]

pdf obj t val )
Set val as the new value for key in the PDF dictionary dict.
If the entry do not exist then it is added.
Parameters
val A PDF object.
PDF_OK The value associated with key in dict was set to val.
PDF_EINVOBJ
key is not a name object or dict is not a dictionary object.
PDF_ERROR
in val is undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t key;
pdf_obj_t value;
...
/* Create a dictionary and insert a key-value pair

into it: /Age -> 29. */
pdf_obj_dict_new (doc, PDF_TRUE, &dict);
pdf_obj_name_new (doc, PDF_FALSE, "Age", &key);

pdf_obj_integer_new (doc, PDF_FALSE, 29, &value);
if (pdf_obj_dict_set (dict, key, value) == PDF_OK)

{
/* The pair key-value was inserted in ’dict’. */
}
pdf_status_t pdf_obj_dict_set_str (pdf obj t dict, pdf char t [Function]
*key, pdf obj t val )
Set val as the new value for key in the PDF dictionary dict.
If the entry do not exist then it is added.
Parameters
key A string containing the name of the key, without the preced-
ing slash character.
val A PDF object.
PDF_OK The value associated with key in dict was set to
PDF_EINVOBJ
dict is not a dictionary object.
PDF_ERROR
in val is undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t root_dict;
pdf_obj_t pages_dict;
...
/* Create a /Pages entry in the root dictionary, as an indirect

object, containing an empty dictionary. */
pdf_obj_doc_get_root (doc, &root_dir);
pdf_obj_dict_new (doc, PDF_TRUE, &pages_dict);
if (pdf_obj_dict_set_str (root_dir, "/Pages", pages_dict)

!= PDF_ERROR)
{
/* The root dictionary now contains a /Pages entry
whose value is an object reference pointing to the
indirect dictionary ’pages’. */
}
pdf_status_t pdf_obj_dict_remove (pdf obj t dict, pdf obj t key ) [Function]
Remove a key-value pair from a dictionary. If key is not found in dict then this is a
no-op.
Parameters
PDF_OK key was found in the dictionary and the pair was removed.
PDF_EINVOBJ
Either dict is not a dictionary object or key is not a name
object.
PDF_ERROR
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t key;
...
/* Remove the "/Foo" entry from ’dict’, if it exists */

if (pdf_obj_dict_remove (dict, key) == PDF_OK)

{
/* The entry, provided it was present, was removed from
the dictionary. */
}
pdf_status_t pdf_obj_dict_remove_str (pdf obj t dict, pdf char t [Function]

*key )
Remove a key-value pair from a dictionary. If key is not found in dict then this is a
no-op.
Parameters
key A string containing the textual representation of a PDF
Name.
PDF_OK key was found in the dictionary and the pair was removed.
PDF_EINVOBJ
dict is not a dictionary object.
PDF_ERROR
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
...
/* Remove the "/Foo" entry from ’dict’, if it exists */

if (pdf_obj_dict_remove (dict, "Foo") == PDF_OK)
{
/* The entry, provided it was present, was removed from
the dictionary. */
}
pdf_bool_t pdf_obj_dict_key_p (pdf obj t dict, pdf obj t key ) [Function]

Determine if a given name object is a key into dict.
Parameters
dict A PDF Dictionary object.
key A PDF Name object.
PDF_TRUE key is in a key-value pair into dict.
PDF_FALSE
key is not in a key-value pair into dict, or dict is not a dic-
tionary object, or key is not a name object.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t key;
pdf_obj_t value;
...

pdf_obj_dict_set_str (dict, "Foo", value);
pdf_obj_dict_key_str_p (dict, "Foo", value); /* Returns PDF_TRUE */
pdf_bool_t pdf_obj_dict_key_str_p (pdf obj t dict, pdf char t [Function]

*key )
Determine if a given key string is a key into dict.
Parameters
key A string containing the string representation of a PDF Name.
PDF_TRUE key is in a key-value pair into dict.
PDF_FALSE
key is not in a key-value pair into dict, or dict is not a dic-
tionary object.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t value;
...
pdf_obj_dict_set_str (dict, "Foo", value);
pdf_obj_dict_key_p (dict, key, value); /* Returns PDF_TRUE */

pdf_obj_dict_key_p (dict, value, key); /* Returns PDF_FALSE */
pdf_bool_t pdf_obj_dict_weak_p (pdf obj t dict, pdf obj t key ) [Function]

Determine if a given key object is a weak reference in dict.
Parameters
key A PDF Name object.
PDF_TRUE key is in a weak reference into dict.
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;
...
/* Determine if the entry "/Foo" has a weak reference in ’dict’ */

pdf_obj_dict_weak_p (dict, key);

pdf_bool_t pdf_obj_dict_weak_str_p (pdf obj t dict, pdf char t [Function]
*key )
Determine if a given key object is a weak reference in dict.
Parameters
key A string containing the string representation of a PDF Name.
PDF_TRUE key is in a weak reference into dict.
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.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t key;
...
/* Determine if the entry "/Foo" has a weak reference in ’dict’ */

pdf_obj_dict_weak_p (dict, "Foo");
pdf_status_t pdf_obj_dict_weak_set (pdf obj t dict, pdf obj t [Function]
key, pdf bool t weak_p )
Set the weak p attribute of key in dict. Any key-value pair with weak_p == PDF_TRUE
has a weak reference. See Section 3.3.5 [Garbage collection in object documents],
page 228.
Parameters

weak p The new value for the weak attribute of the key-value pair.
PDF_OK The weak attribute for the pair was set to weak p.
PDF_EINVOBJ
Either dict is not a PDF dictionary object or key is not a
PDF name object.
PDF_ERROR
Some error prevented the operation to complete.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
pdf_obj_t key;
...
/* Set the weak attribute of the key-value pair in

’dict’ with key "/Foo". */
pdf_obj_dict_weak_set (dict, key, PDF_TRUE);

pdf_status_t pdf_obj_dict_weak_set_str (pdf obj t dict, [Function]
pdf char t *key, pdf bool t weak_p )
Set the weak p attribute of key in dict. Any key-value pair with weak_p == PDF_TRUE
has a weak reference. See Section 3.3.5 [Garbage collection in object documents],
page 228.
Parameters
key A string containing the string representation of a PDF name.
weak p The new value for the weak attribute of the key.
PDF_OK The weak attribute for the pair was set to weak p.
PDF_EINVOBJ
dict is not a PDF dictionary object.
PDF_ERROR
Usage example
pdf_obj_doc_t doc;
pdf_obj_t dict;
...
/* Set the weak attribute of the key-value pair in

’dict’ with key "/Foo". */
pdf_obj_dict_weak_set (dict, "Foo", PDF_TRUE);
3.2.13 Stream Objects

A PDF stream object is an arbitrary long sequence of bytes characterized by a set of
properties. The properties of a stream object are specified by a dictionary that appears just
before the stream in the PDF file.
Unlike strings, a stream can be read incrementally and can be of unlimited length.
All streams must be indirect objects while the dictionary describing the stream must be
a direct object.
pdf_status_t pdf_obj_stream_new (pdf obj doc t doc, pdf stm t [Function]

stm, pdf size t size, pdf obj t attrs_dict, pdf obj t *obj )
Create a new PDF Stream object.
Parameters
stm A base layer stream that will be used to retrieve the data
for the stream object. See Section 2.7 [Filtered Streams],
page 68. The contents of this stream will be copied to an
internal storage by this call.
size The number of octects to read from stm. If this parameter is
zero then read from the stream until it gets exhausted.
attrs dict Dictionary containing keys that will be copied to the dictio-
nary describing the newly created stream. If this dictionary
contains a list of filters then those filters are applied in inverse
order to the data read from stm.
Note that any /Length key present in stm will be ignored.
See the PDF specification for the expected content of the
stream dictionary.
object.
PDF_OK The stream object was successfully created, and a reference
to it was stored in obj.
PDF_EINVOBJ
stm is not a stream object or attr dict is not a dictionary
object.
PDF_ENOMEM
Not enough memory to create the object.
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;
...
/* Create a filter array */

pdf_obj_string_new (doc, PDF_FALSE, "ASCII85Decode");
pdf_obj_string_new (doc, PDF_FALSE, "LZWDecode");
pdf_obj_array_new (doc, PDF_FALSE, 2, &filter_array);

pdf_obj_array_set (filter_array, 0, ascii85_label);
pdf_obj_array_set (filter_array, 1, lzw_label);
/* Create the dictionary */

pdf_obj_dict_new (doc, PDF_FALSE, &dict);
pdf_obj_dict_set_str (dict, "Filter", filter_array);
/* Open a filtered stream to a file containing the data to be

stored in the object stream */
pdf_text_new_from_unicode ("/path/to/data",
14, PDF_TEXT_UTF8,
&data_file_path);
pdf_fsys_file_open (NULL, data_file_path, PDF_FSYS_OPEN_MODE_READ, data_
pdf_stm_file_new (data_file,
0,
0, /* Use the default cache size */
PDF_STM_READ,
&stm);
/* Create the stream object */

if (pdf_obj_stream_new (doc,
stm,
0, /* Exhaust the stream */
dict,
&stream) != PDF_OK)
{
/* Some error prevented the creation of the stream */
pdf_status_t pdf_obj_stream_dict (pdf obj t stream, pdf obj t [Function]

*dict )
Get the stream dictionary associated with stream.
Parameters
stream A stream object.
dict A pointer to a pdf_obj_t variable to store the newly cre-
ated object. The returned object shall not be destroyed nor
modified by the caller.
PDF_OK The dictionary describing stream is now stored in obj.
PDF_EINVOBJ
stream is not a stream object.
PDF_ERROR
dict shall be considered invalid.
Usage example
pdf_obj_t stream;
pdf_obj_t stream_dict;
/* Create a stream object... */
if (pdf_obj_stream_dict (stream, &stream_dict) != PDF_OK)

{
/* Error getting the stream dictionary */
}
pdf_status_t pdf_obj_stream_length (pdf obj t stream, pdf off t [Function]

*length )
Get the size of the encoded stream in octects.
Parameters
stream A stream object.
length A pointer to a pdf size t variable to hold the returned value.
PDF_OK The length of the encoded stream is stored in length.
PDF_EINVOBJ
PDF_ERROR
length shall be considered invalid.
Usage example
pdf_obj_t stream;
pdf_off_t stream_length;
...
/* Get the length of the stream, in octects */

pdf_obj_stream_length (stream, &stream_length);
pdf_off_t pdf_obj_stream_pos (pdf obj t stream ) [Function]
Get the offset of the beginning of stream’s data in the PDF file.
You can use this call only after saving the object in a PDF file.
Parameters
stream A Stream object.
Returns The offset (in octects) of the beginning of the stream data: the position
just after the stream keyword. If the returned number is 0 then an error
occurred.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t stream;
pdf_off_t stream_offset;
...
/* Try to get the offset without previously

saving the object document */
if (stream_offset (stream) == 0)
{
/* Error: document was not saved before to
call pdf_obj_stream_pos */
}
/* Save the object document */

pdf_obj_doc_save (doc, NULL, PDF_OBJ_DOC_SAVE_FULL, save_params);
/* Get the offset where the data of the stream was

stored */
if (stream_offset (stream) == 0)
{
/* Error obtaining the offset of the stream */
}
pdf_status_t pdf_obj_stream_open (pdf obj t stream, enum [Function]
pdf obj stm open mode e mode, pdf stm t *stm )
Create a base layer stream to read the contents of stream. The base layer stream stm
is positioning at the beginning of the data contained in stream.
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.
PDF_OK A filtered stream was opened to read the contents of stream.
PDF_EINVOBJ
PDF_ENOMEM
PDF_ERROR
stm shall be considered invalid.
Usage example
pdf_obj_t stream;
pdf_stm_t stm;
...
/* Get a filtered stream to read the contents

of ’stream’ */
if (pdf_obj_stream_open (stream,
PDF_OBJ_STM_OPEN_MODE_FILTERED,
&stm) != PDF_OK)
{
/* Error opening the stream */
}
3.2.14 Null Object

A PDF null object has a type and a value that are unequal to those of any other object.
There is only one possible value for this object type: the null keyword.
An indirect object reference to a nonexistant object is a reference to the null object.
pdf_status_t pdf_obj_null_new (pdf obj t *obj ) [Function]
Create a direct Null object.
object.
PDF_OK
Usage example
XXX
3.3 Object Documents

At the syntactic level any PDF document can be viewed as a collection of objects organized
in a certain way.
An object document can be associated with a file system file (see Section 2.11 [The
Filesystem Module], page 125).
3.3.1 Object Document Data Types

pdf_obj_doc_t [Data Type]
Opaque type representing an object level document.
struct pdf_obj_doc_save_params_s [Data Type]

Parameters used when saving an object document.
pdf_char_t *header
A complete header string, like
%FOO-1.0
pdf_char_t *crypt_key
An encryption key if the security of the document is activated.
pdf_size_t crypt_key_size
Size of crypt_key.
struct pdf_pm_s *progress_monitor
A pointer to a progress monitor, or NULL.
void *monitor_client_data
Client-specific data for the progress monitor callbacks.
struct pdf_obj_doc_ctx_s [Data Type]

Structure to contain a localization of an error in the contents of an object document.
pdf_off_t line
Line number.
pdf_char_t *error_description
Description of the error.
3.3.2 Opening and Closing Object Documents

pdf_status_t pdf_obj_doc_new (pdf u32 t flags, pdf obj doc t [Function]
*doc )
Create an empty object document.
The newly created object document contains an empty root dictionary and an optional
empty Document Information Dictionary.
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.
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.
PDF_OK The object document was correctly loaded from path and
stored in doc.
PDF_ENOMEM
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
of doc is undefined and should not be used.
Usage example
pdf_text_t file_path;
pdf_obj_doc_t doc;
/* Open a PDF object document from /foo/bar.pdf */

pdf_text_new_from_unicode ("/foo/bar.pdf",
12,
PDF_TEXT_UTF8,
&file_path);
if (pdf_obj_doc_open (NULL, /* Use the default filesystem */

file_path,
"%PDF-",
&doc) != PDF_OK)
{
/* Error opening /foo/bar.pdf */
}
pdf_status_t pdf_obj_doc_close (pdf obj doc t doc ) [Function]

Close an object document.
If the dirty flag of the object document is set then the contents are saved before
closing. The performed saving operation is equivalent to a call to pdf_obj_doc_save
with NULL flags.
Parameters

PDF_OK The object document has been closed. The value of doc
should be considered invalid and shall not be used.
PDF_ERROR
Error while closing the object document. The reference in
doc should be considered invalid and shall not be used.
Usage example
pdf_obj_doc_t mydoc;
/* Close an object document... */
if (pdf_obj_doc_close (mydoc) != PDF_OK)

{
/* Error closing the object document */
}
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
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.
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.
Usage example
struct pdf_obj_doc_save_params_s save_params;
pdf_obj_doc_t doc;
/* Open an object document ’doc’... */
/* Fill in the save parameters */

save_params.header = "%PDF-1.6";
/* No encryption */
save_params.crypt_key = NULL;
save_params.crypt_key_size = 0;
/* Do not use a progress monitor */
save_params.progress_monitor = NULL;
save_params.monitor_client_data = NULL;
/* Save the document in its associated file */

if (pdf_obj_doc_save (doc,
NULL, /* Use the associated file */
PDF_OBJ_DOC_SAVE_FULL,
save_params) != PDF_OK)
{
/* Error saving the object document */
}
3.3.3 Managing Object Document Properties

pdf_status_t pdf_obj_doc_get_id (pdf obj doc t doc, pdf obj t [Function]
*instance_id, pdf obj t *permanent_id )
Return two ID byte arrays identifying the object document.
Parameters
instance id
A pointer to a string object to hold the returned instance id.
If the document does not have a instance id then the null
object is returned.
permanent id
A pointer to a string object to hold the returned permanent
id. If the document does not have a instance id then the null
object is returned.
PDF_OK The document id was correctly stored into instance id and
permanent id.
PDF_ERROR
of instance id and permanent id is undefined.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t instance_id;
pdf_obj_t permanent_id;
/* Create an object document ... */
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 */
}
}
pdf_status_t pdf_obj_doc_set_id (pdf obj doc t doc, pdf obj t [Function]

instance_id, pdf obj t permanent_id )
Set the two ID byte arrays identifying the object document doc.
Parameters
instance id
A string object with the new instance id.
permanent id
A string object with the new permanent id.
PDF_OK The new instance id and permanent id were set in doc.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t instance_id;
pdf_obj_t permanent_id;
/* Create an object document and instance_id, permanent_id... */

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
dirty p Boolean 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;
/* Open an object document */

pdf_text_new_from_unicode ("/foo/bar.pdf",
12,
PDF_TEXT_UTF8,
&file_path);
pdf_obj_doc_open (NULL, /* Use the default filesystem */

file_path,
"%PDF-",
&doc);
/* Modify the object document by adding a /Foo entry to

the catalog. This operation will set the dirty flag of
the document. */
pdf_obj_doc_get_root (doc, &catalog);
pdf_obj_integer_new (doc, PDF_FALSE, 10, &foo_value);
pdf_obj_dict_put_str (catalog, "Foo", foo_value);
/* Clear the dirty flag of the document. */

pdf_obj_doc_set_dirty (doc, PDF_FALSE);
/* Close the document. The /Foo entry in the catalog dictionary is

lost, since the document is not saved. */
pdf_obj_doc_close (doc);
3.3.4 Retrieving and Storing Objects

A PDF object document contains two special objects that can be accessed using specific-
purpose functions:
− The Document Information Dictionary. It is optional.
− The root object, that is the catalog dictionary in a well-formed PDF document. It is
mandatory.
Any other indirect object contained in the object document can be accessed using an
object identifier.
pdf_status_t pdf_obj_doc_get_info_dict (pdf obj doc t doc, [Function]

pdf obj t *info_dict )
Return the Document Information Dictionary of the object document. If the object
document does not contain an info dictionary then the null object is returned.
Parameters
info dict A pointer to a pdf_obj_t variable.
PDF_OK If the object document features an Info dictionary it was
stored in info dict. Otherwise the null object was stored in
info dict.
PDF_ERROR
Error while getting the Info dictionary of the document ob-
ject. The value in info dict should be considered undefined.
Usage example
pdf_obj_doc_t doc;
/* Get the Document Information Dictionary of the

object document. */
if (pdf_obj_doc_get_info_dict (doc, &info_dict)
!= PDF_ERROR)
{
if (pdf_obj_get_type (info_dict) != PDF_OBJ_NULL)
{
/* The info dictionary of the document is stored in
’info_dict’. */
}
else
{
/* The object document does not feature an info
dictionary. */
}
}
pdf_status_t pdf_obj_doc_set_info_dict (pdf obj doc t doc, [Function]

pdf obj t info_dict
Set info dict as the Document Information Dictionary of doc.
info dict should be an indirect dictionary object. If it is associated with a different
document then a deep copy is performed before to set it as the Document Information
Dictionary of doc.
Parameters
info dict An indirect dictionary object.
PDF_OK The dictionary info dict was set as the new Document Infor-
mation Dictionary of doc.
PDF_EINVOBJ
The specified object info dict is not of the proper type.
PDF_ERROR
Usage example
pdf_obj_doc_t doc;
/* Create an object document without an info dictionary */

pdf_obj_doc_new (0, &doc);
/* Create an info dictionary */

pdf_obj_dict_new (doc, PDF_TRUE, &info_dict);
/* Set it as the new info dictionary in ’doc’ */

if (pdf_obj_doc_set_info_dict (doc, info_dict)
== PDF_OK)
{
/* ’info_dict’ is now the Document Information Dictionary of
’doc’ */
}
pdf_status_t pdf_obj_doc_get_root (pdf obj doc t doc, pdf obj t [Function]

*root_dict )
Get the root object (maybe the catalog of a well-formed PDF document) of the object
document doc and store it in root dict.
Parameters
obj A pointer to a pdf_obj_t variable.
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;
/* Get the root object of an object document */

if (pdf_obj_doc_get_root (doc, &root_dict)
!= PDF_ERROR)
{
/* ’root_dict’ contains the root dictionary of the
object document. */
}
pdf_status_t pdf_obj_doc_get_obj (pdf obj doc t doc, pdf obj id t [Function]
obj_id, pdf obj gen t obj_gn, pdf obj t *obj )
Get an object from doc given its obj in and obj gen and store it in obj.
Any previous content of obj is lost.
Parameters
obj in The object identifier of the desired object.
obj gn The generation number of the desired object.
obj A pointer to a pdf_obj_t variable.
PDF_OK The object was stored in obj.
PDF_ERROR
Error while getting the object. The value of obj is invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t pages_dict;
/* Get the pages dictionary of ’doc’ using its object id */

if (pdf_obj_doc_get_obj (doc, 5, 0, &catalog_dir)
!= PDF_ERROR)
{
/* ’catalog_dir’ contains the pages dictionary. */
}
3.3.5 Garbage collection in object documents

A garbage collector is provided by the library to remove non-reachable objects from an
object document.
A non-reachable object is an indirect object that cannot be reached starting from the root
dictionary of the object document. A special case is the Document Information Dictionary.
If it is present it is never collected even if it is not reachable.
The algorithm implemented by the collector is:
1. Mark the Document Information Dictionary if it exists.
2. Starting from the root dictionary, inclusive, mark any reachable object that is not a
weak reference.
3. For every non-marked object...
1. If its acquire counter is 1, destroy it freeing any used memory. Any pdf_obj_t
referencing the object becomes invalid.
Note that the garbage collector is never called implicitly.
pdf_status_t pdf_obj_doc_gc (pdf obj doc t doc ) [Function]

Call the garbage collector on doc, removing non-reachable non-acquired objects.
Parameters
PDF_OK The collection was successful.
PDF_ERROR
An error prevented the collector to terminate. The document
doc should be considered invalid.
Usage example
pdf_obj_doc_t doc;
pdf_obj_t unreachable_obj;
pdf_obj_integer_new (doc, PDF_TRUE, 10, &unreachable_obj);
/* Garbage-collect the document and save its

content. */
if (pdf_obj_doc_gc (doc) != PDF_ERROR)
{
/* ’unreachable_obj’ has been collected and its value is now
undefined. */
}
else
{
/* The collector failed and the document in ’doc’ should be
considered invalid. */
}
Chapter 4: Document Layer 229
4 Document Layer
Chapter 5: Page Contents Layer 230
5 Page Contents Layer

Chapter 6: Implementation Limits 231
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.
6.1 Architectural limits
Quantity Limit Description

Size of a PDF file 10^10 Largest supported PDF file using a cross-reference table.
bytes
integer 2147483647 Largest integer value.
integer - Smallest integer value.
2147483647-
1
real FLT MAX Largest real value.
real FLT MIN Smallest real value.
string in content SIZE MAX/2Maximum length of a string contained in a content
stream stream, in bytes.
name 32768 Maximum length of a name, in bytes.
indirect object ?? Maximum number of indirect objects in a PDF file.
content stream 2^32
objects Maximum
number of
objects in
a content
stream.
linked content 2^32
stream objects Maximum
number
of objects
in linked
content
streams.
6.2 Memory limits

TBC.
Appendix A: GNU Free Documentation License 232
Appendix A GNU Free Documentation License

Version 1.2, November 2002
Copyright 2000,2001,2002 Free Software Foundation, Inc.
c
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies

of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and
useful document free in the sense of freedom: to assure everyone the effective freedom
to copy and redistribute it, with or without modifying it, either commercially or non-
commercially. Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible for modifications
made by others.
This License is a kind of “copyleft”, which means that derivative works of the document
must themselves be free in the same sense. It complements the GNU General Public
License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because
free software needs free documentation: a free program should come with manuals
providing the same freedoms that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License principally for
works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a
notice placed by the copyright holder saying it can be distributed under the terms
of this License. Such a notice grants a world-wide, royalty-free license, unlimited in
duration, to use that work under the conditions stated herein. The “Document”,
below, refers to any such manual or work. Any member of the public is a licensee, and
is addressed as “you”. You accept the license if you copy, modify or distribute the work
in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or
a portion of it, either copied verbatim, or with modifications and/or translated into
another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document
that deals exclusively with the relationship of the publishers or authors of the Document
to the Document’s overall subject (or to related matters) and contains nothing that
could fall directly within that overall subject. (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any mathematics.) The
relationship could be a matter of historical connection with the subject or with related
matters, or of legal, commercial, philosophical, ethical or political position regarding
them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as
being those of Invariant Sections, in the notice that says that the Document is released
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
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.
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.
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
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.
ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the
document and put the following copyright and license notices just after the title page:
Copyright (C) year your name.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ‘‘GNU
Free Documentation License’’.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the
“with. . . Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the
three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing
these examples in parallel under your choice of free software license, such as the GNU
General Public License, to permit their use in free software.
Global variable index 239
Global variable index
(Index is nonexistent)
Data type index 240
Data type index
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
pdf_status_t (*pdf_fsys_file_get_pos_fn_t) pdf_status_t (*pdf_pm_begin_operation_fn_t)

(pdf_fsys_file_t file, pdf_size_t *pos ) (void *client_data ) . . . . . . . . . . . . . . . . . . . . . 24
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 pdf_status_t (*pdf_pm_end_operation_fn_t)
pdf_status_t (*pdf_fsys_file_get_size_fn_t) (void *client_data ) . . . . . . . . . . . . . . . . . . . . . 24
(pdf_fsys_file_t file, pdf_size_t pos ) pdf_status_t
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 (*pdf_pm_get_current_value_fn_t) (void
pdf_status_t (*pdf_fsys_file_open_fn_t) *client_data, void *duration ) . . . . . . . . . . 25
(pdf_text_t path_name, enum pdf_status_t (*pdf_pm_get_duration_fn_t)
pdf_fsys_file_mode_e mode, (void *client_data, void *duration ) . . . 24
pdf_fsys_file_t *file ) . . . . . . . . . . . . . . . . 144 pdf_status_t
pdf_status_t (*pdf_fsys_file_open_tmp_fn_t) (*pdf_pm_set_current_value_fn_t) (void
(pdf_fsys_file_t *file ) . . . . . . . . . . . . . . . 144 *client_data, void *duration ) . . . . . . . . . . 25
pdf_status_t (*pdf_fsys_file_read_fn_t) pdf_status_t (*pdf_pm_set_duration_fn_t)
(pdf_fsys_file_t file, pdf_char_t*buf, (void *client_data, void *duration ) . . . 24
pdf_size_t bytes, pdf_size_t*read_bytes ) pdf_status_t (*pdf_pm_set_text_fn_t) (void
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 *client_data, void *text ) . . . . . . . . . . . . . . 25
pdf_status_t (*pdf_fsys_file_reopen_fn_t) pdf_stm_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
(pdf_fsys_file_t file, enum pdf_text_host_encoding_t . . . . . . . . . . . . . . . . . . . 89
pdf_fsys_file_mode_e mode ) . . . . . . . . . . . . 148 pdf_text_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
pdf_status_t pdf_text_t (*pdf_fsys_file_get_url_fn_t)
(*pdf_fsys_file_request_ria_fn_t) (pdf_fsys_file_t file ) . . . . . . . . . . . . . . . . 148
(pdf_fsys_file_t file, pdf_size_t offset, pdf_text_unicode_options_e . . . . . . . . . . . . . . . . . 88
pdf_size_t count ) . . . . . . . . . . . . . . . . . . . . . . 148 pdf_time_span_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
pdf_status_t (*pdf_fsys_file_set_mode_fn_t)
pdf_time_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
(pdf_fsys_file_t file, enum
pdf_token_reader_t . . . . . . . . . . . . . . . . . . . . . . . . . 151
pdf_fsys_file_mode_e new_mode ) . . . . . . . 147
pdf_token_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
pdf_status_t (*pdf_fsys_file_set_pos_fn_t)
pdf_token_writer_t . . . . . . . . . . . . . . . . . . . . . . . . . 151
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 PDF_TRUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
pdf_status_t (*pdf_fsys_file_set_size_fn_t) PDF_U32_MAX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
(pdf_fsys_file_t file, pdf_size_t pos ) PDF_U32_MIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 pdf_u32_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
pdf_status_t (*pdf_fsys_file_write_fn_t) pdf_uuid_t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
(pdf_fsys_file_t file, pdf_char_t*buf,
pdf_size_t bytes,
pdf_size_t*written_bytes ) . . . . . . . . . . . . 145 S
pdf_status_t struct. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105, 127, 149
(*pdf_fsys_get_folder_contents_fn_t) struct pdf_buffer_s . . . . . . . . . . . . . . . . . . . . . . . . . . 20
(pdf_text_t path_name, pdf_list_t struct pdf_matrix_s . . . . . . . . . . . . . . . . . . . . . . . . . . 75
item_list ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 struct pdf_obj_doc_ctx_s . . . . . . . . . . . . . . . . . . . 218
pdf_status_t (*pdf_fsys_get_item_props_fn_t) struct pdf_obj_doc_save_params_s. . . . . . . . . . 218
(pdf_text_t path_name, struct struct pdf_pm_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
pdf_fsys_item_props_s *props ) . . . . . . . . 145
struct pdf_point_s . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
pdf_status_t (*pdf_fsys_get_parent_fn_t)
struct pdf_quad_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
(pdf_text_t path_name, pdf_text_t
struct pdf_rect_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
parent_path ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
pdf_status_t (*pdf_fsys_init_fn_t) (void
**data ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
pdf_status_t (*pdf_fsys_remove_folder_fn_t) V
(pdf_text_t path_name ) . . . . . . . . . . . . . . . . 145 void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28, 46
Function index 242
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
pdf_hash_key_dealloc_fn . . . . . . . . . . . . . . . . . . . . . 36 pdf_obj_acquire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

pdf_hash_key_p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 pdf_obj_array_get . . . . . . . . . . . . . . . . . . . . . . . . . . 199
pdf_hash_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 pdf_obj_array_new . . . . . . . . . . . . . . . . . . . . . . . . . . 198
pdf_hash_remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 pdf_obj_array_remove . . . . . . . . . . . . . . . . . . . . . . . 203
pdf_hash_rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 pdf_obj_array_remove_at . . . . . . . . . . . . . . . . . . . 203
pdf_hash_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 pdf_obj_array_set . . . . . . . . . . . . . . . . . . . . . . . . . . 199
pdf_i64_abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 pdf_obj_array_size . . . . . . . . . . . . . . . . . . . . . . . . . 200
pdf_i64_add. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 pdf_obj_array_weak_p . . . . . . . . . . . . . . . . . . . . . . . 201
pdf_i64_add_i32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 pdf_obj_array_weak_set . . . . . . . . . . . . . . . . . . . . . 202
pdf_i64_assign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 pdf_obj_boolean_new . . . . . . . . . . . . . . . . . . . . . . . . 190
pdf_i64_assign_quick . . . . . . . . . . . . . . . . . . . . . . . . . 8 pdf_obj_boolean_value . . . . . . . . . . . . . . . . . . . . . . 191
pdf_i64_cmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 pdf_obj_col_add_obj . . . . . . . . . . . . . . . . . . . . . . . . 185
pdf_i64_cmp_i32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 pdf_obj_col_enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
pdf_i64_copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 pdf_obj_col_equal_p . . . . . . . . . . . . . . . . . . . . . . . . 184
pdf_i64_div . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 pdf_obj_col_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
pdf_i64_div_i32_dividend . . . . . . . . . . . . . . . . . . . 14 pdf_obj_col_remove_obj . . . . . . . . . . . . . . . . . . . . . 186
pdf_i64_div_i32_divisor . . . . . . . . . . . . . . . . . . . . . 15 pdf_obj_col_size. . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
pdf_i64_mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 pdf_obj_compressed_p . . . . . . . . . . . . . . . . . . . . . . . 178
pdf_i64_mod_i32_dividend . . . . . . . . . . . . . . . . . . . 16 pdf_obj_copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
pdf_i64_mod_i32_divisor . . . . . . . . . . . . . . . . . . . . . 17 pdf_obj_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
pdf_i64_mult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 pdf_obj_dict_get. . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
pdf_i64_mult_i32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 pdf_obj_dict_get_str . . . . . . . . . . . . . . . . . . . . . . . 205
pdf_i64_neg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 pdf_obj_dict_key_p . . . . . . . . . . . . . . . . . . . . . . . . . 209
pdf_i64_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 pdf_obj_dict_key_str_p . . . . . . . . . . . . . . . . . . . . . 210
pdf_i64_subtraction . . . . . . . . . . . . . . . . . . . . . . . . . 10 pdf_obj_dict_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
pdf_i64_subtraction_i32_min . . . . . . . . . . . . . . . . 11 pdf_obj_dict_remove . . . . . . . . . . . . . . . . . . . . . . . . 208
pdf_i64_subtraction_i32_sub . . . . . . . . . . . . . . . . 11 pdf_obj_dict_remove_str . . . . . . . . . . . . . . . . . . . 209
pdf_i64_to_i32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 pdf_obj_dict_set. . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
pdf_list_add_at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 pdf_obj_dict_set_str . . . . . . . . . . . . . . . . . . . . . . . 207
pdf_list_add_first . . . . . . . . . . . . . . . . . . . . . . . . . . 59 pdf_obj_dict_weak_p . . . . . . . . . . . . . . . . . . . . . . . . 210
pdf_list_add_last. . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 pdf_obj_dict_weak_set . . . . . . . . . . . . . . . . . . . . . . 211
pdf_list_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 pdf_obj_dict_weak_set_str . . . . . . . . . . . . . . . . . 212
pdf_list_get_at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 pdf_obj_dict_weak_str_p . . . . . . . . . . . . . . . . . . . 211
pdf_list_indexof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 pdf_obj_doc_close . . . . . . . . . . . . . . . . . . . . . . . . . . 220
pdf_list_indexof_from . . . . . . . . . . . . . . . . . . . . . . . 54 pdf_obj_doc_gc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
pdf_list_indexof_from_to . . . . . . . . . . . . . . . . . . . 55 pdf_obj_doc_get_id . . . . . . . . . . . . . . . . . . . . . . . . . 222
pdf_list_iterator. . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 pdf_obj_doc_get_info_dict . . . . . . . . . . . . . . . . . 225
pdf_list_iterator_free . . . . . . . . . . . . . . . . . . . . . . 68 pdf_obj_doc_get_obj . . . . . . . . . . . . . . . . . . . . . . . . 227
pdf_list_iterator_from_to . . . . . . . . . . . . . . . . . . 67 pdf_obj_doc_get_root . . . . . . . . . . . . . . . . . . . . . . . 226
pdf_list_iterator_next . . . . . . . . . . . . . . . . . . . . . . 67 pdf_obj_doc_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
pdf_list_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 pdf_obj_doc_open. . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
pdf_list_next_node . . . . . . . . . . . . . . . . . . . . . . . . . . 51 pdf_obj_doc_save. . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
pdf_list_node_value . . . . . . . . . . . . . . . . . . . . . . . . . 56 pdf_obj_doc_set_dirty . . . . . . . . . . . . . . . . . . . . . . 224
pdf_list_previous_node . . . . . . . . . . . . . . . . . . . . . . 52 pdf_obj_doc_set_id . . . . . . . . . . . . . . . . . . . . . . . . . 223
pdf_list_remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 pdf_obj_doc_set_info_dict . . . . . . . . . . . . . . . . . 226
pdf_list_remove_at . . . . . . . . . . . . . . . . . . . . . . . . . . 62 pdf_obj_enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
pdf_list_remove_node . . . . . . . . . . . . . . . . . . . . . . . . 61 pdf_obj_equal_p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
pdf_list_search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 pdf_obj_get_col . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
pdf_list_search_from . . . . . . . . . . . . . . . . . . . . . . . . 49 pdf_obj_get_compressibility . . . . . . . . . . . . . . . 181
pdf_list_search_from_to . . . . . . . . . . . . . . . . . . . . . 50 pdf_obj_get_doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
pdf_list_set_at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 pdf_obj_get_generation . . . . . . . . . . . . . . . . . . . . . 177
pdf_list_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 pdf_obj_get_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
pdf_list_sorted_add . . . . . . . . . . . . . . . . . . . . . . . . . 63 pdf_obj_indirect_p . . . . . . . . . . . . . . . . . . . . . . . . . 179
pdf_list_sorted_indexof . . . . . . . . . . . . . . . . . . . . . 65 pdf_obj_integer_new . . . . . . . . . . . . . . . . . . . . . . . . 189
pdf_list_sorted_indexof_from_to . . . . . . . . . . . 66 pdf_obj_integer_value . . . . . . . . . . . . . . . . . . . . . . 189
pdf_list_sorted_remove . . . . . . . . . . . . . . . . . . . . . . 64 pdf_obj_name_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
pdf_list_sorted_search . . . . . . . . . . . . . . . . . . . . . . 64 pdf_obj_name_size . . . . . . . . . . . . . . . . . . . . . . . . . . 193
pdf_list_sorted_search_from_to . . . . . . . . . . . . . 64 pdf_obj_name_value . . . . . . . . . . . . . . . . . . . . . . . . . 194
Function index 244
pdf_obj_null_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 pdf_time_add_cal_span . . . . . . . . . . . . . . . . . . . . . . 109

pdf_obj_real_new. . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 pdf_time_add_cal_span_with_base . . . . . . . . . . 122
pdf_obj_real_value . . . . . . . . . . . . . . . . . . . . . . . . . 188 pdf_time_add_span . . . . . . . . . . . . . . . . . . . . . . . . . . 111
pdf_obj_release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 pdf_time_cal_span_cmp . . . . . . . . . . . . . . . . . . . . . . 123
pdf_obj_set_compressibility . . . . . . . . . . . . . . . 182 pdf_time_cal_span_diff . . . . . . . . . . . . . . . . . . . . . 124
pdf_obj_stream_dict . . . . . . . . . . . . . . . . . . . . . . . . 215 pdf_time_clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
pdf_obj_stream_length . . . . . . . . . . . . . . . . . . . . . . 215 pdf_time_cmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
pdf_obj_stream_new . . . . . . . . . . . . . . . . . . . . . . . . . 213 pdf_time_copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
pdf_obj_stream_open . . . . . . . . . . . . . . . . . . . . . . . . 216 pdf_time_destroy. . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
pdf_obj_stream_pos . . . . . . . . . . . . . . . . . . . . . . . . . 216 pdf_time_diff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
pdf_obj_string_hex_p . . . . . . . . . . . . . . . . . . . . . . . 197 pdf_time_diff_cal . . . . . . . . . . . . . . . . . . . . . . . . . . 113
pdf_obj_string_hex_set . . . . . . . . . . . . . . . . . . . . . 197 pdf_time_dup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
pdf_obj_string_new . . . . . . . . . . . . . . . . . . . . . . . . . 195 pdf_time_from_cal . . . . . . . . . . . . . . . . . . . . . . . . . . 112
pdf_obj_string_size . . . . . . . . . . . . . . . . . . . . . . . . 195 pdf_time_from_string . . . . . . . . . . . . . . . . . . . . . . . 116
pdf_obj_string_value . . . . . . . . . . . . . . . . . . . . . . . 196 pdf_time_get_local_cal . . . . . . . . . . . . . . . . . . . . . 111
pdf_obj_type_e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 pdf_time_get_utc_cal . . . . . . . . . . . . . . . . . . . . . . . 112
pdf_perror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 pdf_time_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
pdf_realloc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 pdf_time_set_from_i64 . . . . . . . . . . . . . . . . . . . . . . 108
pdf_stm_bseek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 pdf_time_set_from_u32 . . . . . . . . . . . . . . . . . . . . . . 108
pdf_stm_btell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 pdf_time_set_local_offset . . . . . . . . . . . . . . . . . 113
pdf_stm_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 pdf_time_set_to_current_local_time . . . . . . . 117
pdf_stm_file_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 pdf_time_set_to_current_utc_time . . . . . . . . . 117
pdf_stm_flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 pdf_time_span_add . . . . . . . . . . . . . . . . . . . . . . . . . . 119
pdf_stm_install_filter . . . . . . . . . . . . . . . . . . . . . . 71 pdf_time_span_cmp . . . . . . . . . . . . . . . . . . . . . . . . . . 121
pdf_stm_mem_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 pdf_time_span_copy . . . . . . . . . . . . . . . . . . . . . . . . . 120
pdf_stm_peek_char. . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 pdf_time_span_destroy . . . . . . . . . . . . . . . . . . . . . . 118
pdf_stm_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 pdf_time_span_diff . . . . . . . . . . . . . . . . . . . . . . . . . 120
pdf_stm_read_char. . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 pdf_time_span_dup . . . . . . . . . . . . . . . . . . . . . . . . . . 118
pdf_stm_tell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 pdf_time_span_negate . . . . . . . . . . . . . . . . . . . . . . . 119
pdf_stm_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 pdf_time_span_new . . . . . . . . . . . . . . . . . . . . . . . . . . 117
pdf_text_check_host_encoding . . . . . . . . . . . . . . 104 pdf_time_span_set . . . . . . . . . . . . . . . . . . . . . . . . . . 118
pdf_text_cmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 pdf_time_span_set_from_i32 . . . . . . . . . . . . . . . . 119
pdf_text_concat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 pdf_time_span_to_secs . . . . . . . . . . . . . . . . . . . . . . 121
pdf_text_concat_ascii . . . . . . . . . . . . . . . . . . . . . . 100 pdf_time_sub_cal_span . . . . . . . . . . . . . . . . . . . . . . 110
pdf_text_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 pdf_time_sub_span . . . . . . . . . . . . . . . . . . . . . . . . . . 111
pdf_text_dup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 pdf_time_to_string . . . . . . . . . . . . . . . . . . . . . . . . . 115
pdf_text_empty_p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 pdf_time_w32_set_from_filetime . . . . . . . . . . . 125
pdf_text_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 pdf_token_comment_new . . . . . . . . . . . . . . . . . . . . . . 158
pdf_text_get_best_encoding . . . . . . . . . . . . . . . . 104 pdf_token_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . 159
pdf_text_get_country . . . . . . . . . . . . . . . . . . . . . . . . 94 pdf_token_dup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
pdf_text_get_hex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 pdf_token_equal_p . . . . . . . . . . . . . . . . . . . . . . . . . . 159
pdf_text_get_host. . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 pdf_token_get_comment_size . . . . . . . . . . . . . . . . 161
pdf_text_get_host_encoding . . . . . . . . . . . . . . . . 103 pdf_token_get_integer_value . . . . . . . . . . . . . . . 160
pdf_text_get_language . . . . . . . . . . . . . . . . . . . . . . . 94 pdf_token_get_keyword_size . . . . . . . . . . . . . . . . 161
pdf_text_get_pdfdocenc . . . . . . . . . . . . . . . . . . . . . . 97 pdf_token_get_name_size . . . . . . . . . . . . . . . . . . . 161
pdf_text_get_unicode . . . . . . . . . . . . . . . . . . . . . . . . 97 pdf_token_get_real_value . . . . . . . . . . . . . . . . . . 160
pdf_text_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 pdf_token_get_string_size . . . . . . . . . . . . . . . . . 160
pdf_text_new_from_host . . . . . . . . . . . . . . . . . . . . . . 90 pdf_token_get_type . . . . . . . . . . . . . . . . . . . . . . . . . 159
pdf_text_new_from_pdf_string . . . . . . . . . . . . . . . 91 pdf_token_integer_new . . . . . . . . . . . . . . . . . . . . . . 156
pdf_text_new_from_u32 . . . . . . . . . . . . . . . . . . . . . . . 93 pdf_token_keyword_new . . . . . . . . . . . . . . . . . . . . . . 157
pdf_text_new_from_unicode . . . . . . . . . . . . . . . . . . 92 pdf_token_name_new . . . . . . . . . . . . . . . . . . . . . . . . . 157
pdf_text_replace. . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 pdf_token_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
pdf_text_replace_ascii . . . . . . . . . . . . . . . . . . . . . 101 pdf_token_reader_destroy . . . . . . . . . . . . . . . . . . 153
pdf_text_set_country . . . . . . . . . . . . . . . . . . . . . . . . 95 pdf_token_reader_new . . . . . . . . . . . . . . . . . . . . . . . 151
pdf_text_set_host. . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 pdf_token_reader_reset . . . . . . . . . . . . . . . . . . . . . 155
pdf_text_set_language . . . . . . . . . . . . . . . . . . . . . . . 95 pdf_token_real_new . . . . . . . . . . . . . . . . . . . . . . . . . 156
pdf_text_set_pdfdocenc . . . . . . . . . . . . . . . . . . . . . . 99 pdf_token_string_new . . . . . . . . . . . . . . . . . . . . . . . 157
pdf_text_set_unicode . . . . . . . . . . . . . . . . . . . . . . . . 99 pdf_token_valueless_new . . . . . . . . . . . . . . . . . . . 158
Function index 245
pdf_token_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 pdf_token_writer_reset . . . . . . . . . . . . . . . . . . . . . 156

pdf_uuid_equal_p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
pdf_token_writer_destroy . . . . . . . . . . . . . . . . . . 154
pdf_uuid_generate. . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
pdf_token_writer_new . . . . . . . . . . . . . . . . . . . . . . . 152 pdf_uuid_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Gnu PDF

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Gnu PDF

Caricato da

Copyright:

Formati disponibili

GNU PDF Library Reference

first Edition, Updated for version trunk.

Free Software Foundation

2.8.1 Floating Point Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

2.11.5 The Filesystem Implementation Interface . . . . . . . . . . . . . . . 144

3 Object Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

4 Document Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

5 Page Contents Layer . . . . . . . . . . . . . . . . . . . . . . . . . 230

6 Implementation Limits . . . . . . . . . . . . . . . . . . . . . . 231

Appendix A GNU Free Documentation License

Global variable index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Data type index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Function index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

2.2 Error Management

2.2.1 Status types

This list will grow as we get closer to a mature state of development.

2.2.2 Error Reporting procedures

pdf_i64_add (dest, addend_1, addend_2, &st);

pdf_i64_add (dest, addend_1, addend_2, &st);

2.2.3 Debugging procedures

2.3 Memory Allocation

Returns A pointer to the newly allocated memory.

p = (int *) pdf_alloc (sizeof(int));

void pdf_dealloc (const void *pointer ) [Function]

p = (char *) pdf_alloc (21);

p = (char *) pdf_alloc (4);

/* p now points to "abcd" */

p = (char *) pdf_realloc (5);

/* p now points to "abcde" */

p = (char *) pdf_realloc (4);

/* p now points to "abcd" */

2.4 Basic Types

2.4.2 Numeric Types

pdf_u32_t [Data Type]

2.4.3 Big Numbers

pdf_i64_t [Data Type]

bignum = pdf_i64_new((1 << 31),10); /*bignum is now -10*/

pdf_i64_assign(bignum, (1 << 31), 10, p_status);

void pdf_i64_subtraction (pdf i64 t *dest, const pdf i64 t [Function]

factor_1 = pdf_i64_new (0, 10);

dividend = pdf_i64_new(0, 200);

divisor = pdf_i64_new(0, 10);

if (pdf_i64_div (dest, 200, divisor) != PDF_OK) /* Now dest is 20 */

void pdf_i64_div_i32_divisor (pdf i64 t *dest, const pdf i64 t [Function]

dividend = pdf_i64_new(0, 200);

if (pdf_i64_div (dest, dividend, 10) != PDF_OK) /* Now dest is 20 */

divisor The divisor in the division

divisor = pdf_i64_new(0, 10);

if (pdf_i64_mod (dest, 105, divisor) != PDF_OK) /* Now dest is 5 */

dividend = pdf_i64_new(0, 105);

if (pdf_i64_mod (dest, dividend, 10) != PDF_OK) /* Now dest is 5 */

p status Pointer to a pdf status t variable to hold the status of the

number_1 = pdf_i64_new ((1 << 31), 10); /* number_1 is -10 */

number 2 pdf i32 t type variable

number_1 = pdf_i64_new ((1 << 31), 10); /* number_1 is -10 */

Returns A pdf status value:

bignum = pdf_i64_new (0, 10);

2.4.4 Memory Buffers

pdf_buffer_t [Data Type]

pdf_buffer_t pdf_buffer_new (pdf size t size ) [Function]

my_buffer = pdf_buffer_new (1024);

pdf_status_t pdf_buffer_destroy (pdf buffer t buffer ) [Function]

PDF_OK The operation suceeded.

bignum = pdf_i64_new((1 << 31),10); /bignum is now -10/

pdf_status_t (pdf_pm_set_text_fn_t) (void client_data, [Data Type]