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