BmnIArchiveLibRead.h

Go to the documentation of this file.

#pragma once
#ifndef BmnIArchiveLibRead_h
#define BmnIArchiveLibRead_h
 
// headers from this target
#include "BmnFileProcessingFlags.h"
// std:: headers
#include <cstddef>
#include <string>
 
/*
 * An interface class for all archive libraries that should read (uncompress) data from binary files
 */
struct BmnIArchiveLibRead
{
    BmnIArchiveLibRead() = default;
    virtual ~BmnIArchiveLibRead() = default;
 
    /*
     * A method that is called to uncompress compressed data
     * @param source A pointer to a buffer with the subsequent compressed data that should be uncompressed
     * @param sourceTotalSize A number of bytes available in the source buffer
     * @param numberOfReadBytes A number of bytes that were consumed while compressing. This value will be set.
     * @param output A pointer to a buffer that will be filled with uncompressed data
     * @param outputTotalSize A number of bytes that may be filled in the output buffer
     * @param numberOfSetOutputBytes A number of bytes that were set while decompressing. This value will be set.
     * @return A result status based on the success of this function
     */
    virtual BmnFileStreamResults Uncompress(const void* source,
                                            const size_t sourceTotalSize,
                                            size_t& numberOfReadBytes,
                                            void* output,
                                            const size_t outputTotalSize,
                                            size_t& numberOfSetOutputBytes) = 0;
 
    /*
     * If an error previously occurred, this method may be called to obtain its description
     * @return A string describing the last error, or an empty string if no error has occurred
     */
    [[nodiscard]] virtual std::string GetLastUncompressErrorDescription() const noexcept = 0;
 
    /*
     * A method that tells one if the underlying archive library may jump over the source file or not.
     * If it may not, it should be read sequentially and any "jumps" actually imply that all previous
     * compressed bytes were uncompressed.
     * @return Whether the underlying library allow fast jumping over the source data
     */
    [[nodiscard]] virtual bool JumpsAllowed() const noexcept = 0;
 
    /*
     * A method that can be called to quickly jump to a specific position in uncompressed data. This method
     * should be used only if `JumpsAllowed` return 'true'. Otherwise, it will do nothing!
     * @param value A place in output data to which the reader should jump (if jumps are allowed)
     */
    virtual void JumpTo(size_t value) = 0;
 
    /*
     * Get the number of currently decompressed bytes. This only includes bytes that are not part of
     * various headers (actual number of output bytes)
     * @return The number of currently decompressed bytes
     */
    [[nodiscard]] virtual size_t GetNumberOfDecompressedBytes() const noexcept = 0;
 
    /*
     * Some libraries if not all will be able to tell if the end of the stream is reached.
     * This is important because the used library might cache some data internally, which could result
     * in data loss. Thus, calling this method to check if we have processed all the data is
     * advisable.
     * @return 'true' if the underlying stream has a bad state or empty internal cache, or 'false' otherwise
     */
    [[nodiscard]] virtual bool HasReachedTheEndOfStream() const noexcept = 0;
 
    /*
     * This method can help us determine if an error was detected in the past while trying to decompress data
     * @return 'true' if an underlying decompression stream is in a good state, or 'false' if not
     */
    [[nodiscard]] virtual bool IsStreamInGoodState() const noexcept = 0;
};
 
#endif   // BmnIArchiveLibRead_h