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  * @since 2023/12/30
  14  */
  15
  16 #ifndef SQUIRRELJME_STREAM_H
  17 #define SQUIRRELJME_STREAM_H
  18
  19 #include "sjme/nvm.h"
  20
  21 /* Anti-C++. */
  22 #ifdef __cplusplus
  23         #ifndef SJME_CXX_IS_EXTERNED
  24                 #define SJME_CXX_IS_EXTERNED
  25                 #define SJME_CXX_SQUIRRELJME_STREAM_H
  26 extern "C" {
  27         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  28 #endif     /* #ifdef __cplusplus */
  29
  30 /*--------------------------------------------------------------------------*/
  31
  32 /**
  33  * Represents a data stream that can be read from.
  34  *
  35  * @since 2023/12/30
  36  */
  37 typedef struct sjme_stream_inputCore* sjme_stream_input;
  38
  39 /**
  40  * Represents a data stream that can be written to.
  41  *
  42  * @since 2023/12/30
  43  */
  44 typedef struct sjme_stream_outputCore* sjme_stream_output;
  45
  46 /**
  47  * Determines the number of bytes which are quickly available before blocking
  48  * takes effect.
  49  *
  50  * @param stream The stream to read from.
  51  * @param outAvail The number of bytes which are available.
  52  * @return On any resultant error or {@code null}.
  53  * @since 2023/12/31
  54  */
  55 sjme_errorCode sjme_stream_inputAvailable(
  56         sjme_attrInNotNull sjme_stream_input stream,
  57         sjme_attrOutNotNull sjme_attrOutNegativeOnePositive sjme_jint* outAvail);
  58
  59 /**
  60  * Closes an input stream.
  61  *
  62  * @param stream The stream to close.
  63  * @return Any resultant error, if any.
  64  * @since 2023/12/31
  65  */
  66 sjme_errorCode sjme_stream_inputClose(
  67         sjme_attrInNotNull sjme_stream_input stream);
  68
  69 /**
  70  * Creates a stream which reads from the given block of memory.
  71  *
  72  * Memory based streams are never blocking.
  73  *
  74  * @param inPool The pool to allocate within.
  75  * @param outStream The resultant stream.
  76  * @param buffer The buffer to access.
  77  * @param length The length of the buffer.
  78  * @return On any resultant error, if any.
  79  * @since 2023/12/31
  80  */
  81 sjme_errorCode sjme_stream_inputOpenMemory(
  82         sjme_attrInNotNull sjme_alloc_pool* inPool,
  83         sjme_attrOutNotNull sjme_stream_input* outStream,
  84         sjme_attrInNotNull void* buffer,
  85         sjme_attrInPositive sjme_jint length);
  86
  87 /**
  88  * Reads from the given input stream and writes to the destination buffer.
  89  *
  90  * @param stream The stream to read from.
  91  * @param readCount The number of bytes which were read.
  92  * @param dest The destination buffer.
  93  * @param length The number of bytes to read.
  94  * @return Any resultant error, if any.
  95  * @since 2023/12/31
  96  */
  97 sjme_errorCode sjme_stream_inputRead(
  98         sjme_attrInNotNull sjme_stream_input stream,
  99         sjme_attrOutNotNull sjme_attrOutPositive sjme_jint* readCount,
 100         sjme_attrOutNotNullBuf(length) void* dest,
 101         sjme_attrInPositive sjme_jint length);
 102
 103 /**
 104  * Reads from the given input stream and writes to the destination buffer.
 105  *
 106  * @param stream The stream to read from.
 107  * @param readCount The number of bytes which were read.
 108  * @param dest The destination buffer.
 109  * @param offset The offset into the destination buffer.
 110  * @param length The number of bytes to read.
 111  * @return Any resultant error, if any.
 112  * @since 2023/12/31
 113  */
 114 sjme_errorCode sjme_stream_inputReadIter(
 115         sjme_attrInNotNull sjme_stream_input stream,
 116         sjme_attrOutNotNull sjme_attrOutPositive sjme_jint* readCount,
 117         sjme_attrOutNotNullBuf(length) void* dest,
 118         sjme_attrInPositive sjme_jint offset,
 119         sjme_attrInPositive sjme_jint length);
 120
 121 /**
 122  * Closes an output stream.
 123  *
 124  * @param stream The stream to close.
 125  * @return Any resultant error, if any.
 126  * @since 2023/12/31
 127  */
 128 sjme_errorCode sjme_stream_outputClose(
 129         sjme_attrInNotNull sjme_stream_output stream);
 130
 131 /*--------------------------------------------------------------------------*/
 132
 133 /* Anti-C++. */
 134 #ifdef __cplusplus
 135         #ifdef SJME_CXX_SQUIRRELJME_STREAM_H
 136 }
 137                 #undef SJME_CXX_SQUIRRELJME_STREAM_H
 138                 #undef SJME_CXX_IS_EXTERNED
 139         #endif /* #ifdef SJME_CXX_SQUIRRELJME_STREAM_H */
 140 #endif     /* #ifdef __cplusplus */
 141
 142 #endif /* SQUIRRELJME_STREAM_H */