DLI Implementation and Reference Guide
Total Page:16
File Type:pdf, Size:1020Kb
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 prod- ucts 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.