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.8.2.1 2003/12/12 22:08:04 giles 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 gs_main_instance_DEFINED 104 # define gs_main_instance_DEFINED 105 typedef struct gs_main_instance_s gs_main_instance; 106 #endif 107 #ifndef display_callback_DEFINED 108 # define display_callback_DEFINED 109 typedef struct display_callback_s display_callback; 110 #endif 111 112 typedef struct gsapi_revision_s { 113 const char *product; 114 const char *copyright; 115 long revision; 116 long revisiondate; 117 } gsapi_revision_t; 118 119 120 /* Get version numbers and strings. 121 * This is safe to call at any time. 122 * You should call this first to make sure that the correct version 123 * of the Ghostscript is being used. 124 * pr is a pointer to a revision structure. 125 * len is the size of this structure in bytes. 126 * Returns 0 if OK, or if len too small (additional parameters 127 * have been added to the structure) it will return the required 128 * size of the structure. 129 */ 130 GSDLLEXPORT int GSDLLAPI 131 gsapi_revision(gsapi_revision_t *pr, int len); 132 133 /* 134 * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 135 * Ghostscript supports only one instance. 136 * The current implementation uses a global static instance 137 * counter to make sure that only a single instance is used. 138 * If you try to create two instances, the second attempt 139 * will return < 0 and set pinstance to NULL. 140 * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 141 */ 142 /* Create a new instance of Ghostscript. 143 * This instance is passed to most other API functions. 144 * The caller_handle will be provided to callback functions. 145 */ 146 147 GSDLLEXPORT int GSDLLAPI 148 gsapi_new_instance(gs_main_instance **pinstance, void *caller_handle); 149 150 /* 151 * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 152 * Ghostscript supports only one instance. 153 * The current implementation uses a global static instance 154 * counter to make sure that only a single instance is used. 155 * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 156 */ 157 /* Destroy an instance of Ghostscript 158 * Before you call this, Ghostscript must have finished. 159 * If Ghostscript has been initialised, you must call gsapi_exit() 160 * before gsapi_delete_instance. 161 */ 162 GSDLLEXPORT void GSDLLAPI 163 gsapi_delete_instance(gs_main_instance *instance); 164 165 /* Set the callback functions for stdio 166 * The stdin callback function should return the number of 167 * characters read, 0 for EOF, or -1 for error. 168 * The stdout and stderr callback functions should return 169 * the number of characters written. 170 * If a callback address is NULL, the real stdio will be used. 171 */ 172 GSDLLEXPORT int GSDLLAPI 173 gsapi_set_stdio(gs_main_instance *instance, 174 int (GSDLLCALLPTR stdin_fn)(void *caller_handle, char *buf, int len), 175 int (GSDLLCALLPTR stdout_fn)(void *caller_handle, const char *str, int len), 176 int (GSDLLCALLPTR stderr_fn)(void *caller_handle, const char *str, int len)); 177 178 /* Set the callback function for polling. 179 * This is used for handling window events or cooperative 180 * multitasking. This function will only be called if 181 * Ghostscript was compiled with CHECK_INTERRUPTS 182 * as described in gpcheck.h. 183 * The polling function should return 0 if all is well, 184 * and negative if it wants ghostscript to abort. 185 * The polling function must be fast. 186 */ 187 GSDLLEXPORT int GSDLLAPI gsapi_set_poll(gs_main_instance *instance, 188 int (GSDLLCALLPTR poll_fn)(void *caller_handle)); 189 190 /* Set the display device callback structure. 191 * If the display device is used, this must be called 192 * after gsapi_new_instance() and before gsapi_init_with_args(). 193 * See gdevdisp.h for more details. 194 */ 195 GSDLLEXPORT int GSDLLAPI gsapi_set_display_callback( 196 gs_main_instance *instance, display_callback *callback); 197 198 199 /* Initialise the interpreter. 200 * This calls gs_main_init_with_args() in imainarg.c 201 * 1. If quit or EOF occur during gsapi_init_with_args(), 202 * the return value will be e_Quit. This is not an error. 203 * You must call gsapi_exit() and must not call any other 204 * gsapi_XXX functions. 205 * 2. If usage info should be displayed, the return value will be e_Info 206 * which is not an error. Do not call gsapi_exit(). 207 * 3. Under normal conditions this returns 0. You would then 208 * call one or more gsapi_run_*() functions and then finish 209 * with gsapi_exit(). 210 */ 211 GSDLLEXPORT int GSDLLAPI gsapi_init_with_args(gs_main_instance *instance, 212 int argc, char **argv); 213 214 /* 215 * The gsapi_run_* functions are like gs_main_run_* except 216 * that the error_object is omitted. 217 * If these functions return <= -100, either quit or a fatal 218 * error has occured. You then call gsapi_exit() next. 219 * The only exception is gsapi_run_string_continue() 220 * which will return e_NeedInput if all is well. 221 */ 222 223 GSDLLEXPORT int GSDLLAPI 224 gsapi_run_string_begin(gs_main_instance *instance, 225 int user_errors, int *pexit_code); 226 227 GSDLLEXPORT int GSDLLAPI 228 gsapi_run_string_continue(gs_main_instance *instance, 229 const char *str, unsigned int length, int user_errors, int *pexit_code); 230 231 GSDLLEXPORT int GSDLLAPI 232 gsapi_run_string_end(gs_main_instance *instance, 233 int user_errors, int *pexit_code); 234 235 GSDLLEXPORT int GSDLLAPI 236 gsapi_run_string_with_length(gs_main_instance *instance, 237 const char *str, unsigned int length, int user_errors, int *pexit_code); 238 239 GSDLLEXPORT int GSDLLAPI 240 gsapi_run_string(gs_main_instance *instance, 241 const char *str, int user_errors, int *pexit_code); 242 243 GSDLLEXPORT int GSDLLAPI 244 gsapi_run_file(gs_main_instance *instance, 245 const char *file_name, int user_errors, int *pexit_code); 246 247 248 /* Exit the interpreter. 249 * This must be called on shutdown if gsapi_init_with_args() 250 * has been called, and just before gsapi_delete_instance(). 251 */ 252 GSDLLEXPORT int GSDLLAPI 253 gsapi_exit(gs_main_instance *instance); 254 255 /* Visual Tracer */ 256 /* This function is only for debug purpose clients */ 257 struct vd_trace_interface_s; 258 GSDLLEXPORT void GSDLLAPI 259 gsapi_set_visual_tracer(struct vd_trace_interface_s *I); 260 261 262 /* function prototypes */ 263 typedef int (GSDLLAPIPTR PFN_gsapi_revision)( 264 gsapi_revision_t *pr, int len); 265 typedef int (GSDLLAPIPTR PFN_gsapi_new_instance)( 266 gs_main_instance **pinstance, void *caller_handle); 267 typedef void (GSDLLAPIPTR PFN_gsapi_delete_instance)( 268 gs_main_instance *instance); 269 typedef int (GSDLLAPIPTR PFN_gsapi_set_stdio)(gs_main_instance *instance, 270 int (GSDLLCALLPTR stdin_fn)(void *caller_handle, char *buf, int len), 271 int (GSDLLCALLPTR stdout_fn)(void *caller_handle, const char *str, int len), 272 int (GSDLLCALLPTR stderr_fn)(void *caller_handle, const char *str, int len)); 273 typedef int (GSDLLAPIPTR PFN_gsapi_set_poll)(gs_main_instance *instance, 274 int(GSDLLCALLPTR poll_fn)(void *caller_handle)); 275 typedef int (GSDLLAPIPTR PFN_gsapi_set_display_callback)( 276 gs_main_instance *instance, display_callback *callback); 277 typedef int (GSDLLAPIPTR PFN_gsapi_init_with_args)( 278 gs_main_instance *instance, int argc, char **argv); 279 typedef int (GSDLLAPIPTR PFN_gsapi_run_string_begin)( 280 gs_main_instance *instance, int user_errors, int *pexit_code); 281 typedef int (GSDLLAPIPTR PFN_gsapi_run_string_continue)( 282 gs_main_instance *instance, const char *str, unsigned int length, 283 int user_errors, int *pexit_code); 284 typedef int (GSDLLAPIPTR PFN_gsapi_run_string_end)( 285 gs_main_instance *instance, int user_errors, int *pexit_code); 286 typedef int (GSDLLAPIPTR PFN_gsapi_run_string_with_length)( 287 gs_main_instance *instance, const char *str, unsigned int length, 288 int user_errors, int *pexit_code); 289 typedef int (GSDLLAPIPTR PFN_gsapi_run_string)( 290 gs_main_instance *instance, const char *str, 291 int user_errors, int *pexit_code); 292 typedef int (GSDLLAPIPTR PFN_gsapi_run_file)(gs_main_instance *instance, 293 const char *file_name, int user_errors, int *pexit_code); 294 typedef int (GSDLLAPIPTR PFN_gsapi_exit)(gs_main_instance *instance); 295 typedef void (GSDLLAPIPTR PFN_gsapi_set_visual_tracer) 296 (struct vd_trace_interface_s *I); 297 298 299 #ifdef __MACOS__ 300 #pragma export off 301 #endif 302 303 #ifdef __cplusplus 304 } /* extern 'C' protection */ 305 #endif 306 307 #endif /* iapi_INCLUDED */ 308