DLI Implementation and Reference Guide - Datalogics

Implementation and
Reference Guide
Datalogics Interface
Datalogics ®

Datalogics
DATALOGICS INTERFACE
Implementation and Reference Guide

This guide is part of the Adobe® PDF Library v7.0Plus suite; 02/17/06.
Copyright 1999-2006 Datalogics Incorporated. All Rights Reserved.
Use of Datalogics software is subject to the applicable license agreement.
DL Interface is a trademark of Datalogics Incorporated. Other products mentioned herein as Datalogics products
are also trademarks or registered trademarks of Datalogics, Incorporated.
Adobe, Adobe PDF Library, Portable Document Format (PDF), PostScript, Acrobat, Distiller, Exchange and
Reader are trademarks of Adobe Systems Incorporated.
HP and HP-UX are registered trademarks of Hewlett Packard Corporation.
IBM, AIX, AS/400, OS/400, MVS, and OS/390 are registered trademarks of International Business Machines.
Java, J2EE, J2SE, J2ME, all Java-based marks, Sun and Solaris are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States and other countries.
Linux is a registered trademark of Linus Torvalds.
Microsoft, Windows and Windows NT are trademarks or registered trademarks of Microsoft Corporation.
SAS/C is a registered trademark of SAS Institute Inc.
UNIX is a registered trademark of The Open Group.
VeriSign® is a registered trademark of VeriSign, Inc. in the United States and/or other countries.
All other trademarks and registered trademarks are the property of their respective owners.
For additional information, contact:
Datalogics, Incorporated
101 North Wacker Drive, Suite 1800
Chicago, Illinois 60606-7301
Phone: 312-853-8200
Fax: 312-853-8282
www.datalogics.com
dlcomments@datalogics.com

TOC.i
Table of Contents
1 Getting Started 1.1
An Introduction to DLI 1.2
How to Create a PDF Document with DLI 1.2
How to Use this Book 1.4
What’s New in This Release 1.8
What’s New in Previous Releases 1.9
2 Initializing and Terminating the Library 2.1
Overview 2.2
Adobe PDF Library Data Structure 2.2
Adobe PDF Library Version Control 2.5
Files In Memory Activation 2.7
Initializing and Terminating via DLI 2.7
Writing PDF Output to Memory 2.13
API Comparison 2.15
3 Beginning and Ending a Document 3.1
Overview 3.2
4 Fonts 4.1
PDF Font Overview 4.2
Structure of a DLI Font 4.3
Font Creation Calls 4.5
Predefined Font Encodings 4.9
Unicode Text Support 4.10
Code Page Support 4.10
Performance Considerations 4.11
Accessing Fonts 4.11
5 Multibyte Text Work 5.1
Introduction 5.2
Loading and Creating Fonts 5.3
Creating DLPDFTEXT Areas 5.4
Working With DLPDFTEXT Areas 5.6
Performance Considerations 5.9
6 Working with Pages 6.1
Introduction to Page Interface 6.2
Page Interface Calls 6.2
7 Containers within Pages 7.1
What are Containers? 7.2

TOC.ii DLI Implementation and Reference Guide
8 Working with Content 8.1
Overview of Content Interface 8.2
Content Interface Calls 8.3
9 Working with Forms 9.1
Overview of Forms 9.2
Form Calls 9.2
10 Displaying Line Drawings 10.1
Overview 10.2
Approaches to Line Drawing 10.2
Graphic State and Line Drawing 10.14
11 Image Display 11.1
Overview 11.2
Graphic Image Structures 11.2
Graphic Image Forms 11.3
Image Creation Methods 11.5
Creating Transparent Graphics 11.10
12 Color and its Use 12.1
Library Color Descriptions 12.2
Colors in Images 12.2
Creating and Destroying Color Spaces 12.3
Values for Color Channels 12.5
Basic Color Spaces 12.5
Advanced Color Spaces 12.8
Building Patterned Color Spaces 12.10
Conversion between Models 12.12
13 Annotations and Links 13.1
Overview 13.2
Annotation Components 13.2
Modifying the Link Cos Object 13.8
14 Bookmark Creation 14.1
Overview 14.2
15 Digital Signatures 15.1
Overview 15.2
Public and Private Keys 15.2
Digital Signature Calls 15.3

Table of Contents
TOC.iii
16 Error Testing and Recovery 16.1
Overview 16.2
OS/390 Platform Concerns 16.3
17 Samples and Links 17.1
Running DLI Sample Applications 17.2
A DLI Reference Guide A.1

TOC.iv DLI Implementation and Reference Guide

1
Getting Started
This chapter introduces the Datalogics Interface.
Experienced users may want to skip directly to the section
“What’s New in This Release” on page 1.8 for
information on the latest enhancements and additions.
1.1

1.2 DLI Implementation and Reference Guide
An Introduction to DLI
The Datalogics Interface (DLI) facilitates the rapid creation of PDF documents and improves
performance, throughput and graphics handling. It does this by bypassing many of the functions of the
PDF Edit layer and eliminating redundant calls to the COS layer used in the Adobe® PDF Library. For
information on the various layers of Adobe PDF Library please see the Acrobat Core API Overview.
How to Create a PDF Document with DLI
The DLI package exists at the output end of the page creation process. As such, most of the intricacies of
line breaking, page breaking and general composition are outside of its scope.
The process of writing pages is where this package fits into an application. An overview of this process
follows:
1 Initialize DLI. (start of all processing)
2 Define the document.
3 Define fonts: i.e. Identify and describe each font to be used in the job to DLI. These can be done as
encountered, if so desired.
4 Define forms: i.e. Identify and describe each form to be used in the job to DLI. These can be done as
encountered, if so desired.
5 Define graphics: i.e. Identify and define each graphic to be used multiple times to DLI. These can be
done as encountered, if so desired.
6 For each page:
• Create a dlpdfpage object.
• Create a dlpdfcontent object.
7 Generate the content of a single page:
• For each graphic reference on the page, create the graphic in content.
• For each text line on the page, create the text in content.
8 End the content and inform DLI that the content is complete.
9 End the page and inform DLI that the page is complete.
10 End the document.
11 End the job.
Error handling during application execution is handled through the raising and handling of exceptions, as
defined by the Adobe PDF Library. These are similar to operation exceptions in C++. For details on
handling exceptions, please see the chapter “Error Testing and Recovery” on page 16.1.

Getting Started 1.3
What You Should Know
This document is intended for programmers who are familiar with text composition and the creation of
output drivers, or by application designers who are constructing an application based on the DLI
package.
You should have access to the Adobe PDF Library Applications Programming Interface (API) manual and
the Adobe PDF Specifications manual for your system.
For Adobe PDF Library v6.x releases, Adobe PDF Specification 1.5 is appropriate.For Adobe PDF
Library v7.x releases, Adobe PDF Specification 1.6 is appropriate.
NOTE: Some structures permitted in Adobe PDF Specification 1.6 may not be
permitted in Adobe PDF Specification 1.5, and some structures defined in Adobe
PDF Specification 1.5 are not available in Adobe PDF Specification 1.4.
The explanations, assumptions and samples provided in this guide refer to Adobe PDF Library v7.0.0Plus
and DLI v7.0 or higher.
DLI Initialization Required
Starting with DLI v2.1, the initialization process was simplified to enable initialization of the Adobe PDF
Library automatically when DLI itself was initialized. Though it may be functionally possible to bypass
the initialization of DLI for versions 2.1 and higher, an application should not do so. Using the DLI
initialization and termination routines not only simplifies application programming but also allows the
use of the Datalogics Files In Memory (FIM) System, and the enabling of certain optimizations in jobs
which span multiple documents.
NOTE: The Adobe PDF Library and DLI are not intended to be initialized more than
once within a single instance of an application. Doing so can produce undesirable
results. Versions of Adobe PDF Library prior to v6.1 are not thread-safe.
gcc Compilation Version
Adobe compiles their PDF Library components with gcc 3.2 on the Solaris® and Linux® operating
systems, and with Visual Age (xlC) 6.0 on the AIX® system. Datalogics does not recompile Adobe
components on any other compiler on these operating systems. This information is subject to change at
any time, so for the latest details on supported operating-system compilers and versions, please see the
readme.txt file of last-minute updates accompanying your software release files, or the Datalogics
website System Requirements page at http://www.datalogics.com/pdflibraryrequirements.asp.

1.4 DLI Implementation and Reference Guide
Unix Compiler Run-Time Libraries
For clients who are using native (i.e. platform-resident) UNIX® compilers, the run-time libraries for each
of these operating systems are available from the Free Software Foundation. Any clients wishing to
integrate the Adobe PDF Library and DLI components with their natively-compiled applications can
retrieve these run-time libraries free of charge from the Free Software Foundation at http://
www.gnu.org/software/gcc/.
How to Use this Book
This book has been created to guide you through the process of creating PDF documents with DLI. It
consists of two main sections:
• An Implementation section
• A Reference Guide appendix
The Implementation section begins with Chapter 1: Getting Started. It follows the steps needed to create
PDF and introduces DLI in relation to the Adobe PDF Library, explains the methods used in DLI, how
they fit together, and provides various samples.
The Reference Guide appendix lists all DLI methods alphabetically.
Each function or method listed in the first section of this manual, wherever it occurs, is linked to the same
function or method in the second section. In some cases you may find references to a particular function
appearing in several chapters of this document, depending on the context, and the function may be used
for (and explained for) different purposes within each chapter. Click the function name to go to the more

Getting Started 1.5
detailed reference information, which will provide full explanation of each, a full listing of calling
parameters and return values, and any Technical Notes which may apply.
You may also find a separate, standalone /Codesamples folder in your documentation files which
contains additional ASCII-text coding samples.
NOTE: The files in the /Codesamples folder, if present, are not intended to be
buildable source as-is, only to be demonstrations of correct command syntax for
different purposes.
Finally, the DLI release also includes a collection of complete, buildable sample applications, explained in
the "Samples and Links" chapter following.
The following list provides an outline of the chapters as well as a brief description of their contents. Click
on the Chapter title below to jump to its first page.
Chapter 1: "Getting Started" (This chapter) This chapter introduces the Adobe PDF Library and
DLI, including an overview of page creation, and describes the contents of this book, including
enhancements in new releases of DLI.
Chapter 2: "Initializing and Terminating the Library" describes initialization and termination
of the Adobe PDF Library.
Chapter 3: "Beginning and Ending a Document" describes all of the methods used to begin and
end a document.
Chapter 4: "Fonts" discusses creation and arrangement of fonts.
Chapter 5: "Multibyte Text Work" discusses the DLI methods available for creating and
manipulating multibyte text.
Chapter 6: "Working with Pages" DLI assumes that pages will be added to the end of the document
only. A page is represented by a data structure named DLPDFPAGE. This chapter explains the Page
Interface and defines the calls available at this level.
Chapter 7: "Containers within Pages" describes containers within pages, and provides examples of
various applications.
Chapter 8: "Working with Content" The Content Interface contains the bulk of the interface. At
this level, you make marks on paper. Those marks may be on a Page or on a Forms XObject. They may be

1.6 DLI Implementation and Reference Guide
text, line drawings or images. A content element is represented by the structure DLPDFCONTENT. This
chapter explains the Content Interface and defines the calls available at this level.
Chapter 9: "Working with Forms" Forms XObjects are represented via the structure
DLPDFFORM. This chapter explains forms, and defines the calls available.
Chapter 10: "Displaying Line Drawings" describes line drawings and the different approaches,
including directly-drawn and path-drawn methods.
Chapter 11: "Image Display" describes images as a predefined collection of shapes and colors.
Chapter 12: "Color and its Use" discusses Adobe PDF Library color descriptions, colors in images,
creating and destroying color spaces, patterned color spaces and more.
Chapter 13: "Annotations and Links" describes creating annotations and how to modify the Link
COS Structure.
Chapter 14: "Bookmark Creation" describes bookmark creation and the steps involved.
Chapter 15: "Digital Signatures" explains the process of adding a digital signature to a document,
and outlines the methods for use.
Chapter 16: "Error Testing and Recovery" discusses possible errors you may encounter and how
to resolve them.
Chapter 17: "Samples and Links" provides full program samples which have been compiled and
tested to illustrate various aspects of the Adobe PDF Library and DLI.
Appendix A: "DLI Reference Guide" provides an alphabetical listing of all methods used in DLI.
Document Conventions
The terms note, link and bookmark are used in this book the same way they are in the user interface of
Adobe PDF Library v7.x.xPlus®, Adobe Acrobat® and Adobe Reader®. These correspond to the text

Getting Started 1.7
annotation, link annotation and routine entry structures (respectively) that appear in a PDF file. See the
Portable Document Format Reference Manual for a description of the PDF file format.
The following documentation conventions appear throughout the manual to help you differentiate regular
text from product and program names, and to distinguish command syntax.
• Product and program names are set in italic type.
• Multi-line examples are separated from the text and set in
Courier monospace
• Directory names and filenames are contained within the text and set in Courier monospace.
• Commands are contained within the text and set in blue Courier monospace. In most cases, if you
are reading this document in PDF form via Adobe Acrobat or Adobe Reader, clicking on a DLI
command will jump you to the Reference Guide appendix for full information on that command.
• New terms are italicized.
• Page numbers in this book do not correspond to page numbers in the PDF file. The numbering scheme
(e.g. 4.1 or A.10) indicates the chapter number (4) or appendix letter (A) first, followed by the page
number (1 or 10), separated by a period.
Related Documentation
The following documents will be useful in developing applications using DLI.
Datalogics Resources
Adobe PDF Library and DLI Installation Guide This document describes the installation
requirements for using the Adobe PDF Library and DLI on the various platforms to which Datalogics has
ported these products.
Adobe PDF Library Developer Overview This document is designed to aid developers with
incorporating the API calls for the Adobe PDF Library into their composition application.
DLI Implementation and Reference Guide (This book) This document details the Datalogics
Interface, a simplified interface to the COS Layer of the Adobe PDF Library.
Java Interface User Guide This document details the Datalogics Java Interface, a Java-language
wrapper interface to the Adobe PDF Library and DLI.
Adobe Resources
The following documents are distributed by Adobe as part of the original Adobe PDF Library release, and
are redistributed by Datalogics without alteration. These and other documents may also be found on the

1.8 DLI Implementation and Reference Guide
Adobe website at http://partners.adobe.com/asn/acrobat/technotes.jsp. (Descriptions
below are provided by Adobe as part of their original accompanying readme.txt file.)
NOTE: Adobe Solutions Network (ASN) membership may be required in order to
access some material on the Adobe website. See http://
partners.adobe.com/asn/programs/developer/index.jsp for
more details.
Portable Document Format Reference Manual This document describes PDF Standard 1.6
specifications. The latest version may be found at http://partners.adobe.com/public/
developer/pdf/index_reference.html.
NOTE: Adobe also provides an accompanying errata file for this manual, with lastminute
updates and corrections. One copy is provided with this documentation
(see your documentation file folder), and you can check for newer copies at
http://partners.adobe.com/public/developer/en/pdf/
PDF16Errata.pdf
Adobe PDF Library Overview Technical Note #5189 provides background information and
development information for the Adobe PDF Library. Read this document before beginning development
for information such as supported platforms, known issues and development requirements.
Acrobat Core API Overview Technical Note #5190 provides an overview of the Acrobat API in
general. It covers information applicable to both Plug-in development and Library development. Read this
document to obtain an understanding of how the Acrobat API is organized.
Acrobat Core API Reference Technical Note #5191 is the reference manual for all of the Acrobat
API methods made available by the Adobe Acrobat viewer. It documents the parameters, return values
and availability of each method, as well as specific implementation notes. This document is useful while
developing with the Adobe PDF Library or planning development to determine method availability and
capabilities.
PDF Library Supplement to the Acrobat Core API Technical Note #5414 complements the
Acrobat Core API Reference and is specific to the Adobe PDF Library API methods. This is an important
and useful document for all Adobe PDF Library developers.
What’s New in This Release
This section contains highlights of new additions and enhancements to DLI v7.0. You should also check
the accompanying Release Notes file (typically ReleaseNotes.pdf) and readme.txt files (one each
accompanies the software release files and the documentation files in their respective folders or
directories) if present. Release Notes contain fixes and enhancements usually resulting from past problem

Getting Started 1.9
reports; the readme.txt files typically contain last-minute information on the current release of the
software or the documentation files.
Minor version upgrades may be made as running changes rather than full releases, so the version or subversion
number of your release may be newer than those listed here. See the accompanying readme.txt
file for the very latest changes and enhancements.
Revised DLI Version Numbering
Beginning with the Adobe PDF Library v7.x releases, DLI version numbering has been revised upwards
from the previous v3.x series to a new v7.x series, to better correspond with Adobe’s own versioning of
their Acrobat product lines.
What’s New in Previous Releases
A summary of enhancements in prior releases follows below. See the relevant chapters or the Reference
Guide appendix for full details on methods listed below.
DLI v3.0 for Adobe PDF Library v6.x featured a number of changes, briefly outlined here.
Adobe PDF Library Now Thread-Safe
As of Adobe PDF Library v6.1.0Plus and DLI v3.0.11, the Library is now re-entrant, and therefore safe
for multithreaded applications. See the following chapter and “Multi-Thread Initializations” on page 2.11
for more information on thread-safety issues.
Adobe PDF Library Version Control
The Adobe PDF Library is a set of routines associated with other Adobe products such as Adobe Acrobat,
Adobe Acrobat Distiller and Adobe Reader. The original Adobe PDF Library was labeled as version 1.2
in order to maintain consistency with the PDF standard of 1.2. The next version of the Library was
labeled version 4.0 (and subsequently 4.05) due to the tie-in with Acrobat v4.0. Versions 4.0/4.05 of the
Library complied with the PDF standard of 1.3. Adobe PDF Library v5.0.2Plus complied with PDF
Standard 1.4, Adobe PDF Library v6.x complied with PDF Standard 1.5, and so on.
PDF Level Declarations in Output
By default, the Adobe PDF Library declares the current PDF level compliance in output PDF files; e.g.
Adobe PDF Library v7.x applications building pages without Datalogics Interface methods will generate

1.10 DLI Implementation and Reference Guide
PDF v1.6. Applications generating output via DLI may generate different PDF declarations depending on
file contents and application coding; see below and “Adobe PDF Library Version Control” on page 2.5
for more details.
NOTE: Viewing a latest-generation PDF in a prior-version Adobe Acrobat or Adobe
Reader (e.g. viewing PDF v1.5 in Acrobat or Reader v5.0 or earlier) can produce a
popup warning of a PDF level mismatch, to warn the user that certain PDF features
new to that version may not be supported by the viewing program. While this is
only a warning, it may concern some users who have not upgraded to the latest
viewer. You should ensure that your document features are backwards-compatible
to older viewer versions where possible, or warn your users that a viewer upgrade
will be required in order to take full advantage of features in your document, as
appropriate.
PDF Level Declarations via DLI
Applications built with Adobe PDF Library and Datalogics Interface (e.g. Adobe PDF Library v6.1.1Plus
and DLI v3.0.19) and using DLI methods for output will have their output PDF compliance set
appropriately by DLI. Unlike Library output, which will always declare the highest compliance level
supported by the Library, files generated by DLI methods will declare the lowest PDF compliance level
necessary for proper handling of the document. By default, files will identify themselves as PDF v1.3
compliant, and only declare a higher level if the file really does contain higher-level PDF functionality.
(e.g. Output containing Optional Content Groups will declare PDF v1.5 compliance instead.) Some
further explanation can be found under “Selecting PDF Level Declarations via DLI” on page 2.6.
Digital Signature Support
New methods are now available for adding Digital Signatures to your documents, and a chapter on the
subject has been added to this manual. See “Digital Signatures” on page 15.1 for more details.

Getting Started 1.11
Enhanced Unicode Support
Unicode support included in DLI underwent significant revision for the v3.x series. Datalogics now ships
with International Components for Unicode (ICU) modules, which provide a number of benefits for users,
including:
• Complete TrueType, OpenType and TrueType/OpenType Collection font file support
• Support for all major Unicode encoding schemes, as well as hundreds of Chinese/Japanese/Korean/
Vietnamese and vendor-standard input formats
• Support for right-to-left text ordering and automatic character combining using the Unicode
BiDirectional algorithm
• Faster and less-memory-intensive creation of Unicode fonts
• Text output in PDF content areas as Unicode
NOTE: Since Unicode font creation does not use the Adobe PDF Library to locate
fonts, customers must now explicitly load fonts intended for Unicode into a
DLPDFINSTANCE before use. Additionally, users must be able to specify the
system location where these fonts reside. See the DLI sample application
WideText for a demonstration of loading and using Unicode fonts.
Addition of DLPDFTEXT Structure
In support of the revised Unicode architecture, the object DLPDFTEXT has been created. This is a reusable
container for text: an input string is supplied to DLPDFTEXT creation calls in an input encoding. The
DLPDFTEXT object stores this text in Unicode UTF-16 format, with Big-endian or Little-endian
orientation depending on the host platform.
DLI Initialization now Required
Initialization of DLI is now required; support for using DLI without initialization has been removed. If
you intend to use DLI methods in your application, you must intialize DLI via dlpdfinit. DLI users
should initialize the Adobe PDF Library through the DLI initialization call; PDFLInit and PDFLTerm
should never be directly called from a DLI application.
All DLI documents require an instance for creation. The dlpdfdoccreatewithinstance call has
been removed from the API, and the dlpdfinit and dlpdfdoccreate call have been modified
significantly (see “Updated Functions” on page 1.14). DLI should only be initialized once per process.
Streaming PostScript Removed
All PostScript output is produced using the Adobe PDF Library. Support for streaming PostScript created
by DLI has been removed. This facility was previously deprecated in the DLI v2.2 series.

1.12 DLI Implementation and Reference Guide
PDF Image Import Improvements
PDF image import has been enhanced as of DLI v3.0.13. The value of the imported PDF file's Rotate
key, if present, is now honored. Images are imported by DLI and placed in the rotated orientation
displayed by Adobe Reader and Acrobat.
For the dlpdfimagecreatefrompdf call, a value of 0 is now accepted for the Width and Depth
parameters. If either are 0, then the PDF page's crop box is used to form the DLPDFIMAGE's visible
region. This will be shifted using the XDisp and YDisp values to generate the imported image.
New Functions
dlpdfmemfiledeleteonclose
This method marks a Files In Memory (FIM) file to be removed from the filesystem once the last open
filehandle for the file has been closed.
NOTE: No file is automatically removed from memory, unless
dlpdfmemfiledeleteonclose has been called for a specific MDFile.
dlpdfmemfilesetbuffer
This method configures Files In Memory to directly use the buffer passed in as the file contents.
dlpdfmemfilesyssetmemlimit
This method establishes an upper bound, in bytes, of the memory usage allowed for file contents by DLI.
dlpdfmemfilesysgetmemusage
This returns an ASSize_t with the current usage, in bytes, of memory for file contents.

Getting Started 1.13
dlpdfdoccreatesignature
dlpdfdocsetsignatureappearance
dlpdfpageplacesignature
dlpdfsignaturesetdatacallback
dlpdfsignaturesetpkcs7cert
dlpdfsignaturesetx509cert
These new methods support Digital Signatures in documents. See the chapter on “Digital Signatures” on
page 15.1 for more details.
dlpdfdocasciips
This method was added to support creation of PostScript output suitable for transmission through
channels and to devices which do not accept binary data. Most PostScript printers cannot properly
process binary PostScript input; Distiller and most print spoolers will accept binary PostScript data.
dlpdfinstancesetgrcachelimits
This method was added to support customers who would like to limit the amount of filesystem storage
used for the DLI graphics cache. This accepts a low-water and a high-water mark, in bytes. If the graphics
cache reaches the high-water mark, graphics will be removed from the cache in least recently used (LRU)
order. Graphics will be removed until the cache falls to or below the low-water mark.
dlpdftext
This creates a DLPDFTEXT area from a string of a given length (in bytes) and an encoding.
dlpdftextshowencodingnames
This method can be used to obtain a list of valid Encoding names provided via the International
Components for Unicode (ICU) module, for use when calling dlpdftext.
dlpdftextfromutf8
dlpdftextfromutf16le
dlpdftextfromutf16be
dlpdftextfromutf16he
dlpdftextfromutf32le
dlpdftextfromutf32be
dlpdftextfromutf32he
These are convenience functions for common Unicode encodings.

1.14 DLI Implementation and Reference Guide
dlpdftextadvance
This supplies the x and y advance for a string in a DLPDFTEXT area.
dlpdftextstring
dlpdftextlength
dlpdftextstring returns the byte buffer for the stored string. dlpdftextlength returns the length,
in bytes, of this buffer.
dlpdftexttocontent
This pastes the DLPDFTEXT string into a DLPDFCONTENT area.
dlpdftextdestroy
This method destroys a DLPDFTEXT area.
dlpdfttload
This method loads the font from a TrueType or OpenType font file, or the fonts from a TrueType/
OpenType Collection font file. These fonts are loaded into the supplied DLPDFINSTANCE. Fonts loaded
in this manner are used before searching the system directories for fonts.
NOTE: This method does not fully support Adobe CFF-format OpenType font files.
CMaps as defined in the PDF Reference Manual should be used for these fonts.
Datalogics recommends creating them as CIDType0 fonts, using
dlpdfcontentwidetext for setting text.
Updated Functions
dlpdfinit
This has been revised significantly, and now requires three parameters:
• the PDFLData pointer containing Adobe PDF Library initialization data
• the default file system to use, or NULL for the Adobe PDF Library default filesystem
• NULL; reserved for future use as an optional argument
The DLI graphics cache has been enhanced to use the default ASFileSys implementation provided to
dlpdfinit for caching graphics. By default, the graphics cache file size is limited to 1.5GB. Customers

Getting Started 1.15
who wish to use larger graphics cache files are advised to supply a filesystem to dlpdfinit which is
capable of reliably handling files of the larger size.
dlpdfdoccreate
This call no longer accepts a PostScript filename. (Use dlpdfdocsetpsname, or supply one to
dlpdfdocwritePS.) The PDFNeeded flag has been removed; PDF processing is always performed. It
accepts one parameter, the DLPDFINSTANCE to use for the document.
dlpdfterm
This call now removes memory files used for the dlpdfttload call if the Files In Memory system is
used, and if these files are no longer in use.
Deleted Functions
dlpdfdocsevenbitsafe
This method was not able to guarantee a PDF output stream safe for a seven-bit channel. The PDF
specification refers to PDF as a binary format, and expects that consumers are able to accept a binary
input stream.
dlpdfdocHexGraphics
was an API for debugging graphic output. In the DLI v2.2.x series, this was disabled.
dlpdfdocsetformsascontent
...and...
dlpdfimageplaceascontent
...were not able to generate correct PDF output for some imported PDF files. This functionality was not
widely used, and these methods have been removed.
dlpdfdocsetembedappwidth
This method has been removed as fonts will, with the exception of the "standard" 14 fonts, always have
their widths included in the PDF font if the font is present on the system on which a job is run, or if these
widths are supplied to DLI.

1.16 DLI Implementation and Reference Guide
dlpdfdocseterrorfile
...and...
dlpdfdocsetwarningfile
...are no longer supported. Functions which need to communicate errors will raise an ASException as
required.
dlpdfdoccreatewithinstance
This has been replaced by a revised dlpdfdoccreate call. Since DLI initialization is required for v3.x
releases, the dlpdfdoccreate call accepts a DLPDFINSTANCE. See “Updated Functions” on page
1.14 for details.
dlpdffontverifytext
Given a font and a string of text, this method would ensure that every Unicode character had a valid glyph
ID associated with it. Because Unicode is now handled in the DLPDFTEXT structure and not the font, this
method was no longer needed.
dlpdfsetlevel
This method is now reserved for internal use. Although its function has not changed from prior releases, it
is no longer supported for applications built with DLI.
DLI v2.2.13
Default Search Path Suppression Expanded to All Platforms
The enhancement first provided with the Adobe PDF Library v5.0.2Plus and DLI v2.2.12 release for a
method of suppressing the default search path for AdobeFnt.lst on Unix platforms (see “Default
Search Path Suppression” on page 1.17 below) is now expanded to all platforms.
Image Search using Files In Memory
DLI now searches the default ASFileSys (whichever filesystem was selected by the application) for
graphic files, instead of automatically searching only the disk. (Graphic conversions are still cached to a
temporary file on a physical file system.)

Getting Started 1.17
1 Set the default file system to dlpdfmemfilesys.
2 Create a file in the Files In Memory filesystem, and use dlpdfmemfilesetdata to make a region of
memory into the file-in-memory.
3 Call dlpdfimagecreatefromfile with the name of the file-in-memory.
4 Set the default file system back to the original default, if files-in-memory is not being used for anything
else.
NOTE: Users currently using Files-In-Memory in their application but assuming
that images are always retrieved from disk may need to modify their applications.
They should either bring the images from disk into memory, or deliberately switch
the default filesystem to disk temporarily, in order to pull in the graphic(s) before
continuing with further processing.
DLI v2.2.12
Default Search Path Suppression
An enhancement has been added to enable the Adobe PDF Library to ignore its default search path
(which varies somewhat from one platform to another) when compiling its list of resources at
initialization time on Unix platforms. This is done by adding a PDFLDataRec.flags member to
PDFLInit/dlpdfinit, which can be filled with a kPDFLInitIgnoreDefaultDirectories value.
This will stop the Library from searching the current working directory on startup, or writing
AdobeFnt.lst entries on shutdown.

1.18 DLI Implementation and Reference Guide

2
Initializing
and Terminating the
Library
The procedure for initializing DLI and the Adobe PDF
Library defines font locations, memory management
routines and resource allocation in preparation for
document processing.
2.1

2.2 DLI Implementation and Reference Guide
Overview
The DLI initialization process has been simplified such that when DLI is initialized, it automatically
initializes the Adobe PDF Library as well. Initialization via DLI also provides the option of enabling the
Datalogics Files In Memory (FIM) system, by specifying a file system to be used for temporary files and
for file input/output operations.
DLI must be initialized before creating any documents with DLI or making any calls to the Adobe PDF
Library, should be initialized only once per composition program run, and should be terminated prior to
the application shutdown.
Adobe PDF Library Data Structure
Initialization of DLI and the Adobe PDF Library requires a specific collection of information, maintained
in the data structure PDFLDataRec. One such structure should be created and cleared to zeros before
starting the Adobe PDF Library. The next few sections deal with settings of parts of this structure to
prepare for initializing DLI and the Adobe PDF Library.
Setting Resource Directories
The PDFLDataRec record contains two fields (dirList and listLen) which are used to establish a list
of paths to be searched for font resources, its AdobeFnt.lst file. (See “The AdobeFnt.lst File”
below.)
NOTE: DLI does not search directory paths or environmental variable entries for
fonts loaded via dlpdfttload.
The resource directory listing (the PDFLDataRec record ) should not be used in OS/390, but may be used
in all other platforms. This list is constructed by allocating an array of pointers to strings, and filling each
pointer with a pointer to a path.
The field dirList should be set to point to this array. The field listLen should be set to the number of
entries in the above array. Examples of this usage can be found in the accompanying DLI sample
applications.
The AdobeFnt.lst File
The process (your Adobe PDF Library application, and also Adobe Acrobat or Adobe Reader) compiles
an AdobeFnt.lst file for its own use when either constructing a PDF document or rendering/displaying

Initializing and Terminating the Library 2.3
it later, for Adobe PDF Library and Adobe Acrobat applications respectively. It consists primarily of font
information within files found on your machine. (Its actual name varies by product, platform or release
level as AdobeFnt.lst, AdobeFnt07.lst or AdobeFnt08.lst, and possibly others; we will refer to
it generically as AdobeFnt.lst here.)
You should find that the AdobeFnt.lst file is only compiled if one is not already present, or if any file
in the directory is timestamped more recently than the AdobeFnt.lst file itself. The creation time does
of course go up if many files are present. The file is not recompiled every time the application is run, only
when certain conditions are met as described above.
For efficiency, try to minimize the number of files that must be searched. You can do this by running the
application from another location, so that the current working directory is one with very few files in it, or
alternatively make use of the kPDFLInitIgnoreDefaultDirectories flag (see “Default Search Path
Suppression Expanded to All Platforms” on page 1.16 for further details). You must still ensure that the
application gets a list of directories where its resources will be found.
Since the AdobeFnt.lst file is a plaintext file, compiled on an as-needed basis by the application, you
can review its contents in a text editor at any time to verify that it is finding the resources needed. Since it
is possible to have many copies of AdobeFnt.lst scattered about (one may be created whenever an
application is run in a new working directory for the first time), if there is any doubt as to which
AdobeFnt.lst is in use by the application, you are free to delete the existing copies (or temporarily
rename them in order to hide them), run the application again, and then look to see where a new copy has
appeared. Reviewing that file will show you the resources found by that instance of the application.
More information on this for each platform can be found in the Adobe PDF Library Overview, page 21
(February 7, 2005 edition), under the subheading "Initialization Details."
Setting Memory Allocation Routines
You may wish to use this portion of the PDFLDataRec record when your application contains a memory
allocation/deallocation schema that you want the Adobe PDF Library to share. In particular, if your

2.4 DLI Implementation and Reference Guide
application does not use the system malloc/calloc/free routines, which the Adobe PDF Library will
use by default, you may want to use this section.
Control of memory allocation is accomplished by the creation of a new record (TKAllocatorProcs).
You must allocate space for this record and fill in all of the fields in this record if you wish to establish
your own memory manager.
There are several procedures pointed to by this record:
• allocProc — a routine to allocate memory
• reallocProc — a routine to increase the size of an allocated block of memory
• freeProc — a routine to free memory
• memAvailProc — a routine that returns the amount of memory which may be requested without an
error occurring
The definitions of the interfaces for these procedures are contained in PDFInit.h. Basically, they are the
interfaces for malloc (or calloc), realloc and free for standard UNIX. However, each contains as
its first parameter a pointer to user data. This pointer is the fifth field of the TKAllocatorProcs record. See
"Displaying a Square" in the Programs Links chapter for an example of setting these values.
Setting Resource Allocation Routines
The Adobe PDF Library contains a robust set of routines for locating resources. However, if your
application wishes to control access to resources, this section is where such control is established.
The TKResourceProcs record is similar to the TKAllocatorProcs record. It contains a pair of
pointers to procedures for allocating and deallocating resources. The procedure interfaces are defined in
PDFInit.h.

Initializing and Terminating the Library 2.5
Adobe PDF Library Version Control
There are two version issues that you may need to consider when building and running your application:
the version of Adobe PDF Library and DLI in use, and the declared PDF version (or Compliance Level)
being declared within the PDF output being generated.
Obtaining Adobe PDF Library Version Number
The version number of the Adobe PDF Library which was initialized may be obtained at any time after
initialization as the return value of the method PDFLGetVersion:
• The high-order 16 bits of the value are the Major Version Number
• bits 8 through 15 are the Minor Version Number
• bits 0 through 7 are the Sub-minor Version Number
You may wish to have your application obtain and compare the returned Version Number to the constant
kPDFLVersion to see if the version of the Adobe PDF Library being used at runtime is the same, greater,
or less than the Version Number of with which it was compiled.
PDF Level Declarations in Output
PDF output files declare their compliance level with a particular version of the PDF Standard; e.g.
documents created with Adobe PDF Library v7.x can declare PDF v1.6. Applications reading, processing
or displaying PDF output may inspect the declaration within the file to determine how to process it. In
particular, Adobe Acrobat and Reader applications may produce a popup warning of possible
unsupported PDF features if they detect that the declared PDF level of the document is higher than what
they "know" to be the current PDF revision level at the time they were released.
For example, Adobe Acrobat or Reader v6.x will generate a popup warning if it opens a document
declaring PDF v1.6 compliance (output generated by Adobe PDF Library v7.x or similar). Adobe Acrobat
or Reader v5.x will generate a similar warning for PDF v1.6 or v1.5, and so on, even if the document does
not in fact contain any functionality unique to that higher PDF level. While this may seem like overkill,
the default behavior of PDF utilities is to ignore coding that they do not understand. Thus the popup
warning is shown to the user to help avoid situations where high-level content may be quietly ignored by
the utility, and the user does not notice the omission.
The Adobe PDF Library is a set of routines associated with other Adobe products such as Adobe Acrobat,
Adobe Acrobat Distiller and Adobe Reader. The original Adobe PDF Library was labeled as version 1.2
in order to maintain consistency with the PDF standard of 1.2. The next version of the Library was
labeled version 4.0 (and subsequently 4.05) due to the tie-in with Acrobat v4.0. Versions 4.0/4.05 of the
Library complied with the PDF standard of 1.3. Adobe PDF Library v5.0.2Plus complied with PDF

2.6 DLI Implementation and Reference Guide
Standard 1.4, and Adobe PDF Library v6.x complied with PDF Standard 1.5. Adobe PDF Library v7.x
continues the same practice, complying with PDF Standard 1.6.
By default, the Adobe PDF Library declares the current PDF level compliance in output PDF files; e.g.
Adobe PDF Library v7.x applications building pages without Datalogics Interface methods will generate
PDF v1.6. In contrast, DLI output methods declare PDF v1.3 compliance unless the output file actually
contains functionality introduced in a later version. (e.g. Optional Content Groups in PDF v1.5) Thus, if
you generate your PDF output using Adobe PDF Library methods, the document will always declare the
highest PDF version compliance; if you generate your output using DLI methods, it will declare PDF v1.3
unless a higher compliance level is actually needed.
Further description below applies only to PDF output generated via DLI methods.
NOTE: Viewing a latest-generation PDF in a prior-version Adobe Acrobat or Adobe
Reader (e.g. viewing PDF v1.6 in Acrobat or Reader v6.0 or earlier) can produce a
popup warning of a PDF level mismatch, to warn the user that certain PDF features
new to that version may not be supported by the viewing program. While this is
only a warning, it may concern some users who have not upgraded to the latest
viewer. You should ensure that your document features are backwards-compatible
to older viewer versions where possible, or warn your users that a viewer upgrade
will be required in order to take full advantage of features in your document, as
appropriate.
Selecting PDF Level Declarations via DLI
Applications built with Adobe PDF Library and Datalogics Interface (e.g. Adobe PDF Library v6.1.1Plus
and DLI v3.0.19) and using DLI methods for output will have their output PDF compliance set
appropriately by DLI. Unlike output generated solely by Adobe PDF Library methods, DLI-generated
files will by default identify themselves as PDF v1.3 compliant in their simplest form, or higher values if
appropriate, based on the functionality embedded in the document. You can manipulate this declared
value yourself if desired.
Overriding PDF Level Declarations via DLI
When generating PDF output, the internal PDF Compliance Level declaration to be issued is made up of
two internal component values, pdfMajorVer and pdfMinorVer, which are members of the
DLPDFDOC structure. pdfMajorVer defaults to 1, and when using DLI methods for PDF output,
pdfMinorVer initially defaults to 3 (PDF v1.3, for Adobe Acrobat v4 compatibility). If higher-level
functions are used within the output PDF document, the pdfMinorVer will be incremented as
appropriate (e.g. to 4 or 5, representing PDF v1.4 or PDF v1.5 respectively). You can force the declared
Compliance Level by assigning the value you desire to pdfMinorVer within your application.

Initializing and Terminating the Library 2.7
Files In Memory Activation
To increase the throughput of PDF generation, memory-mapped files may be used for temporary storage
and for final output of the PDF content. Output of a PDF file to both memory and disk is also supported
for environments where this feature is desired.
In order to utilize Files In Memory (FIM), DLI must be initialized through the dlpdfinit function call,
and the Datalogics memory file system must be passed to this function call. The memory file system may
be obtained by calling the dlpdfmemfilesys function, detailed below (see “dlpdfmemfilesys” on
page 2.9). This may be called before DLI (and hence the Adobe PDF Library) is initialized. Once set,
storage of temporary files in memory is automatic.
The DLI sample application MultiDoc, accompanying this release, demonstrates the coding and use of
Files In Memory. It can be invoked by adding the command-line argument MEMORY when calling the
sample application.
Initializing and Terminating via DLI
The following commands should be used to initialize and terminate the Adobe PDF Library and DLI. In a
single-threaded application, the initialization and termination processes must be called only once during
the life of the application. Attempting to initialize the Adobe PDF Library and DLI more than once in the
application may cause errors or unpredictable behavior, and is not supported. (You are free to create
multiple documents and/or multiple files within the run, but the initialization and termination of the
Adobe PDF Library and DLI is limited to one iteration of each. In a multi-threaded application, each
thread must perform its own initialization and termination.)

2.8 DLI Implementation and Reference Guide
dlpdfinit
This method initializes DLI, and prepares it to use the ASFileSys passed in as the second parameter;
this may be NULL if the caller does not have an ASFileSys to pass to dlpdfinit, or does not have a
filesystem preference.
The first parameter is a PDFLInit structure used to initialize the Adobe PDF Library. It is the same
structure that would be passed to the PDFLInit function call in legacy programs which use that function.
The second parameter of dlpdfinit is an ASFileSys record specifying what file system should be used
by DLI and the Adobe PDF Library. If NULL, the default file system operations will be used.
The third parameter is NULL, reserved for future use.
CAUTION: Versions of Adobe PDF Library prior to v6.1 are not thread-safe, and
should not be initialized more than once in a single job, either directly or via DLI.
Doing so can produce undesirable results. Your application is free to create
multiple output files or perform multiple tasks without exiting using the
appropriate methods (see the DLI MultiDoc sample application, for example),
but you must not terminate the Library until you are ready to stop the application,
and once you have terminated the Library, you cannot initialize it again. You can
accidentally call dlpdfinit (the DLI command) multiple times without problems,
as it contains internal code that prevents actual initialization from occurring more
than once, but you should not call PDFLInit (the Adobe PDF Library command)
more than once as a fatal error may occur. See further discussion on thread safety
in “Thread-Safe Issues” on page 2.12.
The DLI initialization call dlpdfinit must occur before any other call which makes reference to any
DLPDFDOC structure (with the exception of dlpdfmemfilesys, which may be called for setup
purposes). It returns a DLPDFINSTANCE pointer which may then be used to create documents. The
dlpdfinit function call may also return a NULL pointer, indicating that DLI or the Adobe PDF Library
could not initialize. If this occurs, neither DLI nor the Adobe PDF Library should be used, and if possible,
the calling program should cease execution as soon as is feasible.
Specifying an Alternate File System
The ASFileSys passed to dlpdfinit as its second argument will typically be either NULL (specifying
that the user has no preference for how DLI manages file input and output) or the dlpdfmemfilesys
call. Calling dlpdfmemfilesys will return the ASFileSys record to the Datalogics memory file system
for the Adobe PDF Library. This file system keeps temporary files in memory, instead of on disk, resulting

Initializing and Terminating the Library 2.9
in significantly improved processing speeds on some systems. You can create your own ASFileSys and
pass it in, if you wish more control over how files are manipulated.
NOTE: The included fonts must still be read from disk, and the PDF document
which is created will be written to a disk file, unless the steps described in
"Writing PDF Output to Memory" are taken. If the user has the means to specify
an alternative file system, that too may be passed into dlpdfinit.
Using a Graphics Cache
As of DLI v3.0.11, the DLI graphics cache has been enhanced to use the default ASFileSys
implementation provided to dlpdfinit for caching graphics. By default, the graphics cache file size is
limited to 1.5GB. Customers who wish to use larger graphics cache files are advised to supply a filesystem
to dlpdfinit which is capable of reliably handling files of the larger size.
NOTE: The cache size limit is checked every time a document is destroyed; the
cache may therefore temporarily exceed the cache size limit. When setting the
cache size limit, please note that to resize the graphics cache, free space equal to
the sum of the cache limit and the "low water" mark is required. Files In Memory
users with large graphics workloads are advised to lower the cache size limit to a
number appropriate for their target environment.
dlpdfmemfilesys
This procedure returns the ASFileSys structure which represents Datalogics’ Files In Memory file
system. This file system will only be used if PDF output is requested.
This structure is suitable as the second parameter to the dlpdfinit function.
Image Search using Files In Memory
With the release of DLI v2.2.13, an enhancement was added for a method of holding graphics in memory
and searching for them there, as opposed to storing and searching for graphics on disk only. This was not
in the form of a separate API; instead, DLI was altered to search the default ASFileSys (whichever
filesystem was selected by the application) for graphic files, instead of automatically searching only the
disk. (Graphic conversions are still cached to a temporary file on a physical file system.)
To take advantage of this, you would
1 Set the default file system to dlpdfmemfilesys.
2 Create a file in the Files In Memory filesystem, and use dlpdfmemfilesetdata to make a region of

2.10 DLI Implementation and Reference Guide
memory into the file-in-memory.
3 Call dlpdfimagecreatefromfile with the name of the file-in-memory.
4 Set the default file system back to the original default, if files-in-memory is not being used for anything
else.
NOTE: Users currently using Files-In-Memory in their application but assuming
that images are always retrieved from disk may need to modify their applications.
They should either
NOTE: • bring the images from disk into memory, or
NOTE: • deliberately switch the default filesystem to disk temporarily
NOTE: in order to pull in the graphic(s) before continuing with further processing.
Terminating DLI and the Adobe PDF Library
Termination of DLI is accomplished by calling dlpdfterm with the DLPDFINSTANCE pointer returned
from the dlpdfinit function call. This call should not be made until all DLI structures, with the
exception of the DLPDFINSTANCE pointer, and all PDE and PD library structures are freed. The
dlpdfterm call will free the DLPDFINSTANCE pointer and the pointers set in the PDFLDataRec
structure. Terminating DLI will also terminate the Adobe PDF Library.
dlpdfterm
This method will terminate DLI and the Adobe PDF Library. Call this function after all DLPDFDOC
structures have been disposed of. In the case of multi-threaded applications, each thread that initialized
the Library must also terminate it when finished.
This will typically be one of the last calls of a program using DLI. The call takes a DLPDFINSTANCE
pointer, which is the DLPDFINSTANCE pointer returned by the dlpdfinit function call. Any
composition program using DLI and the Adobe PDF Library should call dlpdfterm to terminate DLI
and the Adobe PDF Library before terminating itself. The dlpdfterm function takes the
DLPDFINSTANCE returned from dlpdfinit as its sole parameter.

Initializing and Terminating the Library 2.11
Typical Order of Calls
In summary, the overall calling sequence would be similar to the following example:
PDFLDataRec InitStruct;
DLPDFINSTANCE *pdfInstance = NULL;
/* to use Files In Memory */
pdfInstance = dlpdfinit(&InitStruct, dlpdfmemfilesys(), NULL);
/* to use standard files */
pdfInstance = dlpdfinit(&InitStruct, NULL, NULL);
if (!pdfInstance) /* if not 0 then error */
{
printf("Error initializing DLI -- aborting\n");
exit(1);
}
/* to close library */
dlpdfterm(pdfInstance);
Multi-Thread Initializations
Adobe PDF Library v6.1.0Plus and DLI v3.0.11 (or higher) are re-entrant, and therefore safe for
multithreaded applications. However, the Adobe PDF Library will perform cleanup work during
termination if no other instances are active, which will cause the Library to not initialize correctly for any
follow-on processes afterwards.
Therefore, though each thread must call PDFLInit/PDFLTerm or dlpdfinit/dlpdfterm (for DLI
applications), take care that Adobe PDF Library and DLI are not re-initialized after the last outstanding

2.12 DLI Implementation and Reference Guide
initialization has been terminated. For example, the following sequence will cause errors when attempting
to initialize Thread 2:
dlpdfinit()
[Thread 1 processing]
dlpdfterm()
dlpdfinit()
[Thread 2 processing]
dlpdfterm()
The problem above is that when Thread 1 terminates, no other processes are seen, and so shutdown
cleanup work begins, leading to errors when the initialization of Thread 2 comes along.
This sequence is recommended instead:
dlpdfinit()
dlpdfinit()
[thread 1 processing]
[thread 2 processing]
dlpdfterm()
dlpdfterm()
Thread-Safe Issues
Releases of the Adobe PDF Library prior to v6.1 were not thread-safe, and so by extension neither was
DLI. Adobe PDF Library v6.1 and its accompanying DLI were the first thread-safe releases in
distribution. Notes on use of prior versions within multi-threaded applications are given below.
It is possible to use pre-v6.1, non-thread-safe Library applications in a threaded environment under the
proper configuration in certain circumstances (although you should plan to upgrade your application to a
thread-safe Adobe PDF Library v6.1.x version at your next opportunity).
The general idea is that your application will queue the threads' interaction with the Library functions so
that they are executed one at a time. This is not too difficult to do if your pre-v6.1.x application uses a
mutex (Mutual Exclusion) algorithm to ensure that only one thread has access to the Library at any given
point in time. Testing has shown that execution time does not appear negatively impacted if the Library
segments are efficiently grouped, so that any given thread's Library activity is over and done with before
the next process calls. When properly implemented, there should be no noticeable deterioration in
performance due to the mutex gatekeeper logic, and a multi-threaded application can thus use an older,
pre-v6.1.x version of the Adobe PDF Library.
NOTE: While these instructions should enable you to implement a multi-threaded
application with an older, non-threadsafe version of the Library, you should
upgrade your application to make use of the latest thread-safe release as soon as
possible. Newer releases contain numerous other improvements in addition to
multithread capability.

Initializing and Terminating the Library 2.13
The problem revolves around the event handler stack. Since the Adobe PDF Library prior to v6.1.x had
only one handler stack, multiple, concurrent processes had no means of determining whose Library
activity was occurring at any given point in time, so it was possible for the Library to return a bad event
for one process that could be caught by another process by mistake. With mutex coding, you can ensure
that only one process has access to the Library at any given time, and the next process is granted access
only after the first one is concluded.
As stated, this works reasonably well as long as the Library access is efficiently arranged within the
application code. That is, you should not simply put one big DURING/HANDLER/END_HANDLER around
the entire algorithm, as the process will then commandeer the Library for its entire job, to the exclusion of
all others. Instead, divide the application algorithm into logical blocks of Library activity, so that Library
access is more likely to be evenly divided among concurrent processes. Also try to ensure that, if possible,
a given process waiting for an external event to finish will not be tying up Library access in the meantime.
Writing PDF Output to Memory
Output of PDF files to memory ("transient files") requires slight changes to your application, summarized
below.
When calling dlpdfdocsetpdfname or dlpdfdocwritepdf functions, these functions must be given
a filename which marks the file as a transient file. This is done by prefacing the document's filename with
the transient prefix, obtained by calling the dlpdfmemfiletransientprefix function. This returns a
character string with the necessary prefix, which marks the file such that it is not written to disk.
Call dlpdfdocwritepdf when the document is complete, and obtain the ASPathName for the string
passed to dlpdfdocwritepdf. Obtain the MDFile representing the Files In Memory entry for the
document via the dlpdfmemfileacquire (ASPathName) function. This returns the MDFile for the
document. Then, the size of the memory buffer needed to contain the file can be obtained with the
dlpdfmemfilesize(MDFile) call, and the information itself is returned (as a const unsigned
char buffer of the size returned by the call above) by the dlpdfmemfiledata (MDFile) function.
Copy the contents of the returned pointer as soon as possible. This pointer should not be changed or
modified, and should not be freed. Call dlpdfmemfilerelease MDFile) to release the file, its
memory and other resources once this file is finished being used. The function will return the remaining
number of acquisitions for the Files In Memory file.

2.14 DLI Implementation and Reference Guide
The functions to support this are:
dlpdfmemfileacquire
This function acquires the file given by the pathname passed in, and returns it as an MDFile. A memory
file is eligible to be removed when no acquisitions are outstanding upon it.
dlpdfmemfilesize
This function returns an ASSize_t value containing the smallest size of a block of memory (in bytes)
which could contain the data of the given MDFile.
dlpdfmemfiledata
This function returns a pointer to a memory representation of this file. The contents should be copied as
soon as possible, and must be neither altered nor freed.
dlpdfmemfilesetdata
This function sets the file passed in to contain the data passed to the function. This completely overwrites
the file’s previous contents. Returns TRUE if successful, or FALSE if the file's contents could not be set.
dlpdfmemfilerelease
Decrements the file's acquisition counter and signals to DLI that the application no longer requires the
use of this file. A file should be released for each acquisition made to the file; if it is not released, then
release of the file's memory and other resources will be delayed until the end of program execution.
dlpdfmemfiletransientprefix
Returns a string representing the transient prefix. Memory files whose names start with the transient
prefix will not be written to disk. Otherwise, the files will be written to disk upon file closure or program
termination.

Initializing and Terminating the Library 2.15
API Comparison
The Hellodli program sample was created to provide a clear comparison between a sample program
using the DLI API in conjunction with the Adobe PDF Library API, and one using the Adobe PDF
Library API exclusively. The similarities and differences between the two types of applications can be seen
by comparing the hellodli.c file to the helowrld.c file provided by Adobe.
The two programs perform largely the same task: Produce a simple, one-page document with a line of text
on it. You can compare the source code for each file to see which Adobe PDF Library methods are
replaced by DLI methods. In most cases, you should find that the DLI methods are simpler and easier to
implement. On a larger scale, DLI methods also enable Files In Memory processing, which in turn allows
faster processing times and reduced I/O activity for intermediate work file actions.

2.16 DLI Implementation and Reference Guide

3
Beginning and
Ending a Document
This chapter describes the methods provided in DLI to
create and write a document.
3.1

3.2 DLI Implementation and Reference Guide
Overview
DLI provides a simple interface to create and write documents. It uses a document structure (DLPDFDOC)
to differentiate between documents, allowing for the simultaneous creation of a number of documents.
DLPDFDOC reflects the current status of the document at all times and is required input to most other DLI
calls. As the document is created with Adobe PDF Library support, a CosDoc and a PDDoc are created
within the Library, and these may be obtained from this structure for use in calls outside of DLI.
The Adobe PDF Library establishes the name and many of the attributes of a document when it is
completed, rather than when it is begun. Many existing composition engines do not do this. For this
reason, the document structure has a convenient set of handles to permit the specification of such
attributes at document creation time, rather than at document write time.
There are a number of calls available at the Document Interface. Multiple documents may be created and
maintained at one time.
Required Use of Exception Handlers
Except for dlpdfinit and dlpdfterm, all calls to the Document Interface must be within an exception
handler (i.e. DURING/HANDLER/END_HANDLER statements) and all DLI documents should be destroyed
prior to closing the Adobe PDF Library. This can be done all at once or one step at a time. Both DLI and
the Adobe PDF Library may raise exceptions in the form of escapes.
dlpdfinit and dlpdfterm must not be enclosed in these handlers because they are not set up before
initialization, and are freed during termination.
dlpdfdoccreate
This method will create and return a pointer to a new document, as a DLPDFDOC pointer. As of DLI v3.0,
this call no longer accepts a PostScript filename. (Use dlpdfdocsetpsname, or supply one to
dlpdfdocwritePS.) It accepts one parameter, the DLPDFINSTANCE to use for the document.
dlpdfdoccompress
This method should be called before any content is placed onto a page. Content placed prior to this call
will not be compressed. The compression algorithm used is Flate.

Beginning and Ending a Document 3.3
dlpdfdocembedfonts
When this method is called, all fonts seen will be embedded in the document if possible, including Base 14
fonts. The flag set by this method is in DLPDFDOC->EmbedFonts, and may be safely manipulated by the
client program. It is also possible to specify embedding and subsetting on the font create call.
NOTE: If a font is available but not licensed for embedding, it will be created as a
referenced font rather than an embedded font. An exception is not returned for
this condition, but the NotEmbedded flag of the DLPDFFONT structure can be
inspected after the dlpdfdocembedfonts call, if desired.
dlpdfdocsetencoding
The encoding of created fonts will default to WinAnsiEncoding on Windows machines and Standard
encoding on all other platforms. You may set it to any valid encoding through this method.
This encoding is used when the font create call does not include an encoding.
dlpdfdocsetpdfname
When the desired name of the PDF file resulting from this document is known at document creation time,
it may be stored using this method and will be retrieved when the document is written.
dlpdfdoclinearize
When it is known at document creation time that this file should be written in a linearized form, this
knowledge may be stored via this method and will be retrieved when the document is written.
dlpdfdocsetdocinfo
This method accepts couplets of information, each a string (encoded as PDFDocEncoding values), and
saves them in the document information structure of the document. This may be done at any time.
dlpdfdocmakethumbnails
For Adobe PDF Library v4.x and higher, this method will create a thumbnail image for each page in the
document. This call may be made at any time prior to writing the document. Thumbnails will be created
automatically at document write time.

3.4 DLI Implementation and Reference Guide
dlpdfdocwritepdf
This call causes the document to be written to a PDF file. It accepts as parameters a document handle, an
optional string giving the name of the file to be written, and a flag indicating whether linearization is
desired.
If a name has been saved via dlpdfdocpdfname, that name will be used in the write, regardless of the
specification of a name in the name parameter. If neither a name parameter nor a saved name is present,
an exception (genErrBadParm) will be raised.
If the linearize parameter is TRUE, or the method dlpdfdoclinearize has been used, the
document will be linearized; otherwise, it will be nonlinearized.
dlpdfdocencrypt
This call causes the document contents to be encrypted using the Adobe PDF Library standard encryption
mechanism. It accepts a DLPDFDOC pointer, a character pointer to the user password, a character pointer
to the owner password, and a PDPerms data type. The latter must contain the security permissions as
outlined in the Acrobat Core API Reference Manual in the PDPerms definition. This call may be made at
any time prior to dlpdfdocwritepdf.
dlpdfdocsetencryptkeylen
This enables variable length encryption keys as supported by the Adobe PDF Library. It accepts a
DLPDFDOC pointer, a parameter specifying the number of bytes between 5 and 16 inclusive used to
determine key length used during encryption.
This function can be called to set the length of the encryption key before a call to dlpdfdocencrypt if
the application is to use an encryption key length other than the original 40-bit length provided in
previous versions.
The use of this function is optional if the original 40-bit key length is to be used. Subsequent calls to
dlpdfdocencrypt will use the number of bytes specified in the call to

Beginning and Ending a Document 3.5
dlpdfdocsetencryptkeylen. If the key length has not been set previously, the standard 5-byte value
is used as the default.
For more information on Encryption, refer to the beginning of section 3.5, "Encryption," in the Adobe
PDF Reference manual. For information on PDDocSetNewSecurityData and
StdSecurityDataRec, see the Adobe Core API Reference Guide.
NOTE: For applications generating multiple documents,
dlpdfdocsetencryptkeylen must be called for each document for which
an encryption key length other than the standard 5-byte value is desired.

3.6 DLI Implementation and Reference Guide

4
Fonts
For most users of DLI, font creation is both one of the
most important and one of the most difficult aspects of an
application. Though DLI has been designed to hide most
of the complexity of font creation, there is still a lot to
understand regarding font creation and usage. With the
ability to use most Windows and Macintosh native code
pages, as well as Unicode (using Adobe PDF Library
v5.0.2Plus or higher), the DLI font mechanism is flexible
enough to handle nearly any user request.
4.1

4.2 DLI Implementation and Reference Guide
PDF Font Overview
It is important to start by understanding the difference between the terms character and glyph. A
character is an abstract, named entity, such as "hyphen." A glyph is the representation of a character
contained within a font: the mark in the PDF file which visually represents the character, what you see onscreen
or on paper. This is an important distinction, since some font types use character identifiers to
typeset text; others use glyph identifiers to typeset text. For this chapter, the terms character and glyph
will be used interchangeably unless the technical distinction is important, in which case this will be noted.
Characters and glyphs in a PDF font can be addressed using either one-byte encodings (such as
WinAnsiEncoding), multibyte encodings (such as Shift-JIS), or 2-byte glyph identifier (GID)
encodings for some TrueType fonts. Some fonts support more than one method of accessing characters.
There are two categories of fonts in the PDF file format:
• Simple fonts
• Composite fonts
Simple Fonts
Simple fonts are those fonts which are addressed using one byte per glyph or character. PostScript Type1
fonts and most TrueType fonts fall into this category. With these fonts, no more than 255 characters are
addressable. DLI offers the flexibility to easily encode which characters are accessible by accepting an
encoding array. The widths of these characters can also be controlled by providing an array of character
widths.
PDF TrueType fonts which have a post table can use encoding vectors to access fonts outside the Adobe
standard one-byte encodings.
Composite Fonts
Composite fonts are fonts which use multibyte encodings or GID values. These are known as CID fonts
(for "Character ID") or Type0 fonts, even though many are not accessed using a CID value.
There are two varieties of Type0 fonts:
• CIDType0
• CIDType2

Fonts 4.3
CIDType0 Fonts
CIDType0 fonts use the CMap file format as specified by Adobe, and will accept a number of different
encodings, though these CMap files are typically somewhat narrow in their range of addressable
characters. A CIDType0 font is usable with a set of CMap files; this is the only way to access characters.
CIDType2 Fonts
CIDType2 fonts are also TrueType font streams, but are addressed using 2-byte glyph identifiers (glyph
IDs). These should not be created using CMaps, since the fonts are not keyed by character but by glyph.
Instead, a CIDToGID map is used to convert the 2-byte character in the PDF text strings to glyph IDs for
the font.
For font files loaded into a DLPDFINSTANCE, DLI uses the International Components for Unicode (ICU)
to translate Unicode inputs and a large array of vendor-defined multibyte encodings to output text. The
DLPDFTEXT structure is used to properly combine characters and support right-to-left reading order. For
CIDType2 fonts, a mapping from the DLPDFTEXT input to glyph IDs for output is generated. Whenever
possible, the output text in the PDF file is in UTF16 big-endian format.
The Adobe PDF Library and DLI also allow CIDType2 fonts to be used for a number of single-byte
vendor encodings. Output is in two-byte glyph IDs which correspond to glyph identifiers in the embedded
font stream. Text is input using the DLPDFCONTENT text calls as if using a single-byte font.
Most TrueType and OpenType font files can be used to create either TrueType (single-byte) or CIDType2
PDF fonts. In all cases, TrueType and CIDType2 fonts should be both embedded and subset to ensure
reliable results when viewing and printing. In this chapter, the term "TrueType font" means a PDF
TrueType font using a one-byte encoding, and the term "CIDType2 font" means a TrueType or OpenType
font using GID values to access characters in the PDF file.
Structure of a DLI Font
A font is reflected in the structure DLPDFFONT. These structures are created by the font creation calls on a
per-document basis. They may be used only within the document they were created with. Fonts are
tracked within the document, and destroyed when the document is destroyed. Pointers to fonts are invalid
after the destruction of their document. All DLPDFFONT structures for a given document will be released
when that document is destroyed. Therefore, methods that use DLPDFFONT as a parameter (i.e.
dlpdfcontenttext, dlpdfcontentwidetext, dlpdfcontenttextwidth,
dlpdfcontentwidetextwidth) must be called before the document is destroyed

4.4 DLI Implementation and Reference Guide
Font Embedding Status
The field DLPDFFONT->NotEmbedded will be TRUE only if a request was made to subset the font but
the request procedure failed. If the font could not embed due to license restrictions (i.e. the request
procedure functioned correctly, but the font itself is not licensed for embedding), an exception will be
raised instead.
Font Subsetting Status
The field DLPDFFONT->SubSetMap will be NULL if a font is not subset. The field will be not NULL if a
font is (or will be) subset.
Font Attributes
The field DLPDFFONT->RequestedFontAttr is a PDEFontAttrs structure. It is populated with the
font attributes of the system font actually used to create the font, with the alterations requested by the
calling application.
Document EmbedFonts Flag
If the document that contains the font carries the flag EmbedFonts (normally set by
dlpdfdocembedfonts), then all fonts for that document will be embedded, regardless of the call used
to create those fonts.
All fonts will be subset unless either
• they were created with a call to explicitly not embed the fonts, or
• license restrictions prevent the font from being embedded.
NOTE: If a font is available but not licensed for embedding, it will be created as a
referenced font rather than an embedded font. An exception is not returned for
this condition, but the NotEmbedded flag of the DLPDFFONT structure can be
inspected after the dlpdfdocembedfonts call, if desired.
Entries in the DLPDFFONT structure should not be altered after a font is created. Except for certain
specific exceptions to be noted here, changes made to this structure will not be subsequently reflected in
the font that is created and placed in the PDF document.

Fonts 4.5
Font Creation Calls
There are several procedures available for creating a DLPDFFONT structure:
• dlpdffontcreate
• dlpdffontcreateembedded
• dlpdffontcreatewithmetrics
• dlpdffontcreatewithmetricsembedded
All of these calls create the DLPDFFONT structure described above. They are listed in increasing order of
control given over font characteristics, and according to the amount of information a user is required to
have about a given font. Those near the top of the list above require less initial information from the user
than those further down.
The dlpdffontcreatewithmetrics and dlpdffontcreatewithmetricsembedded calls can be
used to modify the character width table and the character encoding vector array, as well as all the font
attributes which are reflected in the PDEFontAttrs structure these calls require.
Repetitive Font Creation Calls
A DLPDFDOC maintains a list of defined fonts by the name and font attributes requested. Second and
subsequent calls to create a font structure of a given name and attributes will return the same font
structure as the first call. For example, if you ask for the Type1 font Baskerville 20 times, with the same
attributes every time, only a single PDF font structure for Baskerville will be created, and only a single
DLPDFFONT structure will be created for Baskerville. However, if these requests supply differing font
attributes, more than one copy of Baskerville is created.
NOTE: The dlpdffontcreate family of calls will always allow the creation of
the Adobe standard type 1 fonts. The names of these 14 fonts (sometimes referred
to as the Base 14 fonts) can be found in the PDF Reference.
dlpdffontcreate
This is the basic font access method. It accepts a font name and optionally a font type, both as strings.
When the font type is present, the method will attempt to find a font which matches both that type and
name. If none is found, it will attempt to match the specified name in any type of font.
Font Searching Sequence
The specific dlpdffontcreate search procedure follows this sequence, in order, until a font fitting the
search parameters is identified. For each test below, the order of preference when searching for a match is

4.6 DLI Implementation and Reference Guide
for Type 1 fonts first, then TrueType fonts, and finally CID fonts. If no match occurs, the next test in the
sequence below is attempted.
1 The current DLPDFDOC is searched for fonts with the same name and type as requested. If one was
already created, it is returned.
2 If a Base 14 font is requested and is not to be embedded, it is created and returned.
3 If the name is matched in the DLPDFINSTANCE font cache, the font is copied to the current
DLPDFDOC and returned. (This is where fonts loaded via dlpdfttload are processed.)
4 The system is searched for a font of explicit name and type requested by the user. If found, it is created
and returned.
5 The system is searched for a font of explicit name (without regard to type) requested by the user. If
found, it is created and returned.
6 If any font of the same family and typeface style is found, it is created and returned.
If a font using a one-byte encoding is found for this name, its width table in the document’s encoding will
be loaded into the DLPDFFONT->WidthTable. If the document indicates that all fonts are to be
embedded, this font will be embedded and subset if possible. The font structure created will carry all of
the metrics of this font, so that if it is not embedded and is not present on the imaging platform, a
Multiple Master (or "multi-master") font can be used to provide imaging of the document.
The encoding used in this font will be the encoding specified in dlpdfdocsetencoding, if that call has
been used; otherwise it will default depending on the system in use: WinAnsiEncoding will be used on
Windows systems and Adobe standard encoding will be used on UNIX, OS/390 and AS/400 systems.
If dlpdffontcreate is called without a font name, it will raise a genErrBadParm exception ("Bad
Parameters") and exit.
dlpdffontcreateembedded
This method behaves like dlpdffontcreate, except that:
• The font will be embedded (if possible) regardless of the overall document settings.
• If the subset flag is TRUE, the embedded font will be subset.
• If the subset flag is FALSE, the embedded font will not be subset.
NOTE: Type0 fonts must be subset if they are embedded.

Fonts 4.7
dlpdffontcreatewithmetrics
This method allows the user greater control over the font selection process, and permits alteration of the
width table, encoding vector and font attributes of the font returned. This call should be used when the
characteristics of a font need to be altered.
The application using this function should initialize the PDEFontAttrs structure with NULL values
before calling. It should then fill out the name of the font to be located. Supplied parameters, with the
exception of the psName and cidFontType fields (and the font name given, if the font returned has a
different name), will be used to change the characteristics of the font if these are set.
CAUTION: It is not difficult to create an invalid font by setting these values
incorrectly. Therefore, the application should set only the fields that it is
concerned with affecting in the returned font, and leave the rest as NULL values.
The dlpdffontcreatewithmetrics function will match system fonts based on the parameters in the
PDEFontAttrs structure:
• If a system font is found, it will be altered to reflect the values in the PDEFontAttrs structure (with
the exceptions noted above).
• If no system font is found, a font will be created if a valid width table and set of PDEFontAttrs are
passed into this function.
• If no system font is found and an invalid width table or set of font attributes is passed to this function,
an exception will be raised.
The encoding field in the PDEFontAttrs font attributes structure is an ASAtom containing one of the
significant strings listed in "Predefined Font Encodings," or the name of a predefined encoding or CMap
file (as given in the PDF Reference manual). This should correspond to the encoding format in which the
font’s text is to be typeset.
NOTE: Not all the predefined encodings may be used with all fonts. Details on
which types will accept which values are given in the section on predefined font
encodings later in this chapter.
The type field in the PDEFontAttrs font attributes structure should be filled in by the user. If it is not
(i.e. currently ASAtomNull), then any type of font (Type1, TrueType, etc.) may be used. Otherwise, a

4.8 DLI Implementation and Reference Guide
font of the matching type will be selected if present. If no font of the matching type is found, any suitablynamed
font will be returned.
The charSet field in the PDEFontAttrs font attributes structure may be set to "Roman" or
ASAtomNull. With an ASAtom value of "Roman," only a font containing the Adobe standard character
set will be used; with ASAtomNull, any character set will be acceptable.
The wMode field in the PDEFontAttrs font attributes structure may be set to 0 (horizontal) or 1
(vertical) to select a font of the appropriate writing mode.
The other fields in the font attributes structure are explained in Adobe PDF Library documentation.
Width Table
A width table may be included with this method for use with TrueType or Type1 fonts. Generally, you
should include such a table specifically in cases where you expect that the font is not known either to the
Adobe PDF Library or to Adobe Reader, or when character widths have to be altered — for example, in
the case where an encoding vector (described below) is used. This table is arranged from the first character
to the 256th character for the encoding or encoding vector used to create the font.
A font not present on the system must be represented by a width table.
Encoding Vector
You may wish to modify the encoding vector for a Type1 or TrueType font. There are many reasons for
doing this. It is required if you must access characters within the font not normally encoded. It may be
done as a convenience when your data is encoded differently from the default encoding of the font.
Encodings which are not based on any of the predefined font encodings may also be created and used in
this manner.
The encoding vector is an array of 256 pointers to strings. The values of the strings are the glyph names of
the encoded characters, as these are defined in the font. Positions which are not encoded should contain
the string .notdef.
Type0 fonts may not be encoded. Further, some TrueType fonts may behave unpredictably if an encoding
vector is supplied. The PDF Reference Manual recommends that encoding vectors not be supplied for
TrueType fonts. Please see the PDF Reference Manual for further details.
dlpdffontcreatewithmetricsembedded
This method behaves the same as dlpdffontcreatewithmetrics, but with the following exception:
all fonts created with this method will be embedded (if possible), regardless of the setting of the

Fonts 4.9
document's embed fonts flag; if subset is TRUE the embedded font will be subset, if it is FALSE, the
font will be fully embedded, regardless of the document's font embedding settings. If the requested font is
not found by DLI, or the font is not embeddable due to license restrictions, an exception will be raised.
By manipulating the font calls within the hellodli.c sample program, you can compare results of using
font references, embedded fonts and multi-master fonts.
Predefined Font Encodings
Use of an ASAtomNull for a font encoding will yield a font which uses its "Built-In" encoding; this is
recommended for symbol (e.g. Pi) fonts where a named encoding is not desired. DLI recognizes a number
of strings that, when used to create ASAtoms and passed into DLI functions requiring a font encoding,
serve to denote certain predefined encodings for a font.
Setting the document encoding via dlpdfdocsetencoding does not affect the encoding used for
symbol fonts, to prevent these from becoming inadvertently invalidated. Named encodings passed into the
font creation calls above, however, will be reflected in symbol fonts.
The strings, and the font types they are valid for, are enumerated below:
Table 4-1: Encoding Font Types
Encoding String Value
AdobeStandardEncoding
WinAnsiEncoding
MacRomanEncoding
Valid Font Types
Type1,TrueType
Type1,TrueType
Type1,TrueType
MacExpertEncoding Type1,TrueType
Identity-H
Identity-V
Other Predefined CMaps
CIDType0,CIDType2
CIDType0,CIDType2
CIDType0
Adobe PDF Library v5.x and
higher only:
WinCP1250
WinCP1251
WinCP1253
WinCP1254
WinCP1255
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2

4.10 DLI Implementation and Reference Guide
Encoding String Value
WinCP1256
WinCP1257
WinCP1258
MacCentralEuropean
MacCentralEuropean
MacCroatian
MacRomanian
MacCyrillic
MacUkranian
MacGreek
MacCentralEuropean
MacTurkish
MacArabic
MacHebrew
Valid Font Types
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
CIDType2
Unicode Text Support
Unicode text support is available for customers using Adobe PDF Library v5.x or higher. It is highly
recommended that customers use CIDType2 fonts whenever possible when setting Unicode text.
CIDType2 fonts may be created from most system TrueType and OpenType fonts.
Code Page Support
Users of Adobe PDF Library v5.x (or higher) and CIDType2 fonts are also able to access automatic
translations for many Windows and Macintosh platform encodings. Text to be set in these fonts should be
in a NULL-terminated string in the one-byte platform encoding the font was created with. DLI and the
Adobe PDF Library will automatically translate this into a string of 2-byte GID values.

Fonts 4.11
Performance Considerations
Creation of fonts can be resource-intensive. For users creating multiple documents, the DLPDFINSTANCE
structure for a document caches most information for fonts which have been created for other documents.
This adds a significant speedup for creators of multiple documents over previous versions of DLI.
However, to obtain the best performance from DLI, users should remember the following:
• Fonts created for a document have most of their characteristics, including their system fonts and
translation tables, cached in the DLPDFINSTANCE used to create the document.
• TrueType and Type1 fonts allow for faster processing than CIDType0 and CIDType2 fonts. They
should therefore be used whenever possible.
Accessing Fonts
Font access for the Library is dependent on both the Adobe PDF Library version and the operating
system. It is explained in the Adobe PDF Library Overview manual for all systems other than OS/390.
OS/390 Font Access
For OS/390, the font access method is based on the UNIX method for v1 of the Library. It will attempt to
locate resources via several methods, in this sequence:
1 It will first look for a DD statement named ADOBERES
2 If that is not found, it will look for the PDS member SYS1.PARMLIB(ADOBERES)
3 If that is not found, it will look for ADOBE.PDFLIB.RESOURCE.INDEX(ADOBERES).
4 CMAPS are found by looking for ADOBE.PDFLIB.RESOURCE.INDEX(ADOBECMP).
The ADOBERES listing found at one of those locations is assumed to be a pointer to a listing of 1 entry:
ADOBE.PDFLIB.RESOURCE.INDEX(FONTS). The content of these files is expected to be encoded
using EBCDIC.
The ADOBECMP listing has 1 entry: ADOBE.PDFLIB.RESOURCE.INDEX(CMAPS) This member
contains a lookup table for the CMAP files.

4.12 DLI Implementation and Reference Guide

5
Multibyte
Text Work
DLI has been enhanced over the years to provide
significant support of Unicode and of multibyte character
set encodings. This chapter discusses those enhancements,
and the methods available for multibyte text work.
5.1

5.2 DLI Implementation and Reference Guide
Introduction
Beginning with its v3.0 release, DLI underwent significant enhancements for support of Unicode and of
multibyte character set encodings. With the inclusion of the International Components for Unicode (ICU),
DLI was able to properly set text in hundreds of multibyte encodings and all the common Unicode
encodings. DLI can now set text in scripts which flow from right to left (e.g. Arabic), support the Unicode
BiDirectional algorithm, and feature character shaping and glyph combining. Unicode text composition is
also significantly faster and less memory-intensive than previous DLI Unicode implementations.
NOTE: The previous support for Unicode, as introduced in DLI v2.2, has been
phased out and is no longer available.
There are two components to this support:
• Enhancements to the DLPDFFONT functionality
• A new DLPDFTEXT structure
To use these enhancements, fonts must be explicitly loaded into the DLPDFINSTANCE for a job; once
loaded, they are available to all documents created with the DLPDFINSTANCE. The fonts are used to set
text (in Unicode or multibyte encodings) into a DLPDFTEXT area. The text in the DLPDFTEXT area is
stored in Unicode UCS-2 format (in host-order endianness), and may be manipulated or extracted. The
DLPDFTEXT is placed into a DLPDFCONTENT area, to place the text into the PDF content area. Text is
written to the PDF file in UCS-2 big-endian format whenever possible. All fonts loaded are automatically
subset to ensure proper output in generated PDF documents.
Please see information on the DLI sample “WideText” on page 17.18 for a demonstration of how to use
the new DLI font and text functions to typeset Unicode and multibyte text.

Multibyte Text Work 5.3
Loading and Creating Fonts
To use the enhanced DLI text functionality, fonts must first be loaded into a DLPDFINSTANCE, then
created using the dlpdffontcreate calls.
dlpdfttload
Loading the font is done using the dlpdfttload function. This call accepts TrueType, OpenType and
TrueType collection files.
NOTE: Adobe CFF OpenType font files may not properly subset at this time. The
sample “WideText” on page 17.18 shows the recommended usage for these fonts,
using the DLPDFCONTENT multibyte text handling.
int dlpdfttload (DLPDFINSTANCE, ASFile, ASAtom[], int)
• The first argument provides a DLPDFINSTANCE into which the font is loaded; once that is done, any
document using the instance may create the font.
• The second argument is a font file, supplied as an ASFile for the second parameter; please see the
sample “WideText” on page 17.18 for an example of creating an ASFile from a file on disk.
• The third argument is an array of ASAtoms. Because a font file may contain more than one font, the
caller must supply an array of ASAtoms as the third parameter.
• The fourth argument is the number of array entries. The dlpdfttload function will fill the array with
ASAtoms of the fonts loaded, up to the size of the ASAtom array. If the array is too small to hold all the
font names, the additional fonts will still be loaded, but the names will not be returned. Datalogics
recommends that this array be allocated to hold a sufficient number of entries to prevent this. In
practice, a dozen ASAtom entries should be sufficient.
The dlpdfttload function returns the number of fonts loaded from the font file. An exception may be
raised for invalid parameters, if the font file could not be opened, or if there was a problem invoking the
font loader.
NOTE: If a given font file has already been loaded, dlpdfttload returns a -1,
and does not re-parse the font file (for performance reasons).
Once loaded, the font may then be created using the dlpdffontcreate calls (see “Font Creation Calls”
on page 4.5). The easiest means of creating the DLPDFFONT structure is to call
dlpdffontcreateembedded, supplying the DLPDFDOC in which to use the font, the name of the font
loaded (use the ASAtomGetString call to obtain a C-string representation of the font name), and a

5.4 DLI Implementation and Reference Guide
NULL or "Type0" for the third parameter. The fourth parameter must be True, since it is illegal to embed
Type0 fonts without subsetting.
Because the DLPDFINSTANCE font cache is searched for fonts before the system is searched, a font loaded
with dlpdfttload will be found before the system is examined, unless a more specific font creation call
is used. If both single-byte and multibyte versions of a font are required for a DLI document, use the
dlpdffontcreatewithmetrics calls, specifying Type0 as the font type for multibyte fonts, and
either Type1 or TrueType as appropriate for the single-byte font.
An easier alternative is to create the single-byte versions of the required fonts before loading the fonts into
the DLPDFINSTANCE. However, it is recommended that you use the multibyte font for all text output if
possible, to ensure optimal PDF file viewing performance and file size.
Creating DLPDFTEXT Areas
A DLPDFTEXT area is a container for multibyte and Unicode text. Text is placed into the container using
the dlpdftext function (or one of the shortcut functions) described below. This text is converted into
Unicode, in UTF-16 format, stored in host-endian byte order (little-endian for the Win32 and Intel/Linux
platforms, big-endian elsewhere), and automatically shaped and processed through the Unicode
BiDirectional (BiDi) algorithm. This text may then be placed into a DLPDFCONTENT area for output.
dlpdftext
The dlpdftext method is used to create a DLPDFTEXT area from a buffer of text in a given encoding.
DLPDFTEXT *dlpdftext(void *, ASUns32, ASAtom)
• The first parameter is passed in as a pointer to a data buffer.
• The second parameter is the number of bytes in this buffer.
• The third parameter is the encoding of the supplied text. An exception will be raised for invalid
parameters, or if the text could not be properly converted from the input encoding to the platformendian
Unicode representation.

Multibyte Text Work 5.5
dlpdftextshowencodingnames
There are over 1200 encodings and encoding aliases that may be used as input encodings, corresponding
to the format of the input text for a DLPDFTEXT area. To obtain a list of these encodings, use the
dlpdftextshowencodingnames function call:
void dlpdftextshowencodingnames(char *)
This function call will write out a file containing a list of valid encoding names and aliases to the
pathname supplied as the input parameter. It will raise an exception if unable to write this file.
dlpdftext Shortcut Functions
For NULL-terminated Unicode text (the NULL terminator will vary from encoding to encoding), the
following shortcut functions are provided, each using the encoding listed in parentheses:
• DLPDFTEXT *dlpdftextfromutf8(void *) (utf-8)
• DLPDFTEXT *dlpdftextfromutf16be(void *) (utf-16be)
• DLPDFTEXT *dlpdftextfromutf16he(void *) (utf-16be or utf-16le, by platform)
• DLPDFTEXT *dlpdftextfromutf16le(void *) (utf-16le)
• DLPDFTEXT *dlpdftextfromutf32be(void *) (utf-32be)
• DLPDFTEXT *dlpdftextfromutf32he(void *) (utf-32be or utf-32le, by platform)
• DLPDFTEXT *dlpdftextfromutf32le(void *) (utf-32le)
These shortcut functions require the input text to be NULL-terminated, but do not require a Unicode byteorder
marker. An exception will be raised for invalid input, or if the input text could not be properly
converted to the platform-endian Unicode representation.

5.6 DLI Implementation and Reference Guide
Working With DLPDFTEXT Areas
Once created, a DLPDFTEXT area may not be altered. Users may wish to create a new DLPDFTEXT area
containing a portion of the text in a previously created DLPDFTEXT area to fit text lines to document
boundaries, or to accomplish other tasks. Users may obtain the text from a DLPDFTEXT area and use this
as the basis for a new DLPDFTEXT area, using the dlpdftextstring and dlpdftextlength calls:
dlpdftextstring
void *dlpdftextstring(DLPDFTEXT *)
This call returns the text contained in a DLPDFTEXT area, in UTF-16 format. This text is in host-endian
format (little-endian for Win32 and Intel/Linux platforms, big-endian elsewhere) and does not include a
Unicode byte-order marker. An exception will be raised if an invalid DLPDFTEXT area is supplied.
dlpdftextlength
ASUns32 dlpdftextlength(DLPDFTEXT *)
This call returns the length of the text in a DLPDFTEXT area, in bytes. The buffer returned by the
dlpdftextstring call will be this length. With the buffer and the length returned by these two calls, a
user may make a new DLPDFTEXT area with a subset of the returned text, using the dlpdftext call and
the appropriate Unicode encoding ASAtom.
dlpdftextadvance
The most common use for making new text areas from portions of a DLPDFTEXT area is to copyfit text to
composed lines. The dlpdftextadvance function call is used to supply the width and height change for
a string of text, and accounts for character shaping and combining, as well as horizontal reading
direction. The dlpdfcontentwidetextwidth function call may be used to get a rough estimate of the
width or height change for a string. The dlpdfcontentwidetextwidth call does not take character
shaping or combining into account, and assumes a left-to-right line data orientation. The

Multibyte Text Work 5.7
dlpdftextadvance call looks much like the dlpdfcontentwidetextwidth calls, but with some
enhancements.
void dlpdftextadvance (DLPDFTEXT *, DLPDFFONT *,
PDEGraphicState *,
PDETextState *,
ASFixed, ASFixed,
dlpdftext_X,
ASFixed, ASFixedPoint *)
• The first argument is a DLPDFTEXT area that contains text to be set...
• ...in the indicated DLPDFFONT...
• ...using the supplied graphics of PDEGraphicState...
• ...and text states of PDETextState.
• The fifth argument describes the point size of the font;
• the sixth argument describes the set width of the font;
• the seventh argument, the dlpdftext_X parameter, is one of DLPDFTEXT_X_LEFT or
DLPDFTEXT_X_RIGHT, used to indicate whether the starting location is the left or right end
(respectively) of the text, distinguishing a left-to-right line order (e.g. English) from a right-to-left line
order (e.g. Arabic);
• the eighth argument indicates the angle of text (in counterclockwise degrees), supplied as an ASFixed
value;
• the ninth argument is a pointer to an ASFixedPoint; the X and Y position change resulting from this
call is returned in ASFixed units in this ASFixedPoint.
An exception will be raised for invalid parameters, or if the text advance could not be calculated.
dlpdftexttocontent
Once a line of text to be set is generated, it can be placed into a content area using the
dlpdftexttocontent function call. It is similar in declaration to the dlpdftextadvance call, but

5.8 DLI Implementation and Reference Guide
note the addition of the DLPDFCONTENT area pointer as the second parameter. Also note the additional
ASFixed parameters:
void dlpdftexttocontent (DLPDFTEXT *, DLPDFCONTENT *,
DLPDFFONT *,
PDEGraphicState *,
PDETextState *,
ASFixed, ASFixed, ASFixed, ASFixed,
dlpdftext_X, ASFixed)
• The first argument is a DLPDFTEXT area that contains text to be set...
• ...to be placed in the indicated DLPDFCONTENT...
• ...in the indicated DLPDFFONT...
• ...using the supplied graphics of PDEGraphicState...
• ...and text states of PDETextState.
• The sixth parameter, the first of four ASFixed parameters, denotes font point size;
• the seventh parameter is set width;
• the eighth parameter is the X-axis value of the starting baseline position;
• the ninth parameter is the Y-axis value of the baseline position;
• the tenth parameter, dlpdftext_X, is one of DLPDFTEXT_X_LEFT or DLPDFTEXT_X_RIGHT, used
to indicate whether the starting location is the left or right end (respectively) of the text, distinguishing
a left-to-right line order (e.g. English) from a right-to-left line order (e.g. Arabic);
• the eleventh parameter indicates the angle of text (in counterclockwise degrees), supplied as an
ASFixed value.
dlpdftextdestroy
After placing the DLPDFTEXT area, or after finishing with any DLPDFTEXT area, destroy the text area
with the dlpdftextdestroy function call:
void dlpdftextdestroy (DLPDFTEXT *)
After destroying a DLPDFTEXT area, the memory for the text and other information is released, and the
text area may no longer be used by an application.

Multibyte Text Work 5.9
Performance Considerations
The Unicode and multibyte functions in DLI described above represent an order of magnitude of
performance improvements and run-time memory usage. In addition, Datalogics can offer some notes and
tips on performance and other considerations:
• Do not create separate DLPDFCONTENT areas for each DLPDFTEXT string. In general, each
DLPDFCONTENT area created represents additional overhead during both creation and processing of a
PDF file, increased file size, and slower rendering of a PDF page. Best performance is usually obtained
by using one DLPDFCONTENT area per page, and pasting all content into this content area.
• Avoid using both single-byte and multibyte versions of fonts. This results in increased creation time to
subset two different fonts, as well as slower rendering and processing of PDF files.
• If you are typesetting in Chinese, Japanese or Korean, and are certain that readers of a PDF file will
have the appropriate Acrobat language pack installed for their reader, consider using the Adobe
OpenType fonts (subtype 0 CID fonts), and not embedding or subsetting. Though you will not be able
to use the functionality described in this chapter, this could prove to generate faster and smaller PDF
files. See the WideText sample application included beginning with the DLI v3.0.4 release for a
demonstration of how to set Unicode text using these fonts.

5.10 DLI Implementation and Reference Guide

6
Working with
Pages
This chapter explains pages and defines the calls available
at this level.
6.1

6.2 DLI Implementation and Reference Guide
Introduction to Page Interface
DLI presumes that pages will be added to the end of the document only. This is required for optimal
generation of the PDF Page Tree Structures, and matches the most common modes for creating
documents. If output to PDF is desired and local PostScript is not, you may use DLI to create most pages,
and then add pages out of order to the document via the COS Layer interface. If local PostScript is
enabled, these added pages will be placed as if they were following the last page.
Page Structure
A page is represented in DLI by the data structure DLPDFPAGE. These data structures, one per page, are
tracked within the package and destroyed when the document is destroyed. Pointers to these structures
remain valid until the document is destroyed.
Page Interface Calls
Calls available to the Page Interface in DLI are:
dlpdfpagefindfromnumber
This procedure will return the DLPDFPAGE construct for the specified page. This is provided to allow
pages to be modified after creation without having to keep pointers to all of the pages in the application.
If the page number specified has not yet been created, a NULL pointer will be returned. The first page is
considered to be page number one.
dlpdfpagecreate
This procedure will create a new page in the current document. It will be positioned following all other
pages in the current document. If the specified document does not exist, an exception genErrBadParm
will be raised. Width and Height must be specified as greater than zero, and are assumed to be in points.

Working with Pages 6.3
dlpdfpagerotate
This function will cause the page to be rotated clockwise to the specified angle. Permissible rotation angles
are increments of 90 degrees only. Angle values greater than 360 will be reduced by 360 degrees, then
rounded to the nearest 90-degree increment.
This call may be issued at any time after a page is created and will be effective in PDF and Adobe
PostScript.
dlpdfpagecosobj
This function will return a COS object that represents the page in the Adobe PDF Library. It may be used
to apply COS Layer operations to the page beyond those functions defined in the package.
dlpdfpagenumber
This function will return the sequence number of the specified page. This number may be used in
conjunction with the PDDoc returned by dlpdfdocpddoc to acquire a PDPage for the specified page.
This PDPage will permit Edit Layer functions to be applied to the page beyond those defined in this
package.
dlpdfpagesetid
This function will add an ID Entry to the page dictionary. This is generally a page’s FOLIO.

6.4 DLI Implementation and Reference Guide

7
Containers
within Pages
This chapter describes containers within pages and
provides examples of various applications.
7.1

7.2 DLI Implementation and Reference Guide
What are Containers?
Container may be a misleading name. These structures “contain” text and drawing commands in the
meaning of structure or hierarchy, but they do not have a limited geometry in the sense of edges or
boundaries. They “contain” text in data processing terms, but are not visual constructs like lines and
columns, and hence are not containers in the typographic sense.
The best way to think of these structures is as a boundless plane. This plane may be positioned, rotated, or
scaled relative to the media on which the text will eventually be imaged. There is no restriction on the
order or placement of things within a container. That is, within the container you are not constrained to
move from left to right, or top to bottom. Nor are you limited to the quadrant that is the range of positive
values. Negative positions within the plane may be used as well as positive positions.
You may use as many containers within a page as you wish, and they may be positioned in any way. There
is an overhead for the use of a container, however, and keeping the number small is desirable.
The simplest use of containers is to create one for each page, and leave it positioned at its default location
and rotation. In this case, drawing on the plane and drawing on the page are identical operations. The
default configuration of a plane is
• positioned with its origin at the lower left hand corner of the media
• scaled 1.0 in both horizontal and vertical directions
• oriented with positive values of X proceeding to the right
• oriented with positive values of Y proceeding upward
Often, an existing composition engine will use other positioning. For instance, if your engine assumes that
(0, 0) is the upper left hand corner of the page and positive values of leading proceed down the page, then
repositioning the container will allow you to use the X/Y values you have already calculated without
changing them.
DLI contains three calls that will permit you to modify the location, scaling or rotation of a container
(and its content) relative to a page. These may be used at any time before a container is committed to a
page. Other transformations (mirroring, shearing, etc.) may be accomplished by directly modifying the
field AreaXform within the content structure and calling dlpdfcontentrotate to make that new
transformation effective.
CAUTION: The transform applied here will also apply to all contents, and many of
the possible transformations may not be desirable.

Containers within Pages 7.3
Simplest Container Case
In the simplest case, all of the composed data contain X/Y coordinates in (points * 100), calculated
from the lower left hand corner of the page:
"C" Example: Simplest Container Case
void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth,
userdata *UserData)
{
DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth);
DLPDFCONTENT *Content = dlpdfcontentcreate (Doc);
USERDATA *UserWork = UserData;
while (UserWork)
{
WriteLine (UserWork, Content);
UserWork = UserWork->next;
}
}
dlpdfcontenttopage (Content, Page);
Scaling
This case assumes all of the above, but distances are in (points * 10) vertically and (points *
1000) horizontally. Note that all of your distances, including point sizes and font widths, must conform
to this for this single simple solution:
"C" Example: Container with Scale
void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth,
userdata *UserData)
{
DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth);
DLPDFCONTENT *Content = dlpdfcontentcreate (Doc);
}
dlpdfcontentscale (Content,
FloatToFixed (1/ 1000),
FloatToFixed (1/10));
USERDATA *UserWork = UserData;
while (UserWork)
{
WriteLine (UserWork, Content);
UserWork = UserWork->next;
}
dlpdfcontenttopage (Content, Page);

7.4 DLI Implementation and Reference Guide
Inversion
This case assumes that the data in your text will originate in the upper right hand corner of the page. Scale
factors remain as for the previous example. Note that in the data writing routine, all vertical positions
must be inverted: e.g. something placed at 4 points below the top of the page would be specified to DLI as
-4.
"C" Example: Container Moved to Top of Page
void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth,
userdata *UserData)
{
DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth);
DLPDFCONTENT *Content = dlpdfcontentcreate (Doc);
}
dlpdfcontenttranslate (Content, 0, Depth);
dlpdfcontentscale (Content,
FloatToFixed (1/ 1000),
FloatToFixed (1/10));
userdata *UserWork = UserData;
while (UserWork)
{
WriteLine (UserWork, Content);
UserWork = UserWork->next;
}
dlpdfcontenttopage (Content, Page);

Containers within Pages 7.5
Areas
If your composition engine describes lines as being members of an area and positions within that area,
then you may want to create a container for each area, and distort it to match your definition of an area:
"C" Example: Container within an Area
void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth,
areadata *AreaData)
{
DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth);
areadata *CurrentArea = AreaData;
ASFixedMatrix Matrix;
while (AreaData)
{
DLPDFCONTENT *Content = dlpdfcontentcreate (Doc);
/* Calculate rotated lower left corner */
Matrix.a = Matrix.d = fixedOne;/* Unity Matrix */
Matrix.b = Matrix.c = 0;
/* Translate the matrix to the lower left corner of the
* area to be rotated */
Matrix.h = AreaData->X;
Matrix.v = Depth - AreaData->Y - AreaData->Depth;
/* Rotate the matrix to the desired angle */
dlpdfmatrixrotate (&Matrix, AreaData->Rotation);
/* Translate the width and depth of the area to the
* desired angle */
Point.h = AreaData->Width;
Point.v = AreaData->Depth;
FixedMatrixTransform (&Point, &Matrix, &Point);
/* Translate to the upper left corner of the rotated area */
dlpdcontenttranslate (Content,
Point.h - AreaData->Width,
Point.v - AreaData->Depth);
dlpdfcontentrotate (Content, AreaData->Rotation);
WriteLines (AreaData->UserData, Content);
dlpdfcontenttopage (Content, Page);
}
AreaData = AreaData->Next;

7.6 DLI Implementation and Reference Guide
Collection of Areas
In this example, the page content is divided into areas. Each area has a location relative to the top left of
the page, a width, a depth and a rotation. Each area’s contents are specified as an X/Y coordinate relative
to the top left of the area. For simplicity, assume that all data is in points and is in ASFixed format:
"C" Example: Multiple Containers per Page with Rotation
void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth,
areadata *AreaData)
{
DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth);
areadata *CurrentArea = AreaData;
while (AreaData)
{
DLPDFCONTENT *Content = dlpdfcontentcreate (Doc);
dlpdcontenttranslate (Content, AreaData->X,
Depth - AreaData->Y);
dlpdfcontentrotate (Content, AreaData->Rotation);
WriteLines (AreaData->UserData, Content);
dlpdfcontenttopage (Content, Page);
AreaData = AreaData->Next;
}
For the rotation to work correctly in the preceding example, the composition engine must supply the X/Y
coordinates of the area as the upper left corner viewed from the text, regardless of rotation. That is:
u.l
no
rotation
u.l
90
rotation
u.l
180
rotation
u.l
270
rotation
When the area is always viewed as upright, i.e. the position of the area is always given as the highest,
leftmost point on the page where that is area to be placed with no rotation, the previous example should
be used instead.

8
Working
with Content
This chapter explains content and defines the calls
available at this level.
8.1

8.2 DLI Implementation and Reference Guide
Overview of Content Interface
The Content Interface contains the bulk of the interface. At this level, you make marks on paper. Those
marks may be on a Page or on a Forms XObject. They may be text, line drawings, or images. The marks
made in a content area may also be used in a patterned color.
Control Structures
Control of style is maintained in the Adobe PDF Library structures PDEGraphicState and
PDETextState. These structures are created and modified exactly as if the Adobe PDF Library were
used without DLI.
When created, content structures are always associated with a given document. They may be filled with
arbitrarily complex text. After filling, they are associated with a Page or with a Forms XObject.
Association destroys the structure. A single content element may be associated with a Forms XObject.
Any number of elements may be associated with a Page.
A set of transforms may be associated with a content element to position it within the Forms XObject or
Page. This permits simple definition of text in columns or areas.
Layering of text is straightforward:
• The first mark made is considered to be on the bottom; all following marks are above it.
• When an Image or a Form is included in a page, it is above all preceding text and below all following
text.
• When multiple content elements are contained in a page, they are layered in the order they are added to
the page.
A content element is represented by the structure DLPDFCONTENT. These structures are destroyed when
associated with a page or form, and pointers to them should not be used after that time.

Working with Content 8.3
Content Interface Calls
The following sections contain information about the calls available for content elements.
Creation and Positioning
These calls are used to create and position a text container.
Background colors, textures, and graphics may also be created for a container by the use of image and
drawing commands, although special functions have not been supplied to accomplish these.
dlpdfcontentcreate
This function will create a new content element. It will be created with a rotation of zero degrees, a
position of (0,0), and scaling of (1,1).
dlpdfcontentrotate
This procedure will rotate all of the contents of a given content structure by the specified amount. The
given value may be any amount, but will be reduced to between 0 and 360 degrees. It is expressed in
degrees of counter-clockwise rotation about the content structure’s lower-left corner.
dlpdfcontentscale
This procedure will scale all of the content of a given content structure by the specified amount, which
must be a positive number greater than 0.0001.
dlpdfcontenttranslate
This procedure will move all of the contents of a content structure by the specified amounts, which are
assumed to be in points. Positive values move up or right, depending on the axis; negative values move
down and left.

8.4 DLI Implementation and Reference Guide
Text Placement
These calls are used to position text within a container.
dlpdfcontenttext
This procedure adds a NULL-terminated string of text to the content. It will be placed such that the
baseline of the left edge of the first character aligns with the given position (XPos,YPos) in points. The
baseline should also proceed at the angle specified in Rotate, where zero is to the right and positive
numbers produce counter-clockwise rotation in degrees. It will be set in the specified font at the specified
PointSize and SetWidth. The parameters of PDEGraphicState and PDETextState will be
observed.
dlpdfcontentwidetext
Same as dlpdfcontenttext, but permits Unicode and MultiByte text.
Text Width Evaluation
On occasion, it is necessary to know the width of text. The following calls will accomplish that.
dlpdfcontenttextwidth
This procedure is included as an aid to composition, and to transforming widths, particularly word space
widths, into PDF units. The procedure will return the width (in points) of the specified text.
Its calling parameters include:
• the specified Font
• the text to be measured
• its current SetWidth (horizontal point size)
• Current Text State, a pointer to a PDETextState structure, which may be NULL. It can also be
declared memset() to all 0 values, and used right away; no further initialization is required, nor is it
provided for.
dlpdfcontentwidetextwidth
Same as dlpdfcontenttextwidth, but permits multi-byte (Unicode) text.

Working with Content 8.5
Line Drawing
These calls are used to draw lines within an area, and to fill or stroke those lines. Common to all of these
calls is the PDEGraphicState, which defines line drawing parameters (Line Width, Join, Miter,
etc.) and the Paint Operator, which defines how the path defined should be treated (kPDEStroke,
kPDEFill, kPDEEoFill, or a combination of these).
There are two color definitions within the PDEGraphicState:
• Fill Color will be used with the operators kPDEFill or kPDEEoFill.
• Stroke Color will be used with the operator kPDEStroke.
All of the fields within PDEGraphicState will be honored.
NOTE: Stroking will colorize to a given width, while filling will colorize within the
borders. To draw lines, use stroking to give the line a width.
Functions are provided here to produce commonly-used shapes. The general path operator
dlpdfcontentpath can image arbitrarily complex shapes.
All of the coordinate values and sizes specified below are considered to be in points. The content element
in which these are placed may translate, scale or rotate the image.
dlpdfcontentclip
This call is used to establish a clipping path. Note that clipping paths are not established automatically for
images, forms, or line drawings. Generally, PDF images page more efficiently if there is no clipping
involved.
A clipping region is considered a part of the content structure, and will be ended at the end of a content
structure. Clipping regions may be nested, but each nested region must fit within the previous region. A
clipping region can, and should, be ended as soon as possible, using the dlpdfcontentclipend call.
The Path and Pathlen operands of this call are identical to the dlpdfcontentpath operands. The
EOClip operand should be FALSE for a normal clip and TRUE for an Even/Odd clip.
dlpdfcontentclipend
This call is used to manually end a clipping region prior to the end of the content structure. It should be
called as soon as possible after a clipping region is established.

8.6 DLI Implementation and Reference Guide
dlpdfcontentpath
This procedure will mark a path within the content. The path is specified as an array of ASFixed values,
pointed to by Path, with PathLen entries in the array. This is in all ways the same path as would be used
by the Adobe PDF Library path operators. Such a path may be created manually or by use of the Edit
Layer of the Adobe PDF Library. If created with the Adobe PDF Library, the pointer returned by
PDEPathGetData is sufficient for this call.
NOTE: The length returned by that call is the number of entries in the list, not the
size in bytes of the list.
dlpdfcontentrect
This procedure marks a rectangle in the content. It will be located such that its lower left hand corner is at
(X,Y); it will be Width wide, and Height high. Width and Height may not be specified as zero but may
be specified as negative numbers, which results in flopping the rectangle.
dlpdfcontentline
This procedure will mark a line in the content. The line will extend from (X1,Y1) to (X2,Y2).
dlpdfcontentarc
This procedure is included as an aid in transitioning from PostScript to PDF. It will draw an arc centered
at (X1, Y1), at a radius of Radius, from Angle1 to Angle2, counter-clockwise, where the angles are
considered to be in degrees.
dlpdfcontentarcn
This procedure is included as an aid in transitioning from PostScript to PDF. It will draw an arc centered
at (X1, Y1), at a radius of Radius, from Angle1 to Angle2, clockwise, where the angles are considered
to be in degrees.
dlpdfcontentarcto
This is a convenience method to mimic the PostScript ArcTo operator. It will locate the intersections of
the line (X1,Y1)->(Xint, Yint), and (X2,Y2)->(Xint, Yint), and draw an arc of the specified radius
tangent to those two lines. The line segment from (X1,Y1) to the arc will be drawn. Unlike the PostScript
ArcTo operator, the segment from the tangent to (X2,Y2) will also be drawn.

Working with Content 8.7
dlpdfcontentpieslice
This procedure is included as an aid in graph construction. It will draw a pie slice, centered at (X1,Y1), at
a radius of Radius, from Angle1 to Angle2, counter-clockwise, where the angles are specified in
degrees.
dlpdfcontentpieslicen
This procedure is included as an aid in graph construction. It will draw a pie slice, centered at (X1,Y1), at
a radius of Radius, from Angle1 to Angle2, clockwise, where the angle is specified in degrees.
dlpdfcontentcircle
This procedure is included as an aid in transitioning from PostScript to PDF. It will draw a circle centered
at (X1,Y1), at a radius of Radius.
dlpdfcontentellipse
This procedure is included as an aid in transitioning from PostScript to PDF. It will draw an ellipse
centered at (X1,Y1), at a vertical radius of RadiusV and a horizontal radius of RadiusH.
Paths
Paths are created in the context of a document and represented as a structure, DLPDFPATH.
dlpdfpathcreate
Used to construct a path, this method accepts no parameters. It will return a pointer to DLPDFPATH or
raise an exception indicating that no memory is available.
dlpdfpathdestroy
Used to destroy, this method accepts a pointer to a DLPDFPATH structure and will return nothing. It will
raise the exception Bad Parameter if the pointer is not valid.
dlpdfpathclear
Used to reset a path, this method sets the current position to UNSET, the matrix to UNITY, and removes
any path segment present. It will not deallocate the array used to hold the path, however, since its primary
purpose is to lower the overhead associated with allocation and deallocation. It will raise the exception
Bad Parameter if it is called with a NULL pointer.

8.8 DLI Implementation and Reference Guide
dlpdfpathcurrentx
This method will return the current X position as an ASFixed integer.
dlpdfpathcurrenty
This method will return the current Y position as an ASFixed integer.
dlpdfpathsize
This method will return the current size of the path array (as a count of ASFixed integers) as an integer.
dlpdfpatharray
This method will return a pointer to the first member of the array of ASFixed integers, which is the path.
Appending Line Segments to an Existing Path
The following methods append line segments to an existing path. Each of these accepts a pointer to a path
as the first parameter, and may or may not have additional parameters describing the line segment to be
built. These methods will return nothing, but may raise an exception if the parameters are not properly
formed.
dlpdfpathaddline
This method accepts three parameters:
• The first is a pointer to the path.
• The second is the absolute Xposition.
• The third is the absolute Yposition.
A line will be drawn from the current position to the specified new position. If the current position is the
same as the new position, no line segment will be added to the path, and no notice will be given
(Optimizing). The current position following this command will be the specified position.

Working with Content 8.9
dlpdfpathaddliner
This methods accepts two parameters, the coordinates of the destination to draw to:
• The first is the distance from the current Xposition to the specified Xposition.
• The second is the distance from the current Yposition to the specified Yposition.
A line will be drawn from the current position to the specified new position. If the distances specified are
both zero, no line segment will be added to the path and no notice will be given (Optimizing). The
position following this command will be the position derived by applying the X and Y offsets to the prior
position.
dlpdfpathaddmove
This method accepts two parameters, the coordinates of the destination to move to:
• The first is an Xposition relative to the current context.
• The second is a Yposition relative to the current context.
The current position will be moved to the specified position without adding a stroked line. If the current
position is the same as the specified new position, no line segment will be added to the path, and no notice
will be given (Optimization). The position following this command will be the specified position.
dlpdfpathaddmover
This method accepts two parameters:
• The first is an Xposition relative to the current context.
• The second is a Yposition relative to the current context.
The current position will be moved to the specified position without adding a stroked line. If the current
position is the same as the specified new position, no line segment will be added to the path, and no notice
will be given (Optimization). The position following this command will be the specified position.

8.10 DLI Implementation and Reference Guide
dlpdfpathaddarc
This method accepts six parameters:
• The first is a pointer to the path.
• The second is an Xposition of the arc center point.
• The third is the Yposition of the arc center point.
• The fourth is the radius of the arc.
• The fifth is the start angle (where zero is directly to the right of center) where the arc is to begin.
• The sixth is the end angle where the arc is to end.
If the current position does not coincide with the position defined by X1, Y1, Radius and Start
Angle, then a straight line segment will be added from the current position to this point. A smooth curve
of the specified radius will be drawn from that specified point counter-clockwise to the point specified
by X1, Y1, Radius, End Angle. The current position will be set to that ending point. If the starting and
ending points specify the same angle, a full circle will be drawn. The position following this command will
be the specified position.
dlpdfpathaddarcn
This method accepts six parameters:
• The first is a pointer to the path.
• The second is an Xposition of the arc center point.
• The third is the Yposition of the arc center point.
• The fourth is the radius of the arc.
• The fifth is the start angle (where zero is directly to the right of center) where the arc is to begin.
• The sixth is the end angle where the arc is to end.
If the current position does not coincide with the position defined by X1, Y1, Radius and Start
Angle, then a straight line segment will be added from the current position to this point. A smooth curve
of the specified radius will be drawn from that specified point clockwise to the point specified by X1,
Y1, Radius, End Angle. The current position will be set to that ending point. If the starting and ending
points specify the same angle, a full circle will be drawn. The position following this command will be the
specified position.

Working with Content 8.11
dlpdfpathaddarcto
This method accepts six parameters:
• The first is a pointer to the path.
• The second is an Xposition of the intersection of tangents.
• The third is the Yposition of the intersection of tangents.
• The fourth is the Xposition of a point defining the second tangent.
• The fifth is the Yposition of a point defining the second tangent.
• The sixth is the radius of the arc.
The two lines (CurrX, CurrY)->(X1,Y1) and (X2,Y2)->(X1,Y1) are joined by an arc of radius (R). The
line segment from the current position to the start of the arc is drawn, followed by the arc itself. The line
segment from the end of the arc to the point X2,Y2 is not drawn. The position following this command
will be the intersection of the arc with the line (X2,Y2)->(X1,Y1). If the two lines are colinear, a straight
line segment is drawn from current position to (X1,Y1), which then becomes the current point.
dlpdfpathaddelliparc
This method accepts seven parameters:
• The first is a pointer to the path.
• The second is an Xposition of the arc center point.
• The third is the Yposition of the arc center point.
• The fourth is the horizontal radius (HRad) of the ellipse defining an arc segment.
• The fifth is the vertical radius (VRad) of the same ellipse. The HRad and VRad functions support
creating arc segments from an elliptical shape, instead of a circular shape as described in
dlpdfpathaddarc. If the same horizontal and vertical radii are passed to this function, it behaves
identically to dlpdfpathaddarc.
• The sixth is the start angle (where zero is directly to the right of center) where the arc is to begin.
• The seventh is the end angle where the arc is to end. If the current position does not coincide with
the position defined by X1, Y1, Radius and Start Angle, then a straight line segment will be added
from the current position to this point. A smooth curve of the specified radius will be drawn from
that specified point counter-clockwise to the point specified by X1, Y1, Radius and End Angle. The
current position will be set to that ending point.
If the starting and ending points specify the same angle, a full circle will be drawn. The position following
this command will be the specified position.

8.12 DLI Implementation and Reference Guide
dlpdfpathaddelliparcn
This method accepts seven parameters:
• The first is a pointer to the path.
• The second is an Xposition of the arc center point.
• The third is the Yposition of the arc center point.
• The fourth is the horizontal radius (HRad) of the arc.
• The fifth is the vertical radius (VRad) of the arc. The HRad and VRad support drawing elliptical arc
segments.
• The sixth is the start angle (where zero is directly to the right of center) where the arc is to begin.
• The seventh is the end angle where the arc is to end. If the current position does not coincide with
the position defined by X1, Y1, Radius and Start Angle, then a straight line segment will be added
from the current position to this point.
A smooth curve of the specified radius will be drawn from that specified point clockwise to the point
specified by X1, Y1, Radius and End Angle. The current position will be set to that ending point. If the
starting and ending points specify the same angle, a full circle will be drawn. The position following this
command will be the specified position.
dlpdfpathaddelliparcto
This method accepts seven parameters:
• The first is a pointer to the path.
• The second is the Xposition of the intersection of tangents.
• The third is the Yposition of the intersection of tangents.
• The fourth is the Xposition of a point defining the second tangent.
• The fifth is the Yposition of a point defining the second tangent.
• The sixth is the horizontal radius (HRad) of the arc.
• The seventh is the vertical radius (VRad) of the arc.
The HRad and VRad support drawing elliptical arc segments. The two lines (CurrX,CurrY)->(X1,Y1)
and (X2,Y2)->(X1,Y1) are joined by an arc of radius (R). The line segment from the current position to
the start of the arc is drawn, followed by the arc itself. The line segment from the end of the arc to the
point X2,Y2 is not drawn.
The position following this command will be the intersection of the arc with the line (X2,Y2)->(X1,Y1). If
the two lines are colinear, a straight line segment is drawn from the current position to (X1,Y1), which
then becomes the current point.

Working with Content 8.13
dlpdfpathaddcurve
This method accepts seven parameters:
• The first is a pointer to a path.
• The second and third are the X and Y positions of a point which will be Control Point 1.
• The fourth and fifth are the X and Y positions of a point which will be Control Point 2.
• The sixth and seventh are the X and Y positions of a point which will be the end point of the curve.
A smooth curve (a cubic Bézier) will be drawn from the current position to the end position, under
direction of the two control points. The current position will be the end position of the line at completion
of this operation. If the end position specified is identical to the current position, no segment will be
appended, and no notice will be given (Optimization).
dlpdfpathaddcurver
This method accepts seven parameters:
• The first is a pointer to a path.
• The second and third are the distance from current point to the X and Y positions of a point which will
be used for Control Point 1.
• The fourth and fifth are the distance from current point to the X and Y positions of a point which will
be Control Point 2.
• The sixth and seventh are the distance from the control point to the X and Y positions of a point which
will be the end point of the curve.
A smooth curve (A cubic Bézier) will be drawn from the current position to the end position, under
direction of the two control points. The current position will be the end position of the line at completion
of this operation. If the end position specified is identical to the current position, no segment will be
appended, and no notice will be given (Optimization).
dlpdfpathaddcurvev
This method accepts five parameters:
• The first is a pointer to a path.
• The second and third are the X and Y positions of a point which will be used for Control Point 2.
• The fourth and fifth are the X and Y positions of the end point of the curve.
A smooth curve (a cubic Bézier) will be drawn from the current position to the end position, under
direction of the two control points. Control Point 1 is the current position. The current position will be
the end position of the line at completion of this operation. If the end position specified is identical the
current position, no segment will be appended, and no notice will be given (Optimization).

8.14 DLI Implementation and Reference Guide
dlpdfpathaddcurvey
This method accepts five parameters:
• The first is a pointer to a path.
• The second and third are the X and Y positions of a point which will be used for Control Point 1.
• The fourth and fifth are the X and Y positions of the end point of the curve.
A smooth curve (a cubic Bézier) will be drawn from the current position to the end position, under
direction of the two control points. Control Point 2 is the end position. The current position will be the
end position of the line at completion of this operation. If the end position specified is identical to the
current position, no segment will be appended, and no notice will be given (Optimization).
dlpdfpathaddrect
This method accepts five parameters:
• The first is a pointer to a path.
• The second and third are the X and Y positions of a point which will be one corner of the box.
• The fourth will be the width of the box.
• The fifth will be the depth of the box.
If the specified position is not the current position, a MoveTo to the specified position will be made. A
rectangle will be added to the path, starting at the specified position and proceeding upward (unless the
depth is negative) and to the right (unless the width is negative). The end position after this operation
will be the specified position.
If the width and depth are both zero, no segment will be appended, but the current position will still be
updated.
dlpdfpathaddclose
This method accepts no operands. It will append to the path a close path operator and leave the
current position as the first specified position in the path.
dlpdfpathsetmatrix
This method accepts a pointer to a path and a pointer to a matrix. The specified matrix will be
concatenated (i.e. applied) to the matrix of each container in which this path is drawn, affecting all on the
current path. This allows the user complete and flexible control of the shape drawn by the path. If the
pointer to the path or the matrix is NULL, a genErrBadParm exception will be raised.

Working with Content 8.15
dlpdfmatrixrotate
This function will modify the specified matrix so as to effect counter-clockwise rotation of any marks
drawn via this matrix. Angle is an angle in degrees and fractions of degrees.
Patterns
Patterns are created in the context of a document, and represented by the structure DLPDFPATTERN.
They contain a content block, whose contents become one tile of the pattern. The size, shape, and location
of a given tile can be modified by the specified matrix.
The size of the tile is set by the BBox (Bounding Box) parameter.
Spacing between adjacent tiles is set by the Xstep and Ystep parameters. Tiles may overlap, be placed
adjacent, or be placed with space between them.
The TileType parameter may be 1, 2 or 3, corresponding to the Adobe TileType parameter (see the
Portable Document Format Reference Manual).
The Colored parameter, if true, indicates that the pattern contains its own color specifications which
should be used in place of any fill/stroke color specification. If the Colored parameter is FALSE, it
indicates that the fill/stroke specification should be used for color.
dlpdfpatterncreate
This creates a patterned color space, and returns a pointer to that space. The pointer may be used in
dlpdfcontentusefillpattern or dlpdfcontentusestrokepattern to apply this colored
pattern to all following material. All patterns will be destroyed and their handles invalidated in the
destruction of the document that contains them.
dlpdfcontentusefillpattern
See dlpdfpatterncreate above. Note that this call with a NULL pointer to a pattern will turn off
patterned color space.
dlpdfcontentusestrokepattern
Similar to dlpdfcontentusefillpattern above.

8.16 DLI Implementation and Reference Guide
Referencing Predefined Structures
These calls permit the inclusion in content of complex pre-built structures. These structures may be
arbitrarily positioned, scaled and rotated when placed into the content.
dlpdfcontentreferenceform
This procedure places a copy of a Form into the current content. All of the markings in the Form will
appear. The lower left hand corner of the Form will be positioned at (X, Y). The Form will be rotated
counter-clockwise as per rotate and scaled as per ScaleX and ScaleY.
dlpdfcontentreferenceimage
This procedure places a copy of the referenced image into the current content. It will be placed so as to
align its lower left hand corner with (X, Y), will be scaled as per ScaleX and ScaleY, and rotated as per
Rotate.
The Scale Factors will determine the resulting size of the image. You need to know the original image
resolution and its intended size in order to determine whether a Scale Factor on either axis is required. In
DLI v2.2.5 and higher, the dlpdfimagegetsize method can retrieve image sizing data for you, and
dividing the intended print size by the file size for each dimension (delivered by dlpdfimagegetsize)
will yield a Scale Factor ratio which dlpdfcontentreferenceimage will use to calculate the final
output image size.
The typical scaling calculation using values returned by dlpdfimagegetsize would be to divide the
intended print size by the image size on each axis; e.g.
dlpdfcontentreferenceimage(Content, Image,
Int32ToFixed(72), Int32ToFixed(92), 0,
ASFixedDiv(xPoints, Int32ToFixed(xRasters)),
ASFixedDiv(yPoints, Int32ToFixed(yRasters)));
An image in which each pixel of each raster line represents one PDF unit of output will return the same
values for both image dimension (xRasters and yRasters) and print size (xPoints and yPoints),
and thus a Scale Factor of 1 on both axes.
dlpdfimagegetsize
The Scale Factors specified in dlpdfcontentreferenceimage will determine the resulting size of the
image. This method gives you the image information necessary to calculate those values, dividing the
intended print size by the file size for each dimension. This yields a Scale Factor ratio which
dlpdfcontentreferenceimage uses to calculate the final output image size.

Working with Content 8.17
Associating Content to Page
The dlpdfcontenttopage call places the content onto a page. Once made, the content is no longer
accessible via the DLI Package, and the pointer to the content structure is no longer valid.
dlpdfcontenttopage
This procedure will make the markings placed into content a part of the specified page. Following this
call, the content structure no longer exists: pointers to it are then invalid and should no longer be used.
Adding Comments to Content Elements
dlpdfcontentcomment
This method will insert the specified text string, in the order provided, into the content elements. This
string will always be placed on a separate line, preceded by "%" to mark it as a comment. The comment
text must not contain a newline character, unless the character following that newline is a percent sign
("%"). The content element must be valid; the comment pointer must point at a valid non-NULL, non-zerolength
string.

8.18 DLI Implementation and Reference Guide

9
Working
with Forms
This chapter explains Forms XObjects and defines the
calls available.
9.1

9.2 DLI Implementation and Reference Guide
Overview of Forms
Forms, in this sense, are predefined content that may be placed into a document many times. A form’s
content will be included in the PDF or PostScript document only once, but it may be imaged in the
document any number of times. Defining forms is a powerful means of reducing the size of a document. It
also considerably reduces the time needed to create a document.
Forms Structure
A form is represented in DLI as a structure, DLPDFFORM. Any number of forms may be defined, on a perdocument
basis: if the same form is needed in multiple documents, multiple copies of it must be created.
Forms are tracked within the document structure, and all forms for a document are destroyed when the
document is destroyed. Pointers to forms become invalid when the document is destroyed and must not be
used after that time.
The content of a form may be arbitrarily complex. Forms may contain images as well as other forms.
Form Calls
There are only a few calls which involve forms.
dlpdfformcreate
This function will create a new form in the document specified as Doc, with the content previously placed
into the container Content.
The form will be considered to be of the size specified in BBox. This is an Adobe PDF Library ASFixed
Rectangle, whose contents are assumed to be in points. The Bounding Box need not be located at (0,0);
however, it must have a positive Width and Depth. The content block used to create a form is destroyed
in the form’s creation, and any handles to it become invalid after that point.
dlpdfcontentreferenceform
Reference to a form in content is made via dlpdfcontentreferenceform.

Working with Forms 9.3
dlpdfformdestroy
This destroys the named form, releasing its resources. It invalidates the form handle.

9.4 DLI Implementation and Reference Guide

10
Displaying
Line Drawings
Line drawings are pictures made up of lines connecting
specified points. These lines may be stroked (covered in a
fixed width and colored marking) or filled (the space
defined by the inside of the lines is painted with a defined
color or pattern). The areas defined by such a set of lines
need not be contiguous.
10.1

10.2 DLI Implementation and Reference Guide
Overview
This chapter contains calls used to draw lines within an area, and fill or stroke those lines while producing
commonly-used shapes. Common to all of these calls is the PDEGraphicState, which defines line
drawing parameters (Line Width, Join, Miter, etc.) and the Paint operator, which defines how the
path defined should be treated (kPDEStroke, kPDEFill, kPDEEoFill, or a combination of these).
There are two color definitions within the PDEGraphicState:
• Fill Color will be used with the operators kPDEFill or kPDEEoFill
• Stroke Color will be used with the operator kPDEStroke.
All of the fields within PDEGraphicState will be honored.
NOTE: Stroking will colorize to a given width, while filling will colorize within the
borders. To draw lines, use stroking to give the line a width.
Functions are provided in this chapter to produce commonly-used shapes. The general path operator
dlpdfcontentpath can image arbitrarily complex shapes.
All of the coordinates and sizes specified below are considered to be in points. The content element in
which these are placed may translate, scale, or rotate the image.
Approaches to Line Drawing
There are two approaches to line drawing supported by DLI. The first uses a simple interface to construct
or fill and stroke a structure. The second permits the user to construct an arbitrarily complex collection of
markings, and then place that collection within any number of content structures.

Displaying Line Drawings 10.3
Directly-Drawn Methods
In general, the directly-drawn methods are the simplest to use, and the best choice for operations like
underlining, page rules and area borders. This collection of directly-drawn structures is derived from the
operators for PostScript graphics, and common usage of those operators.
All of these operators have their first three parameters in common. These are:
• The container in which the structure will be drawn
• The current state in which all parameters are used
• The Painting operator, which defines how the path defined should be treated. It must be one of the
following, or a combination of these:
• kPDEStroke — stroke the lines of the structures
• kPDEFill — fill the areas defined by the lines
• kPDEEOFill — stroke the area contained an odd number of times by the area.
In the case of these structures, there can be no multiple containment, and hence EOFill and Fill will
have the same results.
All of the methods have additional parameters, specifying the location and size of the structure drawn.
These will be different for each structure, but will always be ASFixed values.
If the content area in which these structures are drawn is itself distorted (i.e. its AreaMatrix is not the
unity matrix; see the discussion of containers and matrix manipulation beginning with “What are
Containers?” on page 7.2), then the structures drawn will be positioned and shaped to reflect that
distortion.
dlpdfcontentrect
This will draw a rectangle. The four parameters are ASFixed values reflecting X position, Y
position, Width and Depth. If Width and Depth are positive numbers, the rectangle will be
positioned with its lower left hand corner at the position (X,Y).
dlpdfcontentline
This will draw a line. There are four parameters, reflecting ASFixed values for (X,Y) start and (X,Y) end.
NOTE: The Fill operator is meaningless with this structure.

10.4 DLI Implementation and Reference Guide
dlpdfcontentarc
This will draw a curved line.
• The first two parameters are ASFixed values reflecting the (X,Y) position of the center of the circle of
which this arc is a portion.
• The third parameter is the ASFixed value of the Radius of that circle.
• The fourth and fifth parameters are the Start Angle and End Angle at which the arc starts and
ends respectively.
The arc is drawn counter-clockwise from Start Angle to End Angle. The angles are specified in
degrees, with Zero degrees pointing to the right. If the start and end angles are coincident, a full circle will
be drawn.
dlpdfcontentarcn
This is identical to the previous, except that the arc is drawn clockwise.
dlpdfcontentarcto
This is an implementation of the PostScript arcto command, included as a convenience to output drivers
which currently support PostScript.
• The first two parameters are the ASFixed values of the (X,Y) position of the Line Start.
• The third is the ASFixed value of the Radius of the Arc Segment.
• The fourth and fifth are the ASFixed values of the (X,Y) position of the Intersection.
• The sixth and seventh are the ASFixed value of the (X,Y) position of the Line End.
NOTE: This implementation will draw the line segment from the end of the arc to
the end position, which would not be drawn in PostScript.
dlpdfcontentpieslice
This method was included as a convenience operator for the construction of pie charts.
• The first two parameters are the ASFixed values for (X,Y) of the center of the pie the slice is taken
from.
• The third is the ASFixed value for the Diameter of the pie slice.
• The fourth and fifth are the Start Angle and End Angle, in degrees, of the pie slice.
The angles are counter-clockwise from right. The arc of the pie will be drawn counter-clockwise. If the
angles are coincident, a full circle will be drawn.

Displaying Line Drawings 10.5
dlpdfcontentpieslicen
This is identical to dlpdfcontentpieslice above, except that the arc will be drawn clockwise from
the Start Angle to the End Angle.
dlpdfcontentcircle
This method will draw a circle whose center is the first two parameters and whose radius is the third
parameter.
dlpdfcontentellipse
This method will draw an ellipse whose center is the first two parameters, the ASFixed value of the X
Radius is the third parameter, and the ASFixed value of the Y Radius is the fourth parameter.
dlpdfcontentpath
This method will draw an arbitrary path. The path is an array of ASFixed values, constructed according
to the PDF rules for path construction. These can be found in the Adobe PDF Library API Reference
Manual under PDEPathAddSegment.
The path may have been constructed via PDEPath operators, or constructed manually.
NOTE: If constructed via PDEPath, then PDEPathGetData must be used to
obtain the array and array size used in this call.
The first parameter is a pointer to an array of ASFixed; the second is a count of the number of entries in
that array.
Path Drawing Sample
In an accompanying codesamples folder you should find a sample file entitled line drawing using
draw fixed structure.txt. This sample source file will create a document with one page,
containing a square whose lower left corner is one inch above the bottom and one inch right of the left
edge of the page. The square will be red, edged in black. From outer edge to outer edge, the square will be
74 points wide and tall.

10.6 DLI Implementation and Reference Guide
Path Drawing Methods
The directly-drawn shapes are useful for a great number of graphics, but they do not permit filling of
complex arbitrary shapes without the construction of a path. For that reason, a second set of drawing
operators was added. These operators simply construct and draw a path, which may be arbitrarily
complex. It may also be disjointed.
The DLPDFPATH structure will contain a path of any size, allocating additional memory as needed. Path
construction is via methods which add segments to the existing path. These methods seek to include both
the PDF and PostScript graphics operators. When completed, the path may be added to a content area.
The path is not destroyed when imaged and may be reused any number of times. The DLPDFPATH
structure also includes a provision for a CTM Matrix, which may be used to transform the position and
appearance of the path.
Within the path, a current point is maintained. This will be undefined initially, or after a
dlpdfpathaddclose, and will be the end point of the segment added at all other times. Some operators
require that the current point be established prior to adding a segment of that type. Others will add a
straight line segment drawn from the current position to the start of the defined segment prior to a
segment. This behavior mimics the drawing mechanism in PostScript.
The first parameter of all of these methods, except dlpdfpathcreate and dlpdfcontentdrawpath,
is a pointer to a valid DLPDFPATH structure.
dlpdfpathcreate
This method will return a pointer to a new DLPDFPATH structure. The path’s contents will be empty, its
current position will be undefined, and its matrix will be set to the unity matrix. This structure will persist
until specifically deleted by the dlpdfpathdestroy method.
The DLPDFPATH is not specific to a document or content structure. It may be shared across many
documents and placed within any number of content structures.
dlpdfpathclear
This method will remove all content from an existing DLPDFPATH structure and restore it to the state it
was in following the call to dlpdfpathcreate. It is included to lower the overhead of creating many
paths.
dlpdfpathdestroy
This method will destroy a DLPDFPATH structure and free all resources that it used.

Displaying Line Drawings 10.7
dlpdfpathaddmove
This method will change the current position of a DLPDFPATH structure without drawing a line. It may be
used to establish the starting point of a path or to add a disjunction to an existing path. It accepts two
operators, an X and a Y position, as ASFixed values. The current position following this method will be
the specified (X,Y) position.
dlpdfpathaddmover
This method also sets the current position, but sets it relative to the existing current position. If there is no
current position, this method will raise an exception (genErrBadParm). This method accepts two
parameters, an X and a Y displacement, as ASFixed values. The current position following this method
will reflect the application of the X and Y displacements.
dlpdfpathaddline
This method draws a line from the current position to the position specified by its two parameters, X and
Y position as ASFixed values. If there is no current position established, this method will raise an
exception (genErrBadParm). The current position following this method is the specified (X,Y) position.
dlpdfpathaddliner
This method also draws a line segment, drawn from the current position to a new position, specified by X
and Y displacement as ASFixed values. If there is no current position established, this method will raise
an exception (genErrBadParm). The current position following this method will reflect the application
of the X and Y displacements.
dlpdfpathaddarc
This method will append an arc segment to the current path. The parameters specify an (X,Y) position, in
ASFixed values, of the center of the arc, a Radius as an ASFixed value, and two angles in degrees as
ASFixed angles.
If there is a current position, a line segment will be added from the current position to the start angle of
the arc. If there is no current position, a move to the start angle of the arc will be appended to the path.
The arc will be drawn counter-clockwise from the start angle to the end angle. If the angles are coincident,
a full circle will be drawn. The angles will be interpreted such that zero degrees is pointing right.
After completion, the position of the end of the arc will be the current position.

10.8 DLI Implementation and Reference Guide
dlpdfpathaddarcn
This method is identical to dlpdfpathaddarc, except that the arc will be drawn clockwise.
dlpdfpathaddarcto
This method will draw a straight line segment from the current position toward the X and Y coordinates
specified by the first two parameters. This line will terminate at the intersection of an arc connecting this
line to a second line, drawn from the first specified (X,Y) to the second (X,Y) specified by the third and
fourth parameters, at a Radius specified by the fifth parameter.
Xint1/
Yint1
X1/Y1
Xint2/
Yint2
Current Position
X2/Y2
NOTE: The straight segment from Xint2/Yint2 -> X2/Y2 is not drawn. The
current position is set to Xint2/Yint2.
If there is no current position when this method is called, an exception (genErrBadParm) will be raised.
dlpdfpathaddelliparc
This method will append an arc segment to the current path. The parameters specify an (X,Y) position, as
ASFixed values, of the center of the arc, a Horizontal Radius and Vertical Radius as ASFixed
values, and two angles in degrees as ASFixed angles.
The Horizontal Radius and Vertical Radius values create arc segments from an elliptical shape,
instead of the circular arc segments of dlpdfpathaddarc. If the same horizontal and vertical radii are
passed to this function, it behaves identically to dlpdfpathaddarc.
If there is a current position, a line segment will be added from the current position to the start angle
of the arc. If there is no current position, a move to the start angle of the arc will be appended to the
path. The arc will be drawn counter-clockwise from the start angle to the end angle. If the angles
are coincident, a full circle will be drawn. The angles will be interpreted such that zero degrees is pointing
right.
After completion, the position of the end of the arc will be the current position.

Displaying Line Drawings 10.9
dlpdfpathaddelliparcn
This method is identical to dlpdfpathaddelliparc, except that the arc will be drawn clockwise.
dlpdfpathaddelliparcto
This method will draw a straight line segment from the current position toward the X and Y coordinates
specified. This line will terminate at the intersection of an arc connecting this line to a second line, drawn
from the first specified (X,Y) to the second (X,Y) specified, at a specified Horizontal Radius and
Vertical Radius.
dlpdfpathaddcurve
This is the first of the four methods which add a spline, or cubic Bézier curve, to the path.
All Bézier curves consist of four points:
Xctrl1/
Yctrl1
Xend/
Yend
Xstart/
Ystart
Xctrl2/
Yctrl2
This method (as well as the following three) uses current position as the starting point of the curve. If no
starting point is specified, the method will raise an exception (genErrBadParm).
The first two parameters of this method are the position of Control Point 1, the second two parameters
are the position of Control Point 2, and the last two parameters are the position of the end point of the
curve.
Following this method, the current position will be the end point of the curve.
dlpdfpathaddcurver
This method is identical to dlpdfpathaddcurve, except that the positions are expressed as relative
distances from the current point, not absolute distances from the origin.

10.10 DLI Implementation and Reference Guide
dlpdfpathaddcurvev
This method is identical to dlpdfpathaddcurve, except that both the start and first control point are
assumed to be the current position.
Xend/
Yend
Xstart/
Ystart
Xctrl1/
Yctrl1
Xctrl2/
Yctrl2
dlpdfpathaddcurvey
This method is identical to dlpdfpathaddcurve, except that the second control point is assumed to be
the ending position.
Xctrl1/
Yctrl1
Xstart/
Ystart
Xend/
Yend
Xctrl2/
Yctrl2
dlpdfpathaddrect
This method will draw a rectangle. The first two parameters specify the (X,Y) position of a corner, and the
next two specify the width and depth of the rectangle. A positive width will draw to the right, and a
positive depth will draw upward.
Current position need not be set before this method is called, and current position will be set to the
specified (X,Y) position after it is used.

Displaying Line Drawings 10.11
dlpdfpathaddclose
This method will append a straight line segment from the current position to the start of the first element
in the path. If a current position is not set, it will have no effect.
Following this method, the current position will be unset.
NOTE: This does not need to be the last segment of a path. Additional, disjoint
segments may be set.
dlpdfcontentdrawpath
This method is used to add a drawn path to content.
• Its first element is the DLPDFCONTENT onto which this path is to be drawn.
• Its second parameter is the DLPDFPATH structure to be drawn.
• Its third parameter is a pointer to a PDEGraphicState structure. This structure contains definitions
of colors to be applied, and line sizes and parameters to be used when drawing a path.
• The fourth and last parameter is the Path Painting operator. This must be one of
— kPDEStroke
— kPDEFill
— kPDEEoFill
— kPDEStroke | kPDEFill
— kPDEStroke | kPDEEoFill
Path Drawing Sample
In an accompanying codesamples folder you should find a sample file entitled drawing a
rectangle and ellipse in path operators.txt. This program sample shows the use of an
arbitrarily complex path while creating a rectangle with an ellipse embedded within it.

10.12 DLI Implementation and Reference Guide
Transformation Matrices
A Transformation Matrix can be applied to the path as a whole when it is drawn in order to resize or
reposition it. This matrix will be concatenated with the matrix of the container in which the path is
drawn.
Matrix Arguments
The matrix consists of six ASFixed values (a, b, c, d, h and v):
• Values a and b control the movement in X and Y coordinates produced by a movement in X.
• Values c and d control the movement in X and Y coordinates of a movement in Y.
• Values h and v are horizontal and vertical offsets to the position of the drawing (positive values are up
and right).
dlpdfpathsetmatrix
This method will set a matrix which will be applied to the path as a whole when it is drawn. This matrix
will be concatenated with the matrix of the container in which the path is drawn. The method accepts a
single parameter, a pointer to an ASFixedMatrix.
Matrix Translations
The unity matrix ([1, 0, 0, 1, 0, 0]) causes a 1 unit movement in X to be a 1 unit movement in X
and a zero unit movement in Y; a 1 unit movement in Y becomes a 0 unit movement in X and a 1 unit
movement in Y.
More precisely:
RealX = X * a + Y * c + h
RealY = X * b + Y * d + v
Hence:
• the matrix [1 0 0 -1 0 0] will invert the figure drawn
• the matrix [-1 0 0 1 0 0] will mirror-image the figure
• the matrix [.707 .707 -.707 .707 0 0] will rotate it 45 degrees
Image Translation
Translation is the simple movement of the image, and is accomplished by modifying h and/or v. These
values are interpreted in the un-transformed space. For more details, please see section 4.2.2, "Common
Transformations," in the Portable Document Format Reference Manual.

Displaying Line Drawings 10.13
Image Rotation
A matrix may be rotated by using the method dlpdfmatrixrotate. This method accepts a pointer to a
matrix, and transforms it to accomplish a rotation of the specified angle (in degrees, as an ASFixed
value, counter-clockwise).
Image Shearing and Scaling
Shearing of an image may be accomplished by modifying b or c only. Scaling may be accomplished by
modifying a and/or d only.
CAUTION: Be sure to scale before rotating, if you are doing both.

10.14 DLI Implementation and Reference Guide
Graphic State and Line Drawing
This is a brief discussion of the graphic state parameters. For a fuller explanation, please see section 4.3,
"Graphics State," in the Portable Document Format Reference Manual. The fields listed are components
of the PDEGraphicState structure as defined by the Adobe PDF Library SDK.
fillColorSpec
This is the specification of color to be used when kPDEFill or kPDEEoFill is specified as a path, or
when a structure is drawn. Refer to “Library Color Descriptions” on page 12.2 for a full discussion of
setting this value.
NOTE: If a pattern has been set for the container in which this figure is drawn,
that pattern may be used in place of, or in addition to, this color specification.
strokeColorSpec
This is the specification of color to be used when kPDEStroke is specified as a path, or when a structure
is drawn. Refer to “Library Color Descriptions” on page 12.2 for a full discussion of setting this value.
NOTE: If a pattern has been set for the container in which this figure is drawn,
that pattern may be used in place of, or in addition to, this color specification.
lineWidth
This is an ASFixed value in scaled units. Note that a DLPDFPATH matrix, which specifies scaling, will
affect this value. This value must be set specifically when the graphic state structure is created.
lineJoin
• A value of zero for this parameter continues the joined lines to a point.
• A value of 1 rounds over the join at lineWidth Radius.
• A value of 3 butts the line ends and fills the notch with stroke color, causing it to be beveled.
If the value is 0, and the extension of the line to a point exceeds the miterLimit, then the line will be
beveled as with a value of 3.

Displaying Line Drawings 10.15
lineCap
• A value of zero produces butt-ended lines, ending at the end point of the segment.
• A value of 1 produces round-ended lines, with a diameter equal to lineWidth.
• A value of 2 produces square-ended lines, extending 1/2 line width beyond their end point.
miterLimit
Miter is the shape of the intersection of two lines. This parameter limits the length of a miter as a function
of the line thickness. It is specified as an ASFixed value and must be greater than 1. For more
information, see "Miter Limit" in section 4.3.2 of the Adobe PDF Reference Manual v1.5.
flatness
Controls the amount of error permitted between a path’s ideal position and the actual position in which it
is placed. This is an ASFixed value, between 0 and 100. A value of zero permits the device to use its own
flatness value, and is usually the best choice.
dash
A means of producing dashed, dotted or otherwise broken lines in stroking a path. Note that a patterned
color space should not be used in stroking a path (although it can be), because the result will be the
intersection of the pattern and the path, rather than the pattern following the path.
The dash parameter is a pointer to a PDEDash structure. In essence, this structure allows you to define a
pattern of off/on changes to be used in stroking a line to achieve a wide variety of dashed and dotted lines.
For more information, see "PDEDash" within the Declarations section of the Adobe Acrobat Core API
Reference Manual, and "Line Dash Pattern" in section 4.3.2 of the Adobe PDF Reference Manual.

10.16 DLI Implementation and Reference Guide

11
Image
Display
Images are predefined collections of shapes and colors
which are included into the document as a picture. They
may be as simple as a single bitmap or as complex as a
complete PDF page.
11.1

11.2 DLI Implementation and Reference Guide
Overview
Inclusion of graphics is accomplished in two ways. The first is an image, in the sense of a PDF or
PostScript Image Operator. The second is a Encapsulated PostScript (EPS) file. Note that images included
as EPS will not appear in PDF pages on-screen (e.g. when displayed by Adobe Reader or Adobe Acrobat),
but will appear in both PostScript pages and Adobe PDF PostScript pages. Adobe Normalizer Server, also
available from Datalogics, can be used to distill EPS images to PDF format in order to make EPS sources
visible in PDF output.
The interfaces provided in DLI for images are intentionally very low-level. They presume that any
graphics conversions have already been completed. Public-domain packages for the conversion of graphics
from common formats (PNG, GIF, TIFF, etc.) are readily available and can create data in the form these
interfaces expect.
Graphic Image Structures
DLI manages graphics via the structure DLPDFIMAGE. This structure is used for both image and EPS
data.
There are four functions to create images depending on the format (Bitmap, EPS, PDF, and a convenience
function for several other graphic formats), and one function to use an image
(dlpdfcontentreferenceimage).
NOTE: Encapsulated PostScript (EPS) is not a valid graphic format for PDF. The EPS
function available through DLI will enable you to embed the EPS image in the PDF
document, but it will not be visible until the document is printed. (Adobe
Normalizer, also available from Datalogics, can be used to distill EPS images to PDF
format in order to make EPS sources visible in PDF output.)
Image structures are created on a per-document basis. If the same image is used in multiple documents,
multiple copies of that image must be created. Images are tracked within the document and all images are

Image Display 11.3
destroyed when the document is destroyed. Pointers to images become invalid on document destruction
and must not be used after that time.
A document may contain any number of images. Each image will be included in the document only once,
but may be referenced within that document many times.
The image is considered to be a part of the document, and may not be used in any document other than
the one in which it was created. Images need not be directly destroyed, since they will be destroyed
automatically when the document that contains them is destroyed.
Images are tracked and reused via the ImageName value. The same image data with a different Image
Name is considered a different image. Image data is passed into the creation routines via strings in
memory. These strings may be freed after the call to create the image.
Implementations of DLI on UNIX and Windows include public-domain libraries to convert a number of
common graphic forms into bitmaps usable by PDF.
NOTE: The public-domain graphic-conversion libraries used on Unix and Windows
are not available on OS/390 and OS/400 platforms. Consequently some image
creation procedures are not available under OS/390 and OS/400.
Graphic Image Forms
Predefined images typically fall into one of two major varieties:
• Bitmap Graphic Forms
• Graphical Language Forms
Bitmap Graphic Forms
This is the most basic form of image. It consists of a stream of bits; indications of the number of samples
per line, and the number of lines; a description of the samples (color model, sample size); and a
description of ordering. It may also contain a description of resolution (samples per inch horizontal and/
or vertical). The stream may be compressed, in which case the compression algorithm and parameters
must also be given.
These images may be expressed at various levels, from something as simple as “Here is a bitmap of n lines
by n samples in 1-bit gray scale,” to more-complex references to standards for graphics encoding and
compression (e.g. JPEG/JPG, TIFF, GIF, PNG, etc.). However, the Adobe PDF Library package contains

11.4 DLI Implementation and Reference Guide
no logic to transform bitmaps, so they must all be presented to the Adobe PDF Library in a common
manner.
This excerpt from the graphical image example shows the logic for inserting a raw bitmapped graphic into
a document.
"C" Example: Bitmapped Graphic via dlpdfimagecreatefrombmp
/* Allocate memory to hold the image bitmap */
ImageString = malloc (ImageWidth * ImageDepth);
/* Open read the bitmap, and close the bitmap file */
ImageFile = fopen (ImageName, "rb");
fread (ImageString, 1, ImageWidth * ImageDepth, ImageFile);
fclose (ImageFile);
/* Get the color space DeviceGray as a COS object */
GraySpace = PDEColorSpaceCreateFromName (ASAtomFromString
("DeviceGray"));
PDEColorSpaceGetCosObj (GraySpace, &Color);
/* Create a DLPDFIMAGE object from the bitmap */
Image = dlpdfimagecreatefrombmp (Doc, "Bear", ImageString,
ImageDepth * ImageWidth,
ImageWidth, ImageDepth,
8, Color, FALSE);
/* Free the image string from memory */
free (ImageString);
/* "Paste" the image into the container, centered over the
* red box */
dlpdfcontentreferenceimage (Content, Image,
(fixedFour * 72) - ((Image->BBox.left + Image->BBox.right)/2),
(fixedFour * 72) - ((Image->BBox.top + Image->BBox.bottom)/2),
0, fixedOne, fixedOne);
Graphical Language Forms
These forms of graphics are described via line drawing operators, fill and stroke parameters, and
text. They may also include bitmapped graphics. These forms exist solely in the context of a standard
language definition (e.g. PDF: Portable Document Format; CGM: Computer Graphics Metafile; WMF:
Windows Metafile Format; QuickDraw drawing commands; etc.).

Image Display 11.5
Image Creation Methods
With the exception of PDF, for which this package is eminently suitable, all of the graphic forms must be
converted into a stream of line drawing, imaging and text drawing commands before being used as an
image.
DLI supports creating graphical images from a range of sources via the following methods:
dlpdfimagecreatefrombmp
This method creates a DLPDFIMAGE from a bitmap and user-supplied information.
• Its first parameter is the document of which the image is to be a part.
• Its second parameter is a name to be used to identify this image.
• Its third and fourth parameters are pointers to an array of bytes containing the bitmap and the length of
that bitmap.
• Its fifth parameter is the length of a line in samples.
• Its sixth parameter is the number of lines.
• Its seventh parameter is the size of a sample.
• The eighth parameter is a COS Object which describes the color model used for the image.
• The last parameter is a flag. When TRUE, this object will be embedded in the document each time it is
used. When FALSE, it will be embedded only once.
NOTE: DLI will merge inline all bitmapped images under 500 bytes. However, if
the image is equal to one bitmap, then DLI will automatically set the image as an
imagemask. Please see “Creating Transparent Graphics” on page 11.10
This method assumes that the bitmap is ordered into samples within lines, that the first line presented is
the top of the image, and that the first sample presented is the left edge of the image.
Order of Values within Color Models
The type of color model will determine whether the image contains one value per sample (/DeviceGray
or /Indexed color models), three values per sample
(/DeviceRGB), or four values per sample (/DeviceCMYK).
Each value is assumed to have the number of bits specified in the sample size. For
/DeviceRGB they are assumed to be ordered Red/Green/Blue; for /DeviceCMYK they are assumed to be
ordered Cyan/Magenta/Yellow/Black.

11.6 DLI Implementation and Reference Guide
Image Compression and Filtering
If the document specifies compression, the bitmap will be compressed with Flate compression. If the
document specifies Seven-Bit Safe mode, the bitmap will be filtered via ASCII85 to force it into a seven
bit safe data format.
dlpdfimagecreatefromps
This method will create a EPS pass-through object in the PDF document. The EPS graphic is carried in the
document, but not imaged by the document reader. Extracting the document to PostScript will include the
object, and it will display in PostScript. This option is not generally used, but may be needed on occasion.
This method assumes that the text of the EPS object is present as a string in memory.
• The first parameter is a pointer to a document in which this object is to be created.
• The second is a name to be given to this graphic.
• The third and fourth are pointers to a string containing the EPS text and the length of that string.
• The last parameter is a flag. If it is FALSE, this object will be inserted into the document only once. If it
is TRUE, it will be inserted once for each usage.
This segment of the complete graphics example inserts an EPS pass-through object, which will display a
graphic in the PostScript produced from PDF, but not in the PDF document itself:
Inserting a EPS Image with dlpdfimagecreatefromps
/* Open read the bitmap, and close the PostScript file */
ImageFile = fopen ("Image.eps", "rb");
fseek (ImageFile, 0, SEEK_END);
ImageSize = ftell (ImageFile);
fseek (ImageFile, 0, SEEK_SET);
/* Allocate memory to hold the image */
ImageString = malloc (ImageSize);
fread (ImageString, 1, ImageSize, ImageFile);
fclose (ImageFile);
Image = dlpdfimagecreatefromps (Doc, "Grid", ImageString,
ImageSize, FALSE);
/* "Paste" the image into the container, centered over the
* red box */
dlpdfcontentreferenceimage (Content, Image,
(fixedFour * 72) - ((Image->BBox.left + Image->BBox.right)/2),
(fixedFour * 72) - ((Image->BBox.top + Image->BBox.bottom)/2),
0, fixedOne, fixedOne);

Image Display 11.7
dlpdfimagecreatefrompdf
This method will create an image from a PDF file. The image will be of a single specified page of the image
document.
• The first parameter is a handle for the document in which this image is to be placed.
• The second is the name of the file containing the PDF image page.
• The third and fourth are ASFixed values giving the desired width and depth of the image. If either is 0,
the PDF page's crop box is used to form the DLPDFIMAGE's visible region.
• The fifth and sixth are ASFixed values giving the offset within the image document at which the image
should be displayed, relative to the position at which the image page is set.
• The last parameter is an integer which is used as a page number (starting from 1) to access the image
document and to select the image page displayed.
This segment of the complete DLI Graphics example inserts a PDF image into the document:
Inserting a PDF Image with dlpdfimagecreatefrompdf
/* Open the file and obtain the bounding box of page 0 */
{
PDDoc
pdDoc;
PDPage
pdPage;
ASFixedRect
BB;
/* Open the document */
pdDoc = PDDocOpen ("Image.pdf", NULL, NULL, TRUE);
pdPage = PDDocAcquirePage (pdDoc, 0);
PDPageGetBBox (pdPage, &BB);
PDPageRelease (pdPage);
PDDocClose (pdDoc);
Image = dlpdfimagecreatefrompdf (Doc, "Image.pdf",
BB.right - BB.left,
BB.top - BB.bottom,BB.left,BB.bottom,1);
/* "Paste" the image into the container, centered over the
* red box */
dlpdfcontentreferenceimage (Content, Image,
(fixedFour * 72) - ((Image->BBox.left + Image->BBox.right)/2),
(fixedFour * 72) - ((Image->BBox.top + Image->BBox.bottom)/2),
0, fixedOne, fixedOne);
}

11.8 DLI Implementation and Reference Guide
dlpdfimagecreatefromfile
This method invokes various conversion routines to allow a user to simply specify the file name and
obtain a valid DLPDFIMAGE object. All conversions are done internally to DLI.
NOTE: The public-domain graphic-conversion libraries used on Unix and Windows
are not available on OS/390 and OS/400 platforms. Consequently some image
creation procedures are not available under OS/390 and OS/400.
This method accepts only 2 parameters:
• a handle to a document in which the image is to be placed
• a file name which should contain the image
Currently, this method will support JPEG/JPG, GIF, TIFF, PNG and PDF files on the NT and UNIX
platforms, and PDF only on OS/390.
From the complete DLI sample of inserting graphic images, this segment inserts a PDF image via
dlpdfimagecreatefromfile:
"C" Example: Inserting a PDF image with dlpdfimagecreatefromfile
Image = dlpdfimagecreatefromfile (Doc, "math.pdf");
/* "Paste" the image into the container, centered over the
* red box */
dlpdfcontentreferenceimage (Content, Image,
(fixedFour * 72) - ((Image->BBox.left + Image->BBox.right)/2),
(fixedFour * 72) - ((Image->BBox.top + Image->BBox.bottom)/2),
0, fixedOne, fixedOne);
The DLPDFIMAGE objects contains an ASFixedRect object called BBox (Bounding Box), which is set to
the actual size and displacement of the image, as defined by its originator. This may be used in decisions
about positioning and scaling the image.
dlpdfimageplaceascontent
Some applications have difficulty parsing PDF Form XObjects within pages as well as marked content
blocks. Additionally, some applications are known to misinterpret marked content blocks between
different versions of the application. The default action of DLI is to create a Form XObject for each

Image Display 11.9
imported PDF graphic, so that it may be referenced repeatedly without inflating the size of the resulting
output file.
This call will flag an imported PDF graphic file to have any marked content tags removed, and to be set
into the current page's content stream instead of as a form reference.
NOTE: This call may increase the size of PDF files where a graphical object is
referenced repeatedly, as the PDF graphic is appended to the content stream at the
point of insertion.
LoadGraphicList
This method is available on OS/390 only. It reads a cross-reference file which maps graphics keys to their
physical location. The cross-reference table is accessed by the GetGraphicFromList method and, once
read, is stored in memory for the duration of the job. The cross-reference file must be created without line
numbers. The OS/390 distribution includes a sample cross-reference in
ADOBE.PDFLIB.RESOURCE.GRPHLIST(GRPIDX):
Pic1 ADOBE.PDFLIB.RESOURCE.IMAGE.PDF
Pic2 ADOBE.PDFLIB.RESOURCE.DLLOGO.PDF
The parameter containing the graphic list file name is the DDName of the cross-reference file, as in:
LoadGraphicList(“graphics”);
with the associated JCL line:
//GRAPHICS DD DSN=ADOBE.PDFLIB.RESOURCE.GRPHLIST(GRPIDX),DISP=SHR
GetGraphicFromList
This method is available on OS/390 only. It accepts a DLPDFDOC pointer and graphic key string, and
returns the appropriate DLPDFIMAGE pointer. Multiple usage of the same graphic key within a document
is tracked by DLI, resulting in only one instance of the graphic being placed in the document.
NOTE: The graphic key must be passed as an ASCII string.

11.10 DLI Implementation and Reference Guide
Creating Transparent Graphics
A PDF file may contain imagemasks. These are images which are used to mask, or block, the painting of
areas beneath the mask, in the manner of a stencil. Imagemasks are one-bit graphics, where a value of 0
means that the pixel beneath the image is not to show through, and a value of 1 means that the pixel
beneath is visible.
DLI will automatically set any bitmap image created with the dlpdfimagecreatefrombmp function,
having one bit per pixel and no color space (a CosNull object for the ColorSpace parameter), to be an
imagemask. The mask will paint marked regions with the current fill color, and will leave unmarked
regions untouched; page marks below these regions will be visible and not painted over.
To change an image into a mask, simply insert the Imagemask key, with the value of TRUE as a Boolean,
into the image’s dictionary. Then, remove the ColorSpace key from the image's dictionary. (This can be
accomplished through the cosImage member of the DLPDFIMAGE structure.) If the imagemask is to be
placed over an image, it need not be the same size or resolution as any of the images it masks; in fact, the
use of an imagemask of significantly higher resolution than the image to be masked is a useful way to
simulate gradations of transparency.
Transparent Graphics via Imagemasks Sample
In an accompanying /codesamples folder you should find a sample file entitled creating
transparent graphics using imagemasks.txt. This demonstrates how to create a mask from a
suitable graphic which is approximately 11 times as wide and high as the image to be masked.
NOTE: The files in the /Codesamples folder are not intended to be buildable
source as-is, only to be demonstrations of correct command syntax for different
purposes.
dlpdfcontentgstate
This method enables a user to set a graphics state in a PDF file, for graphics operations which normally
have no such state associated with them.
For example, when creating an imagemask to create a green mask, an appropriate color and colorspace
must be specified. Thus dlpdfcontentgstate is called to set the graphics state of the specified
DLPDFCONTENT to that of the PDEGraphicState. This may be done at any point during content
placement operations.

12
Color
and its Use
This chapter discusses Adobe PDF Library color
descriptions, colors in images, patterned color spaces,
creating and destroying color spaces, and more.
12.1

12.2 DLI Implementation and Reference Guide
Library Color Descriptions
Color can be added to pages produced via DLI only with the color fields of the PDEGraphicState. There
are two fields which establish color:
• strokeColorSpec
• fillColorSpec
strokeColorSpec defines the color that applied to lines which are stroked and fillColorSpec
defines the color applied to areas which are filled.
NOTE: Type is generally filled rather than stroked.
Color Description Components
The color description consists of two components:
• The first is a pointer to a PDEColorSpace structure, which describes a color space. This identifies the
type of color: Black and White, RGB, CMYK, etc.
• The second component is an array of from one to seven ASFixed values, which describe the amount of
color in each of the components of the given color model. These components are frequently called color
channels. For example, the color Black can be described variously as (RGB, 0.0, 0.0, 0.0),
(grayScale, 0.0) or (CMYK 0.0, 0.0, 0.0, 1.0); all are different ways of saying “Black.”
Patterned Colors
Patterned colors, which may be used in addition to (or instead of) a solid color, are carried in a separate
field within the DLPDFCONTENT structure, and are set with a specific set of calls to DLPDFCONTENT.
Colors in Images
Color spaces may also be used separately with images if those images are bitmaps. A color model must be
specified as a CosStructure when using dlpdfimagecreatefrombmp. The CosObj form of a color
is obtained from the PDE form by the call PDEColorSpaceGetCosObj. Creating the PDE form is
explained below.
When images are created with any of the other dlpdfimagecreate-type calls, color spaces will be
constructed as needed.

Color and its Use 12.3
Creating and Destroying Color Spaces
For the basic colors, the color spaces used in your document will be in the form of a PDEColorSpace.
This is not a document object, and therefore can be shared between documents. A COS form of that space
will be created and inserted into each document where that color space is used. These color models can be
created when the Adobe PDF Library is initialized, and should be destroyed before it is closed.
CAUTION: If color models are not freed, a close error will result.
Color spaces for the basic colors (DeviceRGB, DeviceCMYK and DeviceGray) are created by a call to
the Adobe PDF Library in this form:
"C " Example: Creating a Gray Color Space
PDEColorSpace GrayModel:
AsAtom GrayAtom;
GrayAtom = ASAtomFromName (“DeviceGray”);
GrayModel = PDEColorSpaceCreateFromName (GrayAtom);
"BAL" Example: Creating A Gray Color Space
In Assembler for OS/390:
GrCol @DLPDFS
DSECT=NO, *
STRUCT=__T_PDECOLORVALUE
GrName ds A“GrayScale”
GrAtom dc h’0’
@DLPDFC
DLFUNC=AsAtomFromEBCDICName,
DLPARAM=(GrName),
DLRETURN=GrAtom
DLPDFC
DLFUNC=pdecolorspacecreatefromname,
dlparam1=(GrAtom),
DLRETURN=GrCol

12.4 DLI Implementation and Reference Guide
Color Space Creation
For Adobe PDF Library v4.0 and higher, all of the color spaces may be created by the procedure
PDEColorSpaceCreate.
NOTE: A COS object is a document object, and cannot be shared between
documents. However, the PDEColorSpace created from a document-specific
COS Object is not a document object, and may be shared.
For example, to create a Calibrated Gray Scale color space, you would need the following code fragment:
Creating Calgray Color Space for Adobe PDF Library v4.0 and later
PDEColorSpace CIEGrey;
PDEGrayCalFlt CIEGreyDesc;
CIEGreyDesc.gamma = 0;
CIEGreyDesc.whitePoint.x = 0.9506;
CIEGreyDesc.whitePoint.y = 1.0;
CIEGreyDesc.whitePoint.z = 1.0890;
CIEGreyDEsc.blackPoint.x = 0.0;
CIEGreyDEsc.blackPoint.y = 0.0;
CIEGreyDesc.blakcPoint.z = 0.0;
CIEGrey = CreateColorSpace (AsAtomFromName (“CalGray”),
(PDEColorSpaceStruct *)&CIEGreyDesc);

Color and its Use 12.5
Values for Color Channels
The values specified for the color channels vary from space to space, but the most common values range
between zero and 1. Since these values are specified to the Adobe PDF Library as ASFixed values, this
allows 16 bits of precision.
Value Conversion and Inversion
Your own system may specify color internally with a greater or lesser precision, or in inverted values.
These must be converted to the Adobe PDF Library’s view of color to function correctly.
Generally, you should first correct the precision, matching it to the Adobe PDF Library’s 16 bit precision,
then correct the inversion (if there is one) by subtracting the number from an ASFixed one.
When the precision difference is a matter of powers of two (as it often is), precision is corrected by
shifting the value to match the Adobe PDF Library’s ASFixed format; e.g. if you are carrying color as a
value of 0-255, shifting left 8 bits will correct precision.
When the color specification is not in binary, e.g. zero to 100 or zero to 1000, try converting via floating
point numbers. You may also create a subroutine to convert color values in precision and direction from
the source system to the Adobe PDF Library’s system.
Basic Color Spaces
The Device color spaces below presume to render color as an absolute value. These are the basic color
spaces, and are fully supported throughout PDF and PostScript.
CIE Calibrated Color Spaces
Calibrated color spaces are colors with perception qualifiers. These are defined by CIE and are intended to
permit a more faithful rendition of color, given a knowledge of the display device characteristics.
A full discussion of the CIE models is beyond the scope of this document, but you can find a great deal of
information on them in the Adobe PDF Specifications document or the PostScript Language Reference.

12.6 DLI Implementation and Reference Guide
Device Gray
This space allows you to use black and white or levels of gray. It has a single channel of color data, which
is viewed by the imaging engine as a value between 1 (White) and zero (Black).
Since the value is specified to the system as an ASFixed value, 16 bits of precision are possible. Generally,
this will be rounded down to 4 decimal positions of precision when written to the PDF file.
The atom used to create this color model is DeviceGray. It is assumed to be present in all levels of PDF,
and does not need to be added to the resource directory as a color space name.
Device RGB
This space allows you to use full color by encoding the color as three channels, one for each of the
Radiant primary colors Red, Green and Blue. Each channel has a value between zero (none of this color)
and 1 (highest level of this color).
The color channels are always
• color[0] = RED
• color[1] = GREEN
• color[2] = BLUE
If your internal model uses a different sequence, you must reorder the colors when setting color values.
The atom used to create an RGB color space is DeviceRGB.
Device CMYK
This space allows you to use full color by encoding the color as 4 channels, one for each of the absorbent
colors Cyan, Magenta and Yellow, and a fourth channel for Black. Each channel has a value between zero
(No Absorption) and 1 (Full Absorption).
The channels are arranged as
• color[0] = CYAN
• color[1] = MAGENTA
• color[2] = YELLOW
• color[3] = BLACK
The atom used to create a CMYK color space is DeviceCMYK.

Color and its Use 12.7
Calibrated Gray
This is a calibrated color space, intended to make use of the knowledge of the display device’s
characteristics to more accurately depict levels of gray. The values for this color space are identical to
those of device gray (i.e. zero to 1, where zero is darkest and 1 is lightest), but for Calibrated Gray, you
must also add to the color space definition the conditions under which the original colors were viewed.
This color space may not be created from PDEColorSpaceCreateFromName. When created via
PDEColorSpaceCreate, its atom is CalGray and the color structure must be a PDEGrayCalFlt.
Calibrated RGB
This is a calibrated color space, intended to make use of the knowledge of the display device’s
characteristics to more accurately depict colors. The values are identical to the DeviceRGB color channels
in value and sequence.
This color space may not be created with PDEColorSpaceCreateFromName. When created with
PDEColorSpaceCreate, its atom is CalRGB, and the color structure must be a PDERGBCalFlt.
CIE Lab
This is a calibrated color space intended to display color. It uses three channels (L, A, and B) in that order:
• The range of the L channel is always zero to 100.
• The range of the A and B channels are specified within the color space model, but must always be in the
range of -128 to +127.
This color space cannot be created with PDEColorSpaceCreateFromName. When created with
PDEColorSpaceCreate, the atom used to specify this color space is Lab, and the color structure must
be a PDELabCalFlt.

12.8 DLI Implementation and Reference Guide
ICC Based
This is a color model promoted by the International Color Consortium (ICC). Its purpose is to encode
color intent, so that this intent may be correctly realized in any medium.
This color model includes a Color Profile, which specifies the number of channels in use, and the range
and limits of those values. In essence, this is a calibrated color space schema, which permits grayScale,
RGB, CMYK and Lab specifications within itself.
This color model may not be created by PDEColorSpaceCreateFromName. When it is created by
PDEColorSpaceCreate, its atom is ICCBased, and the color structure must be
PDEICCBasedColorData.
Advanced Color Spaces
The preceding color spaces all represent colors as a spectrum, from lighter to darker. The following color
spaces do not do so: instead, each color is viewed as an individual.
Separation
This color space names a color, where the color value is a number between zero (none of this tint applied)
to 1 (full tint applied).
If the name specified in this space is known to the display device, then that tint will be used. If it is not
known, a fallback color model will be used, and a transformation function from the tint amount to that
fallback model’s color channel is provided in the model.
This color space may not be created from PDEColorSpaceCreateFromName. When created by
PDEColorSpaceCreate, its atom is Separation and the color structure used must be a
PDESeparationColorData.

Color and its Use 12.9
DeviceN
This color space is a generalization of the separation model. In it, an array of names is specified, rather
than a single name. The number of color channels used by a DeviceN color is the number of names
specified in the DeviceN name array. The value of each channel is from zero to 1.
NOTE: The structure PDColorValue, used to set values for colors, permits only
4 channels.
This color space may not be created by PDEColorSpaceCreateFromName. When created by
PDEColorSpaceCreate, its atom name is DeviceN, and it must use a color structure of
PDEDeviceNColorData.
Indexed
Indexed color spaces are most often used in images, but are by no means limited to images.
An indexed color space first selects a device color space in which it will be rendered. This must be
DeviceRGB, DeviceGray, DeviceCMYK, DeviceN or ICCBased.
It then supplies an array of from 1 to n entries, each entry having the value of a color in the selected
model. (For DeviceGray, there would be one entry per color; for DeviceRGB, three; and so on).
Color is specified as a single channel, which must be an integer between zero and n-1. This value is used
as an index to the array of colors, and the selected entry is imaged in the underlying color space.
This color space cannot be created with PDEColorSpaceCreateFromName. When created with
PDEColorSpaceCreate, its atom is Indexed and the color structure must be a
PDEIndexedColorData.
Patterned
A patterned color space is not really a color space at all. Rather, it is an image which will fill or stroke an
area or line. It may contain colors of its own, or it may be a black-and-white image which is colored per
the underlying color space.
Any valid PDF marking commands may be used to construct the pattern image. The image itself is
constructed as a rectangular space, which is overlaid on the area being filled or stroked. Specification of

12.10 DLI Implementation and Reference Guide
how far apart each tile is to be placed (horizontally and vertically) permits the appearance of nonrectangular
areas.
DLI contains an interface (dlpdfpatterncreate) which will accept a container and convert it into a
patterned color space. This space may then be used within a container via the interface’s
dlpdfcontentusefillpattern or dlpdfcontentusestrokepattern methods.
Building Patterned Color Spaces
DLI permits patterned color spaces to be easily defined and used.
A patterned color space is created by marking a container, exactly as if writing text, then converting that
container into a patterned color space. It is used by instructing the container in which marks are made to
use a particular patterned color space for filling or stroking.
For example, to make a patterned color space like this:
1 Define one tile of the angled line, by creating a content area and drawing that line in that area.
2 Create a pattern of that tile with dlpdfpatterncreate.
3 Set the current container fill pattern to that pattern via dlpdfcontentusefillpattern.
For example, the following code fragment can be used to build patterned color spaces:

Color and its Use 12.11
"C" Example: Filling An Area With A Pattern
DLPDFPATTERN
*Pattern;
DLPDFCONTENT
*PatContent, *PageCont;
PDGraphicState State;
ASFixedMatrix Matrix;
ASFixedRect BBox;
/* Initialize the graphics state */
State.strokeColorSpec.space = State.fillColorSpec.space =
PDEColorSpaceCreateFromName(ASAtomFromString("DeviceGray"));
State.strokeColorSpec.value.color[0] =
State.strokeColorSpec.value.color[0] = 0;
State->GState.miterLimit = fixedTen;
State->GState.flatness = fixedOne;
State->GState.lineWidth = fixedTwo;
/* Draw the pattern “tile” */
PatContent = dlpdfcontentcreate (Doc);
dlpdfcontentline (PatContent, &State, kPDEStroke,
0, 0, fixedTen + fixedTwo, fixedTen + fixedTwo);
BBox.left = BBox.bottom = 0;
BBox.right = BBox.top = fixedTen + fixedTwo;
Matrix.a = Matrix.d = fixedTwo / 3;
Matrix.b = Matrix.c = Matrix.h = Matrix.v = 0;
Pattern = dlpdfpatterncreate (Doc, PatContent, &BBox, &Matrix,
FALSE, 1, BBox.right - fixedTwo, BBox.top - fixedTwo);
/* Set this pattern as the fill pattern */
dlpdfcontentusefillpattern (PageCont, Pattern);
/* Draw and fill the structure */
...
/* Cancel the fill pattern */
dlpdfcontentusefillpattern (PageCont, NULL);
NOTE: A fill pattern is never destroyed. It becomes a part of the document, and
the space used to define the pattern will be freed automatically when the
document is freed.
Repeating Pattern References
Most often, you will want to create a repertoire of fill patterns that matches the capabilities of your
existing composition engine or of the display devices you have been using prior to PDF. If you do this, and
save the pointers to the patterns in a findable manner, then the patterns can be used repeatedly throughout
a document. Note that they are specific to a document, however, so you may not share them between
documents.

12.12 DLI Implementation and Reference Guide
Conversion between Models
On some occasions, it is useful to be able to convert color values between color spaces. This does not
occur often, as most composition engines permit only a single definition of color, but you may
occasionally, for example, need to collapse colors to fewer models, such as when using grayscale in place
of RGB when the color selected is a gray.
The folowing examples assume a gray image encoded as RGB or CMYK.
Collapsing RGB to Gray
If all three channels of the RGB color are the same value, then the color specified is a gray. It may be
simulated in gray by using that value as the gray color value.
"C" Example: Collapsing RGB to Gray
if (State->fillColorSpec.space) == GlobalRGBSpace)
{
if ((State->fillColorSpec.value.color[1] ==
State->fillColorSpec.value.color[2]) &&
(State->fillColorSpec.value.color[2] ==
State->fillColorSpec.value.color[3]))
{
State->fillColorSpec.Space = GlobalGraySpace;
}
}
Collapsing CMYK To Gray
If the first three channels of the CMYK color are the same, then the color is gray. The amount is 1 minus
the sum of one of the first three channels, plus the fourth channel. If this is less than zero, then the amount
is zero.

Color and its Use 12.13
"C" Example: Collapsing CMYK to Gray
if (State->fillColorSpec.space) == GlobalCMYKSpace)
{
if ((State->fillColorSpec.value.color[1] ==
State->fillColorSpec.value.color[2]) &&
(State->fillColorSpec.value.color[2] ==
State->fillColorSpec.value.color[3]))
{
State->fillColorSpec.Space = GlobalGraySpace;
State->fillColorSpec.value.color[0] =
(fixedOne - (State->fillColorSpec.value.color[0] +
State->fillColorSpec.value.color[3]));
if (State->fillColorSpec.value[0] < 0)
State->fillColorSpec.Value[0] = 0;
}
}
Converting RGB to CMYK
RGB and CMY are complements, so we can turn one to the other by subtracting the value from 1.
However, the “K” component of CMYK (Black) is present to enhance the distribution of ink on a printer,
and should be maintained correctly across such conversions.
In converting RGB to CMYK, we complement each of the channels, then identify the smallest of the three
values, subtract it from each channel, and use it as the value for channel 4.
"C" Example: Converting RGB to CMYK
if (State->fillColorSpec.space) == GlobalRGBSpace)
{
State->fillColorSpec.space = GlobalCMYKSpace;
State->fillColorSpec.value.color[3] = fixedOne;
for (i = 0; i < 3; i++)
{
State=>fillColorSpec.value.color[i] =
fixedOne - State->fillColorSpec.value.color[i];
if (State->fillColorSpec.value.color[i] <
State->fillColorSpec.value.color[3])
{
State->fillColorSpec.value.color[3] =
State->fillColorSpec.value.color[i];
}
}
for (i = 0; i < 3; i++)
State->fillColorSpec.value.color[i] -=
State->fillColorSpec.value.color[3];
}
Converting CMYK to RGB
Very similar to conversion of RGB to CMYK, of course.

12.14 DLI Implementation and Reference Guide
"C" Example: Converting CMYK to RGB
if (State->fillColorSpec.space) == GlobalCMYKSpace)
{
State->fillColorSpec.space = GlobalRGBSpace;
for (i = 0; i < 3; i++)
State->fillColorSpec.value.color[i] +=
State->fillColorSpec.value.color[3];
for (i = 0; i < 3; i++)
{
State=>fillColorSpec.value.color[i] =
fixedOne - State->fillColorSpec.value.color[i];
if (State->fillColorSpec.value.color[i] < 0)
State->fillColorSpec.value.color[i] = 0;
}
}

13
Annotations
and Links
Annotations are structures within the PDF document, as
children or subordinate structures to a page, which
permit special actions to be initiated by the user. DLI
supports the creation of text annotations and link
annotations within the document.
13.1

13.2 DLI Implementation and Reference Guide
Overview
Pages may contain text annotations, which are notes appended to the document, and link annotations,
which indicate that an area of the page (always a rectangular area) connects to another area of this or
another document. Links to external documents must be supported externally to this package.
The methods used for creation of annotations return the CosObj which is the annotation. This object
need not be picked up by the application, and does not need to be deallocated by the application.
Modifying for Other Actions
The objects may be modified, either immediately after creation or at any time prior to writing the
document, to permit access to functionalities beyond those described in these method interfaces. There are
fourteen or more different annotation types, and not all are represented by DLI methods, so in some
circumstances you will need to create an object as one type, but then modify it to be another.
Therefore, if you plan to change the annotations to perform other actions, you must make your changes
before the document is released from the resources. See following sections of this chapter for further
details.
Annotation Components
All annotations consist of two parts: a hot spot, which is defined as a rectangular area of the page, and an
action.
Hot Spots
The hot spot can be defined as an ASFixedRectangle, or as a reference to a name contained in a
special Name Tree within the document.
Actions
Actions can be specified in a number of ways, depending on the complexity of the action.
DLI directly supports the most basic forms of annotations, and returns the created CosObj for all
annotations, so that your application can easily construct more complex forms by modifying the basic
forms provided here.

Annotations and Links 13.3
Borders
Borders may be placed around an annotation hot spot to highlight it to the user. Prior to version v4.0, the
Adobe PDF Library allowed a definition of a border as an array of three ASFixed values:
• Horizontal Corner Radius
• Overcall Corner Radius
• Border Width
When Border Width is zero, the border is not drawn.
DLI directly supports this definition only. In the following methods, a reference to borders is presumably
to a NULL pointer, in which case the border is omitted, or a pointer to an array of three ASFixed values,
interpreted as above.
Annotation and Link Colors
Color has a different meaning for each type of annotation:
• For text annotations, it is the color to be used for the background of the closed annotation.
• For links, it is the border color.
Prior to v4.0 of the Adobe PDF Library, colors could be specified only as an array of three ASFixed
values, representing an RGB color. When used below, color means a pointer to such an array, or NULL. If
NULL, then the viewer will select a color.

13.4 DLI Implementation and Reference Guide
dlpdfpageaddtextannotation
The simplest annotation in PDF is a text annotation. This appears as a “sticky note” in Adobe Acrobat or
Adobe Reader and can be opened to display a text message.
• The first parameter is a pointer to the page which will contain this annotation.
• The second parameter is a pointer to an ASFixedRectangle whose upper left corner will be the
upper left corner of the closed annotation.
• The third is a pointer to a border specification.
• The fourth is a pointer to a color specification.
• The fifth is a pointer to a string, which will be used as a title of the opened annotation. This may be a
NULL pointer.
• The sixth parameter is a pointer to a string which is the content of this annotation. If this is a NULL
pointer, the method will raise an exception (genErrBadParm).
• Finally, the seventh parameter is a flag. If TRUE, then this annotation will be open when first displayed.
If FALSE, it will be closed.
From the full example of creating annotations:
"C" Example: Creating Text Annotations
DLPDFDOC *Doc;
DLPDFPAGE *Page1, *Page2;
ASFixedRect NoteRect;
ASFixed Border[3], Color[3];
dlpdfpageaddtextannotation (Page1, &NoteRect, Border,
Color, "Page 1 Note",
"This is a closed note placed on page one", FALSE);
dlpdfpageaddtextannotation (Page2, &NoteRect, Border,
Color, "Page 2 Note",
"This is an open note placed on page Two", TRUE);

Annotations and Links 13.5
dlpdfpageaddlinkannotation
This is the most frequently used annotation. It links an area of the page which contains this annotation to
a separate area on that or another page. The viewer uses these links, when selected, to modify the view of
the document to display the destination area.
This method assumes that the destination will be specified as a page number, an ASFixedRectangle
describing a portion of that destination page, and a FitDescription, saying how the portion of the
page should be displayed.
• The first 4 parameters of this method are identical to the text annotation above, except that the
ASFixedRectangle is used for both location and size, and defines the hot spot where the user might
select this link.
• The fifth parameter is the page number of the destination page. The first page is considered to be page
0. The page referenced need not have been created yet.
• The sixth parameter is the FitType. This is a text string which is one of the set of “XYZ”, “Fit”,
“FitH’, “FitV”, “FitR”, “FitB”, “FitBH”, or “FitBV”. The meanings of these various types can
be seen in the Adobe PDF Library Reference Guide, or the PDF Specification, section 7.3.1.
• The seventh parameter defines a rectangle which will be fitted according to the sixth parameter. In
general, this should describe the extent of the text that you want the user to see when selecting this link.
The values actually used will vary with the FitType specified.
• The eighth parameter is a zoom amount, used only with fit type “XYZ”. It is an ASFixed value, where
1.0 is no zoom, 2.0 is double size, and 0.5 is 1/2 size. If you want the view to remain unchanged, set
this value to PDViewDestNull.
From the full example of creating annotations:
"C" Example: Creating A Link Annotation
DLPDFPAGE *Page1
ASFixedRect BBLink1, PageRect;
ASFixed Border[3], Color[3];
/* Set up the border and color arrays */
Border[0] = Border[1] = 0; /* This is a square box */
Border[2] = fixedTwo; /* Two points in thickness */
Color[0] = Color[2] = 0; /* Its color will be blue */
Color[1] = fixedOne;
dlpdfpageaddlinkannotation (Page1, &BBLink1, Border,
Color, 1, "Fit", &PageRect, PDViewDestNULL);

13.6 DLI Implementation and Reference Guide
dlpdfpageaddlinkannotationfromname
An optional structure within the PDF document is a name tree. This consists of an ordered collection of
strings (names) and a value for each name, which is an array in the form defined in the PDF Specification,
section 7.3.1. The named destination itself is described in sections 7.3.2 and 6.9.
In the Adobe PDF Library, only the DEST name tree may be defined, and within DLI, there is direct
support only for the name tree. Names may be added to the name tree via dlpdfdocnameadd.
Names vs. Destinations
A link may be accomplished using a name, rather than a specific destination. When cross-document links
are to be used, referring to a name permits a more flexible linkage: if the document referred to is modified,
you need not recompose the referring documents.
In practice, this means that you would need to create a name tree which names all of the possible
interesting sites for a link, and publish the names of those sites to potential linking documents. These
names should be derived directly from the text, to identify them by their relevance to the context, rather
than their position within the document.
For example, you might create a name of "Maintaining Backup Files," rather than "Chapter 2," using the
text of the title rather than its sequential position, so you can preserve the link even if the document
chapters are later reorganized.
This method is intended to permit linkages by names within a document. Making a link between
documents is fairly straightforward:
• The first 4 parameters are the same as the previous two methods.
• The fifth parameter is a string giving the name of the destination.
From the full example of adding annotations:
"C" Example: Creating A Link To A Named Destination
DLPDFPAGE *Page2
ASFixedRect BBLink2;
ASFixed Border[3], Color[3];
Border[0] = fixedFive; /* A box with elliptical corners */
Border[1] = fixedTen; /* longer horizontal than vert. */
Border[2] = fixedTwo; /* Two points in thickness */
Color[0] = Color[2] = 0; /* Its color will be black */
Color[1] = 0;
dlpdfpageaddlinkannotationfromname (Page2, &BBLink2,
Border, Color, "Link1");

Annotations and Links 13.7
dlpdfpageaddwebannotation
This procedure supports adding a link structure which is identical in appearance to a link annotation, but
which references a URI (Uniform Resource Indicator, equivalent to a URL) passed as the last character
string. This method is used to place hyperlinks to external documents, on the World Wide Web for
example, within a PDF document.
NOTE: You should have your internet browser running before calling this
procedure or you may receive a “browser is busy” error. Your browser can be
specified in Acrobat via File->Preferences->Weblink.
dlpdfdocnameadd
This method allows the user to add one destination to the name tree structure, the optional ordered list of
names and destinations.
The method accepts four parameters:
• The first is a handle for the document in which the name is to reside.
• The second is a string representing the tree name (can be NULL).
• The third is a string containing the destination name.
• The fourth is a COS structure, which must be an array with contents as described in the PDF
Specification, section 7.3.1.
"C" Example: Creating A Named Destination
/* Create a Destination structure to fit a given rectangle to
* the viewer window */
Dest = CosNewarray (Doc, TRUE, 6);
CosArrayPut (Dest, 0, Page); /* The current page */
CosArrayPut (Dest, 1, CosNewName (Doc, FALSE,
ASAtomFromString (“FitR”)));
CosArrayPut (Dest, 2, CosNewFixed (Doc, FALSE, Left));
CosArrayPut (Dest, 3, CosNewFixed (Doc, FALSE, Bottom));
CosArrayPut (Dest, 4, CosNewFixed (Doc, FALSE, Right));
CosArrayPut (Dest, 5, CosNewFixed (Doc, FALSE, Top));
dlpdfdocnameadd (Doc, "Name Tree", "Destination Name",
Dest);

13.8 DLI Implementation and Reference Guide
dlpdfdocnamefind
This method will return the Cos structure associated with a destination name. If that name does not exist,
a CosNull structure will be returned.
The method accepts two parameters:
• a document handle
• a string containing the desired name
Modifying the Link Cos Object
Each of the three methods which create an annotation return a CosObj. This structure is the annotation
dictionary, and may be modified freely. In practice, it is the link annotation that will most often be
modified.
As created by DLI, the link annotation dictionary will contain the following key/value pairs:
• Type Annot
• SubType Link
• Rect [x, y, x+wide, y+depth]
• Border [v1, v2, v3] (if Border is not NULL)
• Color [r, g, b] (if Color is not NULL)
• Dest [...], where the destination is described in the array
This will create a link whose action is defaulted to “GoTo.”
Although "GoTo" is the normal state for a link within a document, there are 13 possible actions for
selecting a link permitted in PDF Specification 1.2, and a fourteenth added in PDF Specification 1.3. More
may be added in the future.
In order to modify this link to use one of the other actions, you must replace the Dest couplet with an A
key and an action dictionary:
1 The Dest couplet is removed, using
CosDictRemove(Dict, ASAtomFromString (“Dest”));.
2 The action dictionary is created, always as a new, indirect, dictionary structure. It has a Type of
Action, a SubType of the action desired (See PDF Specification, section 6.8), and additional
parameters depending on the action selected.
The following is extracted from the full example of creating annotations:

"C" Example: Modifying a Goto Link into a GotoR Link
/* Create a link to another document */
local_inserttext (Doc, Content1, &gState,
"Link to Line Drawing Sample", fixedFour * 72,
fixedEight * 72, &BBLink3);
CosLink3 = dlpdfpageaddlinkannotation (Page1, &BBLink3,
Border, Color, 0, "XYZ", &BBLink3, PDViewDestNULL);
CosDictRemove (CosLink3, ASAtomFromString ("Dest"));
Action = CosNewDict (Doc->cosDoc, TRUE, 3);
CosDictPut (CosLink3, ASAtomFromString ("A"), Action);
CosDictPut (Action, ASAtomFromString ("Type"),
CosNewName (Doc->cosDoc, FALSE,
ASAtomFromString ("Action")));
CosDictPut (Action, ASAtomFromString ("S"),
CosNewName (Doc->cosDoc, FALSE,
ASAtomFromString ("GoToR")));
Dest = CosNewArray (Doc->cosDoc, FALSE, 2);
CosArrayPut (Dest, 0, CosNewInteger (Doc->cosDoc,
FALSE, 0));
CosArrayPut (Dest, 1, CosNewName (Doc->cosDoc, FALSE,
ASAtomFromString ("Fit")));
CosDictPut (Action, ASAtomFromString ("D"),Dest);
CosDictPut (Action, ASAtomFromString ("F"),
CosNewString (Doc->cosDoc, FALSE,
"ExampleDraw1.pdf", 16));
Annotations and Links 13.9

13.10 DLI Implementation and Reference Guide

14
Bookmark
Creation
Bookmarks, or an outline tree, are used to help the reader
navigate a document. In essence, they form a Table of
Contents for a document. They are displayed on a
collapsible navigation pane adjacent to the window in
which the document body is displayed when using Adobe
Acrobat or Adobe Reader.
14.1

14.2 DLI Implementation and Reference Guide
Overview
You are not limited to a single tree of contents which matches your document. You may build multiple
trees within the outline tree, and you may order material differently than the way it is ordered in the
document. You may use bookmarks to point out and highlight material in any way that you believe to be
useful to a reader of your document.
The outline tree itself must be a single tree, with a single root node. DLI will handle the mechanics of
constructing the actual tree, allowing you to be concerned only with its content.
DLI represents the outline tree as a collection of DLPDFOUTLINE structures. These have a number of
properties, in addition to a pointer to the COS structure which this structure represents. The collection of
such structures is the property of a single given document, and will be destroyed when that document is
destroyed.
dlpdfdocoutlineadd
This method adds a new outline entry to the document:
• The first parameter specifies the document in which it is to reside.
• The second, if not NULL, is the handle of a parent structure.
• The third, if not NULL, is the desired younger sibling (if NULL, it will be added as the last child of that
parent).
• The fourth parameter is required and is the text that will be displayed for this outline entry.
• The fifth is a flag. If TRUE, the entry will be displayed initially as open (its children will be displayed). If
FALSE, it will be displayed initially as closed.
The following parameters describe a location which is to be displayed if this entry is selected.
• First is a page number (the first page is zero)
• Second is a FitType, a text string, as defined in the PDF Specification, section 6.8.1.
• Third is an ASFixed Rectangle, describing a location of the page to be displayed
• Last is a zoom factor, indicating how much the size of the display should increase or decrease.
(PDViewDestNull indicates “Do not change.”)
These last 4 parameters are identical to the destination specifications for links, in the previous section.
From the full example on creating annotations, this segment shows the creation of an outline entry:

Bookmark Creation 14.3
"C" Example: Adding Outline Entries
RootBookMark = dlpdfdocoutlineadd (Doc, NULL, NULL,
"All Pages", TRUE, 0, "Fit", &PageRect, PDViewDestNULL);
/* An annotation for each page, linking to display
* entire page */
Page1BookMark = dlpdfdocoutlineadd (Doc, RootBookMark, NULL,
"Page 1", FALSE, 0, "Fit", &PageRect, PDViewDestNULL);
dlpdfdocoutlineaddfromname
This method is the same as the previous in its action and in its first 4 parameters. It differs in that the
destination is specified as a text string, a name in the destination dictionary of the document. (See the
previous section for adding names and description of the use of name.)
The following is an extract from the full example on annotations:
"C" Example: Adding an Outline with a Named Destination
dlpdfdocoutlineaddfromname (Doc, Page1BookMark, NULL,
"Link to 2", FALSE, "Link1");
Each time you create a DLPDFOUTLINE, a pointer to that structure is returned. You may keep these
pointers in your own data structures as an aid in building the document tree, or you may navigate the
existing structure using the following methods.
dlpdfdocoutline
This method accepts a document handle, and returns the handle of the root outline node. If there are no
outlines, it will return a NULL pointer.
dlpdfdocoutlinefirst
This method accepts an outline handle, and returns the handle of the first child of this outline. If there are
no outlines, it will return a NULL pointer.
dlpdfdocoutlinelast
This method accepts an outline handle, and returns the last child of that outline. If there are no children in
the outline, it returns a NULL pointer.

14.4 DLI Implementation and Reference Guide
dlpdfdocoutlineprev
This method accepts an outline pointer, and returns the handle of the previous child of this outline entry’s
parent. If there is no previous child, it returns a NULL pointer.
dlpdfdocoutlinenext
This method accepts an outline pointer, and returns the pointer of the next child of this outline entry’s
parent. If there is no next child, it returns a NULL pointer.
dlpdfdocoutlineparent
This method accepts a pointer to an outline entry, and returns a pointer to that entry’s parent. If the entry
is the root entry, it returns a NULL pointer.
The DLPDFOUTLINE structure contains three fields which may be accessed, but not changed, by an
application:
• DLPDFOUTLINE->Open is a flag which will be TRUE if the outline entry was created open, FALSE if it
was not.
• DLPDFOUTLINE->Count is a count of the children of this entry.
• DLPDFOUTLINE->Obj is a Cos Obj which is the actual entry in the outline. This entry is a dictionary,
as described in the PDF Specification, section 6.7. It will always have a Dest key, never an A key. You
may replace this key to obtain actions other than “GoTo”.
Opening the Document with Annotations Showing
The default action on opening a document is to show only the document window and hide the navigation
pane. To define a document that should be opened with the navigation pane showing, you need to add the
key PageMode with the value UseOutlines to the document catalog structure. This is done at the Cos
level as:
"C" Example: Setting the Page Mode to Display Navigation Pane
CosDoc cosDoc;
CosObj Catalog;
cosDoc = dlpdfdoccosdoc (Doc);
Catalog = CosDocGetRoot (cosDoc);
CosDictPut (Catalog, ASAtomFromString ("PageMode"),
CosNewName (cosDoc, FALSE,
ASAtomFromString ("UseOutlines")));

15
Digital
Signatures
Digital Signatures are used to validate the document’s
content and protect it against unauthorized tampering,
viewing or modification.
15.1

15.2 DLI Implementation and Reference Guide
Overview
PDF files created with DLI may include digital signatures for use in validating a document's contents.
With a digital signature, a certificate is added to a PDF file containing information about the signer. An
encrypted message, and the key to decrypt this message, are included in the certificate or the signature
PDF fields. The message is generated by a non-reversible mathematical transform of the PDF file's bytes
known as a hash function. A recipient of the PDF file can then decrypt this message. If the message
matches what the recipient calculates using the hash function for the PDF file, the PDF file has not been
altered since it was signed. If it does not match, the document has been changed.
Public and Private Keys
Digital signatures are based on public-key cryptography. In public-key cryptography, there are two keys,
public and private:
• A private key is used to encrypt data that only the public key can decrypt.
• A public key may encrypt data that only the private key can decrypt.
This allows you, the document creator, to distribute a public key freely, and to encrypt a message with
your private key (which must be kept secret). The reader can decrypt a message, but cannot re-encrypt the
message in the same way that you encrypted it when you signed it. This prevents the reader from
pretending to be the document author.
Digital signatures also serve the purpose of non-repudiation. Since only the author can sign a document, a
valid signature means that only the author of the document could have signed the PDF file. This makes
digital signatures useful for contracts or other archival legal documents.
A digital signature in a PDF file has two important parts:
• the certificate
• a series of DLPDFFORM objects which form a visible indicator that a document is signed
The certificate is supplied to DLI and contains information such as the signer's name, their location, and
a signature to validate the certificate.
Certificates are accepted in PKCS #7 format and in x.509 format. For PKCS #7 format, the calling
application must be able to supply a fully-formed certificate, complete with the signed PDF document
hash (supplied by DLI); for an x.509 certificate, the hash value is calculated by DLI and supplied to the

Digital Signatures 15.3
application through a callback routine for signing. This is for security purposes; calling applications
should use secure memory routines when signing the PDF document.
The appearance of the signature is optional; if it is not set, an invisible digital signature will be added to
the PDF file created by DLI. It consists of several layers:
• a background layer
• a layer displayed before the signature is validated
• a layer for the graphical signature representation (such as a scan of a handwritten signature or signature
stamp)
• a layer containing information about the signature
Any of these layers may be omitted; if so, an empty layer is created by DLI for the signature.
Digital Signature Calls
dlpdfdoccreatesignature
This call creates a digital signature object for the DLI document being created. The sigType value is one
of:
dlpdfsigacrox509 (Adobe self-sign plug-in compatible with an x.509 v3 certificate)
dlpdfsigacropkcs7 (Adobe self-sign plug-in compatible with a PKCS #7 certificate)
dlpdfsigverisign (VeriSign signature plug-in compatible with a PKCS #7 certificate)
The nameStr, reasonStr and locationStr arguments are ASCII strings representing the signatory's
name, the reason for signing (such as an initial release or a document revision), and the location of the
signatory respectively. This information is stored outside of the certificate and is optional.

15.4 DLI Implementation and Reference Guide
dlpdfdocsetsignatureappearance
This call sets the appearance layers for the digital signature to the supplied DLPDFFORM values:
• The background layer is the bottommost layer of the digital signature appearance.
• The unverified layer is displayed when the signature has not been verified.
• The signature layer is a graphical representation of the signature itself (such as a scanned
handwritten signature).
• The textSigInfo layer is used to display information about the signature and the signatory.
This call is optional. For an invisible digital signature, do not call this function. All the signature layers are
also optional. Blank layers will be used for any omitted signature appearance layers. These forms are
placed at the origin of the DLI page.
dlpdfsignaturesetx509cert
This call associates an x.509 v3 certificate with a DLPDFSIGNATURE object created as a
dlpdfsigacrox509-certificate digital signature. Do not call this with a DLPDFSIGNATURE object
created as a different certificate type.
The certificate is passed as a binary buffer in the certificate parameter; DLI will read certLen bytes from
this buffer and make a copy for the PDF file's digital signature.
The last parameter is a required callback function, to be called during the dlpdfdocwritepdf function
call. It will be passed a character string containing the SHA-1 hash for the PDF file being written, as a
NULL-terminated string of hexadecimal digits using PKCS #1 padding, containing a BER OID (object
identifier) for the SHA-1 algorithm. The buffer is 256 bytes long (not including the NULL terminator), and
formatted as
0001FFFF .. FF003021300906052B0E03021A05000414
[ 40 hex digits for SHA-1 hash ]
The callback function must encrypt this hash value with the private key corresponding to the public key in
the signature's x.509 certificate, and fill the buffer passed in with 256 hexadecimal digits representing the
encrypted value for the supplied BER formatted hash. A 1024-bit key is used for encryption operations.
NOTE: The signed hash will not have padding, and must be exactly 256
hexadecimal digits. If necessary, use zeros to pad it to the required length.
dlpdfsignaturesetpkcs7cert
This function sets the certificate generation callback for DLPDFSIGNATUREs of type
dlpdfsigacropkcs7 and dlpdfsigverisign. For these signature types, the application using DLI

Digital Signatures 15.5
is required to generated a fully-formed PKCS #7 certificate with an MD5 checksum of the PDF document,
encrypted with the private key corresponding to the public key in the certificate. The RSA public-key
algorithm with a 1024-bit key length is used.
The genPKCS7Cert callback is called by DLI during the dlpdfdocwritepdf function call. The
callback is supplied a binary data buffer of length maxLen. The first 16 bytes of this buffer contain the
MD5 checksum (in binary) for the PDF document to sign. The callback must generate a PKCS #7
certificate as described above, and fill the data buffer with the certificate, in binary. The callback function
must return the length to read from the data buffer, in bytes.
NOTE: maxLen bytes are set aside in the output PDF file for the PKCS #7
certificate, and will be written to the PDF file regardless of the actual certificate
length. Callers should pass length values which are close to the certificate length
if possible.
dlpdfsignaturesetdatacallback
This call is optional for clients using PKCS #7 certificates. A callback function is supplied for the
signature. The callback is called during the dlpdfdocwritepdf function with binary information from
the PDF file. This information will be in sequential pieces, and may be used to generate the PDF document
hash value. The information is supplied as binary values in the character buffer; the length to read is
supplied as the second parameter. A length of 0 indicates that no further data is to be read, and the hash
may be finalized.
dlpdfpageplacesignature
This call associates a digital signature to a page in the PDF file generated by DLI. The signature
appearance must fit in the bounds supplied in imageBBox. This call is required for all digital signatures,
even invisible signatures. For invisible digital signatures, the imageBBox is ignored and may be NULL.

15.6 DLI Implementation and Reference Guide

16
Error
Testing and Recovery
This chapter discusses possible errors you may encounter
and how to resolve them.
16.1

16.2 DLI Implementation and Reference Guide
Overview
The Adobe PDF Library and DLI will communicate errors back to your application program by raising
an exception. For this reason, it is important that you have exception handlers placed to catch such errors
as close as possible to their source, to detect the error as soon as possible and to limit the damage an error
can cause. It is also important that an outer error catcher be in place, as having no exception handler
when an exception is raised will cause a fatal error.
NOTE: Follow the development guidelines for error handling that are included in
the Adobe Acrobat Core API Overview. See chapter 12, “Handling Errors” for more
information.
The Adobe PDF Library provides a mechanism in “C” to define exception handlers. This mechanism
consists of bracketing the code which may cause an exception to be raised with DURING and HANDLER,
followed by a block of code to be executed only if an exception is raised, terminated by END_HANDLER.
CAUTION: Your application must not exit from within the exception handler.
Doing so will leave the exception handler frame on the stack, eventually leading to
a stack overflow and crash. Your application should exit beyond the
END_HANDLER statement, not within the HANDLER/END_HANDLER block. See
“Risks of Function Returns within Exception Handlers” on page 16.3 following
below.
Always use the macros defined by Adobe for returning from functions under various conditions. For
example:
"C" Example: Error Handler
DURING
Image = dlpdfimagecreatefromfile (Doc, FileName);
HANDLER
char Buffer[1024];
ASGetErrorString(ASGetExceptionErrorCode(), Buffer, 1024);
printf (“Unable to process image ‘%s’ for reason ‘%s’,
FileName, Buffer);
Image = NULL;
END_HANDLER
To support you in handling an error, both the Adobe PDF Library and DLI report errors via exception
names. These names are available via the method ASGetExceptionErrorCode. It will be translated
into a meaningful text string via the call ASGetErrorString.

Error Testing and Recovery 16.3
Each method documents the exceptions that may be raised by that method. You may design error routines
which examine the exception code and act differently based on its value.
Be careful in placing DURING/HANDLER/END_HANDLER constructs. Try to get them as close to a definable
piece of your data constructs as possible. Depending on the function of your application, this may allow a
single construct to fail without removing all of a line, area, page, or the document as a whole.
The more handler constructs you build, the smaller the effect of an error may be, and the greater your
chances that your application may be able to recover from that error and continue (depending on the
nature of the problem, of course).
Risks of Function Returns within Exception Handlers
Do not return from a function while inside an exception handler, since doing so can cause unexpected and
hard-to-trace program crashes. If an application must exit while inside a DURING/HANDLER/
END_HANDLER construct, use the E_RETURN(X) macro to return the value X, or the E_RTRN_VOID
macro to exit a function with no return value.
OS/390 Platform Concerns
The preceding error recovery mechanism applies on the OS/390 platform if the SAS/C compiler is used. In
cases where the OS/390 application is not compiled via SAS/C, it must use a different mechanism to
obtain the error status. This consists of three primary function calls:
DLExceptionFlag
Returns: ASInt32
DLExceptionFlag returns 0 if no exception was raised by the exception handler in the most-recentlycalled
Adobe PDF Library or DLI function. A non-zero return value indicates that an error was detected
while processing the last function call.
This error mechanism is destructive, in that the flag value is reset by accessing it with the
DLExceptionFlag function call.
NOTE: If DLExceptionFlag returns a non-zero return code, the return value
of the function in which the error occurred is undefined.

16.4 DLI Implementation and Reference Guide
DLExceptionCode
Returns: ASInt32
DLExceptionCode returns the last exception code set by an exception raised by an Adobe PDF Library
or DLI function. The code value returned by the DLExceptionCode function may be used to retrieve an
error message via a call to ASGetErrorString, as documented in the Adobe PDF Library Developer
Guide.
DLExceptionMessage
Returns: char*
DLExceptionMessage returns a non-NULL pointer if an additional message string was generated by
Adobe PDF Library or DLI when an exception was raised. This pointer may be NULL when an error is
raised if the Adobe PDF Library or DLI function does not supply the optional message string.
The application should call DLExceptionFlag after each Adobe PDF Library and DLI function call to
determine if an exception was raised. If the flag is non-zero, the application should use
DLExceptionCode and/or DLExceptionMessage to obtain additional information, then handle the
exception as appropriate.
These are the basic steps that should be followed:
1 Call the desired Adobe PDF Library/DLI function
2 Get the Exception Status by calling DLExceptionFlag
3 If DLExceptionFlag returns a non-zero value:
• Get additional error information (DLExceptionCode, ASGetErrorString, DLExceptionFlag)
• Handle exception as appropriate to the application (e.g. switch to a default font, flush the current
statement, etc.).

17
Samples
and Links
The following pages explain the full DLI sample
programs that have been compiled and tested, and which
accompany this release. They illustrate various aspects of
the usage of Adobe PDF Library and DLI.
17.1

17.2 DLI Implementation and Reference Guide
Running DLI Sample Applications
Notes on each specific DLI sample follow below. You are not required to test any or all of them, but if
you do, we suggest running them in the order given below.
Some samples require one or more command-line arguments, and will prompt for them if not given.
You should find the following DLI samples in individual subfolders under
C:\Datalogics\APDFL7.0.0\DLI\Samples (or similar). On Windows platforms, a Visual Studio
Solution file for all DLI samples can be found in C:\Datalogics\APDFL7.0.0\DLI\Samples\All
(see dli_samples.sln).
NOTE: Sample applications included in each release are subject to change. Some
samples may not appear in releases on certain platforms.
Activating Files-in-Memory
In the MultiDoc sample, adding the command-line keyword "MEMORY" will run the application using
Files-in-Memory methods. This will make use of memory work files instead of I/O processing to disk, and
as a result should show improved processing times.
Within the sample, "MEMORY" is recognized as an indicator which then determines the calling arguments
for dlpdfinit, as shown in the following typical excerpt, where FileSystemType is defined as
eMemFileSys if MEMORY was found in the calling arguments for the application:
switch (FileSystemType)
{
case eStdFileSys:
pdfInstance=dlpdfinit(&DataRec, NULL, NULL);
break;
case eMemFileSys:
pdfInstance=dlpdfinit(&DataRec, dlpdfmemfilesys(), NULL);
break;
default:
printf("Unknown File System requested.");
return 8;

Samples and Links 17.3
HelloDLI
This application is similar to the Adobe PDF Library sample HeloWrld, generating a single page reading
"Hello DLI!" via DLI methods. Comparing HelloDLI.c to HeloWrld.c can show the simplified
coding available via DLI for performing common Adobe PDF Library tasks.

17.4 DLI Implementation and Reference Guide
Paths
This sample shows how to draw various simple shapes using DLI, and how to draw PDF paths with DLI.
A path in PDF, like in PostScript, consists of a series of movements from a starting point. A path is filled
with the fill color in the graphics state, and the lines connecting the movements of the path are
drawn with the stroke color in the graphics state. This sample also demonstrates some common
matrix operations, such as rotations and translations of paths.
For common shapes, DLI has shortcut operations to create paths, such as for rectangles and arcs.
This sample also demonstrates the use of CMYK color spaces. For an example of using RGB color spaces,
please see “Annotations” on page 17.12.

Samples and Links 17.5
Graphics
This sample demonstrates how to imports graphics from DLI-supported graphic file formats ( RAW, EPS,
PNG, JPEG/JPG, GIF, TIFF and PDF ) into a PDF document, how to scale these to the individual graphic's
design width and height, and how to place these on the page. Details on some graphic formats follow
below.
NOTE: An Encapsulated PostScript (EPS) image written to an output PDF file will
be present in the file, but will not display when viewed in PDF output. It will
appear when produced as PostScript (e.g. to a PostScript printer). You may need to
define EPSF_ENABLED in this example in order to process the EPS sample image.

17.6 DLI Implementation and Reference Guide
EPS
EPS graphics will not show when viewing the output PDF graphic; EPS graphics will only print, and only
when printing to a PostScript device. These graphics are stored in PDF as comments.
If you need to convert EPS files to PDF, please contact Datalogics for information on licensing Adobe
Normalizer Server, or use Adobe Distiller.
PDF
PDF pages are imported as graphical elements, and some items such as annotations and bookmarks are
not imported with the PDF file. Additionally, Acrobat Forms are not imported at this time. PDF images
created with the dlpdfimagecreatefromfile call are created from the first page; to import other
pages, use the dlpdfimagecreatefrompdf function.
PNG
Alpha channels are currently flattened into a 1-bit plane (visible/invisible) to facilitate placement using a
threshhold algorithm. This threshhold cannot be changed at this time.
TIFF
Only the first page of a multipage TIFF image will be processed at this time.
Alpha channels are currently flattened into a 1-bit plane (visible/invisible) to facilitate placement using a
threshhold algorithm. This threshhold cannot be changed at this time.
BMP
NOTE: Some BMP images with LZW skip markers may not embed properly. If
possible, avoid images with LZW skip markers.
For all raster images, DLI attempts to do as little image alteration as possible, though usually some image
processing is required to create stream information suitable for inclusion in PDF files.
NOTE: All images are cached by DLI by filename. Applications should not attempt
to change image file data during a job, as unpredictable or unexpected results
could occur.

Samples and Links 17.7
Encrypt
This produces a simple PDF document (a blank page with a red square), applying encryption to the output
PDF file, requiring one of two passwords for viewing:
When prompted by Adobe Acrobat or Adobe Reader, entering the user password "ValidUser" (casesensitive,
must be entered as shown) will open the document for viewing and printing.
Entering the owner password "DocOwner" will open the document for viewing and printing as before,
but will also allow current protection to be modified or removed.
Compare the action under either password when following the "File->SaveAs..." menu and
attempting to change the Security settings on the new file to be created. The owner password must be

17.8 DLI Implementation and Reference Guide
given before Security settings can be viewed or modified:

Samples and Links 17.9
FontFaux
This sample demonstrates how to create a font for use in a PDF file when the font is not present on the
system on which an application is running, and illustrates the meanings of the various font attributes
available to the user in the PDEFontAttrs structure. It demonstrates font fauxing techniques for
simulating the appearance of various referenced fonts which are neither embedded in the document nor
available on the viewing user machine.
The sample creates a number of simulated ("faux") fonts, each with different attributes. When the created
PDF document is opened, Adobe Acrobat or Adobe Reader will substitute a font for that used by the PDF
file. The document contains enough information for each font that a viewer can create a lookalike font.

17.10 DLI Implementation and Reference Guide
That lookalike will not be suitable for precise typography, but should be acceptable for web-delivery
documents.
NOTE: Only fonts using characters in the Adobe standard encodings (Standard,
WinAnsi and MacRoman) can be fauxed correctly. Attempting to do this with
fonts containing characters outside the range of standard encodings will result in
a bad display. Set the PD_STD_ENCODING font flag in the PDEFontAttrs
structure to indicate that the font uses only "standard" characters.
FontVerification
This application is useful for creating a quick-reference table of fonts available to your application. It
compiles a directory of all fonts found in the current resource listing, including a hyperlinked Table of
Contents and a sample listing, font dump and encoding grid page for every font found. It demonstrates

Samples and Links 17.11
basic font creation using DLI, and displays the fonts which the Adobe PDF Library was able to locate on
the host system.
NOTE: On machines with lengthy resource listings (i.e. numerous fonts available),
this application may take a minute or two to complete. Some time may elapse
before any completion messages appear onscreen.
For each single-byte Type 1 or TrueType font found, a font will be created in DLI with the same name and
type. Each character of a target encoding will then be displayed in a grid formation, to verify proper font
creation. Fonts of other types (e.g. MultiMaster fonts, Type 0 fonts) will be noted in the Table of
Contents, but not used for font creation.
See the source code comments in Fontverification.c for more information on how the resource lists
are compiled, and what options are available for maintaining them and controlling how they are
compiled.

17.12 DLI Implementation and Reference Guide
Annotations
This sample demonstrates types of PDF annotations for which DLI provides output support. (Other
annotation types can be done at the COS layer; see the sample “AcroForm” on page 17.15 for more
details.) This sample also shows how to manipulate RGB color spaces to produce colored text and path
elements.
Annotations include features such as "sticky notes" (open or closed), bookmarks and hyperlinks (enabling
the user to jump to other places in the current document, to other PDF documents or other files, or to
Internet addresses elsewhere).
The first two pages of output demonstrate links to other documents and to other pages within the same
document. (e.g. a link on Page 1 will take you to Page 2, and a link on Page 2 will take you to Page 1.)
Notice that the link can specify not only the destination being pointed to but also the type of screen
display to use when you arrive. For example, Page 1’s "Link to page 2," if selected, will take you to a fullpage
view of Page 2. However, Page 2’s "Link to page 1," if selected, will zoom in on its Page 1 target note
to fill the entire screen.
Finally, the third page demonstrates two methods of visually cueing the reader to embedded hyperlinks:
boxing the hyperlink area with an outline rule, or generating text of a different color. In either case,
clicking on the links should trigger a jump to the Datalogics website at http://
www.datalogics.com.

Samples and Links 17.13
memFiles
This sample demonstrates use of the Datalogics Files-in-Memory file system. Using this filesystem, a DLI
user can create ASFile objects from a memory buffer , enabling creation of images from memory such as
database BLOBs (Binary Large OBjects). The filesystem also allows the user to write PDF files to memory
buffers, which can then be retrieved, written to other files or manipulated in various ways.
Temporary files are also written to the Files-in-Memory filesystem, if it is active at the time the temporary
file is opened. This usually occurs when a document is created.
MultiDoc
This sample controls the generation of multiple documents from a single run of the application. It has two
required arguments:
• Argument 1 must be the number of documents to produce.
• Argument 2 must be the number of pages per document to produce.
Several additional, optional arguments may also be used to vary the output as desired, such as MEMORY
for Files-in-Memory processing, or PSTOUT or PDFOUT keywords to generate PostScript or PDF output
respectively. (This sample is mainly intended to demonstrate program operation, not text output.) Other
command-line arguments can also be given in order to test output variations or application performance.
Run the sample with no command-line arguments for a short usage message; see the source code file
MultiDoc.c for more details.

17.14 DLI Implementation and Reference Guide
NestedPDF
This sample generates a set of output documents, in which a pair of PDF graphic files are in turn included
within a larger PDF file, repeating the process several times. It demonstrates the ability of the interface to
embed PDF files as graphics, in the presence of conflicting names, to show PDF Form XObject name
scoping rules.
This sample also demonstrates how to create patterns in DLI for painting content areas with a
background.

Samples and Links 17.15
AcroForm
This sample demonstrates how to create an Acrobat Form using the Adobe PDF Library and DLI,
creating a number of different field types using COS-layer object manipulation.

17.16 DLI Implementation and Reference Guide
SignDoc
This sample demonstrates how to place a digital signature into a PDF file generated by DLI. This
signature will be compatible with the Adobe self-sign plugin, and will contain an x.509 certificate.
NOTE: Included in this project is a file "rsasign.cpp", containing a very slow
implementation of the RSA encryption algorithm. Datalogics does not recommend
using this implementation as a basis for Production code.
DLI can also produce signatures with PCKS #7-format certificates, for the Adobe self-sign plugin and the
VeriSign signature plugin. Customers wishing to do this will follow a slightly different path, and must be
able to generate these certificates.
This sample uses a dummy x.509 certificate; the key pair used to generate this certificate is stored in the
sample.key.info file in the @Data directory.
As of Adobe PDF Library v6.1.1 and DLI v3.0.23, this sample application produces digital signatures
compatible with the Adobe Acrobat v5 validation plug-in. In later releases, DLI will be upgraded to
generate digital signatures compatible with Adobe Acrobat v6 or higher. You should also be aware that
this sample takes a long time to run.

Samples and Links 17.17
psOutput
This sample demonstrates generation of PostScript from the Adobe PDF Library and DLI. The sample
will create a new DLI document, add the pages (in reverse order) of a sample PDF file to the document,
and write a PostScript Level 2 output file. Additionally, an output PDF file will be written.
The application does all processing of the material in PDF form; the PostScript is generated by exporting
the PDF file created by the Adobe PDF Library and DLI to PostScript output. This sample shows how
one might write an application to convert PDF files to PostScript for printing or other processing.

17.18 DLI Implementation and Reference Guide
WideText
This sample demonstrates the DLI interface to the ICU functionality, used to typeset lines of text in
Unicode or other wide-text encodings. This functionality supercedes the Unicode functionality present in
the DLI v2.2.x series. This functionality is available for TrueType, TrueType Collection and OpenType
font files. This sample also demonstrates the use of DLPDFTEXT areas for placement of text.
NOTE: This sample uses ArialUnicodeMS and BitstreamCyberbit fonts, which are
not distributed with Adobe PDF Library or DLI. You must ensure that these fonts are
accessible (or that the sample is modified to use others instead) when running this
program, or problems may occur, as either a raised exception or an output
document containing blank glyphs.

A
DLI Reference Guide
This appendix defines methods available with DLI.
A.1

A.2 DLI Implementation and Reference Guide
dlpdfcontentarc (DLPDFCONTENT *Content,
PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1,
ASFixed Radius, ASFixed Angle1, ASFixed Angle2)
Return Value: void
Description
Parameters
Return Value
Included as an aid in transitioning from PostScript to PDF. It will
draw an arc centered at (X1,Y1), at a radius of Radius, from
Angle1 to Angle2, counter-clockwise, where the angles are
considered to be in degrees.
• DLPDFCONTENT *Content: Element structures, destroyed
when associated with a page or form; pointers to them
should not be used after that time.
• PDEGraphicState *gState: Color definitions; pathdrawing
line sizes and parameters.
• int PaintOp: A composite of text-display flags, set by
performing a bitwise OR with the desired combination of flag
values kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed X1
• ASFixed Y1
• ASFixed Radius
• ASFixed Angle1
• ASFixed Angle2
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentarcn,
dlpdfcontentarcto
All DLI supported platforms.

DLI Reference Guide A.3
dlpdfcontentarcn (DLPDFCONTENT *Content,
PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1,
ASFixed Radius, ASFixed Angle1, ASFixed Angle2)
Return Value: void
Description
Parameters
Return Value
This procedure is included as an aid in transitioning from Post-
Script to PDF. It will draw an arc centered at (X1,Y1), at a radius
of Radius, from Angle1 to Angle2, clockwise, where the
angles are considered to be in degrees.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• int PaintOp: A composite of flags which define how the
text will be displayed. It is set by performing a bitwise OR with
the desired combination of the Adobe PDF Library flag values
kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed X1
• ASFixed Y1
• ASFixed Radius
• ASFixed Angle1
• ASFixed Angle2
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentarc,
dlpdfcontentarcto
All DLI-supported platforms.

A.4 DLI Implementation and Reference Guide
dlpdfcontentarcto (DLPDFCONTENT *Content,
PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1,
ASFixed Radius, ASFixed X2, ASFixed Y2, ASFixed Xint, ASFixed Yint)
Return Value: void
Description
Parameters
Return Value
This is a convenience method to mimic the PostScript ArcTo
operator. It will locate the intersections of the line (X1,Y1)-
>(Xint,Yint), and (X2,Y2)->(Xint,Yint), and draw an arc of
the specified radius tangent to those two lines. The line segment
from (X1,Y1) to the arc will be drawn. Unlike the Post-
Script ArcTo operator, the segment from the tangent to
(X2,Y2) will also be drawn.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• int PaintOp: A composite of flags which define how the
text will be displayed. It is set by performing a bitwise OR with
the desired combination of the Adobe PDF Library flag values
kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed X1
• ASFixed Y1
• ASFixed Radius
• ASFixed X2
• ASFixed Y2
• ASFixed Xint
• ASFixed Yint
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentarc,
dlpdfcontentarcn
All DLI-supported platforms.

DLI Reference Guide A.5
dlpdfcontentcircle (DLPDFCONTENT *Content,
PDEGraphicState *gState, int PaintOp, ASFixed X, ASFixed Y,
ASFixed Radius)
Return Value: void
Description
Parameters
Return Value
This procedure is included as an aid in transitioning from Post-
Script to PDF. It will draw a circle centered at (X,Y) at a radius of
Radius.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• int PaintOp: A composite of flags which define how the
text will be displayed. It is set by performing a bitwise OR with
the desired combination of the Adobe PDF Library flag values
kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed X
• ASFixed Y
• ASFixed Radius
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentellipse
All DLI-supported platforms.

A.6 DLI Implementation and Reference Guide
dlpdfcontentclip (DLPDFCONTENT *Content, ASFixed *Path,
int PathLen, int EOClip)
Return Value: void
Description
Parameters
Return Value
Establish a clipping path. Note that clipping paths are not established
automatically for images, forms, or line drawings. Generally,
PDF images page more efficiently if there is no clipping
involved.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• ASFixed *Path: Specifies path; identical to
dlpdfcontentpath operand.
• int PathLen: Specifies path length; identical to
dlpdfcontentpath operand
• int EOClip: Should be FALSE (0) for a normal clip and
TRUE (1) for an even/odd clip.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentclipend,
dlpdfcontentpath
All DLI-supported platforms.
Technical Notes
1 Clipping paths are not established automatically for images, forms, or line drawings. Generally, PDF
images page more efficiently if there is no clipping involved.
2 A clipping region is considered a part of the content structure, and will be ended at the end of a
content structure. Clipping regions may be nested, but each nested region must fit within the previous
region. A clipping region can and should be ended as soon as possible, using the
dlpdfcontentclipend call.

DLI Reference Guide A.7
dlpdfcontentclipend (DLPDFCONTENT *Content)
Return Value: void
Description
Parameters
Return Value
This call is used to manually end a clipping region prior to the
end of the content structure. It should be called as soon as possible
after a clipping region is established.
DLPDFCONTENT *Content: Represents the content element.
These structures are destroyed when associated with a page or
form, and pointers to them should not be used after that time.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentclip
All DLI-supported platforms.

A.8 DLI Implementation and Reference Guide
dlpdfcontentcomment (DLPDFCONTENT *Content,
char *Comment)
Return Value: void
Description
Parameters
Return Value
This method will insert the specified text string as a comment, in
the order provided, into the content elements.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• char *Comment: A text string
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.
Technical Notes
1 The comment string will always be placed on a separate line, beginning with a percent sign (“%”)
provided by DLI to mark it as a comment.
2 The comment text must not contain a new line character, unless you provide a percent sign
immediately following it. (DLI provides only the initial percent sign for each comment. Follow-on
new lines within the comment text must contain their own starting percent sign for each comment line
of output.)
3 The content element must be valid: the comment pointer must point at a valid non-NULL, non-zero
length string.

DLI Reference Guide A.9
dlpdfcontentcreate (DLPDFDOC *Doc)
Return Value: DLPDFCONTENT*
Description
Parameters
Return Value
Creates a new content element with a rotation of zero degrees,
a position of (0,0) and scaling of (1,1).
DLPDFDOC *Doc: represents the document structure and the
current status of the document at all times.
DLPDFCONTENT*
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.10 DLI Implementation and Reference Guide
dlpdfcontentellipse (DLPDFCONTENT *Content,
PDEGraphicState *gState, int PaintOp, ASFixed X, ASFixed Y,
ASFixed RadiusH, ASFixed RadiusV)
Return Value: void
Description
Parameters
Return Value
This procedure is included as an aid in transitioning from Post-
Script to PDF. It will draw an ellipse centered at (X,Y), at a vertical
radius of RadiusV, and a horizontal radius of RadiusH.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• int PaintOp: A composite of flags which define how the
text will be displayed. It is set by performing a bitwise OR with
the desired combination of the Adobe PDF Library flag values
kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed X
• ASFixed Y
• ASFixed RadiusH
• ASFixed RadiusV
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentcircle
All DLI-supported platforms.

DLI Reference Guide A.11
dlpdfcontentfontskew (DLPDFCONTENT *Content,
ASFixedMatrix *Matrix)
Return Value: void
Description
Parameters
Return Value
Causes the font currently in effect for this content structure to
appear "twisted" according to the matrix supplied.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• ASFixedMatrix *Matrix
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.
Technical Notes
1 This may be used to simulate an italic or reverse-italic font using a Roman font.

A.12 DLI Implementation and Reference Guide
dlpdfcontentgstate (DLPDFCONTENT *Content,
const PDEGraphicState *newGState)
Return Value: void
Description
Parameters
Return Value
Sets the graphics state of the specified DLPDFCONTENT to that
of the PDEGraphicState. This may be done at any point during
content placement operations.
• DLPDFCONTENT* Content: Represents the document
structure and the current status of the document at all times.
• const PDEGraphicState *newGState
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.13
dlpdfcontentline (DLPDFCONTENT *Content, PDEGraphicState
*gState, int PaintOp, ASFixed X1, ASFixed Y1, ASFixed X2, ASFixed Y2)
Return Value: void
Description
Parameters
Return Value
This procedure will mark a line in the content, extending from
(X1,Y1) to (X2,Y2).
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• int PaintOp: A composite of flags which define how the
text will be displayed. It is set by performing a bitwise OR with
the desired combination of the Adobe PDF Library flag values
kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed X1: Start X-axis coordinate
• ASFixed Y1: Start Y-axis coordinate
• ASFixed X2: End X-axis coordinate
• ASFixed Y2: End Y-axis coordinate
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.14 DLI Implementation and Reference Guide
dlpdfcontentpath (DLPDFCONTENT *Content,
PDEGraphicState *gState, int PaintOp, ASFixed *Path, int PathLen)
Return Value: void
Description
Parameters
Return Value
This procedure will mark a path within the content.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• PDEGraphicState *gState
• int PaintOp: A composite of flags which define how the
text will be displayed. It is set by performing a bitwise OR with
the desired combination of the Adobe PDF Library flag values
kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed *Path: Specifies path
• int PathLen: Specifies path length
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.
Technical Notes
1 This is in all ways the same path as would be used by the Adobe PDF Library path operators. Such a
path may be created manually or by use of the Edit Layer of the Adobe PDF Library.
2 If created with the Adobe PDF Library, the pointer returned by PDEPathGetData is sufficient for
this call. The length returned by that call must be the number of entries in the list, not the size in bytes
of the list.

DLI Reference Guide A.15
dlpdfcontentpieslice (DLPDFCONTENT *Content,
PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1,
ASFixed Radius, ASFixed Angle1, ASFixed Angle2)
Return Value: void
Description
Parameters
Return Value
This procedure is included as an aid in graph construction. It will
draw a pie slice, centered at (X1,Y1), at a radius of Radius,
from Angle1 to Angle2, counter-clockwise, where the angles
are specified in degrees.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• int PaintOp: A composite of flags which define how the
text will be displayed. It is set by performing a bitwise OR with
the desired combination of the Adobe PDF Library flag values
kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed X1
• ASFixed Y1
• ASFixed Radius
• ASFixed Angle1
• ASFixed Angle2
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentpieslicen
All DLI-supported platforms.

A.16 DLI Implementation and Reference Guide
dlpdfcontentpieslicen (DLPDFCONTENT *Content,
PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1,
ASFixed Radius, ASFixed Angle1, ASFixed Angle2)
Return Value: void
Description
Parameters
Return Value
This procedure is included as an aid in graph construction. It will
draw a pie slice, centered at (X1,Y1), at a radius of Radius,
from Angle1 to Angle2, clockwise, where the angle is specified
in degrees.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• int PaintOp: A composite of flags which define how the
text will be displayed. It is set by performing a bitwise OR with
the desired combination of the Adobe PDF Library flag values
kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed X1
• ASFixed Y1
• ASFixed Radius
• ASFixed Angle1
• ASFixed Angle2
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentpieslice
All DLI-supported platforms.

DLI Reference Guide A.17
dlpdfcontentrect (DLPDFCONTENT *Content,
PDEGraphicState *gState, int PaintOp, ASFixed X, ASFixed Y,
ASFixed Width, ASFixed Height)
Return Value: void
Description
Parameters
Return Value
This procedure marks a rectangle in the content. It will be
located such that its lower left hand corner is at (X,Y).
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• int PaintOp: A composite of flags which define how the
text will be displayed. It is set by performing a bitwise OR with
the desired combination of the Adobe PDF Library flag values
kPDEFill, kPDEStroke, kPDEEoFill and
kPDEInvisible.
• ASFixed X: The X location of the rectangle.
• ASFixed Y: The Y location of the rectangle.
• ASFixed Width: The width of the rectangle. This may not
be specified as zero, but may be specified as a negative value,
which results in flopping the rectangle (i.e. right instead of
left).
• ASFixed Height: The height of the rectangle. This may
not be specified as zero, but may be specified as a negative
value, which results in flopping the rectangle (i.e. down
instead of up).
void
Exceptions
Header
Availability
dli.h
All DLI-supported platforms.

A.18 DLI Implementation and Reference Guide
dlpdfcontentreferenceform (DLPDFCONTENT *Content,
DLPDFFORM *Form, ASFixed X, ASFixed Y, ASFixed Rotate,
ASFixed ScaleX, ASFixed ScaleY)
Return Value: void
Description
Parameters
Return Value
Places a reference to the specified DLPDFFORM into the specified
content structure, with the lower left corner of the form
positioned at (X,Y), and with the specified rotation and scaling
factors.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• DLPDFFORM *Form
• ASFixed X: X coordinate for Form placement
• ASFixed Y: Y coordinate for Form placement.
• ASFixed Rotate: Degrees to rotate the form
counterclockwise
• ASFixed ScaleX: X-axis Scale Factor. “No scaling” is
represented by the value 1.
• ASFixed ScaleY: Y-axis Scale Factor. “No scaling” is
represented by the value 1.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.19
dlpdfcontentreferenceimage (DLPDFCONTENT *Content,
DLPDFIMAGE *Image, ASFixed X, ASFixed Y, ASFixed Rotate,
ASFixed ScaleX, ASFixed ScaleY)
Return Value: void
Description
Parameters
Return Value
This procedure places a copy of the referenced image into the
current content.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• DLPDFIMAGE *Image
• ASFixed X: The X-axis location of the rotation point
• ASFixed Y: The Y-axis location of the rotation point
• ASFixed Rotate: Amount of counterclockwise rotation in
degrees
• ASFixed ScaleX: X-axis Scale Factor
• ASFixed ScaleY: Y-axis Scale Factor
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfimagegetsize (New in DLI v2.2.5)
All DLI-supported platforms.
Technical Notes
1 The image will be placed so as to align its lower left hand corner with the given (X,Y) location, scaled
as per ScaleX and ScaleY, and rotated as per Rotate.
2 Image rotation, if any, always occurs about its origin, typically the lower-left corner of the image, and
the point of rotation is located by the given (X,Y) location.
3 The Scale Factors will determine the resulting size of the image. You need to know the original image
resolution and its intended size in order to determine whether a Scale Factor on either axis is required.
In DLI v2.2.5 or higher, the dlpdfimagegetsize method can retrieve image sizing data for you,
and dividing the intended print size by the file size for each dimension (delivered by
dlpdfimagegetsize) will yield a Scale Factor ratio which dlpdfcontentreferenceimage uses
to calculate the final output image size.
4 The typical scaling calculation using values returned by dlpdfimagegetsize would be to divide the
intended print size by the image size on each axis (e.g.
"dlpdfcontentreferenceimage(Content, Image, Int32ToFixed(72),

A.20 DLI Implementation and Reference Guide
Int32ToFixed(92), 0, ASFixedDiv(xPoints,Int32ToFixed(xRasters)),
ASFixedDiv(yPoints,Int32ToFixed(yRasters)));").
5 An image in which each pixel of each raster line represents one PDF unit of output will return the same
values for both image dimension (xRasters and yRasters) and print size (xPoints and
yPoints), and thus a Scale Factor of 1 on both axes.

DLI Reference Guide A.21
dlpdfcontentrotate (DLPDFCONTENT *Content, ASFixed Rotate)
Return Value: void
Description
Parameters
Return Value
Rotates all of the contents of a given content structure by the
specified amount.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• ASFixed Rotate: May be any amount, but will be reduced
to between 0 and 360 degrees. Considered to be in degrees
of counterclockwise rotation about the content structure’s
lower left corner.
void
Exceptions
Header
dli.h
Related Methods
Availability

A.22 DLI Implementation and Reference Guide
dlpdfcontentscale (DLPDFCONTENT *Content, ASFixed XScale,
ASFixed YScale)
Return Value: void
Description
Parameters
Return Value
Scales all of the content of a given content structure by the
specified amount.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• ASFixed XScale: X-axis scale factor, a positive number
greater than 0.0001.
• ASFixed YScale: Y-axis scale factor, a positive number
greater than 0.0001.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.23
dlpdfcontenttext (DLPDFCONTENT *Content, DLPDFFONT *Font,
char *str, PDEGraphicState *gState, PDETextState *tState,
ASFixed pointSize, ASFixed setWidth, ASFixed XPos, ASFixed YPos,
ASFixed Rotate)
Return Value: void
Description
Parameters
Parameters (Continued)
Return Value
Adds a NULL-terminated string of text to the content. It will be
placed such that the baseline of the left edge of the first character
aligns to the position (XPos,YPos) in points.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• DLPDFFONT *Font: Reflects the font. It is created by
dlpdffontcreate on a per-document basis, and may
only be used within the document it was created in. Fonts are
tracked within the document and destroyed when the
document is destroyed. Pointers to fonts are invalid after the
destruction of their document.
• char *str: Text string
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• PDETextState *tState: The current text state. This
should not be NULL. A zero-filled PDETextState
parameter is permitted.
• ASFixed pointSize: Point size
• ASFixed setWidth: Set width
• ASFixed XPos: Position along the X axis where the
baseline of the left edge of the first character will be aligned.
• ASFixed YPos: Position along the Y axis where the
baseline of the left edge of the first character will be aligned.
• ASFixed Rotate: Angle at which the baseline should
proceed, where zero is to the right and positive numbers
express counterclockwise rotation in degrees.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontenttextwidth,
dlpdfcontentwidetext,
dlpdfcontentwidetextwidth
All DLI-supported platforms.

A.24 DLI Implementation and Reference Guide
dlpdfcontenttextwidth (DLPDFFONT *Font, char *Text,
ASFixed SetWidth, PDETextState *TState)
Return Value: ASFixed
Description
Parameters
Return Value
Returns the width (in points) of the specified Text set in the
specified Font with the specified SetWidth. The fourth parameter
is an optional Current Text State, which may be NULL.
• DLPDFFONT *Font: The specified font
• char *Text: The specified text
• ASFixed SetWidth: The specified width
• PDETextState *TState: The current text state. This may
be NULL. A zero-filled PDETextState parameter is also
permitted.
ASFixed
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontenttext,
dlpdfcontentwidetext,
dlpdfcontentwidetextwidth
All DLI-supported platforms.

DLI Reference Guide A.25
dlpdfcontenttopage (DLPDFCONTENT *Content,
DLPDFPAGE *Page)
Return Value: void
Description
Parameters
Return Value
This procedure will make the markings placed into content a
part of the specified page. Following this call, the content structure
no longer exists; pointers to it are invalid and should not be
used.
• DLPDFCONTENT *Content: Represents the content
element. This structure is destroyed when associated with a
page or form, and pointers to them should not be used after
that time.
• DLPDFPAGE *Page: Represents a page. This structure is
tracked within the package and destroyed when the
document is destroyed. Pointers to this structure remain valid
until the document is destroyed.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.26 DLI Implementation and Reference Guide
dlpdfcontenttranslate (DLPDFCONTENT *Content, ASFixed X,
ASFixed Y)
Return Value: void
Description
Parameters
Return Value
Moves all the contents of a content structure by the specified
amounts.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• ASFixed X: The X-axis amount by which content structure
will be moved, in points. Positive X values move right;
negative X values move left.
• ASFixed Y: The Y-axis amount by which content structure
will be moved, in points. Positive Y values move up; negative
Y values move down.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.27
dlpdfcontentusefillpattern (DLPDFCONTENT *Content,
DLPDFPATTERN *Pattern)
Return Value: void
Description
Parameters
Return Value
Applies the fill pattern.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• DLPDFPATTERN *Pattern: If this is NULL, the patterned
color space will be turned Off.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpatterncreate,
dlpdfcontentusestrokepattern
All DLI-supported platforms.

A.28 DLI Implementation and Reference Guide
dlpdfcontentusestrokepattern (DLPDFCONTENT *Content,
DLPDFPATTERN *Pattern)
Return Value: void
Description
Parameters
Similar to dlpdfcontentusefillpattern, but strokes
instead of filling.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• DLPDFPATTERN *Pattern
Return Value
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentusefillpattern
All DLI-supported platforms.

DLI Reference Guide A.29
dlpdfcontentwidetext (DLPDFCONTENT *Content, DLPDFFONT
*Font, char *str, int Length, PDEGraphicState *gState, PDETextState
*tState, ASFixed PS, ASFixed SW, ASFixed X, ASFixed Y, ASFixed Rotate)
Return Value: void
Description
Parameters
Return Value
Same as dlpdfcontenttext, but permits Unicode and
MultiByte text.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• DLPDFFONT *Font
• char *str: A text string
• int Length
• PDEGraphicState *gState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
• PDETextState *tState: The current text state. This may
be NULL. A zero-filled PDETextState parameter is also
permitted.
• ASFixed PS: Point Size scale factor along the Y axis
(vertical). 1 = no scaling (2 = double the original size, 0.5 =
½ the original size, etc...)
• ASFixed SW: Set Width scale factor along the X axis
(horizontal). 1 = no scaling.
• ASFixed X: X coordinate of the lower left corner of the
bounding box for the text
• ASFixed Y: Y coordinate of the lower left corner of the
bounding box for the text
• ASFixed Rotate: Angle of rotation. 0 = no rotation.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontenttext,
dlpdfcontenttextwidth,
dlpdfcontentwidetextwidth
All DLI-supported platforms.
Technical Notes
1 Double-byte NULL values acting as Unicode string terminators are not required, and, if present, are not
included in any Unicode string length calculations.

A.30 DLI Implementation and Reference Guide
dlpdfcontentwidetextwidth (DLPDFFONT *Font, char
*string, int Length, ASFixed SetWidth, PDETextState *TState,
PDEGraphicState *GState)
Return Value: ASFixed
Description
Parameters
Return Value
Same as dlpdfcontenttextwidth, but permits multi-byte
(Unicode) text.
• DLPDFFONT *Font
• char *string
• int Length
• ASFixed SetWidth
• PDETextState *TState: The current text state. This
should not be NULL. A zero-filled PDETextState
parameter is permitted.
• PDEGraphicState *GState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path.
ASFixed
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontenttext,
dlpdfcontenttextwidth,
dlpdfcontentwidetext
All DLI-supported platforms.
Technical Notes
1 Double-byte NULL values acting as Unicode string terminators are not required, and, if present, are not
included in any Unicode string length calculations.

DLI Reference Guide A.31
dlpdfdocasciips (DLPDFDOC *Doc)
Return Value: void
Description
Parameters
Return Value
This method supports creation of PostScript output suitable for
transmission through channels and to devices which do not
accept binary data. Most PostScript printers cannot properly
process binary PostScript input, although Distiller and most print
spoolers will accept binary PostScript data.
DLPDFDOC *Doc: Represents the document structure and the
current status of the document at all times.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.32 DLI Implementation and Reference Guide
dlpdfdoccomplete (DLPDFDOC *Doc)
Return Value: void
Description
Parameters
Return Value
Completes the page tree for a document and creates specified
thumbnails. It is called internally by dlpdfdocwritepdf and
dlpdfdocwritePS, and may be manually called to write the
document using other interface elements (e.g. writing to a custom
file system), or as a method of imaging pages prior to writing
the document.
DLPDFDOC *Doc: Represents the document structure and the
current status of the document at all times.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocwritepdf,
dlpdfdocwritePS
All DLI-supported platforms.

DLI Reference Guide A.33
dlpdfdoccompress (DLPDFDOC *Doc)
Return Value: void
Description
Parameters
Return Value
Turns compression On (by default, it is Off) for text streams used
within the PDF document. When on, Flate compression will be
used on all textual content, images and forms. This method
should be called before any content is placed onto a page. Content
placed prior to this call will not be compressed.
DLPDFDOC *Doc: Represents the document structure and the
current status of the document at all times.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.34 DLI Implementation and Reference Guide
dlpdfdoccosdoc (DLPDFDOC *Doc)
Return Value: CosDoc
Description
Parameters
Return Value
Used with the COS layer of the Adobe PDF Library to accomplish
functions outside DLI.
DLPDFDOC *Doc: Represents the document structure and the
current status of the document at all times.
CosDoc: Reflects the constructed document
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocpddoc,
dlpdfdoccomplete
All DLI-supported platforms.
Technical Notes
1 The COS form of the document must not be used in any way that accesses pages prior to writing the
document or calling dlpdfdoccomplete. Prior to those calls, the page tree is not complete.

DLI Reference Guide A.35
dlpdfdoccreate (DLPDFINSTANCE *instance)
Return Value: DLPDFDOC *
Description
Parameters
Creates a new, empty document.
DLPDFINSTANCE *instance: The DLPDFINSTANCE to use
for the document
Return Value DLPDFDOC *
Exceptions
Header
Related Methods
Availability
genErrBadParam
dli.h
dlpdfdocdestroy,
dlpdfdocsetpsname,
dlpdfdocwritePS (See Technical Notes below)
All DLI-supported platforms.
Technical Notes
1 Processing is much faster if the Adobe PDF Library is not invoked; however, the Library must be
invoked if PDF and PostScript are to be created.
2 See the Adobe API Reference Guide for information on Adobe PostScript support.
3 As of DLI v3.0, this call no longer accepts a PostScript filename. (Use dlpdfdocsetpsname, or
supply one to dlpdfdocwritePS.) The PDFNeeded flag has been removed; PDF processing is
always performed.

A.36 DLI Implementation and Reference Guide
dlpdfdoccreatesignature (DLPDFDOC *Doc,
dlpdfsighandler sigType, char *nameStr, char *reasonStr,
char *locationStr)
Return Value: DLPDFSIGNATURE *
Description
Parameters
This call creates a digital signature object for the DLI document
being created.
• DLPDFDOC *Doc: The document for which the signature
object will be created
• dlpdfsighandler sigType: The signature type, one of
dlpdfsigacrox509, dlpdfsigacropkcs7 or
dlpdfsigverisign; see Technical Notes below.
• char *nameStr: (Optional) Signatory Name
• char *reasonStr: (Optional) Reason for signing (e.g.
Initial Release; Document Revision)
• char *locationStr: (Optional) Location of the signatory
Return Value DLPDFSIGNATURE *
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocsetsignatureappearance
dlpdfpageplacesignature
All DLI-supported platforms.
Technical Notes
1 The sigType is one of:
• dlpdfsigacrox509 (Adobe self-sign plug-in compatible with an x.509 v3 certificate)
• dlpdfsigacropkcs7 (Adobe self-sign plug-in compatible with a PKCS #7 certificate)
• dlpdfsigverisign (VeriSign signature plug-in compatible with a PKCS #7 certificate)

DLI Reference Guide A.37
dlpdfdocdestroy (DLPDFDOC *Doc)
Return Value: void
Description
Parameters
Return Value
Destroys the specified document, releasing all resources used in
the document.
DLPDFDOC *Doc: represents the document structure and the
current status of the document at all times.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdoccreate,
dlpdfinstancesetgrcachelimits
All DLI-supported platforms.
Technical Notes
1 All documents should be destroyed before terminating DLI.
2 A pointer to a DLPDFDOC structure is invalid and should not be used after calling dlpdfdocdestroy
for that structure.
3 The collection of information regarding where elements lie within a document is the responsibility of
the composition engine. DLI cannot provide assistance with this.
4 If dlpdfinstancesetgrcachelimits had been set previously, the graphics cache size is evaluated
at this time, and graphics are purged if the cache size exceeds its preset high-water mark limit.
5 If applicable, dlpdfdocdestroy removes the Files In Memory file representing the DLI document if
no handle has been acquired to the file in memory.

A.38 DLI Implementation and Reference Guide
dlpdfdocembedfonts (DLPDFDOC *Doc)
Return Value: void
Description
Parameters
Return Value
This call will set the input document to embed and subset all
fonts which are present on the system when created, regardless
of the font call used to create them. Fonts created with dlpdffontcreateembedded
or dlpdffontcreatewithmetricsembedded
with the Subset parameter set to
FALSE will be fully embedded after calling this function (license
permitting; see Technical Notes below).
DLPDFDOC *Doc: The document for which to embed all fonts
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdffontcreateembedded,
dlpdffontcreatewithmetricsembedded
All DLI-supported platforms.
Technical Notes
1 If a font is available but not licensed for embedding, it will be created as a referenced font rather than
an embedded font. An exception is not returned for this condition, but the NotEmbedded flag of the
DLPDFFONT structure can be inspected after the dlpdfdocembedfonts call, if desired.

DLI Reference Guide A.39
dlpdfdocencrypt (DLPDFDOC *Doc, char *UserPW,
char *OwnerPW, PDPerms Permissions)
Return Value: void
Description
Parameters
Return Value
Applies the Adobe PDF Library standard security mechanism to
the document, using the permissions specified in the Permissions
parameter as outlined in the Acrobat Core API Reference
Manual in the PDPerms definition on page 2101.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• char *UserPW: (Case sensitive) string for User Password
• char *OwnerPW: (Case sensitive) string for Owner Password
• PDPerm Permissions
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocsetencryptkeylen
Adobe PDF Library v4.05 and higher; all DLI-supported platforms.
Technical Notes
1 Both Owner Password and User Password are case-sensitive. Either password will allow viewing of the
document, but only the Owner can modify its Security settings.
2 This call may be made at any time prior to dlpdfdocwritepdf.

A.40 DLI Implementation and Reference Guide
dlpdfdoclinearize (DLPDFDOC *Doc)
Return Value: void
Description
Parameters
Return Value
Instructs DLI to linearize any PDF output created from this document,
regardless of the setting of the linearization flag used at
document output time.
DLPDFDOC *Doc: Represents the document structure and the
current status of the document at all times.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.
Technical Notes
1 This is included in support of document processing systems which know the desired result of
document creation at the start of document processing, but which may not retain that knowledge until
the end of processing.

DLI Reference Guide A.41
dlpdfdocmakethumbnails (DLPDFDOC *Doc)
Return Value: void
Description
Parameters
Return Value
Instructs the application to create thumbnail page images. These
will be added to all pages when the file is written to PDF.
DLPDFDOC *Doc: Represents the document structure and the
current status of the document at all times.
void
Exceptions
Header
dli.h
Related Methods
Availability
Adobe PDF Library v4.05 and later; all DLI-supported platforms.

A.42 DLI Implementation and Reference Guide
dlpdfdocnameadd (DLPDFDOC *Doc, char *TreeName, char
*Name, CosObj Dest)
Return Value: void
Description
Parameters
Return Value
Adds a new name and an associated destination (as a COS
structure) to the name tree, which will be named as defined in
TreeName. “Dests” is the default TreeName value, which is
assumed if NULL is used.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• char *TreeName: TreeName string, or NULL for default
TreeName.
• char *Name: Name string
• CosObj Dest
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocnamefind
All DLI-supported platforms.

DLI Reference Guide A.43
dlpdfdocnamefind (DLPDFDOC *Doc, char *TreeName, char
*Name,)
Return Value: CosObj
Description
Parameters
Return Value
Locates a name in the tree, and returns its associated COS structure.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• char *TreeName: TreeName string, or NULL for default
TreeName
• char *Name: Name string
CosObj
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocnameadd
All DLI-supported platforms.

A.44 DLI Implementation and Reference Guide
dlpdfdocoutline (DLPDFDOC *Doc)
Return Value: DLPDFOUTLINE*
Description
Parameters
Return Value
Returns a pointer to the root outline node. This node contains
no text; it is used simply as a container for nodes at the root
layer. If there are no outlines, this pointer will be NULL.
DLPDFDOC *Doc: Represents the document structure and the
current status of the document at all times.
DLPDFOUTLINE*
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.45
dlpdfdocoutlineadd (DLPDFDOC *Doc, DLPDFOUTLINE *Parent,
DLPDFOUTLINE *Before, char *Text, int Open, long PageNumber, char
*Fit, ASFixedRect *Where, ASFixed Zoom)
Return Value: DLPDFOUTLINE*
Description
Parameters
Return Value
Creates an outline structure within the document specified.
• DLPDFDOC *Doc: Specifies the document in which the new
outline will reside
• DLPDFOUTLINE *Parent: If specified, the new outline
structure will be contained within the parent. If not specified,
the new outline structure will be placed within the root node.
• DLPDFOUTLINE *Before: If specified, the new outline
entry will be positioned directly after the previous outline
entry given. If not specified, the new entry will be created as
the last within the parent or root.
• char *Text: Text that will appear in the displayed outline
and which must be specified
• int Open: A Boolean operator: if TRUE, the entry will be
open and its children will be displayed; if FALSE, it will be
closed.
• long PageNumber: The zero-relative number of the page
to which this link connects
• char *Fit: valid PDF fit type expressed as a string.
• ASFixedRect *Where: location of the rectangle to be
displayed. Only portions are used, based on the Fit Type
specified in Fit.
• ASFixed Zoom: factor by which the size of the display
should be increased or decreased.
DLPDFOUTLINE*: Internal structure that reflects the outline
entry
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocoutlineaddfromname,
dlpdfdocoutlinecosobj,
dlpdfdocoutlinefirst,
dlpdfdocoutlinelast,
dlpdfdocoutlinenext,
dlpdfdocoutlineparent,
dlpdfdocoutlineprev
All DLI-supported platforms.

A.46 DLI Implementation and Reference Guide
Technical Notes
1 Only internal destinations (within the same document) are supported by this method.
2 Valid Fit Type values are “Fit”, “FitH”, “FitV”, “FitBH”, “FitBV”, “FitR”, “FitB”, and
“XYZ”. See the Adobe PDF Library Reference Guide for explanations of the meaning of each fit type
and which values of rectangle and zoom are used for each.
3 If nested outlines are desired, these structures should be saved by the application. They will be
destroyed automatically when the document is destroyed and may not be accessed after that time.
Their contents must not be modified, as they are maintained within the package.
4 Zero values in the rectangle will behave as PDViewNull values, as will a zero value for Zoom.
5 The most common values used are XYZ as the fit type, Zero for Zoom, and the (X,Y) coordinates of
the upper left hand edge of the desired target text in Where.top and Where.left. This will change
to the target page and position the specified text so it is within the display window, leaving the
Magnification factor where the user last set it.

DLI Reference Guide A.47
dlpdfdocoutlineaddfromname (DLPDFDOC *Doc,
DLPDFOUTLINE *Parent, DLPDFOUTLINE *Before, char *Text, int Open,
char *DestName)
Return Value: DLPDFOUTLINE*
Description
Parameters
Return Value
Exceptions
Header
Related Methods
Availability
Adds a new outline entry using the named destination, rather
than a specified document.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• DLPDFOUTLINE *Parent
• DLPDFOUTLINE *Before
• char *Text: Text string
• int Open
• char *DestName: String for destination name
DLPDFOUTLINE*
dlpdfdocoutlineadd,
dlpdfdocoutlinecosobj,
dlpdfdocoutlinefirst,
dlpdfdocoutlinelast,
dlpdfdocoutlinenext,
dlpdfdocoutlineparent,
dlpdfdocoutlineprev
dli.h
dlpdfdocoutlineadd
All DLI-supported platforms.

A.48 DLI Implementation and Reference Guide
dlpdfdocoutlinecosobj (DLPDFOUTLINE *Outline)
Return Value: CosObj
Description
Parameters
Return Value
Returns the COS structure that is the outline entry. It may be
modified by the user to accomplish actions other than those
specified by this package.
DLPDFOUTLINE *Outline
CosObj
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocoutline
All DLI-supported platforms.
Technical Notes
1 Only the Title, Dest, A (Action), or AA (Additional Action) keys should be modified. Modification
of other keys may result in invalid documents.

DLI Reference Guide A.49
dlpdfdocoutlinefirst (DLPDFOUTLINE *Outline)
Return Value: DLPDFOUTLINE*
Description
Parameters
Return Value
Returns a pointer to the first child outline of the specified outline
DLPDFOUTLINE *Outline
DLPDFOUTLINE*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocoutlinelast,
dlpdfdocoutlinenext,
dlpdfdocoutlineparent,
dlpdfdocoutlineprev
All DLI-supported platforms.
Technical Notes
1 If the specified outline contains no children, this method will return a NULL.

A.50 DLI Implementation and Reference Guide
dlpdfdocoutlinelast (DLPDFOUTLINE *Outline)
Return Value: DLPDFOUTLINE*
Description
Parameters
Return Value
Returns a pointer to the last child outline of a specified outline
node. If the node contains no children, this method will return a
NULL.
DLPDFOUTLINE *Outline
DLPDFOUTLINE*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocoutlinefirst,
dlpdfdocoutlinenext,
dlpdfdocoutlineparent,
dlpdfdocoutlineprev
All DLI-supported platforms.

DLI Reference Guide A.51
dlpdfdocoutlinenext (DLPDFOUTLINE *Outline)
Return Value: DLPDFOUTLINE*
Description
Parameters
Return Value
Returns a pointer to the outline node that follows the specified
node
DLPDFOUTLINE *Outline
DLPDFOUTLINE*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocoutlinefirst,
dlpdfdocoutlinelast,
dlpdfdocoutlineparent,
dlpdfdocoutlineprev
All DLI-supported platforms.
Technical Notes
1 If the specified node is the last within its parent, this method will return a NULL.

A.52 DLI Implementation and Reference Guide
dlpdfdocoutlineparent (DLPDFOUTLINE *Outline)
Return Value: DLPDFOUTLINE*
Description
Parameters
Return Value
Returns a pointer to the parent of the specified node
DLPDFOUTLINE *Outline
DLPDFOUTLINE*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocoutlinefirst,
dlpdfdocoutlinelast,
dlpdfdocoutlinenext,
dlpdfdocoutlineprev
All DLI-supported platforms.
Technical Notes
1 If this node is the root node, this method will return a NULL.

DLI Reference Guide A.53
dlpdfdocoutlineprev (DLPDFOUTLINE *Outline)
Return Value: DLPDFOUTLINE*
Description
Parameters
Return Value
Returns a pointer to the outline node that precedes this node
within its container.
DLPDFOUTLINE *Outline
DLPDFOUTLINE*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocoutlinefirst,
dlpdfdocoutlinelast,
dlpdfdocoutlinenext,
dlpdfdocoutlineparent
All DLI-supported platforms.
Technical Notes
1 If this is the first node in the container, this node will return a NULL.

A.54 DLI Implementation and Reference Guide
dlpdfdocpddoc (DLPDFDOC *Doc)
Return Value: PDDoc
Description
Parameters
Return Value
Used with the PD Layer of the Adobe PDF Library to accomplish
functions outside of DLI.
DLPDFDOC *Doc represents the document structure and the
current status of the document at all times.
PDDoc reflects the constructed document.
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdoccosdoc
All DLI-supported platforms.
Technical Notes
1 The PDDoc must not be used in any way prior to calling dlpdfdocwritepdf, dlpdfdocwritePS
or dlpdfdoccomplete. Prior to those calls, the page tree is not complete.

DLI Reference Guide A.55
dlpdfdocsetdocinfo (DLPDFDOC *Doc, ASAtom Field,
char *Value)
Return Value: void
Description
Parameters
Return Value
Creates or replaces an entry in the document’s DocInfo directory
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• ASAtom Field: Any name is valid, although only certain
names have meaning to PDF readers
• char *Value: A string, encoded as PDFDocEncoding
values
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.
Technical Notes
1 This method may be called at any time.

A.56 DLI Implementation and Reference Guide
dlpdfdocsetencoding (DLPDFDOC *Doc, ASAtom Encoding)
Return Value: void
Description
Parameters
Return Value
Exceptions
Header
Sets the default encoding for fonts used within the document.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• ASAtom Encoding: Valid values are ASAtoms containing
“MacRomanEncoding”, “MacExpertEncoding” or
“WinAnsiEncoding”. A NULL ASAtom, as returned by the
ASAtomNull function, is also allowed, meaning
“Standard” encoding
void
genErrBadParam: Raised if any encoding value other than the
values specified above (or a NULL document pointer) is passed
to this function.
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.57
dlpdfdocsetencryptkeylen (DLPDFDOC *Doc, unsigned int
KeyLenBytes)
Return Value: void
Description
Parameters
Return Value
Exceptions
Header
Related Methods
Availability
Enables variable-length encryption keys as supported by the
Adobe PDF Library.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• unsigned int KeyLenBytes: The desired encryption key
length in bytes, from 5 to 15 inclusive
void
This function itself throws no specific exceptions, but the underlying
functions within the Adobe PDF Library may throw exceptions.
dli.h
dlpdfdocencrypt
All DLI-supported platforms.
Technical Notes
1 For more information on Encryption, please refer to the beginning of section 3.5 in the Adobe PDF
Specification Guide. For information on PDDocSetNewSecurityData and
StdSecurityDataRec, see the Adobe Core API Reference Guide.
2 This function can be called to set the length of the encryption key before a call to dlpdfdocencrypt,
if the application requires an encryption key length other than the original 40-bit length of previous
versions.
3 This function is optional if the original 40-bit key length will be used. Subsequent calls to
dlpdfdocencrypt will use the number of bytes specified in the call to
dlpdfdocsetencryptkeylen. If the key length has not been set previously, the standard 5-byte
value is used as the default.
4 For applications generating multiple documents, dlpdfdocsetencryptkeylen must be called for
each document for which an encryption key length other than the standard 5-byte value is desired.

A.58 DLI Implementation and Reference Guide
dlpdfdocsetpdfname (DLPDFDOC *Doc, char *Name)
Return Value: void
Description
Parameters
Return Value
Saves the desired location of a PDF file which results from this
document.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• char *Name: This name will be used in place of any name
specified in a dlpdfdocwritepdf procedure call.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocsetpsname
All DLI-supported platforms.
Technical Notes
1 This is included in support of document processing systems which know the desired result of
document creation at the start of document processing, but which may not retain that knowledge until
the end of processing.

DLI Reference Guide A.59
dlpdfdocsetpsname (DLPDFDOC *Doc, char *Name)
Return Value: void
Description
Parameters
Return Value
Saves the desired location of a PostScript file which results from
this document.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• char *Name: This name will be used in place of any name
specified in a dlpdfdocwritePS procedure call.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocsetpdfname
All DLI-supported platforms.
Technical Notes
1 This is included in support of document processing systems which know the desired result of
document creation at the start of document processing, but which may not retain that knowledge until
the end of processing.

A.60 DLI Implementation and Reference Guide
dlpdfdocsetsignatureappearance (DLPDFDOC *Doc,
DLPDFSIGNATURE *Sig, DLPDFFORM *background, DLPDFFORM
*unverified, DLPDFFORM *signature, DLPDFFORM *textSigInfo)
Return Value: void
Description
Parameters
Return Value
This call sets the appearance layers for the digital signature to
the supplied DLPDFFORM values. This call is optional. For an
invisible digital signature, do not call this function. All the signature
layers are also optional. Blank layers will be used for any
omitted signature appearance layers.
• DLPDFDOC *Doc: document for which the signature object
will be created
• DLPDFSIGNATURE *Sig: signature to which appearance
settings will be assigned
• DLPDFFORM *background: bottom-most layer of the
digital signature appearance
• DLPDFFORM *unverified: layer displayed when the
signature has not been verified
• DLPDFFORM *signature: graphical representation of the
signature itself (such as a scanned handwritten signature)
• DLPDFFORM *textSigInfo: layer displaying information
about the signature and the signatory
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdoccreatesignature,
dlpdfpageplacesignature
All DLI-supported platforms.

DLI Reference Guide A.61
dlpdfdocwritepdf (DLPDFDOC *Doc, char *FileName,
int Linearize)
Return Value: void
Description
Parameters
Return Value
Exceptions
Header
Related Methods
Availability
Writes the document to PDF.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• char *FileName: May be NULL if it was set by a previous
call to dlpdfdocsetpdfname, otherwise, if the filename
is not specified, a genErrBadParam exception will be
raised. If the filename was set, dlpdfdocsetpdfname
has been called.
• int Linearize: If true, linear optimized output will be
created. If the procedure dlpdfdoclinearize has been
called prior to a call to write the document, the document
will be linearized regardless of the setting of the linearization
flag.
void
genErrBadParam: Raised if the filename is not specified.
dli.h
dlpdfdocwritePS
All DLI-supported platforms.

A.62 DLI Implementation and Reference Guide
dlpdfdocwritePS (DLPDFDOC *Doc, char *FileName)
Return Value: void
Description
Parameters
Return Value
Exceptions
Header
Related Methods
Availability
Writes the document to PostScript.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• char *FileName: May be NULL if it was set by a previous
call to dlpdfdocsetpsname, otherwise, if the filename is
not specified, a genErrBadParam exception will be raised.
If the filename was set, dlpdfdocsetpsname has been
called.
void
genErrBadParam: Raised if the filename is not specified.
dli.h
dlpdfdocwritepdf
All DLI-supported platforms.

DLI Reference Guide A.63
dlpdffontcreate (DLPDFDOC *Doc, char *fontName,
char *fontType)
Return Value: DLPDFFONT*
Description
Parameters
Return Value
This function call will cause the Adobe PDF Library to search the
system default font locations and the locations supplied at initialization
time for a font of the specified name (and of the
specified type, if supplied). If a font cannot be located, this call
will raise an exception. The font returned will be created in the
document's default encoding if that encoding is compatible
with the font; otherwise, a platform-dependent default will be
used.
• DLPDFDOC *Doc: The document for which to embed all
fonts
• char *fontName: The font name to search for
• char *fontType: The type of font (e.g. "Type1,"
"TrueType," "Type3") to search for. This may be NULL.
The DLPDFFONT * which has been created
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocembedfonts,
dlpdffontcreateembedded,
dlpdffontcreatewithmetrics,
dlpdffontcreatewithmetricsembedded
All DLI-supported platforms.
Technical Notes
1 When a font type is specified, a font of that type and name is sought. If no such font is found, any
type of font with the same name is sought. Please see “Font Searching Sequence” on page 1.5 for the
specific order of search tests followed when the font creation process attempts to locate a font in
resources.

A.64 DLI Implementation and Reference Guide
dlpdffontcreateembedded (DLPDFDOC *Doc,
char *fontName, char *fontType, ASBool Subset)
Return Value: DLPDFFONT*
Description
Parameters
Return Value
This function call will cause the Adobe PDF Library to search the
system default font locations and the locations supplied at initialization
time for a font of the specified name (and of the
specified type, if supplied). If a font cannot be located, this call
will raise an exception. The font returned will be embedded and
created in the document's default encoding if that encoding is
compatible with the font; otherwise, a platform-dependent
default will be used. If the Subset parameter is set to TRUE,
the font will be embedded and subset.
• DLPDFDOC *Doc: The document for which to embed all
fonts
• char *fontName: Font name to search for
• char *fontType: The type of font to search for (e.g.
"Type0," "Type1," "TrueType," "Type3"). This may be
NULL.
• ASBool Subset: If TRUE, then the font is both embedded
and subset. If FALSE, the entire font file is embedded in the
PDF document. For Type0 fonts, this must be TRUE.
The DLPDFFONT which has been created
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocembedfonts,
dlpdffontcreate,
dlpdffontcreatewithmetrics,
dlpdffontcreatewithmetricsembedded
All DLI-supported platforms.

DLI Reference Guide A.65
dlpdffontcreatewithmetrics (DLPDFDOC *Doc,
char *fontName, PDEFontAttrs *fontAttrs, unsigned short *Widths,
char *Encoding [])
Return Value: DLPDFFONT*
Description
Parameters
Return Value
This function call will cause the Adobe PDF Library to search the
system default font locations and the locations supplied at initialization
time for a font of the specified name and attributes. If
the font cannot be found, one will be created if a width table
and valid font attributes have been supplied. If no encoding is
specified in the font attributes, the font will be created with the
document's default font encoding.
• DLPDFDOC *Doc: The document for which to embed all
fonts
• char *fontName: Font name to search for
• PDEFontAttrs *fontAttrs: A PDEFontAttrs
structure which has been zero-filled and set with parameters
which the caller wants to see reflected in the returned font.
See the Adobe Acrobat Core API Reference for details on this
structure.
• unsigned short Widths: If non-NULL, an array of 256
values; see Technical Note 1 below.
• char *Encoding: If non-NULL, an array of 256 values; see
Technical Note 2 below.
The DLPDFFONT which has been created
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocembedfonts,
dlpdffontcreate,
dlpdffontcreateembedded,
dlpdffontcreatewithmetricsembedded
All DLI-supported platforms.
Technical Notes
1 The widths array refers to the width of the character in that position, in EMs. If this argument is
NULL, the default character widths in the requested encoding of the FontAttrs structure are used.
This must be NULL for Type0 fonts.
2 Each element of the encoding array is the PostScript name of the character to use for the specified
code point. If this is NULL, the encoding specified in the PDEFontAttrs structure is used (and must
be NULL for Type0 fonts). When specifying an encoding vector, a width table is highly recommended.

A.66 DLI Implementation and Reference Guide
dlpdffontcreatewithmetricsembedded
(DLPDFDOC *Doc, char *fontName, PDEFontAttrs *fontAttrs,
unsigned short *Widths, char *Encoding [], ASBool Subset)
Return Value: DLPDFFONT*
Description
Parameters
Return Value
This function call will cause the Adobe PDF Library to search the
system default font locations and the locations supplied at initialization
time for a font of the specified name and attributes. If
the font cannot be found, an exception will be raised. If no
encoding is specified in the font attributes, the font will be created
with the document's default font encoding. The created
font will be embedded; if Subset is set to TRUE, then the font
will be subset as well.
• DLPDFDOC *Doc: The document for which to embed all
fonts
• char *fontName: The font name to search for
• PDEFontAttrs *fontAttrs: A PDEFontAttrs
structure which has been zero-filled and set with parameters
which the caller wants to see reflected in the returned font.
See the Adobe Acrobat Core API Reference for details on this
structure.
• unsigned short *Widths: If non-NULL, an array of 256
values; see Technical Note 1 below.
• char *Encoding: If non-NULL, an array of 256 values; see
Technical Note 2 below.
• ASBool Subset: If TRUE, then the font is both embedded
and subset. If FALSE, the entire font file is embedded in the
PDF document. For Type0 fonts, this must be TRUE.
The DLPDFFONT which has been created
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocembedfonts,
dlpdffontcreate,
dlpdffontcreateembedded,
dlpdffontcreatewithmetrics
All DLI-supported platforms.

DLI Reference Guide A.67
Technical Notes
1 Each element of the widths array represents the width of the character in that position, in EMs. If
this argument is NULL, the default character widths in the requested encoding of the PDEFontAttrs
structure are used. This must be NULL for Type0 fonts.
2 Each element of the encoding array is the PostScript name of the character to use for the specified
code point. If this argument is NULL, the encoding specified in the PDEFontAttrs structure is used.
This must be NULL for Type0 fonts. When specifying an encoding vector, a width table is highly
recommended.

A.68 DLI Implementation and Reference Guide
dlpdfformcreate (DLPDFDOC *Doc, DLPDFCONTENT *Content,
ASFixedRect *BBox)
Return Value: DLPDFFORM*
Description
Parameters
Return Value
Creates a new form in the document specified as Doc., with the
content previously placed into the container Content. The
form will be considered to be of the size specified in BBox. The
Bounding Box need not be located at (0,0); however, it must
have a positive Width and Depth.
• DLPDFDOC *Doc: Name of new form created with this call
• DLPDFCONTENT *Content: Represents the content
element. The content block used to create a form is destroyed
in the form’s creation, and any handles to it become invalid.
• ASFixedRect *BBox: Represents the bounding box of the
form, in points.
DLPDFFORM*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfformdestroy
All DLI-supported platforms.

DLI Reference Guide A.69
dlpdfformdestroy (DLPDFFORM *Form)
Return Value: void
Description
Parameters
Return Value
Destroys the named form, releasing its resources and invalidating
the form handle.
DLPDFFORM *Form
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfformcreate
All DLI-supported platforms.

A.70 DLI Implementation and Reference Guide
dlpdfimagecreatefrombmp (DLPDFDOC *Doc,
char *ImageName, char *Image, long ImageSize, long Width, Long Depth,
int bpc, CosObj ColorSpace, int InLine)
Return Value: DLPDFIMAGE*
Description
Parameters
Return Value
Creates an image from a bitmap. The map is considered to be
scanned left to right and top to bottom.
• DLPDFDOC *Doc represents the document structure and the
current status of the document at all times.
• char *ImageName: Image name string
• char *Image: Pointer to the image raster data
• long ImageSize in bytes. Should be equal to
((Width*Depth*BitsPerComponent)/8)*
CompPerPixel. Components per pixel is derived from
ColorSpace.
• long Width in pixels
• Long Depth in pixels
• int bpc
• CosObj ColorSpace: this should be the color space name
as a COS structure (/DeviceGray, /DeviceRGB or
/DeviceCMYK, which have 1, 3, and 4 components per pixel
respectively), a CosNull structure (if this is a 1BPP, onechannel
bitmap to be placed as an imagemask), or an
indexed color space structure which has one component per
pixel.
• int InLine: A flag which when TRUE will embed this
structure in the document each time it is used. When FALSE,
it will be embedded only once.
DLPDFIMAGE*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfimagecreatefromfile,
dlpdfimagecreatefrompdf,
dlpdfimagecreatefromps
All DLI-supported platforms.
Technical Notes
1 For efficiency purposes, DLI inlines images when the ImageLength parameter is less than 500 bytes.
2 The bitmap processed by this function is a “raw” bitmap with no header information or wrapper.
Unprocessed BMP files are not supported by this function.

DLI Reference Guide A.71
dlpdfimagecreatefromfile (DLPDFDOC *Doc, char *Name)
Return Value: DLPDFIMAGE*
Description
Parameters
Return Value
Invokes the graphics library conversion facility, which will convert
an arbitrary file containing an image (JPG/JPEG, PNG, TIFF,
GIF or PDF) into a returned DLPDFIMAGE* structure for further
processing.
• DLPDFDOC *Doc represents the document structure and
the current status of the document at all times.
• char *Name: Name string
DLPDFIMAGE*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfimagecreatefrombmp,
dlpdfimagecreatefrompdf,
dlpdfimagecreatefromps
Not available on OS/390

A.72 DLI Implementation and Reference Guide
dlpdfimagecreatefrompdf (DLPDFDOC *Doc,
char *ImageName, ASFixed Width, ASFixed Depth, ASFixed XDisp,
ASFixed YDisp, long Page)
Return Value: DLPDFIMAGE*
Description
Parameters
Return Value
This convenience operator will create an image from a file containing
a PDF document. If importing an image containing a
Rotate key, that value will be honored. Images will be placed
in the same orientation displayed by Adobe Reader and Acrobat.
The specified page of the PDF document will be used as a
graphic image.
• DLPDFDOC *Doc represents the document structure and the
current status of the document at all times.
• char *ImageName: Image name string
• ASFixed Width
• ASFixed Depth
• ASFixed XDisp
• ASFixed YDisp
• long Page
DLPDFIMAGE*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfimagecreatefrombmp,
dlpdfimagecreatefromfile,
dlpdfimagecreatefromps
All DLI-supported platforms.
Technical Notes
1 As of DLI v3.0.11, a value of 0 is now accepted for the Width and Depth parameters. If either is 0,
the PDF page's crop box is used to form the DLPDFIMAGE's visible region. This will be shifted using
the XDisp and YDisp values to generate the imported image.
2 Datalogics recommends supplying a value of 0 for the width, depth, and x- and y-displacements,
unless it is otherwise known that the imported graphic should be placed with a visible region other
than that visible in Adobe Acrobat or Reader.
3 The BoundingBox in the returned DLPDFIMAGE is not rotated by the value of the Rotate key for
the imported page, and thus can be used to determine the "real" width and depth of the imported PDF
image.

DLI Reference Guide A.73
dlpdfimagecreatefromps (DLPDFDOC *Doc,
char *ImageName, char *Image, long ImageSize, int InLine)
Return Value: DLPDFIMAGE*
Description
Parameters
Return Value
Creates an image from an EPS graphic. It must contain a
“%%BoundingBox” statement.
• DLPDFDOC *Doc represents the document structure and the
current status of the document at all times.
• char *ImageName: Name of Image
• char *Image: The graphic is contained in this array.
• long ImageSize: Size of image
• int Inline: A flag, which when TRUE embeds this
structure in the graphic each time it is used. When FALSE, it
will be embedded only once.
DLPDFIMAGE*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfimagecreatefrombmp,
dlpdfimagecreatefromfile,
dlpdfimagecreatefrompdf
All DLI-supported platforms.
Technical Notes
1 DLI does not convert PostScript fragments to PDF. Any PostScript images will not be viewable in most
PDF viewers. This method is included for PDF files which will go to printers or print processors which
can appropriately handle these fragments.

A.74 DLI Implementation and Reference Guide
dlpdfimagegetsize (DLPDFIMAGE *Image, ASUns32 *xRasters,
ASUns32 *yRasters, ASFixed *xPoints, ASFixed *yPoints)
Return Value: void
Description
Parameters
Return Value
This procedure retrieves image size information from a graphic
file.
• DLPDFIMAGE *Image: Represents a pointer to the image
file. This method will examine the image file and return
values in the four arguments following.
• ASUns32 *xRasters: Width of image in rasters or image
units (depending on format)
• ASUns32 *yRasters: Height of image in rasters or image
units (depending on format)
• ASFixed *xPoints: Intended print width in PDF units
• ASFixed *yPoints: Intended print height in PDF units
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentreferenceimage
All DLI-supported platforms.
Technical Notes
1 The Scale Factors specified in dlpdfcontentreferenceimage will determine the resulting size of
the image. This method gives you the image information necessary to calculate those values, dividing
the intended print size by the file size for each dimension. This yields a Scale Factor ratio which
dlpdfcontentreferenceimage uses to calculate the final output image size.
2 The typical scaling calculation using values returned by this method would occur during the call to
dlpdfcontentreferenceimage; e.g. "dlpdfcontentreferenceimage(Content, Image,
Int32ToFixed(72), Int32ToFixed(92), 0,
ASFixedDiv(xPoints,Int32ToFixed(xRasters)),
ASFixedDiv(yPoints,Int32ToFixed(yRasters)));".
3 An image in which each pixel of each raster line represents one PDF unit of output will return the same
values for both image dimension (xRasters and yRasters) and print size (xPoints and
yPoints), and thus a Scale Factor of 1 on both axes.

DLI Reference Guide A.75
dlpdfinit (PDFLData pdflLibData, ASFileSys defaultFS, void *unused)
Return Value: DLPDFINSTANCE *
Description
Parameters
Initializes the Adobe PDF Library and DLI, and should be called
prior to creating the first document.
• PDFLData pdflLibData: contains the initialization
information for the Adobe PDF Library.
• ASFileSys defaultFS: the default file system for file
input/output and creation of temporary files. If this parameter
is NULL, the default file system for the current platform will
be used.
• void *unused: NULL; reserved for future use
Return Value DLPDFINSTANCE *
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfilesys,
dlpdfterm
All DLI-supported platforms.
Technical Notes
1 Initialization of DLI is now required; support for using DLI without initialization has been removed.
If you intend to use DLI methods in your application, you must intialize DLI via dlpdfinit. DLI
users should initialize the Adobe PDF Library through the DLI initialization call; PDFLInit and
PDFLTerm should never be directly called from a DLI application.
2 In a multi-threaded application, each thread must do its own initialization and termination of the
Library.
3 This procedure, along with dlpdfterm, replaces the need for calls to PDFLInit and PDFLTerm.
DLI should be initialized, or the Adobe PDF Library, but not both.
4 You can accidentally call dlpdfinit (the DLI command) multiple times without problems, as it
contains internal code that prevents actual initialization from occurring more than once, but you
cannot call PDFLInit (the Adobe PDF Library command) more than once as a fatal error will occur.
5 dlpdfinit and dlpdfterm are the only methods which must not be enclosed in exception handlers
(i.e. DURING/HANDLER/END_HANDLER statements), because they are not set up before initialization,
and are freed during termination.
6 As of DLI v3.0.11, the DLI graphics cache has been enhanced to use the default ASFileSys
implementation provided to dlpdfinit for caching graphics. By default, the graphics cache file size
is limited to 1.5GB. Customers who wish to use larger graphics cache files are advised to supply a

A.76 DLI Implementation and Reference Guide
filesystem to dlpdfinit which is capable of reliably handling files of the larger size.
NOTE: The cache size limit is checked every time a document is destroyed; the
cache may therefore temporarily exceed the cache size limit. When setting the
cache size limit, please note that to resize the graphics cache, free space equal to
the sum of the cache limit and the "low water" mark is required. Files In Memory
users with large graphics workloads are advised to lower the cache size limit to a
number appropriate for their target environment.

DLI Reference Guide A.77
dlpdfinstancesetcancelproc (DLPDFINSTANCE *dliInst,
CancelProc cProc, void *cData)
Return Value: void
Description
Parameters
Return Value
This call sets the cancel procedure used when writing a document
using the dlpdfdocwritepdf call, along with other
calls which may take a large quantity of time. This progress
monitor will be used for all documents created with the specified
instance.
• DLPDFInstance *dliInst: The DLPDFINSTANCE for
which to set the cancel procedure
• CancelProc cProc: The cancel procedure to use. See the
Adobe Acrobat Core API Reference for details on creating a
cancel procedure.
• void *cData: A pointer to client data which is passed to
the cancel procedure callback. See the Adobe Acrobat Core
API Reference for details.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.78 DLI Implementation and Reference Guide
dlpdfinstancesetgrcachelimits (DLPDFINSTANCE *dliInst,
ASUns32 highLimit, ASUns32 deleteLimit)
Return Value: void
Description
Parameters
Return Value
This call supports a control on the amount of filesystem storage
used for the DLI graphics cache. It accepts a low-water and a
high-water mark, in bytes. At document-destroy time (i.e. when
a call to dlpdfdocdestroy is made), the graphics cache size
is evaluated, and if it exceeds the high-water mark in size,
graphics will be removed from the cache in least recently used
(LRU) order until the cache falls to or below the low-water mark.
• DLPDFINSTANCE *dliInst: The DLPDFINSTANCE for
which the cache will be reviewed
• ASUns32 highLimit: The high-water mark level, in bytes.
Exceeding this level will trigger a purge of graphics in LRU
order at document-destroy time.
• ASUns32 deleteLimit: The low-water mark level, in
bytes, above which graphics will be purged at documentdestroy-time.
Graphics will be removed in LRU order until the
total storage is at or below this figure.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocdestroy
All DLI-supported platforms.
Technical Notes
1 The highLimit value is a trigger-point setting only, not a storage limit; the cache is allowed to grow
beyond that point. The highLimit value is inspected only at document-destroy time when
dlpdfdocdestroy is called, not before. The graphics cache may grow larger than the highLimit
value during document creation, but will be reduced to the deleteLimit point before the next
document is begun.
2 As of DLI v3.0.11, the DLI graphics cache has been enhanced to use the default ASFileSys
implementation provided to dlpdfinit for caching graphics. By default, the graphics cache file size
is limited to 1.5GB. Customers who wish to use larger graphics cache files are advised to supply a

DLI Reference Guide A.79
filesystem to dlpdfinit which is capable of reliably handling files of the larger size.
NOTE: The cache size limit is checked every time a document is destroyed; the
cache may therefore temporarily exceed the cache size limit. When setting the
cache size limit, please note that to resize the graphics cache, free space equal to
the sum of the cache limit and the "low water" mark is required. Files In Memory
users with large graphics workloads are advised to lower the cache size limit to a
number appropriate for their target environment.

A.80 DLI Implementation and Reference Guide
dlpdfinstancesetprogressmonitor
(DLPDFINSTANCE *dliInst, ProgressMonitor pRec, void *progData)
Return Value: void
Description
Parameters
Return Value
This call sets the progress monitor used when writing a document
using the dlpdfdocwritepdf call, along with other
calls which may take a large quantity of time. This progress
monitor will be used for all documents created with the specified
instance.
• DLPDFINSTANCE *dliInst: The DLPDFINSTANCE for
which to set the progress monitor
• ProgressMonitor pRec: The progress monitor to use.
See the Adobe Acrobat Core API Reference for details on
creating and obtaining progress monitors.
• void *progData: A pointer to client data which is passed
to the progress monitor callbacks. See the Adobe Acrobat
Core API Reference for details.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.81
dlpdfmatrixrotate (ASFixedMatrix *Matrix, ASFixed Angle)
Return Value: void
Description
Parameters
Return Value
Rotates a matrix counterclockwise by the specified angle after
accepting a pointer to the matrix.
• ASFixedMatrix *Matrix: Matrix to be rotated
• ASFixed Angle: In degrees, as an ASFixed
counterclockwise value
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.82 DLI Implementation and Reference Guide
dlpdfmemfileacquire (ASPathName Name)
Return Value: MDFile
Description
Parameters
Return Value
Acquires a Files In Memory representation for the file named
FileName, previously created with an ASFileOpen call. It
returns this file as an MDFile, which may then be used to
obtain a representation of the file's contents.
ASPathName Name
MDFile
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfilerelease
All DLI-supported platforms.

DLI Reference Guide A.83
dlpdfmemfiledata (MDFile File)
Return Value: unsigned const char *
Description
Parameters
Returns a pointer (of the size returned by the dlpdfmemfilesize
function call) containing a memory representation
of the file passed into the function. This should be neither
altered nor freed, and should be copied by the application into
the application’s memory area.
MDFile File
Return Value unsigned const char *
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfileacquire,
dlpdfmemfilerelease,
dlpdfmemfilesize
All DLI-supported platforms.

A.84 DLI Implementation and Reference Guide
dlpdfmemfiledeleteonclose (MDFile File)
Return Value: void
Description
Parameters
Return Value
This method marks a Files In Memory file to be removed from
the filesystem once the last open filehandle for this file has been
closed. No file is automatically removed from memory, unless
this call has been made on a specific MDFile.
MDFile File
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfileacquire,
dlpdfmemfilerelease
All DLI-supported platforms.

DLI Reference Guide A.85
dlpdfmemfilerelease (MDFile File)
Return Value: int
Description
Parameters
Return Value
Relinquishes one acquisition as made by the dlpdfmemfileacquire
call, and returns the number of acquisitions left on
the file.
MDFile
Int
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfileacquire
All DLI-supported platforms.
Technical Notes
1 An application should make one release call for each acquire call: the release call signals that
the acquiring program no longer needs the file, and its resources may be safely freed.

A.86 DLI Implementation and Reference Guide
dlpdfmemfilesetbuffer (MDFile File, unsigned char * Data,
ASSize_t Size)
Return Value: ASBool
Description
Parameters
Return Value
This method configures Files In Memory to directly use the
buffer passed in as the file contents. Unlike dlpdfmemfilesetdata,
this method does not copy the buffer; the file
instance and buffer instance are one and the same.
• MDFile File: File to be overwritten
• unsigned char * Data: Memory to replace the File’s
previous content.
• ASSize_t Size
ASBool: TRUE is returned if the file’s data buffer could be set
to this memory, FALSE if it could not.
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfileacquire,
dlpdfmemfilerelease,
dlpdfmemfilesetdata
All DLI-supported platforms.
Technical Notes
1 As of DLI v3.0.11, the dlpdfmemfilesetbuffer and dlpdfmemfilesetdata calls no longer
rewind the memory files to position 0.

DLI Reference Guide A.87
dlpdfmemfilesetdata (MDFile File, unsigned const char * Data,
ASSize_t Size)
Return Value: ASBool
Description
Parameters
Return Value
Sets the file passed in to contain the data passed to the function.
This completely overwrites the file’s previous contents.
• MDFile File: File to be overwritten
• unsigned const char * Data: Data that replaces
File content.
• ASSize_t Size
ASBool: TRUE is returned if the file could be set to this data,
FALSE if it could not.
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfileacquire,
dlpdfmemfilerelease,
dlpdfmemfilesetbuffer
All DLI-supported platforms.
Technical Notes
1 As of DLI v3.0.11, the dlpdfmemfilesetbuffer and dlpdfmemfilesetdata calls no longer
rewind the memory files to position 0.

A.88 DLI Implementation and Reference Guide
dlpdfmemfilesize (MDFile File)
Return Value: ASSize_t
Description
Parameters
Return Value
Returns the size of the memory buffer which the dlpdfmemfiledata
call will return if called. This is the smallest size of
buffer that can accommodate the memory representation of
Files In Memory passed in as a file.
MDFile File
ASSize_t
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfileacquire,
dlpdfmemfilerelease
All DLI-supported platforms.

DLI Reference Guide A.89
dlpdfmemfilesys (void)
Return Value: ASFileSys
Description
Parameters
Return Value
Returns the ASFileSys structure which represents the Datalogics
Files In Memory file system.This file system will only be
used if PDF output is requested.
None
ASFileSys
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfinit,
dlpdfmemfileacquire,
dlpdfmemfilerelease
All DLI-supported platforms.
Technical Notes
1 This method is suitable as the second parameter for the dlpdfinit function, or for any other Adobe
PDF Library function call requiring an ASFileSys record.

A.90 DLI Implementation and Reference Guide
dlpdfmemfilesysgetmemusage (void)
Return Value: ASSize_t
Description
Parameters
Return Value
This returns an ASSize_t with the current usage, in bytes, of
memory for Files In Memory file contents by DLI.
None
ASSize_t
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfileacquire,
dlpdfmemfilerelease
dlpdfmemfilesyssetmemlimit
All DLI-supported platforms.

DLI Reference Guide A.91
dlpdfmemfilesyssetmemlimit (ASSize_t memLimit)
Return Value: void
Description
Parameters
Return Value
This establishes an upper bound, in bytes, of the memory usage
allowed for Files In Memory file contents by DLI.
ASSize_t memLimit
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfileacquire,
dlpdfmemfilerelease
dlpdfmemfilesysgetmemusage
All DLI-supported platforms.

A.92 DLI Implementation and Reference Guide
dlpdfmemfiletransientprefix (void)
Return Value: const char *
Description
Parameters
Returns a NULL-terminated string representing the prefix for the
transient files
None
Return Value const char *
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfmemfileacquire,
dlpdfmemfilerelease
All DLI-supported platforms.
Technical Notes
1 Transient files are files which are to reside entirely within the bounds of Files In Memory, and are not
to be written to disk upon file closure. All temporary files created by the Adobe PDF Library and DLI
are automatically transient files when Files In Memory is activated.
2 Applications which wish to write PDF files to memory areas should append this prefix to the
beginning of all their file names. Files which do not start with this prefix will be written to disk upon
file closure or upon program termination.

DLI Reference Guide A.93
dlpdfpageaddlinkannotation (DLPDFPAGE *Page,
ASFixedRect *Location, ASFixed *Border, ASFixed *Color,
long PageNumber, Char *Fit, ASFixedRect *Where, ASFixed *Zoom)
Return Value: CosObj
Description
Parameters
Return Value
Creates a link annotation in the specified page.
• DLPDFPAGE *Page: Represents a page. This structure is
tracked within the package and destroyed when the
document is destroyed. Pointers to this structure remain valid
until the document is destroyed.
• ASFixedRect *Location: The hot spot for the link will
be located at the rectangle specified here.
• ASFixed *Border: (Optional) An array of three ASFixed
values in the order Horizontal Corner Radius,
Vertical Corner Radius and Line Width, drawing a
visible border around the hot spot.
• ASFixed *Color: Optional pointer by which border color
may be set. When used, this is assumed to point to an array
of three ASFixed values, giving the color as Red, Green and
Blue values.
• long PageNumber: The zero-relative number of the page
to which this link connects. The page referenced does not
need to have been created yet.
• Char *Fit: Must be a valid PDF fit type expressed as a
string. The list of valid types are “Fit”, “FitH”, “FitV”,
“FitBH”, “FitBV”, “FitR”, “FitB” and “XYZ”. See the
Adobe PDF Library Reference Guide for explanations of the
meaning of each fit type, and which values of the rectangle
and zoom are used for each.
• ASFixedRect *Where: The rectangle to be displayed. This
is used to distinguish an annotation. Only portions of this
rectangle are used, based on the Fit Type selected in Fit.
• ASFixed *Zoom: Adjustment to size of link target display.
CosObj: The actual link structure which may be modified by
the user to access capabilities beyond this interface.
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpageaddlinkannotationfromname,
dlpdfpageaddtextannotation,
dlpdfpageaddwebannotation
All DLI-supported platforms.

A.94 DLI Implementation and Reference Guide
Technical Notes
1 Only internal destinations (within the same document) are supported in this method.
2 Zero values in the rectangle will behave as PDViewNull values, as will a zero value for Zoom.
3 The most common values used are XYZ as the fit type, Zero for Zoom, and the (X,Y) coordinates of the
upper left hand edge of the desired target text in Where.top and Where.left. This will change to
the target page and position the specified text so it is within the display window, leaving the
Magnification factor where the user last set it.

DLI Reference Guide A.95
dlpdfpageaddlinkannotationfromname
(DLPDFPAGE *Page, ASFixedRect *Location, ASFixed *Border,
ASFixed *Color, char *Target)
Return Value: CosObj
Description
Parameters
Return Value
Adds a new link to a page using the named destination rather
than a specified destination.
• DLPDFPAGE *Page
• ASFixedRect *Location: Location of rectangle
• ASFixed *Border
• ASFixed *Color: Link color
• char *Target
CosObj
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpageaddlinkannotation,
dlpdfpageaddtextannotation,
dlpdfpageaddwebannotation
All DLI-supported platforms.

A.96 DLI Implementation and Reference Guide
dlpdfpageaddtextannotation (DLPDFPAGE *Page,
ASFixedRect *Location, ASFixed *Border, ASFixed *Color, char *Title,
char *Contents, int Open)
Return Value: CosObj
Description
Parameters
Return Value
Creates a text annotation within the specified page.
• DLPDFPAGE *Page: Represents a page. This structure is
tracked within the package and destroyed when the
document is destroyed. Pointers to this structure remain valid
until the document is destroyed.
• ASFixedRect *Location: The lower-left corner of where
the text annotation is to be displayed.
• ASFixed *Border: (Optional) an array of three ASFixed
values: Horizontal Corner Radius, Vertical
Corner Radius and Line Width.
• ASFixed *Color: (Optional) an array of three ASFixed
values giving the color as Red, Green and Blue values.
• char *Title: (Optional) displayed in the title bar of an
open text annotation.
• char *Contents: (Required) the displayed contents of the
annotation.
• int Open: A Boolean where TRUE will cause the annotation
to be opened by default, while FALSE will cause it to be
closed by default.
CosObj
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpageaddlinkannotation,
dlpdfpageaddlinkannotationfromname,
dlpdfpageaddwebannotation
All DLI-supported platforms.
Technical Notes
1 A page may contain any number of annotations. There are capabilities of annotations beyond those
described here. To access those capabilities, modify the COS structure returned by this call.

DLI Reference Guide A.97
dlpdfpageaddwebannotation (DLPDFPAGE *Page,
ASFixedRect *Location, ASFixed *Border, ASFixed *Color,
char *URIDestination)
Return value: CosObj
Description
Parameters
Return Value
Adds a new link to a page, using a URI (equivalent to URL) destination
given by the URIDestination parameter. This URI is
assumed to be in UTF-8 text format; support for URIs in other
character sets is unavailable at this time.
• DLPDFPAGE *Page
• ASFixedRect *Location
• ASFixed *Border
• ASFixed *Color
• char *URIDestination: URI destination in UTF-8 text
format.
CosObj
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpageaddlinkannotation,
dlpdfpageaddlinkannotationfromname,
dlpdfpageaddtextannotation
All DLI-supported platforms.
Technical Notes
1 You should have your internet browser running before calling this procedure or you may receive a
“browser is busy” error. Your browser can be specified in Adobe Acrobat or Adobe Reader via File-
>Preferences->Weblink.

A.98 DLI Implementation and Reference Guide
dlpdfpagecosobj (DLPDFPAGE *Page)
Return Value: CosObj
Description
Parameters
Return Value
This function will return a COS structure that represents the
page in the Adobe PDF Library. It may be used to apply COS
Layer operations to the page beyond those functions defined in
the package.
DLPDFPAGE *Page
CosObj
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.99
dlpdfpagecreate (DLPDFDOC *Doc, ASFixed Width,
ASFixed Height)
Return Value: DLPDFPAGE*
Description
Parameters
Return Value
Exceptions
Header
Creates a new page in the current document, positioned to follow
all other pages in the current document.
• DLPDFDOC *Doc: Represents the document structure and
the current status of the document at all times.
• ASFixed Width: Must be specified as greater than zero;
assumed to be in points.
• ASFixed Height: Must be specified as greater than zero;
assumed to be in points.
DLPDFPAGE*
genErrBadParam: Raised if the specified document does not
exist.
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.100 DLI Implementation and Reference Guide
dlpdfpagefindfromnumber (DLPDFDOC *Doc,
long PageNumber)
Return Value: DLPDFPAGE*
Description
Parameters
Return Value
Allows pages to be modified after creation without requiring
pointers to all pages in the application. If the page number specified
has not yet been created, a NULL pointer will be returned.
The first page is considered to be page one.
• DLPDFDOC *Doc represents the document structure and the
current status of the document at all times.
• long PageNumber
DLPDFPAGE*
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.101
dlpdfpagenumber (DLPDFPAGE *Page)
Return Value: long
Description
Parameters
Return Value
Returns the sequence number of the specified page. This number
may be used in conjunction with the PDDoc returned by
dlpdfdocpddoc to acquire a PDPage for the specified page.
This PDPage will permit Edit Layer functions to be applied to
the page beyond those defined in this package.
DLPDFPAGE *Page
long
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.102 DLI Implementation and Reference Guide
dlpdfpagerotate (DLPDFPAGE *Page, PDRotate Angle)
Return Value: void
Description
Parameters
Return Value
Rotates page clockwise in 90-degree increments. Angles specified
will be reduced if necessary by 360 degrees, then rounded
to the nearest 90-degree increment.
• DLPDFPAGE *Page
• PDRotate Angle
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.
Technical Notes
1 This call may be issued at any time after a page is created, and will be effective in PDF and Adobe
PostScript.

DLI Reference Guide A.103
dlpdfpagesetart (DLPDFPAGE *Page, ASFixedRect *Rect)
Return Value: void
Description
Parameters
Return Value
Sets the Art box for the DLPDFPAGE provided as input to the
function. Please see the "Page Boundaries" section of Prepress
Support in the Adobe PDF Reference Manual for more details.
• DLPDFPAGE *Page
• ASFixedRect *Rect
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpagesetbleed,
dlpdfpagesetcrop,
dlpdfpagesetmediabox,
dlpdfpagesettrim
All DLI-supported platforms.

A.104 DLI Implementation and Reference Guide
dlpdfpagesetbleed (DLPDFPAGE *Page, ASFixedRect *Rect)
Return Value: void
Description
Parameters
Return Value
Sets the Bleed box for the DLPDFPAGE provided as input to the
function. Please see the "Page Boundaries" section of Prepress
Support in the Adobe PDF Reference Manual for more details.
• DLPDFPAGE *Page
• ASFixedRect *Rect
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpagesetart,
dlpdfpagesetcrop,
dlpdfpagesetmediabox,
dlpdfpagesettrim
All DLI-supported platforms.

DLI Reference Guide A.105
dlpdfpagesetcrop (DLPDFPAGE *Page, ASFixedRect *Rect)
Return Value: void
Description
Parameters
Return Value
Sets the Crop box for the DLPDFPAGE provided as input to the
function. Please see the "Page Boundaries" section of Prepress
Support in the Adobe PDF Reference Manual for more details.
• DLPDFPAGE *Page
• ASFixedRect *Rect
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpagesetart,
dlpdfpagesetbleed,
dlpdfpagesetmediabox,
dlpdfpagesettrim
All DLI-supported platforms.

A.106 DLI Implementation and Reference Guide
dlpdfpagesetid (DLPDFPAGE *Page, char *Id)
Return Value: void
Description
Parameters
Return Value
Adds an ID Entry to the page dictionary. This is generally a
page’s FOLIO.
• DLPDFPAGE *Page
• char *Id: ID entry.
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.107
dlpdfpagesetmediabox (DLPDFPAGE *Page,
ASFixedRect *Rect)
Return Value: void
Description
Parameters
Return Value
Sets the Media box for the DLPDFPAGE provided as input to the
function. Please see the "Page Boundaries" section of Prepress
Support in the Adobe PDF Reference Manual for more details.
• DLPDFPAGE *Page
• ASFixedRect *Rect
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpagesetart,
dlpdfpagesetbleed,
dlpdfpagesetcrop,
dlpdfpagesettrim
All DLI-supported platforms.

A.108 DLI Implementation and Reference Guide
dlpdfpagesettrim (DLPDFPAGE *Page, ASFixedRect *Rect)
Return Value: void
Description
Parameters
Return Value
Sets the Trim box for the DLPDFPAGE provided as input to the
function. Please see the "Page Boundaries" section of Prepress
Support in the Adobe PDF Reference Manual for more details.
• DLPDFPAGE *Page
• ASFixedRect *Rect
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpagesetart,
dlpdfpagesetbleed,
dlpdfpagesetcrop,
dlpdfpagesetmediabox
All DLI-supported platforms.

DLI Reference Guide A.109
dlpdfpathaddarc (DLPDFPATH *Path, ASFixed X, ASFixed Y,
ASFixed Rad, ASFixed T1, ASFixed T2)
Return Value: void
Description
Parameters
Return Value
Appends an arc segment to the current path. The current position
will be set to the ending point.
• DLPDFPATH *Path: Pointer to the path.
• ASFixed X: Starting X position of the arc
• ASFixed Y: Starting Y position of the arc
• ASFixed Rad: Radius of the arc
• ASFixed T1: Start angle for the arc
• ASFixed T2: End angle for the arc
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddarcn,
dlpdfpatthaddarcto,
dlpdfpathaddelliparc,
dlpdfpathadddelliparcn,
dlpdfpathaddelliparcto
All DLI-supported platforms.
Technical Notes
1 If the current position is not the starting position defined by (X,Y,Radius,StartAngle), then a
straight line segment will be added from the current position to get there. A smooth curve of the
specified radius will be drawn from that specified point counter-clockwise to the angle specified by
EndAngle.
2 If the starting and ending degree values specify the same angle, a full circle will be drawn, and the
position following this command will be the specified position.

A.110 DLI Implementation and Reference Guide
dlpdfpathaddarcn (DLPDFPATH *Path, ASFixed X, ASFixed Y,
ASFixed Rad, ASFixed T1, ASFixed T2)
Return Value: void
Description
Parameters
Return Value
Identical to dlpdfpathaddarc, except the arc will be drawn
clockwise.
• DLPDFPATH *Path is the pointer to the path.
• ASFixed X
• ASFixed Y
• ASFixed Rad
• ASFixed T1
• ASFixed T2
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddarc,
dlpdfpatthaddarcto,
dlpdfpathaddelliparc,
dlpdfpathadddelliparcn,
dlpdfpathaddelliparcto
All DLI-supported platforms.

DLI Reference Guide A.111
dlpdfpathaddarcto (DLPDFPATH *Path, ASFixed X1, ASFixed Y1,
ASFixed X2, ASFixed Y2, ASFixed Rad)
Return Value: void
Description
Parameters
Return Value
Appends a straight line segment from the current position
towards the first pair of X and Y coordinates specified, terminating
when it intersects an arc connecting this line to a second line
drawn between the first and second pairs of (X,Y) coordinates.
The arc is circular, drawn at the specified radius.
• DLPDFPATH *Path is the pointer to the path.
• ASFixed X1 is the X-axis position of the intersection of
tangents.
• ASFixed Y1 is the Y-axis position of the intersection of
tangents.
• ASFixed X2 is the X-axis position of a point defining the
second tangent.
• ASFixed Y2 is the Y-axis position of a point defining the
second tangent.
• ASFixed Rad is the radius of the arc.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddarcn,
dlpdfpatthaddarc,
dlpdfpathaddelliparc,
dlpdfpathadddelliparcn,
dlpdfpathaddelliparcto
All DLI-supported platforms.

A.112 DLI Implementation and Reference Guide
Xint1/
Yint1
X1/Y1
Xint2/
Yint2
Current Position
X2/Y2
Technical Notes
1 The two lines (CurrX,CurrY)->(X1,Y1) and (X2,Y2)->(X1,Y1) are joined by an arc of radius (Rad).
The line segment from the current position to the start of the arc is drawn, followed by the arc itself,
finishing at (Xint2,Yint2). The line segment from the end of the arc to the point (X2,Y2) is not
drawn.
2 The position following this command will be the intersection of the arc with the line (X2,Y2)-
>(X1,Y1), shown above as (Xint2,Yint2). If the two lines are colinear, a straight line segment is
drawn from the current position to (X1,Y1), which then becomes the current point.

DLI Reference Guide A.113
dlpdfpathaddclose (DLPDFPATH *Path)
Return Value: void
Description
Parameters
Return Value
Appends a “close path” operator to the path. The current
position after the path is closed is (1,-1).
DLPDFPATH *Path is the pointer to the path
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.114 DLI Implementation and Reference Guide
dlpdfpathaddcurve (DLPDFPATH *Path, ASFixed Ctrl1X,
ASFixed Ctrl1Y, ASFixed Ctrl2X, ASFixed Ctrl2Y, ASFixed EndX,
ASFixed EndY)
Return Value: void
Description
Parameters
Return Value
Exceptions
Header
Related Methods
Availability
Adds a spline or cubic Bézier curve to the path.
• DLPDFPATH *Path is the pointer to the path.
• ASFixed Ctrl1X is the X position of a point which will be
Control Point 1.
• ASFixed Ctrl1Y is the Y position of a point which will be
Control Point 1.
• ASFixed Ctrl2X is the X position of a point which will be
Control Point 2.
• ASFixed Ctrl2Y is the Y position of a point which will be
Control Point 2.
• ASFixed EndX is the X position which will be the end point
of the curve.
• ASFixed EndY is the Y position which will be the end point
of the curve.
void
genErrBadParam is returned if no starting point is specified.
dli.h
dlpdfpathaddcurver,
dlpdfpathaddcurvev,
dlpdfpathaddcurvey
All DLI-supported platforms.

DLI Reference Guide A.115
Ctrl1X/
Ctrl1Y
EndX/
EndY
StartX/
StartY
Ctrl2X/
Ctrl2Y
Technical Notes
1 A smooth curve (a cubic Bézier) will be drawn from the current position to the end position, under
direction of the two control points. At completion of this operation, the current position will be the
end position of the line. If the end position specified is identical to the current position, no segment will
be appended and no notice will be given (optimization).
2 All Bézier curves consist of four points. This method (as well as dlpdfpathaddcurver,
dlpdfpathaddcurvev and dlpdfpathaddcurvey) uses current position as the starting point of
the curve. The first two parameters of this method are the position of Control Point1, the second two
parameters are the position of Control Point 2, and the last two parameters are the position of the end
point of the curve.
3 If no starting point is specified, the method will raise an exception (genErrBadParm).

A.116 DLI Implementation and Reference Guide
dlpdfpathaddcurver (DLPDFPATH *Path, ASFixed Ctrl1X,
ASFixed Ctrl1Y, ASFixed Ctrl2X, ASFixed Ctrl2Y, ASFixed EndX,
ASFixed EndY)
Return Value: void
Description
Parameters
Return Value
Identical to dlpdfpathaddcurve, except that the positions
are expressed as relative distances from the current point, not
absolute distances from the origin.
• DLPDFPATH *Path is the pointer to the path
• ASFixed Ctrl1X is the X position of a point which will be
Control Point 1.
• ASFixed Ctrl1Y is the Y position of a point which will be
Control Point 1.
• ASFixed Ctrl2X is the X position of a point which will be
Control Point 2.
• ASFixed Ctrl2Y is the Y position of a point which will be
Control Point 2.
• ASFixed EndX is the X position which will be the end point
of the curve.
• ASFixed EndY is the Y position which will be the end point
of the curve.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddcurve,
dlpdfpathaddcurvev,
dlpdfpathaddcurvey
All DLI-supported platforms.

DLI Reference Guide A.117
dlpdfpathaddcurvev (DLPDFPATH *Path, ASFixed Ctrl2X,
ASFixed Ctrl2Y, ASFixed EndX, ASFixed EndY)
Return Value: void
Description
Parameters
Return Value
Identical to dlpdfpathaddcurve, except that both the start
and first control point are assumed to be the current position.
• DLPDFPATH *Path: The pointer to the path.
• ASFixed Ctrl2X: The X position of a point which will be
Control Point 2.
• ASFixed Ctrl2Y: The Y position of a point which will be
Control Point 2.
• ASFixed EndX: The X position which will be the end point
of the curve.
• ASFixed EndY: The Y position which will be the end point
of the curve.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddcurve,
dlpdfpathaddcurver,
dlpdfpathaddcurvey
All DLI-supported platforms.
EndX/
EndY
StartX/
StartY
Ctrl1X/
Ctrl1Y
Ctrl2X/
Ctrl2Y
Technical Notes
1 This method is identical to dlpdfpathaddcurve, except that both the start and first control point
are assumed to be the current position.

A.118 DLI Implementation and Reference Guide
dlpdfpathaddcurvey (DLPDFPATH *Path, ASFixed Ctrl1X,
ASFixed Ctrl1Y, ASFixed EndX, ASFixed EndY)
Return Value: void
Description
Parameters
Return Value
Identical to dlpdfpathaddcurve, except that the second
control point is assumed to be the ending position.
• DLPDFPATH *Path is the pointer to the path
• ASFixed Ctrl1X
• ASFixed Ctrl1Y
• ASFixed EndX
• ASFixed EndY
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddcurve,
dlpdfpathaddcurver,
dlpdfpathaddcurvev
All DLI-supported platforms.
Ctrl1X/
Ctrl1Y
StartX/
StartY
EndX/
EndY
Ctrl2X/
Ctrl2Y
Technical Notes
1 This method is identical to dlpdfpathaddcurve, except that the second control point is assumed to
be the ending position.

DLI Reference Guide A.119
dlpdfpathaddelliparc (DLPDFPATH *Path, ASFixed CentX,
ASFixed CentY, ASFixed HRad, ASFixed VRad, ASFixed T1, ASFixed T2)
Return Value: void
Description
Parameters
Return Value
Appends an arc segment to the current path. This method
accepts seven parameters.
• DLPDFPATH *Path is the pointer to the path.
• ASFixed CentX is the X-axis position of the arc center
point.
• ASFixed CentY is the Y-axis position of the arc center
point.
• ASFixed HRad is the horizontal radius of the ellipse
defining an arc segment.
• ASFixed VRad is the vertical radius of the same ellipse. The
HRad and VRad functions support creating arc segments
from an elliptical shape, as opposed to the circular shape
described in dlpdfpathaddarc, although if the same
value is used for both horizontal and vertical radii, it behaves
identically to dlpdfpathaddarc.
• ASFixed T1 is the beginning arc angle (where zero is
directly to the right of center).
• ASFixed T2 is the ending arc angle.
void
Exceptions
Header
Related Methods
dli.h
dlpdfpathaddarc,
dlpdfpathaddarcn,
dlpdfpatthaddarcto,
dlpdfpathadddelliparcn,
dlpdfpathaddelliparcto
Availability
Technical Notes
1 If the current position does not coincide with the position defined by
(CentX,CentY,HRad,VRad,StartAngle), then a straight line segment will be added from the
current position to get there. A smooth curve of the specified radius will be drawn from that specified
point counter-clockwise to the point specified by (CentX,CentY,HRad,VRad,EndAngle). The current
position will be set to that ending point. If the starting and ending points specify the same angle, a full
circle will be drawn.
2 The position following this command will be the specified position.

A.120 DLI Implementation and Reference Guide
dlpdfpathaddelliparcn (DLPDFPATH *Path, ASFixed CentX,
ASFixed CentY, ASFixed HRad, ASFixed VRad, ASFixed T1, ASFixed T2)
Return Value: void
Description
Parameters
Return Value
This method is identical to dlpdfpathaddelliparc,
except that the arc will be drawn clockwise.
• DLPDFPATH *Path is the pointer to the path.
• ASFixed CentX is the X-axis position of the arc center
point.
• ASFixed CentY is the Y-axis position of the arc center
point.
• ASFixed HRad is the horizontal radius of the ellipse
defining an arc segment.
• ASFixed VRad is the vertical radius of the same ellipse. The
HRad and VRad functions support creating arc segments
from an elliptical shape, as opposed to the circular shape
described in dlpdfpathaddarc, although if the same
value is used for both horizontal and vertical radii, it behaves
identically to dlpdfpathaddarc.
• ASFixed T1 is the beginning arc angle (where zero is
directly to the right of center).
• ASFixed T2 is the ending arc angle.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddarc,
dlpdfpathaddarcn,
dlpdfpatthaddarcto,
dlpdfpathaddelliparc,
dlpdfpathaddelliparcto
All DLI-supported platforms.

DLI Reference Guide A.121
dlpdfpathaddelliparcto (DLPDFPATH *Path, ASFixed X1,
ASFixed Y1, ASFixed X2, ASFixed Y2, ASFixed HRad, ASFixed VRad)
Return Value: void
Description
Parameters
Return Value
Appends a straight line segment from the current position
towards the first pair of X and Y coordinates specified, terminating
when it intersects an arc connecting this line to a second line
drawn between the first and second pairs of (X,Y) coordinates.
The arc is elliptical, drawn at the specified horizontal and vertical
radius.
• DLPDFPATH *Path: The pointer to the path
• ASFixed X1: The Xposition of the intersection of tangents
• ASFixed Y1: The Yposition of the intersection of tangents
• ASFixed X2: The Xposition of the endpoint of the second
tangent
• ASFixed Y2: The Yposition of the endpoint of the second
tangent
• ASFixed HRad: The horizontal radius of the arc
• ASFixed VRad: The vertical radius of the arc
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddarc,
dlpdfpathaddarcn,
dlpdfpathaddarcto,
dlpdfpathaddelliparc
All DLI-supported platforms.

A.122 DLI Implementation and Reference Guide
dlpdfpathaddline (DLPDFPATH *Path, ASFixed X, ASFixed Y)
Return Value: void
Description
Parameters
Return Value
Draws a line from the current position to the specified new position.
If the current position is the same as the new position, no
line segment will be added to the path and no notice will be
given. The current position following this command will be the
specified position.
• DLPDFPATH *Path is the pointer to the path.
• ASFixed X is the absolute X-axis position.
• ASFixed Y is the absolute Y-axis position.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddliner
All DLI-supported platforms.

DLI Reference Guide A.123
dlpdfpathaddliner (DLPDFPATH *Path, ASFixed X, ASFixed Y)
Return Value: void
Description
Parameters
Return Value
Draws a line from the current position for the given X and Y offset
distances (i.e. this is a movement relative to the current position).
If the distances specified are both zero, no line segment
will be added to the path and no notice will be given. The position
following this command will be the position derived by
applying the X and Y offsets to the prior position.
• DLPDFPATH *Path is the pointer to the path.
• ASFixed X is the X-axis distance to draw from the current X
position to the new X position.
• ASFixed Y is the Y-axis distance to draw from the current Y
position to the specified Y position.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddline
All DLI-supported platforms.

A.124 DLI Implementation and Reference Guide
dlpdfpathaddmove (DLPDFPATH *Path, ASFixed X, ASFixed Y)
Return Value: void
Description
Parameters
Return Value
Moves the current position to the specified new position without
adding a stroked line. If the current position is the same as
the specified new position, no adjustment of the current position
will be added to the path and no notice will be given. The
position following this command will be the specified position.
• DLPDFPATH *Path is the pointer to the path.
• ASFixed X is the specified X-axis position.
• ASFixed Y is the specified Y-axis position.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddmover
All DLI-supported platforms.

DLI Reference Guide A.125
dlpdfpathaddmover (DLPDFPATH *Path, ASFixed X, ASFixed Y)
Return Value: void
Description
Parameters
Return Value
Moves the current position for the given X and Y offset distances
(i.e. this is a movement relative to the current position). If
the distances specified are both zero, no movement will be
added to the path and no notice will be given. The position following
this command will be derived by applying the X and Y
offsets to the prior position.
• DLPDFPATH *Path is the pointer to the path.
• ASFixed X is the X-axis distance to move from the current X
position to the new X position.
• ASFixed Y is the Y-axis distance to move from the current Y
position to the new Y position.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathaddmove
All DLI-supported platforms.

A.126 DLI Implementation and Reference Guide
dlpdfpathaddrect (DLPDFPATH *Path, ASFixed X, ASFixed Y,
ASFixed Width, ASFixed Depth)
Return Value: void
Description
Parameters
Return Value
Draws a rectangle.
• DLPDFPATH *Path is the pointer to the path
• ASFixed X is the X position of a point which will be one
corner of the box
• ASFixed Y is the Y position of a point which will be one
corner of the box
• ASFixed Width will be the width of the box
• ASFixed Depth will be the depth of the box
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.
Technical Notes
1 If the specified position is not the current position, a MoveTo to the specified position will be made. A
rectangle will be added to the path, starting at the specified position and proceeding upward (unless
Depth is negative) and to the right (unless Width is negative). The end position after this operation
will be the specified position. If Width and Depth are both zero, no segment will be appended, but
the current position will still be updated.

DLI Reference Guide A.127
dlpdfpatharray (DLPDFPATH *Path)
Return Value: ASFixed*
Description
Parameters
Return Value
This method will return a pointer to the first member of the
array of ASFixed integers, which is the path.
DLPDFPATH *Path is the pointer to the path.
ASFixed*
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.128 DLI Implementation and Reference Guide
dlpdfpathclear (DLPDFPATH *Path)
Return Value: void
Description
Parameters
Return Value
Exceptions
Header
Used to reset a path, this method will set the current position to
UNSET, set the matrix to UNITY, and remove any path segment
present. It will not deallocate the array used to hold the path,
however, since its primary purpose is to lower the overhead
associated with allocation and deallocation.
DLPDFPATH *Path is the pointer to the path.
void
genErrBadParam is raised if the method is called with a NULL
pointer.
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.129
dlpdfpathcreate (void)
Return Value: DLPDFPATH*
Description
Parameters
Return Value
Exceptions
Header
Related Methods
Availability
Creates a new, empty DLPDFPATH structure.
None
DLPDFPATH*
genErrNoMemory
dli.h
dlpdfpathdestroy
All DLI-supported platforms.

A.130 DLI Implementation and Reference Guide
dlpdfpathcurrentx (DLPDFPATH *Path)
Return Value: ASFixed
Description
Parameters
Return Value
This method will return the current X position as an ASFixed
value.
DLPDFPATH *Path is the pointer to the path
ASFixed
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathcurrenty
All DLI-supported platforms.

DLI Reference Guide A.131
dlpdfpathcurrenty (DLPDFPATH *Path)
Return Value: ASFixed
Description
Parameters
Return Value
This method will return the current Y position as an ASFixed
value.
DLPDFPATH *Path is the pointer to the path.
ASFixed
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfpathcurrentx
All DLI-supported platforms.

A.132 DLI Implementation and Reference Guide
dlpdfpathdestroy (DLPDFPATH *Path)
Return Value: void
Description
Parameters
Return Value
Exceptions
Header
Related Methods
Availability
Destroys a DLPDFPATH structure and frees its resources.
DLPDFPATH *Path: The pointer to the path
void
genErrBadParam: Raised if the pointer is not valid
dli.h
dlpdfpathcreate
All DLI-supported platforms.

DLI Reference Guide A.133
dlpdfpathsetmatrix (DLPDFPATH *Path, ASFixedMatrix *Matrix)
Return Value: void
Description
Parameters
Return Value
Exceptions
Header
This method will accept a pointer to a path and a pointer to a
matrix. The specified matrix will be concatenated to the matrix
of the container in each container in which this path is drawn.
This allows the user complete and flexible control of the shape
drawn by the path.
• DLPDFPATH *Path is the pointer to the path
• ASFixedMatrix *Matrix
void
genErrBadParam exception is raised if the pointer to the path
or the matrix is NULL
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.134 DLI Implementation and Reference Guide
dlpdfpathsize (DLPDFPATH *Path)
Return Value: ASInt32
Description
Parameters
Return Value
This method will return the current size of the path array as an
integer.
DLPDFPATH *Path is the pointer to the path.
ASInt32
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.135
dlpdfpatterncreate (DLPDFDOC *Doc, DLPDFCONTENT
*Content, ASFixedRect *BBox, ASFixedMatrix *Matrix, int Colored,
int TileType, ASFixed XStep, ASFixed YStep)
Return Value: DLPDFPATTERN*
Description
Parameters
Return Value
This creates a patterned color space and returns a pointer to
that space. The pointer may be used in dlpdfcontentusefillpattern
or dlpdfcontentusestrokepattern to
apply this colored pattern to all following material. All patterns
will be destroyed and their handles invalidated at the destruction
of the document that contains them.
• DLPDFDOC *Doc: represents the document structure and
the current status of the document at all times.
• DLPDFCONTENT *Content: Represents the content
element. These structures are destroyed when associated
with a page or form, and pointers to them should not be
used after that time.
• ASFixedRect *BBox
• ASFixedMatrix *Matrix
• int Colored
• int TileType
• ASFixed XStep
• ASFixed YStep
DLPDFPATTERN*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfcontentusefillpattern,
dlpdfcontentusestrokepattern
All DLI-supported platforms.

A.136 DLI Implementation and Reference Guide
dlpdfpatternrotate (ASFixedMatrix *Matrix, ASFixed Angle)
Return Value: void
Description
Parameters
Return Value
This function will modify the specified matrix so as to effect counterclockwise
rotation of any marks drawn via this matrix. Angle is an angle
in degrees and fractions of degrees.
• ASFixedMatrix *Matrix
• ASFixed Angle
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

DLI Reference Guide A.137
dlpdfpageplacesignature (DLPDFPAGE *Page,
DLPDFSIGNATURE *Sig, ASFixedRect *imageBBox)
Return Value: void
Description
Parameters
Return Value
This call associates a digital signature to a page in the PDF file
generated by DLI. This call is required for all digital signatures
including invisible ones, although for invisible digital signatures,
the imageBBox is ignored and may be NULL.
• DLPDFPAGE *Page: page to receive the signature
• DLPDFSIGNATURE *Sig: signature to be associated with
the page
• ASFixedRect *imageBBox: bounding box in which
signature must fit.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdoccreatesignature,
dlpdfdocsetsignatureappearance
dlpdfdocwritepdf
All DLI-supported platforms.

A.138 DLI Implementation and Reference Guide
dlpdfseterrorfile (FILE *errorFilePtr)
Return Value: void
Description
Parameters
Return Value
Sets file to which error messages will be logged.
File *errorFilePtr: By default error messages are logged
to stderr
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfsetwarningfile
All DLI-supported platforms.

DLI Reference Guide A.139
dlpdfsetwarningfile (FILE * warningFilePtr)
Return Value: void
Description
Parameters
Return Value
Sets file to which warning messages will be logged.
File *warningFilePtr: By default warning messages are
not logged.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfseterrorfile
All DLI-supported platforms.

A.140 DLI Implementation and Reference Guide
dlpdfsignaturesetdatacallback
(DLPDFSIGNATURE *signature, void (*dataCallback)(char *, int))
Return Value: void
Description
Parameters
Return Value
This is an optional call for clients using PKCS #7 certificates. A
callback function is supplied for the signature.
• DLPDFSIGNATURE *signature: signature with which
PKCS #7 certificate will be associated
• void (*dataCallback)(char *, int): callback
function, called during the dlpdfdocwritepdf function
call; see Technical Notes below.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfsignaturesetpkcs7cert
dlpdfdocwritepdf
All DLI-supported platforms.
Technical Notes
1 The callback is called during the dlpdfdocwritepdf function with binary information from the
PDF file. This information will be in sequential pieces, and may be used to generate the PDF document
hash value. The information is supplied as binary values in the character buffer; the length to read is
supplied as the second parameter.
2 A length of 0 (zero) passed in the callback function indicates that no further data is to be read, and the
hash may be finalized.

DLI Reference Guide A.141
dlpdfsignaturesetpkcs7cert (DLPDFSIGNATURE *signature,
int maxLen, int (*genPKCS7Cert)(char *))
Return Value: void
Description
Parameters
Return Value
This function sets the certificate generation callback for DLPDF-
SIGNATUREs of type dlpdfsigacropkcs7 and dlpdfsigverisign.
• DLPDFSIGNATURE *signature: signature with which
certificate will be associated
• int maxlen: number of bytes provided to the
genPKCS7Cert callback
• int (*genPKCS7Cert)(char *): callback function, called during
the dlpdfdocwritepdf function call; see Technical Notes
below.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocwritepdf
dlpdfsignaturesetdatacallback
dlpdfsignaturesetx509cert
All DLI-supported platforms.
Technical Notes
1 For these signature types, dlpdfsigacropkcs7 and dlpdfsigverisign, the application using
DLI is required to generated a fully-formed PKCS #7 certificate with an MD5 checksum of the PDF
document, encrypted with the private key corresponding to the public key in the certificate. The RSA
public-key algorithm with a 1024-bit key length is used.
2 The genPKCS7Cert callback is called by DLI during the dlpdfdocwritepdf function call. The
callback is supplied a binary data buffer of length maxLen. The first 16 bytes of this buffer contain the
MD5 checksum (in binary) for the PDF document to sign. The callback must generate a PKCS #7
certificate as described above, and fill the data buffer with the certificate, in binary. The callback
function must return the length to read from the data buffer, in bytes.
NOTE: maxLen bytes are set aside in the output PDF file for the PKCS #7
certificate, and will be written to the PDF file regardless of the actual certificate
length. Callers should pass length values which are close to the certificate length,
if possible.

A.142 DLI Implementation and Reference Guide
dlpdfsignaturesetx509cert (DLPDFSIGNATURE *signature,
char *certificate, int certLen, void (*encryptSHA1Hash)(char *))
Return Value: void
Description
Parameters
Return Value
This call associates an x.509 v3 certificate with a DLPDFSIGNA-
TURE object created as a dlpdfsigacrox509 certificate digital
signature.
• DLPDFSIGNATURE *signature: signature with which
x.509 v3 certificate will be associated
• char *certificate: a binary buffer in the certificate
parameter; DLI will read certLen bytes from this buffer and
make a copy for the PDF file's digital signature
• int certLen: number of bytes to be read from certificate
buffer
• void (*encryptSHA1Hash)(char *): callback
function, called during the dlpdfdocwritepdf function
call; see Technical Notes below.
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfdocwritepdf
dlpdfsignaturesetpkcs7cert
All DLI-supported platforms.
Technical Notes
1 It is an error to call this with a DLPDFSIGNATURE object created as a different certificate type.
2 The last parameter is a required callback function. This function will be called during the
dlpdfdocwritepdf function call. It will be passed a character string containing the SHA-1 hash for
the PDF file being written, as a NULL-terminated string of hexadecimal digits using PKCS #1 padding,
containing a BER OID (object identifier) for the SHA-1 algorithm. The buffer is 256 bytes long (not
including the NULL terminator), and formatted as
0001FFFF .. FF003021300906052B0E03021A05000414
[ 40 hex digits for SHA-1 hash ]
3 The callback function must encrypt this hash value with the private key corresponding to the public
key in the signature's x.509 certificate, and fill the buffer passed in with 256 hexadecimal digits
representing the encrypted value for the supplied BER formatted hash. A 1024-bit key is used for
encryption operations. Note that the signed hash will not have padding, and must be exactly 256
hexadecimal digits. Zeros must be used for padding, if required.

DLI Reference Guide A.143
dlpdfterm (DLPDFINSTANCE * instance)
Return Value: void
Description
Parameters
Return Value
Terminates the Adobe PDF Library and DLI. All active documents
should be closed prior to this call.
DLPDFINSTANCE *instance
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdfinit,
dlpdfttload
All DLI-supported platforms.
Technical Notes
1 This will typically be one of the last calls of a program using DLI.
2 In a multi-threaded application, each thread must do its own initialization and termination of the
Library.
3 dlpdfinit and dlpdfterm are the only methods which must not be enclosed in exception handlers
(i.e. DURING/HANDLER/END_HANDLER statements), because they are not set up before initialization,
and are freed during termination.
4 As of DLI v3.0.11, the dlpdfterm call now removes memory files used for the dlpdfttload call if
the Files In Memory filesystem is used, and if these files are no longer in use.

A.144 DLI Implementation and Reference Guide
dlpdftext (void *Text, ASUns32 Length, ASAtom Encoding)
Return Value: DLPDFTEXT*
Description
Parameters
Return Value
Returns a DLPDFTEXT structure for the given Text and
Length, in the given Encoding.
• void *Text: the text to be passed to the DLPDFTEXT
structure
• ASUns32 Length: Length of the Text string in bytes.
• ASAtom Encoding: Encoding of the input Text; a valid
ICU Encoding value; see Technical Notes below
DLPDFTEXT*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftextfromutf8,
dlpdftextfromutf16be,
dlpdftextfromutf16he,
dlpdftextfromutf16le,
dlpdftextfromutf32be,
dlpdftextfromutf32he,
dlpdftextfromutf32le
All DLI-supported platforms.
Technical Notes
1 Text passed to this method does not require a NULL terminator, since its Length is given as a calling
argument. Conversely, the related methods listed above do not accept a Length argument, and
assume that a NULL terminator is present.
2 Valid ICU Encoding values for the Encoding argument of this method can be obtained via the
dlpdftextshowencodingnames call.

DLI Reference Guide A.145
dlpdftextadvance (DLPDFTEXT *Text, DLPDFFONT *Font,
PDEGraphicState *GState, PDETextState *TState,
ASFixed PointSize, ASFixed SetWidth, dlpdftext_X XMeaning,
ASFixed Angle, ASFixedPoint *Advance)
Return Value: void
Description
Parameters
Return Value
This method supplies the x and y advance for a string in a DLP-
DFTEXT area.
• DLPDFTEXT *Text: the text structure to be acted upon
• DLPDFFONT *Font: The specified font
• PDEGraphicState *GState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path
• PDETextState *TState: Current text state; should not
be NULL. A zero-filled PDETextState parameter is
permitted.
• ASFixed PointSize: Point size
• ASFixed SetWidth: Set width
• dlpdftext_X XMeaning: DLPDFTEXT_X_LEFT or
DLPDFTEXT_X_RIGHT, used to indicate whether the
starting location is the left or right end (respectively) of the
text, distinguishing a left-to-right line order (e.g. English)
from a right-to-left line order (e.g. Arabic)
• ASFixed Angle: Angle of flow, in degrees, as an
ASFixed counterclockwise angle
• ASFixedPoint *Advance: The returned x and y position
change after evaluation of the text
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.146 DLI Implementation and Reference Guide
dlpdftextdestroy (DLPDFTEXT *Text)
Return Value: void
Description
Parameters
Return Value
This method destroys the indicated DLPDFTEXT instance.
DLPDFTEXT *Text: the text structure to be acted upon
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext
All DLI-supported platforms.

DLI Reference Guide A.147
dlpdftextfromutf16be (void *Text)
Return Value: DLPDFTEXT*
Description
Parameters
Return Value
Returns a DLPDFTEXT structure for the given UTF16 big-endian
Unicode Text string.
void *Text: the text to be passed to the DLPDFTEXT structure
DLPDFTEXT*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext,
dlpdftextfromutf16he,
dlpdftextfromutf16le,
dlpdftextfromutf32be,
dlpdftextfromutf32he,
dlpdftextfromutf32le,
dlpdftextfromutf8
All DLI-supported platforms.
Technical Notes
1 Text passed to this method requires a NULL terminator. Only the related method dlpdftext will
accept unterminated text strings, since that method includes Length as an additional calling
argument.

A.148 DLI Implementation and Reference Guide
dlpdftextfromutf16he (void *Text)
Return Value: DLPDFTEXT*
Description
Parameters
Return Value
Returns a DLPDFTEXT structure for the given UTF16 hostendian
Unicode Text string.
void *Text: the text to be passed to the DLPDFTEXT structure
DLPDFTEXT*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext,
dlpdftextfromutf16be,
dlpdftextfromutf16le,
dlpdftextfromutf32be,
dlpdftextfromutf32he,
dlpdftextfromutf32le,
dlpdftextfromutf8
All DLI-supported platforms.
Technical Notes
1 Text passed to this method requires a NULL terminator. Only the related method dlpdftext will
accept unterminated text strings, since that method includes Length as an additional calling
argument.

DLI Reference Guide A.149
dlpdftextfromutf16le (void *Text)
Return Value: DLPDFTEXT*
Description
Parameters
Return Value
Returns a DLPDFTEXT structure for the given UTF16 littleendian
Unicode Text string.
void *Text: the text to be passed to the DLPDFTEXT structure
DLPDFTEXT*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext,
dlpdftextfromutf16be,
dlpdftextfromutf16he,
dlpdftextfromutf32be,
dlpdftextfromutf32he,
dlpdftextfromutf32le,
dlpdftextfromutf8
All DLI-supported platforms.
Technical Notes
1 Text passed to this method requires a NULL terminator. Only the related method dlpdftext will
accept unterminated text strings, since that method includes Length as an additional calling
argument.

A.150 DLI Implementation and Reference Guide
dlpdftextfromutf32be (void *Text)
Return Value: DLPDFTEXT*
Description
Parameters
Return Value
Returns a DLPDFTEXT structure for the given UTF32 big-endian
Unicode Text string.
void *Text: the text to be passed to the DLPDFTEXT structure
DLPDFTEXT*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext,
dlpdftextfromutf16be,
dlpdftextfromutf16he,
dlpdftextfromutf16le,
dlpdftextfromutf32he,
dlpdftextfromutf32le,
dlpdftextfromutf8
All DLI-supported platforms.
Technical Notes
1 Text passed to this method requires a NULL terminator. Only the related method dlpdftext will
accept unterminated text strings, since that method includes Length as an additional calling
argument.

DLI Reference Guide A.151
dlpdftextfromutf32he (void *Text)
Return Value: DLPDFTEXT*
Description
Parameters
Return Value
Returns a DLPDFTEXT structure for the given UTF32 hostendian
Unicode Text string.
void *Text: the text to be passed to the DLPDFTEXT structure
DLPDFTEXT*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext,
dlpdftextfromutf16be,
dlpdftextfromutf16he,
dlpdftextfromutf16le,
dlpdftextfromutf32be,
dlpdftextfromutf32le,
dlpdftextfromutf8
All DLI-supported platforms.
Technical Notes
1 Text passed to this method requires a NULL terminator. Only the related method dlpdftext will
accept unterminated text strings, since that method includes Length as an additional calling
argument.

A.152 DLI Implementation and Reference Guide
dlpdftextfromutf32le (void *Text)
Return Value: DLPDFTEXT*
Description
Parameters
Return Value
Returns a DLPDFTEXT structure for the given UTF32 littleendian
Unicode Text string.
void *Text: the text to be passed to the DLPDFTEXT structure
DLPDFTEXT*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext,
dlpdftextfromutf16be,
dlpdftextfromutf16he,
dlpdftextfromutf16le,
dlpdftextfromutf32be,
dlpdftextfromutf32he,
dlpdftextfromutf8
All DLI-supported platforms.
Technical Notes
1 Text passed to this method requires a NULL terminator. Only the related method dlpdftext will
accept unterminated text strings, since that method includes Length as an additional calling
argument.

DLI Reference Guide A.153
dlpdftextfromutf8 (void *Text)
Return Value: DLPDFTEXT*
Description
Parameters
Return Value
Returns a DLPDFTEXT structure for the given UTF8 Unicode
Text string.
void *Text: the text to be passed to the DLPDFTEXT structure
DLPDFTEXT*
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext,
dlpdftextfromutf16be,
dlpdftextfromutf16he,
dlpdftextfromutf16le,
dlpdftextfromutf32be,
dlpdftextfromutf32he,
dlpdftextfromutf32le
All DLI-supported platforms.
Technical Notes
1 Text passed to this method requires a NULL terminator. Only the related method dlpdftext will
accept unterminated text strings, since that method includes Length as an additional calling
argument.

A.154 DLI Implementation and Reference Guide
dlpdftextlength (DLPDFTEXT *Text)
Return Value: ASUns32
Description
Parameters
Return Value
This method returns the length, in bytes, of the buffer for the
stored string. NULL string terminators are not stored, and thus
are not counted as part of the length.
DLPDFTEXT *Text: the text structure to be acted upon
ASUns32
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext,
dlpdftextstring
All DLI-supported platforms.

DLI Reference Guide A.155
dlpdftextshowencodingnames (char *FileName)
Return Value: void
Description
Parameters
Return Value
Returns an output file of the given FileName, listing all valid
Encoding names provided via the International Components for
Unicode (ICU) module for use when calling dlpdftext to
construct the DLPDFTEXT object.
char *FileName: Name for the output file to be created
void
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext
All DLI-supported platforms.

A.156 DLI Implementation and Reference Guide
dlpdftextstring (DLPDFTEXT *Text)
Return Value: char *
Description
Parameters
This method returns the byte buffer for the stored string.
DLPDFTEXT *Text: the text structure to be acted upon
Return Value char *
Exceptions
Header
Related Methods
Availability
dli.h
dlpdftext,
dlpdftextlength
All DLI-supported platforms.

DLI Reference Guide A.157
dlpdftexttocontent (DLPDFTEXT *Text,
DLPDFCONTENT *Content, DLPDFFONT *Font,
PDEGraphicState *GState, PDETextState *TState,
ASFixed PointSize, ASFixed SetWidth, ASFixed XPos,
ASFixed YPos, dlpdftext_X XMeaning, ASFixed Angle)
Return Value: void
Description
Parameters
Parameters (continued)
Return Value
This method pastes the DLPDFTEXT string into a DLPDFCON-
TENT area.
• DLPDFTEXT *Text: the text structure to be acted upon
• DLPDFCONTENT *Content: the target structure in which
the text will be pasted
• DLPDFFONT *Font: The specified font
• PDEGraphicState *GState: Contains definitions of
colors to be applied, and line sizes and parameters to be used
when drawing a path
• PDETextState *TState: The current text state. This
should not be NULL. A zero-filled PDETextState
parameter is permitted.
• ASFixed PointSize: Point size
• ASFixed SetWidth: Set width
• ASFixed Xpos: X position of starting point within
DLPDFCONTENT
• ASFixed Ypos: Y position of starting point within
DLPDFCONTENT
• dlpdftext_X XMeaning: DLPDFTEXT_X_LEFT or
DLPDFTEXT_X_RIGHT, used to indicate whether the
starting location is the left or right end (respectively) of the
text, distinguishing a left-to-right line order (e.g. English)
from a right-to-left line order (e.g. Arabic)
• ASFixed Angle: Angle of flow, in degrees, as an
ASFixed counterclockwise angle
void
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.

A.158 DLI Implementation and Reference Guide
dlpdfttload (DLPDFINSTANCE *Instance, ASFile TTFont,
ASAtom *Names, int NameLen)
Return Value: int
Description
Parameters
Return Value
This method loads the given font from an ASFile TrueType or
OpenType font file, or the fonts from a TrueType/OpenType Collection
font file. These fonts are loaded into the supplied DLPD-
FINSTANCE. Fonts loaded in this manner are used before
searching the system directories for fonts.
• DLPDFINSTANCE *Instance: the DLPDFINSTANCE for
which the font(s) will be loaded
• ASFile TTFont: fonts from file or collection to be loaded
• ASAtom *Names: pointer to font ASAtom(s) to be loaded
(one or more)
• int NameLen: number of ASAtom *Names to be
completed
int: Number of fonts loaded
Exceptions
Header
dli.h
Related Methods
Availability
All DLI-supported platforms.
Technical Notes
1 This method does not fully support Adobe CFF-format OpenType font files. CMaps as defined in the
PDF Reference Manual should be used for these fonts. Datalogics recommends creating them as
CIDType0 fonts, using dlpdfcontentwidetext for setting text.
2 DLI does not search directory paths or environmental variable entries for fonts loaded via
dlpdfttload.
3 If a given font file has already been loaded, dlpdfttload returns a -1, and does not re-parse the font
file (for performance reasons).
4 As of DLI v3.0.11, the dlpdfterm call now removes memory files used for the dlpdfttload call if
the Files In Memory filesystem is used, and if these files are no longer in use.

DLI Reference Guide A.159
GetGraphicFromList (DLPDFDOC *Doc, char *Name)
Return Value: DLPDFIMAGE*
Description
Parameters
Return Value
Obtains a DLPDFIMAGE* by specifying the target document
and the key for the graphic file.
• DLPDFINSTANCE *Instance: Represents the document
structure and the current status of the document at all times.
• char *Name: Name string
DLPDFIMAGE*: NULL is returned if the graphic is not found.
Exceptions
Header
Related Methods
Availability
dli.h
LoadGraphicList
Available on OS/390 only

A.160 DLI Implementation and Reference Guide
LoadGraphicList (char *ListFileName)
Return Value: void
Description
Parameters
Return Value
Reads a cross-reference file which maps graphics keys to their
physical location. The cross-reference table is accessed by the
GetGraphicFromList method, and, once read, is stored in
memory for the duration of the job.
char *ListFileName: File name
void
Exceptions
Header
Related Methods
Availability
dli.h
GetGraphicFromList
Available on OS/390 only

Index
A
A key
Use in Links 13.8
AcroForm (Sample DLI Application) 17.15
action (parameter)
Use in Annotations and Links 13.2
Action Dictionary
Use in Links
Creating Replacement 13.8
Modifying 13.8
Actions
in Annotations and Links 13.2
Adobe
Acrobat 1.6, 1.7, 1.8, 2.2, 2.5, 14.1, 17.7, A.97
Distiller 1.9, 2.5, 17.6
Normalizer Server 11.2, 17.6
Reader 1.6, 1.7, 1.9, 2.2, 2.5, 4.8, 13.4, 14.1,
17.7, A.97
Technical Notes
#5189 (Adobe PDF Library Overview) 1.8
#5190 (Acrobat Core API Overview) 1.8
#5191 (Acrobat Core API Reference) 1.8
#5414 (PDF Library Supplement to the
Acrobat Core API) 1.8
ADOBECMP
OS/390 Location Search 4.11
AdobeFnt.lst 2.2
Efficient use of 2.3
Naming variations 2.3
Search path definition via PDFLDataRec 2.2
Use in Default Search Path Suppression 1.16,
1.17
ADOBERES
OS/390 Location Search 4.11
allocProc
Use in Setting Memory Allocation Routines 2.4
Annotation Dictionary
Modifying 13.8
Annotations
action (parameter) 13.2
Border Specification 13.4
Color Specification 13.4
Components 13.2
Content 13.4
hot spot (parameter) 13.2
Introduction 13.1
Link
Overview 13.2
Modifying for Other Actions 13.2
Open/Close Flag 13.4
Opening the Document with Annotations
Showing 14.4
Text
Overview 13.2
Title 13.4
Annotations (Sample DLI Application) 17.12
Annotations and Links
Borders
Color 13.3
Definition 13.3
Calls 13.4, 13.5, 13.6, 13.7, 13.8
Colors
Links 13.3
Text Annotations (when closed) 13.3
ArcTo (PostScript operator) 8.6, A.4
ASCII
Use in Displaying Images 11.9
ASCII85
Use in Displaying Images 11.6
ASFile 17.13
ASFileSys
Specifying an Alternate File System via
dlpdfinit 2.8
Use in Image Search using Files in Memory 1.16,
2.9
Use in Initializing and Terminating via DLI 2.8,
2.9
Use in Specifying an Alternate File System 2.8
ASFixed
Use in Basic Color Spaces
Device Gray 12.6
Use in Color Channels
Definitions 12.5
Inversion Correction 12.5
Precision Correction 12.5
Use in Color Description 12.2
ASFixedMatrix
Use in Line Drawing 10.12
ASFixedRect
Use in Displaying Images 11.8
ASFixedRectangle
Use in Annotations and Links 13.4, 13.5
hot spot Definition 13.2
ASGetErrorString
Use in Error Handling 16.2, 16.4
ASGetExceptionErrorCode
Use in Error Handling 16.2
ASPathName
Use in Writing PDF Output to Memory 2.13
ASSize_t
Use in Writing PDF Output to Memory 2.14

I.ii
DLI Implementation and Reference Guide
B
Background patterns, creating 17.14
Backwards Compatibility, Ensuring 1.10, 2.6
BBox (parameter)
Use in Content Interface Calls 8.15
Use in Displaying Images 11.8
Use in Forms 9.2
Bézier Curve
Use in
dlpdfpathaddcurve 8.13
dlpdfpathaddcurver 8.13
dlpdfpathaddcurvev 8.13
dlpdfpathaddcurvey 8.14
Use in Line Drawing
Basic points 10.9, A.115
Calls 10.9, 10.10
Parameters 10.9, A.115
Bitmaps
Image Conversion from 11.2
Use in Image Color Spaces 12.2
blobs (Binary Large OBjects) 17.13
Bookmarks
Accessing DLPDFOUTLINE fields 14.4
Building Multiple Trees 14.2
Calls 14.2, 14.3, 14.4
DLPDFOUTLINE 14.2, 14.3
DLPDFOUTLINE->Count 14.4
DLPDFOUTLINE->Obj 14.4
DLPDFOUTLINE->Open 14.4
Introduction 14.1
Opening Document with Annotations
Showing 14.4
Outline Tree 14.2
Overview 14.2
PageMode 14.4
PDViewDestNull 14.2
Border
Use in Annotations and Links 13.4
Border (parameter)
Use in Annotation Dictionary 13.8
BoundingBox (PostScript statement) A.73
Browser
Specifying via Acrobat 13.7
C
CalGray
Use in Color Spaces
Basic 12.7
Calibrated Gray Scale 12.4
calloc
Alternate Routines for 2.4
PDFInit.h Interface to 2.4
CalRGB
Use in Color Spaces
Basic 12.7
Cautions
Color Models must be Freed before Closing 12.3
Do not Exit from within Error Handler 16.2
Initialize pre-v6.1 Library and DLI only once 2.8
Invalid Font Creation 4.7
Scale Before Rotating Image 10.13
Transformation, Undesirable Side-Effects via
dlpdfcontentrotate 7.2
CGM (Computer Graphics Metafile)
Use in Graphical Language Forms 11.4
CIDToGID Conversion Map 4.3
CIDType2 font
Terminology usage 4.3
Clipping Path A.6
Use in Line Drawing 8.5
CMYK Color
Collapsing to Gray 12.12
Converting to RGB 12.13
Use in Color Description 12.2
Use in ICC Based Color Profile 12.8
Color
Color Description Components 12.2
Converting Values to Binary 12.5
of Annotations and Links 13.3
Use in Annotations and Links 13.4
Use in Images 12.2
Use with PDFGraphicState 12.2
Color (parameter)
Use in Annotation Dictionary 13.8
Color Channels
Inversion Correction 12.5
Precision Correction 12.5
Value Conversion and Inversion 12.5
Values for 12.5
Color Models
/DeviceCMYK
Order of Values Assumed 11.5
Use in Displaying Images 11.5
/DeviceGray
Use in Displaying Images 11.5
/DeviceRGB
Order of Values Assumed 11.5
Use in Displaying Images 11.5
/Indexed
Use in Displaying Images 11.5
Order of Values 11.5
Color Profile
Use in Color Spaces
Basic 12.8
Color Spaces
Advanced
DeviceN 12.9
Indexed 12.9
Overview 12.8
Patterned 12.9
Separation 12.8

Index
I.iii
Basic
Calibrated Gray 12.7
Calibrated RGB 12.7
CIE Calibrated Color 12.5
CIE Lab 12.7
Device CMYK 12.6
Device Gray 12.6
Device RGB 12.6
ICC Based 12.8
Conversion of Values between Models
CMYK To Gray 12.12
CMYK to RGB 12.13
Overview 12.12
RGB to CMYK 12.13
RGB to Gray 12.12
Creating and Destroying 12.3
Patterned
Building 12.10
Repeating References 12.11
ColorSpace
Use in Displaying Images 11.10
Comments
Use in Adding to Content Elements 8.17
Compression
Activating 3.2, A.33
Calls 3.2
Flate
Use in Displaying Images 11.6
Use in Documents, Beginning and
Ending 3.2, A.33
Containers within Pages 7.1
Inversion 7.4
Overview 7.2
Scaling 7.3
Content Elements
representation by DLPDFCONTENT 8.2
Content Interface Calls 8.3
Adding Comments to Content Elements 8.17
Calls 8.17
Associating Content to Page 8.17
Calls 8.17
Control Structures 8.2
Creation and Positioning 8.3
Calls 8.3
Line Drawing 8.5
Calls 8.5, 8.6, 8.7
Fill Color 8.5
kPDEEoFill 8.5
kPDEFill 8.5
kPDEStroke 8.5
Paint Operator 8.5
PDEGraphicState 8.5
Overview 8.2
Paths 8.7
Appending Line Segments 8.8
Calls 8.8, 8.9, 8.10, 8.11, 8.12, 8.13, 8.14,
8.15
Calls 8.7, 8.8
Patterns 8.15
Calls 8.15
Referencing Predefined Structures 8.16
Calls 8.16
Text Placement 8.4
Calls 8.4
Text Width Evaluation 8.4
Calls 8.4
Conventions, Document 1.6
CosDictRemove
Use in Links
Replacing 13.8
CosDoc
Use in Document Creation 3.2
cosImage
Use in Displaying Images 11.10
CosNull
Use in Links 13.8
CosObj
Use in Annotations and Links 13.2, 13.8
Use in Image Color Spaces 12.2
CosStructure
Use in Image Color Spaces 12.2
Cross-Reference File, OS/390
Use in Displaying Images 11.9
CTM Matrix
Use in Line Drawing 10.6
Current Point
Use in Line Drawing 10.6
D
dash
Use in Line Drawing 10.15
Dashed and Dotted Lines 10.15
Data Structure, Library 2.2
DDName
Use in Displaying Images 11.9
Dest (parameter)
Use in Annotation Dictionary 13.8
Use in Bookmarks 14.4
Use in Links
Replacing 13.8
Destination
Adding to Name Tree 13.7
Obtaining Name 13.8
Use in Links 13.6, 13.7
Use of, vs. Name 13.6
Destination Dictionary
Use in Bookmarks 14.3
DeviceCMYK
Creating Color Space for 12.3
Use in Color Spaces
Advanced 12.9
Basic 12.6
DeviceGray
Creating Color Space for 12.3
Use in Color Spaces
Advanced 12.9

I.iv
DLI Implementation and Reference Guide
Basic 12.6
DeviceN
Use in Color Spaces
Advanced 12.9
DeviceRGB
Creating Color Space for 12.3
Use in Color Spaces
Advanced 12.9
Basic 12.6
Digital Signatures
Appearance layers 15.3, 15.4
Calls
dlpdfdoccreatesignature 15.3
dlpdfdocsetsignatureappearance 15.4
dlpdfpageplacesignature 15.5
dlpdfsignaturesetdatacallback 15.5
dlpdfsignaturesetpkcs7cert 15.4
dlpdfsignaturesetx509cert 15.4
Components of 15.2
imageBBox (signature bounding box) 15.5
Introduction 15.1
Overview 15.2
Public and Private Keys 15.2
sigType (plug-in compatibility) 15.3
dirList
Use in Setting Resource Directories 2.2
DLExceptionCode
Use in Error Handling 16.4
DLExceptionFlag
Use in Error Handling 16.3, 16.4
DLExceptionMessage
Use in Error Handling 16.4
DLI
DLI-selected PDF Level Declarations 2.6
How to Create a PDF Document 1.2
Initialization in DLI v3.0 1.11
Introduction 1.2
Overriding DLI-selected PDF Level
Declarations 2.6
Required Initialization 1.3
DLPDFCONTENT 8.2
Use by dlpdftexttocontent 1.14
Use in Displaying Images 11.10
Use in Line Drawing 10.11
Use in Patterned Colors 12.2
Use with CIDType2 fonts 4.3
dlpdfcontent objects 1.2
dlpdfcontentarc A.2
Use in Content Interface Calls 8.6
Use in Line Drawing 10.4
dlpdfcontentarcn A.3
Use in Content Interface Calls 8.6
Use in Line Drawing 10.4
dlpdfcontentarcto A.4
Use in Content Interface Calls 8.6
Use in Line Drawing 10.4
dlpdfcontentcircle A.5
Use in Content Interface Calls 8.7
Use in Line Drawing 10.5
dlpdfcontentclip A.6
Use in Content Interface Calls 8.5
dlpdfcontentclipend A.6, A.7
Use in Content Interface Calls 8.5
Use in Line Drawing 8.5
dlpdfcontentcomment A.8
Use in Content Interface Calls 8.17
dlpdfcontentcreate A.9
Use in Content Interface Calls 8.3
dlpdfcontentdrawpath
Use in Line Drawing 10.6, 10.11
dlpdfcontentellipse A.10
Use in Content Interface Calls 8.7
Use in Line Drawing 10.5
dlpdfcontentfontskew A.11
dlpdfcontentgstate A.12
Use in Displaying Images 11.10
dlpdfcontentline A.13
Use in Content Interface Calls 8.6
Use in Line Drawing 10.3
dlpdfcontentpath A.14
Use in Content Interface Calls 8.5, 8.6
Use in Line Drawing 8.5, 10.2, 10.5
dlpdfcontentpieslice A.10, A.15
Use in Content Interface Calls 8.7
Use in Line Drawing 10.4
dlpdfcontentpieslicen A.16
Use in Content Interface Calls 8.7
Use in Line Drawing 10.5
dlpdfcontentrect A.17
Use in Content Interface Calls 8.6
Use in Line Drawing 10.3
dlpdfcontentreferenceform A.18
Use in Content Interface Calls 8.16
Use in Forms 9.2
dlpdfcontentreferenceimage A.19
Usage example 8.16
Use in Content Interface Calls 8.16
Use in Displaying Images 11.2
dlpdfcontentrotate A.21
Use in Content Interface Calls 8.3
dlpdfcontentscale A.22
Use in Content Interface Calls 8.3
dlpdfcontenttext A.23, A.29
Use in Content Interface Calls 8.4
dlpdfcontenttextwidth A.24, A.30
Use in Content Interface Calls 8.4
dlpdfcontenttopage A.25
Use in Content Interface Calls 8.17
dlpdfcontenttranslate A.26
Use in Content Interface Calls 8.3
dlpdfcontentusefillpattern A.27, A.28, A.135
Use in Color Spaces
Advanced 12.10
Patterned 12.10

Index
I.v
Use in Content Interface Calls 8.15
dlpdfcontentusestrokepattern A.28, A.135
Use in Color Spaces
Advanced 12.10
Use in Content Interface Calls 8.15
dlpdfcontentwidetext A.29
Updates in DLI v3.0 1.14
Use in Content Interface Calls 8.4
dlpdfcontentwidetextwidth A.30
Use in Content Interface Calls 8.4
DLPDFDOC 2.6, A.37
EmbedFonts
Use in Documents, Beginning and Ending 3.3
Use in Creation Calls in DLI
Font Searching Sequence 4.6
Repetitive Calling 4.5
Use in Displaying Images 11.9
Use in Document Status 3.2
Use in Documents, Beginning and Ending 3.2
Encryption 3.4
Use in Initializing and Terminating via DLI 2.8,
2.10
Use in Multiple Document Creation 3.2
dlpdfdocasciips A.31
dlpdfdoccomplete A.32
dlpdfdoccompress A.33
Use in Documents, Beginning and Ending 3.2
dlpdfdoccosdoc A.34
dlpdfdoccreate A.35
Modifications in DLI v3.0 1.16
Updates in DLI v3.0 1.11
Use in Documents, Beginning and Ending 3.2
dlpdfdoccreatesignature A.36
Use in digital signatures 15.3
dlpdfdoccreatewithinstance
Removal from DLI v3.0 1.11
dlpdfdocdestroy A.37
dlpdfdocembedfonts A.38, A.63, A.64, A.65, A.66
Use in Documents, Beginning and Ending 3.3
Use of Document EmbedFonts Flag 4.4
dlpdfdocencrypt A.39
Use in Documents, Beginning and Ending 3.4
dlpdfdocHexGraphics A.41
dlpdfdoclinearize A.40
Use in Documents, Beginning and Ending 3.3,
3.4
dlpdfdocmakethumbnails A.41
Use in Documents, Beginning and Ending 3.3
dlpdfdocnameadd A.42
Use in Annotations and Links 13.6
Use in Links 13.7
dlpdfdocnamefind A.43
Use in Links 13.8
dlpdfdocoutline A.44
Use in Bookmarks 14.3
dlpdfdocoutlineadd A.45
Use in Bookmarks 14.2
dlpdfdocoutlineaddfromname A.47
Use in Bookmarks 14.3
dlpdfdocoutlinecosobj A.48
dlpdfdocoutlinefirst A.49
Use in Bookmarks 14.3
dlpdfdocoutlinelast A.50
Use in Bookmarks 14.3
dlpdfdocoutlinenext A.51
Use in Bookmarks 14.4
dlpdfdocoutlineparent A.52
Use in Bookmarks 14.4
dlpdfdocoutlineprev A.53
Use in Bookmarks 14.4
dlpdfdocpddoc A.54, A.101
Use in Page Interface 6.3
dlpdfdocsetdocinfo A.55
Use in Documents, Beginning and Ending 3.3
dlpdfdocsetencoding A.56
Use in Documents, Beginning and Ending 3.3
dlpdfdocsetencryptkeylen A.57
Use in Documents, Beginning and Ending 3.4,
3.5
dlpdfdocsetpdfname A.58
Use in Documents, Beginning and Ending 3.3
Use in Writing PDF Output to Memory 2.13
dlpdfdocsetpsname A.59
Use required for dlpdfdoccreate 1.15, 3.2, A.35
dlpdfdocsetsignatureappearance A.60
Use in digital signatures 15.4
dlpdfdocwritepdf A.58, A.61
Use in digital signatures 15.4, 15.5
Use in Documents, Beginning and Ending 3.4
with dlpdfdocencrypt 3.4
Use in Writing PDF Output to Memory 2.13
dlpdfdocwritePS A.59, A.62
Use required for dlpdfdoccreate 1.15, 3.2, A.35
DLPDFFONT 3.3, 4.3, 4.4, A.38
Font Attributes 4.4
Font Embedding Status 4.4
Font Subsetting Status 4.4
Use in Creation Calls in DLI 4.5
Repetitive Calling 4.5
WidthTable 4.6
dlpdffontcreate A.63, A.64, A.65, A.66
Use in Font Creation 4.5
Use in Font Searching Sequence 4.5
Use in Loading and Creating Fonts 5.3
Use in Multibyte Text Work 5.3
dlpdffontcreateembedded 4.5, A.63, A.64, A.65,
A.66
Use in Font Creation 4.5, 4.6
Use in Loading and Creating Fonts 5.3
dlpdffontcreatewithmetrics A.63, A.64, A.65, A.66
Use in Font Creation 4.5, 4.7
Use in Loading and Creating Fonts 5.4
Use in Matching System Fonts 4.7
dlpdffontcreatewithmetricsembedded A.63, A.64,
A.65, A.66
Use in Font Creation 4.5, 4.8
DLPDFFORM 9.2
Use in Digital Signatures 15.2, 15.4

I.vi
DLI Implementation and Reference Guide
dlpdfformcreate A.68
Use in Forms 9.2
dlpdfformdestroy A.69
Use in Forms 9.3
DLPDFIMAGE
Use in Displaying Images 11.2, 11.5, 11.8, 11.9,
11.10
dlpdfimagecreatefrombmp A.70
Use in Displaying Images 11.10
Use in Image Color Spaces 12.2
dlpdfimagecreatefromfile A.71
Use in Displaying Images 11.8
Use in Image Search using Files in Memory 1.17,
2.10
dlpdfimagecreatefrompdf A.72
What’s New in DLI v3.0 1.12
dlpdfimagecreatefromps A.73
dlpdfimagegetsize A.74
Use in Content Interface Calls 8.16
dlpdfinit A.75
Caution on Multiple Initializations of Library 2.8
Error Handler not required 3.2, A.75, A.143
Invoking Files in Memory 17.2
Note on Writing PDF Output to Memory 2.9
Specifying an Alternate File System 2.8
Updates in DLI v3.0 1.11
Use in Default Search Path Suppression 1.17
Use in Files in Memory 2.7
Use in Initializing and Terminating the
Library 2.10
Failure to Initialize 2.8
Use in Initializing and Terminating via DLI 2.8,
2.9, 2.10
Use in Multi-Thread Initializations 2.11
Use in Specifying an Alternate File System 2.8
Use in Terminating Library 2.10
Using a Graphics Cache 2.9
DLPDFINSTANCE
Addition in DLI v3.0 1.11
Unicode font translation via ICU 4.3
Use by dlpdfttload 1.14
Use in Creation Calls in DLI
Font Searching Sequence 4.6
Use in dlpdfdoccreate 1.15, 1.16, 3.2
Use in Initializing and Terminating the
Library 2.10
Use in Initializing and Terminating via DLI 2.8,
2.10
Use in Terminating Library 2.10
dlpdfinstancesetcancelproc A.77
dlpdfinstancesetgrcachelimits A.78
dlpdfinstancesetprogressmonitor A.80
dlpdfmatrixrotate A.81
Use in Line Drawing 10.13
dlpdfmemfileacquire A.81, A.82
Use in Writing PDF Output to Memory 2.13, 2.14
dlpdfmemfiledata A.83, A.84
Use in Writing PDF Output to Memory 2.13, 2.14
dlpdfmemfiledeleteonclose A.84
Note on usage for file deletion 1.12
dlpdfmemfilerelease A.85
Use in Writing PDF Output to Memory 2.13, 2.14
dlpdfmemfilesetbuffer A.86
dlpdfmemfilesetdata A.87
Differences from dlpdfmemfilesetbuffer A.86
Use in Image Search using Files in Memory 1.17,
2.9
Use in Writing PDF Output to Memory 2.14
dlpdfmemfilesize 2.14, A.88
Use in Writing PDF Output to Memory 2.13, 2.14
dlpdfmemfilesys A.89
Use in Files in Memory 2.7
Use in Image Search using Files in Memory 1.17,
2.9
Use in Initializing and Terminating the Library 2.8
Use in Initializing and Terminating via DLI 2.9
Use in Specifying an Alternate File System 2.8
dlpdfmemfilesysgetmemusage A.90
dlpdfmemfilesyssetmemlimit A.91
dlpdfmemfiletransientprefix A.92
Use in Writing PDF Output to Memory 2.13, 2.14
DLPDFOUTLINE
Use in Bookmarks 14.2, 14.3, 14.4
DLPDFPAGE 6.2
dlpdfpage objects 1.2
dlpdfpageaddlinkannotation A.93
Use in Annotations and Links 13.5
dlpdfpageaddlinkannotationfromname A.95
Use in Annotations and Links 13.6
dlpdfpageaddtextannotation A.96
Use in Annotations and Links 13.4
dlpdfpageaddwebannotation A.97
Use in Links 13.7
dlpdfpagecosobj A.98
Use in Page Interface 6.3
dlpdfpagecreate A.99
Use in Page Interface 6.2
dlpdfpagefindfromnumber A.100
Use in Page Interface 6.2
dlpdfpagenumber A.101
Use in Page Interface 6.3
dlpdfpageplacesignature A.137
Use in digital signatures 15.5
dlpdfpagerotate A.102
Use in Page Interface 6.3
dlpdfpagesetart A.103
dlpdfpagesetbleed A.104
dlpdfpagesetcrop A.105
dlpdfpagesetid A.106
Use in Page Interface 6.3
dlpdfpagesetmediabox A.107
dlpdfpagesettrim A.108
DLPDFPATH
Effect of DLPDFPath.scaling on

Index
I.vii
PDEGraphicState.lineWidth 10.14
Use in Line Drawing 10.6, 10.7, 10.11, 10.14
Use in Paths 8.7
dlpdfpathaddarc A.109
Use in Content Interface Calls 8.10
Use in Line Drawing 10.7
dlpdfpathaddarcn A.110
Use in Content Interface Calls 8.10
Use in Line Drawing 10.8
dlpdfpathaddarcto A.111
Use in Content Interface Calls 8.11
dlpdfpathaddclose
Use in Content Interface Calls 8.14
Use in Line Drawing 10.6, 10.11
dlpdfpathaddcurve A.114
Use in Content Interface Calls 8.13
Use in Line Drawing 10.9
dlpdfpathaddcurver A.116
Use in Content Interface Calls 8.13
Use in Line Drawing 10.9
dlpdfpathaddcurvev A.117
Use in Content Interface Calls 8.13
Use in Line Drawing 10.10
dlpdfpathaddcurvey A.118
Use in Content Interface Calls 8.14
Use in Line Drawing 10.10
dlpdfpathaddelliparc
Use in Content Interface Calls 8.11
dlpdfpathaddelliparcn A.120
Use in Content Interface Calls 8.12
dlpdfpathaddelliparcto A.121
Use in Content Interface Calls 8.12
dlpdfpathaddline A.122
Use in Content Interface Calls 8.8
Use in Line Drawing 10.7
dlpdfpathaddliner A.123
Use in Content Interface Calls 8.9
Use in Line Drawing 10.7
dlpdfpathaddmove A.124
Use in Content Interface Calls 8.9
Use in Line Drawing 10.7
dlpdfpathaddmover A.125
Use in Content Interface Calls 8.9
Use in Line Drawing 10.7
dlpdfpathaddrect A.126
Use in Content Interface Calls 8.14
Use in Line Drawing 10.10
dlpdfpathadelliparc A.119
dlpdfpatharray A.127
Use in Content Interface Calls 8.8
dlpdfpathclear A.128
Use in Content Interface Calls 8.7
Use in Line Drawing 10.6
dlpdfpathclosepath A.113
dlpdfpathcreate A.129
Use in Content Interface Calls 8.7
Use in Line Drawing 10.6
dlpdfpathcurrentx A.130
Use in Content Interface Calls 8.8
dlpdfpathcurrenty A.131
Use in Content Interface Calls 8.8
dlpdfpathdestroy A.132
Use in Content Interface Calls 8.7
Use in Line Drawing 10.6
dlpdfpathsetmatrix A.133
Use in Content Interface Calls 8.14
Use in Line Drawing 10.12
dlpdfpathsize A.134
Use in Content Interface Calls 8.8
DLPDFPATTERN 8.15
Parameters
BBox 8.15
Colored 8.15
TileType 8.15
Xstep 8.15
Ystep 8.15
dlpdfpatterncreate A.27, A.135
Use in Color Spaces
Advanced 12.10
Patterned 12.10
Use in Content Interface Calls 8.15
dlpdfpatternrotate A.136
dlpdfseterrorfile A.138
dlpdfsetwarningfile A.139
DLPDFSIGNATURE
Use in Digital Signatures 15.4
dlpdfsignaturesetdatacallback A.140
Use in digital signatures 15.5
dlpdfsignaturesetpkcs7cert A.141
Use in digital signatures 15.4
dlpdfsignaturesetx509cert A.142
Use in digital signatures 15.4
dlpdfterm A.143
Error Handler not required 3.2, A.75, A.143
Use in Initializing and Terminating the
Library 2.10
Use in Initializing and Terminating via DLI 2.10
Use in Multi-Thread Initializations 2.11
Use in Terminating Library 2.10
DLPDFTEXT 17.18
Use in Multibyte Text Work 5.6
dlpdftext A.144
Obtaining Encoding names via
dlpdftextshowencodingnames 1.13,
A.155
Use in Multibyte Text Work 5.4
Associated shortcut functions 5.5
DLPDFTEXT (structure) 1.16, 5.2
Addition in DLI v3.0 1.11
Creating 5.4, 5.5
Performance Considerations 5.9
Shortcut Functions 5.5
Unicode font translation via ICU 4.3
Use by dlpdftextdestroy 1.14
Use by dlpdftexttocontent 1.14
Use in dlpdftext (method) A.144
Use in dlpdftextadvance A.145
Use in dlpdftextdestroy A.146

I.viii
DLI Implementation and Reference Guide
Use in dlpdftextlength A.154
Use in dlpdftextstring A.156
Use in dlpdftexttocontent A.157
What’s New in DLI v3.0 1.13, 1.14
Working with 5.6, 5.7, 5.8
dlpdftextadvance A.145
Use in Multibyte Text Work 5.6
dlpdftextdestroy A.146
Use in Multibyte Text Work 5.8
dlpdftextfromutf16be A.147
Use in Multibyte Text Work 5.5
dlpdftextfromutf16he A.148
Use in Multibyte Text Work 5.5
dlpdftextfromutf16le A.149
Use in Multibyte Text Work 5.5
dlpdftextfromutf32be A.150
Use in Multibyte Text Work 5.5
dlpdftextfromutf32he A.151
Use in Multibyte Text Work 5.5
dlpdftextfromutf32le A.152
Use in Multibyte Text Work 5.5
dlpdftextfromutf8 A.153
Use in Multibyte Text Work 5.5
dlpdftextlength A.154
Use in Multibyte Text Work 5.6
dlpdftextshowencodingnames A.155
Use in Multibyte Text Work 5.5
dlpdftextstring A.156
Use in Multibyte Text Work 5.6
dlpdftexttocontent A.157
Use in Multibyte Text Work 5.7
dlpdfttload A.158
Clearance of memory files by dlpdfterm 1.15
Note on no default font searching 2.2
Use in Font Searching Sequence 4.6
Use in Multibyte Text Work 5.3
Document Conventions 1.6
Document Handle
Use in Links 13.8
Document Information
Calls 3.3
Document Interface
Use with Error Handler 3.2
Document Opening
with Annotations Showing 14.4
Documents, Beginning and Ending
Calls 3.2, 3.3, 3.4
Overview 3.2
E
E_RETURN(X)
Use in Error Handling 16.3
E_RTRN_VOID
Use in Error Handling 16.3
eMemFileSys
Use in Files in Memory in DLI Samples 17.2
Encoding
Generation of Grid via FontVerification (Sample
DLI Application) 17.10
Encoding Vector 4.8
Encrypt (Sample DLI Application) 17.7
Changing Security Settings 17.7
DocOwner Password 17.7
ValidUser Password 17.7
Encryption
Calls 3.4
Setting Encryption Key Length 3.4
Use in Documents, Beginning and Ending 3.4
EPS (Encapsulated PostScript)
Image Conversion from 11.2
Use in Graphics (Sample DLI Application) 17.5
Error Handling
ASGetErrorString 16.2
ASGetExceptionErrorCode 16.2
DURING 16.2, 16.3
E_RETURN(X) 16.3
E_RTRN_VOID 16.3
END_HANDLER 16.2, 16.3
Exception Codes from Methods 16.3
Exception Names 16.2
HANDLER 16.2, 16.3
Handler Constructs
Multiple 16.3
Risks of Returning from within 16.3
Handler Mechanism 16.2
OS/390 Platform Concerns 16.3
Overview 16.2
Errors
Communication back to Application 16.2
Link
"Browser is Busy" 13.7
OS/390
Not Using SAS/C
ASGetErrorString 16.4
DLExceptionCode 16.4
DLExceptionFlag 16.3, 16.4
DLExceptionMessage 16.4
Using SAS/C 16.3
Outer Error Catcher 16.2
Examples
Adding Outline Entries 14.3
with a Named Destination 14.3
Bitmapped Graphic via
dlpdfimagecreatefrombmp 11.4
Collapsing
CMYK to Gray 12.13
RGB to Gray 12.12
Converting
CMYK to RGB 12.14
RGB to CMYK 12.13
Creating
Calgray Color Space 12.4

Index
I.ix
Gray Color Space
Assembler 12.3
C coding 12.3
Link Annotation 13.5
Link To A Named Destination 13.6
Named Destination 13.7
Text Annotations 13.4
Drawing a Rectangle and Ellipse in Path
Operators 10.11
Filling an Area with a Pattern 12.11
Inserting
EPSF Image with
dlpdfimagecreatefromps 11.6
PDF Image
via dlpdfimagecreatefromfile 11.8
via dlpdfimagecreatefrompdf 11.7
Line Drawing Using Fixed Structure 10.5
Modifying a Goto Link into a GotoR Link 13.9
Multiple Containers per Page with Rotation 7.6
Setting the Page Mode to Display Navigation
Pane 14.4
Transparent Graphics via Imagemasks 11.10
Exception Handlers, Required Use 3.2
Exceptions
Use in Error Handling 16.2
F
Filename, Setting Output PDF
Calls 3.3
Files in Memory
Activating within MultiDoc sample 2.7, 17.2
Activation 2.7
MEMORY Command Line Argument, Use
of 17.2
Use of dlpdfinit 17.2
Use of eMemFileSys in DLI Samples 17.2
Use of FileSystemType in DLI Samples 17.2
Files, Transient 2.13
FileSystemType
Use in Files in Memory in DLI Samples 17.2
fill (parameter)
Use in Displaying Images 11.4
Fill Color
Use in PDEGraphicState 10.2
fillColorSpec
Use in Color Description 12.2
Use in Line Drawing 10.14
Fit Type
Use in Bookmarks 14.2
FitDescription
Use in Annotations and Links 13.5
FitType
Use in Annotations and Links 13.5
Use in Links 13.5
Values
Fit 13.5
FitB 13.5
FitBH 13.5
FitBV 13.5
FitH 13.5
FitR 13.5
FitV 13.5
XYZ 13.5
Fixed Rectangle
Use in Bookmarks 14.2
Flate Compression
Use in Displaying Images 11.6
flatness
Use in Line Drawing 10.15
FOLIO 6.3, A.106
Font Dump
Via FontVerification (Sample DLI
Application) 17.10
Font Searching Sequence 4.5
FontFaux (Sample DLI Application) 17.9
Fonts
Accessing 4.11
OS/390-specific 4.11
Calls 3.3
Code Page Support 4.10
Composite Fonts
CIDType0 4.3
CIDType2 4.3
Overview 4.2
Creation Calls in DLI
Calls 4.5, 4.6, 4.7, 4.8
dlpdffontcreatewithmetrics
Width Table 4.8
Font Searching Sequence 4.5
Matching Calls to System Fonts 4.7
Overview 4.5
Performance Considerations 4.11
Repetitive Calling 4.5
Default Encoding Selection 3.3
differences between characters and glyphs 4.2
Embedding
Document EmbedFonts flag 4.4
Subsetting Limitations 4.4
Font Dump via FontVerification (Sample DLI
Application) 17.10
Font Searching Sequence 4.5
Overview 4.2
PDFLDataRec
Use in Setting Resource Directories 2.2
Predefined Font Encodings 4.9
Encoding Font Types Table 4.9
Resources, Identifying Non-Standard Locations
of 2.2
Search Paths 2.2
Simple Fonts 4.2
Standard Encoding
Default Setting 3.3
Structure of a DLI Font 4.3
Terminology usage
CIDType2 font 4.3
TrueType font 4.3

I.x
DLI Implementation and Reference Guide
Unicode 4.10
Use in Multibyte Text Work 5.3
WinAnsiEncoding
Default Setting 3.3
FontVerification (Sample DLI Application) 17.10
Encoding Grid 17.10
Slow Feedback from 17.11
Table of Contents 17.10
Form XObjects
Use in Displaying Images 11.8
Forms 9.2
Calls 9.2, 9.3
dlpdfformcreate
Use of Bounding Box 9.2
Content Complexity 9.2
Destruction 9.2
Overview 9.2
Structure 9.2
Use in Referencing Predefined Structures 8.16
Forms XObjects
Association with Content Structures 8.2
Use in Content Interface 8.2
free
Alternate Routines for 2.4
PDFInit.h Interface to 2.4
Free Software Foundation 1.4
freeProc
Use in Setting Memory Allocation Routines 2.4
G
gcc Compilation Version 1.3
genErrBadParm 4.6, 6.2
Use in Annotations and Links 13.4
GetGraphicFromList A.159
Use in Displaying Images 11.9
GetGraphicFromList, OS/390
Use in Displaying Images 11.9
GIF (Graphics Interchange Format)
Encoding and Compression References 11.3
Image Conversion from 11.2
Use in Displaying Images 11.8
Use in Graphics (Sample DLI Application) 17.5
Glyph IDs 4.3
GoTo
Use in Annotation Dictionary 13.8
Graphics (Sample DLI Application) 17.5
Graphics cache
What’s New in DLI v3.0 1.13
Graphics, One-Bit
Use in Displaying Images 11.10
grayScale
Use in Color Description 12.2
Use in ICC Based Color Profile 12.8
H
HelloDLI (Sample DLI Application) 17.3
Comparison with helowrld.c 2.15
HeloWrld (Sample Adobe PDF Library
Application) 17.3
Comparison with hellodli.c 2.15
hot spot (parameter)
Definition of 13.2
Use in Annotations and Links 13.2, 13.5
Hyperlinks
Use in Links 13.7
I
ICC (International Color Consortium) 12.8
ICCBased
Use in Color Spaces
Advanced 12.9
Use in ICC Based Color Profile 12.8
ICU (International Components for Unicode)
Obtaining Encoding names via
dlpdftextshowencodingnames 1.13,
A.155
Unicode font translation via ICU 4.3
Use in Multibyte Text Work 5.2
What’s New 1.11
Image Import Improvements in DLI v3.0 1.12
Imagemask
ImageMask key 11.10
Note on Use of Bitmaps 11.5
Use in Displaying Images 11.10
ImageName
Use in Displaying Images 11.3
Images, Displaying
EPS Pass-Through Objects 11.6
Example 11.6
Graphic Image Forms
Bitmaps 11.3
Example 11.4
Graphical Language 11.4
Graphic Image Structures
Destroying 11.3
Formats Supported 11.2
ImageName Use 11.3
Multiple Document Use 11.2
Image Creation Methods
Assorted Formats
dlpdfimagecreatefromfile 11.8
Example 11.8
Supported Formats 11.8
Bitmaps
Compression and Filtering 11.6
dlpdfimagecreatefrombmp 11.5
Values within Color Models 11.5
EPS

Index
I.xi
dlpdfimagecreatefromps 11.6
Example 11.6
Form XObject
dlpdfimageplaceascontent 11.8
GetGraphicFromList 11.9
LoadGraphicList 11.9
PDF
dlpdfimagecreatefrompdf 11.7
Example 11.7
Transparent Graphics
dlpdfcontentgstate 11.10
Imagemasks 11.10
Sample 11.10
Included EPS Images Not Appearing in PDF
Pages 11.2, 11.6
Overview 11.2
Indexed (atom)
Use in Color Spaces
Advanced 12.9
Initializing and Terminating the Library
Comparison of Applications with and without
DLI 2.15
Files In Memory
Activation 2.7
Image Search using Files in Memory 2.9
Output to Memory, Writing PDF 2.13
Calls 2.14
Transient Files 2.13
Overview 2.2
PDFLDataRec Initialization 2.2
Memory Allocation Routines, Setting 2.3
Resource Allocation Routines, Setting 2.4
Resource Directories, Setting 2.2
Terminating 2.10
Thread-Safe Issues
Initialization of non-thread-safe Library
releases 2.12
Multi-Thread Initializations 2.11
mutex (Mutual Exclusion algorithm) 2.12
Version Number, Obtaining 2.5
With DLI
Calls 2.8, 2.9, 2.10
Overview 2.7
Specifying an Alternate File System 2.8
Typical Order of Calls 2.11
Using a Graphics Cache 2.9
Intended Audience 1.3
J
JPEG/JPG (Joint Photographic Experts Group)
Encoding and Compression References 11.3
Use in Displaying Images 11.8
Use in Graphics (Sample DLI Application) 17.5
K
Keys, Public and Private 15.2
kPDEEoFill
Use in Content Interface Calls 8.5
Use in Line Drawing 10.2, 10.3, 10.11, 10.14
Use in PDEGraphicState 10.2
kPDEFill
Use in Content Interface Calls 8.5
Use in Line Drawing 10.2, 10.3, 10.11, 10.14
Use in PDEGraphicState 10.2
kPDEStroke
Use in Content Interface Calls 8.5
Use in Line Drawing 10.2, 10.3, 10.11, 10.14
Use in PDEGraphicState 10.2
kPDEStroke | kPDEEoFill
Use in Line Drawing 10.11
kPDEStroke | kPDEFill
Use in Line Drawing 10.11
kPDFLInitIgnoreDefaultDirectories
Use in Default Search Path Suppression 1.17, 2.3
kPDFLVersion
Use in Obtaining Version Number 2.5
L
Lab
Use in Color Spaces
Basic 12.7
Use in ICC Based Color Profile 12.8
Library Data Structure 2.2
Line Drawing 10.1
Directly-Drawn Methods 10.3
Calls 10.3, 10.4, 10.5
Common Parameters 10.3
dlpdfcontentpath
Example 10.5
Graphic State 10.14
Overview 10.2
Path Drawing Methods 10.6
Calls 10.6, 10.7, 10.8, 10.9, 10.10, 10.11,
10.12
Common Parameters 10.6
Example 10.11
Transformation Matrix 10.12
Arguments 10.12
dlpdfmatrixrotate 10.13
Inversion Matrix 10.12
Mirror-image matrix 10.12
Rotation Matrix 10.12
Scale/Rotation Caution 10.13
Scaling 10.13
Shearing 10.13
Translations 10.12
Unity Matrix 10.12
Linearization
Calls 3.3
Use in Documents, Beginning and Ending 3.3,

I.xii
DLI Implementation and Reference Guide
3.4
lineCap
Use in Line Drawing 10.15
lineJoin
Use in Line Drawing 10.14
lineWidth
Use in Line Drawing 10.14
Link Annotation
Modifying 13.8
Link Cos Object
Modifying 13.8
Links
action (parameter) 13.2
Calls 13.4, 13.5, 13.6, 13.7, 13.8
Components 13.2
Cross-document 13.6
Destination Page Number 13.5
FitType 13.5
hot spot (parameter)
Definition of 13.2, 13.5
Introduction 13.1
List of Possible Actions 13.8
Modifying 13.8
Overview 13.2
URI 13.7
URL 13.7
Zoom 13.5
listLen
Use in Setting Resource Directories 2.2
LoadGraphicList A.160
M
Major Version Number 2.5
malloc
Alternate Routines for 2.4
PDFInit.h Interface to 2.4
Matrix operations
Rotations 17.4
Translation of Paths 17.4
MDFile
Use in Writing PDF Output to Memory 2.13, 2.14
memAvailProc
Use in Setting Memory Allocation Routines 2.4
memFiles (Sample DLI Application) 17.13
MEMORY
Use in Files in Memory Activation 17.2
Memory Allocation Routines, Setting 2.3
allocProc 2.4
freeProc 2.4
memAvailProc 2.4
reallocProc 2.4
Minor Version Number 2.5
Miter
Use in Line Drawing 10.15
miterLimit
Use in Line Drawing 10.15
Multibyte Text
Commands 5.3, 5.4, 5.5, 5.6, 5.7, 5.8
Creating DLPDFTEXT Areas 5.4
Introduction 5.2
Loading and Creating Fonts 5.3
Performance Considerations 5.9
Working With DLPDFTEXT Areas 5.6
MultiDoc (Sample DLI Application) 17.13
Required Arguments 17.13
mutex (Mutual Exclusion algorithm) 2.12
N
name
Use in Links
instead of Destination 13.6
name (parameter)
Use in Links 13.7, 13.8
Name Tree A.42
Adding Destination 13.7
Use in Annotations and Links 13.6
hot spot Definition 13.2
Use in Links 13.6
Named Destination
Use in Annotations and Links 13.6
Names
Use in Annotations and Links 13.6
vs. Destinations 13.6
NestedPDF (Sample DLI Application) 17.14
NotEmbedded (flag) 3.3, 4.4, A.38
Notes
"Browser is Busy" Error during Link 13.7
Adobe CFF OpenType font files may not properly
subset 5.3
ASN membership may be required for Adobe
website access 1.8
Base 14 Fonts
Creation Allowed by dlpdffontcreate 4.5
Bitmapped Images under 500 Bytes Always
Merged Inline 11.5
BMP images with LZW skip markers may not embed
properly 17.6
Cache size limit is checked every time a document
is destroyed 2.9, A.76, A.79
CFF-format OpenType font files not fully
supported 1.14
Colorizing via Stroke and Fill 8.5, 10.2
Default-filesystem settings may need updating
for images in memory 1.17, 2.10
Digital Signature signed hash values must be exactly
256 hex digits 15.4
Disk resources used by default if Output to Memory
is not set 2.9
DLI v2.2 Unicode support now superceded by
new Multibyte text methods 5.2

Index
I.xiii
dlpdfcontentarcto Discrepancies with PostScript
Output 10.4
DLPDFINSTANCE required for Unicode font
creation 1.11
dlpdfmemfiledeleteonclose required for memory
file deletion 1.12
dlpdfpathaddarcto Line Drawing Details 10.8
dlpdfpathaddclose, Adding Disjoint Path Segments
After 10.11
dlpdfttload does not re-parse previously-loaded
font file 5.3
Document Sharing of COS Objects and
PDEColorSpaces 12.4
Encryption Key Length, Setting in Multiple
Documents 3.5
Error Handling should conform to Adobe
guidelines 16.2
File Sizes, Effect on, by
Repeated Graphical Object References 11.9
Files in /Codesamples folder not buildable source
as-is 1.5, 11.10
Fill Operator Not Valid via dlpdfcontentline 10.3
Fill Patterns are Never Destroyed 12.11
Font Encoding, Limitations on Predefined 4.7
Font not licensed for embedding will be created
as Referenced instead 3.3, 4.4
Function Return Value is Undefined if Error
Occurs 16.3
Graphic Conversions,Some Unavailable on OS/
390 and OS/400 11.3, 11.8
Graphic Key on OS/390 Must be ASCII
String 11.9
Images cached by filename 17.6
Included EPS Images Not Appearing in PDF
Pages 11.2, 17.5
Library is not thread-safe 1.3
No default font searching for dlpdfttload 2.2
Only fonts using standard encodings may be
fauxed 17.10
Pass accurate length values for PKCS #7 certificate
output space reservation 15.5,
A.141
Pattern Interaction with Color when Drawing
Figures 10.14
PDColorValue Permits Only 4 Channels 12.9
PDEPathGetData Requirement for Path Data
Retrieval 10.5
PDEPathGetData Return Value 8.6
PDF Reference Manual errata file available for
download 1.8
Popup warning may occur for new PDF in old
viewers 1.10, 2.6
RSA encryption algorithm within SignDoc sample
not recommended for Production
code 17.16
Sample applications are subject to change 17.2
Slow Feedback from FontVerification (Sample DLI
Application) 17.11
Structure Variations may exist between PDF 1.6
O
and earlier 1.3
Type is Filled, Not Stroked 12.2
Type0 Fonts must be Subset if Embedded 4.6
Unicode NULL string terminators not required or
included in calculations A.29, A.30
Upgrade applications to thread-safe capability as
soon as possible 2.12
WideText sample application uses fonts not distributed
with DLI 17.18
Outline Tree
Adding New Entry 14.2
Use in Bookmarks
Building Multiple Trees 14.2
Output File, Writing
Calls 3.3, 3.4
Document Information 3.3
Encryption 3.4
Linearization 3.4
Security Permissions 3.4
P
Page
Use in Content Interface 8.2
Page Interface Calls 6.2, 6.3
Page Structure 6.2
PageMode
Use in Bookmarks 14.4
Paint Operator
Use in Content Interface Calls 8.5
Use in Line Drawing 10.2
Pass-Through Objects
Use in Displaying EPS Images 11.6
Passwords
Setting in Encrypt (Sample DLI Application) 17.7
Paths (Sample DLI Application) 17.4
Patterned Colors 12.2
Patterns, creating background 17.14
PCKS #7-format certificates 17.16
PD_STD_ENCODING (flag) 17.10
PDColorValue
Use in Color Spaces
Advanced 12.9
PDDoc 3.2
PDDocSetNewSecurityData
Use in Documents, Beginning and Ending 3.5
PDEColorSpace
Creating and Destroying 12.3
Document Sharing 12.4
Use in Color Description 12.2
PDEColorSpaceCreate
Creating and Destroying 12.4
Use in Color Spaces
Advanced 12.8, 12.9

I.xiv
DLI Implementation and Reference Guide
Basic 12.7
Use in ICC Based Color Profile 12.8
PDEColorSpaceCreateFromName
Use in Color Spaces
Advanced 12.8, 12.9
Basic 12.7, 12.8
PDEColorSpaceGetCosObj
Use in Image Color Spaces 12.2
PDEDash
Use in Line Drawing 10.15
PDEDeviceNColorData
Use in Color Spaces
Advanced 12.9
PDEFontAttrs 4.4, 4.7, 17.9, 17.10
charset field 4.8
encoding field 4.7
type field 4.7
Use in Creation Calls in DLI 4.5
wMode field 4.8
PDEGraphicState 8.4, 8.5
Color Definitions 10.2
Use in Color Description 12.2
Use in Content Interface 8.2
Use in Displaying Images 11.10
Use in Line Drawing 10.2, 10.11, 10.14
dash 10.15
fillColorSpec 10.14
flatness 10.15
lineCap 10.15
lineJoin 10.14
lineWidth 10.14
miterLimit 10.15
effect on lineJoin 10.14
strokeColorSpec 10.14
PDEGrayCalFlt
Use in Color Spaces
Basic 12.7
PDEICCBasedColorData
Use in ICC Based Color Profile 12.8
PDEIndexedColorData
Use in Color Spaces
Advanced 12.9
PDELabCalFlt
Use in Color Spaces
Basic 12.7
PDEPath
Use in Line Drawing 10.5
PDEPathAddSegment
Cited in PDF Rules for Path Construction 10.5
PDEPathGetData A.14
Use in Content Interface Calls 8.6
Use in Line Drawing 8.6, 10.5
PDERGBCalFlt
Use in Color Spaces
Basic 12.7
PDESeparationColorData
Color Spaces
Advanced 12.8
PDETextState 8.4
Use in Content Interface 8.2
PDF
Image Conversion from 11.2
Level Declarations in Output 1.9, 2.5
Declarations via DLI 1.10
DLI-selected Declarations 2.6
Overriding DLI-selected Declarations 2.6
Use in Displaying Images 11.7, 11.8, 11.9
Use in Graphical Language Forms 11.4
Use in Graphics (Sample DLI Application) 17.5
PDF Library
Use in Multithreaded Applications 1.9
Version Control 1.9, 2.5
PDF Page Tree Structures 6.2
PDFInit.h
Use in Setting Memory Allocation Routines 2.4
Use in Setting Resource Allocation Routines 2.4
PDFLDataRec 2.11
Use in Default Search Path Suppression 1.17
Use in Initializing and Terminating the Library 2.2
Use in Setting Memory Allocation Routines 2.3
Use in Terminating Library 2.10
PDFLGetVersion
Use in Obtaining Version Number 2.5
PDFLInit
Caution on Multiple Initializations of pre-v6.1
Library 2.8, A.75
Prohibition on calling from DLI v3.0 1.11, A.75
Use in Default Search Path Suppression 1.17
Use in Initializing and Terminating via DLI 2.8
Use in Multi-Thread Initializations 2.11
PDFLTerm
Prohibition on calling from DLI v3.0 1.11, A.75
Use in Multi-Thread Initializations 2.11
pdfMajorVer 2.6
pdfMinorVer 2.6
PDFNeeded (flag)
Removal from dlpdfdoccreate 1.15, A.35
PDPerms
Use in Documents, Beginning and Ending
Encryption 3.4
PDViewDestNull
Use in Bookmarks 14.2
Use in Links
with Zoom 13.5
Performance Considerations
Font Creation Calls in DLI 4.11
Plugins
Self-Sign 17.16
VeriSign Signature 17.16
PNG (Portable Network Graphics)
Encoding and Compression References 11.3
Image Conversion from 11.2
Use in Displaying Images 11.8
Use in Graphics (Sample DLI Application) 17.5

Index
I.xv
Private keys 15.2
psOutput (Sample DLI Application) 17.17
Public keys 15.2
Q
QuickDraw
Use in Graphical Language Forms 11.4
R
RAW (Unformatted Unannotated Bitmap)
Use in Graphics (Sample DLI Application) 17.5
readme.txt 1.8, 1.9
realloc
PDFInit.h Interface to 2.4
reallocProc
Use in Setting Memory Allocation Routines 2.4
Rect (parameter)
Use in Annotation Dictionary 13.8
Rectangles
Use in Links 13.5
Release Notes 1.8
Resource Allocation Routines, Setting 2.4
Resource Directories, Setting
Use in Initializing and Terminating the Library 2.2
Resources
Adobe
Adobe Acrobat Core API Overview 1.8
Adobe Acrobat Core API Reference 1.8
Adobe PDF Library Overview 1.8
Adobe PDF Library Supplement to the Acrobat
Core API 1.8
Portable Document Format Reference
Manual 1.8
Errata file 1.8
Datalogics
Adobe PDF Library and DLI Installation
Guide 1.7
Adobe PDF Library Developer Overview 1.7
DLI Implementation and Reference Guide 1.7
Java Interface User Guide 1.7
RGB Color
Collapsing to Gray 12.12
Converting to CMYK 12.13
Use in Annotations and Links 13.3
Use in Color Description 12.2
Use in ICC Based Color Profile 12.8
Rotate (flag), in imported image files 1.12
RSA encryption algorithm 17.16
S
Sample DLI Applications
AcroForm 17.15
Activating Files in Memory 17.2
Annotations 17.12
Encrypt 17.7
FontFaux 17.9
FontVerification 17.10
Graphics 17.5
HelloDLI 17.3
memFiles 17.13
MultiDoc 17.13
NestedPDF 17.14
Overview 17.2
Paths 17.4
psOutput 17.17
SignDoc 17.16
WideText 17.18
Security Permissions
Use in Documents, Beginning and Ending
Encryption 3.4
Use in Encrypt (Sample DLI Application) 17.7
Self-Sign Plugin 17.16
Separation
Color Spaces
Advanced 12.8
Seven-Bit Safe
Use in Displaying Images 11.6
Signatures
as images in Digital Signatures 15.3
SignDoc (Sample DLI Application) 17.16
Standard Encoding
Use in Documents, Beginning and Ending 3.3
StdSecurityDataRec
Use in Documents, Beginning and Ending 3.5
sticky note
Use in Annotations and Links 13.4
Streaming PostScript
Removal from DLI v3.0 1.11
stroke (parameter)
Use in Displaying Images 11.4
Stroke Color 8.5
Use in PDEGraphicState 10.2
strokeColorSpec
Use in Color Description 12.2
Use in Line Drawing 10.14
Sub-minor Version Number 2.5
SubType (parameter)
Use in Annotation Dictionary 13.8
Use in Links 13.8
T
Table of Contents
Generation via FontVerification (Sample DLI
Application) 17.10
Text Container
Creation and Positioning 8.3
Text Placement Calls 8.4
Text Layering 8.2
Text Width 8.4
Thread Safety

I.xvi
DLI Implementation and Reference Guide
Caution on Multiple Initializations of pre-v6.1
Library 2.8
Initialization of non-thread-safe Library
releases 2.12
Multi-Thread Initializations 2.11
Thumbnails
Calls 3.3
Use in Documents, Beginning and Ending 3.3
TIFF (Tagged Image File Format)
Encoding and Compression References 11.3
Image Conversion from 11.2
Use in Displaying Images 11.8
Use in Graphics (Sample DLI Application) 17.5
TKAllocatorProcs
Use in Setting Memory Allocation Routines 2.4
TKResourceProcs
Use in Setting Resource Allocation Routines 2.4
Transformation Matrix
Arguments 10.12
Overview 10.12
Translations
Inversion 10.12
Mirror-image 10.12
Rotation 10.12, 10.13
Scale/Rotation Caution 10.13
Scaling 10.13
Shearing 10.13
Translation 10.12
Transforms
Association with Content Elements 8.2
Tree Name
Use in Links 13.7
TrueType font
Terminology usage 4.3
Type
Filled vs. Stroked 12.2
Type (parameter)
Use in Annotation Dictionary 13.8
Use in Links 13.8
U
Unicode
as CIDType2 Fonts 4.3
Text Support
Font Type Recommendations 4.10
NULL string terminators A.29, A.30
Unix Compiler Run-Time Libraries 1.4
URI
Use in Links 13.7
URL
Use in Links 13.7
UseOutlines
Use in Bookmarks 14.4
V
VeriSign signature plugin 17.16
Version Number, Obtaining 2.5
W
What’s New in Previous Releases
DLI v2.2.12
Default Search Path Suppression 1.17
DLI v2.2.13
Default Search Path Suppression Expanded to
All Platforms 1.16
Image Search using Files in Memory 1.16
DLI v3.0
Addition of DLPDFTEXT Structure 1.11
Adobe PDF Library now Thread-Safe 1.9
Deleted Functions
dlpdfdoccreatewithinstance 1.16
dlpdfdocHexGraphics 1.15
dlpdfdocsetembedappwidth 1.15
dlpdfdocseterrorfile 1.16
dlpdfdocsetformsascontent 1.15
dlpdfdocsetwarningfile 1.16
dlpdfdocsevenbitsafe 1.15
dlpdffontverifytext 1.16
dlpdfimageplaceascontent 1.15
dlpdfsetlevel 1.16
Digital Signature Support 1.10
DLI Initialization now Required 1.11
Enhanced Unicode Support 1.11
New Functions
dlpdfdocasciips 1.13
dlpdfdoccreatesignature 1.13
dlpdfdocsetsignatureappearance 1.13
dlpdfinstancesetgrcachelimits 1.13
dlpdfmemfiledeleteonclose 1.12
dlpdfmemfilesetbuffer 1.12
dlpdfmemfilesysgetmemusage 1.12
dlpdfmemfilesyssetmemlimit 1.12
dlpdfpageplacesignature 1.13
dlpdfsignaturesetdatacallback 1.13
dlpdfsignaturesetpkcs7cert 1.13
dlpdfsignaturesetx509cert 1.13
dlpdftext 1.13
dlpdftextadvance 1.14
dlpdftextdestroy 1.14
dlpdftextfromutf16be 1.13
dlpdftextfromutf16he 1.13
dlpdftextfromutf16le 1.13
dlpdftextfromutf32be 1.13
dlpdftextfromutf32he 1.13
dlpdftextfromutf32le 1.13
dlpdftextfromutf8 1.13
dlpdftextlength 1.14
dlpdftextshowencodingnames 1.13

Index
I.xvii
dlpdftextstring 1.14
dlpdftexttocontent 1.14
dlpdfttload 1.14
PDF Image Import Improvements 1.12
Streaming PostScript Removed 1.11
Updated Functions
dlpdfdoccreate 1.15
dlpdfinit 1.14, 1.15
dlpdfterm 1.15
What’s New in This Release
Overview 1.8
Revised DLI Version Numbering 1.9
WideText (Sample DLI Application) 1.11, 17.18
WinAnsiEncoding
Use in Documents, Beginning and Ending 3.3
WMF (Windows Metafile Format)
Use in Graphical Language Forms 11.4
Writing Pages
Procedure for 1.2
X
x.509 certificate 17.16
XYZ
Use in Links
with Zoom 13.5
Z
zoom
Use in Bookmarks 14.2
Use in Links 13.5

I.xviii
DLI Implementation and Reference Guide

Index
I.xix

I.xx
DLI Implementation and Reference Guide

Index
I.xxi