nanocoat/include/sjme/rom.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  * ROM related structures, this replicates what is in @c JarPackageShelf.
  12  *
  13  * @since 2023/12/12
  14  */
  15
  16 #ifndef SQUIRRELJME_ROM_H
  17 #define SQUIRRELJME_ROM_H
  18
  19 #include "sjme/nvm.h"
  20 #include "sjme/list.h"
  21 #include "sjme/romInternal.h"
  22 #include "sjme/stream.h"
  23 #include "sjme/seekable.h"
  24 #include "sjme/zip.h"
  25
  26 /* Anti-C++. */
  27 #ifdef __cplusplus
  28         #ifndef SJME_CXX_IS_EXTERNED
  29                 #define SJME_CXX_IS_EXTERNED
  30                 #define SJME_CXX_SQUIRRELJME_ROM_H
  31 extern "C" {
  32         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  33 #endif     /* #ifdef __cplusplus */
  34
  35 /*--------------------------------------------------------------------------*/
  36
  37 /**
  38  * Standard ROM library structure.
  39  *
  40  * @since 2023/12/12
  41  */
  42 typedef struct sjme_rom_libraryBase sjme_rom_libraryBase;
  43
  44 /** Synthetic library structure. */
  45 typedef sjme_rom_libraryBase* sjme_rom_library;
  46
  47 /** List of ROM libraries. */
  48 SJME_LIST_DECLARE(sjme_rom_library, 0);
  49
  50 /** The type ID of ROM libraries. */
  51 #define SJME_TYPEOF_BASIC_sjme_rom_library SJME_BASIC_TYPE_ID_OBJECT
  52
  53 /**
  54  * Common cache between suites and libraries.
  55  *
  56  * @since 2023/12/20
  57  */
  58 typedef struct sjme_rom_cache
  59 {
  60         /** The allocation pool to use. */
  61         sjme_alloc_pool* allocPool;
  62
  63         /** Wrapped object, if applicable. */
  64         sjme_frontEnd frontEnd;
  65 } sjme_rom_cache;
  66
  67 /**
  68  * Internal cache for ROM libraries.
  69  *
  70  * @since 2023/12/12
  71  */
  72 typedef struct sjme_rom_libraryCache
  73 {
  74         /** Common cache data. */
  75         sjme_rom_cache common;
  76
  77         /** Cached size of the library. */
  78         sjme_jint size;
  79
  80         /** Is raw access checked? */
  81         sjme_jboolean checkedRawAccess : 1;
  82
  83         /** Is raw access valid. */
  84         sjme_jboolean validRawAccess : 1;
  85 } sjme_rom_libraryCache;
  86
  87 /**
  88  * Internal cache for ROM suites.
  89  *
  90  * @since 2023/12/12
  91  */
  92 typedef struct sjme_rom_suiteCache
  93 {
  94         /** Common cache data. */
  95         sjme_rom_cache common;
  96
  97         /** Libraries that exist within the suite. */
  98         sjme_list_sjme_rom_library* libraries;
  99 } sjme_rom_suiteCache;
 100
 101 /**
 102  * Functions used to access a single library.
 103  *
 104  * @since 2023/12/12
 105  */
 106 typedef struct sjme_rom_libraryFunctions sjme_rom_libraryFunctions;
 107
 108 /**
 109  * Functions used to access a suite, which is an entire ROM.
 110  *
 111  * @since 2023/12/12
 112  */
 113 typedef struct sjme_rom_suiteFunctions sjme_rom_suiteFunctions;
 114
 115 struct sjme_rom_libraryBase
 116 {
 117         /** Common data. */
 118         sjme_nvm_commonBase common;
 119
 120         /** Functions used to access library information. */
 121         const sjme_rom_libraryFunctions* functions;
 122
 123         /** The handle, may be to a seekable. */
 124         sjme_pointer handle;
 125
 126         /** The prefix, if applicable. */
 127         sjme_lpcstr prefix;
 128
 129         /** The library ID. */
 130         sjme_jint id;
 131
 132         /** The library name. */
 133         sjme_lpcstr name;
 134
 135         /** Hash of the library name. */
 136         sjme_jint nameHash;
 137
 138         /** Internal cache, used by internal library functions. */
 139         sjme_rom_libraryCache cache;
 140 };
 141
 142 /**
 143  * Closes the library.
 144  *
 145  * @param inLibrary The library being closed.
 146  * @return Any resultant error, if any.
 147  * @since 2024/08/16
 148  */
 149 typedef sjme_errorCode (*sjme_rom_libraryCloseFunc)(
 150         sjme_attrInNotNull sjme_rom_library inLibrary);
 151
 152 /**
 153  * Initializes the library.
 154  *
 155  * @param inLibrary The input library.
 156  * @param data Any data passed to init.
 157  * @return Any resultant error, if any.
 158  * @since 2023/12/29
 159  */
 160 typedef sjme_errorCode (*sjme_rom_libraryInitFunc)(
 161         sjme_attrInNotNull sjme_rom_library inLibrary,
 162         sjme_attrInNullable sjme_pointer data);
 163
 164 typedef sjme_errorCode (*sjme_rom_libraryPathFunc)();
 165
 166 /**
 167  * Access the direct raw data of a given library.
 168  *
 169  * @param inLibrary The library to access in a raw fashion.
 170  * @param dest The destination buffer.
 171  * @param srcPos The source position within the file.
 172  * @param length The number of bytes to read.
 173  * @return Any resultant error, if any.
 174  * @since 2023/12/30
 175  */
 176 typedef sjme_errorCode (*sjme_rom_libraryRawData)(
 177         sjme_attrInNotNull sjme_rom_library inLibrary,
 178         sjme_attrOutNotNullBuf(length) sjme_pointer dest,
 179         sjme_attrInPositive sjme_jint srcPos,
 180         sjme_attrInPositive sjme_jint length);
 181
 182 /**
 183  * Returns the raw size of the library, also can be used to check if raw
 184  * access is supported in opaque handlers.
 185  *
 186  * @param inLibrary The input library
 187  * @param outSize The output raw size, if the result is @c -1 then it indicates
 188  * that this operation is not supported on the given library and it should
 189  * not try to access resources and otherwise using raw data access.
 190  * @return Any resultant error code.
 191  * @since 2023/12/30
 192  */
 193 typedef sjme_errorCode (*sjme_rom_libraryRawSizeFunc)(
 194         sjme_attrInNotNull sjme_rom_library inLibrary,
 195         sjme_attrOutNotNull sjme_jint* outSize);
 196
 197 /**
 198  * Opens the given resource as a stream.
 199  *
 200  * @param inLibrary The library to read the resource from.
 201  * @param outStream The resultant stream for accessing data.
 202  * @param resourceName The name of the resource.
 203  * @return Any resultant error code.
 204  * @since 2023/12/30
 205  */
 206 typedef sjme_errorCode (*sjme_rom_libraryResourceStreamFunc)(
 207         sjme_attrInNotNull sjme_rom_library inLibrary,
 208         sjme_attrOutNotNull sjme_stream_input* outStream,
 209         sjme_attrInNotNull sjme_lpcstr resourceName);
 210
 211 /**
 212  * Obtains the default launch parameters from the given suite.
 213  *
 214  * @param inPool The pool to allocate within.
 215  * @param inSuite The suite to get the launch parameters from.
 216  * @param outMainClass The main class to launch.
 217  * @param outMainArgs The arguments to pass to the main class.
 218  * @param outById The main class path by ID.
 219  * @param outByName The main class path by name.
 220  * @return Any resultant error, if any.
 221  * @since 2024/08/16
 222  */
 223 typedef sjme_errorCode (*sjme_rom_suiteDefaultLaunchFunc)(
 224         sjme_attrInNotNull sjme_alloc_pool* inPool,
 225         sjme_attrInNotNull sjme_rom_suite inSuite,
 226         sjme_attrOutNotNull sjme_lpstr* outMainClass,
 227         sjme_attrOutNotNull sjme_list_sjme_lpstr** outMainArgs,
 228         sjme_attrOutNotNull sjme_list_sjme_jint** outById,
 229         sjme_attrOutNotNull sjme_list_sjme_lpstr** outByName);
 230
 231 /**
 232  * Function used to initialize the suite.
 233  *
 234  * @param inSuite The input suite.
 235  * @param data Any data passed to init.
 236  * @return Any error state.
 237  * @since 2023/12/15
 238  */
 239 typedef sjme_errorCode (*sjme_rom_suiteInitFunc)(
 240         sjme_attrInNotNull sjme_rom_suite inSuite,
 241         sjme_attrInNullable sjme_pointer data);
 242
 243 /**
 244  * Returns the ID of the library for the given suite.
 245  *
 246  * @param functions The suite functions.
 247  * @param inSuite The current suite being accessed.
 248  * @param inLibrary The library to get the ID of.
 249  * @param outId The output library ID, cannot be zero.
 250  * @return Any resultant error code.
 251  * @since 2023/12/18
 252  */
 253 typedef sjme_errorCode (*sjme_rom_suiteLibraryIdFunc)(
 254         sjme_attrInNotNull sjme_rom_suite inSuite,
 255         sjme_attrInNotNull sjme_rom_library inLibrary,
 256         sjme_attrOutNotNull sjme_jint* outId);
 257
 258 /**
 259  * Determines the list of libraries within the suite.
 260  *
 261  * @param inSuite The suite the request is being made in.
 262  * @param outLibraries The output library list.
 263  * @return Any resultant error code.
 264  * @since 2023/12/21
 265  */
 266 typedef sjme_errorCode (*sjme_rom_suiteListLibrariesFunc)(
 267         sjme_attrInNotNull sjme_rom_suite inSuite,
 268         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibraries);
 269
 270 typedef sjme_errorCode (*sjme_rom_suiteLoadLibraryFunc)();
 271
 272 struct sjme_rom_libraryFunctions
 273 {
 274         /** Closes the library. */
 275         sjme_rom_libraryCloseFunc close;
 276
 277         /** Initializes the library, implementation specific. */
 278         sjme_rom_libraryInitFunc init;
 279
 280         /** Function to get the path of a library. */
 281         sjme_rom_libraryPathFunc path;
 282
 283         /** Access of raw bytes of the input library. */
 284         sjme_rom_libraryRawData rawData;
 285
 286         /** The size of this library. */
 287         sjme_rom_libraryRawSizeFunc rawSize;
 288
 289         /** Access a resource as a stream. */
 290         sjme_rom_libraryResourceStreamFunc resourceStream;
 291 };
 292
 293 struct sjme_rom_suiteFunctions
 294 {
 295         /** Optional default launch parameters. */
 296         sjme_rom_suiteDefaultLaunchFunc defaultLaunch;
 297
 298         /** Initialize suite cache. */
 299         sjme_rom_suiteInitFunc init;
 300
 301         /** Returns the ID of the given library. */
 302         sjme_rom_suiteLibraryIdFunc libraryId;
 303
 304         /** Lists the libraries in the suite. */
 305         sjme_rom_suiteListLibrariesFunc list;
 306
 307         /** Loads a single library. */
 308         sjme_rom_suiteLoadLibraryFunc loadLibrary;
 309 };
 310
 311 struct sjme_rom_suiteBase
 312 {
 313         /** Common data. */
 314         sjme_nvm_commonBase common;
 315
 316         /** Functions. */
 317         const sjme_rom_suiteFunctions* functions;
 318
 319         /** The handle, may be to a seekable. */
 320         sjme_pointer handle;
 321
 322         /** Internal cache, used by suite implementations. */
 323         sjme_rom_suiteCache cache;
 324 };
 325
 326 /**
 327  * Initializes a library from a Zip that is already loaded.
 328  *
 329  * @param pool The pool to use for allocations.
 330  * @param outLibrary The resultant library.
 331  * @param libName The library name.
 332  * @param prefix Optional prefix when accessing Zip contents.
 333  * @param zip The Zip to access as a library.
 334  * @return Any resultant error, if any.
 335  * @since 2024/08/16
 336  */
 337 sjme_errorCode sjme_rom_libraryFromZip(
 338         sjme_attrInNotNull sjme_alloc_pool* pool,
 339         sjme_attrOutNotNull sjme_rom_library* outLibrary,
 340         sjme_attrInNotNull sjme_lpcstr libName,
 341         sjme_attrInNullable sjme_lpcstr prefix,
 342         sjme_attrInNotNull sjme_zip zip);
 343
 344 /**
 345  * Initializes a library from a Zip that is in memory, this will load the Zip.
 346  *
 347  * @param pool The pool to use for allocations.
 348  * @param outLibrary The resultant library.
 349  * @param libName The library name.
 350  * @param base The base address where the Zip is.
 351  * @param length The length of the Zip.
 352  * @return Any resultant error, if any.
 353  * @since 2024/01/01
 354  */
 355 sjme_errorCode sjme_rom_libraryFromZipMemory(
 356         sjme_attrInNotNull sjme_alloc_pool* pool,
 357         sjme_attrOutNotNull sjme_rom_library* outLibrary,
 358         sjme_attrInNotNull sjme_lpcstr libName,
 359         sjme_attrInNotNull sjme_cpointer base,
 360         sjme_attrInPositive sjme_jint length);
 361
 362 /**
 363  * Initializes a library from a Zip that is a given seekable, this will load
 364  * the Zip.
 365  *
 366  * @param pool The pool to use for allocations.
 367  * @param outLibrary The resultant library.
 368  * @param libName The library name.
 369  * @param seekable The seekable to access the Zip through.
 370  * @return Any resultant error, if any.
 371  * @since 2024/01/01
 372  */
 373 sjme_errorCode sjme_rom_libraryFromZipSeekable(
 374         sjme_attrInNotNull sjme_alloc_pool* pool,
 375         sjme_attrOutNotNull sjme_rom_library* outLibrary,
 376         sjme_attrInNotNull sjme_lpcstr libName,
 377         sjme_attrInNotNull sjme_seekable seekable);
 378
 379 /**
 380  * Calculates the hash of the given library.
 381  *
 382  * @param library The library to calculate the hash of.
 383  * @param outHash The output hash.
 384  * @return On any resultant error.
 385  * @since 2023/12/27
 386  */
 387 sjme_errorCode sjme_rom_libraryHash(
 388         sjme_attrInNotNull sjme_rom_library library,
 389         sjme_attrOutNotNull sjme_jint* outHash);
 390
 391 /**
 392  * Makes a virtual library from the given functions.
 393  *
 394  * @param pool The pool to allocate within.
 395  * @param outLibrary The output library.
 396  * @param libName The library name.
 397  * @param data Any data to forward to the initializer.
 398  * @param inFunctions The functions which define how to access the library.
 399  * @param inFrontEnd Input front end initialization, is optional.
 400  * @return Any error code.
 401  * @since 2023/12/29
 402  */
 403 sjme_errorCode sjme_rom_libraryNew(
 404         sjme_attrInNotNull sjme_alloc_pool* pool,
 405         sjme_attrOutNotNull sjme_rom_library* outLibrary,
 406         sjme_attrInNotNull sjme_lpcstr libName,
 407         sjme_attrInNullable sjme_pointer data,
 408         sjme_attrInNotNull const sjme_rom_libraryFunctions* inFunctions,
 409         sjme_attrInNullable const sjme_frontEnd* copyFrontEnd);
 410
 411 /**
 412  * Reads from a library directly to access its raw bytes.
 413  *
 414  * @param library The library to access.
 415  * @param destPtr The destination buffer.
 416  * @param srcPos The source position.
 417  * @param length The number of bytes to read.
 418  * @return Any resultant error if any.
 419  * @since 2023/12/30
 420  */
 421 sjme_errorCode sjme_rom_libraryRawRead(
 422         sjme_attrInNotNull sjme_rom_library library,
 423         sjme_attrOutNotNullBuf(length) sjme_pointer destPtr,
 424         sjme_attrInPositive sjme_jint srcPos,
 425         sjme_attrInPositive sjme_jint length);
 426
 427 /**
 428  * Reads from a library directly to access its raw bytes, this variant of
 429  * the function provides more control over offsets so that it can more easily
 430  * be used with iterators and such.
 431  *
 432  * @param library The library to access.
 433  * @param destPtr The destination buffer.
 434  * @param destOffset The offset into the destination.
 435  * @param srcPos The source position.
 436  * @param srcOffset The source offset.
 437  * @param length The number of bytes to read.
 438  * @return Any resultant error if any.
 439  * @since 2023/12/30
 440  */
 441 sjme_errorCode sjme_rom_libraryRawReadIter(
 442         sjme_attrInNotNull sjme_rom_library library,
 443         sjme_attrOutNotNullBuf(length) void* destPtr,
 444         sjme_attrInPositive sjme_jint destOffset,
 445         sjme_attrInPositive sjme_jint srcPos,
 446         sjme_attrInPositive sjme_jint srcOffset,
 447         sjme_attrInPositive sjme_jint length);
 448
 449 /**
 450  * Returns the raw size of the library.
 451  *
 452  * @param library The library to get the raw size of.
 453  * @param outSize The resultant size.
 454  * @return Any resultant error code.
 455  * @since 2023/12/30
 456  */
 457 sjme_errorCode sjme_rom_libraryRawSize(
 458         sjme_attrInNotNull sjme_rom_library library,
 459         sjme_attrOutNotNull sjme_jint* outSize);
 460
 461 /**
 462  * Obtains the given resource as a stream.
 463  *
 464  * @param library The library to get the resource from.
 465  * @param outStream The resultant stream.
 466  * @param rcName The name of the resource to obtain.
 467  * @return On any errors, if any.
 468  * @since 2023/12/31
 469  */
 470 sjme_errorCode sjme_rom_libraryResourceAsStream(
 471         sjme_attrInNotNull sjme_rom_library library,
 472         sjme_attrOutNotNull sjme_stream_input* outStream,
 473         sjme_attrInNotNull sjme_lpcstr rcName);
 474
 475 /**
 476  * Resolves the class path library by their ID.
 477  *
 478  * @param inSuite The suite to look within.
 479  * @param inIds The IDs to obtain.
 480  * @param outLibs The output libraries.
 481  * @return Any resultant error state.
 482  * @since 2023/12/18
 483  */
 484 sjme_errorCode sjme_rom_resolveClassPathById(
 485         sjme_attrInNotNull sjme_rom_suite inSuite,
 486         sjme_attrInNotNull const sjme_list_sjme_jint* inIds,
 487         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibs);
 488
 489 /**
 490  * Resolves the class path library by their name.
 491  *
 492  * @param inSuite The suite to look within.
 493  * @param inNames The names to obtain.
 494  * @param outLibs The output libraries.
 495  * @return Any resultant error state.
 496  * @since 2023/12/18
 497  */
 498 sjme_errorCode sjme_rom_resolveClassPathByName(
 499         sjme_attrInNotNull sjme_rom_suite inSuite,
 500         sjme_attrInNotNull const sjme_list_sjme_lpcstr* inNames,
 501         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibs);
 502
 503 /**
 504  * Obtains the default launch parameters from the given suite.
 505  *
 506  * @param inPool The pool to allocate within.
 507  * @param inSuite The suite to get the launch parameters from.
 508  * @param outMainClass The main class to launch.
 509  * @param outMainArgs The arguments to pass to the main class.
 510  * @param outById The main class path by ID.
 511  * @param outByName The main class path by name.
 512  * @return Any resultant error, if any.
 513  * @since 2024/08/16
 514  */
 515 sjme_errorCode sjme_rom_suiteDefaultLaunch(
 516         sjme_attrInNotNull sjme_alloc_pool* inPool,
 517         sjme_attrInNotNull sjme_rom_suite inSuite,
 518         sjme_attrOutNotNull sjme_lpstr* outMainClass,
 519         sjme_attrOutNotNull sjme_list_sjme_lpstr** outMainArgs,
 520         sjme_attrOutNotNull sjme_list_sjme_jint** outById,
 521         sjme_attrOutNotNull sjme_list_sjme_lpstr** outByName);
 522
 523 /**
 524  * Combines multiple suites into one.
 525  *
 526  * @param pool The pool to allocate within.
 527  * @param outSuite The output suite.
 528  * @param inSuites The input suites.
 529  * @param numInSuites The number of input suites.
 530  * @return
 531  */
 532 sjme_errorCode sjme_rom_suiteFromMerge(
 533         sjme_attrInNotNull sjme_alloc_pool* pool,
 534         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 535         sjme_attrInNotNull sjme_rom_suite* inSuites,
 536         sjme_attrInPositive sjme_jint numInSuites);
 537
 538 /**
 539  * Scans the payload for suites
 540  *
 541  * @param pool The pool to allocate within.
 542  * @param outSuite The output resultant suite, if there would be nothing in
 543  * here then this outputs @c NULL .
 544  * @param payloadConfig The payload configuration used.
 545  * @return Any error status.
 546  * @since 2023/12/15
 547  */
 548 sjme_errorCode sjme_rom_suiteFromPayload(
 549         sjme_attrInNotNull sjme_alloc_pool* pool,
 550         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 551         sjme_attrInNotNull const sjme_payload_config* payloadConfig);
 552
 553 /**
 554  * Initializes a suite from a Zip.
 555  *
 556  * @param pool The pool to use for allocations.
 557  * @param outSuite The resultant suite.
 558  * @param seekable The seekable to access the Zip through.
 559  * @return Any resultant error, if any.
 560  * @since 2024/08/11
 561  */
 562 sjme_errorCode sjme_rom_suiteFromZipSeekable(
 563         sjme_attrInNotNull sjme_alloc_pool* pool,
 564         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 565         sjme_attrInNotNull sjme_seekable seekable);
 566
 567 /**
 568  * Returns all of the libraries which are available within this suite.
 569  *
 570  * @param inSuite The input suite.
 571  * @param outLibs The resultant libraries.
 572  * @return Any resultant error state.
 573  * @since 2023/12/20
 574  */
 575 sjme_errorCode sjme_rom_suiteLibraries(
 576         sjme_attrInNotNull sjme_rom_suite inSuite,
 577         sjme_attrOutNotNull sjme_list_sjme_rom_library** outLibs);
 578
 579 /**
 580  * Makes a virtual suite from the given functions.
 581  *
 582  * @param pool The pool to allocate within.
 583  * @param outSuite The output suite.
 584  * @param data Any data to pass to the initializer.
 585  * @param inFunctions The functions which define how to access the suite.
 586  * @param copyFrontEnd Input front end initialization, is optional.
 587  * @return Any error code.
 588  * @since 2023/12/15
 589  */
 590 sjme_errorCode sjme_rom_suiteNew(
 591         sjme_attrInNotNull sjme_alloc_pool* pool,
 592         sjme_attrOutNotNull sjme_rom_suite* outSuite,
 593         sjme_attrInNullable sjme_pointer data,
 594         sjme_attrInNotNull const sjme_rom_suiteFunctions* inFunctions,
 595         sjme_attrInNullable const sjme_frontEnd* copyFrontEnd);
 596
 597 /*--------------------------------------------------------------------------*/
 598
 599 /* Anti-C++. */
 600 #ifdef __cplusplus
 601         #ifdef SJME_CXX_SQUIRRELJME_ROM_H
 602 }
 603                 #undef SJME_CXX_SQUIRRELJME_ROM_H
 604                 #undef SJME_CXX_IS_EXTERNED
 605         #endif /* #ifdef SJME_CXX_SQUIRRELJME_ROM_H */
 606 #endif     /* #ifdef __cplusplus */
 607
 608 #endif /* SQUIRRELJME_ROM_H */