GhostMono

About

GhostMono is the C# interface into the GhostAPI library developed for Linux systems.

Enums

Tasks

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

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;
};

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 GhostMono 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("-dNOPAUSE");
    gsparams.args.Add("-dBATCH");
    gsparams.args.Add("-I%rom%Resource/Init/");
    gsparams.args.Add("-dSAFER");
    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.

GhostMono 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 GhostMono is a good starting point.

For full documentation on parameters refer to Ghostscript parameters.

The Event class

GhostMono contains a public class gsThreadCallBack. This class is used to set and get callback information as they occur. GhostMono will create these payloads and deliver them back to the application layer's ProgressCallBack method asynchronously.

public class gsThreadCallBack
{
    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 gsThreadCallBack(bool completed, int progress, gsParamState_t param)
    {
        m_completed = completed;
        m_progress = progress;
        m_param = param;
    }
}

GSMONO

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 GSMONO();
m_ghostscript.ProgressCallBack += new GSMONO.Progress(gsProgress);
m_ghostscript.StdIOCallBack += new GSMONO.StdIO(gsIO);
m_ghostscript.DLLProblemCallBack += new GSMONO.DLLProblem(gsDLL);
m_ghostscript.PageRenderedCallBack += new GSMONO.PageRendered(gsPageRendered);
m_ghostscript.DisplayDeviceOpen();

/* example callback stubs for asynchronous operations */
private void gsProgress(gsThreadCallBack 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 GSMONO are explained below.

Delegates

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

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.

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

DisplayDeviceRenderAll

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

public gsStatus DisplayDeviceRenderAll(String fileName, double zoom, bool aa, GS_Task_t task)

m_ghostscript.DisplayDeviceRenderAll("my_document.pdf",
                                     0.1,
                                     false,
                                     GS_Task_t.DISPLAY_DEV_THUMBS_NON_PDF);

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

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. ¹

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

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

GetStatus

Returns the current status of Ghostscript.

public gsStatus GetStatus()

gsStatus status = m_ghostscript.GetStatus();

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.