Ghostscript language bindings

Introduction
About our APIs
Demo code
C#
Overview
GhostAPI
GhostNET
GhostMono
Java
Overview
gsjava.jar
Python
Overview
gsapi.py

# GhostNET

## About

`GhostNET` is the `C#` interface into the `GhostAPI` library developed for Windows systems.

## Enums

### Tasks

The Ghostscript task type `enum` is used to inform `GhostAPI` of the type of operation which is being requested.

Task | Description
--- | ---
PS_DISTILL | Task associated with converting a PostScript stream to a PDF document
CREATE_XPS | Task associated with outputting a copy of a document to XPS
SAVE_RESULT | Task associated with saving documents
GET_PAGE_COUNT | Task associated with getting the page count of a document
GENERIC | Generic task identifier
DISPLAY_DEV_THUMBS | Display Device task associated with rendering thumbnails
DISPLAY_DEV_NON_PDF | Display Device task associated with non-PDF or non-XPS rendering 1
DISPLAY_DEV_PDF | Display Device task associated with PDF & XPS rendering 1
DISPLAY_DEV_RUN_FILE | Display Device task associated with running files

Task types are defined as `GS_Task_t`.

    public enum GS_Task_t
    {
        PS_DISTILL,
        CREATE_XPS,
        SAVE_RESULT,
        GET_PAGE_COUNT,
        GENERIC,
        DISPLAY_DEV_THUMBS,
        DISPLAY_DEV_NON_PDF,
        DISPLAY_DEV_PDF,
        DISPLAY_DEV_RUN_FILE
    }

### Results

Result types are defined as `GS_Result_t`.

    public enum GS_Result_t
    {
        gsOK,
        gsFAILED,
        gsCANCELLED
    }

### Status

Status is defined as `gsStatus`.

    public enum gsStatus
    {
        GS_READY,
        GS_BUSY,
        GS_ERROR
    };

## The Parameter Struct

The parameter struct `gsParamState_t` allows for bundles of information to be processed by Ghostscript to complete overall requests.

    public struct gsParamState_t
    {
        public String outputfile;
        public String inputfile;
        public GS_Task_t task;
        public GS_Result_t result;
        public int num_pages;
        public List<int> pages;
        public int firstpage;
        public int lastpage;
        public int currpage;
        public List<String> args;
        public int return_code;
        public double zoom;
        public bool aa;
        public bool is_valid;
    };

### Parameters explained

Setting up your parameters (with any dedicated bespoke method(s) which your application requires) is needed when communicating directly with `GhostAPI`.

When requesting Ghostscript to process an operation an application developer should send a parameter payload which defines the details for the operation.

For example in `GhostNET` we can see the public method as follows:

    public gsStatus DistillPS(String fileName, int resolution)
    {
        gsParamState_t gsparams = new gsParamState_t();
        gsparams.args = new List<string>();

        gsparams.inputfile = fileName;
        gsparams.args.Add("gs");
        gsparams.args.Add("-sDEVICE=pdfwrite");
        gsparams.outputfile = Path.GetTempFileName();
        gsparams.args.Add("-o" + gsparams.outputfile);
        gsparams.task = GS_Task_t.PS_DISTILL;

        return RunGhostscriptAsync(gsparams);
    }

Here we can see a parameter payload being setup before being passed on to the asynchronous method `RunGhostscriptAsync` which sets up a worker thread to run according to the task type in the payload.

`GhostNET` handles many common operations on an application developer's behalf, however if you require to write your own methods to interface with `GhostAPI` then referring to the public methods in `GhostNET` is a good starting point.

For full documentation on parameters refer to Ghostscript parameters.

## The Event class

`GhostNET` contains a public class `gsEventArgs` which is an extension of the C# class EventArgs. This class is used to set and get events as they occur. `GhostNET` will create these payloads and deliver them back to the application layer's `ProgressCallBack` method asynchronously.

    public class gsEventArgs : EventArgs
    {
        private bool m_completed;
        private int m_progress;
        private gsParamState_t m_param;
        public bool Completed
        {
            get { return m_completed; }
        }
        public gsParamState_t Params
        {
            get { return m_param; }
        }
        public int Progress
        {
            get { return m_progress; }
        }
        public gsEventArgs(bool completed, int progress, gsParamState_t param)
        {
            m_completed = completed;
            m_progress = progress;
            m_param = param;
        }
    }

## GSNET

This class should be instantiated as a member variable in your application with callback definitions setup as required.

Handlers for asynchronous operations can injected by providing your own bespoke callback methods to your instance's `ProgressCallBack` function.

    /* Set up ghostscript with callbacks for system updates */
    m_ghostscript = new GSNET();
    m_ghostscript.ProgressCallBack += new GSNET.Progress(gsProgress);
    m_ghostscript.StdIOCallBack += new GSNET.StdIO(gsIO);
    m_ghostscript.DLLProblemCallBack += new GSNET.DLLProblem(gsDLL);
    m_ghostscript.PageRenderedCallBack += new GSNET.PageRendered(gsPageRendered);
    m_ghostscript.DisplayDeviceOpen();

    /* example callback stubs for asynchronous operations */
    private void gsProgress(gsEventArgs asyncInformation)
    {
        Console.WriteLine($"gsProgress().progress:{asyncInformation.Progress}");

        if (asyncInformation.Completed) // task complete
        {
            // what was the task?
            switch (asyncInformation.Params.task)
            {
                case GS_Task_t.CREATE_XPS:
                    Console.WriteLine($"CREATE_XPS.outputfile:");
                    Console.WriteLine($"{asyncInformation.Params.result.outputfile}");
                    break;

                case GS_Task_t.PS_DISTILL:
                    Console.WriteLine($"PS_DISTILL.outputfile:");
                    Console.WriteLine($"{asyncInformation.Params.result.outputfile}");
                    break;

                case GS_Task_t.SAVE_RESULT:

                    break;

                case GS_Task_t.DISPLAY_DEV_THUMBS:

                    break;

                case GS_Task_t.DISPLAY_DEV_RUN_FILE:

                    break;

                case GS_Task_t.DISPLAY_DEV_PDF:

                    break;

                case GS_Task_t.DISPLAY_DEV_NON_PDF:

                    break;

                default:

                    break;
            }

            // task failed
            if (asyncInformation.Params.result == GS_Result_t.gsFAILED)
            {
                switch (asyncInformation.Params.task)
                {
                    case GS_Task_t.CREATE_XPS:

                        break;

                    case GS_Task_t.PS_DISTILL:

                        break;

                    case GS_Task_t.SAVE_RESULT:

                        break;

                    default:

                        break;
                }
                return;
            }

            // task cancelled
            if (asyncInformation.Params.result == GS_Result_t.gsCANCELLED)
            {

            }
        }
        else // task is still running
        {
            switch (asyncInformation.Params.task)
            {
                case GS_Task_t.CREATE_XPS:

                    break;

                case GS_Task_t.PS_DISTILL:

                    break;

                case GS_Task_t.SAVE_RESULT:

                    break;
            }
        }
    }

    private void gsIO(String message, int len)
    {
        Console.WriteLine($"gsIO().message:{message}, length:{len}");
    }

    private void gsDLL(String message)
    {
        Console.WriteLine($"gsDLL().message:{message}");
    }

    private void gsPageRendered(int width,
                                int height,
                                int raster,
                                IntPtr data,
                                gsParamState_t state)
    {

    };

> NOTE
> Once a Ghostscript operation is in progress any defined callback functions will be called as the operation runs up unto completion. These callback methods are essential for your application to interpret activity events and react accordingly.

An explanation of callbacks and the available public methods within `GSNET` are explained below.

### Delegates

To handle asynchronous events `GhostNET` has four delegates which define callback methods that an application can assign to.

Callback | Description
--- | ---
`DLLProblemCallBack` | Occurs if there is some issue with the Ghostscript DLL
`StdIOCallBack` | Occurs if Ghostscript outputs something to `stderr` or `stdout`
`ProgressCallBack` | Occurs as Ghostscript makes its way through a file
`PageRenderedCallBack` | Occurs when a page has been rendered and the data from the display device is ready

#### DLLProblemCallBack

    internal delegate void DLLProblem(String mess);
    internal event DLLProblem DLLProblemCallBack;

#### StdIOCallBack

    internal delegate void StdIO(String mess,
                                 int len);
    internal event StdIO StdIOCallBack;

#### ProgressCallBack

    internal delegate void Progress(gsEventArgs info);
    internal event Progress ProgressCallBack;

#### PageRenderedCallBack

    internal delegate void PageRendered(int width,
                                        int height,
                                        int raster,
                                     IntPtr data,
                             gsParamState_t state);
    internal event PageRendered PageRenderedCallBack;

### GetVersion

Use this method to get Ghostscript version info as a handy `String`.

    public String GetVersion()

    String gs_vers = m_ghostscript.GetVersion();

> NOTE
> An exception will be thrown if there is any issue with the Ghostscript DLL.

### DisplayDeviceOpen

Sets up the display device ahead of time.

    public gsParamState_t DisplayDeviceOpen()

    m_ghostscript.DisplayDeviceOpen();

> NOTE
> Calling this method instantiates ghostscript and configures the encoding and the callbacks for the display device.

### DisplayDeviceClose

Closes the display device and deletes the instance.

    public gsParamState_t DisplayDeviceClose()

    m_ghostscript.DisplayDeviceClose();

> NOTE
> Calling this method deletes ghostscript.

### GetPageCount

Use this method to get the number of pages in a supplied document.

    public int GetPageCount(String fileName)

    int page_number = m_ghostscript.GetPageCount("my_document.pdf");

> NOTE
> If Ghostscript is unable to determine the page count then this method will return `-1`.

### CreateXPS

Launches a thread to create an XPS document for Windows printing. This method is asynchronous and logic should be hooked into your application upon GSNET instantiation to interpret progress.

    public gsStatus CreateXPS(String fileName,
                                 int resolution,
                                 int num_pages,
                              double width,
                              double height,
                                bool fit_page,
                                 int firstpage,
                                 int lastpage)

    m_ghostscript.CreateXPS("my_document.pdf",
                            300,
                            10,
                            1000,
                            1000,
                            true,
                            0,
                            9);

asynchronous

### DistillPS

Launches a thread rendering all the pages of a supplied PostScript file to a PDF.

    public gsStatus DistillPS(String fileName, int resolution)

    m_ghostscript.DistillPS("my_postscript_document.ps", 300);

asynchronous

### DisplayDeviceRunFile

Launches a thread to run a file with the display device.

    public gsStatus DisplayDeviceRunFile(String fileName,
                                         double zoom,
                                           bool aa, // anti-aliasing value
                                            int firstpage,
                                            int lastpage)

    m_ghostscript.DisplayDeviceRunFile("my_document.pdf",
                                       1.0,
                                       true,
                                       0,
                                       9);

asynchronous

### DisplayDeviceRenderThumbs

Launches a thread rendering all the pages with the display device to collect thumbnail images.

Recommended zoom level for thumbnails is between 0.05 and 0.2, additionally anti-aliasing is probably not required.

    public gsStatus DisplayDeviceRenderThumbs(String fileName,
                                              double zoom,
                                                bool aa)

    m_ghostscript.DisplayDeviceRenderThumbs("my_document.pdf",
                                            0.1,
                                            false);

asynchronous

### DisplayDeviceRenderPages

Launches a thread rendering a set of pages with the display device. For use with languages that can be indexed via pages which include PDF and XPS. 1

    public gsStatus DisplayDeviceRenderPages(String fileName,
                                                int first_page,
                                                int last_page,
                                             double zoom)

    m_ghostscript.DisplayDeviceRenderPages("my_document.pdf",
                                           0,
                                           9,
                                           1.0);

asynchronous

### GetStatus

Returns the current status of `Ghostscript`.

    public gsStatus GetStatus()

    gsStatus status = m_ghostscript.GetStatus();

### Cancel

Cancels asynchronous operations.

    public void Cancel()

    m_ghostscript.Cancel();

### GhostscriptException

An application developer can log any exceptions in this public class as required by editing the constructor.

    public class GhostscriptException : Exception
    {
        public GhostscriptException(string message) : base(message)
        {
            // Report exceptions as required
        }
    }

## Notes

#### 1: Ghostscript & Page Description Languages

Ghostscript handles the following PDLs: `PCL` `PDF` `PS` `XPS`.

`PCL` and `PS` do not allow random access, meaning that, to print page 2 in a 100 page document, Ghostscript has to read the entire document stream of 100 pages.

On the other hand, `PDF` and `XPS` allow for going directly to page 2 and then only dealing with that content. The tasks `DISPLAY_DEV_NON_PDF` and `DISPLAY_DEV_PDF` keep track of what sort of input Ghostscript is dealing with and enables the application to direct progress or completion callbacks accordingly.

About
Enums
Tasks
Results
Status
The Parameter Struct
Parameters explained
The Event class
GSNET
Delegates
GetVersion
DisplayDeviceOpen
DisplayDeviceClose
GetPageCount
CreateXPS
DistillPS
DisplayDeviceRunFile
DisplayDeviceRenderThumbs
DisplayDeviceRenderPages
GetStatus
Cancel
GhostscriptException
Notes