Page 1/4

Read Me - Enfocus PitStop Server 10 Copyright 2010 Enfocus NV all rights reserved Abstract
Enfocus PitStop Server is a hot folder based application that allows automatic preflight and correction of PDF documents.

Table of Contents

New Features Product Upgrade Info System Requirements Product Key & Activation Known Issues Version History Contact Information & Product Feedback Legal Notices

New Features

A brief overview of the new features in PitStop Server 10 is listed below. Transparency flattening Optimize PDF for file size Better color handling A complete feature overview is listed in the version history.

Product Upgrade Info

PitStop Server 10 is a paying upgrade for users that have PitStop Server 09 or an older version. An upgrade path from earlier Enfocus PitStop Server versions is available to registered users on our website at http://www.enfocus.com. Special note for existing Enfocus PitStop Server users Installing PitStop Server 10 will preserve your existing preferences and color repository. If needed, Preflight Profiles and Action Lists will be converted to the correct PitStop Server structure.

System Requirements

For the system requirements, please see: http://www.enfocus.com/product.php?id=861&page=SR
Product Key & Activation
After installing the software, you will have the possibility to start a 30-day fully functional trial period. Therefore you will be asked to step through a wizard in order to start your trial. Afterwards, the product will only run when activated, thus requiring a Product Key. You can find this 30-character Product Key (e.g. ABC5EF-GH2JKL-M45P9R-ST22WX-YZ5234) in the DVD case, together with the e-mail providing the link to download the electronic version

Page 2/4

Known Issues
For known issues, please see the Enfocus Knowledge Base: http://www.enfocus.com/support/knowledgebase

Version History

Update Information For seeing a detailed overview of the new features or fixes in updates, please see the Enfocus Knowledge Base: http://www.enfocus.com/support/knowledgebase Enfocus PitStop Server 10 Transparency flattening Transparency flattening to ensure a predictable output. Although the latest print engines can flatten transparency well, earlier generations that are still widely spread cannot always handle transparency reliably. When outputting on different devices the result may differ. Optimize PDF for file size An action list is added to reduce the size of a PDF to optimize it for the web of for archiving. Removing invisible images out of the trim or crop box and down sampling high resolution images are actions that are done to reach this goal. Better color handling Check and inspect ink coverage the right way, taking transparency, overprint and layers into account. Use Black point compensation with Little CMS or Adobe CMM
Enfocus PitStop Server 9 Processing speed Taking full advantage of multiple processor or multiple-core systems and the new predictive Action List Engine makes PitStop Server 09 faster than ever before. Real background processing on Mac. On the Mac, PitStop Server 09 is capable of behaving as a true background process, which makes it suitable for use on a Mac XServe system in a true server configuration. Better integration with the command-line application. To integrate PitStop Server 09 in a larger context, PitStop Server now comes with a command-line interface.
Enfocus PitStop Server 08 Technology Runs as a startup item on Mac OS X, service on Windows. Supports Mac OS X 10.5 (Leopard) and Microsoft Windows Vista (all flavors). Simultaneous processing of up to 2 PDF files (on multi-processor machines). Watchdog application makes sure PitStop Server is running at all times. Improved reporting to end-users (on preflighting errors etc.) and to administrators (on application problems). Detailed logging information can be retained by PitStop Server, and exported as a text or XML file for further analysis.

Page 3/4

Color management now supports a choice of three different color management engines (Little CMS, Adobe CMS and the operating system color management engine). Support for the new PDF/X-4 standard and the latest specifications (1v4) of the Ghent PDF Workgroup (www.gwg.org). Full compatibility with PitStop Professional 08 PDF Profiles and Action Lists. User Experience New and more intuitive user interface makes major features readily available. Reworked documentation makes key information easier to find. Contextual (right-click) menus make frequently used tasks available after one click. Hot Folders PitStop Server can now process complete folders and maintain folder hierarchies during processing. File renaming options make it easier to keep track or organize processed files. Variables make renaming files easy. Hot folders can be locked so that their critical settings cannot be altered without permission. Import and export of hot folders makes it easy to move workflows to different servers. The free 08 updates fix or enhance functionality in several areas, for example improvements for GWG compliancy (08, update 5)

Contact Information

Enfocus welcomes and values all problem reports, ideas and suggestions. If you have the choice we prefer electronic mail to other media. Feel free to send us (preferably small) sample files as email attachments. Use Get Support from the PitStop Server Help menu or http://www.enfocus.com/support to report a problem or request a feature. E-mail: support@enfocus.com Web: http://www.enfocus.com International Contact Information Enfocus Kortrijksesteenweg Gent Belgium T: +11 F: +12 North America Contact Information Enfocus Inc. 8535 Gander Creek Drive Miamisburg, OH 45342 USA T : +F : +454 1702

Page 4/4

Limited Warranty
This software is provided "as is" and without warranty, express and implied, including but not limited to any implied warranties of merchantability and fitness for a particular purpose. In no event will Enfocus NV be liable for any damages, including lost profits, lost savings, or other incidental or consequential damages, even if Enfocus NV is advised of the possibility of such damages, or for any claim by you or any third party. 2009 Enfocus NV all rights reserved. Enfocus is an EskoArtwork company. Certified PDF is a registered trademark of Enfocus NV; patent pending. Enfocus PitStop Pro, Enfocus PitStop Server, Enfocus PitStop Connect, Enfocus Instant PDF, Enfocus StatusCheck, Enfocus CertifiedPDF.net, Enfocus Instant Barcode, Enfocus PitStop Extreme, Enfocus PDF Workflow Suite, Enfocus LightSwitch, Enfocus FullSwitch, Enfocus PowerSwitch, Enfocus SwitchClient and Enfocus SwitchScripter are product names of Enfocus NV. Acrobat, Distiller, InDesign, Illustrator, Photoshop, FrameMaker, PDFWriter, PageMaker, the Adobe logo, the Acrobat logo and PostScript are trademarks of Adobe Systems Incorporated. Macintosh, Mac, Mac OS and ColorSync are trademarks of Apple Computer, Inc., registered in the U.S. and other countries. Windows, Windows 2000, Windows XP and Windows Vista are registered trademarks of Microsoft Corporation. PANTONE Colors displayed here may not match PANTONE-identified standards. Consult current PANTONE Color Publications for accurate color. PANTONE and other Pantone, Inc. trademarks are the property of Pantone, Inc. Pantone, Inc., 2006. OPI is a trademark of Aldus Corporation. Quark, QuarkXPress, QuarkXTensions, XTensions and the XTensions logo among others, are trademarks of Quark, Inc. and all applicable affiliated companies, Reg. U.S. Pat. & Tm. Off. and in many other countries. This product and use of this product is under license from Markzware under U.S.Patent No. 5,963,641. Other brand and product names may be trademarks or registered trademarks of their respective holders. All specifications, terms and descriptions of products and services are subject to change without notice or recourse.

Certied PDF is a trademark of Artwork Systems; patent pending. Enfocus PitStop Professional, Enfocus PitStop Server, and Enfocus Instant PDF are product names of Artwork Systems. PDF, Acrobat and PostScript are trademarks of Adobe System Incorporated. Mac OS is a trademark of Apple Computer Incorporated. Windows and Windows NT are registered trademarks of Microsoft Corporation. Other names might be trademarks or registered trademarks in certain jurdisdictions.
Copyright 1996-2007, Artwork Systems. All rights reserved.
3.2.2 Purpose of this document
If you have never worked with the Enfocus PitStop Server SDK (SDK = Software Development Kit) this is the right document for you. It will introduce you to the concepts, explain what is possible and what not and guide you towards making a simple solution using Enfocus PitStop Library.
Keep in mind that this document provides an overview of the Enfocus PitStop Server SDK and of programming with the Enfocus PitStop Library API (API = Application Programming Interface). You will not nd detailed information on all calls or declarations in the Enfocus PitStop Library API; those are in a separate document called "Enfocus PitStop Library API".
3.2.3 Prerequisite Knowledge
You should have decent working knowledge of the programming language C as the Enfocus PitStop Library API has an ANSI C interface. It is further assumed that the reader is familiar with Enfocus PitStop Server and understands the concepts of PDF Proles, Action Lists, Certied PDF and preighting.
3.2.4 Structure of this document
This is a short summary of the chapters in this document and their purpose:
PitStop Library Page Documentation Requirements An overview of the system requirements of PitStop Library and the Enfocus PitStop Server SDK. Using PitStop Library in your Solution Restrictions on how you can use Enfocus PitStop Library API, and information on how to deploy it. Typical PitStop Library Lifecycle Information on the basic approach to using PitStop Library in your solution. This chapter gives no program code, but an overview of the order in which to do things and the necessary calls involved in a typical implementation. Getting Started: the Template Application An overview of the Template project, designed to be a very basic implementation of the Enfocus PitStop Library API. Enfocus PitStop Server SDK FAQ Typical errors made when you start using the Enfocus PitStop Library API (and their solutions!). Where to go from here. Pointers to more documentation when this document is not enough to gure things out.

Initialization is the time when you pass important information to PitStop Library. This includes: Your private handshake routine. Enfocus PitStop Server SDK uses this to identify your application and to determine the functionality that is available to you. Information on the solution you are using PitStop Library in. This information is used in various places such as the Certied PDF Edit Log and preight reports. Information on directories you want to use for temporary les, extra directories where fonts are located and various resource directories the library uses.
Full information on what the different structures are you need to pass during PitStop Library initialization, is in the Enfocus PitStop Library API documentation.
Initialization is also a good time to setup the progress callback the PitStop Library uses to report what it is doing while processing les. You need to do this only once by calling EPL_RegisterProgressCallback().
3.3.3 Setting up for Processing

3.3.3.1 Congurations

New in Enfocus PitStop Server SDK is the concept of congurations. Congurations allow for fast switching between different sets of values used for processing. Even if your application doesnt need fast switching, you will always need at least one conguration before you can process PDF les. Therefore, one of the rst things you will probably do after initializing, is creating a new conguration with the EPL_CreateConguration() call. 3.3.3.2 EPL_Settings
Once you have a conguration, you need to set all the relevant settings for processing. This is done through the calls in the EPL_Settings.h header le: EPL_SetBoolToSetting() to set boolean values,
3.3 Typical PitStop Library Lifecycle
EPL_SetLongToSetting() to set enum and long values, EPL_SetStringToSetting() to set strings, and EPL_SetFilePathToSetting() to set lepaths. The only other call that changes settings on a conguration is EPL_CongureColorManagement(), which sets all color management settings. 3.3.3.3 Action Lists and PDF Proles
Before you start processing you have to specify which Action Lists and PDF Prole you want to use, if any. PitStop Library supports processing with the following combinations of Action Lists and PDF Proles: One or more Action Lists One PDF Prole One or more Action Lists and a PDF Prole. In this case the Action Lists are processed before the les are preighted using the PDF Prole.
Once you setup Action Lists or a PDF Prole with the calls specied below, they remain into effect over calls to EPL_Process(). This means you have to call these functions only when you want to change the Action Lists or PDF Prole you are using. If you have to switch between different sets of PDF Proles and/or Action Lists, you can use congurations as noted above. 3.3.3.4 Specifying Action Lists
If no Action Lists are required while processing les, call the EPL_SetLongToSetting() function with eEPL_Mutator_Int_SetMutatorNone as enum type and eEPS_DocumentActionList as value. If you do want Action Lists while processing les call the EPL_SetFilePathToSetting() function with enum type eEPL_Mutator_FilePath_SetMutator and the path to the Action List. Some extra considerations: If you want more than one Action List to be processed, call the EPL_SetFilePathToSetting() function more than once. The Action Lists will be processed in the same order in which you set them up. Keep in mind that the order in which Action Lists are processed might be important and the result may differ depending on the order. If you want to replace the Action Lists rst use the eEPL_Mutator_Int_SetMutatorNone setting, and then set up the new Action Lists with EPL_SetFilePathToSetting(). It is important to realize that a selection that exists at the end of one Action List, remains in effect at the start of the following Action List. If you do not want that, you should begin your Action Lists with a "Select All" action. You can specify an Action List from an Action List database by using iterators. With EPL_StartIteratorMutator() and EPL_NextIterator() you can iterate through a database. When you have found the action list you want, use EPL_GetIteratorPath() to get its path and EPL_SetFilePathToSetting() to select it. 3.3.3.5 Specifying a PDF Prole

EPL_Finalize() should be the last function you call, after this no other PitStop Library functions may be called. This call releases all resources, both memory and les, used by PitStop Library. If for some reason you do not call EPL_Finalize(), the only adverse effect will be that some temporary les might not be cleaned up. These les will be automatically removed the next time you start PitStop Library.
Enfocus PitStop Server SDK FAQ
This chapter contains a number of issues that we frequently come across when explaining how to use PitStop Library. If there is only one chapter you read in this whole document, it should be this one!
3.4.1 Initialize/Finalize

3.4.1.1 Handshake

What is this handshake you keep talking about?
The handshake is basically a piece of code that you must include in your application so that PitStop Library can uniquely identify your application and determine which functions you are allowed to use. Without a handshake, you will not be able to initialize PitStop Library.
Where can I get a handshake?
To obtain a handshake please contact Enfocus Integrator Support (integrator@enfocus.com).
How do I use the handshake?
The handshake consists of 3 source les: 2 headers and 1 c le. You must include the headers in your include path, and compile and link against the c le. In your own code, you must create an EPS_PrivateStruct, pass that struct to the private function to ll out the required data, and pass the struct to the EPL_Initialize() function. The name of the private function depends on your company name.

Example code:

EPS_PrivateStruct thePrivateStruct; EPS_OEM_EnfocusTest_Private( &thePrivateStruct ); EPL_InitializeInfoStruct theInitStruct;. theInitStruct.mPrivate = &thePrivateStruct; EPL_Initialize( &thePrivateStruct );
3.4.2 Passing information to and from PitStop Library

3.4.2.1 Structs

Whats up with all those structs?
Almost all PitStop Library functions take a struct as parameter. Before passing one of these structs to a PitStop Library call, there are 2 things you must remember to do: memset the struct to 0, and ll out the struct size. This is to ensure compatibility between different (minor) versions of PitStop Library.
3.4 Enfocus PitStop Server SDK FAQ 3.4.2.2 Encodings
What encoding should I use? In order to support a variety of languages, PitStop Library is fully Unicode compliant. We did however not want to put the burden of being Unicode compliant on Integrators and as such all functions which get a string from or specify a string to the PitStop Library accept different encodings: eEPS_EncodingCode_ASCII: should only be used when you are certain your string will contain only 7-bit ASCII characters. In general use of this option for anything but the simplest strings is strongly discouraged. eEPS_EncodingCode_Platform: this encoding is always the same as the system encoding on which the PitStop Library is running. For a western Windows computer this will usually be WinAnsi, for a Macintosh MacRoman encoding, for a Japanese system Shift-Jis. Keep in mind that these encodings might not support all characters, for example dont try to request Japanese error strings from the PitStop Library in Platform encoding unless you are absolutely certain your application will only run on Japanese operating systems. eEPS_EncodingCode_UTF8: this encoding is UTF-8 Unicode. Unicode markers at the beginning of the string must not be used; the PitStop Library always assumes the byte ordering is that of the platform on which it is running. eEPS_EncodingCode_UTF16: this encoding is UTF-16 Unicode. Unicode markers at the beginning of the string must not be used; the PitStop Library always assumes the byte ordering is that of the platform it is running on. 3.4.2.3 Memory Allocation

How should I handle memory allocation when passing information to PitStop Library? In a lot of functions you have to pass information to PitStop Library, usually as structures and strings. In all these cases you are responsible for memory allocation and, once the function returns, deallocation of that memory. In no case will the PitStop Library take over memory allocation and de-allocate it itself. In environments where such differences exist, PitStop Library assumes that the memory passed to it, is xed and non-moveable; i.e. it is expected that memory will not be purged or re-allocated by the operating system during the call. It is your responsibility to make sure this is a valid assumption. How does memory allocation work when getting information from PitStop Library? In a number of functions PitStop Library has to pass information to you and the size of that information is not previously known. Functions that pass such information to the application use two variables to allow the PitStop Library: a pointer pointing to a memory buffer and an integer dening the size of that memory buffer. Theses two variables have to be set up before you call the function and you must allocate the memory pointed to before the call. Once the function returns you are responsible to de-allocate the memory.
This raises the common problem that you often wont know how big the buffer is that you need to allocate; normally PitStop Library calculates the exact size needed in the same function. This problem can be dealt with in two ways:
PitStop Library Page Documentation The buffer can be bigger than what is actually needed; if you can make a reasonable assumption for the size of the information returned you could allocate a buffer that will always be big enough. If the buffer is not big enough, PitStop Library will return an error and the buffer contents is undened. You can call the function in question with the buffer pointer variable set to null and the buffer size variable set to zero. If you do so the function will ll the size variable with the exact size that is needed. This allows you to subsequently allocate the correct buffer and call the function again with a correct buffer and size.
Whatever solution you choose, allocating and de-allocating memory always remain your responsibility.

3.4.2.4

Strings
What string terminators does PitStop Library use?

Getting strings from the PitStop Library poses extra problems regarding the zero terminator. These are the rules used by PitStop Library for strings: The buffer size returned by PitStop Library never includes room for the zero terminator. When returning strings PitStop Library never includes the zero terminator.
This means that if you want to zero terminate strings you are responsible to do so. Depending on the encoding you use you will have to allocate one or two bytes more than the value returned by PitStop Library and add one or two zeroes to the end of the string returned by PitStop Library.

3.4.3 Settings

3.4.3.1 Languages
What are the supported languages?
PitStop Library supports multiple languages. The base language is (US) English; this language is always available. Currently PitStop Library supports ve extra languages through the use of language les. These language les need to be present in the "Resources\lng" folder next to the PitStop Library le in order to be used or alternatively you can specify a different path to the language les during initialization of the library.
The languages that are currently supported are: French Spanish German Italian Japanese
3.4 Enfocus PitStop Server SDK FAQ I see a GetLanguage function, but no SetLanguage. How do I change the language?
All settings, including languages, are set using the calls in the EPL_Settings header. For languages, you want the call EPL_SetStringToSetting(). The arguments are: A conguration handle. The type of setting you wish to change. In this case: eEPL_Language_String_Language. A pointer to an EPS_StringStruct containing the language code. Currently supported language codes are: enUS, frFR, esES, deDE, itIT, jaJA. 3.4.3.2 Changing Settings
I cant nd an EPL_SetX() function Every setting that can be set on a conguration is set using one of 4 functions: EPL_SetBoolToSetting(), EPL_SetLongToSetting(), EPL_SetStringToSetting() and EPL_SetFilePathToSetting(). These functions all have a similar signature: they take a conguration handle, a setting type, and a value. So they are used to set a specic setting (the setting type) to a specic value, for a specic conguration. The list of setting types can be found in the API documentation. You will notice that all setting types have similar names: they all start with eEPL_ followed by the category, the type of setting (Bool, Int, String or FilePath), and nally the actual setting name. Thus for example eEPL_Main_Int_Unit is used to set the Unit, which is an Int (or long), and belongs to the category Main. There is no separate call to set enum values, those are set using EPL_SetLongToSetting(). Why cant I set eEPL_Certify_Bool_CertWFChangeProle using EPL_SetLongToSetting()? For type safety reasons, there are separate functions for setting a long/enum or a boolean value. Although PitStop Library uses enums to denote boolean values (eEPS_True and eEPS_False), you cannot use EPL_SetLongToSetting() to set these values. 3.4.3.3 Handles

What are handles? When working with a number of functions in the library, handles are used. A handle is an opaque variable that is returned to you by the PitStop Library as the result of a function call and that you can use later to identify a resource (such as for example a report document) you want to work with. When you create a handle (for example through the EPL_CreatePdfHandle() or EPL_CreateConguration() calls) you should rst create a pointer of the correct type (for example EPL_DocumentPdfPtr for PDF documents), initialize it to 0, and pass its address in the create call. On return, the handle can be stored in a handle type variable (for example EPL_DocumentPdfHandle). Handles are unique in one run of PitStop Library but should not be stored across different runs of the PitStop Library. You should not try to de-allocate handles nor assume anything about their actual contents as this will surely break your solution when PitStop Library is upgraded.

18 3.4.3.4 Congurations

So what are these congurations anyway?
A conguration is a collection of settings for PitStop Library. The idea is to allow fast switching between congurations. Congurations contain settings for the language, mutators, Certied workow settings, fonts, etc.
A typical example for the use of congurations is a hotfolder-based application: every hotfolder could have its own conguration with a PDF Prole and specic settings, and the application can quickly switch between the different hotfolders, without having to change all the settings on PitStop Library. What if I dont want to use congurations?
Although PitStop Library requires a conguration before it can process or work with reports, the impact this has on applications that dont wish to use congurations is minimal. It is sufcient to create a conguration handle, set this conguration as active, and then pass the conguration to all set calls. Remember to close the conguration before nalizing PitStop Library! Do I have to set the active conguration after each set call to make the setting persistent?
No. All functions that change a setting for a conguration can be used on the active conguration, without a need to call EPL_SetAsCurrentConguration() again.
3.4.4 The Enfocus PitStop PDF Prole and Action List Library

3.4.4.1 Mutators

What are mutators? Mutator is the name used in Enfocus PitStop Server SDK for both PDF Proles and Action Lists. Likewise, the Enfocus PitStop PDF Prole and Action List Library is often referred to as the Mutator Library or Mutator Editor Library.
The term mutator is never used in documentation for the end user - there we will always talk about PDF Proles and Action Lists, and we strongly encourage you to do the same. Internally however, the word mutator is used to mean either PDF Proles or Action Lists, or both. After all, Mutator Library sounds a lot more friendly than Enfocus PDF Prole and Action List Library, dont you think? 3.4.4.2 Mutator Library vs Processing Library

Whats that about a Processing Library?
Enfocus PitStop Server SDK consists of 2 libraries, ofcially called Enfocus PitStop Library and Enfocus PitStop PDF Prole and Action List Library. The former is more often referred to as just
3.4 Enfocus PitStop Server SDK FAQ
PitStop Library, and the latter as the Mutator Library (see above). Often, this documentation will talk about PitStop Library when in fact the information is valid for both PitStop Library and the Mutator Library. In some contexts however, it is important to stress the difference between PitStop Library and the Mutator Library. In those cases, PitStop Library is sometimes called the Processing Library, because its main purpose is to process PDF les. This in contrast to the Mutator Library, whose main purpose is to select and/or edit mutators.
Does that mean I need the Mutator Library to set the PDF Prole for processing?
No, simple selection of mutators can be done in PitStop Library by using lepaths or iterators. You only need the Mutator Library if you want to edit mutators, or use the Enfocus graphical UI for mutator selection. If your users dont need to select mutators, or if your application has its own UI for that, you dont need the Mutator Library. Also note that if you dont use the Mutator Library, there is no need to include it in your applications installer.
Can I pass handles from one library to the other?
No, handles are valid only for the library where they were created.
Which functions/structs/enums/headers are for the Mutator Library?
You can easily determine to which library a function, struct, enum or header belongs by looking at the prex: EPL_ is used for those items specic to PitStop Library, EPM_ is for the Mutator Library, and EPS_ for those items that are used by both. For example lepaths are used in both libraries, so the struct dening a lepath is called EPS_tagFilePath. Likewise, EPL_Initialize() is the initialization function for PitStop Library, and EPM_Initialize() initializes the Mutator Library. Both use the same handshake, so that is declared in EPS_Handshake.h

3.4.5 Error Handling

3.4.5.1 PitStop Library Error Handling
How does PitStop Library handle errors and exceptions?

Even though the external interface of PitStop Library is purely C, internally we use C++ and use C++ exceptions to handle error conditions. In release builds these exceptions are never allowed to be propagated outside of PitStop Library code; you will always receive error codes from the respective function calls instead of exceptions.
All PitStop Library functions return a result of type enum EPS_ErrorCodes. This return value will either be eEPS_NoError if the function executed successfully, or one of the error codes dened in the EPS_Errors.h header le. When checking return codes, please use the enums dened in this header le and not literal values. For example, do not assume that eEPS_NoError will always be zero (as it happens to be now).
20 Can I get a human readable error description?
If something goes wrong in a function and the function returns an error, you can get a descriptive text for the error by calling the EPL_GetErrorString() function. This function can be used even if the PitStop Library was not initialized.
English error strings are always returned, and you can use the international parameters to request error strings in other languages, when available. If the PitStop Library has not yet been initialized international strings may not be available. 3.4.5.2 Error Codes
Why am I getting eEPS_ErrorIncorrectStructSize? This is usually caused by one of 3 things: The headers you built with are more recent than the library you are using. Make sure you are using the most recent library. Note that using a library that is more recent than the headers should not give any problems. You forgot to set the struct size. Remember that every struct must be memset to 0, and the struct size must be lled out. You used the wrong struct to calculate the struct size parameter. This type of mistake is easily avoided by using a small function or macro to initialize PitStop Library structs, or by always using the same idiom for struct initialization, making errors easier to spot. What does eEPS_ErrorBasic or eEPS_ErrorBasicTools mean? These are unexpected, low-level errors inside PitStop Library. Examples can be le system errors or corrupt PDF streams, among others. Because this type of error can be hard to track, we have provided the EPL_GetLastErrorDescription() function. This function can be used to get more information about the last error. Note that this information is platform and implementation specic, and is provided solely to help you diagnose the problem. We cannot guarantee that this information will be in a specic language (usually the English string is available, but on systems with a different OS language it may not be), and hence it should normally not be shown to the end user. Why am I getting an eEPS_ErrorInitializationFailed error? The most likely cause is a problem with your handshake. Please contact Enfocus Integrator Support (integrator@enfocus.com) to resolve this. See the section Asking Questions to Developer Support for more information. Im getting eEPS_ErrorBadInputArgument The source of this error depends greatly on what you are trying to do. Most common is forgetting to ll out a required parameter, or passing a null pointer where this is not allowed, or giving an invalid combination of parameters. In most cases, reading the documentation of the struct you are passing to PitStop Library should help clear this up.

3.4 Enfocus PitStop Server SDK FAQ What about eEPS_ErrorIncorrectEnumValue?
This error is returned when you are trying to assign an incorrect value to an enum parameter. For example giving the value -1 when an EPS_Boolean is expected will result in an eEPS_ErrorIncorrectEnumValue error. In many cases the compiler should catch these errors at compile time because, as much as possible, we have dened the structs to take advantage of the type checking capabilities of C and C++. I keep getting eEPS_FatalError
This means something went very wrong in PitStop Library. Please contact Enfocus Integrator Support (integrator@enfocus.com) to resolve this. See the section Asking Questions to Developer Support for more information.

Requirements

3.5.1 Supported Platforms
PitStop Library is supported on the following operating systems: Windows Mac OS X Refer to the System Requirements document included in the Enfocus PitStop Server SDK for the detailed system requirements.
3.5.2 Enfocus PitStop Server SDK requirements
To read the documentation in this SDK you will need Adobe Reader or any other PDF viewer, or a web browser.
Tested web browsers are: Opera 9.0 (Windows & Mac OS X) Firefox 1.5 (Windows & Mac OS X) Firefox 2.0 (Windows & Mac OS X) Internet Explorer 6.0 (Windows) Safari 2.0 (Mac OS X)
The samples have been tested with: Microsoft Visual Studio.NET 2003 (using nmake) Microsoft Visual Studio.NET 2005 Express Edition (using nmake) Apple GCC 4.0 (using gnu make) Other development environments might work but have not been thoroughly tested and are not supported.
3.6 Using PitStop Library in your Solution
Using PitStop Library in your Solution
3.6.1 Types of Developers

3.6.1.1 OEM Partners

An OEM Partner is a company who integrates the services provided by PitStop Library under the terms of an explicit Software Bundling Agreement with Enfocus Software. Entering into a Software Bundling Agreement entails signing an NDA agreement with Artwork Systems, necessitates the need for an upfront technology fee, specic licensing terms for use of the technology and volume based reporting and payment. An OEM partner developer will typically work with the PitStop Library SDK. 3.6.1.2 Integrator
An Integrator is an individual or company who integrates the services provided by PitStop Server into his own solution; and who does so without entering a formal Software Bundling Agreement with Artwork Systems. An Integrator partner developer will typically work with the PitStop Server SDK.
3.6.2 PitStop Library and Integrators
3.6.2.1 Acquiring PitStop Library
As an Integrator, you need: A copy of the Enfocus PitStop Server SDK, which you most probably already have as you are reading this document. If not, you can obtain the latest version from our web site (refer to Getting the latest version of the Enfocus PitStop Server SDK). A license to use PitStop Server. You can download the PitStop Server trial version or just use the PitStop Library that can be found in the Enfocus PitStop Server SDK. This will allow you to evaluate the PitStop Library for 30 days. After that you must buy a registration key for PitStop Server or the PitStop Library will refuse to run. To verify the status of your trial period (or to enter your PitStop Server Product Key), install PitStop Server and open the About dialog. 3.6.2.2 Using PitStop Library from PitStop Server vs. from PitStop Server SDK

You can choose whether you want to work with the PitStop Library which is part of the PitStop Server installer or the PitStop Library from the Enfocus PitStop Server SDK.
If you choose the former, your application will need to know where PitStop Server is installed (e.g. by having the user select it) and you need to load PitStop Library from that location.
Enfocus recommends using the PitStop Library and resources which are part of the PitStop Server SDK. Your installer needs to copy these les into folders of your choosing as long as they do not overwrite or otherwise interfere with the Enfocus installers (e.g. copy them to your own application folder). Benets of this approach are that you always know the version of PitStop Library that you are
PitStop Library Page Documentation using and that you may ship updated versions of PitStop Library even when those are not yet available to PitStop Server.

3.6.2.3

Licensing Restrictions
Licensing for PitStop Library is governed by the same licensing restrictions as PitStop Server. For your convenience a copy of the licensing restrictions for PitStop Server is included in the Enfocus PitStop Server SDK. If you have questions about licensing or want to use PitStop Library in a way that is not allowed by the standard licensing terms, contact Artwork Systems. 3.6.2.4 Deploying your Solution
If you deploy your solution, your customer needs to install PitStop Server and register it with a valid registration key. After that PitStop Library can be used either by PitStop Server or by your solution.
To obtain a copy of the PitStop Server installer, you can: have your costumer download PitStop Server from our web site. bundle a copy of the (unmodied) PitStop Server installer with your solution.
To obtain a valid registration key for PitStop Server, you can: have your customer buy PitStop Server. buy a registration key for PitStop Server yourself and supply it to your customer
Please keep in mind that under the terms of the licensing agreement for PitStop Server one customer on one system can only use every registration key you buy for PitStop Server. This practically means that if you deploy your solution to 10 customers, you need to purchase 10 separate registration keys for PitStop Server and issue each of your customer a unique registration key.
Depending on your choice of how to nd PitStop Library (cfr. above) you may need to add PitStop Library and the related resources to your installer.
3.7 Where to go from here.

Where to go from here.

This chapter points you to other sources of information regarding working with PitStop Library.
3.7.1 Other Documentation in this Enfocus PitStop Server SDK

More information in this Enfocus PitStop Server SDK can be found in: Enfocus PitStop Library API This document contains the full description of all function in the Enfocus PitStop Server SDK, with a description of their purpose, parameters, return values and a code example where it makes sense. Sample Applications The sample applications, described in the next paragraph, can serve as a starting point for your development or as a help to highlight specic features of the Enfocus PitStop Server SDK. Header Files Even though our header les contain little or no documentation we have done our best to select logical names for functions and variables. From looking at the header les you - being a developer yourself - should be able to gure out anything that is not clear from this overview or the full Enfocus PitStop Library API.

3.7.2 Samples

The Enfocus PitStop Server SDK contains a number of sample projects to get you started and show how to use various PitStop Library features. All samples are provided in the folder called "Samples"; they all contain the necessary source les and a makele to build them.
Each sample is contained in its own sub-folder; a special "SDKUtils" folder contains code used by all sample projects. The following paragraphs give a (short) description of each sample.

3.7.2.1

GetInfo
This sample shows how to get information about PitStop Library and the supported languages.

3.7.2.2

InitializeLibrary
This sample shows how to initialize PitStop Library in 2 ways: one sets only the minimum required parameters, the other shows the usage of some other parameters.

3.7.2.3

ProcessEAL_PPP
This sample shows how to process a le with a PDF Prole and/or Action List and how to show the results of the processing. It ushes all this output to the console.
26 3.7.2.4 IterateEAL_PPP
This shows how to use the PitStop Library iterators to iterate over a folder and over the mutator database. 3.7.2.5 OpenSaveClose
This demonstrates different ways of opening, saving and closing documents with PitStop Library.
3.7.3 Accessing the Knowledge Base on our Web Site
The Knowledge Base on our web site contains frequently asked questions, problems and workarounds for problems with our end user products, but also for PitStop Library. Before contacting us, please make sure your question is not already answered in the Knowledge Base.
To access the Knowledge Base, go to our web site at http://www.enfocus.com and under the "Support" menu select "Knowledge Base". You can then browse all issues related to PitStop Library or search on specic search terms.
3.7.4 Asking Questions to Developer Support
Once you purchased the Enfocus PitStop Server SDK, you also get free access for a limited number of cases to developer support. To ask a question or give a remark about the Enfocus PitStop Server SDK, use the integrator@enfocus.com email address.

When asking questions, please be as complete as possible! When asking questions about non- or malfunctioning code, provide us with the sample code you used to reproduce the problem and with a clear description of what it is you are trying to accomplish. Although sometimes a code fragment is enough, it is often much more useful if you provide a complete, compilable example. Often, the SDK samples can be used as a starting point for such a sample application. If the problem happens only for specic PDF les, PDF Proles or Action Lists, please include these problem les as well. For problems you can also use the "report a problem" page on our partners (site http://partners.enfocus.com).
3.8 Overview of the Samples

Overview of the Samples

3.8.1 GetInfo
This sample gets all information that can be queried from PitStop Library without processing PDF documents or looking at preight reports. It ushes all this output to the console. Information provided includes: General information on the PitStop Library. Information on the languages installed in PitStop Library. See also: page_getinfo

3.8.2 InitializeLibrary

This sample shows how to initialize the library and set common settings. Initialization can be controlled by sUseCustomInit, which switches initialization between the standard EPLSDK_InitLibrary and the custom InitializeLibrary_InitializeLibrary of this sample. After initialization a conguration is created and set, which is needed for changing the language and main unit. After this it is shown how to add a progress callback and how to set certied personal info. Before nalizing the conguration is closed. Following steps are illustrated in this sample: InitializeLibrary_CustomizedInitializeLibrary(): initialize the library with custom folders. InitializeLibrary_SetLanguageAndUnits(): changing two settings: language and main unit InitializeLibrary_SetProgressCallback(): setting the progress callback to keep track of the progress of the processing. InitializeLibrary_SetCertiedPersonalInfo(): setting some settings about Certied personal info. See also: page_initializelibrary

3.8.3 IterateEAL_PPP

This sample shows how to use iterators. There are two different kind of iterators: Folder and Mutator Iterators. Folder iterators iterate over directories. Mutator iterators iterate mutator databases. This sample contains the following methods: IterateEAL_PPP_IterateFolder(): iterate a folder, uses IterateEAL_PPP_IterateItems to iterate its items. IterateEAL_PPP_IterateMutatorDBS(): iterate the 4 different Mutator databases, uses IterateEAL_PPP_IterateMutatorDB. IterateEAL_PPP_IterateMutatorDB(): does the actual iteration of a selected database, uses IterateEAL_PPP_IterateItems() to iterate its items.