DLI Implementation and Reference Guide

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; 08/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 [email protected] 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.9 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.16

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.11

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.9 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.5Plus 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/pdflibrary- requirements.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 last- minute 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 This guide provides background 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 and PDF Library API Overview This guide provides an overview of the Acrobat API in general. It covers information applicable to both Plug-in development and PDF Library development. Read this document to obtain an understanding of how the Acrobat API is organized.

Acrobat and PDF Library API Reference This is the reference manual for all of the Acrobat API methods made available to the Acrobat Viewer and Adobe PDF Library. 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.

NOTE: As of the v7.x release series, the former "PDF Library Supplement to the Acrobat Core API" (Technical Note #5414) is now combined with this manual, as a separate section near the back of the main book.

3D Annotations Tutorial As its Introduction explains, "This tutorial describes how to programmatically create 3D annotations in PDF files. The code [...] can be used as part of an application developed using the Adobe PDF Library."

SnippetRunner Cookbook This documents the useful SnippetRunner sample application development tool, provided by Adobe as a means of rapidly developing new functions using Library methods, and testing them within the context of a working Library application. Getting Started 1.9

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 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 sub- version 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 1.10 DLI Implementation and Reference Guide

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 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 initialize 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 handle 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, AdobeFnt08.lst, AdobeFnt09.lst and so on; 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 HFTGetVersion:

• 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.

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, including the parent process and every child process, 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

Interception of File I/O When Using Files in Memory

The Files in Memory filesystem emulates a filesystem in memory, and "intercepts" file operations as you might expect. You should bear in mind the following points:

• When an ASFile is opened with the ASFILE_READ flag and without the ASFILE_CREATE mode flags, if a file by that name exists on disk (relative from the current working directory if given as a relative path or as a "pathless" filename), then it will be read into memory, and this will be used as the basis of the FIM ASFile. • When an ASFile is closed, if it was opened with the ASFILE_WRITE mode and its name does not start with the "transient file" prefix (returned via dlpdfmemfiletransientprefix ), it will be written to the path and filename used to open the file, if the path used in the filename exists. Again, this is interpreted as a relative path if a "pathless" pathname was used to open the file. Transient files (files starting with the specified prefix) will not be written to disk on closure. • When an ASFile is closed, it is not removed by default. This implementation was chosen to better emulate a standard I/O environment (where closing a file does not remove it from disk; rather, an explicit removal is required). One may call dlpdfmemfiledeleteonclose to signal that a specified file should be removed after all the active references to the file are released: when ASFileSysClose has been called for each ASFileSysOpenFile call, and when dlpdfmemfilerelease has been called for each dlpdfmemfileacquire call. Also, if the FIM file does not own the memory used for the file, it will not be released by FIM. 2.16 DLI Implementation and Reference Guide

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. 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.

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 suitably- named 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 Valid Font Types

AdobeStandardEncoding Type1,TrueType

WinAnsiEncoding Type1,TrueType

MacRomanEncoding Type1,TrueType

MacExpertEncoding Type1,TrueType

Identity-H CIDType0,CIDType2

Identity-V CIDType0,CIDType2

Other Predefined CMaps CIDType0

Adobe PDF Library v5.x and higher only:

WinCP1250 CIDType2

WinCP1251 CIDType2

WinCP1253 CIDType2

WinCP1254 CIDType2

WinCP1255 CIDType2 4.10 DLI Implementation and Reference Guide

Encoding String Value Valid Font Types

WinCP1256 CIDType2

WinCP1257 CIDType2

WinCP1258 CIDType2

MacCentralEuropean CIDType2

MacCroatian CIDType2

MacRomanian CIDType2

MacCyrillic CIDType2

MacUkranian CIDType2

MacGreek CIDType2

MacCentralEuropean CIDType2

MacTurkish CIDType2

MacArabic CIDType2

MacHebrew 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 platform- endian 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 byte- order 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

rotation 180 180

u.l u.l rotation 270 90 rotation u.l

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.

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:

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-zero- length 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 per- document 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. X1/Y1 Xint1/ Xint2/ Yint1 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.

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/ Xctrl2/ Yctrl1 Yctrl2

dlpdfpathaddcurvey

This method is identical to dlpdfpathaddcurve, except that the second control point is assumed to be the ending position. Xctrl1/ Yctrl1

Xend/ Yend Xctrl2/ Yctrl2 Xstart/ Ystart

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 can be accomplished in two ways. The first and more common method is as an image, in the sense of a PDF or PostScript Image Operator. The second is as an Encapsulated PostScript (EPS) file. One point to be aware of when including EPS images is that they 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.

In the collection of sample applications accompanying your DLI release is one named Graphics, which demonstrates DLI methods available for merging various graphic image formats in your PDF document, including PNG, JPEG/JPG, GIF, TIFF, PDF and RAW (bitmap). It may help to refer to this sample when reading the following sections.

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 grayscale,” 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. (the image width) • Its sixth parameter is the number of lines. (image depth) • Its seventh parameter is the number of bits per color channel of the bitmap, typically 8 (bits) to express 255 levels of each color. • 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.11

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. See “Identifying a Supported RAW Bitmap” on page 11.6 following for more details.

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.

Identifying a Supported RAW Bitmap

Many variants of bitmap exist, and their characteristics determine whether you can include them in your document via dlpdfimagecreatefrombmp. In certain cases you may need to do some pre-processing of your image bitmap to rework its data into a form that dlpdfimagecreatefrombmp will accept.

When we refer to "raw" format, we are referring to a collection of pixels as specified in the Adobe PDF Reference manual for image formats. (See Section 4.8.2 of the Adobe PDF Reference, "Sample Representation.") Each row must begin and end on a byte boundary, padded as necessary if the number of data bits per row is not a multiple of 8.

Regarding different variants of bitmap (e.g. Format16bppRgb555, Format24bppRgb), DLI does not explicitly include or exclude specific formats, but instead will attempt to support any format that generally fits the guidelines imposed by the Adobe PDF Reference, most notably those in Table 4.39 of that guide, "Additional entries specific to an image dictionary." These specify that:

• the number of bits per channel must be the same across channels • the number of bits per channel must be 1, 2, 4 or 8 (16 is also allowed if limited to PDF v1.5 compliance or higher.)

In particular, the bits per color channel (bpc) parameter of dlpdfimagecreatefrombmp maps to the /BitsPerComponent entry in the Image Xobject, and the color model parameter maps to the /ColorSpace entry. Thus some bitmap images may be usable as-is; others may require some preprocessing by you before they can be incorporated in your new PDF document.

dlpdfimagecreatefromps

This method will create an Encapsulated PostScript (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 Image Display 11.7

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 excerpt from the DLI sample application Graphics inserts an EPS pass-through object, which will display a graphic in the PostScript produced from PDF (though not when viewing 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);

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 excerpt from the DLI sample application Graphics 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); } Image Display 11.9

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.

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.

This excerpt from the DLI sample application Graphics inserts a PDF image via dlpdfimagecreatefromfile:

"C" Example: Inserting a PDF image with dlpdfimagecreatefromfile

Image = dlpdfimagecreatefromfile (Doc, "math.pdf");

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 11.10 DLI Implementation and Reference Guide

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. Image Display 11.11

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 as an imagemask if it contains one bit per pixel and no color space (a CosNull object for the ColorSpace parameter). 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. 11.12 DLI Implementation and Reference Guide 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 non- rectangular 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: Annotations and Links 13.9

"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)); 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-recently- called 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.5\DLI\Samples (or similar). On Windows platforms, a Visual Studio Solution file for all DLI samples can be found in C:\Datalogics\APDFL7.0.5\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 threshold algorithm. This threshold 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 threshold algorithm. This threshold 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" (case- sensitive, 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 full- page 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 supersedes 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 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.

Parameters • 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; path- drawing 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentarcn, dlpdfcontentarcto

Availability 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 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentarc, dlpdfcontentarcto

Availability 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 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentarc, dlpdfcontentarcn

Availability 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 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentellipse

Availability All DLI-supported platforms. A.6 DLI Implementation and Reference Guide

dlpdfcontentclip (DLPDFCONTENT *Content, ASFixed *Path, int PathLen, int EOClip) Return Value: void

Description Establish a clipping path. Note that clipping paths are not established automatically for images, forms, or line drawings. Gener- ally, PDF images page more efficiently if there is no clipping involved.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentclipend, dlpdfcontentpath

Availability 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 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.

Parameters 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentclip

Availability All DLI-supported platforms. A.8 DLI Implementation and Reference Guide

dlpdfcontentcomment (DLPDFCONTENT *Content, char *Comment) Return Value: void

Description This method will insert the specified text string as a comment, in the order provided, into the content elements.

Return Value 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 Creates a new content element with a rotation of zero degrees, a position of (0,0) and scaling of (1,1).

Parameters DLPDFDOC *Doc: represents the document structure and the current status of the document at all times.

Return Value 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 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentcircle

Availability All DLI-supported platforms. DLI Reference Guide A.11

dlpdfcontentfontskew (DLPDFCONTENT *Content, ASFixedMatrix *Matrix) Return Value: void

Description Causes the font currently in effect for this content structure to appear "twisted" according to the matrix supplied.

Return Value 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 Sets the graphics state of the specified DLPDFCONTENT to that of the PDEGraphicState. This may be done at any point during content placement operations.

Parameters • DLPDFCONTENT* Content: Represents the document structure and the current status of the document at all times. • const PDEGraphicState *newGState

Return Value 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 This procedure will mark a line in the content, extending from (X1,Y1) to (X2,Y2).

Return Value 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 This procedure will mark a path within the content.

Parameters • 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

Return Value 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 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentpieslicen

Availability 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 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentpieslice

Availability 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 This procedure marks a rectangle in the content. It will be located such that its lower left hand corner is at (X,Y).

Parameters • 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).

Return Value void

Exceptions

Header dli.h

Availability 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 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.

Parameters • 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.

Return Value 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 This procedure places a copy of the referenced image into the current content.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfimagegetsize (New in DLI v2.2.5)

Availability 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 Rotates all of the contents of a given content structure by the specified amount.

Parameters • 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.

Return Value 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 Scales all of the content of a given content structure by the specified amount.

Parameters • 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.

Return Value 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 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.

Parameters • 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.

Parameters (Continued) • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontenttextwidth, dlpdfcontentwidetext, dlpdfcontentwidetextwidth

Availability All DLI-supported platforms. A.24 DLI Implementation and Reference Guide

dlpdfcontenttextwidth (DLPDFFONT *Font, char *Text, ASFixed SetWidth, PDETextState *TState) Return Value: ASFixed

Description 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.

Parameters • 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.

Return Value ASFixed

Exceptions

Header dli.h

Related Methods dlpdfcontenttext, dlpdfcontentwidetext, dlpdfcontentwidetextwidth

Availability All DLI-supported platforms. DLI Reference Guide A.25

dlpdfcontenttopage (DLPDFCONTENT *Content, DLPDFPAGE *Page) Return Value: void

Description 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.

Parameters • 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.

Return Value 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 Moves all the contents of a content structure by the specified amounts.

Parameters • 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.

Return Value 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 Applies the fill pattern.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpatterncreate, dlpdfcontentusestrokepattern

Availability All DLI-supported platforms. A.28 DLI Implementation and Reference Guide

dlpdfcontentusestrokepattern (DLPDFCONTENT *Content, DLPDFPATTERN *Pattern) Return Value: void

Description Similar to dlpdfcontentusefillpattern, but strokes instead of filling.

Return Value

Exceptions

Header dli.h

Related Methods dlpdfcontentusefillpattern

Availability 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 Same as dlpdfcontenttext, but permits Unicode and MultiByte text.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontenttext, dlpdfcontenttextwidth, dlpdfcontentwidetextwidth

Availability 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 Same as dlpdfcontenttextwidth, but permits multi-byte (Unicode) text.

Parameters • 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.

Return Value ASFixed

Exceptions

Header dli.h

Related Methods dlpdfcontenttext, dlpdfcontenttextwidth, dlpdfcontentwidetext

Availability 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 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.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value 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 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 cus- tom file system), or as a method of imaging pages prior to writing the document.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocwritepdf, dlpdfdocwritePS

Availability All DLI-supported platforms. DLI Reference Guide A.33

dlpdfdoccompress (DLPDFDOC *Doc) Return Value: void

Description 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. Con- tent placed prior to this call will not be compressed.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value 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 Used with the COS layer of the Adobe PDF Library to accomplish functions outside DLI.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value CosDoc: Reflects the constructed document

Exceptions

Header dli.h

Related Methods dlpdfdocpddoc, dlpdfdoccomplete

Availability 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 Creates a new, empty document.

Parameters DLPDFINSTANCE *instance: The DLPDFINSTANCE to use for the document

Return Value DLPDFDOC *

Exceptions genErrBadParam

Header dli.h

Related Methods dlpdfdocdestroy, dlpdfdocsetpsname, dlpdfdocwritePS (See Technical Notes below)

Availability 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 This call creates a digital signature object for the DLI document being created.

Parameters • 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 dli.h

Related Methods dlpdfdocsetsignatureappearance dlpdfpageplacesignature

Availability 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 Destroys the specified document, releasing all resources used in the document.

Parameters DLPDFDOC *Doc: represents the document structure and the current status of the document at all times.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdoccreate, dlpdfinstancesetgrcachelimits

Availability 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 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).

Parameters DLPDFDOC *Doc: The document for which to embed all fonts

Return Value void

Exceptions

Header dli.h

Related Methods dlpdffontcreateembedded, dlpdffontcreatewithmetricsembedded

Availability 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 Applies the Adobe PDF Library standard security mechanism to the document, using the permissions specified in the Permis- sions parameter as outlined in the Acrobat Core API Reference Manual in the PDPerms definition on page 2101.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocsetencryptkeylen

Availability 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 Instructs DLI to linearize any PDF output created from this document, regardless of the setting of the linearization flag used at document output time.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value 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 Instructs the application to create thumbnail page images. These will be added to all pages when the file is written to PDF.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value 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 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.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocnamefind

Availability All DLI-supported platforms. DLI Reference Guide A.43

dlpdfdocnamefind (DLPDFDOC *Doc, char *TreeName, char *Name,) Return Value: CosObj

Description Locates a name in the tree, and returns its associated COS structure.

Return Value CosObj

Exceptions

Header dli.h

Related Methods dlpdfdocnameadd

Availability All DLI-supported platforms. A.44 DLI Implementation and Reference Guide

dlpdfdocoutline (DLPDFDOC *Doc) Return Value: DLPDFOUTLINE*

Description 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.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value 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 Creates an outline structure within the document specified.

Parameters • 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.

Return Value DLPDFOUTLINE*: Internal structure that reflects the outline entry

Exceptions

Header dli.h

Related Methods dlpdfdocoutlineaddfromname, dlpdfdocoutlinecosobj, dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Availability 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 Adds a new outline entry using the named destination, rather than a specified document.

Parameters • 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

Return Value DLPDFOUTLINE*

Exceptions dlpdfdocoutlineadd, dlpdfdocoutlinecosobj, dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Header dli.h

Related Methods dlpdfdocoutlineadd

Availability All DLI-supported platforms. A.48 DLI Implementation and Reference Guide

dlpdfdocoutlinecosobj (DLPDFOUTLINE *Outline) Return Value: CosObj

Description 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.

Parameters DLPDFOUTLINE *Outline

Return Value CosObj

Exceptions

Header dli.h

Related Methods dlpdfdocoutline

Availability 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 Returns a pointer to the first child outline of the specified outline

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Availability 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 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.

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinefirst, dlpdfdocoutlinenext, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Availability All DLI-supported platforms. DLI Reference Guide A.51

dlpdfdocoutlinenext (DLPDFOUTLINE *Outline) Return Value: DLPDFOUTLINE*

Description Returns a pointer to the outline node that follows the specified node

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Availability 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 Returns a pointer to the parent of the specified node

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineprev

Availability 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 Returns a pointer to the outline node that precedes this node within its container.

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineparent

Availability 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 Used with the PD Layer of the Adobe PDF Library to accomplish functions outside of DLI.

Parameters DLPDFDOC *Doc represents the document structure and the current status of the document at all times.

Return Value PDDoc reflects the constructed document.

Exceptions

Header dli.h

Related Methods dlpdfdoccosdoc

Availability 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 Creates or replaces an entry in the document’s DocInfo directory

Parameters • 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

Return Value 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 Sets the default encoding for fonts used within the document.

Parameters • 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

Return Value void

Exceptions genErrBadParam: Raised if any encoding value other than the values specified above (or a NULL document pointer) is passed to this function.

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.57

dlpdfdocsetencryptkeylen (DLPDFDOC *Doc, unsigned int KeyLenBytes) Return Value: void

Description Enables variable-length encryption keys as supported by the Adobe PDF Library.

Parameters • 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

Return Value void

Exceptions This function itself throws no specific exceptions, but the underlying functions within the Adobe PDF Library may throw exceptions.

Header dli.h

Related Methods dlpdfdocencrypt

Availability 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 Saves the desired location of a PDF file which results from this document.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocsetpsname

Availability All DLI-supported platforms.

Technical Notes

dlpdfdocsetpsname (DLPDFDOC *Doc, char *Name) Return Value: void

Description Saves the desired location of a PostScript file which results from this document.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocsetpdfname

Availability All DLI-supported platforms.

Technical Notes

dlpdfdocsetsignatureappearance (DLPDFDOC *Doc, DLPDFSIGNATURE *Sig, DLPDFFORM *background, DLPDFFORM *unverified, DLPDFFORM *signature, DLPDFFORM *textSigInfo) Return Value: void

Description 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.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdoccreatesignature, dlpdfpageplacesignature

Availability All DLI-supported platforms. DLI Reference Guide A.61

dlpdfdocwritepdf (DLPDFDOC *Doc, char *FileName, int Linearize) Return Value: void

Description Writes the document to PDF.

Parameters • 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.

Return Value void

Exceptions genErrBadParam: Raised if the filename is not specified.

Header dli.h

Related Methods dlpdfdocwritePS

Availability All DLI-supported platforms. A.62 DLI Implementation and Reference Guide

dlpdfdocwritePS (DLPDFDOC *Doc, char *FileName) Return Value: void

Description Writes the document to PostScript.

Return Value void

Exceptions genErrBadParam: Raised if the filename is not specified.

Header dli.h

Related Methods dlpdfdocwritepdf

Availability All DLI-supported platforms. DLI Reference Guide A.63

dlpdffontcreate (DLPDFDOC *Doc, char *fontName, char *fontType) Return Value: DLPDFFONT*

Description 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.

Parameters • 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.

Return Value The DLPDFFONT * which has been created

Exceptions

Header dli.h

Related Methods dlpdfdocembedfonts, dlpdffontcreateembedded, dlpdffontcreatewithmetrics, dlpdffontcreatewithmetricsembedded

Availability 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 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.

Parameters • 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.

Return Value The DLPDFFONT which has been created

Exceptions

Header dli.h

Related Methods dlpdfdocembedfonts, dlpdffontcreate, dlpdffontcreatewithmetrics, dlpdffontcreatewithmetricsembedded

Availability 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 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.

Parameters • 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.

Return Value The DLPDFFONT which has been created

Exceptions

Header dli.h

Related Methods dlpdfdocembedfonts, dlpdffontcreate, dlpdffontcreateembedded, dlpdffontcreatewithmetricsembedded

Availability 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 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.

Parameters • 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.

Return Value The DLPDFFONT which has been created

Exceptions

Header dli.h

Related Methods dlpdfdocembedfonts, dlpdffontcreate, dlpdffontcreateembedded, dlpdffontcreatewithmetrics

Availability 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 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.

Parameters • 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.

Return Value DLPDFFORM*

Exceptions

Header dli.h

Related Methods dlpdfformdestroy

Availability All DLI-supported platforms. DLI Reference Guide A.69

dlpdfformdestroy (DLPDFFORM *Form) Return Value: void

Description Destroys the named form, releasing its resources and invalidat- ing the form handle.

Parameters DLPDFFORM *Form

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfformcreate

Availability 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 Creates an image from a bitmap. The map is considered to be scanned left to right and top to bottom. For more discussion on specific bitmap formats supported by this method, please see the discussion under “Identifying a Supported RAW Bitmap” on page 11.6.

Parameters • 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*BitsPerChannel)/8)* CompPerPixel. Components per pixel is derived from ColorSpace. • long Width in pixels • Long Depth in pixels • int bpc: Bits per Channel of the incoming bitmap, usually 8, indicating a possible 255 different levels of color for each color component channel represented. See Technical Notes below. • CosObj ColorSpace: this should be the color space name as a COS structure (/DeviceGray, /DeviceRGB or /DeviceCMYK, which have 1, 3, and 4 color components per pixel respectively), a CosNull structure (if this is a 1BPP, one-channel 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.

Return Value DLPDFIMAGE*

Exceptions

Header dli.h

Related Methods dlpdfimagecreatefromfile, dlpdfimagecreatefrompdf, dlpdfimagecreatefromps

Availability All DLI-supported platforms. DLI Reference Guide A.71

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; this does not refer to Windows BMP files. Unprocessed BMP files are not supported by this function. 3 Rows must begin and end on byte boundaries, padded as necessary if the number of data bits per row is not a multiple of 8. 4 The bpc parameter represents Bits per Channel, not bits per color; it defines the number of bits in each color channel of the incoming bitmap. So, for example, an RGB color model typically uses 24 bits per color: 8 bits for each of 3 channels (R, G and B). You would specify 8 for your bpc parameter in this scenario, not 24. 5 Per Adobe specifications (see Section 4.8.2 of the Adobe PDF Reference, "Sample Representation"), the number of bits per channel must be the same across channels, and must be 1, 2, 4 or 8. (16 is also allowed if limited to PDF v1.5 compliance or higher.) A.72 DLI Implementation and Reference Guide

dlpdfimagecreatefromfile (DLPDFDOC *Doc, char *Name) Return Value: DLPDFIMAGE*

Description 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.

Parameters • DLPDFDOC *Doc represents the document structure and the current status of the document at all times. • char *Name: Name string

Return Value DLPDFIMAGE*

Exceptions

Header dli.h

Related Methods dlpdfimagecreatefrombmp, dlpdfimagecreatefrompdf, dlpdfimagecreatefromps

Availability Not available on OS/390 DLI Reference Guide A.73

dlpdfimagecreatefrompdf (DLPDFDOC *Doc, char *ImageName, ASFixed Width, ASFixed Depth, ASFixed XDisp, ASFixed YDisp, long Page) Return Value: DLPDFIMAGE*

Description 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 Acro- bat. The specified page of the PDF document will be used as a graphic image.

Parameters • 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

Return Value DLPDFIMAGE*

Exceptions

Header dli.h

Related Methods dlpdfimagecreatefrombmp, dlpdfimagecreatefromfile, dlpdfimagecreatefromps

Availability 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. A.74 DLI Implementation and Reference Guide

dlpdfimagecreatefromps (DLPDFDOC *Doc, char *ImageName, char *Image, long ImageSize, int InLine) Return Value: DLPDFIMAGE*

Description Creates an image from an EPS graphic. It must contain a “%%BoundingBox” statement.

Parameters • 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.

Return Value DLPDFIMAGE*

Exceptions

Header dli.h

Related Methods dlpdfimagecreatefrombmp, dlpdfimagecreatefromfile, dlpdfimagecreatefrompdf

Availability 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. DLI Reference Guide A.75

dlpdfimagegetsize (DLPDFIMAGE *Image, ASUns32 *xRasters, ASUns32 *yRasters, ASFixed *xPoints, ASFixed *yPoints) Return Value: void

Description This procedure retrieves image size information from a graphic file.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentreferenceimage

Availability 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. A.76 DLI Implementation and Reference Guide

dlpdfinit (PDFLData pdflLibData, ASFileSys defaultFS, void *unused) Return Value: DLPDFINSTANCE *

Description Initializes the Adobe PDF Library and DLI, and should be called prior to creating the first document.

Parameters • 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 dli.h

Related Methods dlpdfmemfilesys, dlpdfterm

Availability 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 initialize 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 DLI Reference Guide A.77

filesystem to dlpdfinit which is capable of reliably handling files of the larger size.

dlpdfinstancesetcancelproc (DLPDFINSTANCE *dliInst, CancelProc cProc, void *cData) Return Value: void

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.79

dlpdfinstancesetgrcachelimits (DLPDFINSTANCE *dliInst, ASUns32 highLimit, ASUns32 deleteLimit) Return Value: void

Description 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.

Parameters • 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 document- destroy-time. Graphics will be removed in LRU order until the total storage is at or below this figure.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocdestroy

Availability 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 A.80 DLI Implementation and Reference Guide

filesystem to dlpdfinit which is capable of reliably handling files of the larger size.

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.82 DLI Implementation and Reference Guide

dlpdfmatrixrotate (ASFixedMatrix *Matrix, ASFixed Angle) Return Value: void

Description Rotates a matrix counterclockwise by the specified angle after accepting a pointer to the matrix.

Parameters • ASFixedMatrix *Matrix: Matrix to be rotated • ASFixed Angle: In degrees, as an ASFixed counterclockwise value

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.83

dlpdfmemfileacquire (ASPathName Name) Return Value: MDFile

Description 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.

Parameters ASPathName Name

Return Value MDFile

Exceptions

Header dli.h

Related Methods dlpdfmemfilerelease

Availability All DLI-supported platforms. A.84 DLI Implementation and Reference Guide

dlpdfmemfiledata (MDFile File) Return Value: unsigned const char *

Description 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.

Parameters MDFile File

Return Value unsigned const char *

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease, dlpdfmemfilesize

Availability All DLI-supported platforms. DLI Reference Guide A.85

dlpdfmemfiledeleteonclose (MDFile File) Return Value: void

Description This method marks a Files In Memory file to be removed from the filesystem once the last open handle for this file has been closed. No file is automatically removed from memory, unless this call has been made on a specific MDFile.

Parameters MDFile File

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease

Availability All DLI-supported platforms. A.86 DLI Implementation and Reference Guide

dlpdfmemfilerelease (MDFile File) Return Value: int

Description Relinquishes one acquisition as made by the dlpdfmemfileacquire call, and returns the number of acquisitions left on the file.

Parameters MDFile

Return Value Int

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire

Availability 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. DLI Reference Guide A.87

dlpdfmemfilesetbuffer (MDFile File, unsigned char * Data, ASSize_t Size) Return Value: ASBool

Description 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.

Parameters • MDFile File: File to be overwritten • unsigned char * Data: Memory to replace the File’s previous content. • ASSize_t Size

Return Value ASBool: TRUE is returned if the file’s data buffer could be set to this memory, FALSE if it could not.

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease, dlpdfmemfilesetdata

Availability 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

dlpdfmemfilesetdata (MDFile File, unsigned const char * Data, ASSize_t Size) Return Value: ASBool

Description Sets the file passed in to contain the data passed to the function. This completely overwrites the file’s previous contents.

Parameters • MDFile File: File to be overwritten • unsigned const char * Data: Data that replaces File content. • ASSize_t Size

Return Value ASBool: TRUE is returned if the file could be set to this data, FALSE if it could not.

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease, dlpdfmemfilesetbuffer

Availability 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.89

dlpdfmemfilesize (MDFile File) Return Value: ASSize_t

Description 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.

Parameters MDFile File

Return Value ASSize_t

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease

Availability All DLI-supported platforms. A.90 DLI Implementation and Reference Guide

dlpdfmemfilesys (void) Return Value: ASFileSys

Description Returns the ASFileSys structure which represents the Data- logics Files In Memory file system. This file system will only be used if PDF output is requested.

Parameters None

Return Value ASFileSys

Exceptions

Header dli.h

Related Methods dlpdfinit, dlpdfmemfileacquire, dlpdfmemfilerelease

Availability 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. DLI Reference Guide A.91

dlpdfmemfilesysgetmemusage (void) Return Value: ASSize_t

Description This returns an ASSize_t with the current usage, in bytes, of memory for Files In Memory file contents by DLI.

Parameters None

Return Value ASSize_t

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease dlpdfmemfilesyssetmemlimit

Availability All DLI-supported platforms. A.92 DLI Implementation and Reference Guide

dlpdfmemfilesyssetmemlimit (ASSize_t memLimit) Return Value: void

Description This establishes an upper bound, in bytes, of the memory usage allowed for Files In Memory file contents by DLI.

Parameters ASSize_t memLimit

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease dlpdfmemfilesysgetmemusage

Availability All DLI-supported platforms. DLI Reference Guide A.93

dlpdfmemfiletransientprefix (void) Return Value: const char *

Description Returns a NULL-terminated string representing the prefix for the transient files

Parameters None

Return Value const char *

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease

Availability 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. A.94 DLI Implementation and Reference Guide

dlpdfpageaddlinkannotation (DLPDFPAGE *Page, ASFixedRect *Location, ASFixed *Border, ASFixed *Color, long PageNumber, Char *Fit, ASFixedRect *Where, ASFixed *Zoom) Return Value: CosObj

Description Creates a link annotation in the specified page.

Parameters • 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.

Return Value CosObj: The actual link structure which may be modified by the user to access capabilities beyond this interface.

Exceptions

Header dli.h

Related Methods dlpdfpageaddlinkannotationfromname, dlpdfpageaddtextannotation, dlpdfpageaddwebannotation

Availability All DLI-supported platforms. DLI Reference Guide A.95

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. A.96 DLI Implementation and Reference Guide

dlpdfpageaddlinkannotationfromname (DLPDFPAGE *Page, ASFixedRect *Location, ASFixed *Border, ASFixed *Color, char *Target) Return Value: CosObj

Description Adds a new link to a page using the named destination rather than a specified destination.

Parameters • DLPDFPAGE *Page • ASFixedRect *Location: Location of rectangle • ASFixed *Border • ASFixed *Color: Link color • char *Target

Return Value CosObj

Exceptions

Header dli.h

Related Methods dlpdfpageaddlinkannotation, dlpdfpageaddtextannotation, dlpdfpageaddwebannotation

Availability All DLI-supported platforms. DLI Reference Guide A.97

dlpdfpageaddtextannotation (DLPDFPAGE *Page, ASFixedRect *Location, ASFixed *Border, ASFixed *Color, char *Title, char *Contents, int Open) Return Value: CosObj

Description Creates a text annotation within the specified page.

Return Value CosObj

Exceptions

Header dli.h

Related Methods dlpdfpageaddlinkannotation, dlpdfpageaddlinkannotationfromname, dlpdfpageaddwebannotation

Availability 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. A.98 DLI Implementation and Reference Guide

dlpdfpageaddwebannotation (DLPDFPAGE *Page, ASFixedRect *Location, ASFixed *Border, ASFixed *Color, char *URIDestination) Return value: CosObj

Description 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Location • ASFixed *Border • ASFixed *Color • char *URIDestination: URI destination in UTF-8 text format.

Return Value CosObj

Exceptions

Header dli.h

Related Methods dlpdfpageaddlinkannotation, dlpdfpageaddlinkannotationfromname, dlpdfpageaddtextannotation

Availability 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. DLI Reference Guide A.99

dlpdfpagecosobj (DLPDFPAGE *Page) Return Value: CosObj

Description 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.

Parameters DLPDFPAGE *Page

Return Value CosObj

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.100 DLI Implementation and Reference Guide

dlpdfpagecreate (DLPDFDOC *Doc, ASFixed Width, ASFixed Height) Return Value: DLPDFPAGE*

Description Creates a new page in the current document, positioned to follow all other pages in the current document.

Parameters • 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.

Return Value DLPDFPAGE*

Exceptions genErrBadParam: Raised if the specified document does not exist.

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.101

dlpdfpagefindfromnumber (DLPDFDOC *Doc, long PageNumber) Return Value: DLPDFPAGE*

Description 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.

Parameters • DLPDFDOC *Doc represents the document structure and the current status of the document at all times. • long PageNumber

Return Value DLPDFPAGE*

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.102 DLI Implementation and Reference Guide

dlpdfpagenumber (DLPDFPAGE *Page) Return Value: long

Description 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.

Parameters DLPDFPAGE *Page

Return Value long

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.103

dlpdfpagerotate (DLPDFPAGE *Page, PDRotate Angle) Return Value: void

Description 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.

Parameters • DLPDFPAGE *Page • PDRotate Angle

Return Value 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. A.104 DLI Implementation and Reference Guide

dlpdfpagesetart (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value: void

Description 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetbleed, dlpdfpagesetcrop, dlpdfpagesetmediabox, dlpdfpagesettrim

Availability All DLI-supported platforms. DLI Reference Guide A.105

dlpdfpagesetbleed (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value: void

Description 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetart, dlpdfpagesetcrop, dlpdfpagesetmediabox, dlpdfpagesettrim

Availability All DLI-supported platforms. A.106 DLI Implementation and Reference Guide

dlpdfpagesetcrop (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value: void

Description 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetart, dlpdfpagesetbleed, dlpdfpagesetmediabox, dlpdfpagesettrim

Availability All DLI-supported platforms. DLI Reference Guide A.107

dlpdfpagesetid (DLPDFPAGE *Page, char *Id) Return Value: void

Description Adds an ID Entry to the page dictionary. This is generally a page’s FOLIO.

Parameters • DLPDFPAGE *Page • char *Id: ID entry.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.108 DLI Implementation and Reference Guide

dlpdfpagesetmediabox (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value: void

Description 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetart, dlpdfpagesetbleed, dlpdfpagesetcrop, dlpdfpagesettrim

Availability All DLI-supported platforms. DLI Reference Guide A.109

dlpdfpagesettrim (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value: void

Description 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetart, dlpdfpagesetbleed, dlpdfpagesetcrop, dlpdfpagesetmediabox

Availability All DLI-supported platforms. A.110 DLI Implementation and Reference Guide

dlpdfpathaddarc (DLPDFPATH *Path, ASFixed X, ASFixed Y, ASFixed Rad, ASFixed T1, ASFixed T2) Return Value: void

Description Appends an arc segment to the current path. The current position will be set to the ending point.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarcn, dlpdfpatthaddarcto, dlpdfpathaddelliparc, dlpdfpathadddelliparcn, dlpdfpathaddelliparcto

Availability 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. DLI Reference Guide A.111

dlpdfpathaddarcn (DLPDFPATH *Path, ASFixed X, ASFixed Y, ASFixed Rad, ASFixed T1, ASFixed T2) Return Value: void

Description Identical to dlpdfpathaddarc, except the arc will be drawn clockwise.

Parameters • DLPDFPATH *Path is the pointer to the path. • ASFixed X • ASFixed Y • ASFixed Rad • ASFixed T1 • ASFixed T2

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarc, dlpdfpatthaddarcto, dlpdfpathaddelliparc, dlpdfpathadddelliparcn, dlpdfpathaddelliparcto

Availability All DLI-supported platforms. A.112 DLI Implementation and Reference Guide

dlpdfpathaddarcto (DLPDFPATH *Path, ASFixed X1, ASFixed Y1, ASFixed X2, ASFixed Y2, ASFixed Rad) Return Value: void

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarcn, dlpdfpatthaddarc, dlpdfpathaddelliparc, dlpdfpathadddelliparcn, dlpdfpathaddelliparcto

Availability All DLI-supported platforms. DLI Reference Guide A.113

X1/Y1 Xint1/ Xint2/ Yint1 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. A.114 DLI Implementation and Reference Guide

dlpdfpathaddclose (DLPDFPATH *Path) Return Value: void

Description Appends a “close path” operator to the path. The current position after the path is closed is (1,-1).

Parameters DLPDFPATH *Path is the pointer to the path

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.115

dlpdfpathaddcurve (DLPDFPATH *Path, ASFixed Ctrl1X, ASFixed Ctrl1Y, ASFixed Ctrl2X, ASFixed Ctrl2Y, ASFixed EndX, ASFixed EndY) Return Value: void

Description Adds a spline or cubic Bézier curve to the path.

Parameters • 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.

Return Value void

Exceptions genErrBadParam is returned if no starting point is specified.

Header dli.h

Related Methods dlpdfpathaddcurver, dlpdfpathaddcurvev, dlpdfpathaddcurvey

Availability All DLI-supported platforms. A.116 DLI Implementation and Reference Guide

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). DLI Reference Guide A.117

dlpdfpathaddcurver (DLPDFPATH *Path, ASFixed Ctrl1X, ASFixed Ctrl1Y, ASFixed Ctrl2X, ASFixed Ctrl2Y, ASFixed EndX, ASFixed EndY) Return Value: void

Description Identical to dlpdfpathaddcurve, except that the positions are expressed as relative distances from the current point, not absolute distances from the origin.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddcurve, dlpdfpathaddcurvev, dlpdfpathaddcurvey

Availability All DLI-supported platforms. A.118 DLI Implementation and Reference Guide

dlpdfpathaddcurvev (DLPDFPATH *Path, ASFixed Ctrl2X, ASFixed Ctrl2Y, ASFixed EndX, ASFixed EndY) Return Value: void

Description Identical to dlpdfpathaddcurve, except that both the start and first control point are assumed to be the current position.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddcurve, dlpdfpathaddcurver, dlpdfpathaddcurvey

Availability All DLI-supported platforms.

EndX/ EndY

StartX/ StartY Ctrl1X/ Ctrl2X/ Ctrl1Y 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. DLI Reference Guide A.119

dlpdfpathaddcurvey (DLPDFPATH *Path, ASFixed Ctrl1X, ASFixed Ctrl1Y, ASFixed EndX, ASFixed EndY) Return Value: void

Description Identical to dlpdfpathaddcurve, except that the second control point is assumed to be the ending position.

Parameters • DLPDFPATH *Path is the pointer to the path • ASFixed Ctrl1X • ASFixed Ctrl1Y • ASFixed EndX • ASFixed EndY

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddcurve, dlpdfpathaddcurver, dlpdfpathaddcurvev

Availability All DLI-supported platforms.

Ctrl1X/ Ctrl1Y

EndX/ EndY Ctrl2X/ Ctrl2Y StartX/ StartY

Technical Notes

1 This method is identical to dlpdfpathaddcurve, except that the second control point is assumed to be the ending position. A.120 DLI Implementation and Reference Guide

dlpdfpathaddelliparc (DLPDFPATH *Path, ASFixed CentX, ASFixed CentY, ASFixed HRad, ASFixed VRad, ASFixed T1, ASFixed T2) Return Value: void

Description Appends an arc segment to the current path. This method accepts seven parameters.

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.

Return Value void

Exceptions

Header dli.h

Related Methods 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. DLI Reference Guide A.121

dlpdfpathaddelliparcn (DLPDFPATH *Path, ASFixed CentX, ASFixed CentY, ASFixed HRad, ASFixed VRad, ASFixed T1, ASFixed T2) Return Value: void

Description This method is identical to dlpdfpathaddelliparc, except that the arc will be drawn clockwise.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarc, dlpdfpathaddarcn, dlpdfpatthaddarcto, dlpdfpathaddelliparc, dlpdfpathaddelliparcto

Availability All DLI-supported platforms. A.122 DLI Implementation and Reference Guide

dlpdfpathaddelliparcto (DLPDFPATH *Path, ASFixed X1, ASFixed Y1, ASFixed X2, ASFixed Y2, ASFixed HRad, ASFixed VRad) Return Value: void

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarc, dlpdfpathaddarcn, dlpdfpathaddarcto, dlpdfpathaddelliparc

Availability All DLI-supported platforms. DLI Reference Guide A.123

dlpdfpathaddline (DLPDFPATH *Path, ASFixed X, ASFixed Y) Return Value: void

Description 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.

Parameters • DLPDFPATH *Path is the pointer to the path. • ASFixed X is the absolute X-axis position. • ASFixed Y is the absolute Y-axis position.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddliner

Availability All DLI-supported platforms. A.124 DLI Implementation and Reference Guide

dlpdfpathaddliner (DLPDFPATH *Path, ASFixed X, ASFixed Y) Return Value: void

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddline

Availability All DLI-supported platforms. DLI Reference Guide A.125

dlpdfpathaddmove (DLPDFPATH *Path, ASFixed X, ASFixed Y) Return Value: void

Description 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.

Parameters • DLPDFPATH *Path is the pointer to the path. • ASFixed X is the specified X-axis position. • ASFixed Y is the specified Y-axis position.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddmover

Availability All DLI-supported platforms. A.126 DLI Implementation and Reference Guide

dlpdfpathaddmover (DLPDFPATH *Path, ASFixed X, ASFixed Y) Return Value: void

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddmove

Availability All DLI-supported platforms. DLI Reference Guide A.127

dlpdfpathaddrect (DLPDFPATH *Path, ASFixed X, ASFixed Y, ASFixed Width, ASFixed Depth) Return Value: void

Description Draws a rectangle.

Parameters • 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

Return Value 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. A.128 DLI Implementation and Reference Guide

dlpdfpatharray (DLPDFPATH *Path) Return Value: ASFixed*

Description This method will return a pointer to the first member of the array of ASFixed integers, which is the path.

Parameters DLPDFPATH *Path is the pointer to the path.

Return Value ASFixed*

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.129

dlpdfpathclear (DLPDFPATH *Path) Return Value: void

Description 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.

Parameters DLPDFPATH *Path is the pointer to the path.

Return Value void

Exceptions genErrBadParam is raised if the method is called with a NULL pointer.

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.130 DLI Implementation and Reference Guide

dlpdfpathcreate (void) Return Value: DLPDFPATH*

Description Creates a new, empty DLPDFPATH structure.

Parameters None

Return Value DLPDFPATH*

Exceptions genErrNoMemory

Header dli.h

Related Methods dlpdfpathdestroy

Availability All DLI-supported platforms. DLI Reference Guide A.131

dlpdfpathcurrentx (DLPDFPATH *Path) Return Value: ASFixed

Description This method will return the current X position as an ASFixed value.

Parameters DLPDFPATH *Path is the pointer to the path

Return Value ASFixed

Exceptions

Header dli.h

Related Methods dlpdfpathcurrenty

Availability All DLI-supported platforms. A.132 DLI Implementation and Reference Guide

dlpdfpathcurrenty (DLPDFPATH *Path) Return Value: ASFixed

Description This method will return the current Y position as an ASFixed value.

Parameters DLPDFPATH *Path is the pointer to the path.

Return Value ASFixed

Exceptions

Header dli.h

Related Methods dlpdfpathcurrentx

Availability All DLI-supported platforms. DLI Reference Guide A.133

dlpdfpathdestroy (DLPDFPATH *Path) Return Value: void

Description Destroys a DLPDFPATH structure and frees its resources.

Parameters DLPDFPATH *Path: The pointer to the path

Return Value void

Exceptions genErrBadParam: Raised if the pointer is not valid

Header dli.h

Related Methods dlpdfpathcreate

Availability All DLI-supported platforms. A.134 DLI Implementation and Reference Guide

dlpdfpathsetmatrix (DLPDFPATH *Path, ASFixedMatrix *Matrix) Return Value: void

Description 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.

Parameters • DLPDFPATH *Path is the pointer to the path • ASFixedMatrix *Matrix

Return Value void

Exceptions genErrBadParam exception is raised if the pointer to the path or the matrix is NULL

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.135

dlpdfpathsize (DLPDFPATH *Path) Return Value: ASInt32

Description This method will return the current size of the path array as an integer.

Parameters DLPDFPATH *Path is the pointer to the path.

Return Value ASInt32

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.136 DLI Implementation and Reference Guide

dlpdfpatterncreate (DLPDFDOC *Doc, DLPDFCONTENT *Content, ASFixedRect *BBox, ASFixedMatrix *Matrix, int Colored, int TileType, ASFixed XStep, ASFixed YStep) Return Value: DLPDFPATTERN*

Description 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.

Parameters • 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

Return Value DLPDFPATTERN*

Exceptions

Header dli.h

Related Methods dlpdfcontentusefillpattern, dlpdfcontentusestrokepattern

Availability All DLI-supported platforms. DLI Reference Guide A.137

dlpdfpatternrotate (ASFixedMatrix *Matrix, ASFixed Angle) Return Value: void

Description 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.

Parameters • ASFixedMatrix *Matrix • ASFixed Angle

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.138 DLI Implementation and Reference Guide

dlpdfpageplacesignature (DLPDFPAGE *Page, DLPDFSIGNATURE *Sig, ASFixedRect *imageBBox) Return Value: void

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdoccreatesignature, dlpdfdocsetsignatureappearance dlpdfdocwritepdf

Availability All DLI-supported platforms. DLI Reference Guide A.139

dlpdfseterrorfile (FILE *errorFilePtr) Return Value: void

Description Sets file to which error messages will be logged.

Parameters File *errorFilePtr: By default error messages are logged to stderr

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfsetwarningfile

Availability All DLI-supported platforms. A.140 DLI Implementation and Reference Guide

dlpdfsetwarningfile (FILE * warningFilePtr) Return Value: void

Description Sets file to which warning messages will be logged.

Parameters File *warningFilePtr: By default warning messages are not logged.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfseterrorfile

Availability All DLI-supported platforms. DLI Reference Guide A.141 dlpdfsignaturesetdatacallback (DLPDFSIGNATURE *signature, void (*dataCallback)(char *, int)) Return Value: void

Description This is an optional call for clients using PKCS #7 certificates. A callback function is supplied for the signature.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfsignaturesetpkcs7cert dlpdfdocwritepdf

Availability 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. A.142 DLI Implementation and Reference Guide

dlpdfsignaturesetpkcs7cert (DLPDFSIGNATURE *signature, int maxLen, int (*genPKCS7Cert)(char *)) Return Value: void

Description This function sets the certificate generation callback for DLPDF- SIGNATUREs of type dlpdfsigacropkcs7 and dlpdfsigverisign.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocwritepdf dlpdfsignaturesetdatacallback dlpdfsignaturesetx509cert

Availability 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.

dlpdfsignaturesetx509cert (DLPDFSIGNATURE *signature, char *certificate, int certLen, void (*encryptSHA1Hash)(char *)) Return Value: void

Description This call associates an x.509 v3 certificate with a DLPDFSIGNA- TURE object created as a dlpdfsigacrox509 certificate digital signature.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocwritepdf dlpdfsignaturesetpkcs7cert

Availability 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. A.144 DLI Implementation and Reference Guide

dlpdfterm (DLPDFINSTANCE * instance) Return Value: void

Description Terminates the Adobe PDF Library and DLI. All active documents should be closed prior to this call.

Parameters DLPDFINSTANCE *instance

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfinit, dlpdfttload

Availability 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. DLI Reference Guide A.145

dlpdftext (void *Text, ASUns32 Length, ASAtom Encoding) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given Text and Length, in the given Encoding.

Parameters • 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

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftextfromutf8, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le

Availability 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. A.146 DLI Implementation and Reference Guide

dlpdftextadvance (DLPDFTEXT *Text, DLPDFFONT *Font, PDEGraphicState *GState, PDETextState *TState, ASFixed PointSize, ASFixed SetWidth, dlpdftext_X XMeaning, ASFixed Angle, ASFixedPoint *Advance) Return Value: void

Description This method supplies the x and y advance for a string in a DLP- DFTEXT area.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.147

dlpdftextdestroy (DLPDFTEXT *Text) Return Value: void

Description This method destroys the indicated DLPDFTEXT instance.

Parameters DLPDFTEXT *Text: the text structure to be acted upon

Return Value void

Exceptions

Header dli.h

Related Methods dlpdftext

Availability All DLI-supported platforms. A.148 DLI Implementation and Reference Guide

dlpdftextfromutf16be (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF16 big-endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLPDFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le, dlpdftextfromutf8

Availability 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

dlpdftextfromutf16he (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF16 host- endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLPDFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf16le (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF16 little- endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLPDFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf32be (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF32 big-endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLPDFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32he, dlpdftextfromutf32le, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf32he (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF32 host- endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLPDFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32le, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf32le (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF32 little- endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLPDFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf8 (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF8 Unicode Text string.

Parameters void *Text: the text to be passed to the DLPDFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le

Availability All DLI-supported platforms.

Technical Notes

dlpdftextlength (DLPDFTEXT *Text) Return Value: ASUns32

Description 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.

Parameters DLPDFTEXT *Text: the text structure to be acted upon

Return Value ASUns32

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextstring

Availability All DLI-supported platforms. A.156 DLI Implementation and Reference Guide

dlpdftextshowencodingnames (char *FileName) Return Value: void

Description 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.

Parameters char *FileName: Name for the output file to be created

Return Value void

Exceptions

Header dli.h

Related Methods dlpdftext

Availability All DLI-supported platforms. DLI Reference Guide A.157

dlpdftextstring (DLPDFTEXT *Text) Return Value: char *

Description This method returns the byte buffer for the stored string.

Parameters DLPDFTEXT *Text: the text structure to be acted upon

Return Value char *

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextlength

Availability All DLI-supported platforms. A.158 DLI Implementation and Reference Guide

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 This method pastes the DLPDFTEXT string into a DLPDFCON- TENT area.

Parameters • 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

Parameters (continued) • 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

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.159

dlpdfttload (DLPDFINSTANCE *Instance, ASFile TTFont, ASAtom *Names, int NameLen) Return Value: int

Description This method loads the given font from an ASFile TrueType or OpenType font file, or the fonts from a TrueType/OpenType Col- lection 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.

Parameters • 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

Return Value 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. A.160 DLI Implementation and Reference Guide

GetGraphicFromList (DLPDFDOC *Doc, char *Name) Return Value: DLPDFIMAGE*

Description Obtains a DLPDFIMAGE* by specifying the target document and the key for the graphic file.

Parameters • DLPDFINSTANCE *Instance: Represents the document structure and the current status of the document at all times. • char *Name: Name string

Return Value DLPDFIMAGE*: NULL is returned if the graphic is not found.

Exceptions

Header dli.h

Related Methods LoadGraphicList

Availability Available on OS/390 only DLI Reference Guide A.161

LoadGraphicList (char *ListFileName) Return Value: void

Description 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.

Parameters char *ListFileName: File name

Return Value void

Exceptions

Header dli.h

Related Methods GetGraphicFromList

Availability Available on OS/390 only A.162 DLI Implementation and Reference Guide Index

A Text Overview 13.2 A key Title 13.4 Use in Links 13.8 Annotations (Sample DLI Application) 17.12 AcroForm (Sample DLI Application) 17.15 Annotations and Links action (parameter) Borders Use in Annotations and Links 13.2 Color 13.3 Action Dictionary Definition 13.3 Use in Links Calls 13.4, 13.5, 13.6, 13.7, 13.8 Creating Replacement 13.8 Colors Modifying 13.8 Links 13.3 Actions Text Annotations (when closed) 13.3 in Annotations and Links 13.2 ArcTo (PostScript operator) 8.6, A.4 Adobe ASCII Acrobat 1.6, 1.7, 2.2, 2.5, 14.1, 17.7, A.98 Use in Displaying Images 11.10 Distiller 1.9, 2.5, 17.6 ASCII85 Normalizer Server 11.2, 17.6 Use in Displaying Images 11.6 Reader 1.6, 1.7, 1.9, 2.2, 2.5, 4.8, 13.4, 14.1, ASFile 17.13 17.7, A.98 ASFILE_CREATE Flag ADOBECMP Use in Interception of File I/O 2.15 OS/390 Location Search 4.11 ASFILE_READ Flag AdobeFnt.lst 2.2, 2.3 Use in Interception of File I/O 2.15 AdobeFnt07.lst 2.3 ASFileSys AdobeFnt08.lst 2.3 Specifying an Alternate File System via AdobeFnt09.lst 2.3 dlpdfinit 2.8 Efficient use of 2.3 Use in Image Search using Files in Memory 1.16, Naming variations 2.3 2.9 Reviewing contents of 2.3 Use in Initializing and Terminating via DLI 2.8, Search path definition via PDFLDataRec 2.2 2.9 Use in Default Search Path Suppression 1.16, Use in Specifying an Alternate File System 2.8 1.17 ASFileSysClose Use with kPDFLInitIgnoreDefaultDirectories Use in Interception of File I/O 2.15 flag 2.3 ASFileSysOpenFile ADOBERES Use in Interception of File I/O 2.15 OS/390 Location Search 4.11 ASFixed allocProc Use in Basic Color Spaces Use in Setting Memory Allocation Routines 2.4 Device Gray 12.6 Annotation Dictionary Use in Color Channels Modifying 13.8 Definitions 12.5 Annotations Inversion Correction 12.5 action (parameter) 13.2 Precision Correction 12.5 Border Specification 13.4 Use in Color Description 12.2 Color Specification 13.4 ASFixedMatrix Components 13.2 Use in Line Drawing 10.12 Content 13.4 ASFixedRect hot spot (parameter) 13.2 Use in Displaying Images 11.9 Introduction 13.1 ASFixedRectangle Link Use in Annotations and Links 13.4, 13.5 Overview 13.2 hot spot Definition 13.2 Modifying for Other Actions 13.2 ASGetErrorString Open/Close Flag 13.4 Use in Error Handling 16.2, 16.4 Opening the Document with Annotations ASGetExceptionErrorCode Showing 14.4 Use in Error Handling 16.2 I.ii DLI Implementation and Reference Guide

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

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

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

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

Use in Matching System Fonts 4.7 Use in Initializing and Terminating via DLI 2.8, dlpdffontcreatewithmetricsembedded A.63, A.64, 2.10 A.65, A.66 Use in Terminating Library 2.10 Use in Font Creation 4.5, 4.8 dlpdfinstancesetcancelproc A.78 DLPDFFORM 9.2 dlpdfinstancesetgrcachelimits A.79 Use in Digital Signatures 15.2, 15.4 dlpdfinstancesetprogressmonitor A.81 dlpdfformcreate A.68 dlpdfmatrixrotate A.82 Use in Forms 9.2 Use in Line Drawing 10.13 dlpdfformdestroy A.69 dlpdfmemfileacquire A.82, A.83 Use in Forms 9.3 Use in Interception of File I/O 2.15 DLPDFIMAGE Use in Writing PDF Output to Memory 2.13, 2.14 Use in Displaying Images 11.2, 11.5, 11.9, 11.10, dlpdfmemfiledata A.84, A.85 11.11 Use in Writing PDF Output to Memory 2.13, 2.14 dlpdfimagecreatefrombmp A.70 dlpdfmemfiledeleteonclose A.85 Identifying Supported Bitmaps 11.6 Note on usage for file deletion 1.12 Sample code 11.4 Use in Interception of File I/O 2.15 Use as imagemask 11.11 dlpdfmemfilerelease A.86 Use in Image Color Spaces 12.2 Use in Interception of File I/O 2.15 dlpdfimagecreatefromfile A.72 Use in Writing PDF Output to Memory 2.13, 2.14 Sample code 11.9 dlpdfmemfilesetbuffer A.87 Use in Displaying Images 11.9 dlpdfmemfilesetdata A.88 Use in Image Search using Files in Memory 1.17, Differences from dlpdfmemfilesetbuffer A.87 2.10 Use in Image Search using Files in Memory 1.17, dlpdfimagecreatefrompdf A.73 2.9 Sample code 11.8 Use in Writing PDF Output to Memory 2.14 What’s New in DLI v3.0 1.12 dlpdfmemfilesize 2.14, A.89 dlpdfimagecreatefromps A.74 Use in Writing PDF Output to Memory 2.13, 2.14 Sample code 11.7 dlpdfmemfilesys A.90 dlpdfimagegetsize A.75 Use in Files in Memory 2.7 Use in Content Interface Calls 8.16 Use in Image Search using Files in Memory 1.17, dlpdfinit A.76 2.9 Caution on Multiple Initializations of Library 2.8 Use in Initializing and Terminating the Library 2.8 Error Handler not required 3.2, A.76, A.144 Use in Initializing and Terminating via DLI 2.9 Invoking Files in Memory 17.2 Use in Specifying an Alternate File System 2.8 Note on Writing PDF Output to Memory 2.9 dlpdfmemfilesysgetmemusage A.91 Specifying an Alternate File System 2.8 dlpdfmemfilesyssetmemlimit A.92 Updates in DLI v3.0 1.11 dlpdfmemfiletransientprefix A.93 Use in Default Search Path Suppression 1.17 Use in Interception of File I/O 2.15 Use in Files in Memory 2.7 Use in Writing PDF Output to Memory 2.13, 2.14 Use in Initializing and Terminating the DLPDFOUTLINE Library 2.10 Use in Bookmarks 14.2, 14.3, 14.4 Failure to Initialize 2.8 DLPDFPAGE 6.2 Use in Initializing and Terminating via DLI 2.8, dlpdfpage objects 1.2 2.9, 2.10 dlpdfpageaddlinkannotation A.94 Use in Multi-Thread Initializations 2.11 Use in Annotations and Links 13.5 Use in Specifying an Alternate File System 2.8 dlpdfpageaddlinkannotationfromname A.96 Use in Terminating Library 2.10 Use in Annotations and Links 13.6 Using a Graphics Cache 2.9 dlpdfpageaddtextannotation A.97 DLPDFINSTANCE Use in Annotations and Links 13.4 Addition in DLI v3.0 1.11 dlpdfpageaddwebannotation A.98 Unicode font translation via ICU 4.3 Use in Links 13.7 Use by dlpdfttload 1.14 dlpdfpagecosobj A.99 Use in Creation Calls in DLI Use in Page Interface 6.3 Font Searching Sequence 4.6 dlpdfpagecreate A.100 Use in dlpdfdoccreate 1.15, 1.16, 3.2 Use in Page Interface 6.2 Use in Initializing and Terminating the dlpdfpagefindfromnumber A.101 Library 2.10 Use in Page Interface 6.2 Index I.vii

dlpdfpagenumber A.102 dlpdfpathaddrect A.127 Use in Page Interface 6.3 Use in Content Interface Calls 8.14 dlpdfpageplacesignature A.138 Use in Line Drawing 10.10 Use in digital signatures 15.5 dlpdfpathadelliparc A.120 dlpdfpagerotate A.103 dlpdfpatharray A.128 Use in Page Interface 6.3 Use in Content Interface Calls 8.8 dlpdfpagesetart A.104 dlpdfpathclear A.129 dlpdfpagesetbleed A.105 Use in Content Interface Calls 8.7 dlpdfpagesetcrop A.106 Use in Line Drawing 10.6 dlpdfpagesetid A.107 dlpdfpathclosepath A.114 Use in Page Interface 6.3 dlpdfpathcreate A.130 dlpdfpagesetmediabox A.108 Use in Content Interface Calls 8.7 dlpdfpagesettrim A.109 Use in Line Drawing 10.6 DLPDFPATH dlpdfpathcurrentx A.131 Effect of DLPDFPath.scaling on Use in Content Interface Calls 8.8 PDEGraphicState.lineWidth 10.14 dlpdfpathcurrenty A.132 Use in Line Drawing 10.6, 10.7, 10.11, 10.14 Use in Content Interface Calls 8.8 Use in Paths 8.7 dlpdfpathdestroy A.133 dlpdfpathaddarc A.110 Use in Content Interface Calls 8.7 Use in Content Interface Calls 8.10 Use in Line Drawing 10.6 Use in Line Drawing 10.7 dlpdfpathsetmatrix A.134 dlpdfpathaddarcn A.111 Use in Content Interface Calls 8.14 Use in Content Interface Calls 8.10 Use in Line Drawing 10.12 Use in Line Drawing 10.8 dlpdfpathsize A.135 dlpdfpathaddarcto A.112 Use in Content Interface Calls 8.8 Use in Content Interface Calls 8.11 DLPDFPATTERN 8.15 dlpdfpathaddclose Parameters Use in Content Interface Calls 8.14 BBox 8.15 Use in Line Drawing 10.6, 10.11 Colored 8.15 dlpdfpathaddcurve A.115 TileType 8.15 Use in Content Interface Calls 8.13 Xstep 8.15 Use in Line Drawing 10.9 Ystep 8.15 dlpdfpathaddcurver A.117 dlpdfpatterncreate A.27, A.136 Use in Content Interface Calls 8.13 Use in Color Spaces Use in Line Drawing 10.9 Advanced 12.10 dlpdfpathaddcurvev A.118 Patterned 12.10 Use in Content Interface Calls 8.13 Use in Content Interface Calls 8.15 Use in Line Drawing 10.10 dlpdfpatternrotate A.137 dlpdfpathaddcurvey A.119 dlpdfseterrorfile A.139 Use in Content Interface Calls 8.14 dlpdfsetwarningfile A.140 Use in Line Drawing 10.10 DLPDFSIGNATURE dlpdfpathaddelliparc Use in Digital Signatures 15.4 Use in Content Interface Calls 8.11 dlpdfsignaturesetdatacallback A.141 dlpdfpathaddelliparcn A.121 Use in digital signatures 15.5 Use in Content Interface Calls 8.12 dlpdfsignaturesetpkcs7cert A.142 dlpdfpathaddelliparcto A.122 Use in digital signatures 15.4 Use in Content Interface Calls 8.12 dlpdfsignaturesetx509cert A.143 dlpdfpathaddline A.123 Use in digital signatures 15.4 Use in Content Interface Calls 8.8 dlpdfterm A.144 Use in Line Drawing 10.7 Error Handler not required 3.2, A.76, A.144 dlpdfpathaddliner A.124 Use in Initializing and Terminating the Use in Content Interface Calls 8.9 Library 2.10 Use in Line Drawing 10.7 Use in Initializing and Terminating via DLI 2.10 dlpdfpathaddmove A.125 Use in Multi-Thread Initializations 2.11 Use in Content Interface Calls 8.9 Use in Terminating Library 2.10 Use in Line Drawing 10.7 DLPDFTEXT 17.18 dlpdfpathaddmover A.126 Use in Multibyte Text Work 5.6 Use in Content Interface Calls 8.9 dlpdftext A.145 Use in Line Drawing 10.7 Obtaining Encoding names via I.viii DLI Implementation and Reference Guide

dlpdftextshowencodingnames 1.13, Use with Error Handler 3.2 A.156 Document Opening Use in Multibyte Text Work 5.4 with Annotations Showing 14.4 Associated shortcut functions 5.5 Documentation DLPDFTEXT (structure) 1.16, 5.2 Adobe Addition in DLI v3.0 1.11 3D Annotations Tutorial 1.8 Creating 5.4, 5.5 Acrobat and PDF Library API Overview 1.8 Performance Considerations 5.9 Acrobat and PDF Library API Reference 1.8 Shortcut Functions 5.5 Adobe PDF Library Overview 1.8 Unicode font translation via ICU 4.3 Portable Document Format Reference Use by dlpdftextdestroy 1.14 Manual 1.8 Use by dlpdftexttocontent 1.14 Errata file 1.8 Use in dlpdftext (method) A.145 SnippetRunner Cookbook 1.8 Use in dlpdftextadvance A.146 Datalogics Use in dlpdftextdestroy A.147 Adobe PDF Library and DLI Installation Use in dlpdftextlength A.155 Guide 1.7 Use in dlpdftextstring A.157 Adobe PDF Library Developer Overview 1.7 Use in dlpdftexttocontent A.158 DLI Implementation and Reference Guide 1.7 What’s New in DLI v3.0 1.13, 1.14 Java Interface User Guide 1.7 Working with 5.6, 5.7, 5.8 Documents, Beginning and Ending dlpdftextadvance A.146 Calls 3.2, 3.3, 3.4 Use in Multibyte Text Work 5.6 Overview 3.2 dlpdftextdestroy A.147 Use in Multibyte Text Work 5.8 dlpdftextfromutf16be A.148 E Use in Multibyte Text Work 5.5 dlpdftextfromutf16he A.149 E_RETURN(X) Use in Multibyte Text Work 5.5 Use in Error Handling 16.3 dlpdftextfromutf16le A.150 E_RTRN_VOID Use in Multibyte Text Work 5.5 Use in Error Handling 16.3 dlpdftextfromutf32be A.151 eMemFileSys Use in Multibyte Text Work 5.5 Use in Files in Memory in DLI Samples 17.2 dlpdftextfromutf32he A.152 Encoding Use in Multibyte Text Work 5.5 Generation of Grid via FontVerification (Sample dlpdftextfromutf32le A.153 DLI Application) 17.10 Use in Multibyte Text Work 5.5 Encoding Vector 4.8 dlpdftextfromutf8 A.154 Encrypt (Sample DLI Application) 17.7 Use in Multibyte Text Work 5.5 Changing Security Settings 17.7 dlpdftextlength A.155 DocOwner Password 17.7 Use in Multibyte Text Work 5.6 ValidUser Password 17.7 dlpdftextshowencodingnames A.156 Encryption Use in Multibyte Text Work 5.5 Calls 3.4 dlpdftextstring A.157 Setting Encryption Key Length 3.4 Use in Multibyte Text Work 5.6 Use in Documents, Beginning and Ending 3.4 dlpdftexttocontent A.158 EPS (Encapsulated PostScript) Use in Multibyte Text Work 5.7 Image Conversion from 11.2 dlpdfttload A.159 Use in Graphics (Sample DLI Application) 17.5 Clearance of memory files by dlpdfterm 1.15 Error Handling Note on no default font searching 2.2 ASGetErrorString 16.2 Use in Font Searching Sequence 4.6 ASGetExceptionErrorCode 16.2 Use in Multibyte Text Work 5.3 DURING 16.2, 16.3 Document Conventions 1.6 E_RETURN(X) 16.3 Document Handle E_RTRN_VOID 16.3 Use in Links 13.8 END_HANDLER 16.2, 16.3 Document Information Exception Codes from Methods 16.3 Calls 3.3 Exception Names 16.2 Document Interface HANDLER 16.2, 16.3 Index I.ix

Handler Constructs F Multiple 16.3 Risks of Returning from within 16.3 Filename, Setting Output PDF Handler Mechanism 16.2 Calls 3.3 OS/390 Platform Concerns 16.3 Files in Memory Overview 16.2 Activating within MultiDoc sample 2.7, 17.2 Errors Activation 2.7 Communication back to Application 16.2 MEMORY Command Line Argument, Use Link of 17.2 "Browser is Busy" 13.7 Use of dlpdfinit 17.2 OS/390 Use of eMemFileSys in DLI Samples 17.2 Not Using SAS/C Use of FileSystemType in DLI Samples 17.2 ASGetErrorString 16.4 Files, Transient 2.13 DLExceptionCode 16.4 FileSystemType DLExceptionFlag 16.3, 16.4 Use in Files in Memory in DLI Samples 17.2 DLExceptionMessage 16.4 fill (parameter) Using SAS/C 16.3 Use in Displaying Images 11.4 Outer Error Catcher 16.2 Fill Color Examples Use in PDEGraphicState 10.2 Adding Outline Entries 14.3 fillColorSpec with a Named Destination 14.3 Use in Color Description 12.2 Bitmapped Graphic via Use in Line Drawing 10.14 dlpdfimagecreatefrombmp 11.4 Fit Type Collapsing Use in Bookmarks 14.2 CMYK to Gray 12.13 FitDescription RGB to Gray 12.12 Use in Annotations and Links 13.5 Converting FitType CMYK to RGB 12.14 Use in Annotations and Links 13.5 RGB to CMYK 12.13 Use in Links 13.5 Creating Values Calgray Color Space 12.4 Fit 13.5 Gray Color Space FitB 13.5 Assembler 12.3 FitBH 13.5 C coding 12.3 FitBV 13.5 Link Annotation 13.5 FitH 13.5 Link To A Named Destination 13.6 FitR 13.5 Named Destination 13.7 FitV 13.5 Text Annotations 13.4 XYZ 13.5 Drawing a Rectangle and Ellipse in Path Fixed Rectangle Operators 10.11 Use in Bookmarks 14.2 Filling an Area with a Pattern 12.11 Flate Compression Inserting Use in Displaying Images 11.6 EPSF Image with flatness dlpdfimagecreatefromps 11.7 Use in Line Drawing 10.15 PDF Image FOLIO 6.3, A.107 via dlpdfimagecreatefromfile 11.9 Font Dump via dlpdfimagecreatefrompdf 11.8 Via FontVerification (Sample DLI Line Drawing Using Fixed Structure 10.5 Application) 17.10 Modifying a Goto Link into a GotoR Link 13.9 Font Searching Sequence 4.5 Multiple Containers per Page with Rotation 7.6 FontFaux (Sample DLI Application) 17.9 Setting the Page Mode to Display Navigation Fonts Pane 14.4 Accessing 4.11 Transparent Graphics via Imagemasks 11.11 OS/390-specific 4.11 Exception Handlers, Required Use 3.2 Calls 3.3 Exceptions Code Page Support 4.10 Use in Error Handling 16.2 Composite Fonts CIDType0 4.3 CIDType2 4.3 Overview 4.2 I.x DLI Implementation and Reference Guide

Creation Calls in DLI Free Software Foundation 1.4 Calls 4.5, 4.6, 4.7, 4.8 freeProc dlpdffontcreatewithmetrics Use in Setting Memory Allocation Routines 2.4 Width Table 4.8 Font Searching Sequence 4.5 Matching Calls to System Fonts 4.7 G Overview 4.5 Performance Considerations 4.11 gcc Compilation Version 1.3 Repetitive Calling 4.5 genErrBadParm 4.6, 6.2 Default Encoding Selection 3.3 Use in Annotations and Links 13.4 differences between characters and glyphs 4.2 GetGraphicFromList A.160 Embedding Use in Displaying Images 11.10 Document EmbedFonts flag 4.4 GetGraphicFromList, OS/390 Subsetting Limitations 4.4 Use in Displaying Images 11.10 Font Dump via FontVerification (Sample DLI GIF (Graphics Interchange Format) Application) 17.10 Encoding and Compression References 11.3 Font Searching Sequence 4.5 Image Conversion from 11.2 Overview 4.2 Use in Displaying Images 11.9 PDFLDataRec Use in Graphics (Sample DLI Application) 11.2, Use in Setting Resource Directories 2.2 17.5 Predefined Font Encodings 4.9 Glyph IDs 4.3 Encoding Font Types Table 4.9 GoTo Resources, Identifying Non-Standard Locations Use in Annotation Dictionary 13.8 of 2.2 Graphics (Sample DLI Application) 17.5 Search Paths 2.2 Graphics cache Simple Fonts 4.2 What’s New in DLI v3.0 1.13 Standard Encoding Graphics, One-Bit Default Setting 3.3 Use in Displaying Images 11.11 Structure of a DLI Font 4.3 grayScale Terminology usage Use in Color Description 12.2 CIDType2 font 4.3 Use in ICC Based Color Profile 12.8 TrueType font 4.3 Unicode 4.10 Use in Multibyte Text Work 5.3 H WinAnsiEncoding Default Setting 3.3 HelloDLI (Sample DLI Application) 17.3 FontVerification (Sample DLI Application) 17.10 Comparison with helowrld.c 2.16 Encoding Grid 17.10 HeloWrld (Sample Adobe PDF Library Slow Feedback from 17.11 Application) 17.3 Table of Contents 17.10 Comparison with hellodli.c 2.16 Form XObjects HFTGetVersion Use in Displaying Images 11.9 Use in Obtaining Version Number 2.5 Forms 9.2 hot spot (parameter) Calls 9.2, 9.3 Definition of 13.2 dlpdfformcreate Use in Annotations and Links 13.2, 13.5 Use of Bounding Box 9.2 Hyperlinks Content Complexity 9.2 Use in Links 13.7 Destruction 9.2 Overview 9.2 Structure 9.2 I Use in Referencing Predefined Structures 8.16 Forms XObjects ICC (International Color Consortium) 12.8 Association with Content Structures 8.2 ICCBased Use in Content Interface 8.2 Use in Color Spaces free Advanced 12.9 Alternate Routines for 2.4 Use in ICC Based Color Profile 12.8 PDFInit.h Interface to 2.4 ICU (International Components for Unicode) Index I.xi

Obtaining Encoding names via Activation 2.7 dlpdftextshowencodingnames 1.13, Image Search using Files in Memory 2.9 A.156 Output to Memory, Writing PDF 2.13 Unicode font translation via ICU 4.3 Calls 2.14 Use in Multibyte Text Work 5.2 Interception of File I/O 2.15 What’s New 1.11 Transient Files 2.13 Image Import Improvements in DLI v3.0 1.12 Overview 2.2 Imagemask PDFLDataRec Initialization 2.2 ImageMask key 11.11 Memory Allocation Routines, Setting 2.3 Note on Use of Bitmaps 11.5 Resource Allocation Routines, Setting 2.4 Use in Displaying Images 11.11 Resource Directories, Setting 2.2 ImageName Terminating 2.10 Use in Displaying Images 11.3 Thread-Safe Issues Images, Displaying Initialization of non-thread-safe Library EPS Pass-Through Objects 11.6 releases 2.12 Example 11.7 Multi-Thread Initializations 2.11 Graphic Image Forms mutex (Mutual Exclusion algorithm) 2.12 Bitmaps 11.3 Version Number, Obtaining 2.5 Example 11.4 With DLI Graphical Language 11.4 Calls 2.8, 2.9, 2.10 Graphic Image Structures Overview 2.7 Destroying 11.3 Specifying an Alternate File System 2.8 Formats Supported 11.2 Typical Order of Calls 2.11 ImageName Use 11.3 Using a Graphics Cache 2.9 Multiple Document Use 11.2 Intended Audience 1.3 Image Creation Methods Assorted Formats dlpdfimagecreatefromfile 11.9 J Example 11.9 Supported Formats 11.9 JPEG/JPG (Joint Photographic Experts Group) Bitmaps Encoding and Compression References 11.3 Compression and Filtering 11.6 Use in Displaying Images 11.9 dlpdfimagecreatefrombmp 11.5, 11.6 Use in Graphics (Sample DLI Application) 11.2, Identifying Supported Variants 11.6 17.5 Values within Color Models 11.5 EPS dlpdfimagecreatefromps 11.6 K Example 11.7 Form XObject Keys, Public and Private 15.2 dlpdfimageplaceascontent 11.9 kPDEEoFill GetGraphicFromList 11.10 Use in Content Interface Calls 8.5 LoadGraphicList 11.10 Use in Line Drawing 10.2, 10.3, 10.11, 10.14 PDF Use in PDEGraphicState 10.2 dlpdfimagecreatefrompdf 11.8 kPDEFill Example 11.8 Use in Content Interface Calls 8.5 Transparent Graphics Use in Line Drawing 10.2, 10.3, 10.11, 10.14 dlpdfcontentgstate 11.11 Use in PDEGraphicState 10.2 Imagemasks 11.11 kPDEStroke Sample 11.11 Use in Content Interface Calls 8.5 Included EPS Images Not Appearing in PDF Use in Line Drawing 10.2, 10.3, 10.11, 10.14 Pages 11.2, 11.6 Use in PDEGraphicState 10.2 Overview 11.2 kPDEStroke | kPDEEoFill Indexed (atom) Use in Line Drawing 10.11 Use in Color Spaces kPDEStroke | kPDEFill Advanced 12.9 Use in Line Drawing 10.11 Initializing and Terminating the Library kPDFLInitIgnoreDefaultDirectories Comparison of Applications with and without Use in Default Search Path Suppression 1.17, 2.3 DLI 2.16 kPDFLVersion Files In Memory Use in Obtaining Version Number 2.5 I.xii DLI Implementation and Reference Guide

L Overview 13.2 URI 13.7 Lab URL 13.7 Use in Color Spaces Zoom 13.5 Basic 12.7 listLen Use in ICC Based Color Profile 12.8 Use in Setting Resource Directories 2.2 Library Data Structure 2.2 LoadGraphicList A.161 Line Drawing 10.1 Directly-Drawn Methods 10.3 Calls 10.3, 10.4, 10.5 M Common Parameters 10.3 dlpdfcontentpath Major Version Number 2.5 Example 10.5 malloc Graphic State 10.14 Alternate Routines for 2.4 Overview 10.2 PDFInit.h Interface to 2.4 Path Drawing Methods 10.6 Matrix operations Calls 10.6, 10.7, 10.8, 10.9, 10.10, 10.11, Rotations 17.4 10.12 Translation of Paths 17.4 Common Parameters 10.6 MDFile Example 10.11 Use in Writing PDF Output to Memory 2.13, 2.14 Transformation Matrix 10.12 memAvailProc Arguments 10.12 Use in Setting Memory Allocation Routines 2.4 dlpdfmatrixrotate 10.13 memFiles (Sample DLI Application) 17.13 Inversion Matrix 10.12 MEMORY Mirror-image matrix 10.12 Use in Files in Memory Activation 17.2 Rotation Matrix 10.12 Memory Allocation Routines, Setting 2.3 Scale/Rotation Caution 10.13 allocProc 2.4 Scaling 10.13 freeProc 2.4 Shearing 10.13 memAvailProc 2.4 Translations 10.12 reallocProc 2.4 Unity Matrix 10.12 Minor Version Number 2.5 Linearization Miter Calls 3.3 Use in Line Drawing 10.15 Use in Documents, Beginning and Ending 3.3, miterLimit 3.4 Use in Line Drawing 10.15 lineCap Multibyte Text Use in Line Drawing 10.15 Commands 5.3, 5.4, 5.5, 5.6, 5.7, 5.8 lineJoin Creating DLPDFTEXT Areas 5.4 Use in Line Drawing 10.14 Introduction 5.2 lineWidth Loading and Creating Fonts 5.3 Use in Line Drawing 10.14 Performance Considerations 5.9 Link Annotation Working With DLPDFTEXT Areas 5.6 Modifying 13.8 MultiDoc (Sample DLI Application) 17.13 Link Cos Object Required Arguments 17.13 Modifying 13.8 mutex (Mutual Exclusion algorithm) 2.12 Links action (parameter) 13.2 Calls 13.4, 13.5, 13.6, 13.7, 13.8 N Components 13.2 Cross-document 13.6 name Destination Page Number 13.5 Use in Links FitType 13.5 instead of Destination 13.6 hot spot (parameter) name (parameter) Definition of 13.2, 13.5 Use in Links 13.7, 13.8 Introduction 13.1 Name Tree A.42 List of Possible Actions 13.8 Adding Destination 13.7 Modifying 13.8 Use in Annotations and Links 13.6 Index I.xiii

hot spot Definition 13.2 as Referenced instead 3.3, 4.4 Use in Links 13.6 Function Return Value is Undefined if Error Named Destination Occurs 16.3 Use in Annotations and Links 13.6 Graphic Conversions, Some Unavailable on OS/ Names 390 and OS/400 11.3, 11.9 Use in Annotations and Links 13.6 Graphic Key on OS/390 Must be ASCII vs. Destinations 13.6 String 11.10 NestedPDF (Sample DLI Application) 17.14 Images cached by filename 17.6 NotEmbedded (flag) 3.3, 4.4, A.38 Included EPS Images Not Appearing in PDF Notes Pages 11.2, 17.5 "Browser is Busy" Error during Link 13.7 Library is not thread-safe 1.3 Adobe CFF OpenType font files may not properly No default font searching for dlpdfttload 2.2 subset 5.3 Only fonts using standard encodings may be ASN membership may be required for Adobe fauxed 17.10 website access 1.8 Pass accurate length values for PKCS #7 certifi- Base 14 Fonts cate output space reservation 15.5, Creation Allowed by dlpdffontcreate 4.5 A.142 Bitmapped Images under 500 Bytes Always Pattern Interaction with Color when Drawing Merged Inline 11.5 Figures 10.14 BMP images with LZW skip markers may not em- PDColorValue Permits Only 4 Channels 12.9 bed properly 17.6 PDEPathGetData Requirement for Path Data Cache size limit is checked every time a docu- Retrieval 10.5 ment is destroyed 2.9, A.77, A.80 PDEPathGetData Return Value 8.6 CFF-format OpenType font files not fully PDF Library Supplement now combined into Ac- supported 1.14 robat and PDF Library API Colorizing via Stroke and Fill 8.5, 10.2 Reference 1.8 Default-filesystem settings may need updating PDF Reference Manual errata file available for for images in memory 1.17, 2.10 download 1.8 Digital Signature signed hash values must be ex- Popup warning may occur for new PDF in old actly 256 hex digits 15.4 viewers 1.10, 2.6 Disk resources used by default if Output to Mem- RSA encryption algorithm within SignDoc sample ory is not set 2.9 not recommended for Production DLI v2.2 Unicode support now superseded by code 17.16 new Multibyte text methods 5.2 Sample applications are subject to change 17.2 dlpdfcontentarcto Discrepancies with PostScript Slow Feedback from FontVerification (Sample DLI Output 10.4 Application) 17.11 DLPDFINSTANCE required for Unicode font Structure Variations may exist between PDF 1.6 creation 1.11 and earlier 1.3 dlpdfmemfiledeleteonclose required for memory Type is Filled, Not Stroked 12.2 file deletion 1.12 Type0 Fonts must be Subset if Embedded 4.6 dlpdfpathaddarcto Line Drawing Details 10.8 Unicode NULL string terminators not required or dlpdfpathaddclose, Adding Disjoint Path Seg- included in calculations A.29, A.30 ments After 10.11 Upgrade applications to thread-safe capability as dlpdfttload does not re-parse previously-loaded soon as possible 2.12 font file 5.3 WideText sample application uses fonts not dis- Document Sharing of COS Objects and tributed with DLI 17.18 PDEColorSpaces 12.4 Encryption Key Length, Setting in Multiple Documents 3.5 O Error Handling should conform to Adobe guidelines 16.2 Outline Tree File Sizes, Effect on, by Adding New Entry 14.2 Repeated Graphical Object References 11.10 Use in Bookmarks Files in /Codesamples folder not buildable source Building Multiple Trees 14.2 as-is 1.5, 11.11 Output File, Writing Fill Operator Not Valid via dlpdfcontentline 10.3 Calls 3.3, 3.4 Fill Patterns are Never Destroyed 12.11 Document Information 3.3 Font Encoding, Limitations on Predefined 4.7 Encryption 3.4 Font not licensed for embedding will be created Linearization 3.4 I.xiv DLI Implementation and Reference Guide

Security Permissions 3.4 Color Definitions 10.2 Use in Color Description 12.2 Use in Content Interface 8.2 P Use in Displaying Images 11.11 Use in Line Drawing 10.2, 10.11, 10.14 Page dash 10.15 Use in Content Interface 8.2 fillColorSpec 10.14 Page Interface Calls 6.2, 6.3 flatness 10.15 Page Structure 6.2 lineCap 10.15 PageMode lineJoin 10.14 Use in Bookmarks 14.4 lineWidth 10.14 Paint Operator miterLimit 10.15 Use in Content Interface Calls 8.5 effect on lineJoin 10.14 Use in Line Drawing 10.2 strokeColorSpec 10.14 Pass-Through Objects PDEGrayCalFlt Use in Displaying EPS Images 11.6 Use in Color Spaces Passwords Basic 12.7 Setting in Encrypt (Sample DLI Application) 17.7 PDEICCBasedColorData Paths (Sample DLI Application) 17.4 Use in ICC Based Color Profile 12.8 Patterned Colors 12.2 PDEIndexedColorData Patterns, creating background 17.14 Use in Color Spaces PCKS #7-format certificates 17.16 Advanced 12.9 PD_STD_ENCODING (flag) 17.10 PDELabCalFlt PDColorValue Use in Color Spaces Use in Color Spaces Basic 12.7 Advanced 12.9 PDEPath PDDoc 3.2 Use in Line Drawing 10.5 PDDocSetNewSecurityData PDEPathAddSegment Use in Documents, Beginning and Ending 3.5 Cited in PDF Rules for Path Construction 10.5 PDEColorSpace PDEPathGetData A.14 Creating and Destroying 12.3 Use in Content Interface Calls 8.6 Document Sharing 12.4 Use in Line Drawing 8.6, 10.5 Use in Color Description 12.2 PDERGBCalFlt PDEColorSpaceCreate Use in Color Spaces Creating and Destroying 12.4 Basic 12.7 Use in Color Spaces PDESeparationColorData Advanced 12.8, 12.9 Color Spaces Basic 12.7 Advanced 12.8 Use in ICC Based Color Profile 12.8 PDETextState 8.4 PDEColorSpaceCreateFromName Use in Content Interface 8.2 Use in Color Spaces PDF Advanced 12.8, 12.9 Image Conversion from 11.2 Basic 12.7, 12.8 Level Declarations in Output 1.10, 2.5 PDEColorSpaceGetCosObj Declarations via DLI 1.10 Use in Image Color Spaces 12.2 DLI-selected Declarations 2.6 PDEDash Overriding DLI-selected Declarations 2.6 Use in Line Drawing 10.15 Use in Displaying Images 11.8, 11.9, 11.10 PDEDeviceNColorData Use in Graphical Language Forms 11.4 Use in Color Spaces Use in Graphics (Sample DLI Application) 11.2, Advanced 12.9 17.5 PDEFontAttrs 4.4, 4.7, 17.9, 17.10 PDF Library charset field 4.8 Use in Multithreaded Applications 1.9 encoding field 4.7 Version Control 1.9, 2.5 type field 4.7 PDF Page Tree Structures 6.2 Use in Creation Calls in DLI 4.5 PDFInit.h wMode field 4.8 Use in Setting Memory Allocation Routines 2.4 PDEGraphicState 8.4, 8.5 Use in Setting Resource Allocation Routines 2.4 Index I.xv

PDFLDataRec 2.11 Use in Annotation Dictionary 13.8 Use in Default Search Path Suppression 1.17 Rectangles Use in Initializing and Terminating the Library 2.2 Use in Links 13.5 Use in Setting Memory Allocation Routines 2.3 Release Notes 1.9 Use in Terminating Library 2.10 Resource Allocation Routines, Setting 2.4 PDFLInit Resource Directories, Setting Caution on Multiple Initializations of pre-v6.1 Use in Initializing and Terminating the Library 2.2 Library 2.8, A.76 RGB Color Prohibition on calling from DLI v3.0 1.11, A.76 Collapsing to Gray 12.12 Use in Default Search Path Suppression 1.17 Converting to CMYK 12.13 Use in Initializing and Terminating via DLI 2.8 Use in Annotations and Links 13.3 Use in Multi-Thread Initializations 2.11 Use in Color Description 12.2 PDFLTerm Use in ICC Based Color Profile 12.8 Prohibition on calling from DLI v3.0 1.11, A.76 Rotate (flag), in imported image files 1.12 Use in Multi-Thread Initializations 2.11 RSA encryption algorithm 17.16 pdfMajorVer 2.6 pdfMinorVer 2.6 PDFNeeded (flag) S Removal from dlpdfdoccreate 1.15, A.35 PDPerms Sample DLI Applications Use in Documents, Beginning and Ending AcroForm 17.15 Encryption 3.4 Activating Files in Memory 17.2 PDViewDestNull Annotations 17.12 Use in Bookmarks 14.2 Encrypt 17.7 Use in Links FontFaux 17.9 with Zoom 13.5 FontVerification 17.10 Performance Considerations Graphics 17.5 Font Creation Calls in DLI 4.11 HelloDLI 17.3 Plugins memFiles 17.13 Self-Sign 17.16 MultiDoc 17.13 VeriSign Signature 17.16 NestedPDF 17.14 PNG (Portable Network Graphics) Overview 17.2 Encoding and Compression References 11.3 Paths 17.4 Image Conversion from 11.2 psOutput 17.17 Use in Displaying Images 11.9 SignDoc 17.16 Use in Graphics (Sample DLI Application) 11.2, WideText 17.18 17.5 Security Permissions Private keys 15.2 Use in Documents, Beginning and Ending psOutput (Sample DLI Application) 17.17 Encryption 3.4 Public keys 15.2 Use in Encrypt (Sample DLI Application) 17.7 Self-Sign Plugin 17.16 Separation Q Color Spaces Advanced 12.8 QuickDraw Seven-Bit Safe Use in Graphical Language Forms 11.4 Use in Displaying Images 11.6 Signatures as images in Digital Signatures 15.3 R SignDoc (Sample DLI Application) 17.16 Standard Encoding RAW (Unformatted Unannotated Bitmap) Use in Documents, Beginning and Ending 3.3 Use in Graphics (Sample DLI Application) 11.2, StdSecurityDataRec 17.5 Use in Documents, Beginning and Ending 3.5 readme.txt 1.9 sticky note realloc Use in Annotations and Links 13.4 PDFInit.h Interface to 2.4 Streaming PostScript reallocProc Removal from DLI v3.0 1.11 Use in Setting Memory Allocation Routines 2.4 stroke (parameter) Rect (parameter) Use in Displaying Images 11.4 I.xvi DLI Implementation and Reference Guide

Stroke Color 8.5 Type Use in PDEGraphicState 10.2 Filled vs. Stroked 12.2 strokeColorSpec Type (parameter) Use in Color Description 12.2 Use in Annotation Dictionary 13.8 Use in Line Drawing 10.14 Use in Links 13.8 Sub-minor Version Number 2.5 SubType (parameter) Use in Annotation Dictionary 13.8 U Use in Links 13.8 Unicode as CIDType2 Fonts 4.3 T Text Support Font Type Recommendations 4.10 Table of Contents NULL string terminators A.29, A.30 Generation via FontVerification (Sample DLI Unix Compiler Run-Time Libraries 1.4 Application) 17.10 URI Text Container Use in Links 13.7 Creation and Positioning 8.3 URL Text Placement Calls 8.4 Use in Links 13.7 Text Layering 8.2 UseOutlines Text Width 8.4 Use in Bookmarks 14.4 Thread Safety Caution on Multiple Initializations of pre-v6.1 Library 2.8 V Initialization of non-thread-safe Library releases 2.12 VeriSign signature plugin 17.16 Multi-Thread Initializations 2.11 Version Number, Obtaining 2.5 Thumbnails Calls 3.3 Use in Documents, Beginning and Ending 3.3 W TIFF (Tagged Image File Format) Encoding and Compression References 11.3 What’s New in Previous Releases Image Conversion from 11.2 DLI v2.2.12 Use in Displaying Images 11.9 Default Search Path Suppression 1.17 Use in Graphics (Sample DLI Application) 11.2, DLI v2.2.13 17.5 Default Search Path Suppression Expanded to TKAllocatorProcs All Platforms 1.16 Use in Setting Memory Allocation Routines 2.4 Image Search using Files in Memory 1.16 TKResourceProcs DLI v3.0 Use in Setting Resource Allocation Routines 2.4 Addition of DLPDFTEXT Structure 1.11 Transformation Matrix Adobe PDF Library now Thread-Safe 1.9 Arguments 10.12 Deleted Functions Overview 10.12 dlpdfdoccreatewithinstance 1.16 Translations dlpdfdocHexGraphics 1.15 Inversion 10.12 dlpdfdocsetembedappwidth 1.15 Mirror-image 10.12 dlpdfdocseterrorfile 1.16 Rotation 10.12, 10.13 dlpdfdocsetformsascontent 1.15 Scale/Rotation Caution 10.13 dlpdfdocsetwarningfile 1.16 Scaling 10.13 dlpdfdocsevenbitsafe 1.15 Shearing 10.13 dlpdffontverifytext 1.16 Translation 10.12 dlpdfimageplaceascontent 1.15 Transforms dlpdfsetlevel 1.16 Association with Content Elements 8.2 Digital Signature Support 1.10 Tree Name DLI Initialization now Required 1.11 Use in Links 13.7 Enhanced Unicode Support 1.11 TrueType font New Functions Terminology usage 4.3 dlpdfdocasciips 1.13 Index I.xvii

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 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.9 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