1 /* Copyright (C) 1994, 1996, 1999 Aladdin Enterprises. 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: scommon.h,v 1.8 2002/06/16 05:00:54 lpd Exp $ */ 18 /* Definitions common to stream clients and implementors */ 19 20 #ifndef scommon_INCLUDED 21 # define scommon_INCLUDED 22 23 #include "gsmemory.h" 24 #include "gstypes.h" /* for gs_string */ 25 #include "gsstype.h" /* for extern_st */ 26 27 /* 28 * There are three major structures involved in the stream package. 29 * 30 * A stream is an "object" that owns a buffer, which it uses to implement 31 * byte-oriented sequential access in a standard way, and a set of 32 * procedures that handle things like buffer refilling. See stream.h 33 * for more information about streams. 34 */ 35 #ifndef stream_DEFINED 36 # define stream_DEFINED 37 typedef struct stream_s stream; 38 #endif 39 40 /* 41 * A stream_state records the state specific to a given variety of stream. 42 * The buffer processing function of a stream maintains this state. 43 */ 44 typedef struct stream_state_s stream_state; 45 46 /* 47 * A stream_template provides the information needed to create a stream. 48 * The client must fill in any needed setup parameters in the appropriate 49 * variety of stream_state, and then call the initialization function 50 * provided by the template. See strimpl.h for more information about 51 * stream_templates. 52 */ 53 typedef struct stream_template_s stream_template; 54 55 /* 56 * The stream package works with bytes, not chars. 57 * This is to ensure unsigned representation on all systems. 58 * A stream currently can only be read or written, not both. 59 * Note also that the read procedure returns an int, not a char or a byte; 60 * we use negative values to indicate exceptional conditions. 61 * (We cast these values to int explicitly, because some compilers 62 * don't do this if the other arm of a conditional is a byte.) 63 * 64 * Note that when a stream reaches an exceptional condition, that condition 65 * remains set until the client does something explicit to reset it. 66 * (There should be a 'sclearerr' procedure to do that, but there isn't.) 67 * In particular, if a read stream encounters an exceptional condition, 68 * it delivers the data it has in its buffer, and then all subsequent 69 * calls to read data (sgetc, sgets, etc.) will return the exceptional 70 * condition without reading any more actual data. 71 */ 72 /* End of data */ 73 #define EOFC ((int)(-1)) 74 /* Error */ 75 #define ERRC ((int)(-2)) 76 /* Interrupt */ 77 #define INTC ((int)(-3)) 78 /****** INTC IS NOT USED YET ******/ 79 /* Callout */ 80 #define CALLC ((int)(-4)) 81 #define max_stream_exception 4 82 /* The following hack is needed for initializing scan_char_array in iscan.c. */ 83 #define stream_exception_repeat(x) x, x, x, x 84 85 /* 86 * Define cursors for reading from or writing into a buffer. 87 * We lay them out this way so that we can alias 88 * the write pointer and the read limit. 89 */ 90 typedef struct stream_cursor_read_s { 91 const byte *ptr; 92 const byte *limit; 93 byte *_skip; 94 } stream_cursor_read; 95 typedef struct stream_cursor_write_s { 96 const byte *_skip; 97 byte *ptr; 98 byte *limit; 99 } stream_cursor_write; 100 typedef union stream_cursor_s { 101 stream_cursor_read r; 102 stream_cursor_write w; 103 } stream_cursor; 104 105 /* 106 * Define the prototype for the procedures known to both the generic 107 * stream code and the stream implementations. 108 */ 109 110 /* Initialize the stream state (after the client parameters are set). */ 111 #define stream_proc_init(proc)\ 112 int proc(stream_state *) 113 114 /* Process a buffer. See strimpl.h for details. */ 115 #define stream_proc_process(proc)\ 116 int proc(stream_state *, stream_cursor_read *,\ 117 stream_cursor_write *, bool) 118 119 /* Release the stream state when closing. */ 120 #define stream_proc_release(proc)\ 121 void proc(stream_state *) 122 123 /* Initialize the client parameters to default values. */ 124 #define stream_proc_set_defaults(proc)\ 125 void proc(stream_state *) 126 127 /* Reinitialize any internal stream state. Note that this does not */ 128 /* affect buffered data. We declare this as returning an int so that */ 129 /* it can be the same as the init procedure; however, reinit cannot fail. */ 130 #define stream_proc_reinit(proc)\ 131 int proc(stream_state *) 132 133 /* Report an error. Note that this procedure is stored in the state, */ 134 /* not in the main stream structure. */ 135 #define stream_proc_report_error(proc)\ 136 int proc(stream_state *, const char *) 137 stream_proc_report_error(s_no_report_error); 138 139 /* 140 * Some types of streams have the ability to read their parameters from 141 * a parameter list, and to write all (or only the non-default) 142 * parameters to a parameter list. Since these are not virtual 143 * procedures for the stream (they operate on stream_state structures 144 * even if no actual stream has been created), we name them differently. 145 */ 146 #define stream_state_proc_get_params(proc, state_type)\ 147 int proc(gs_param_list *plist, const state_type *ss, bool all) 148 #define stream_state_proc_put_params(proc, state_type)\ 149 int proc(gs_param_list *plist, state_type *ss) 150 151 /* 152 * Define a generic stream state. If a processing procedure has no 153 * state of its own, it can use stream_state; otherwise, it must 154 * create a "subclass". There is a hack in stream.h to allow the stream 155 * itself to serve as the "state" of a couple of heavily used stream types. 156 * 157 * In order to simplify the structure descriptors for concrete streams, 158 * we require that the generic stream state not contain any pointers 159 * to garbage-collectable storage. 160 */ 161 #define STREAM_MAX_ERROR_STRING 79 162 #define stream_state_common\ 163 const stream_template *template;\ 164 gs_memory_t *memory;\ 165 stream_proc_report_error((*report_error));\ 166 int min_left; /* required bytes for lookahead */ \ 167 char error_string[STREAM_MAX_ERROR_STRING + 1] 168 struct stream_state_s { 169 stream_state_common; 170 }; 171 172 extern_st(st_stream_state); 173 #define public_st_stream_state() /* in stream.c */\ 174 gs_public_st_simple(st_stream_state, stream_state, "stream_state") 175 176 #endif /* scommon_INCLUDED */ 177