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