Poke_Transporter_GB/include/FileContainerReader.h

#ifndef _FILECONTAINERREADER_H
#define _FILECONTAINERREADER_H

#include "typeDefs.h"

#define FILE_NAME_LENGTH 16
#define DEFAULT_CHUNK_SIZE 2048

/**
 * @brief This class provides functionality to read files from the file container format
 * created by the make-file-container tool.
 *
 * This format consists of multiple compressed chunks.
 *
 * It is done this way to keep the decompression buffer small (because we can't afford to consume too much IWRAM)
 * but still allow for large file containers and bundling files together. (which you might want to do to improve compression ratios)
 * The chunk size can be configured when creating the file container, and the
 * FileContainerReader will read and decompress chunks on demand when seeking or reading data.
 */
class FileContainerReader
{
public:
    FileContainerReader(const u8 **chunkList, u32 chunkCount, u32 chunkSize = DEFAULT_CHUNK_SIZE);
    ~FileContainerReader();

    /**
     * @brief This function initializes the FileContainerReader. It should be called before any other function is used.
     * The reason for this initialization step is to give you control over the moment when the first chunk is decompressed.
     * This can be useful if you want to perform some setup or checks before the decompression process begins. By calling init() explicitly, you can ensure that the FileContainerReader is ready to handle file reading operations at the appropriate time in your application.
     *
     * Note: because of this, we also only pass the decompression buffer here
     * If the decompression buffer is not large enough to hold the chunks,
     * the function will return false and the FileContainerReader will not be initialized. In this case, you should provide a larger decompression buffer and call init() again.
     *
     * If it DOES return true, please note that the FileContainerReader will keep using the decompressionBuffer_ until
     * it gets destroyed.
     */
    bool init(u8 *decompressionBuffer, u32 decompressionBufferSize);

    /**
     * @brief Returns the number of files stored in the file container.
     */
    u32 getNumberOfFiles() const;

    /**
     * @brief IF the file container stores the file names,
     * this function returns a pointer to the file name of the file at the given index.
     * Otherwise, it returns nullptr.
     */
    const char* getFileName(u32 fileIndex);

    /**
     * @brief This function returns the size of the file at the given index.
     */
    u32 getFileSize(u32 fileIndex) const;

    /**
     * @brief This function seeks to the beginning of the file at the given index.
     */
    void seekToFile(u32 fileIndex);

    /**
     * @brief Read data from the current position in the file container into the provided buffer.
     */
    void read(u8 *buffer, u32 size);

    /**
     * @brief Gives you a direct pointer to the specified file in the decompression buffer. (unsafe!)
     *
     * This is useful to use data directly from the decompression buffer without having to allocate and
     * copy another buffer. This is essential in high memory pressure scenarios, such as mystery_gift_builder.
     * We can't afford to keep multiple linebuffers in memory in addition to the decompression buffer and all the other variables there.
     *
     * WARNING: this is only safe if you know the file is stored fully in the current chunk, because files may span multiple chunks.
     * Or if the container only consists of a single chunk.
     * Pointers acquired this way will become stale whenever a seek is done to a position in a different chunk, 
     * as that will cause the decompression buffer to be overwritten with the new chunk's data.
     */
    u8 *getPointerToFileInDecompressionBuffer(u32 fileIndex);

    /**
     * @brief Combines seekToFile and read().
     * Just a convenience function to make our code shorter :-)
     */
    void seekAndRead(u32 fileIndex, u8 *buffer, u32 size);

    /**
     * @brief Even shorter variant of seekAndRead that reads the entire file at once.
     * But it assumes you have provided a large enough buffer to hold the entire file.
     *
     * (useful for text table reading)
     */
    void readFile(u32 fileIndex, u8 *buffer);
protected:
private:
    /**
     * @brief This function calculates the file offset for the specified file index
     * The file offset is determined by reading the file index (which contains the file entry sizes)
     * and summing up the sizes of all previous entries + header size + optional name table size
     * (if names are stored).
     */
    u32 getFileOffset(u32 fileIndex) const;

    /**
     * @brief This function seeks to the specified absolute offset in the file container data.
     * Absolute offset refers to an offset across the file container chunks.
     */
    void seek(u32 offset);

    /**
     * @brief This function just uncompresses the chunk at the specified index
     * into decompressionBuffer_.
     */
    void uncompressChunk(u32 chunkIndex);

    char fileNameBuffer_[FILE_NAME_LENGTH + 1];
    u8 *decompressionBuffer_;
    const u8 **chunkList_;
    u32 chunkCount_;
    u32 chunkSize_;
    u16 *fileIndex_;
    u32 curChunkIndex_;
    u32 curPos_;
    u32 fileCount_;
    bool hasNames_;
};

#endif