DL FormsAPI User Guide - Datalogics1.2 DL FormsAPI User Guide An Introduction to DL FormsAPI...

Datalogics®

User Guide

DL FormsAPI

DatalogicsD L F O R M S A P I

User Guide

This guide is part of the Datalogics DL FormsAPI v1.1 suite; 07/26/06.Copyright 1999-2006 Datalogics Incorporated. All Rights Reserved. Use of Datalogics software is subject to the applicable license agreement.DL FormsAPI 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, PostScript, Acrobat, Distiller, Exchange and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States or other countries.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.All other trademarks and registered trademarks are the property of their respective owners.

For additional information, contact:Datalogics, Incorporated101 North Wacker Drive, Suite 1800Chicago, Illinois 60606-7301

Phone: 312-853-8200Fax: [email protected]

http://www.datalogics.com


Table of Contents

1 Getting Started 1.1

An Introduction to DL FormsAPI 1.2

What You Should Know 1.2

How to Use this Book 1.2

What’s New in This Release 1.4

What’s New in Previous Releases 1.6

2 Installing DL FormsAPI 2.1

DL FormsAPI Installation Procedure 2.2

UNIX Installation 2.3

Windows Installation 2.9

3 Overview of DL FormsAPI 3.1

An Introduction to DL FormsAPI 3.2

Typical Job Workflow 3.3

Font Resources 3.4

Error Handling 3.4

4 User Interface Functions 4.1

Introduction 4.2

Control Interfaces 4.3

File Handling 4.7

File Information 4.9

Data Modification 4.11

Image Handling 4.13

Document Creation 4.15

Printing 4.17

A DL FormsAPI Reference Appendix A.1

C o n t e n t s . i i User Guide

1
GettingStarted
This chapter introduces Datalogics DL FormsAPI.

Experienced users may want to skip directly to the section

“What’s New in This Release” on page 1.4 for

information on the latest enhancements and additions.

1.1

1 . 2 DL FormsAPI User Guide

An Introduction to DL FormsAPI

Datalogics DL FormsAPI is a product created and designed at the request of many Adobe PDF Library

and DLI customers who wanted a simpler means of performing specific tasks on Acrobat Form

documents and Forms Data Format (FDF) files. It provides various services for updating form field values,

"flattening" form fields into document text objects, generating updated or flattened forms, printing them,

adding certain image types, or generating reports of form information.

This utility makes use of the Adobe PDF Library and Datalogics Interface (DLI) to facilitate the rapid

creation of PDF via a true Adobe internal interface for interpreting the input documents.

The Adobe PDF Library and Datalogics Interface are also available separately from Datalogics, on

multiple platforms, to enable you to add true Adobe PDF processing and output capability to your own

applications. Contact your Datalogics representative or visit the Datalogics website at http://

www.datalogics.com for more details.

What You Should Know

This document is intended for programmers and other users who are familiar with PDF documents,

Adobe Acrobat forms, file manipulation and general computer processes, or by application designers who

are constructing an application based on the Adobe PDF Library and DLI package.

How to Use this Book

This book has been created to guide you through the process of installing and operating the DL

FormsAPI utility.

This chapter, Getting Started, outlines the chapters to follow, explains the document conventions used

here, and lists other related documentation which you may find useful for your work. Follow-on chapters



G e t t i n g S t a r t e d 1 . 3

will outline the the steps needed to install DL FormsAPI and perform conversion or updating operations

with it.

The following list provides an outline of the chapters as well as a brief description of their contents. Click

on each Chapter title below to jump to its first page.

Chapter 1: "Getting Started" (This chapter) This introduces the DL FormsAPI utility and describes

the contents of this book.

Chapter 2: "Installing DL FormsAPI" outlines unpacking and installation of the product files.

Chapter 3: "Overview of DL FormsAPI" gives a general explanation of DL FormsAPI and its

components.

Chapter 4: "User Interface Functions" describes the various methods available for processing and

manipulating Acrobat forms and FDF files.

Reference Appendix A: "DL FormsAPI Reference Appendix" provides full details on each

interface available in DL FormsAPI.

D o c u m e n t C o n v e n t i o n s

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.

• All user interface names in this paper are prefixed dlf (representing DL FormsAPI)

• DL FormsAPI names will be universally in lower case. Enumerator values will be universally UPPER

CASE.

• Commands are contained within the text and set in Courier monospace. If you are reading this

document in PDF form via Adobe Acrobat or Adobe Reader, clicking on a blue command will usually

jump you to a Reference 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.


What’s New in This Release

This section contains highlights of new additions and enhancements to DL FormsAPI v1.1P1k (or

higher). You should also check the accompanying ReadMe.txt file in the software folder or directory,

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

N e w I n t e r f a c e s

listFieldNamesToString

This new Java interface is similar to listFieldNames (the Java version of dlflistfieldnames), but

returns its results in memory as a list of strings containing the field data, as opposed to an output file

containing the same data.

listFieldsToString

This new Java interface is similar to listFields (the Java version of dlflistfields), but returns its

results in memory as a list of strings containing the field data, as opposed to an output file containing the

same data.

U p d a t e d I n t e r f a c e s

dlfinsertimage

The default handling for images included via dlfinsertimage or insertImage interfaces has been

changed, such that the resolution at which the image was scanned will be taken into account, and the

image will be automatically scaled to its original size. (All of the specified image-fitting options will be

applied after any such scaling, not before.)

If the image does not contain information about its original size (most now do), it will be assumed to have

been scanned at 96 dpi. Internal logic has now been modified to set the pels per meter to 96 dpi if no pels

per meter value has been given. Use 72 / (pels per meter * 0.0254) as the default scale factor.


DL FormsAPI n o w a v a i l a b l e f o r Adobe PDF Library v e r s i o n s 6 o r 7

This release of DL FormsAPI v1.1 is now available in release builds compatible with either Adobe PDF

Library v7.0.xPlus or the older v6.1.1Plus. A given release build is only compatible with one or the other,

not both, so ask your Datalogics Support representative for a new release of DL FormsAPI if you are

upgrading your Adobe PDF Library.

Identifying your DL FormsAPI/Adobe PDF Library compatibility

To determine which version compatibility applies to your current release of DL FormsAPI, check the

version prefix of the files in your /Bin folder.

e.g. In a Windows platform default installation, DL FormsAPI using Adobe PDF Library v6.1 will show

DL61 prefixes in the C:\Datalogics\DL_FormsAPI\Bin folder, as seen here:

DL FormsAPI n o w a v a i l a b l e f o r S u n S o l a r i s

DL FormsAPI is now available for the Sun Solaris platform as well as for the Windows platforms.

Contact your Datalogics Sales representative if you are interested in obtaining DL FormsAPI on

additional platforms.


What’s New in Previous Releases

v 1 . 1 P 1 d

DL FormsAPI now built with Adobe PDF Library v7

This release of DL FormsAPI v1.1 was built with Adobe PDF Library v7.0.1Plus. Previous releases of DL

FormsAPI (v1.0 and earlier) were built with Adobe PDF Library v6.1.1Plus or earlier. Subsequent releases

of DL FormsAPI v1.1P1p or higher are being built with Adobe PDF Library v7.0.5Plus.

dlfgetPDF and dlfsetPDF now documented calls

dlfgetPDF and dlfsetPDF are now documented as functional calls. They were first introduced as

undocumented functions in the DL FormsAPI v1.0P1b release.

v 1 . 0 P 1 e

Embedded Linefeeds Now Honored in Multiline Text Fields

In a text field with Multiline capability, an embedded linefeed will now cause a line break wherever it

appears within the text string, allowing more control of short line breaking if desired.

First Production Release

DL FormsAPI v1.0 is the first Production release of the product, including all features and enhancements

first developed in the Beta release versions itemized below.


New Interfaces

dlfgetPDF

This interface, when called, will return the current PDDoc; i.e. the document that is defined as the current

DL FormsAPI target.

dlfsetasprinter

If this interface is called with a value of TRUE, then all following flattening operations will omit fields

which are not to be displayed on a printer. If it is FALSE, then fields which are not to be displayed on a

printer will be displayed. The default value is FALSE.

dlfsetPDF

This interface, when called, will set the current PDDoc as the current DL FormsAPI target.

Updated Interfaces

dlfaddresourcepath

The definition of dlfaddresourcepath has been slightly modified. Any number of these calls can now

be made before an initialization, and the paths specified will all be searched when the initialization action

is performed.

The list of paths will persist from one initialization to the next until a call is made with a NULL pointer to

a path. This NULL call will reset the list to no entries, at which point a new set of paths may then be

defined. If the NULL pointer is not passed in, dlfaddresourcepath will accumulate new entries

without purging the old ones. New entries can be added even after one or more initialization calls have

been performed.

v 0 . 0 1 B 1 m

New Interfaces

dlflistfieldnames

This interface is similar to dlflistfields, but returns only the name of each field, one name per line,

as a means of quickly compiling a list of all current fields

dlfsetdllpath

This interface provides a means of specifying a path to the DLL location.


v 0 . 0 1 B 1 f

DL FormsAPI Now Thread-Safe

As of DL FormsAPI v0.01B1f, the product is now safe for multithreaded applications.

Updated Interfaces

dlfsecurePDF

Early Beta releases of DL FormsAPI included int Read as the third calling argument, preceding int

Print. This has been deleted; User (Read) protection will be automatically applied whenever a

Userpassword value is defined. A user will need to enter the defined User password before the

document can be opened for viewing.

2
InstallingDL FormsAPI
This chapter discusses installation of Datalogics DL

FormsAPI.

2.1


DL FormsAPI Installation Procedure

S u p p o r t e d P l a t f o r m s a n d C o m p i l e r s

The following table lists the supported platforms, operating system and compiler versions for DL

FormsAPI. Except where noted, support for a higher version above and beyond that listed below is not

automatically implied. Please see notes following the table (below) for more details.

Table 2-1: Supported Platforms and Version Numbers

Notes on Supported Platforms and Compilers

1 The preceding table refers to DL FormsAPI v1.1 releases (and higher) only. If building your

application with a prior release, please consult its accompanying documentation.

2 Except where noted, the preceding table refers to 32-bit implementations only.

Platform Operating System Version Compiler and Version

Sun Solaris v8 and higher gcc v3.2.3

Windows (Intel) Windows NT 4.0 (Service Pack 6 and higher), 2000 or XP

MS Visual Studio .NET

I n s t a l l i n g D L F o r m s A P I 2 . 3

UNIX Installation

UNIX installations will typically contain all DL FormsAPI release files in one .tar.gz file, which you

must run through gunzip and then un-tar into its component files.

After downloading via ftp or copying the release from CD-ROM (depending on how you receive your

software from Datalogics), select a high-level location for unpacking the release: e.g. /var, /opt, /var/

Datalogics or /opt/Datalogics. The release will unpack itself into a directory tree under the

current location.

The following steps demonstrate a typical installation on a Solaris v5.8 machine. Other UNIX platforms

will be similar:

1 After login, copy the .tar.gz file (DLF_gcc3.2.3_Release_1_1_P1g.tar.gz in this case) to

your selected location; e.g. /var/Datalogics:

NOTE: The following screen illustrations show a DL FormsAPI v1.1 installation.

Installation screens for other release versions are similar.


2 Issue the gunzip command for your release file:

The UNIX prompt will return as soon as the file is unzipped. An ls command at this point should

show that the original file no longer displays a .gz suffix:


3 Issue the unpack command for your release file; e.g.:

tar xvf DLF_gcc3.2.3_Release_1_1_P1g.tar

This will unpack the release .tar file into its component files:

Subsidiary directories will be created as the unpacking process proceeds.

4 After the process has finished, you should find that the directories and subdirectories are now

populated with the unpacked files. The only visible difference in the current working directory will be

a new DLF folder that has appeared:

NOTE: Not all folders will contain files at installation time. On certain platforms,

some folders may be created empty.


5 Change your working directory to the DLF folder. Issuing an ls * command at this level should show

the six (as of DL FormsAPI v1.1) subsidiary folders within DLF:

6 You will need to create (or update) the LB_LIBRARY_PATH environment variable to point to the

library locations needed by DL FormsAPI, including its own libraries and those already on your

system: e.g.

setenv LD_LIBRARY_PATH ../../Bin:/usr/local/lib

Installation is complete at this point. You can continue on to build one or more of the sample

applications. We recommend building at least one, to verify that your installation finished correctly.


B u i l d i n g S a m p l e s o n U N I X

1 Under the /DLF branch that was just created, locate the Samples folder, open it and list its contents:

You should see several sample application folders (four, in this example) and a platform.mak file

(which is not accessed directly; it will be referenced by those within the individual sample folders).

2 Choose a sample to build, such as Flatten in this example here, and change your directory into that

folder. An ls command should show you a source-code file and a makefile:


3 A gmake command issued there should build the sample without further intervention:

When it completes, an ls command should show a compiled object (.o) file and a finished

application.

4 If all goes well, issuing a ./FlattenPDF command here, with no input command-line arguments,

should yield a USAGE message for you from the program, showing you the correct syntax to use:

Your sample application is ready to run.


Windows Installation

Installation of DL FormsAPI is straightforward, consisting primarily of unpacking a .zip file and

possibly relocating some components if desired. DL FormsAPI is distributed on Windows platforms in

.DLL form.

1 The release is packaged as a .zip file. (e.g. DLF_VS7_Release_1.0P1b.zip). Download it via

your secure ftp account at ftp.datalogics.com or copy it from your release CD-ROM, as

appropriate.

NOTE: Release package contents may vary; these screen illustrations are examples

only.

ftp.datalogics.com

2 . 1 0 DL FormsAPI User Guide

2 Unzip the file in the desired location, such as (in this example) C:\Datalogics\DL_FormsAPI. Be

sure that the "All files" radio button and "Use folder names" checkbox are selected:

3 If using the Windows WinZip utility, you will see the lower right corner indicator turn red as

unpacking proceeds, and return to green when complete:

I n s t a l l i n g D L F o r m s A P I 2 . 1 1

4 You should see a folder collection similar to this when unpacking is complete:

Select the \Bin folder.

5 You should find a collection of .DLL files within the \Bin folder that will be used for DL FormsAPI

operation:

You have the option of relocating these files where a DL FormsAPI application can find them, or

updating your Path definition to include this location.


Installation is complete at this point. You can move on to building and running the included sample

applications within the \Samples folder if desired:

3
Overviewof DL FormsAPI
This chapter discusses the available features and

functions of Datalogics DL FormsAPI.

3.1


An Introduction to DL FormsAPI

Many customers have requested support with flattening of Adobe Acrobat Forms documents

("acroforms"): that is, replacing the form fields with non-form fields, so that the fields’ current values

become objects of the document itself, part of the text.

In general, these customers have a very specific set of requirements. These might include:

• Open an external PDF file, directly or via a Forms Data Format (FDF) file.

• Replace or update field contents, via either a list of fieldname and value, or an FDF file

• Write the document as PDF output with acroforms (form fields), using the modified values

• Write the document as PDF output without acroforms (flattened), with the modified values in place of

forms

• Print the document

• Add signature images (i.e. not digital signatures, but images such as autographs) to the document for

printing

• List the names of acroform fields in the document

DL FormsAPI will format all fields to the same appearance that you see when viewing the document via

Adobe Acrobat or Adobe Reader. This makes use of a small composition engine, the ability to parse rich

text, and a small paginator to position text within a rectangle. It will accept documents from either the

system default file system or a memory buffer, and it will write documents to the default file system or to

a memory buffer. It can read in and write out PDF content via a URL that includes HTTP addresses.

U s i n g DL FormsAPI w i t h i n a n Adobe PDF Library A p p l i c a t i o n

Although this package is based on the Adobe PDF Library, that is not exposed to your application; you

only need to work with the DL FormsAPI methods listed in this guide, then include this functionality in

your finished application as a Dynamic Link Library (on Windows platforms) or a shared library (on

UNIX).

However, in complex applications it may be necessary to use both products to complete the task. When

using both Adobe PDF Library (APDFL) and DL FormsAPI in the same application, keep the following

points in mind:

O v e r v i e w o f D L F o r m s A P I 3 . 3

• Initializing DL FormsAPI also initializes APDFL. You must call DL FormsAPI’s initialization

(dlfinit), but do not call APDFL's initializer (PDFLInit, or dlpdfinit for Datalogics Interface

applications) as well.

• DL FormsAPI releases may be built on Adobe PDF Library v6.1 or v7.0 components. You should

ensure that your release of DL FormsAPI is at the same level as the Adobe PDF Library modules used

in your application: v6.1 or v7.0. See “Identifying your DL FormsAPI/Adobe PDF Library

compatibility” on page 1.5 for more details.

• The DL FormsAPI calls dlfgetPDF and dlfsetPDF will return the current PDDoc and set the

current PDDoc as DL FormsAPI's target PDDoc, respectively. The input/output declarations of the

accepted (dlfsetPDF) and returned (dlfgetPDF) parameters are as void *, cast to and from the

PDDoc to use. In this manner a user can pass documents back and forth between DL FormsAPI and

APDFL.

Typical Job Workflow

The typical work flow for using this package will involve a number of tasks in sequence, the exact number

depending on the type of work to perform. A full process covering all aspects of DL FormsAPI work can

take the following path:

• Initialize the package

• Open a PDF document

• Does the document contain acroforms?

• List the form fields

• Replace the current value of a named field

• Obtain the value of a named field

• Merge FDF document contents with PDF

• Flatten the PDF document

• Add graphic signature images

• Set security for the resulting PDF document

• Save the PDF document

• Save selected pages from the PDF document

• Merge PDF documents

• Print the PDF document

• Close the PDF document

• Terminate the package

NOTE: In multi-threaded applications using both DL FormsAPI and Adobe PDF Library,

dlfgetPDF and dlfsetPDF must be acting within the same thread. These pass

documents back and forth between the two products, not between threads.


Font Resources

Font resources may be needed in the process of flattening text, or when replacing contents of forms fields

(if a subset font was used for the forms field current value). The path to locate these must be specified

prior to initiating the package.

DL FormsAPI does not support XAF forms or Rich Text fields within forms.

Error Handling

Unlike the returned-exceptions model of error handling, such as that of Adobe PDF Library and DLI,

communication of error status within DL FormsAPI uses the “C” run-time stdio model instead,

indicating success or failure (or other status as appropriate) via the return code of the function. More

details on the nature of the failure are available via a separate interface.

DL FormsAPI never raises an exception, in either the Adobe PDF Library or the “C++” sense. All

exceptions raised in APDFL will be caught by the package. PDF and FDF documents will be parsed for

meaning when opened, rather than on an as-needed basis.

4
User Interface Functions
This chapter discusses the available functions and usage

of Datalogics DL FormsAPI.

4.1


Introduction

The prefix dlf (for DL FormsAPI) is used as a prefix for all user interface names, in all lower case.

Enumerator values will be universally UPPERCASE. All character strings accepted into or generated from

DL FormsAPI may be encoded in either PDDocEncoding (or WinAnsiEncoding) or UCS2, encoded as

UTF16 Host Endian. The interface dlfsetencoding selects which encoding will be used, and it may be

changed at any point.

U s e r I n t e r f a c e F u n c t i o n s 4 . 3

Control Interfaces

These interfaces are used to initialize and terminate the library, as well as to gather any information

needed for the application itself. In a threaded environment, each thread must initiate and terminate the

package.

A return code of zero indicates there were no problems in executing the function. A non-zero return code

indicates the function did not complete correctly.

i n t dlfinit ( i n t T e m p I n M e m o r y ) ;

This is called once to initialize the utility. If the value of TempInMemory is true, we will set the library to

create all temporary files in memory. If false, we will create all temporary files in the default file system.

i n t dlfterm( ) ;

This is called once to terminate the utility.

i n t dlfsetdllpath ( u n s i g n e d c h a r * N a m e ) ;

This permits setting the path which is used to locate the DLL.

u n s i g n e d l o n g dlfversion ( ) ;

Returns the version number of the utility in the form ((Version Major << 16) & Version Minor).

This form is suitable for testing for compatibility.

u n s i g n e d c h a r * dlfversionstring ( ) ;

Returns the version number as a string in DL version and release format (e.g. 1.2P2a).

u n s i g n e d c h a r * dlflasterror ( ) ;

This interface will return a text string which describes the last error to occur. The string will be a null

pointer if no error has occurred.


v o i d dlflasterrornumber ( u n s i g n e d l o n g * d l f c o d e , u n s i g n e d l o n g * a p d f l c o d e ) ;

This interface will return the identity of the last error encountered, as a numeric value. This value is

composed of two pieces:

• The DL FormsAPI error code, local to this API

• The Adobe PDF Library error code which may be present in some cases

The APDFL error code will be zero in all cases except in which the DL FormsAPI error code indicates an

APDFL error.

i n t dlfaddresourcepath ( u n s i g n e d c h a r * P a t h ) ;

This interface may be called any number of times prior to calling dlfinit. Each call will add a path to

the list of paths to be searched for resources. Any number of these calls can be made before an

initialization, and the paths specified will all be searched when the initialization action is performed.

The list of paths will persist from one initialization to the next until a call is made with a NULL pointer to

a path. This NULL call will reset the list to no entries, at which point a new set of paths may then be

defined. If the NULL pointer is not passed in, dlfaddresourcepath will accumulate new entries

without purging the old ones. New entries can be added even after one or more initialization calls have

been performed.

i n t dlfsetreadtype ( D L F I O T y p e T y p e ) ;

This interface selects how PDF and FDF files will be opened. The attribute is one of the following

enumerations:

Table 4-1: dlfsetreadtype DLFIOType Options

Default value is DLFIOType_FileSystem.

DLFIOType_FileSystem (Default)

The supplied pointer points to a null-terminated ASCII string which rep-resents a file name of a PDF or FDFFDF file located on the local machine’s file system. The Size field of the open command is not used.

DLFIOType_InMemory The supplied pointer is to a block of unsigned characters which contain a representation of a PDF or FDF file. The Size field of the open com-mand is the extent of that file.

DLFIOType_URL The supplied pointer is to a null-terminated URL which describes a PDF or FDF file accessible via FILE:, HTTP:, HTTPS:, GOPHER: or FTP:. The service type must be included in the URL. The Size field of the open command is not used.


i n t dlfsetwritetype ( D L F I O T y p e T y p e ) ;

This interface selects how PDF and informational files will be written. The attribute is one of the same

enumerations used for dlfsetreadtype. Default value is DLFIOType_FileSystem.

i n t dlfsetcompression ( D L F C O M P R E S S I O N C o m p r e s s i o n , i n t L i n e a r -i z e ) ;

This interface sets the compression that will be used on all later PDF document writes. Note that the

greater the level of compression or optimization used, the slower the write will be. Default value is

DLFCOMPRESSION_DLFCOMPRESS. Compression is selected by an enumeration; see the following table.

Table 4-2: dlfsetcompression Compression Options

This interface also allows selecting if the output file is to be linearized. In general, creating a linearized

document takes longer, but results in a somewhat smaller document. A linearized document may be byte

served.

DLFCOMPRESSION_DLFLEAVECOMPRESS

This will generate output with the same compression setting as the input, however it was configured.

DLFCOMPRESSION_DLFUNCOMPRESS

This will write the document completely uncompressed. This is the fast-est way to write a document, and guarantees it can be read by all read-ers. However, it will be significantly larger than needed.

DLFCOMPRESSION_DLFCOMPRESS (Default)

This will compress a document as much as possible using facilities avail-able prior to PDF v1.6. The document is readable under any version of Reader or Acrobat. LZW compression will be avoided.

DLFCOMPRESSION_DLFOPTIMIZE

This will compress the document as in DLFCOMPRESSION_DLFCOMPRESS, but will also merge fonts and images that may be used multiple times. The largest case for using this is when documents are stitched together, and each document may use the same font or image. There is a fairly large time penalty for using this facility, as it requires intensive processing of the document content.

DLFCOMPRESSION_DLFMAXCOMPRESS

This will write the smallest possible form of the document. However, it can only be read using Acrobat or Adobe Reader 6 or greater (PDF v1.5 or greater). This form may be the best for storing PDF, including storing forms for later processing. This will compress the document as in DLFCOMPRESSION_DLFMAXCOMPRESS, and will also do the optimiza-tion of fonts as images, as in DLFCOMPRESSION_DLFOPTIMIZE.

DLFCOMPRESSION_DLFMAXOPTIMIZE

This will compress the document as in DLFCOMPRESSION_DLFMAXCOMPRESS, and will also do the optimiza-tion of fonts as images, as in DLFCOMPRESSION_DLOPTIMIZE.


i n t dlfsetasprinter ( i n t T r u e ) ;

Many types of annotations are intended to be visible in screen displays but removed during printing, such

as certain button controls or text annotations ("sticky notes"). (e.g. When a button annotation is defined

in a document, two of the options for its Common Properties are "Visible but doesn’t print" and "Hidden

but printable.") Normally, the document will be flattened in the state that you would view it on-screen,

and thus annotations visible there will remain so after flattening. (i.e. Their viewing properties carry

forward into the flattened document.) In addition, annotations intended only for print output will

normally not be included in the flattened document, and thus they will not appear if the flattened

document is subsequently printed.

However, if this interface is called with a value of TRUE, the situation is reversed: the flattening process

will then include all printable annotations (those which are to be displayed on a printer) when flattening

the document, and exclude those which are not printable. The default value is FALSE.

This setting takes effect for the duration of the program run or unless reset by another

dlfsetasprinter call. It applies not only to the currently-open file but also to all future files, until its

setting is cancelled or the program exits.

i n t dlfsetencoding ( D L F E N C O D I N G E n c o d i n g ) ;

This interface sets the encoding to be used by character strings in and out of the package. It may be set to

DLFENCODING_DLFPDDOC to indicate that strings are in PDDOC or WinAnsiEncoding, or

DLFENCODING_DLFUTF16 to indicate that strings are in UCS2, encoded in UTF16 Host Endian. BOM

is not required for UTF16. The default value is DLFENCODING_DLFPDDOC.


File Handling

These interfaces are used to open a PDF file, and to establish that file as the “current” PDF file.

i n t dlfopenPDF ( u n s i g n e d c h a r * N a m e , f p o s _ t S i z e ) ;

This interface opens the specified file. The package will allow only one single PDF file to be open at any

time.

i n t dlfopenFDF ( u n s i g n e d c h a r * N a m e , f p o s _ t S i z e ) ;

When the file referenced is a Forms Data Format (FDF) file, it is opened. It may or may not contain a valid

reference to a PDF file with which it is associated. If it does not contain such a reference, or if the

reference is not valid, or cannot be satisfied, then no PDF file will be opened. The current PDF file, if there

is one open, will be closed. If a valid name is found, that file will be opened and will become the current

PDF file.

A non-zero return code indicates that the function did not complete correctly. In all cases, this also means

that there is no current PDF or FDF document established. How a file is opened, and what parameters are

meaningful, depends on the file open method selected in package initialization above

(dlfsetreadtype).

v o i d dlfgetPDF ( ) ;

This call will return the current PDDoc as DL FormsAPI's target PDDoc in applications that make use of

both DL FormsAPI and Adobe PDF Library methods.

The output declaration of the dlfgetPDF parameter is as void *, cast from the PDDoc to use. In this

manner a user can pass documents back and forth between DL FormsAPI and Adobe PDF Library. See

“Using DL FormsAPI within an Adobe PDF Library Application” on page 3.2 for more details.

CAUTION: If a second file is opened before the first is closed, the first will be

automatically closed without being written to output.





i n t dlfsetPDF ( v o i d * P D D o c ) ;

This call will set the current PDDoc as DL FormsAPI's target PDDoc in applications that make use of both

DL FormsAPI and Adobe PDF Library methods.

The input declaration of the dlfsetPDF parameter is as void *, cast from the PDDoc to use. In this

manner a user can pass documents back and forth between DL FormsAPI and Adobe PDF Library. See

“Using DL FormsAPI within an Adobe PDF Library Application” on page 3.2 for more details.

i n t dlfclosePDF ( ) ;

This interface closes the current PDF document, and frees all resources used for it.

It is never necessary to call this interface. Calling dlfopenPDF, dlfopenFDF or dlfterm will behave as

if this interface has been called.




NOTE: This interface does not save the current document. If a modified document

is to be saved, one of the save document interfaces must be used. If an FDF

document is also open, it is also closed.


File Information

It is anticipated that this portion of the API will be used primarily in the data analysis step, preceding the

document processing step. In this step, we will extract information about the fields of the document, and

an analyst will compare those fields to the information available to be placed into the document, building

a mapping.

i n t dlfhasacroforms ( ) ;

This interface will return true if there is a current PDF document, and that document contains acroforms.

It will return false if there is no current PDF document, or if the current PDF document does not contain

an acroforms dictionary.

c h a r * dlffieldvalue ( u n s i g n e d c h a r * N a m e ) ;

This interface will return the text string which represents the current value for the field named in Name. If

there is no current value, a null pointer will be returned.

i n t dlflistfields ( u n s i g n e d c h a r * N a m e , f p o s _ t * S i z e ) ;

This interface will create a file as specified in dlfsetwritetype. If the file is to memory, Size is set to

the maximum size that buffer can contain on input, and will contain the size actually used on return.

The file will consist of records demarcated by the system NewLine character(s). Each record will consist of

the name of a field in the acroforms directory of the current dictionary. Output will be written in either

PDDocEncoding or UTF16 Host Endian Encoding, as selected by the interface dlfsetencoding. A

non-zero return value indicates that a problem occurred and the file was not created.

(Also see listFieldsToString under “Java-Specific Interfaces” on page 4.10 below.)

i n t dlflistfieldnames ( u n s i g n e d c h a r * N a m e , f p o s _ t * S i z e ) ;



This interface functions in a manner similar to that of dlflistfields, consisting of records

demarcated by the system NewLine character(s), but writes only the name of a field on each line, without

further information. Output will be written in either PDDocEncoding or UTF16 Host Endian Encoding,


as selected by the interface dlfsetencoding. A non-zero return value indicates that a problem occurred

and the file was not created.

(Also see listFieldNamesToString under “Java-Specific Interfaces” on page 4.10 below.)

i n t dlflistfieldsandlocations ( u n s i g n e d c h a r * N a m e , f p o s _ t * S i z e ) ;



The file will consist of records demarcated by the system NewLine character(s). Each record will consist of

the name of a field in the acroforms directory of the current dictionary, followed by one or more locations

where this field is to be displayed.

Each location should be in the format “(“, Page Number (zero relative), Lower Left Corner X

relative page lower left corner X, Lower Left Corner Y Relative Page Lower

left Corner Y, Width, Depth, and finally “)”. All coordinates and distances should be in points and

fractions of points.

Output will be written in either PDDocEncoding or UTF16 Host Endian Encoding, as selected by the

interface dlfsetencoding.

A non-zero return value indicates that a problem occurred and the file was not created.

J a v a - S p e c i f i c I n t e r f a c e s

The following variants of DL FormsAPI interfaces are available in Java form only.

java.lang.string listFieldNamesToString

This Java-specific interface functions in a manner similar to that of dlflistfieldnames, but returns

its results in memory as a list of strings containing the field names, as opposed to an output file containing

the same data.

This interface will return only the name of each field in the current document. The string will be either

UTF16 or PDDOC encoding, according to the value set via the setEncoding interface.

U s e r I n t e r f a c e F u n c t i o n s 4 . 1 1

java.lang.string listFieldsToString

This Java-specific interface functions in a manner similar to that of dlflistfields, but returns its

results in memory as a list of strings containing the field data, as opposed to an output file containing the

same data.

This interface will return the fully-qualified name of each field in the current document. The string will be

either UTF16 or PDDOC encoding, according to the value set via the setEncoding interface.

Data Modification

i n t dlfsetfieldvalue ( u n s i g n e d c h a r * N a m e , u n s i g n e d c h a r * V a l u e ) ;

This interface sets the specified field’s current value to the given specified value. A non-zero return code

indicates that the action was not done.

i n t dlfmergePDFandFDF( ) ;

This interface will cause all values specified in the current FDF to be merged into the current PDF

document. A non-zero return code indicate that this action was not done.

i n t dlfflattenPDF

This interface will cause the current PDF document to become flattened (i.e. fields in the document will be

converted from Adobe Acrobat form fields to document content). A non-zero return code indicates that

this action was not done.

i n t dlfflattenfield ( u n s i g n e d c h a r * N a m e ) ;

This interface will cause only the specified field to be flattened. When the field to be flattened is a Button

field, DL FormsAPI will display the field according to the currently selected appearance. (See

dlfsetasprinter.) When it is a Text field, DL FormsAPI will display it with the current text, or the

default text if there is no current text. When it is a choice field, DL FormsAPI will display the current


choice value (or values, if multiple choices are permitted). If it is a signature field, DL FormsAPI will

display nothing.

i n t dlfdeletefield ( u n s i g n e d c h a r * N a m e ) ;

This interface will cause the named field to be completely removed from the document. It is used for

actions such as removing buttons, or unused fields.

i n t dlfhidefield ( u n s i g n e d c h a r * N a m e )

This interface will cause the named field to be hidden. it will remain in the document, but it cannot be

seen or modified.

i n t dlflockfield ( u n s i g n e d c h a r * N a m e )

This interface will cause the named field to be locked. It will remain a field in the document, will display

and print, but it cannot be modified by the document user.

i n t dlfremovepages ( i n t F i r s t P a g e , i n t L a s t P a g e ) ;

This interface will remove the specified pages, by relative page number, from the current document. Page

numbers are specified base 1. (i.e. The first page is numbered 1.)

FirstPage is required. LastPage may be -1, indicating the last page of the document.

NOTE: The dlfsetasprinter interface will affect whether printable

annotations will actually appear in a document that was flattened before printing.

You should review your flattened output and your printed output to ensure that

annotations are (or are not) appearing as you intend. See “int dlfsetasprinter

(int True);” on page 4.6 for more details.

NOTE: Page numbers are always relative, and hence change if pages are removed.

If you want to remove pages 2-3, and 5, from a document, you should either

remove 5 first (i.e. start from the far end and remove as you go back), or subtract

the number of pages removed preceding page 5 before removing what used to be

the fifth page itself (i.e. Remove pages 2 and 3, then page 3 again).


Image Handling

When including images in your document, be sure that the scaling and positioning values will place the

image(s) correctly. The size of the image in output will be affected by the scale at which it was originally

scanned, and if that information is not embedded in the image and readable by DL FormsAPI, certain

default assumptions will be made instead. You can make size, scaling and positioning adjustments as

required in order to fit the image to its alotted space on the page.

H a n d l i n g o f U n s c a l e d I m a g e s

The default handling for images included via dlfinsertimage or insertImage interfaces takes into

account the resolution at which the image was originally scanned, as that data is usually embedded within

the image file itself, and the image will be automatically scaled to its original size. PDF always displays a

bitmap image as if it is 72 dpi when the scale factor is 1.0.

In some cases, however, an image file may not indicate its original scale. If the image does not contain

information about its original size (most now do), it will be assumed to have been scanned at 96 dpi, and

internal logic will set the pels per meter to 96 dpi as a result.

i n t dlfinsertimage ( u n s i g n e d c h a r * I m a g e , u n s i g n e d l o n g I m a g e -S i z e , u n s i g n e d c h a r * F i e l d N a m e , i n t H P o s , i n t V P o s ) ;

This interface will read an image in Windows BMP format from the source specified via

dlfsetreadtype. The image resulting will be placed in the location(s) specified for the Acroform Field

named in FieldName. Since the image size may not match the field size, horizontal and vertical

positioning options are available for either positioning the unaltered image within the field area or scaling

it in different ways to fill the alotted space.

The horizontal positioning (HPos value) can be one of the following enumerations:

Table 4-3: dlfinsertimage Horizontal Positioning Options

DLFHPOS_LEFT (Default) Position the image to the left end of the field.

DLFHPOS_CENTER Center the image horizontally within the field.

DLFHPOS_RIGHT Position the image to the right end of the field.

DLFHPOS_SCALEUP Scale the image horizontally up to the width of the field.

DLFHPOS_SCALEDOWN Scale the image horizontally down to the width of the field.

DLFHPOS_NODISTORT Scale the image to the field in both directions, maintaining the original aspect ratio of the image.


The vertical positioning (VPos value) options are similar:

Table 4-4: dlfinsertimage Vertical Positioning Options

When either DLFHPOS_NODISTORT or DLFVPOS_NODISTORT is specified, the image will be scaled up or

down to fit the field as appropriate, but it will not be skewed or distorted in order to fill the field.

If it is not an exact fit in the field, there will be some whitespace left over, either above and below it or on

either side of it, depending on which direction is the best fit. The image will be positioned within that

whitespace according to the setting of the shorter axis; e.g. if the leftover whitespace is on either side of

the image, and its horizontal (HPos) value was DLFHPOS_RIGHT, the image will be positioned to the

right end of the field, with all leftover whitespace to the left.

If the image is oversized for the field in either dimension and scaling is not permitted, it will be clipped to

the field size.

DLFVPOS_TOP Position the image to the top end of the field.

DLFVPOS_CENTER Center the image vertically within the field.

DLFVPOS_BOTTOM (Default) Position the image to the bottom end of the field.

DLFVPOS_SCALEUP Scale the image vertically up to the height of the field.

DLFVPOS_SCALEDOWN Scale the image vertically down to the height of the field.

DLFVPOS_NODISTORT Scale the image to the field in both directions, maintaining the original aspect ratio of the image.


Document Creation

i n t dlfsecurePDF ( u n s i g n e d c h a r * U s e r P a s s w o r d ,u n s i g n e d c h a r * O w n e r P a s s w o r d , i n t P r i n t , i n t c o p y , i n t e d i t ,i n t e d i t N o t e s , i n t s a v e A s , i n t l o n g K e y ) ;

This interface will allow the user to specify that the PDF document written should be secured, and how it

should be secured. If longKey is True, 128-byte encryption will be used in place of the default 32-byte

encryption.

A non-zero return code indicates that this action was not taken.

i n t dlfsave ( u n s i g n e d c h a r * N a m e , f p o s _ t * S i z e ) ;

Save the current document as specified in dlfsetwritetype. If the file is to memory, Size is set to the

maximum size that buffer can contain on input, and will contain the size actually used on return. A non-

zero return value indicates that the action was not performed.

i n t dlfsavesome ( u n s i g n e d c h a r * N a m e , f p o s _ t * S i z e , i n t F i r s t P a g e , i n t L a s t P a g e ) ;

This interface is identical to dlfsave, above, except that it saves only a single range of pages rather than

all pages. FirstPage is relative 1, and is required. LastPage may be -1, in which case it is interpreted

as the last page of the document.

i n t dlfsaveappend ( u n s i g n e d c h a r * N a m e , f p o s _ t * S i z e ) ;

This interface will behave precisely the same as dlfsave, if the specified file does not exist or is not a

PDF File. However, if the specified file is a PDF file, then rather than saving the current document, its

pages will be appended to the existing document. This is useful when creating a number of forms that are

logically “bundled” into one resulting document.

NOTE: 128-byte encrypted files cannot be read by versions of Adobe Acrobat or

Adobe Reader older than v5.x.


i n t dlfmergepages ( u n s i g n e d c h a r * N a m e , f p o s _ t * S i z e ,i n t F i r s t P a g e , i n t L a s t P a g e , i n t B e f o r e P a g e ) ;

This interface behaves the same as dlfsaveappend, with the following differences:

• The output file must exist prior to calling this interface, and must be a PDF document with at least one

page.

• Only the portion of the current document between FirstPage and LastPage will be added to the

output document.

• The pages will be added preceding BeforePage, rather than at the end of the document.

All page number are specified as relative 1. The FirstPage number is required. The LastPage number

may be -1, indicating the end of the source document. The BeforePage page number may be -1,

indicating the end of the receiving document. (In other words,

dlfmergepages("outdoc.pdf", 0, 1, -1, -1) is identical to

dlfsaveappend("outdoc.pdf", 0).)


Printing

The print environment available for DL FormsAPI and its underlying Adobe PDF Library is highly

dependent on the platform in which the process is running, with two significant factors to consider.

First, Windows offers a wide selection of print options, Macintosh a slightly smaller set, and UNIX a very

narrow set. What DL FormsAPI attempts to present is a print interface that can be used without a

complex data structure, and which will provide the best possible print control in all environments.

Second, a major variable in print environment is whether the process resides on a server or client

platform. On a server platform, all print control information must be supplied by the application to the

package. On a client platform, the application could ask the user for information about how he wants this

data to be printed.

With these variables in mind, the printer interface breaks the job into smaller sections or tasks. One prints

the job to a specified device with a specified set of options (the server side and UNIX print facility).

Another asks the user to fill in the blanks (the client-side print facility). There are two calls to print,

depending on which facility is to be used, and a collection of calls to set print capabilities.

i n t dlfprint

This interface will cause the current PDF document to be printed to the pre-specified device. A single set of

print parameters will be used, modified by settable parameters below.

i n t dlfprintperuser ( ) ;

This interface is available only on Windows. It will display the Windows print dialog box, and will print

the document according to the user-selected options. If the user chooses to cancel the print, this call will

return a non-zero value. Any values selected in the following functions will be used as default values in the

print dialog.

NOTE: The dlfsetasprinter interface will affect whether printable

annotations will actually appear in a document that was flattened before printing.

You should review your flattened output and your printed output to ensure that

annotations are (or are not) appearing as you intend. See “int dlfsetasprinter

(int True);” on page 4.6 for more details.


i n t dlfprintsetbin ( l o n g B i n N u m b e r ) ;

Sets the source for paper in the current printer. Printer name must be set before this interface is called. If

the specified BinNumber is not valid for the specified device, an error will be returned.

i n t dlfprintsetcollate ( i n t C o l l a t e ) ;

When multiple copies are printed, they may be collated or merged. The default is merged.

i n t dlfprintsetcopies ( l o n g N u m b e r O f C o p i e s ) ;

Sets the number of copies to be produced. Default is 1 copy.

i n t dlfprintsetduplex ( i n t D u p l e x M o d e ) ;

Sets the printer duplex mode. Default is no duplex.

i n t dlfprintsetpages ( l o n g S t a r t , l o n g E n d , i n t A p p e n d ) ;

Set pages to be printed. Page numbers are 1 relative. Setting Start to zero will start with first page.

Setting End to zero will end with last page. Default is all pages. If the End page value is greater than the

last page of the document, the last page will be used as the end page and no error will be returned.

i n t dlfprintsetpapersize ( l o n g W i d t h , l o n g D e p t h ) ;

Set the paper size to be used when printing.

i n t dlfprintsetprintername ( u n s i g n e d c h a r * N a m e ) ;

Sets the name of the printer in Windows systems, and the name of the print queue in UNIX systems. If the

specified name is not a valid printer or print queue, an error will be returned.

i n t dlfprintsetprinttofile ( u n s i g n e d c h a r * N a m e , f p o s _ t * S i z e ) ;

Sets pages to be printed to a file rather than to a printer. File type is as set by dlfsetwritetype. If not

a memory file, then Size is ignored. If Name is a NULL pointer, this sets a previous print-to-file setting to

be off. Default is no print to file.

A
DL FormsAPI Reference Appendix
This appendix defines methods available with DL

FormsAPI.

A.1

A . 2 DL FormsAPI User Guide

dlfaddresourcepath (unsigned char *Path)

Return Value: int

Description This interface may be called any number of times prior to calling dlfinit. Each call will add a path to the list of paths to be searched for resources. Any number of these calls can be made before an initialization, and the paths specified will all be searched when the initialization action is performed.The list of paths will persist from one initialization to the next until a call is made with a NULL pointer to a path. This NULL call will reset the list to no entries, at which point a new set of paths may then be defined. If the NULL pointer is not passed in, dlfaddresourcepath will accumulate new entries without purg-ing the old ones. New entries can be added even after one or more initialization calls have been performed.

Parameters unsigned char *Path: fully-attributed path leading to your resource loca-tion(s)

Return Value int:zero if successful; non-zero if function did not complete correctly

Header dlflib.h

Related Interfaces

Availability All DL FormsAPI supported platforms.

DL FormsAPI R e f e r e n c e A p p e n d i x A . 3

dlfclosePDF ()

Return Value: int

Technical Notes

1 It is never necessary to call this interface. Calling dlfopenPDF, dlfopenFDF or dlfterm will

behave as if this interface has been called.

2 This interface does not save the current document. If a modified document is to be saved, one of the

save document interfaces must be used. If an FDF document is also open, it is also closed.

Description This interface closes the current PDF document, and frees all resources used for it. See Technical Notes below.

Parameters


Header dlflib.h

Related Interfaces dlfopenPDF,dlfopenFDF,dlfterm



dlfdeletefield (unsigned char *Name)

Return Value: int

Description This interface will cause the named field to be completely removed from the doc-ument. It is used for actions such as removing buttons, or unused fields.

Parameters unsigned char *Name: Name of the field to be deleted


Header dlflib.h

Related Interfaces dlfhidefield,dlflockfield



dlffieldvalue (unsigned char *Name)

Return Value: char *

Description This interface will return the text string which represents the current value for the field named in Name. If there is no current value, a null pointer will be returned.

Parameters unsigned char *Name: name of the field to be queried

Return Value char *: pointer to the retrieved value

Header dlflib.h

Related Interfaces dlfsetfieldvalue



dlfflattenfield (unsigned char *Name)

Return Value: int

Description This interface will cause only the specified field to be flattened.• When the field to be flattened is a Button field, DL FormsAPI will display the

field according to the currently selected appearance. (See dlfsetasprinter.)

• When it is a Text field, DL FormsAPI will display it with the current text, or the default text if there is no current text.

• When it is a choice field, DL FormsAPI will display the current choice value (or values, if multiple choices are permitted).

• If it is a signature field, DL FormsAPI will display nothing.

Parameters unsigned char *Name: Name of the field to be flattened


Header dlflib.h

Related Interfaces dlfflattenPDF,dlfsetasprinter



dlfflattenPDF ()

Return Value: int

Description This interface will cause the current PDF document to become flattened (i.e. fields in the document will be converted from Adobe Acrobat form fields to document content).

Parameters


Header dlflib.h

Related Interfaces dlfflattenfield,dlfsetasprinter



dlfgetPDF ()Return Value: void

Technical Notes

1 In multi-threaded applications using both DL FormsAPI and Adobe PDF Library, dlfgetPDF and

dlfsetPDF must be acting within the same thread. These pass documents back and forth between the

two products, not between threads.

Description This call will return the current PDDoc as DL FormsAPI's target PDDoc in applica-tions that make use of both DL FormsAPI and Adobe PDF Library methods.The output declaration of the dlfgetPDF parameter is as void *, cast from the PDDoc to use. In this manner a user can pass documents back and forth between DL FormsAPI and Adobe PDF Library. See “Using DL FormsAPI within an Adobe PDF Library Application” on page 3.2 for more details.

Parameters

Return Value

Header dlflib.h

Related Interfaces dlfsetPDF



dlfhasacroforms ()

Return Value: int

Description This interface will return true if there is a current PDF document, and that docu-ment contains acroforms. It will return false if there is no current PDF docu-ment, or if the current PDF document does not contain an acroforms dictionary.

Parameters

Return Value • int true: if there is a current PDF document, and that document contains acroforms

• int false: if there is no current PDF document, or if the current PDF document does not contain an Acroforms dictionary

Header dlflib.h

Related Interfaces


A . 1 0 DL FormsAPI User Guide

dlfhidefield (unsigned char *Name)

Return Value: int

Description This interface will cause the named field to be hidden. it will remain in the docu-ment, but it cannot be seen or modified.

Parameters unsigned char *Name: Name of the field to be hidden


Header dlflib.h

Related Interfaces dlfdeletefield,dlflockfield


DL FormsAPI R e f e r e n c e A p p e n d i x A . 1 1

dlfinit (int TempInMemory)

Return Value: int

Technical Notes

1 In a threaded environment, each thread must initiate and terminate the package.

Description This is called once to initialize the utility.

Parameters int TempInMemory: If true, all temporary files will be created in memory; if false, all temporary files will be created in the default file system

Return Value int: A return code of zero indicates there were no problems in executing the function. A non-zero return code indicates the function did not complete cor-rectly.

Header dlflib.h

Related Interfaces dlfterm



dlfinsertimage (unsigned char *Image, unsigned long ImageSize, unsigned char *FieldName, int HPos, int VPos)

Return Value: int

Technical Notes

1 Images will be automatically scaled according to their original scan dpi values, as indicated within the

image file. If the image does not contain information about its original size (most now do), it will be

assumed to have been scanned at 96 dpi. This is set prior to any subsequent resizing set by the user.

2 The horizontal positioning (HPos value) can be one of the following enumerations:

Table A-5: dlfinsertimage Horizontal Positioning Options

Description This interface will read an image in Windows BMP format from the source speci-fied via dlfsetreadtype. The image resulting will be placed in the location(s) specified for the Acroform Field named in FieldName. It will be positioned and scaled according to the values specified in HPos and VPos. See Technical Notes below and “Image Handling” on page 4.13 for more details on size and position-ing options.

Parameters • unsigned char *Image: pointer to inserted image• unsigned long ImageSize: size of the input BMP data• unsigned char *FieldName: location to place the resulting image• int HPos: horizontal position and/or scaling instruction. See Technical Notes

below.• int VPos: vertical position and/or scaling instruction. See Technical Notes

below.


Header dlflib.h

Related Interfaces


DLFHPOS_LEFT (Default) Position the image to the left end of the field.

DLFHPOS_CENTER Center the image horizontally within the field.

DLFHPOS_RIGHT Position the image to the right end of the field.

DLFHPOS_SCALEUP Scale the image horizontally up to the width of the field.

DLFHPOS_SCALEDOWN Scale the image horizontally down to the width of the field.

DLFHPOS_NODISTORT Scale the image to the field in both directions, maintaining the original aspect ratio of the image.


3 The vertical positioning (VPos value) options are similar:

Table A-6: dlfinsertimage Vertical Positioning Options

4 When either DLFHPOS_NODISTORT or DLFVPOS_NODISTORT is specified, the image will be scaled

up or down to fit the field as appropriate, but it will not be skewed or distorted in order to fill the

field.

If it is not an exact fit in the field, there will be some whitespace left over, either above and below it or

on either side of it, depending on which direction is the best fit. The image will be positioned within

that whitespace according to the setting of the shorter axis; e.g. if the leftover whitespace is on either

side of the image, and its horizontal (HPos) value was DLFHPOS_RIGHT, the image will be positioned

to the right end of the field, with all leftover whitespace to the left.

If the image is oversized for the field in either dimension and scaling is not permitted, it will be clipped

to the field size.

DLFVPOS_TOP Position the image to the top end of the field.

DLFVPOS_CENTER Center the image vertically within the field.

DLFVPOS_BOTTOM (Default) Position the image to the bottom end of the field.

DLFVPOS_SCALEUP Scale the image vertically up to the height of the field.

DLFVPOS_SCALEDOWN Scale the image vertically down to the height of the field.

DLFVPOS_NODISTORT Scale the image to the field in both directions, maintaining the original aspect ratio of the image.


dlflasterror ()

Return Value: char *

Description This interface will return a text string which describes the last error to occur. The string will be a null pointer if no error has occurred.

Parameters

Return Value • char *text: string describing the last error to occur• null: if no error has occurred

Header dlflib.h

Related Interfaces dlflasterrornumber



dlflasterrornumber (unsigned long *dlfcode, unsigned long *apdflcode)

Return Value: void

Description This interface will return the identity of the last error encountered, as a numeric value. This value is composed of two pieces: the DL FormsAPI error code, local to this API, and, if present, the Adobe PDF Library error code which may be returned in some cases.

Parameters • unsigned long *dlfcode: DL FormsAPI error code, local to this API• unsigned long *apdflcode: APDFL error code, if present; 0 (zero) if not

Return Value void

Header dlflib.h

Related Interfaces dlflasterror



dlflistfieldnames (unsigned char *Name, fpos_t *Size)

Return Value: int

Description This interface will create a file as specified in dlfsetwritetype. If the file is to memory, Size is set to the maximum size that buffer can contain on input, and will contain the size actually used on return.This interface functions in a manner similar to that of dlflistfields, consist-ing of records demarcated by the system NewLine character(s), but writes only the name of a field on each line, without further information. Output will be written in either PDDocEncoding or UTF16 Host Endian Encoding, as selected by the interface dlfsetencoding. A non-zero return value indicates that a problem occurred and the file was not created

Parameters • unsigned char *Name: Name of file to contain the output listing• fpos_t *Size: Maximum size that buffer can contain on input; will contain

size actually used on return

Return Value int: A return code of zero indicates there were no problems in executing the function. A non-zero return value indicates that a problem occurred and the file was not created.

Header dlflib.h

Related Interfaces dlflistfields,dlflistfieldsandlocations,listFieldNamesToString (Java only),listFieldsToString (Java only)



dlflistfields (unsigned char *Name, fpos_t *Size)

Return Value: int

Description This interface will create a file as specified in dlfsetwritetype. If the file is to memory, Size is set to the maximum size that buffer can contain on input, and will contain the size actually used on return.The file will consist of records demarcated by the system NewLine character(s). Each record will consist of the name of a field in the acroforms directory of the current dictionary. Output will be written in either PDDocEncoding or UTF16 Host Endian Encoding, as selected by the interface dlfsetencoding. A non-zero return value indicates that a problem occurred and the file was not created.



Return Value int: A return code of zero indicates there were no problems in executing the function. A non-zero return value indicates that a problem occurred and the file was not created.

Header dlflib.h

Related Interfaces dlflistfieldnames,dlflistfieldsandlocations,listFieldNamesToString (Java only),listFieldsToString (Java only)



dlflistfieldsandlocations (unsigned char *Name, fpos_t *Size)

Return Value: int

Technical Notes

1 Each location should be in the format “(“, Page Number (zero relative), Lower Left Corner X

relative page lower left corner X, Lower Left Corner Y Relative Page Lower

left Corner Y, Width, Depth, and finally “)”. All coordinates and distances should be in points

and fractions of points.

Description This interface will create a file as specified in dlfsetwritetype. If the file is to memory, Size is set to the maximum size that buffer can contain on input, and will contain the size actually used on return.The file will consist of records demarcated by the system NewLine character(s). Each record will consist of the name of a field in the acroforms directory of the current dictionary, followed by one or more locations where this field is to be dis-played. See Technical Notes below for details on record layout.Output will be written in either PDDocEncoding or UTF16 Host Endian Encod-ing, as selected by the interface dlfsetencoding.A non-zero return value indicates that a problem occurred and the file was not created.




Header dlflib.h

Related Interfaces dlflistfieldnames,dlflistfields,listFieldNamesToString (Java only),listFieldsToString (Java only)



dlflockfield (unsigned char *Name)

Return Value: int

Description This interface will cause the named field to be locked. It will remain a field in the document, will display and print, but it cannot be modified by the document user.

Parameters unsigned char *Name: Name of the field to be locked


Header dlflib.h

Related Interfaces dlfdeletefield,dlfhidefield



dlfmergepages (unsigned char *Name, fpos_t *Size, int FirstPage, int LastPage, int BeforePage)

Return Value: int

Technical Notes

1 This interface behaves the same as dlfsaveappend, with the following differences:

• The output file must exist prior to calling this interface, and must be a PDF document with at least

one page.

• Only the portion of the current document between FirstPage and LastPage will be added to the

output document.

• The pages will be added preceding BeforePage, rather than at the end of the document.

2 All page numbers are specified as relative 1. The FirstPage number is required. The LastPage

number may be -1, indicating the end of the source document. The BeforePage number may be -1,

indicating the end of the receiving document. (In other words,

dlfmergepages("outdoc.pdf", 0, 1, -1, -1) is identical to

dlfsaveappend("outdoc.pdf", 0).)

Description This interface merges pages into an existing output document. It behaves the same as dlfsaveappend, but allows only a specified portion of the input doc-ument to be merged, and allows an output document page location to be given (i.e. pages may be inserted between two existing output pages,preceding the page indicated by BeforePage, rather than just at the end of the document).

Parameters • unsigned char *Name: Name of file to which pages will be added• fpos_t *Size: Maximum size that buffer can contain on input; will contain

size actually used on return• int FirstPage: first page of range to be merged in output file• int LastPage: last page of range to be merged in output file, or -1 for last

page of source document• int BeforePage: page of output file before which the new pages will be

added, or -1 to indicate end of receiving document

Return Value int:zero if successful; non-zero if action was not performed

Header dlflib.h

Related Interfaces dlfsave,dlfsavesome,dlfsaveappend



dlfmergePDFandFDF ()

Return Value: int

Description This interface will cause all values specified in the current FDF to be merged into the current PDF document. A non-zero return code indicate that this action was not done.

Parameters


Header dlflib.h

Related Interfaces dlfopenFDF,dlfopenPDF



dlfopenFDF (unsigned char *Name, fpos_t *Size)

Return Value: int

Description This interface opens the referenced Forms Data Format (FDF) file. It may or may not contain a valid reference to a PDF file with which it is associated. If it does not contain such a reference, or if the reference is not valid, or cannot be satisfied, then no PDF file will be opened. The current PDF file, if there is one open, will be closed. If a valid name is found, that file will be opened and will become the cur-rent PDF file.A non-zero return code indicates that the function did not complete correctly. In all cases, this also means that there is no current PDF or FDF document estab-lished. How a file is opened, and what parameters are meaningful, depends on the file open method specified in package initialization via dlfsetreadtype.

Parameters • unsigned char *Name: Name of FDF file to open• fpos_t *Size: Maximum size that buffer can contain on input; will contain



Header dlflib.h

Related Interfaces dlfmergePDFandFDF,dlfopenPDF



dlfopenPDF (unsigned char *Name, fpos_t *Size)

Return Value: int

Description This interface opens the referenced Portable Document Format (PDF) file. The package will allow only one single PDF file to be open at any time. If a second file is opened before the first is closed, the first will be automatically closed, without being written to output.

Parameters • unsigned char *Name: Name of PDF file to open• fpos_t *Size: Maximum size that buffer can contain on input; will contain



Header dlflib.h

Related Interfaces dlfmergePDFandFDF,dlfopenFDF



dlfprint ()Return Value: int

Description This interface will cause the current PDF document to be printed to the pre-speci-fied device. A single set of print parameters is used, modified by settable parame-ters which can be manipulated by various DL FormsAPI dlfprintset* interfaces. See the individual dlfprintset* interfaces in this Appendix, or “Printing” on page 4.17 for more information on using print set interfaces to configure your printer and your print output.

Parameters


Header dlflib.h

Related Interfaces dlfprintperuser



dlfprintperuser ()Return Value: int

Description This interface is available only on Windows. It will display the Windows print dia-log box, and will print the document according to the user-selected options. If the user chooses to cancel the print, this call will return a non-zero value. Any values selected via the dlfprintset* functions will be used as default values in the print dialog.

Parameters


Header dlflib.h

Related Interfaces dlfprint

Availability Windows platforms only


dlfprintsetbin (long BinNumber)

Return Value: int

Description This interface sets the source for paper in the current printer. The Printer Name must be set via dlfprintsetprintername before this interface is called. If the specified BinNumber is not valid for the specified device, an error will be returned.

Parameters long BinNumber: bin or tray number selection for the specified printer

Return Value int:zero if successful; non-zero if BinNumber value is not valid for the specified device

Header dlflib.h

Related Interfaces dlfprintsetcollate,dlfprintsetcopies,dlfprintsetduplex,dlfprintsetpages,dlfprintsetpapersize,dlfprintsetprintername,dlfprintsetprinttofile



dlfprintsetcollate (int Collate)

Return Value: int

Description This interface specifies whether multiple copies of a print job should be collated or merged. Default is merged.

Parameters int Collate: flag indicating whether collating is specified


Header dlflib.h

Related Interfaces dlfprintsetbin,dlfprintsetcopies,dlfprintsetduplex,dlfprintsetpages,dlfprintsetpapersize,dlfprintsetprintername,dlfprintsetprinttofile



dlfprintsetcopies (long NumberOfCopies)

Return Value: int

Description Sets the number of copies to be produced. Default is 1 copy.

Parameters long NumberOfCopies: Number of copies to be printed


Header dlflib.h

Related Interfaces dlfprintsetbin,dlfprintsetcollate,dlfprintsetduplex,dlfprintsetpages,dlfprintsetpapersize,dlfprintsetprintername,dlfprintsetprinttofile



dlfprintsetduplex (int DuplexMode)

Return Value: int

Description Sets the printer duplex mode. Default is No Duplex.

Parameters int DuplexMode: Flag indicating whether Duplex mode is specified. Default is No Duplex.


Header dlflib.h

Related Interfaces dlfprintsetbin,dlfprintsetcollate,dlfprintsetcopies,dlfprintsetpages,dlfprintsetpapersize,dlfprintsetprintername,dlfprintsetprinttofile



dlfprintsetpages (long Start, long End, int Append)

Return Value: int

Description This interface specifies the pages to be printed. Page numbers are 1-relative. Set-ting Start to 0 (zero) will start with first page. Setting End to 0 (zero) will end with last page. Default is All Pages. If the End page value is greater than the last page of the document, the last page will be used as the end page and no error will be returned.

Parameters • long Start: Starting page number, or 0 for First Page• long End: Ending page number, or 0 for Last Page• int Append: Add specified pages to current print job being defined


Header dlflib.h

Related Interfaces dlfprintsetbin,dlfprintsetcollate,dlfprintsetcopies,dlfprintsetduplex,dlfprintsetpapersize,dlfprintsetprintername,dlfprintsetprinttofile



dlfprintsetpapersize (long Width, long Depth)

Return Value: int

Description Sets the paper size to be used when printing.

Parameters • long Width: Width of paper to be used• long Depth: Depth of paper to be used


Header dlflib.h

Related Interfaces dlfprintsetbin,dlfprintsetcollate,dlfprintsetcopies,dlfprintsetduplex,dlfprintsetpages,dlfprintsetprintername,dlfprintsetprinttofile



dlfprintsetprintername (unsigned char *Name)

Return Value: int

Description Sets the name of the printer in Windows systems, and the name of the print queue in UNIX systems. If the specified name is not a valid printer or print queue, an error will be returned.

Parameters unsigned char *Name: Name of the printer on Windows systems or print queue on UNIX systems

Return Value int:zero if successful; non-zero if the specified name is not a valid printer or print queue

Header dlflib.h

Related Interfaces dlfprintsetbin,dlfprintsetcollate,dlfprintsetcopies,dlfprintsetduplex,dlfprintsetpages,dlfprintsetpapersize,dlfprintsetprinttofile

Availability Windows and UNIX systems


dlfprintsetprinttofile (unsigned char *Name, fpos_t *Size)

Return Value: int

Description This interface sets pages to be printed to a file rather than to a printer. File type is as set by dlfsetwritetype. If not a memory file, then Size is ignored. Call-ing this with Name as a NULL pointer will cancel any previous print-to-file setting. Default is no print to file.

Parameters • unsigned char *Name: Name of file to write, or NULL to cancel a previous setting

• fpos_t *Size: Size of memory file, if applicable


Header dlflib.h

Related Interfaces dlfprintsetbin,dlfprintsetcollate,dlfprintsetcopies,dlfprintsetduplex,dlfprintsetpages,dlfprintsetpapersize,dlfprintsetprintername



dlfremovepages (int FirstPage, int LastPage)

Return Value: int

Technical Notes

1 Page numbers are always relative, and hence change if pages are removed. If you want to remove pages

2-3, and 5, from a document, you should either remove 5 first (i.e. start from the far end and remove

as you go back), or subtract the number of pages removed preceding page 5 before removing what

used to be the fifth page itself (i.e. Remove pages 2 and 3, then page 3 again).

Description This interface will remove the specified pages, by relative page number, from the current document. Page numbers are specified base 1. (i.e. the first page is num-bered 1.) See Technical Notes below.

Parameters • int FirstPage: first page of range to remove, starting from 1• int LastPage: last page of range to remove, or -1 to remove all pages

through end of document


Header dlflib.h

Related Interfaces



dlfsave (unsigned char *Name, fpos_t *Size)

Return Value: int

Description Saves the current document as specified in dlfsetwritetype. If the file is to memory, Size is set to the maximum size that the buffer can contain on input, and will contain the size actually used on return. A non-zero return value indicates that the action was not performed.




Header dlflib.h

Related Interfaces dlfsavesome,dlfsaveappend,dlfmergepages



dlfsaveappend (unsigned char *Name, fpos_t *Size)

Return Value: int

Description Similar to dlfsave and operates in the same manner if the file specified in Name does not exist. If the file indicated by Name does exist, pages of the current document will be appended to the existing file, rather than overwriting the named file with a new copy. This is useful when concatenating a number of input documents into one output file. A non-zero return value indicates that the action was not performed.




Header dlflib.h

Related Interfaces dlfsave,dlfsavesome,dlfmergepages



dlfsavesome (unsigned char *Name, fpos_t *Size, int FirstPage, int LastPage)

Return Value: int

Description Similar to dlfsave, but saves a specified single range of pages of the current document, rather than the entire document. If the file is to memory, Size is set to the maximum size that the buffer can contain on input, and will contain the size actually used on return. A non-zero return value indicates that the action was not performed.


size actually used on return• int FirstPage: first page of range to save, starting from 1• int LastPage: last page of range to be merged in output file, or -1 for last

page of source document


Header dlflib.h

Related Interfaces dlfsave,dlfsaveappend,dlfmergepages



dlfsecurePDF(unsigned char *UserPassword, unsigned char *OwnerPassword,int Print, int Copy, int Edit, int EditNotes, int SaveAs, int LongKey)

Return Value: int

Description This interface will allow the user to specify that the PDF document written should be secured, and how it should be secured. A non-zero return code indicates that this action was not taken.

Parameters • unsigned char *UserPassword: Value for the optional User password to be applied to the document. This password, if defined, will be required before the document can be opened for viewing or for any other work by a user or process later on.

• unsigned char *OwnerPassword: Value for the optional Owner password to be applied to the document. This password, if defined, will be required before any Security changes can be made to the document by a user or process later on.

• int Print: Flag indicating whether printing of the document will be allowed• int Copy: Flag indicating whether the Copying and Extraction flag can be set

to allow copying of the file contents• int Edit: Flag indicating whether document text can be updated prior to

output of the file• int EditNotes: Flag indicating whether Note annotations can be

embedded in the output document • int SaveAs: Flag indicating whether SaveAs opernations will be permitted

in order to save the current document as a file of a different name• int LongKey: Specifies the Encryption key length for the document. If longKey is True, 128-byte encryption will be used in place of the default 32-byte encryption.

Return Value int: A return code of zero indicates there were no problems in executing the function. A non-zero return code indicates the function did not complete cor-rectly or the operation was otherwise not completed.

Header dlflib.h

Related Interfaces



Technical Notes

1 128-byte encrypted files cannot be read by versions of Adobe Acrobat or Adobe Reader older than

v5.x.

2 Early Beta releases of DL FormsAPI included int Read as the third calling argument, preceding int

Print. This has been deleted; User (Read) protection will be automatically applied whenever a

Userpassword value is defined. A user will need to enter the defined User password before the

document can be opened for viewing.


dlfsetasprinter (int True)

Return Value: int

Technical Notes

1 Many types of annotations are intended to be visible in screen displays but removed during printing,

such as certain button controls or text annotations ("sticky notes"). (e.g. When a button annotation is

defined in a document, two of the options for its Common Properties are "Visible but doesn’t print"

and "Hidden but printable.") Normally, the document will be flattened in the state that you would

view it on-screen, and thus annotations visible there will remain so after flattening. (i.e. Their viewing

properties carry forward into the flattened document.) In addition, annotations intended only for print

output will normally not be included in the flattened document, and thus they will not appear if the

flattened document is subsequently printed.

However, if this interface is called with a value of TRUE, the situation is reversed: the flattening process

will then include all printable annotations (those which are to be displayed on a printer) when

flattening the document, and exclude those which are not printable.

2 This setting takes effect for the duration of the program run or unless reset by another

dlfsetasprinter call. It applies not only to the currently-open file but also to all future files, until

its setting is cancelled or the program exits.

Description This interface sets a flag to indicate whether the document should be flattened with printable annotations included. Normal flattening operations will include annotations which are visible on-screen, but not show annotations intended to appear on printouts. This interface will reverse that setting. See Technical Notes below. Default is FALSE.

Parameters int True: Flag indicating whether flattened document will include annotations normally visible when printed


Header dlflib.h

Related Interfaces dlfflattenfield,dlfflattenPDF



dlfsetcompression (DLFCOMPRESSION Compression, int Linearize)

Return Value: int

Description Sets the compression that will be used on all later PDF document writes. The greater the level of compression or optimization used, the slower the write will be. This interface also allows selecting if the output file is to be linearized. In general, linearization takes longer, but results in a somewhat smaller document. A linear-ized document may be byte served.

Parameters • DLFCOMPRESSION Compression: Type of Compression to be applied to the output file, selected by an enumeration. See the table in Technical Notes below.

• int Linearize: Flag indicating whether output is to be linearized


Header dlflib.h

Related Interfaces



Technical Notes

Table A-7: dlfsetcompression Compression Options

DLFCOMPRESSION_DLFLEAVECOMPRESS

This will generate output with the same compression setting as the input, however it was configured.

DLFCOMPRESSION_DLFUNCOMPRESS

This will write the document completely uncompressed. This is the fast-est way to write a document, and guarantees it can be read by all read-ers. However, it will be significantly larger than needed.

DLFCOMPRESSION_DLFCOMPRESS (Default)

This will compress a document as much as possible using facilities avail-able prior to APDFL v1.6. The document is readable under any version of Reader or Acrobat. LZW compression will be avoided.

DLFCOMPRESSION_DLFOPTIMIZE

This will compress the document as in DLFCOMPRESSION_DLFCOMPRESS, but will also merge fonts and images that may be used multiple times. The largest case for using this is when documents are stitched together, and each document may use the same font or image. There is a fairly large time penalty for using this facility, as it requires intensive processing of the document content.

DLFCOMPRESSION_DLFMAXCOMPRESS

This will write the smallest possible form of the document. However, it can only be read using Acrobat or Adobe Reader 6 or greater (APDFL v1.6 or greater). This form may be the best for storing PDF, including storing forms for later processing. This will compress the document as in DLFCOMPRESSION_DLFMAXCOMPRESS, and will also do the optimiza-tion of fonts as images, as in DLFCOMPRESSION_DLFOPTIMIZE.

DLFCOMPRESSION_DLFMAXOPTIMIZE

This will compress the document as in DLFCOMPRESSION_DLFMAXCOMPRESS, and will also do the optimiza-tion of fonts as images, as in DLFCOMPRESSION_DLOPTIMIZE.


dlfsetdllpath (unsigned char *Name)

Return Value: int

Description This interface permits setting the path which is used to locate the DLL.

Parameters unsigned char *Name: fully-attributed path to the DLL location


Header dlflib.h

Related Interfaces



dlfsetencoding (DLFENCODING Encoding)

Return Value: int

Technical Notes

Table A-8: dlfsetencoding Encoding Options

Description This interface sets the encoding to be used by character strings in and out of the package.

Parameters DLFENCODING Encoding: Type of encoding to be applied to character strings; see Technical Notes below. BOM is not required for UTF16. The default value is DLFENCODING_DLFPDDOC.


Header dlflib.h

Related Interfaces


DLFENCODING_DLFPDDOC (Default)

Indicate that strings are in PDDOC or WinAnsiEncoding

DLFENCODING_DLFUTF16 Indicate that strings are in UCS2, encoded in UTF16 Host Endian


dlfsetfieldvalue (unsigned char *Name, unsigned char *Value)

Return Value: int

Description This interface sets the specified field’s current value to the given specified value. A non-zero return code indicates that the action was not done.

Parameters • unsigned char *Name: Name of field to update• unsigned char *Value: Value to be assigned to that field


Header dlflib.h

Related Interfaces dlffieldvalue



dlfsetPDF (void *PDDoc)

Return Value: int

Technical Notes

1 In multi-threaded applications using both DL FormsAPI and Adobe PDF Library, dlfgetPDF and

dlfsetPDF must be acting within the same thread. These pass documents back and forth between the

two products, not between threads.

Description This call will set the current PDDoc as DL FormsAPI's target PDDoc in applications that make use of both DL FormsAPI and Adobe PDF Library methods.The input declaration of the dlfsetPDF parameter is as void *, cast from the PDDoc to use. In this manner a user can pass documents back and forth between DL FormsAPI and Adobe PDF Library. See “Using DL FormsAPI within an Adobe PDF Library Application” on page 3.2 for more details

Parameters void *PDDoc: the document that is defined as the current DL FormsAPI target


Header dlflib.h

Related Interfaces dlfgetPDF



dlfsetreadtype (DLFIOType Type)

Return Value: int

Technical Notes

Table A-9: dlfsetreadtype DLFIOType Options

Description This interface selects how PDF and FDF files will be opened when the subsequent dlfopenFDF or dlfopenPDF command is issued. See Technical Notes below for details on opening enumeration values.

Parameters DLFIOType Type: Type of open operation to be used on the PDF or FDF file(s) to be processed. See Technical Notes below for details on opening enumeration values.


Header dlflib.h

Related Interfaces dlfopenFDF,dlfopenPDF


DLFIOType_FileSystem (Default)

The supplied pointer points to a null-terminated ASCII string which rep-resents a file name of a PDF or FDF file located on the local machine’s file system. The Size field of the open command is not used.

DLFIOType_InMemory The supplied pointer is to a block of unsigned characters which contain a representation of a PDF or FDF file. The Size field of the open com-mand is the extent of that file.

DLFIOType_URL The supplied pointer is to a null-terminated URL which describes a PDF or FDF file accessible via FILE:, HTTP:, HTTPS:, GOPHER: or FTP:. The service type must be included in the URL. The Size field of the open command is not used.


dlfsetwritetype (DLFIOType Type)

Return Value: int

Description This interface selects how PDF and informational files will be written. The attribute is one of the same enumerations used for dlfsetreadtype. Default value is DLFIOType_FileSystem

Parameters DLFIOType Type: Type of open operation to be used on the PDF or FDF file(s) to be processed. See Technical Notes under dlfsetreadtype for details on opening enumeration values.


Header dlflib.h

Related Interfaces dlfsetreadtype



dlfterm ()Return Value: int

Technical Notes

1 In a threaded environment, each thread must initiate and terminate the package.

Description This is called once to terminate the utility.

Parameters


Header dlflib.h

Related Interfaces dlfinit



dlfversion ()Return Value: unsigned long

Description Returns the version number of the utility in the form ((Version Major << 16) & Version Minor). This form is suitable for testing for compatibility.

Parameters

Return Value unsigned long dlfversion: Version Number of the utility in the form ((Version Major << 16) & Version Minor

Header dlflib.h

Related Interfaces



dlfversionstring ()Return Value: char *

Description Returns the version number as a string in Datalogics version and release format (e.g. 1.2P2a).

Parameters

Return Value char *: pointer to the retrieved text string

Header dlflib.h

Related Interfaces



listFieldNamesToString ()

Return Value: java.lang.String

(Java only)

Description This Java-specific interface functions in a manner similar to that of dlflist-fieldnames, but returns its results in memory as a list of strings containing the field names, as opposed to an output file containing the same data.This interface will return only the name of each field in the current document. The string will be either UTF16 or PDDOC encoding, according to the value set via the setEncoding interface.

Parameters

Return Value java.lang.String

Header

Related Interfaces dlflistfieldnames,dlflistfields,dlflistfieldsandlocations,listFieldsToString (Java only)



listFieldsToString ()

Return Value: java.lang.String

(Java only)

Description This Java-specific interface functions in a manner similar to that of dlflist-fields, but returns its results in memory as a list of strings containing the field data, as opposed to an output file containing the same data.This interface will return the fully-qualified name of each field in the current docu-ment. The string will be either UTF16 or PDDOC encoding, according to the value set via the setEncoding interface.

Parameters

Return Value java.lang.String

Header

Related Interfaces dlflistfieldnames,dlflistfields,dlflistfieldsandlocations,listFieldNamesToString (Java only)


Index

A

AdobeAcrobat 1.3PDF Library

Error codes returned from 4.4, A.15Use within DL FormsAPI 1.2

Reader 1.3Adobe PDF Library

Version Compatibility with 1.5

C

CautionsOpening second file will automatically close first

one without writing output 4.7Compilers, Supported 2.2Conventions, Document 1.3

D

Datalogics Interface (DLI)Use within DL FormsAPI 1.2

Datalogics website 1.2DL FormsAPI

How to Use this Book 1.2Installation

UNIX 2.3Windows 2.9

Intended Audience 1.2Introduction 1.2, 3.2Use in Multithreaded Applications 1.8What You Should Know 1.2What’s New in Previous Releases 1.6What’s New in This Release 1.4

dlfaddresourcepath 1.7, 4.4, A.2dlfclosePDF 4.8, A.3DLFCOMPRESSION 4.5, A.41

Compression Options 4.5, A.42dlfdeletefield 4.12, A.4dlffieldvalue 4.9, A.5dlfflattenfield 4.11, A.6dlfflattenPDF 4.11, A.7dlfgetPDF 1.6, 1.7, 3.3, 4.7, A.8dlfhasacroforms 4.9, A.9dlfhidefield 4.12, A.10dlfinit 3.3, 4.3, A.11

preceding with dladdresourcepath calls 4.4use with dlfaddresourcepath 4.4, A.2use within an Adobe PDF Library application 3.3

dlfinsertimage 1.4, 4.13, A.12

dlflasterror 4.3, A.14dlflasterrornumber 4.4, A.15dlflistfieldnames 1.7, 4.9, A.16dlflistfields 4.9, A.17dlflistfieldsandlocations 4.10, A.18dlflockfield 4.12, A.19dlfmergepages 4.16, A.20

comparison with dlfsaveappend 4.16, A.20dlfmergePDFandFDF 4.11, A.21dlfopenFDF 4.7, A.22dlfopenPDF 4.7, A.23dlfprint 4.17, A.24dlfprintperuser 4.17, A.25dlfprintsetbin 4.18, A.26dlfprintsetcollate 4.18, A.27dlfprintsetcopies 4.18, A.28dlfprintsetduplex 4.18, A.29dlfprintsetpages 4.18, A.30dlfprintsetpapersize 4.18, A.31dlfprintsetprintername 4.18, A.32dlfprintsetprinttofile 4.18, A.33dlfremovepages 4.12, A.34dlfsave 4.15, A.35

comparison with dlfsaveappend 4.15comparison with dlfsavesome 4.15

dlfsaveappend 4.15, A.36comparison with dlfmergepages 4.16, A.20

dlfsavesome 4.15, A.37dlfsecurePDF 1.8, 4.15, A.38dlfsetasprinter 1.7, 4.6, 4.11, 4.12, 4.17, A.40dlfsetcompression 4.5, A.41dlfsetdllpath 1.7, 4.3, A.43dlfsetencoding 4.2, 4.6, A.44

encoding options A.44use with dlflistfieldnames 4.10use with dlflistfields 4.9, A.17use with dlflistfieldsandlocations 4.10, A.18

dlfsetfieldvalue 4.11, A.45dlfsetPDF 1.6, 1.7, 3.3, 4.8, A.46dlfsetreadtype 4.4, A.47

open options 4.4, A.47use with dlfinsertimage 4.13, A.12

dlfsetwritetype 4.5, A.48effect on dlfprintsetprinttofile 4.18, A.33effect on dlfsave 4.15, A.35use with dlflistfieldnames 4.9use with dlflistfields 4.9, A.16, A.17use with dlflistfieldsandlocations 4.10, A.18

dlfterm 4.3, A.49dlfversion 4.3, A.50dlfversionstring 4.3, A.51dlpdfinit 3.3Document Conventions 1.3

I . i i D L F o r m s A P I U s e r G u i d e

E

Error Handlingexceptions from APDFL 3.4model 3.4PDF/FDF parsing 3.4returned error text string 4.3, A.14returned last error number 4.4, A.15

F

Font Resources 3.4

G

gunzip 2.3, 2.4

I

InstallationProcedures

UNIX 2.3Supported Platforms and Compilers 2.2

Introduction to DL FormsAPI 3.2Use within an Adobe PDF Library application 3.2

L

listFieldNamesToString 1.4, 4.10, A.52listFieldsToString 1.4, 4.9, 4.11, A.53

N

New Interfacesv0.01B1m

dlflistfieldnames 1.7dlfsetdllpath 1.7

v1.0dlfgetPDF 1.7dlfsetasprinter 1.7dlfsetPDF 1.7

v1.1P1klistFieldNamesToString 1.4listFieldsToString 1.4

Notes128-byte encrypted files cannot be read by pre-

v5.x Acrobat or Reader 4.15dlfclose interface does not save the current

document 4.8dlfgetPDF and dlfsetPDF must act within the

same thread 3.3, 4.7, 4.8dlfsetasprinter setting can affect printed output

annotations 4.12, 4.17Installation screen illustrations show

v6.1.0Plus 2.3Not all folders contain files at installation

time 2.5Page numbers always relative 4.12Release package contents may vary 2.9

P

PDFLInit 3.3Platforms, Supported 2.2

R

ReadMe.txt 1.4readme.txt 1.4

S

Sun SolarisSupported Versions 2.2

T

tar/un-tar 2.3, 2.5

U

Updated Interfacesv0.01B1f

dlfsecurePDF 1.8v1.0

dlfaddresourcepath 1.7v1.1P1k

dlfinsertimage 1.4User API Calls

Control Interfacesdlfaddresourcepath 4.4dlfinit 4.3dlflasterror 4.3dlflasterrornumber 4.4dlfsetasprinter 4.6, A.40dlfsetcompression 4.5

Compression Options 4.5, A.42dlfsetdllpath 4.3dlfsetencoding 4.6dlfsetreadtype 4.4, 4.5dlfsetwritetype 4.5dlfterm 4.3dlfversion 4.3dlfversionstring 4.3

I n d e x I . i i i

Data Modificationdlfdeletefield 4.12dlfflattenfield 4.11dlfflattenPDF 4.11dlfhidefield 4.12dlfinsertimage

Horizontal Positioning Options 4.13, 4.14, A.12, A.13

dlflockfield 4.12dlfmergePDFandFDF 4.11dlfremovepages 4.12dlfsetfieldvalue 4.11Note on dlfsetasprinter effects 4.12

Document Creationdlfmergepages 4.16dlfsave 4.15dlfsaveappend 4.15, 4.16dlfsavesome 4.15dlfsecurePDF 4.15

File HandlingdlfclosePDF 4.8dlfgetPDF 4.7dlfopenFDF 4.7, 4.8dlfopenPDF 4.7, 4.8dlfsetPDF 4.8dlfsetreadtype 4.7, A.22dlfTerm 4.8

File Informationdlffieldvalue 4.9dlfhasacroforms 4.9dlflistfieldnames 4.9dlflistfields 4.9dlflistfieldsandlocations 4.10Java-Specific Interfaces

listFieldNamesToString 4.10listFieldsToString 4.11

Image Handlingdlfinsertimage 4.13Unscaled images 4.13

Printingdlfprint 4.17dlfprintperuser 4.17dlfprintsetbin 4.18dlfprintsetcollate 4.18dlfprintsetcopies 4.18dlfprintsetduplex 4.18dlfprintsetpages 4.18dlfprintsetpapersize 4.18dlfprintsetprintername 4.18dlfprintsetprinttofile 4.18Note on dlfsetasprinter effects 4.17

W

What’s New in Previous Releasesv0.01B1f

Now thread-safe 1.8Updated Interfaces

dlfsecurePDF 1.8v0.01B1m

New Interfacesdlflistfieldnames 1.7dlfsetdllpath 1.7

v1.0P1eEmbedded Linefeeds Now Honored 1.6First Production Release 1.6New Interfaces

dlfgetPDF 1.7dlfsetasprinter 1.7dlfsetPDF 1.7

Updated Interfacesdlfaddresourcepath 1.7

v1.1P1dDL FormsAPI now built on Adobe PDF Library

v7 1.6dlfgetPDF and dlfsetPDF now documented

calls 1.6What’s New in This Release 1.4

Available for either APDFL v6 or v7 1.5New Interfaces

listFieldNamesToString 1.4listFieldsToString 1.4

Now available on Solaris 1.5Overview 1.4Updated Interfaces

dlfinsertimage 1.4Windows (Intel)

Supported Versions 2.2Workflow 3.3

DL FormsAPI User Guide - Datalogics1.2 DL FormsAPI User Guide An Introduction to DL FormsAPI...

Documents

Transcript of DL FormsAPI User Guide - Datalogics1.2 DL FormsAPI User Guide An Introduction to DL FormsAPI...