Acrobat Distiller API Reference

Restriction on Directory Access

Distiller restricts the directories that PostScript file operators can access. The default behavior limits directory access to the temp and font cache directories. Earlier versions of Acrobat Distiller allowed PostScript file operators to have unlimited directory access.

The following Acrobat Distiller command line options (Windows) and user preference (Mac) enable unlimited directory access. Such unlimited access can pose security problems.

  • Windows: -F command line option

  • Mac OS: AllowPSFileOps user preference

For information on using these Acrobat Distiller command line options and preferences with the EMBED pdfMark command, refer to the PDFmark Reference .

Windows Automation

For most applications, the best way to automate Distiller under Windows is through the automation interface. The automation interface makes it easy to create and control Distiller from any programming language that supports automation. Distiller supports Visual Basic and Visual C++ with or without MFC.

Distiller exposes one interface: PdfDistiller. This interface provides methods, properties, and events.

In Visual Basic, if you want to just create and use a Distiller instance without spooling or events, the code can be as simple as the following:

Dim pdf As PdfDistiller
 pdf.FileToPdf "My Test File.ps", "", ""

Unless otherwise noted, all examples in this chapter use Visual Basic notation.

Methods

Create

Creates a Distiller instance. You do not need to call this method, because a Distiller instance is always created if one of the other methods needs it. However, you may want to call this method if you are handling events and want to display the Distiller startup messages before you submit any jobs.

Each user of the automation interface has its own Distiller instance. There is no sharing of a common Distiller as is done with the WM_COPYDATA interface.

FileToPDF

Submits a PostScript file job to Distiller.

This method always creates a log file, regardless of the setting of the Delete Log Files for Successful Jobs preference in Distiller.

Parameters

strInputPostScript

The PostScript file to process.

strOutputPDF

The name of the PDF file.

strPDFOptions

The name and path of the Adobe PDF settings file to use.

Returns

short int (true on success, false otherwise)

If 0 is returned, the parameters are invalid; if -1 is returned, the PDF creation itself failed. If the user set the bSpoolJobs flag before calling this method, then it returns an error only for invalid parameters.

FileToPDF2

Submits a PostScript file job to Distiller. This method is the same as FileToPDF except for the addition of an option to apply security.

Parameters

strInputPostScript

The PostScript file to process.

strOutputPDF

The name of the PDF file.

strPDFOptions

The name and path of the Adobe PDF settings file to use.

long bApplySecurity

A Boolean value that, if greater than 0 , causes security to be applied to the PDF as currently defined in the Distiller application security dialog box.

Returns

short int (true on success, false otherwise)

If 0 is returned, the parameters are invalid; if -1 is returned, the PDF creation itself failed. If the user set the bSpoolJobs flag before calling this method, then it returns an error only for invalid parameters.

Properties

bShowWindow

bSpoolJobs

bShowWindow

Specifies whether Distiller opens with the status windows. This property takes effect only if you set it before calling the Create method or any other method. If you have already started Distiller, bShowWindow has no effect.

Syntax

[get/set] As Long

bSpoolJobs

Specifies whether Distiller queues PDF jobs through its internal spooler or processes each job immediately.

By default, bSpoolJobs is false , and FileToPDF processes the PDF job immediately and does not return until the PDF file is created.

If bSpoolJobs is true , FileToPDF submits the PDF job to Distiller’s internal job queue and returns immediately. The job will be processed at some later time. To find out when the job is done, you can watch for the events Distiller runs during job processing.

Syntax

[get/set] As Long

Events

OnJobStart

Run once when a job begins processing.

Syntax

OnJobStart( ByVal strInputPostScript As String,
   ByVal_ strOutputPDF As String )

OnJobDone

Run once when a job completes successfully.

Syntax

OnJobDone( ByVal strInputPostScript As String,
   _ByVal strOutputPDF As String )

OnJobFail

Run once when a job ends unsuccessfully.

Syntax

OnJobFail( ByVal strInputPostScript As String,
   _ByVal strOutputPDF As String )

OnLogMessage

Run at various times with the text messages that normally appear in Distiller’s message log window.

A single call to OnLogMessage may contain multiple lines or partial lines of text. In the current version of Distiller, the text may contain line feed characters without carriage return characters. Your application should not make any assumptions about how this text is formatted and should be prepared to receive either line feed characters (LF) alone or carriage return - line feed (CR-LF) pairs.

Syntax

OnLogMessage( ByVal strMessage As String )

OnPercentDone

Run periodically during a job to indicate overall progress.

Syntax

OnPercentDone( ByVal nPercentDone As Long )

OnPageNumber

Run periodically during a job to indicate the current page number.

Syntax

OnPageNumber( ByVal nPageNumber As Long )