nanocoat/include/sjme/stream.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * Stream support.
  12  *
  13  * @file stream.h
  14  * @since 2023/12/30
  15  */
  16
  17 #ifndef SQUIRRELJME_STREAM_H
  18 #define SQUIRRELJME_STREAM_H
  19
  20 #include "sjme/nvm.h"
  21
  22 /* Anti-C++. */
  23 #ifdef __cplusplus
  24         #ifndef SJME_CXX_IS_EXTERNED
  25                 #define SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_SQUIRRELJME_STREAM_H
  27 extern "C" {
  28         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  29 #endif     /* #ifdef __cplusplus */
  30
  31 /*--------------------------------------------------------------------------*/
  32
  33 /**
  34  * Represents a data stream that can be read from.
  35  *
  36  * @since 2023/12/30
  37  */
  38 typedef struct sjme_stream_inputCore sjme_stream_inputCore;
  39
  40 /**
  41  * Represents a data stream that can be read from.
  42  *
  43  * @since 2023/12/30
  44  */
  45 typedef struct sjme_stream_inputCore* sjme_stream_input;
  46
  47 /**
  48  * The core output stream which is written to with data.
  49  *
  50  * @since 2024/01/09
  51  */
  52 typedef struct sjme_stream_outputCore sjme_stream_outputCore;
  53
  54 /**
  55  * Represents a data stream that can be written to.
  56  *
  57  * @since 2023/12/30
  58  */
  59 typedef struct sjme_stream_outputCore* sjme_stream_output;
  60
  61 /**
  62  * Determines the number of bytes which are quickly available before blocking
  63  * takes effect.
  64  *
  65  * @param stream The stream to read from.
  66  * @param outAvail The number of bytes which are available.
  67  * @return On any resultant error.
  68  * @since 2024/01/01
  69  */
  70 typedef sjme_errorCode (*sjme_stream_inputAvailableFunc)(
  71         sjme_attrInNotNull sjme_stream_input stream,
  72         sjme_attrOutNotNull sjme_attrOutNegativeOnePositive sjme_jint* outAvail);
  73
  74 /**
  75  * Closes the given input stream and frees up any resources.
  76  *
  77  * @param stream The stream to close.
  78  * @return On any resultant error.
  79  * @since 2024/01/01
  80  */
  81 typedef sjme_errorCode (*sjme_stream_inputCloseFunc)(
  82         sjme_attrInNotNull sjme_stream_input stream);
  83
  84 /**
  85  * Reads from the given input stream and writes to the destination buffer.
  86  *
  87  * @param stream The stream to read from.
  88  * @param readCount The number of bytes which were read, if end of stream is
  89  * reached this will be @c -1 .
  90  * @param dest The destination buffer.
  91  * @param length The number of bytes to read.
  92  * @return Any resultant error, if any.
  93  * @since 2024/01/01
  94  */
  95 typedef sjme_errorCode (*sjme_stream_inputReadFunc)(
  96         sjme_attrInNotNull sjme_stream_input stream,
  97         sjme_attrOutNotNull sjme_attrOutNegativeOnePositive sjme_jint* readCount,
  98         sjme_attrOutNotNullBuf(length) sjme_pointer dest,
  99         sjme_attrInPositive sjme_jint length);
 100
 101 /**
 102  * Functions for input streams.
 103  *
 104  * @since 2024/01/01
 105  */
 106 typedef struct sjme_stream_inputFunctions
 107 {
 108         /** Number of bytes available. */
 109         sjme_stream_inputAvailableFunc available;
 110
 111         /** Close stream. */
 112         sjme_stream_inputCloseFunc close;
 113
 114         /** Read from stream. */
 115         sjme_stream_inputReadFunc read;
 116 } sjme_stream_inputFunctions;
 117
 118 struct sjme_stream_inputCore
 119 {
 120         /** Functions for input. */
 121         const sjme_stream_inputFunctions* functions;
 122
 123         /** Front end holders. */
 124         sjme_frontEnd frontEnd;
 125
 126         /** The current number of read bytes. */
 127         sjme_jint totalRead;
 128
 129         /** Uncommon stream specific data. */
 130         sjme_jlong uncommon[sjme_flexibleArrayCount];
 131 };
 132
 133 /**
 134  * Gets the state information from the given input stream.
 135  *
 136  * @param uncommonType The uncommon type.
 137  * @param base The base pointer.
 138  * @since 2024/01/01
 139  */
 140 #define SJME_INPUT_UNCOMMON(uncommonType, base) \
 141         SJME_UNCOMMON_MEMBER(sjme_stream_inputCore, uncommon, \
 142                 uncommonType, (base))
 143
 144 /**
 145  * Determines the size of the input stream structure.
 146  *
 147  * @param uncommonSize The uncommon size.
 148  * @return The input stream structure size.
 149  * @since 2024/01/01
 150  */
 151 #define SJME_SIZEOF_INPUT_STREAM_N(uncommonSize) \
 152     SJME_SIZEOF_UNCOMMON_N(sjme_stream_inputCore, uncommon, uncommonSize)
 153
 154 /**
 155  * Determines the size of the input stream structure.
 156  *
 157  * @param uncommonType The uncommon type.
 158  * @return The input stream structure size.
 159  * @since 2024/01/01
 160  */
 161 #define SJME_SIZEOF_INPUT_STREAM(uncommonType) \
 162         SJME_SIZEOF_INPUT_STREAM_N(sizeof(uncommonType))
 163
 164 /**
 165  * Closes the specified output stream.
 166  *
 167  * @param stream The output stream to close.
 168  * @param optResult Optional output result.
 169  * @return On any resultant error, if any.
 170  * @since 2024/01/09
 171  */
 172 typedef sjme_errorCode (*sjme_stream_outputCloseFunc)(
 173         sjme_attrInNotNull sjme_stream_output stream,
 174         sjme_attrOutNullable sjme_pointer* optResult);
 175
 176 /**
 177  * Writes to the given output stream.
 178  *
 179  * @param stream The stream to write to.
 180  * @param buf The bytes to write.
 181  * @param length The number of bytes to write.
 182  * @return On any resultant error, if any.
 183  * @since 2024/01/09
 184  */
 185 typedef sjme_errorCode (*sjme_stream_outputWriteFunc)(
 186         sjme_attrInNotNull sjme_stream_output stream,
 187         sjme_attrInNotNull sjme_cpointer buf,
 188         sjme_attrInPositiveNonZero sjme_jint length);
 189
 190 /**
 191  * Functions for writing to the output.
 192  *
 193  * @since 2024/01/09
 194  */
 195 typedef struct sjme_stream_outputFunctions
 196 {
 197         /** Closes the specified stream. */
 198         sjme_stream_outputCloseFunc close;
 199
 200         /** Writes to the given output stream. */
 201         sjme_stream_outputWriteFunc write;
 202 } sjme_stream_outputFunctions;
 203
 204 struct sjme_stream_outputCore
 205 {
 206         /** Functions for output. */
 207         const sjme_stream_outputFunctions* functions;
 208
 209         /** Front end holders. */
 210         sjme_frontEnd frontEnd;
 211
 212         /** The current number of written bytes. */
 213         sjme_jint totalWritten;
 214
 215         /** Uncommon stream specific data. */
 216         sjme_jlong uncommon[sjme_flexibleArrayCount];
 217 };
 218
 219 /**
 220  * Gets the state information from the given output stream.
 221  *
 222  * @param uncommonType The uncommon type.
 223  * @param base The base pointer.
 224  * @since 2024/01/09
 225  */
 226 #define SJME_OUTPUT_UNCOMMON(uncommonType, base) \
 227         SJME_UNCOMMON_MEMBER(sjme_stream_outputCore, uncommon, \
 228                 uncommonType, (base))
 229
 230 /**
 231  * Determines the size of the output stream structure.
 232  *
 233  * @param uncommonSize The uncommon size.
 234  * @return The output stream structure size.
 235  * @since 2024/01/09
 236  */
 237 #define SJME_SIZEOF_OUTPUT_STREAM_N(uncommonSize) \
 238     SJME_SIZEOF_UNCOMMON_N(sjme_stream_outputCore, uncommon, uncommonSize)
 239
 240 /**
 241  * Determines the size of the output stream structure.
 242  *
 243  * @param uncommonType The uncommon type.
 244  * @return The output stream structure size.
 245  * @since 2024/01/09
 246  */
 247 #define SJME_SIZEOF_OUTPUT_STREAM(uncommonType) \
 248         SJME_SIZEOF_OUTPUT_STREAM_N(sizeof(uncommonType))
 249
 250 /**
 251  * Determines the number of bytes which are quickly available before blocking
 252  * takes effect.
 253  *
 254  * @param stream The stream to read from.
 255  * @param outAvail The number of bytes which are available.
 256  * @return On any resultant error or @c NULL .
 257  * @since 2023/12/31
 258  */
 259 sjme_errorCode sjme_stream_inputAvailable(
 260         sjme_attrInNotNull sjme_stream_input stream,
 261         sjme_attrOutNotNull sjme_attrOutNegativeOnePositive sjme_jint* outAvail);
 262
 263 /**
 264  * Closes an input stream.
 265  *
 266  * @param stream The stream to close.
 267  * @return Any resultant error, if any.
 268  * @since 2023/12/31
 269  */
 270 sjme_errorCode sjme_stream_inputClose(
 271         sjme_attrInNotNull sjme_stream_input stream);
 272
 273 /**
 274  * Creates a stream which reads from the given block of memory.
 275  *
 276  * Memory based streams are never blocking.
 277  *
 278  * @param inPool The pool to allocate within.
 279  * @param outStream The resultant stream.
 280  * @param base The buffer to access.
 281  * @param length The length of the buffer.
 282  * @return On any resultant error, if any.
 283  * @since 2023/12/31
 284  */
 285 sjme_errorCode sjme_stream_inputOpenMemory(
 286         sjme_attrInNotNull sjme_alloc_pool* inPool,
 287         sjme_attrOutNotNull sjme_stream_input* outStream,
 288         sjme_attrInNotNull sjme_cpointer base,
 289         sjme_attrInPositive sjme_jint length);
 290
 291 /**
 292  * Reads from the given input stream and writes to the destination buffer.
 293  *
 294  * @param stream The stream to read from.
 295  * @param readCount The number of bytes which were read, if end of stream is
 296  * reached this will be @c -1 .
 297  * @param dest The destination buffer.
 298  * @param length The number of bytes to read.
 299  * @return Any resultant error, if any.
 300  * @since 2023/12/31
 301  */
 302 sjme_errorCode sjme_stream_inputRead(
 303         sjme_attrInNotNull sjme_stream_input stream,
 304         sjme_attrOutNotNull sjme_attrOutNegativeOnePositive sjme_jint* readCount,
 305         sjme_attrOutNotNullBuf(length) sjme_pointer dest,
 306         sjme_attrInPositive sjme_jint length);
 307
 308 /**
 309  * Reads from the given input stream and writes to the destination buffer.
 310  *
 311  * @param stream The stream to read from.
 312  * @param readCount The number of bytes which were read, if end of stream is
 313  * reached this will be @c -1 .
 314  * @param dest The destination buffer.
 315  * @param offset The offset into the destination buffer.
 316  * @param length The number of bytes to read.
 317  * @return Any resultant error, if any.
 318  * @since 2023/12/31
 319  */
 320 sjme_errorCode sjme_stream_inputReadIter(
 321         sjme_attrInNotNull sjme_stream_input stream,
 322         sjme_attrOutNotNull sjme_attrOutNegativeOnePositive sjme_jint* readCount,
 323         sjme_attrOutNotNullBuf(length) sjme_pointer dest,
 324         sjme_attrInPositive sjme_jint offset,
 325         sjme_attrInPositive sjme_jint length);
 326
 327 /**
 328  * Reads a single byte from the input stream.
 329  *
 330  * @param stream The stream to read from.
 331  * @param result The resultant byte, @c -1 indicates end of stream while
 332  * every other value is always positive.
 333  * @return Any resultant error, if any.
 334  * @since 2023/12/31
 335  */
 336 sjme_errorCode sjme_stream_inputReadSingle(
 337         sjme_attrInNotNull sjme_stream_input stream,
 338         sjme_attrOutNotNull sjme_attrOutNegativeOnePositive sjme_jint* result);
 339
 340 /**
 341  * Reads a Java value from the given stream.
 342  *
 343  * @param stream The stream to read from.
 344  * @param typeId The type to read.
 345  * @param outValue The resultant value.
 346  * @return On any error, if any.
 347  * @since 2024/01/05
 348  */
 349 sjme_errorCode sjme_stream_inputReadValueJ(
 350         sjme_attrInNotNull sjme_stream_input stream,
 351         sjme_attrInRange(0, SJME_NUM_BASIC_TYPE_IDS)
 352                 sjme_basicTypeId typeId,
 353         sjme_attrOutNotNull sjme_jvalue* outValue);
 354
 355 /**
 356  * Closes an output stream.
 357  *
 358  * @param stream The stream to close.
 359  * @param optResult Optional resultant output value, if any.
 360  * @return Any resultant error, if any.
 361  * @since 2023/12/31
 362  */
 363 sjme_errorCode sjme_stream_outputClose(
 364         sjme_attrInNotNull sjme_stream_output stream,
 365         sjme_attrOutNullable sjme_pointer* optResult);
 366
 367 /**
 368  * Contains the result of the written byte array.
 369  *
 370  * @since 2024/01/09
 371  */
 372 typedef struct sjme_stream_resultByteArray
 373 {
 374         /** The buffer where the data is. */
 375         sjme_jbyte* array;
 376
 377         /** The length of the array. */
 378         sjme_jint length;
 379
 380         /**
 381          * If this is set to @c SJME_JNI_TRUE , then the close handler for
 382          * the byte array will free the memory contained in the buffer. To prevent
 383          * it from being freed, this should return @c SJME_JNI_FALSE in which case
 384          * the @c optResult value will be written to with the final buffer.
 385          */
 386         sjme_jboolean free;
 387
 388         /** The input whatever value. */
 389         sjme_pointer whatever;
 390
 391         /** The optional output result. */
 392         sjme_pointer* optResult;
 393 } sjme_stream_resultByteArray;
 394
 395 /**
 396  * This function is called back when the output byte array stream has been
 397  * closed, which provides the byte array for access.
 398  *
 399  * @param stream The stream that is finished and is about to be closed.
 400  * @param result The result of the array operation.
 401  * @return Any resultant error, if any.
 402  * @since 2024/01/09
 403  */
 404 typedef sjme_errorCode (*sjme_stream_outputByteArrayFinishFunc)(
 405         sjme_attrInNotNull sjme_stream_output stream,
 406         sjme_attrInNotNull sjme_stream_resultByteArray* result);
 407
 408 /**
 409  * Opens a dynamically resizing output byte array.
 410  *
 411  * @param inPool The pool to allocate within.
 412  * @param outStream The resultant output stream.
 413  * @param initialLimit The initial buffer limit.
 414  * @param finish The function to call when the stream is closed.
 415  * @param whatever Can be used to pass whatever is needed for the finish
 416  * processor.
 417  * @return On any error, if any.
 418  * @since 2024/01/09
 419  */
 420 sjme_errorCode sjme_stream_outputOpenByteArray(
 421         sjme_attrInNotNull sjme_alloc_pool* inPool,
 422         sjme_attrOutNotNull sjme_stream_output* outStream,
 423         sjme_attrInPositive sjme_jint initialLimit,
 424         sjme_attrInNotNull sjme_stream_outputByteArrayFinishFunc finish,
 425         sjme_attrInNullable sjme_pointer whatever);
 426
 427 /**
 428  * Opens an output stream which writes to the given block of memory, note that
 429  * when it reaches the end of the block it will fail to write following it.
 430  *
 431  * @param inPool The pool to allocate within.
 432  * @param outStream The resultant output stream.
 433  * @param base The base memory address to write to.
 434  * @param length The length of the memory region.
 435  * @return Any resultant error, if any.
 436  * @since 2024/01/09
 437  */
 438 sjme_errorCode sjme_stream_outputOpenMemory(
 439         sjme_attrInNotNull sjme_alloc_pool* inPool,
 440         sjme_attrOutNotNull sjme_stream_output* outStream,
 441         sjme_attrInNotNull sjme_pointer base,
 442         sjme_attrInPositive sjme_jint length);
 443
 444 /**
 445  * Writes to the given output stream.
 446  *
 447  * @param outStream The stream to write to.
 448  * @param src The source bytes.
 449  * @param length The number of bytes to write.
 450  * @return Any resultant error, if any.
 451  * @since 2024/01/09
 452  */
 453 sjme_errorCode sjme_stream_outputWrite(
 454         sjme_attrInNotNull sjme_stream_output outStream,
 455         sjme_attrOutNotNullBuf(length) sjme_pointer src,
 456         sjme_attrInPositive sjme_jint length);
 457
 458 /**
 459  * Writes to the given output stream.
 460  *
 461  * @param stream The stream to write to.
 462  * @param src The source bytes.
 463  * @param offset The offset into the buffer.
 464  * @param length The number of bytes to write.
 465  * @return Any resultant error, if any.
 466  * @since 2024/01/09
 467  */
 468 sjme_errorCode sjme_stream_outputWriteIter(
 469         sjme_attrInNotNull sjme_stream_output stream,
 470         sjme_attrOutNotNullBuf(length) sjme_pointer src,
 471         sjme_attrInPositive sjme_jint offset,
 472         sjme_attrInPositive sjme_jint length);
 473
 474 /**
 475  * Writes a single byte to the output stream.
 476  *
 477  * @param outStream The stream to write to.
 478  * @param value The value to write, only the lower eight bits are kept.
 479  * @return Any resultant error, if any.
 480  * @since 2024/01/09
 481  */
 482 sjme_errorCode sjme_stream_outputWriteSingle(
 483         sjme_attrInNotNull sjme_stream_output outStream,
 484         sjme_attrInRange(0, 256) sjme_jint value);
 485
 486 /**
 487  * Writes a Java value to the output stream.
 488  *
 489  * @param outStream The stream to write to.
 490  * @param typeId The type to write.
 491  * @param value The value to write.
 492  * @return Any resultant error, if any.
 493  * @since 2024/01/09
 494  */
 495 sjme_errorCode sjme_stream_outputWriteValueJP(
 496         sjme_attrInNotNull sjme_stream_output outStream,
 497         sjme_attrInRange(0, SJME_NUM_BASIC_TYPE_IDS) sjme_basicTypeId typeId,
 498         sjme_attrInNotNull const sjme_jvalue* value);
 499
 500 /**
 501  * Writes a Java value to the output stream.
 502  *
 503  * @param outStream The stream to write to.
 504  * @param typeId The type to write.
 505  * @param ... The value to write.
 506  * @return Any resultant error, if any.
 507  * @since 2024/01/09
 508  */
 509 sjme_errorCode sjme_stream_outputWriteValueJ(
 510         sjme_attrInNotNull sjme_stream_output outStream,
 511         sjme_attrInRange(0, SJME_NUM_BASIC_TYPE_IDS) sjme_basicTypeId typeId,
 512         ...);
 513
 514 /*--------------------------------------------------------------------------*/
 515
 516 /* Anti-C++. */
 517 #ifdef __cplusplus
 518         #ifdef SJME_CXX_SQUIRRELJME_STREAM_H
 519 }
 520                 #undef SJME_CXX_SQUIRRELJME_STREAM_H
 521                 #undef SJME_CXX_IS_EXTERNED
 522         #endif /* #ifdef SJME_CXX_SQUIRRELJME_STREAM_H */
 523 #endif     /* #ifdef __cplusplus */
 524
 525 #endif /* SQUIRRELJME_STREAM_H */