1 /* Copyright (C) 2001-2012 Artifex Software, Inc. 2 All Rights Reserved. 3 4 This software is provided AS-IS with no warranty, either express or 5 implied. 6 7 This software is distributed under license and may not be copied, 8 modified or distributed except as expressly authorized under the terms 9 of the license contained in the file LICENSE in this distribution. 10 11 Refer to licensing information at http://www.artifex.com or contact 12 Artifex Software, Inc., 7 Mt. Lassen Drive - Suite A-134, San Rafael, 13 CA 94903, U.S.A., +1(415)492-9861, for further information. 14 */ 15 16 17 18 /* 19 * Public API for Ghostscript interpreter 20 * for use both as DLL and for static linking. 21 * 22 * Should work for Windows, OS/2, Linux, Mac. 23 * 24 * DLL exported functions should be as similar as possible to imain.c 25 * You will need to include "ierrors.h". 26 * 27 * Current problems: 28 * 1. Ghostscript does not support multiple instances. 29 * 2. Global variables in gs_main_instance_default() 30 * and gsapi_instance_counter 31 */ 32 33 /* Exported functions may need different prefix 34 * GSDLLEXPORT marks functions as exported 35 * GSDLLAPI is the calling convention used on functions exported 36 * by Ghostscript 37 * GSDLLCALL is used on callback functions called by Ghostscript 38 * When you include this header file in the caller, you may 39 * need to change the definitions by defining these 40 * before including this header file. 41 * Make sure you get the calling convention correct, otherwise your 42 * program will crash either during callbacks or soon after returning 43 * due to stack corruption. 44 */ 45 46 #ifndef iapi_INCLUDED 47 # define iapi_INCLUDED 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 #if defined(_WINDOWS_) || defined(__WINDOWS__) 54 # ifndef _Windows 55 # define _Windows 56 # endif 57 #endif 58 59 #ifdef _Windows 60 # ifndef GSDLLEXPORT 61 # define GSDLLEXPORT __declspec(dllexport) 62 # endif 63 # ifndef GSDLLAPI 64 # define GSDLLAPI __stdcall 65 # endif 66 # ifndef GSDLLCALL 67 # define GSDLLCALL __stdcall 68 # endif 69 #endif /* _Windows */ 70 71 #if defined(OS2) && defined(__IBMC__) 72 # ifndef GSDLLAPI 73 # define GSDLLAPI _System 74 # endif 75 # ifndef GSDLLCALL 76 # define GSDLLCALL _System 77 # endif 78 #endif /* OS2 && __IBMC */ 79 80 #ifdef __MACOS__ 81 # pragma export on 82 #endif 83 84 #ifndef GSDLLEXPORT 85 # define GSDLLEXPORT 86 #endif 87 #ifndef GSDLLAPI 88 # define GSDLLAPI 89 #endif 90 #ifndef GSDLLCALL 91 # define GSDLLCALL 92 #endif 93 94 #if defined(__IBMC__) 95 # define GSDLLAPIPTR * GSDLLAPI 96 # define GSDLLCALLPTR * GSDLLCALL 97 #else 98 # define GSDLLAPIPTR GSDLLAPI * 99 # define GSDLLCALLPTR GSDLLCALL * 100 #endif 101 102 #ifndef display_callback_DEFINED 103 # define display_callback_DEFINED 104 typedef struct display_callback_s display_callback; 105 #endif 106 107 typedef struct gsapi_revision_s { 108 const char *product; 109 const char *copyright; 110 long revision; 111 long revisiondate; 112 } gsapi_revision_t; 113 114 /* Get version numbers and strings. 115 * This is safe to call at any time. 116 * You should call this first to make sure that the correct version 117 * of the Ghostscript is being used. 118 * pr is a pointer to a revision structure. 119 * len is the size of this structure in bytes. 120 * Returns 0 if OK, or if len too small (additional parameters 121 * have been added to the structure) it will return the required 122 * size of the structure. 123 */ 124 GSDLLEXPORT int GSDLLAPI 125 gsapi_revision(gsapi_revision_t *pr, int len); 126 127 /* 128 * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 129 * Ghostscript supports only one instance. 130 * The current implementation uses a global static instance 131 * counter to make sure that only a single instance is used. 132 * If you try to create two instances, the second attempt 133 * will return < 0 and set pinstance to NULL. 134 * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 135 */ 136 /* Create a new instance of Ghostscript. 137 * This instance is passed to most other API functions. 138 * The caller_handle will be provided to callback functions. 139 */ 140 141 GSDLLEXPORT int GSDLLAPI 142 gsapi_new_instance(void **pinstance, void *caller_handle); 143 144 /* 145 * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 146 * Ghostscript supports only one instance. 147 * The current implementation uses a global static instance 148 * counter to make sure that only a single instance is used. 149 * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 150 */ 151 /* Destroy an instance of Ghostscript 152 * Before you call this, Ghostscript must have finished. 153 * If Ghostscript has been initialised, you must call gsapi_exit() 154 * before gsapi_delete_instance. 155 */ 156 GSDLLEXPORT void GSDLLAPI 157 gsapi_delete_instance(void *instance); 158 159 /* Set the callback functions for stdio 160 * The stdin callback function should return the number of 161 * characters read, 0 for EOF, or -1 for error. 162 * The stdout and stderr callback functions should return 163 * the number of characters written. 164 * If a callback address is NULL, the real stdio will be used. 165 */ 166 GSDLLEXPORT int GSDLLAPI 167 gsapi_set_stdio(void *instance, 168 int (GSDLLCALLPTR stdin_fn)(void *caller_handle, char *buf, int len), 169 int (GSDLLCALLPTR stdout_fn)(void *caller_handle, const char *str, int len), 170 int (GSDLLCALLPTR stderr_fn)(void *caller_handle, const char *str, int len)); 171 172 /* Set the callback function for polling. 173 * This is used for handling window events or cooperative 174 * multitasking. This function will only be called if 175 * Ghostscript was compiled with CHECK_INTERRUPTS 176 * as described in gpcheck.h. 177 * The polling function should return 0 if all is well, 178 * and negative if it wants ghostscript to abort. 179 * The polling function must be fast. 180 */ 181 GSDLLEXPORT int GSDLLAPI gsapi_set_poll(void *instance, 182 int (GSDLLCALLPTR poll_fn)(void *caller_handle)); 183 184 /* Set the display device callback structure. 185 * If the display device is used, this must be called 186 * after gsapi_new_instance() and before gsapi_init_with_args(). 187 * See gdevdisp.h for more details. 188 */ 189 GSDLLEXPORT int GSDLLAPI gsapi_set_display_callback( 190 void *instance, display_callback *callback); 191 192 /* Initialise the interpreter. 193 * This calls gs_main_init_with_args() in imainarg.c 194 * 1. If quit or EOF occur during gsapi_init_with_args(), 195 * the return value will be e_Quit. This is not an error. 196 * You must call gsapi_exit() and must not call any other 197 * gsapi_XXX functions. 198 * 2. If usage info should be displayed, the return value will be e_Info 199 * which is not an error. Do not call gsapi_exit(). 200 * 3. Under normal conditions this returns 0. You would then 201 * call one or more gsapi_run_*() functions and then finish 202 * with gsapi_exit(). 203 */ 204 GSDLLEXPORT int GSDLLAPI gsapi_init_with_args(void *instance, 205 int argc, char **argv); 206 207 /* 208 * The gsapi_run_* functions are like gs_main_run_* except 209 * that the error_object is omitted. 210 * If these functions return <= -100, either quit or a fatal 211 * error has occured. You then call gsapi_exit() next. 212 * The only exception is gsapi_run_string_continue() 213 * which will return e_NeedInput if all is well. 214 */ 215 216 GSDLLEXPORT int GSDLLAPI 217 gsapi_run_string_begin(void *instance, 218 int user_errors, int *pexit_code); 219 220 GSDLLEXPORT int GSDLLAPI 221 gsapi_run_string_continue(void *instance, 222 const char *str, unsigned int length, int user_errors, int *pexit_code); 223 224 GSDLLEXPORT int GSDLLAPI 225 gsapi_run_string_end(void *instance, 226 int user_errors, int *pexit_code); 227 228 GSDLLEXPORT int GSDLLAPI 229 gsapi_run_string_with_length(void *instance, 230 const char *str, unsigned int length, int user_errors, int *pexit_code); 231 232 GSDLLEXPORT int GSDLLAPI 233 gsapi_run_string(void *instance, 234 const char *str, int user_errors, int *pexit_code); 235 236 GSDLLEXPORT int GSDLLAPI 237 gsapi_run_file(void *instance, 238 const char *file_name, int user_errors, int *pexit_code); 239 240 /* Exit the interpreter. 241 * This must be called on shutdown if gsapi_init_with_args() 242 * has been called, and just before gsapi_delete_instance(). 243 */ 244 GSDLLEXPORT int GSDLLAPI 245 gsapi_exit(void *instance); 246 247 /* Visual Tracer */ 248 /* This function is only for debug purpose clients */ 249 struct vd_trace_interface_s; 250 GSDLLEXPORT void GSDLLAPI 251 gsapi_set_visual_tracer(struct vd_trace_interface_s *I); 252 253 /* function prototypes */ 254 typedef int (GSDLLAPIPTR PFN_gsapi_revision)( 255 gsapi_revision_t *pr, int len); 256 typedef int (GSDLLAPIPTR PFN_gsapi_new_instance)( 257 void **pinstance, void *caller_handle); 258 typedef void (GSDLLAPIPTR PFN_gsapi_delete_instance)( 259 void *instance); 260 typedef int (GSDLLAPIPTR PFN_gsapi_set_stdio)(void *instance, 261 int (GSDLLCALLPTR stdin_fn)(void *caller_handle, char *buf, int len), 262 int (GSDLLCALLPTR stdout_fn)(void *caller_handle, const char *str, int len), 263 int (GSDLLCALLPTR stderr_fn)(void *caller_handle, const char *str, int len)); 264 typedef int (GSDLLAPIPTR PFN_gsapi_set_poll)(void *instance, 265 int(GSDLLCALLPTR poll_fn)(void *caller_handle)); 266 typedef int (GSDLLAPIPTR PFN_gsapi_set_display_callback)( 267 void *instance, display_callback *callback); 268 typedef int (GSDLLAPIPTR PFN_gsapi_init_with_args)( 269 void *instance, int argc, char **argv); 270 typedef int (GSDLLAPIPTR PFN_gsapi_run_string_begin)( 271 void *instance, int user_errors, int *pexit_code); 272 typedef int (GSDLLAPIPTR PFN_gsapi_run_string_continue)( 273 void *instance, const char *str, unsigned int length, 274 int user_errors, int *pexit_code); 275 typedef int (GSDLLAPIPTR PFN_gsapi_run_string_end)( 276 void *instance, int user_errors, int *pexit_code); 277 typedef int (GSDLLAPIPTR PFN_gsapi_run_string_with_length)( 278 void *instance, const char *str, unsigned int length, 279 int user_errors, int *pexit_code); 280 typedef int (GSDLLAPIPTR PFN_gsapi_run_string)( 281 void *instance, const char *str, 282 int user_errors, int *pexit_code); 283 typedef int (GSDLLAPIPTR PFN_gsapi_run_file)(void *instance, 284 const char *file_name, int user_errors, int *pexit_code); 285 typedef int (GSDLLAPIPTR PFN_gsapi_exit)(void *instance); 286 typedef void (GSDLLAPIPTR PFN_gsapi_set_visual_tracer) 287 (struct vd_trace_interface_s *I); 288 289 #ifdef __MACOS__ 290 #pragma export off 291 #endif 292 293 #ifdef __cplusplus 294 } /* extern 'C' protection */ 295 #endif 296 297 #endif /* iapi_INCLUDED */ 298