<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"><html><head><title>The Ghostscript Interpreter Application Programming Interface (API)</title><!-- $Id: API.htm,v 1.53 2005/10/20 19:46:22 ray Exp $ --><!-- Supercedes the API in DLL.htm --><link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"></head> <body><!-- [1.0 begin visible header] ============================================ --> <!-- [1.1 begin headline] ================================================== --> <h1>The Ghostscript Interpreter Application Programming Interface (API)</h1> <!-- [1.1 end headline] ==================================================== --> <!-- [1.2 begin table of contents] ========================================= --> <h2>Table of contents</h2> <ul><li><a href="#API">What is the Ghostscript Interpreter API?</a><li><a href="#Exported_functions ">Exported functions</a><ul><li><a href="#revision"><b><tt>gsapi_revision</tt></b></a><li><a href="#new_instance"><b><tt>gsapi_new_instance</tt></b></a><li><a href="#delete_instance"><b><tt>gsapi_delete_instance</tt></b></a><li><a href="#set_stdio"><b><tt>gsapi_set_stdio</tt></b></a><li><a href="#set_poll"><b><tt>gsapi_set_poll</tt></b></a><li><a href="#set_display_callback"><b><tt>gsapi_set_display_callback</tt></b></a><li><a href="#run"><b><tt>gsapi_run_string_begin</tt></b></a><li><a href="#run"><b><tt>gsapi_run_string_continue</tt></b></a><li><a href="#run"><b><tt>gsapi_run_string_end</tt></b></a><li><a href="#run"><b><tt>gsapi_run_string_with_length</tt></b></a><li><a href="#run"><b><tt>gsapi_run_string</tt></b></a><li><a href="#init"><b><tt>gsapi_init_with_args</tt></b></a><li><a href="#run"><b><tt>gsapi_run_*</tt></b></a><li><a href="#exit"><b><tt>gsapi_exit</tt></b></a><li><a href="#set_visual_tracer"><b><tt>gsapi_set_visual_tracer</tt></b></a><li><a href="#return_codes">Return codes</a></ul><li><a href="#Example_usage">Example usage</a><li><a href="#stdio">Standard input and output</a><li><a href="#display">Display device</a></ul> <!-- [1.2 end table of contents] =========================================== --> <!-- [1.3 begin hint] ====================================================== --> <p>For other information, see the <a href="Readme.htm">Ghostscriptoverview</a>. <p><b>WARNING:</b> The API described in this document is subject to changes infuture releases, possibly ones that are not backward compatible with whatis described here. <!-- [1.3 end hint] ======================================================== --> <hr> <!-- [1.0 end visible header] ============================================== --> <!-- [2.0 begin contents] ================================================== -->  <h2><a name="API"></a>What is the Ghostscript Interpreter API?</h2> <p>The Ghostscript interpreter can be built as a dynamic link library (DLL) on the Windows or OS/2 platforms, as a shared object on the Linux platform and as a framework on MacOS X.With some changes, it could be built as a static library.This document describes the Application Programming Interface (API)for the Ghostscript interpreter library.  This should not be confused with the <a href="Lib.htm">Ghostscript library</a> which provides a graphicslibrary but not the interpreter.<p>This supercedes the old <a href="DLL.htm">DLL</a> interface.<p>To provide the interface described in the <a href="Use.htm">usage documentation</a>, a smaller independent executable loads the DLL/shared object.This executable must provide all the interaction with the windowing system, including image windows and, if necessary, a text window. <p>The Ghostscript interpreter library's name and characteristics differfor each platform: <ul><li>The Win32 DLL <b><tt>gsdll32.dll</tt></b> hasMULTIPLE NONSHARED data segments.  Under Win32s it can be used by only oneprogram at a time, but under Windows 95/98 or Windows NT it can be called bymultiple programs simultaneously. <li>The OS/2 DLL <b><tt>gsdll2.dll</tt></b> hasMULTIPLE NONSHARED data segments and can be called by multiple programssimultaneously. <li>The Linux shared object <b><tt>libgs.so</tt></b>can be used by multiple programs simultaneously. <li>The MacOS X <b><tt>Ghostscript.framework</tt></b> can also be usedby multiple applications at once.</ul> <p>The source for the executable is in <b><tt>dw</tt></b>*.* (Windows),<b><tt>dp</tt></b>*.* (OS/2) and  <b><tt>dx</tt></b>*.* (Linux).  See these source files for examples of how to use the DLL. A similarexample for MacOS using the Carbon API is provided in <b><tt>dm</tt></b>*.*. <p>The source file <tt>dxmainc.c</tt> can also serve as an example of how to use the framework shared component on MacOS X, providing the same command-line tool it doeson any linux, bsd or similar operating system. Just change the header includes to use the Ghostscript namespace:<blockquote><pre><tt>#include &lt;Ghostscript/ierrors.h&gt;#include &lt;Ghostscript/iapi.h&gt;</tt></pre></blockquote>and link with:<blockquote><pre><tt>cc -o gsc dxmainc.c -framework Ghostscript</tt></pre></blockquote>To get a useable executable. <tt>Ghostscript.framework</tt> must be properlyinstalled in the search path for this to work. <p>At this stage, Ghostscript does not support multiple instancesof the interpreter within a single process. <hr> <h2><a name="Exported_functions"></a>Exported functions</h2> <p>The functions exported by the DLL/shared object are described in the header file <a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a>and are summarised below.  Omitted from the summary arethe calling convention (e.g. __stdcall), details of return values and error handling.  <ul><li><b><tt>int <a href="#revision">gsapi_revision</a>  (gsapi_revision_t *pr, int len);</tt></b> <li><b><tt>int <a href="#new_instance">gsapi_new_instance</a>(void **pinstance, void *caller_handle);</tt></b> <li><b><tt>void <a href="#delete_instance">gsapi_delete_instance</a>(void *instance);</tt></b> <li><b><tt>int <a href="#set_stdio">gsapi_set_stdio</a>(void *instance,    int(*stdin_fn)(void *caller_handle, char *buf, int len),    int(*stdout_fn)(void *caller_handle, const char *str, int len),    int(*stderr_fn)(void *caller_handle, const char *str, int len));</tt></b> <li><b><tt>int <a href="#set_poll">gsapi_set_poll</a>(void *instance, int(*poll_fn)(void *caller_handle));</tt></b> <li><b><tt>int <a href="#set_display_callback">gsapi_set_display_callback</a>(void *instance, display_callback *callback);</tt></b> <li><b><tt>int <a href="#init">gsapi_init_with_args</a>(void *instance, int argc, char **argv);</tt></b> <li><b><tt>int <a href="#run">gsapi_run_string_begin</a>(void *instance, int user_errors, int *pexit_code);</tt></b> <li><b><tt>int <a href="#run">gsapi_run_string_continue</a>(void *instance,     const char *str, unsigned int length, int user_errors, int *pexit_code);</tt></b> <li><b><tt>int <a href="#run">gsapi_run_string_end</a>(void *instance, int user_errors, int *pexit_code);</tt></b> <li><b><tt>int <a href="#run">gsapi_run_string_with_length</a>(void *instance,     const char *str, unsigned int length, int user_errors, int *pexit_code);</tt></b> <li><b><tt>int <a href="#run">gsapi_run_string</a>(void *instance,     const char *str, int user_errors, int *pexit_code);</tt></b> <li><b><tt>int <a href="#run">gsapi_run_file</a>(void *instance,     const char *file_name, int user_errors, int *pexit_code);</tt></b> <li><b><tt>int <a href="#exit">gsapi_exit</a>(void *instance);</tt></b> <li><b><tt>int<a href="#set_visual_tracer">gsapi_set_visual_tracer</a>(gstruct vd_trace_interface_s *I);</tt></b> </ul> <h3><a name="revision"></a><b><tt>gsapi_revision()</tt></b></h3> <blockquote>This function returns the revision numbers and strings of the Ghostscriptinterpreter library; you should call it before any other interpreterlibrary functions to make sure that the correct version of the Ghostscript interpreter has been loaded. <blockquote><pre>typedef struct gsapi_revision_s {    const char *product;    const char *copyright;    long revision;    long revisiondate;} gsapi_revision_t;gsapi_revision_t r; if (gsapi_revision(&amp;r, sizeof(r)) == 0) {    if (r.revision < 650)       printf("Need at least Ghostscript 6.50");}else {    printf("revision structure size is incorrect");}</pre></blockquote></blockquote>  <h3><a name="new_instance"></a><b><tt>gsapi_new_instance()</tt></b></h3><blockquote>Create a new instance of Ghostscript.This instance is passed to most other gsapi functions.The caller_handle will be provided to callback functions.<b>At this stage, Ghostscript supports only one instance</b>.</blockquote>  <h3><a name="delete_instance"></a><b><tt>gsapi_delete_instance()</tt></b></h3><blockquote>Destroy an instance of Ghostscript.Before you call this, Ghostscript must have finished.If Ghostscript has been initialised, you must call <b><tt>gsapi_exit</tt></b> before <b><tt>gsapi_delete_instance</tt></b>.</blockquote>  <h3><a name="set_stdio"></a><b><tt>gsapi_set_stdio()</tt></b></h3><blockquote>Set the callback functions for stdioThe stdin callback function should return the number ofcharacters read, 0 for EOF, or -1 for error.The stdout and stderr callback functions should returnthe number of characters written.</blockquote>  <h3><a name="set_poll"></a><b><tt>gsapi_set_poll()</tt></b></h3><blockquote>Set the callback function for polling.This is used for handling window events or cooperativemultitasking.  This function will only be called ifthe Ghostscript interpreter was compiled with <b><tt>CHECK_INTERRUPTS</tt></b>as described in <b><tt><a href="../src/gpcheck.h">gpcheck.h</a></tt></b>.The polling function should return zero if all is well,and return negative if it wants ghostscript to abort.The polling function must be fast.</blockquote> <h3><a name="set_display_callback"></a><b><tt>gsapi_set_display_callback()</tt></b></h3><blockquote>Set the callback structure for the <a href="#display">display</a>device.  If the <a href="#display">display</a> device is used, this must be called after <b><tt>gsapi_new_instance()</tt></b>and before <b><tt>gsapi_init_with_args()</tt></b>.See <b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>for more details.</blockquote> <h3><a name="init"></a><b><tt>gsapi_init_with_args()</tt></b></h3><blockquote>Initialise the interpreter.This calls <b><tt>gs_main_init_with_args()</tt></b> in <b><tt><a href="../src/imainarg.c">imainarg.c</a></tt></b>.See below for <a href="#return_codes">return codes</a>.The arguments are the same as the "C" main function:argv[0] is ignored and the user supplied arguments are argv[1] to argv[argc-1].</blockquote> <h3><a name="run"></a><b><tt>gsapi_run_*()</tt></b></h3><blockquote>The <b><tt>gsapi_run_*</tt></b> functions are like <b><tt>gs_main_run_*</tt></b> except that the error_object is omitted.If these functions return <= -100, either quit or a fatalerror has occured.  You must call <b><tt>gsapi_exit()</tt></b> next.The only exception is <b><tt>gsapi_run_string_continue()</tt></b>which will return <b><tt>e_NeedInput</tt></b> if all is well.See below for <a href="#return_codes">return codes</a>.<p>There is a 64 KB length limit on any buffer submitted to a <tt>gsapi_run_*</tt> function for processing. If you have morethan 65535 bytes of input then you must split it into smaller pieces and submit each in a separate <tt>gsapi_run_string_continue()</tt> call.</blockquote> <h3><a name="exit"></a><b><tt>gsapi_exit()</tt></b></h3><blockquote>Exit the interpreter.This must be called on shutdown if <b><tt>gsapi_init_with_args()</tt></b>has been called, and just before <b><tt>gsapi_delete_instance()</tt></b>.</blockquote> <h3><a name="set_visual_tracer"></a><b><tt>gsapi_set_visual_tracer()</tt></b></h3><blockquote>Pass visual tracer interface block to Ghostscript.See <a href="Lib.htm#Visual_trace"><b><tt>Lib.htm</tt></b></a> for reference about the interface block structure.This function is useful for debug clients only. Release clients must not call it.</blockquote>  <h3><a name="return_codes"></a>Return codes</h3> <p>The <b><tt>gsapi_init_with_args</tt></b>, <b><tt>gsapi_run_*</tt></b> and<b><tt>gsapi_exit</tt></b> functions return an integer code. <p><table width="80%" align="center" cellpadding=0 cellspacing=0><tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Return codes from <b><tt>gsapi_*()</tt></b></font><hr><tr valign=bottom>	<th align=left>Code	<td>&nbsp;&nbsp;&nbsp;&nbsp;	<th align=left>Status<tr>	<td colspan=3><hr><tr valign=top>	<td align=left>0	<td>&nbsp;	<td>No errors<tr valign=top>	<td align=left>e_Quit	<td>&nbsp;	<td>"<b><tt>quit</tt></b>" has been executed.	This is not an error.	<b><tt>gsapi_exit()</tt></b> must be called next.<tr valign=top>	<td align=left>e_NeedInput	<td>&nbsp;	<td>More input is needed by        <b><tt>gsapi_run_string_continue()</tt></b>.        This is not an error.<tr valign=top>	<td align=left>e_Info	<td>&nbsp;	<td>"<b><tt>gs -h</tt></b>" has been executed. 	This is not an error.	<b><tt>gsapi_exit()</tt></b> must be called next.<tr valign=top>	<td align=left>&lt; 0	<td>&nbsp;	<td>Error<tr valign=top>	<td align=left>&lt;= -100	<td>&nbsp;	<td>Fatal error.<b><tt>gsapi_exit()</tt></b> must be called next.</table></blockquote> <p>The <b><tt>gsapi_run_*()</tt></b> functions do not flush stdio.If you want to see output from Ghostscript youmust do this explicitly as shown in the example below. <p>When executing a string with <b><tt>gsapi_run_string_*()</tt></b>,<b><tt>currentfile</tt></b> is the input from the string.Reading from <b><tt>%stdin</tt></b> uses the stdin callback.</blockquote>   <h2><a name="Example_usage"></a>Example Usage</h2>Some overly simple examples of using the Ghostscript interpreter library are below.  Some more examples including other programming languagesmay be found at<a href="http://www.cs.wisc.edu/~ghost/doc/gsapi.htm">http://www.cs.wisc.edu/~ghost/doc/gsapi.htm</a>. <p>To use try out these examples in a development environment like Microsoft'sdeveloper tools or Metrowerks Codewarrior, create a new project, save the examplesource code as a <tt>.c</tt> file and add it, along with the Ghostscript dll or sharedlibrary. You will also need to make sure the Ghostscript headers are available, eitherby adding their location (the <tt>src</tt> directory in the Ghostscript sourcedistribution) to the project's search path, or by copying ierrors.h and iapi.h into thesame directory as the example source.</p>  <h3>Example 1</h3><pre>/* Example of using GS DLL as a ps2pdf converter.  */ #if defined(_WIN32) && !defined(_Windows)# define _Windows#endif#ifdef _Windows/* add this source to a project with gsdll32.dll, or compile it directly with: *   cl -D_Windows -Isrc -Febin\ps2pdf.exe ps2pdf.c bin\gsdll32.lib */# include &lt;windows.h&gt;# define GSDLLEXPORT __declspec(dllimport)#endif #include "ierrors.h"#include "iapi.h" void *minst; int main(int argc, char *argv[]){    int code, code1;    const char * gsargv[10];    int gsargc;    gsargv[0] = "ps2pdf";	/* actual value doesn't matter */    gsargv[1] = "-dNOPAUSE";    gsargv[2] = "-dBATCH";    gsargv[3] = "-dSAFER";    gsargv[4] = "-sDEVICE=pdfwrite";    gsargv[5] = "-sOutputFile=out.pdf";    gsargv[6] = "-c";    gsargv[7] = ".setpdfwrite";    gsargv[8] = "-f";    gsargv[9] = "input.ps";    gsargc=10;     code = gsapi_new_instance(&minst, NULL);    if (code &lt; 0)	return 1;    code = gsapi_init_with_args(minst, gsargc, gsargv);    code1 = gsapi_exit(minst);    if ((code == 0) || (code == e_Quit))	code = code1;     gsapi_delete_instance(minst);     if ((code == 0) || (code == e_Quit))	return 0;    return 1;}</pre> <h3>Example 2</h3><pre>/* Similar to command line gs */ #if defined(_WIN32) && !defined(_Windows)# define _Windows#endif#ifdef _Windows

Lines 1–500 of 748. Load more