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