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 |
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¶
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 )