nanocoat/include/sjme/seekable.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  * Seekable buffers.
  12  *
  13  * @since 2024/01/01
  14  */
  15
  16 #ifndef SQUIRRELJME_SEEKABLE_H
  17 #define SQUIRRELJME_SEEKABLE_H
  18
  19 #include "sjme/stdTypes.h"
  20 #include "sjme/alloc.h"
  21 #include "sjme/closeable.h"
  22
  23 /* Anti-C++. */
  24 #ifdef __cplusplus
  25         #ifndef SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_SQUIRRELJME_SEEKABLE_H
  28 extern "C" {
  29         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  30 #endif     /* #ifdef __cplusplus */
  31
  32 /*--------------------------------------------------------------------------*/
  33
  34 /**
  35  * Core seekable structure.
  36  *
  37  * @since 2024/01/01
  38  */
  39 typedef struct sjme_seekableBase sjme_seekableBase;
  40
  41 /**
  42  * Opaque seekable data.
  43  *
  44  * @since 2024/01/01
  45  */
  46 typedef sjme_seekableBase* sjme_seekable;
  47
  48 /**
  49  * Seekable lock core structure.
  50  *
  51  * @since 2024/01/01
  52  */
  53 typedef struct sjme_seekable_lockBase sjme_seekable_lockBase;
  54
  55 /**
  56  * Opaque locked seekable structure.
  57  *
  58  * @since 2024/01/01
  59  */
  60 typedef struct sjme_seekable_lockBase* sjme_seekable_lock;
  61
  62 struct sjme_seekable_lockBase
  63 {
  64         /** The owning seekable. */
  65         sjme_seekable seekable;
  66
  67         /**
  68          * The base address pointer.
  69          *
  70          * Depending on the implementation, if the memory within the lock is
  71          * modified it may directly change the resultant memory or file.
  72          */
  73         sjme_pointer base;
  74
  75         /** The length of the lock. */
  76         sjme_jint length;
  77 };
  78
  79 /**
  80  * This is the action that can change what happens when a locked region is
  81  * unlocked.
  82  *
  83  * @since 2024/01/01
  84  */
  85 typedef enum sjme_seekable_unlockAction
  86 {
  87         /** Discard any bytes that were written. */
  88         SJME_SEEKABLE_UNLOCK_ACTION_DISCARD,
  89
  90         /**
  91          * Write the data back to the seekable.
  92          *
  93          * Note that this only has an effect if the buffer in memory is a copy
  94          * of the source seekable, in which case it was not directly mappable.
  95          */
  96         SJME_SEEKABLE_UNLOCK_ACTION_WRITE_BACK,
  97
  98         /** The number of unlock actions. */
  99         SJME_NUM_SEEKABLE_UNLOCK_ACTION
 100 } sjme_seekable_unlockAction;
 101
 102 /**
 103  * Implementation state within seekables.
 104  *
 105  * @since 2024/08/11
 106  */
 107 typedef struct sjme_seekable_implState
 108 {
 109         /** The pool this is in. */
 110         sjme_alloc_pool* inPool;
 111
 112         /** Internal handle. */
 113         sjme_pointer handle;
 114
 115         /** Internal index. */
 116         sjme_jint index;
 117
 118         /** Internal length. */
 119         sjme_jint length;
 120
 121         /** Forward close? */
 122         sjme_jboolean forwardClose;
 123 } sjme_seekable_implState;
 124
 125 /**
 126  * Closes the seekable stream.
 127  *
 128  * @param inSeekable The current seekable.
 129  * @param inImplState The implementation state.
 130  * @return Any resultant error, if any.
 131  * @since 2024/08/11
 132  */
 133 typedef sjme_errorCode (*sjme_seekable_closeFunc)(
 134         sjme_attrInNotNull sjme_seekable inSeekable,
 135         sjme_attrInNotNull sjme_seekable_implState* inImplState);
 136
 137 /**
 138  * Initializes the new seekable.
 139  *
 140  * @param inSeekable The current seekable.
 141  * @param inImplState The implementation state.
 142  * @param data Any passed in data through initialize.
 143  * @return Any resultant error, if any.
 144  * @since 2024/08/11
 145  */
 146 typedef sjme_errorCode (*sjme_seekable_initFunc)(
 147         sjme_attrInNotNull sjme_seekable inSeekable,
 148         sjme_attrInNotNull sjme_seekable_implState* inImplState,
 149         sjme_attrInNullable sjme_pointer data);
 150
 151 /**
 152  * Reads from the given seekable.
 153  *
 154  * @param inSeekable The current seekable.
 155  * @param inImplState The implementation state.
 156  * @param outBuf The buffer to write to.
 157  * @param base The base address to read from.
 158  * @param length The number of bytes to read.
 159  * @return Any resultant error, if any.
 160  * @since 2024/08/11
 161  */
 162 typedef sjme_errorCode (*sjme_seekable_readFunc)(
 163         sjme_attrInNotNull sjme_seekable inSeekable,
 164         sjme_attrInNotNull sjme_seekable_implState* inImplState,
 165         sjme_attrOutNotNullBuf(length) sjme_buffer outBuf,
 166         sjme_attrInPositive sjme_jint base,
 167         sjme_attrInPositiveNonZero sjme_jint length);
 168
 169 /**
 170  * Returns the size of the seekable.
 171  *
 172  * @param inSeekable The current seekable.
 173  * @param inImplState The implementation state.
 174  * @param outSize The resultant size of the seekable.
 175  * @return Any resultant error, if any.
 176  * @since 2024/08/11
 177  */
 178 typedef sjme_errorCode (*sjme_seekable_sizeFunc)(
 179         sjme_attrInNotNull sjme_seekable inSeekable,
 180         sjme_attrInNotNull sjme_seekable_implState* inImplState,
 181         sjme_attrOutNotNull sjme_jint* outSize);
 182
 183 /**
 184  * Functions for seekable implementations.
 185  *
 186  * @since 2024/08/11
 187  */
 188 typedef struct sjme_seekable_functions
 189 {
 190         /** Closes the stream. */
 191         sjme_seekable_closeFunc close;
 192
 193         /** Initializes the stream. */
 194         sjme_seekable_initFunc init;
 195
 196         /** Read from the given stream. */
 197         sjme_seekable_readFunc read;
 198
 199         /** Return the size of the stream. */
 200         sjme_seekable_sizeFunc size;
 201 } sjme_seekable_functions;
 202
 203 struct sjme_seekableBase
 204 {
 205         /** Closeable. */
 206         sjme_closeableBase closable;
 207
 208         /** Implementation state. */
 209         sjme_seekable_implState implState;
 210
 211         /** Front end data. */
 212         sjme_frontEnd frontEnd;
 213
 214         /** Functions for stream access. */
 215         const sjme_seekable_functions* functions;
 216
 217         /** Spinlock for stream access. */
 218         sjme_thread_spinLock lock;
 219
 220         /** The pool this is in. */
 221         sjme_alloc_pool* inPool;
 222 };
 223
 224 /**
 225  * Opens a generic stream.
 226  *
 227  * @param inPool The pool to allocate within.
 228  * @param outSeekable The resultant seekable.
 229  * @param inFunctions The seekable functions.
 230  * @param data Any data to pass to the initialize function.
 231  * @param copyFrontEnd Front-end data as needed.
 232  * @return Any resultant error, if any,
 233  * @since 2024/08/11
 234  */
 235 sjme_errorCode sjme_seekable_open(
 236         sjme_attrInNotNull sjme_alloc_pool* inPool,
 237         sjme_attrOutNotNull sjme_seekable* outSeekable,
 238         sjme_attrInNotNull const sjme_seekable_functions* inFunctions,
 239         sjme_attrInNullable sjme_pointer data,
 240         sjme_attrInNullable const sjme_frontEnd* copyFrontEnd);
 241
 242 /**
 243  * Initializes a seekable from the given memory range.
 244  *
 245  * @param inPool The pool to allocate within.
 246  * @param outSeekable The resultant seekable.
 247  * @param base The base memory address.
 248  * @param length The length of memory block.
 249  * @return Any resultant error, if any.
 250  * @since 2024/01/01
 251  */
 252 sjme_errorCode sjme_seekable_openMemory(
 253         sjme_attrInNotNull sjme_alloc_pool* inPool,
 254         sjme_attrOutNotNull sjme_seekable* outSeekable,
 255         sjme_attrInNotNull sjme_pointer base,
 256         sjme_attrInPositive sjme_jint length);
 257
 258 /**
 259  * Wraps a seekable and provides a sub-seekable within this.
 260  *
 261  * @param inPool The pool to allocate within.
 262  * @param inSeekable The input seekable, to get the sub-seekable of.
 263  * @param outSeekable The output seekable.
 264  * @param base The base address to get.
 265  * @param length The length of the seekable range.
 266  * @return Any resultant error, if any.
 267  * @since 2024/01/01
 268  */
 269 sjme_errorCode sjme_seekable_openSeekable(
 270         sjme_attrInNotNull sjme_alloc_pool* inPool,
 271         sjme_attrInNotNull sjme_seekable inSeekable,
 272         sjme_attrOutNotNull sjme_seekable* outSeekable,
 273         sjme_attrInPositive sjme_jint base,
 274         sjme_attrInPositive sjme_jint length);
 275
 276 /**
 277  * Reads from the given seekable.
 278  *
 279  * @param seekable The seekable to read from.
 280  * @param outBuf The output buffer.
 281  * @param seekBase The base of the seekable to read from.
 282  * @param length The number of bytes to read.
 283  * @return Any resultant error, if any.
 284  * @since 2024/08/11
 285  */
 286 sjme_errorCode sjme_seekable_read(
 287         sjme_attrInNotNull sjme_seekable seekable,
 288         sjme_attrOutNotNull sjme_buffer outBuf,
 289         sjme_attrInPositive sjme_jint seekBase,
 290         sjme_attrInPositive sjme_jint length);
 291
 292 /**
 293  * Reads from the given seekable in reverse byte order for every @c wordSize
 294  * that is read from the input.
 295  *
 296  * @param seekable The seekable to read from.
 297  * @param wordSize The word size for the read, every number of this many
 298  * bytes will be reversed.
 299  * @param outBuf The output buffer.
 300  * @param seekBase The base of the seekable to read from.
 301  * @param length The number of bytes to read.
 302  * @return Any resultant error, if any.
 303  * @since 2024/08/13
 304  */
 305 sjme_errorCode sjme_seekable_readReverse(
 306         sjme_attrInNotNull sjme_seekable seekable,
 307         sjme_attrInRange(2, 8) sjme_jint wordSize,
 308         sjme_attrOutNotNull sjme_buffer outBuf,
 309         sjme_attrInPositive sjme_jint seekBase,
 310         sjme_attrInPositive sjme_jint length);
 311
 312 #if defined(SJME_CONFIG_HAS_LITTLE_ENDIAN)
 313
 314 /**
 315  * Reads big endian data from the given seekable.
 316  *
 317  * @param seekable The seekable to read from.
 318  * @param wordSize The word size for the read, every number of bytes will
 319  * be possibly reversed if required.
 320  * @param outBuf The output buffer.
 321  * @param seekBase The base of the seekable to read from.
 322  * @param length The number of bytes to read.
 323  * @return Any resultant error, if any.
 324  * @since 2024/08/13
 325  */
 326 #define sjme_seekable_readBig(seekable, wordSize, outBuf, seekBase, \
 327         length) \
 328         (sjme_seekable_readReverse((seekable), (wordSize), (outBuf), (seekBase), \
 329         (length)))
 330
 331 /**
 332  * Reads little endian data from the given seekable.
 333  *
 334  * @param seekable The seekable to read from.
 335  * @param wordSize The word size for the read, every number of bytes will
 336  * be possibly reversed if required.
 337  * @param outBuf The output buffer.
 338  * @param seekBase The base of the seekable to read from.
 339  * @param length The number of bytes to read.
 340  * @return Any resultant error, if any.
 341  * @since 2024/08/13
 342  */
 343 #define sjme_seekable_readLittle(seekable, wordSize, outBuf, seekBase, \
 344         length) \
 345         (sjme_seekable_read((seekable), (outBuf), (seekBase), (length)))
 346
 347 #else
 348
 349 /**
 350  * Reads big endian data from the given seekable.
 351  *
 352  * @param seekable The seekable to read from.
 353  * @param wordSize The word size for the read, every number of bytes will
 354  * be possibly reversed if required.
 355  * @param outBuf The output buffer.
 356  * @param seekBase The base of the seekable to read from.
 357  * @param length The number of bytes to read.
 358  * @return Any resultant error, if any.
 359  * @since 2024/08/13
 360  */
 361 #define sjme_seekable_readBig(seekable, wordSize, outBuf, seekBase, \
 362         length) \
 363         (sjme_seekable_read((seekable), (outBuf), (seekBase), (length)))
 364
 365 /**
 366  * Reads little endian data from the given seekable.
 367  *
 368  * @param seekable The seekable to read from.
 369  * @param wordSize The word size for the read, every number of bytes will
 370  * be possibly reversed if required.
 371  * @param outBuf The output buffer.
 372  * @param seekBase The base of the seekable to read from.
 373  * @param length The number of bytes to read.
 374  * @return Any resultant error, if any.
 375  * @since 2024/08/13
 376  */
 377 #define sjme_seekable_readLittle(seekable, wordSize, outBuf, seekBase, \
 378         length) \
 379         (sjme_seekable_readReverse((seekable), (wordSize), (outBuf), (seekBase), \
 380         (length)))
 381
 382 #endif
 383
 384 /**
 385  * Locks a region of a seekable so that the data stored there can be accessed
 386  * directly via memory access. Depending on the seekable implementation, there
 387  * are multiple possibilities as to what may occur: if the seekable is
 388  * directly from memory it will just map to that pointer accordingly, if
 389  * the seekable is backed by a file then it will be memory mapped, otherwise
 390  * a buffer will be created with a copy of the bytes at the given region and
 391  * will stay as such until unlocked. Per the implementation, if the seekable
 392  * data is modified in memory it may change that actual memory or file.
 393  *
 394  * @param seekable The seekable to lock within.
 395  * @param outLock The resultant lock.
 396  * @param base The base address within the seekable to lock.
 397  * @param length The number of bytes to lock.
 398  * @return Any resultant error, if any.
 399  * @since 2024/01/01
 400  */
 401 sjme_errorCode sjme_seekable_regionLock(
 402         sjme_attrInNotNull sjme_seekable seekable,
 403         sjme_attrOutNotNull sjme_seekable_lock* outLock,
 404         sjme_attrInPositive sjme_jint base,
 405         sjme_attrInPositive sjme_jint length);
 406
 407 /**
 408  * Unlocks a locked seekable region, the resultant action may or may not
 409  * have an effect depending on the implementation.
 410  *
 411  * @param inLock The lock to unlock.
 412  * @param action The action to perform on the unlock.
 413  * @return Any resultant error, if any.
 414  * @see sjme_seekable_unlockAction
 415  * @since 2024/01/01
 416  */
 417 sjme_errorCode sjme_seekable_regionUnlock(
 418         sjme_attrInNotNull sjme_seekable_lock inLock,
 419         sjme_attrInRange(0, SJME_NUM_SEEKABLE_UNLOCK_ACTION)
 420                 sjme_seekable_unlockAction action);
 421
 422 /**
 423  * Returns the size of the given seekable.
 424  *
 425  * @param seekable The seekable to get the size of.
 426  * @param outSize The size of the seekable.
 427  * @return Any resultant error, if any.
 428  * @since 2024/08/11
 429  */
 430 sjme_errorCode sjme_seekable_size(
 431         sjme_attrInNotNull sjme_seekable seekable,
 432         sjme_attrOutNotNull sjme_jint* outSize);
 433
 434 /*--------------------------------------------------------------------------*/
 435
 436 /* Anti-C++. */
 437 #ifdef __cplusplus
 438         #ifdef SJME_CXX_SQUIRRELJME_SEEKABLE_H
 439 }
 440                 #undef SJME_CXX_SQUIRRELJME_SEEKABLE_H
 441                 #undef SJME_CXX_IS_EXTERNED
 442         #endif /* #ifdef SJME_CXX_SQUIRRELJME_SEEKABLE_H */
 443 #endif     /* #ifdef __cplusplus */
 444
 445 #endif /* SQUIRRELJME_SEEKABLE_H */