gs/doc/API.htm

<!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.11.2.3 2002/02/01 06:16:22 giles 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="#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="#return_codes">Return codes</a>
</ul>
<li><a href="#Typical_usage">Typical 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">Ghostscript
overview</a>.

<p>
<b>WARNING:</b> The API described in this document is subject to changes in
future releases, possibly ones that are not backward compatible with what
is 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 graphics
library 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 provides 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 differ
for each platform:

<ul>
<li>The Win32 DLL <b><tt>gsdll32.dll</tt></b> has
MULTIPLE NONSHARED data segments.  Under Win32s it can be used by only one
program at a time, but under Windows 95/98 or Windows NT it can be called by
multiple programs simultaneously.

<li>The OS/2 DLL <b><tt>gsdll2.dll</tt></b> has
MULTIPLE NONSHARED data segments and can be called by multiple programs
simultaneously.

<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 used
by 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.

The source file <p><tt>dxmainc.c</tt> can serve as an example of how to use the
framework shared component on MacOS X. Just change the header includes to use
the Ghostscript namespace:
<blockquote><pre><tt>#include &lt;Ghostscript/errors.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 properly
installed in the search path for this to work.

<p>
At this stage, Ghostscript does not support multiple instances
of 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 are
the 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>
(gs_main_instance **pinstance, void *caller_handle);
</tt></b>

<li><b><tt>
void
<a href="#delete_instance">gsapi_delete_instance</a>
(gs_main_instance *instance);
</tt></b>

<li><b><tt>
int
<a href="#set_stdio">gsapi_set_stdio</a>
(gs_main_instance *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>
(gs_main_instance *instance, int(*poll_fn)(void *caller_handle));
</tt></b>

<li><b><tt>
int
<a href="#set_display_callback">gsapi_set_display_callback</a>
(gs_main_instance *instance, display_callback *callback);
</tt></b>

<li><b><tt>
int
<a href="#init">gsapi_init_with_args</a>
(gs_main_instance *instance, int argc, char **argv);
</tt></b>

<li><b><tt>
int
<a href="#run">gsapi_run_string_begin</a>
(gs_main_instance *instance, int user_errors, int *pexit_code);
</tt></b>

<li><b><tt>
int
<a href="#run">gsapi_run_string_continue</a>
(gs_main_instance *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>
(gs_main_instance *instance, int user_errors, int *pexit_code);
</tt></b>

<li><b><tt>
int
<a href="#run">gsapi_run_string_with_length</a>
(gs_main_instance *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>
(gs_main_instance *instance,
    const char *str, int user_errors, int *pexit_code);
</tt></b>

<li><b><tt>
int
<a href="#run">gsapi_run_file</a>
(gs_main_instance *instance,
    const char *file_name, int user_errors, int *pexit_code);
</tt></b>

<li><b><tt>
int
<a href="#exit">gsapi_exit</a>
(gs_main_instance *instance);
</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 Ghostscript
interpreter library; you should call it before any other interpreter
library 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 stdio
The stdin callback function should return the number of
characters read, 0 for EOF, or -1 for error.
The stdout and stderr callback functions should return
the 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 cooperative
multitasking.  This function will only be called if
the 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>.
</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>.
</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 fatal
error 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>.
</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="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 you
must 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="Typical_usage"></a>Typical Usage</h2>
A really short example of using the Ghostscript interpreter library is:

<pre>
#include &lt;stdio.h&gt;
#include "errors.h"
#include "iapi.h"

/* stdio functions */
static int
gsdll_stdin(void *instance, char *buf, int len)
{
    int ch;
    int count = 0;
    while (count &lt; len) {
	ch = fgetc(stdin);
	if (ch == EOF)
	    return 0;
	*buf++ = ch;
	count++;
	if (ch == '\n')
	    break;
    }
    return count;
}

static int
gsdll_stdout(void *instance, const char *str, int len)
{
    fwrite(str, 1, len, stdout);
    fflush(stdout);
    return len;
}

static int
gsdll_stderr(void *instance, const char *str, int len)
{
    fwrite(str, 1, len, stderr);
    fflush(stderr);
    return len;
}

gs_main_instance *minst;
const char start_string[] = "systemdict /start get exec\n";

int main(int argc, char *argv[])
{
    int code;
    int exit_code;

    code = gsapi_new_instance(&minst, NULL);
    if (code < 0)
	return 1;
    gsapi_set_stdio(minst, gsdll_stdin, gsdll_stdout, gsdll_stderr);
    code = gsapi_init_with_args(minst, argc, argv);
    if (code == 0)
	code = gsapi_run_string(minst, start_string, 0, &exit_code);
    gsapi_exit(minst);

    gsapi_delete_instance(minst);

    if ((code == 0) || (code == e_Quit))
	return 0;
    return 1;
}
</pre>


<p>
Another partial code example showing how you can feed Ghostscript piecemeal:
<pre>
    char *command = "1 2 add == flush\n";
    int exit_code;
    gsapi_run_string_begin(minst, 0, &exit_code);
    gsapi_run_string_continue(minst, command, strlen(command), 0, &exit_code);
    gsapi_run_string_continue(minst, "qu", 2, 0, &exit_code);
    gsapi_run_string_continue(minst, "it", 2, 0, &exit_code);
    gsapi_run_string_end(minst, 0, &exit_code);
</pre>


<h2><a name="Multiple_threads"></a>Multiple threads</h2>
The Ghostscript library should have been compiled with a
thread safe run time library.
Synchronisation of threads is entirely up to the caller.

<h2><a name="stdio"></a>Standard input and output</h2>
<p>
When using the Ghostscript interpreter library interface, you have a
choice of two standard input/output methods.
<ul>
<li>If you do nothing, the "C" stdio will be used.
<li>If you use <b><tt>gsapi_set_stdio()</tt></b>,  all stdio will
 be redirected to the callback functions you provide.
 This would be used in a graphical user interface environment
 where stdio is not available, or where you wish to process
 Ghostscript input or output.
</ul>
<p>
The callback functions are described in
<a href="../src/iapi.h"><b><tt>iapi.h</tt></b></a>.


<h2><a name="display"></a>Display device</h2>
<p>
The <b><tt>display</tt></b> device is available for use with
the Ghostscript interpreter library.  This is described in the file
<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>.
This device provides you with access to the raster output of
Ghostscript.  It is your responsibility to copy this raster
to a display window or printer.
<p>
To use this device, you must provide a callback structure
with addresses of a number of callback functions.
The address of the callback structure is provided using
<b><tt>gsapi_set_display_callback()</tt></b>.
This must be called after
<b><tt>gsapi_new_instance()</tt></b>
and before
<b><tt>gsapi_init_with_args()</tt></b>.
<p>
The callbacks are for device open, close, resize, sync, page,
memory allocation and updating.
Each callback function contains a handle can be set using
<blockquote>
  -dDisplayHandle=1234
</blockquote>
<p>
The device raster format can be configured using
<blockquote>
  -dDisplayFormat=NNNN
</blockquote>
Options include
<ul>
<li> native, gray, RGB or CMYK color spaces.
<li> alpha byte (ignored).
<li> 1 to 16 bits/component.
<li> bigendian (RGB) or littleendian (BGR) order.
<li> top first or bottom first raster.
<li> 16 bits/pixel with 555 or 565 bitfields.
</ul>
The format values are described in
<b><tt><a href="../src/gdevdsp.h">gdevdsp.h</a></tt></b>.
The format is flexible enough to support common Windows, OS/2, Linux
and Mac raster formats.  To select the display device with a
Windows 24-bit RGB raster:
<pre>
    char **nargv;
    char arg1[64];
    char arg2[64];
    char arg3[64];
    code = gsapi_new_instance(&minst, NULL);
    gsapi_set_stdio(minst, gsdll_stdin, gsdll_stdout, gsdll_stderr);
    code = gsapi_set_display_callback(minst, &display_callback);
    sprintf(arg1, "-sDEVICE=display");
    sprintf(arg2, "-dDisplayHandle=%d", 0);
    sprintf(arg3, "-dDisplayFormat=%d",
        DISPLAY_COLORS_RGB | DISPLAY_ALPHA_NONE | DISPLAY_DEPTH_8 |
        DISPLAY_LITTLEENDIAN | DISPLAY_BOTTOMFIRST);
    nargv = (char **)malloc((argc + 4) * sizeof(char *));
    nargv[0] = argv[0];
    nargv[1] = arg1;
    nargv[2] = arg2;
    nargv[3] = arg3;
    memcpy(nargv + 4, argv + 1, argc * sizeof(char *));
    argc += 3;
    code = gsapi_init_with_args(minst, argc, nargv);
</pre>

<p>
The display device provides you with the address and size of the
raster using the <b><tt>display_size()</tt></b> callback.
You are then responsible for displaying this raster.
Some examples are in
<b><tt><a href="../src/dwmain.c">dwmain.c</a></tt></b> (Windows),
<b><tt><a href="../src/dpmain.c">dpmain.c</a></tt></b> (OS/2) and
<b><tt><a href="../src/dxmain.c">dxmain.c</a></tt></b> (X11/Linux).

<p>

<!-- [2.0 end contents] ==================================================== -->

<!-- [3.0 begin visible trailer] =========================================== -->
<hr>


<p>
<small>Copyright &copy; 2001 artofcode LLC.  All rights reserved.</small>

<p>
<small>This file is part of AFPL Ghostscript.  See the
<a href="Public.htm">Aladdin Free Public License</a> (the "License") for
full details of the terms of using, copying, modifying, and redistributing
AFPL Ghostscript.</small>

<p>
<small>Ghostscript version 7.04, 31 January 2002


<!-- [3.0 end visible trailer] ============================================= -->

</body>
</html>