1 /* 2 Copyright (C) 2015-2021, Dirk Krause 3 SPDX-License-Identifier: BSD-3-Clause 4 */ 5 6 /* 7 WARNING: This file was generated by the dkct program (see 8 http://dktools.sourceforge.net/ for details). 9 Changes you make here will be lost if dkct is run again! 10 You should modify the original source and run dkct on it. 11 Original source: dk4strm.ctr 12 */ 13 14 #ifndef DK4STRM_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4STRM_H_INCLUDED 1 17 18 19 /** @file 20 Generic dk4_stream_t interface for 21 input and output operations. 22 23 CRT on Windows: Optional. 24 */ 25 26 #ifndef DK4CONF_H_INCLUDED 27 #if DK4_BUILDING_DKTOOLS4 28 #include "dk4conf.h" 29 #else 30 #include <dktools-4/dk4conf.h> 31 #endif 32 #endif 33 34 #ifndef DK4TYPES_H_INCLUDED 35 #if DK4_BUILDING_DKTOOLS4 36 #include <libdk4base/dk4types.h> 37 #else 38 #include <dktools-4/dk4types.h> 39 #endif 40 #endif 41 42 #ifndef DK4ERROR_H_INCLUDED 43 #if DK4_BUILDING_DKTOOLS4 44 #include <libdk4base/dk4error.h> 45 #else 46 #include <dktools-4/dk4error.h> 47 #endif 48 #endif 49 50 #ifndef STDLIB_H_INCLUDED 51 #include <stdlib.h> 52 #define STDLIB_H_INCLUDED 1 53 #endif 54 55 /** API for stream function. 56 */ 57 typedef struct { 58 void *d; /**< In: Low level data. */ 59 char *b; /**< In: Buffer for data to write or read. */ 60 size_t sz_in; /**< In: Number of bytes to write or read. */ 61 size_t sz_out; /**< Out: Number of bytes written or read. */ 62 int cmd; /**< In: Command to execute. */ 63 int res; /**< Out: Low level operation result. */ 64 } dk4_stream_api_t; 65 66 /** Function to execute one low level command. 67 */ 68 typedef void dk4_stream_api_fct_t(dk4_stream_api_t *); 69 70 /** Generic I/O stream. 71 */ 72 typedef struct { 73 dk4_stream_api_fct_t *fct; /**< Function for low level operations. */ 74 void *d; /**< Low level data object. */ 75 char *bi; /**< Buffer for input. */ 76 char *bo; /**< Buffer for output. */ 77 dk4_um_t bwr; /**< Number of bytes written. */ 78 size_t szbi; /**< Input buffer size. */ 79 size_t szbo; /**< Output buffer size. */ 80 size_t usbi; /**< Bytes used in input buffer. */ 81 size_t usbo; /**< Bytes used in output buffer. */ 82 size_t rebi; /**< Read bytes from input buffer. */ 83 int fl; /**< Flags for allowed operations. */ 84 int feoi; /**< Flag: Found end of input. */ 85 int bwo; /**< Flag: Numeric overflow in bwr. */ 86 int oenc; /**< Output encoding for 32 bit characters. */ 87 int zreof; /**< Flag: Zero bytes read indicates EOF. */ 88 } dk4_stream_t; 89 90 #ifdef __cplusplus 91 extern "C" { 92 #endif 93 94 /** Open new stream, allocate memory. 95 @param obj Low level object. 96 @param fct Low level function. 97 @param fl Read/write flags: DK4_STREAM_READ, DK4_STREAM_WRITE 98 or (DK4_STREAM_READ | DK4_STREAM_WRITE). 99 @param ibs Input buffer size (0 for default). 100 @param obs Output buffer size (0 for default). 101 @param erp Error report, may be NULL. 102 @return Pointer to new stream on success, NULL on error. 103 104 Error codes: 105 - DK4_E_INVALID_ARGUMENTS<br> 106 if obj or fct is NULL or fl is invalid, 107 - DK4_E_MATH_OVERFLOW<br> 108 if ibs or obs is too large, 109 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 110 if allocation of input or output buffer failed. 111 */ 112 dk4_stream_t * 113 dk4stream_open( 114 void *obj, 115 dk4_stream_api_fct_t *fct, 116 int fl, 117 size_t ibs, 118 size_t obs, 119 dk4_er_t *erp 120 ); 121 122 /** Close data stream, release memory. 123 @param strm Stream to close. 124 @param erp Error report, may be NULL. 125 @return 1 on success, 0 on error. 126 127 Error codes: 128 - DK4_E_INVALID_ARGUMENTS<br> 129 if strm is NULL, 130 - DK4_E_WRITE_FAILED<br> 131 if writing one ore multiple bytes to the stream failed, 132 - DK4_E_FLUSH_FAILED<br> 133 if flushing data downwards failed, 134 - DK4_E_CLOSE_FAILED<br> 135 if closing downward data failed. 136 */ 137 int 138 dk4stream_close(dk4_stream_t *strm, dk4_er_t *erp); 139 140 /** Write one byte to output stream. 141 @param strm Output stream. 142 @param c Byte to write. 143 @param erp Error report, may be NULL. 144 @return 1 on success, 0 on error. 145 146 Error codes: 147 - DK4_E_INVALID_ARGUMENTS<br> 148 if strm is NULL or not opened for writing, 149 - DK4_E_WRITE_FAILED<br> 150 if writing one ore multiple bytes to the stream failed, 151 - DK4_E_FLUSH_FAILED<br> 152 if flushing data downwards failed. 153 */ 154 int 155 dk4stream_write_byte(dk4_stream_t *strm, char c, dk4_er_t *erp); 156 157 /** Write a buffer to output stream. 158 @param strm Output stream. 159 @param b Buffer start address. 160 @param sz Number of bytes to write. 161 @param erp Error report, may be NULL. 162 @return 1 on success (all bytes written), 0 on error. 163 164 Error codes: 165 - DK4_E_INVALID_ARGUMENTS<br> 166 if strm is NULL or not opened for writing, 167 - DK4_E_WRITE_FAILED<br> 168 if writing one ore multiple bytes to the stream failed, 169 - DK4_E_FLUSH_FAILED<br> 170 if flushing data downwards failed. 171 */ 172 int 173 dk4stream_write(dk4_stream_t *strm, const void *b, size_t sz, dk4_er_t *erp); 174 175 176 /** Write a char string to the stream. 177 @param strm Output stream. 178 @param str String to write. 179 @param erp Error report, may be NULL. 180 @return 1 on success (all bytes written), 0 on error. 181 182 Error codes: 183 - DK4_E_INVALID_ARGUMENTS<br> 184 if strm is NULL or not opened for writing, 185 - DK4_E_WRITE_FAILED<br> 186 if writing one ore multiple bytes to the stream failed, 187 - DK4_E_FLUSH_FAILED<br> 188 if flushing data downwards failed. 189 */ 190 int 191 dk4stream_write_char_string(dk4_stream_t *strm, const char *str, dk4_er_t *erp); 192 193 /** Flush stream input and output data. 194 @param strm Stream to flush. 195 @param flfl Flush type: 0=just flush output buffer 196 contents to low level object, 1=0+flush low level object, 197 2=1+flush all low level objects recursively (for output filtering). 198 @param erp Error report, may be NULL. 199 @return 1 on success, 0 on error. 200 201 Error codes: 202 - DK4_E_INVALID_ARGUMENTS<br> 203 if strm is NULL. 204 - DK4_E_WRITE_FAILED<br> 205 if writing one ore multiple bytes to the stream failed 206 - DK4_E_FLUSH_FAILED<br> 207 if flushing data downwards failed. 208 */ 209 int 210 dk4stream_flush(dk4_stream_t *strm, int flfl, dk4_er_t *erp); 211 212 /** Flush stream output data. 213 @param strm Stream to flush. 214 @param flfl Flush type: 0=just flush output buffer 215 contents to low level object, 1=0+flush low level object, 216 2=1+flush all low level objects recursively (for output filtering). 217 @param erp Error report, may be NULL. 218 @return 1 on success, 0 on error. 219 220 Error codes: 221 - DK4_E_INVALID_ARGUMENTS<br> 222 if strm is NULL or not opened for writing, 223 - DK4_E_WRITE_FAILED<br> 224 if writing one ore multiple bytes to the stream failed, 225 - DK4_E_FLUSH_FAILED<br> 226 if flushing data downwards failed. 227 */ 228 int 229 dk4stream_flush_write(dk4_stream_t *strm, int flfl, dk4_er_t *erp); 230 231 /** Flush stream input data (discard data in input buffer). 232 @param strm Stream to flush. 233 @param erp Error report, may be NULL. 234 @return 1 on success, 0 on error. 235 236 Error codes: 237 - DK4_E_INVALID_ARGUMENTS<br> 238 if strm is NULL or not opened for writing. 239 */ 240 int 241 dk4stream_flush_read(dk4_stream_t *strm, dk4_er_t *erp); 242 243 /** Read a single character. 244 @param dst Pointer to variable for result. 245 @param strm Stream to read from. 246 @param erp Error report, may be NULL. 247 @return 1 on success, 0 on error. 248 249 Error codes: 250 - DK4_E_INVALID_ARGUMENTS<br> 251 if strm is NULL or not opened for reading, 252 */ 253 int 254 dk4stream_c8_read_byte(char *dst, dk4_stream_t *strm, dk4_er_t *erp); 255 256 /** Read multiple bytes into buffer. 257 @param b Pointer to buffer start address. 258 @param szptr Pointer to size variable, in: available size, 259 out: number of bytes read. 260 @param strm Stream to read from. 261 @param erp Error report, may be NULL. 262 @return 1 on success (there were bytes read), 0 on error. 263 264 Error codes: 265 - DK4_E_INVALID_ARGUMENTS<br> 266 if strm is NULL or not opened for reading, 267 - DK4_E_NOT_FOUND<br> 268 if end of input was detected in read attempt, 269 - DK4_E_READ_FAILED<br> 270 if a read attempt failed for other reasons. 271 */ 272 int 273 dk4stream_read(void *b, size_t *szptr, dk4_stream_t *strm, dk4_er_t *erp); 274 275 /** Get number of bytes written. 276 @param strm Stream to get number of bytes for. 277 @return Number of bytes written to the stream (number of bytes 278 received from the upside, not number of bytes written 279 downwards). 280 */ 281 dk4_um_t 282 dk4stream_bytes_written(const dk4_stream_t *strm); 283 284 /** Check for numeric overflow in number of bytes written. 285 @param strm Stream to check. 286 @return 1 if overflow occured, 0 if there was no overflow. 287 */ 288 int 289 dk4stream_overflow_bytes_written(const dk4_stream_t *strm); 290 291 /** Check whether end of input was found during read attempt. 292 @param strm Stream to check. 293 @return 1 if EOF was detected, 0 otherwise. 294 */ 295 int 296 dk4stream_found_eof(const dk4_stream_t *strm); 297 298 #ifdef __cplusplus 299 } 300 #endif 301 302 303 304 /** Flags whether read or write operations allowed. 305 */ 306 enum { 307 DK4_STREAM_READ = 1, /**< Reading from stream allowed. */ 308 DK4_STREAM_WRITE = 2 /**< Writing to stream allowed. */ 309 }; 310 311 312 313 /** Low level commands to execute in the stream API function. 314 The api.cmd is set to one of the values. 315 Depending on api.cmd, other api attributes must be set 316 on input or must be set as response by the low level function. 317 */ 318 enum { 319 /** Read data. 320 Input api.d: Low level data. 321 Input api.b: Input data buffer. 322 Input api.sz_in: Input data buffer 323 size. 324 Output api.res: 1=any bytes found, 325 0=no bytes found. 326 Output api.sz_out: Number of bytes 327 read into input 328 buffer. 329 */ 330 DK4_STREAM_API_READ = 1, 331 332 /** Write data. 333 Input api.d: Low level data. 334 Input api.b: Output data buffer. 335 Input api.sz_in: Output data buffer 336 size. 337 Output api.res: 1=all bytes 338 written, 339 0=not all bytes 340 written. 341 Output api.sz_out: Number of bytes 342 written. 343 */ 344 DK4_STREAM_API_WRITE , 345 346 /** Flush data. 347 Input api.d: Low level data. 348 Output api.res: 1=no error reported, 349 0=error reported. 350 */ 351 DK4_STREAM_API_FLUSH , 352 353 /** Check whether end of input is found. 354 Input api.d: Low level data. 355 Output api.res 1=end of input 356 reached, 357 0=not yet reached. 358 */ 359 DK4_STREAM_API_AT_END , 360 361 /** Close low level data. 362 Input api.d: Low level data. 363 Output api.res: 1=no error reported, 364 0=error reported. 365 */ 366 DK4_STREAM_API_CLOSE , 367 368 /** Check whether a read result of 0 369 indicates EOF. 370 Input api.d: Low level data. 371 Output api.res 1=reading zero bytes 372 indicates EOF, 0=no. 373 */ 374 DK4_STREAM_API_ZERO_READ_IS_EOF 375 }; 376 377 378 #endif 379