File.hpp

Go to the documentation of this file.

// ======================================================================
// \title Os/File.hpp
// \brief common function definitions for Os::File
// ======================================================================
#ifndef Os_File_hpp_
#define Os_File_hpp_

#include <Fw/FPrimeBasicTypes.hpp>
#include <Fw/Types/ConstStringBase.hpp>
#include <Os/Os.hpp>
#include <Utils/Hash/Hash.hpp>

// Forward declaration for UTs
namespace Os {
namespace Test {
namespace FileTest {
struct Tester;
}
}  // namespace Test
}  // namespace Os

namespace Os {

struct FileHandle {};

// This class encapsulates a very simple file interface that has the most often-used features
class FileInterface {
  public:
    enum Mode {
        OPEN_NO_MODE,     
        OPEN_READ,        
        OPEN_CREATE,      
        OPEN_WRITE,       
        OPEN_SYNC_WRITE,  
        OPEN_APPEND,      
        MAX_OPEN_MODE     
    };

    enum Status {
        OP_OK,              
        DOESNT_EXIST,       
        NO_SPACE,           
        NO_PERMISSION,      
        BAD_SIZE,           
        NOT_OPENED,         
        FILE_EXISTS,        
        NOT_SUPPORTED,      
        INVALID_MODE,       
        INVALID_ARGUMENT,   
        NO_MORE_RESOURCES,  
        OTHER_ERROR,        
        OUTSIDE_SANDBOX,    
        MAX_STATUS          
    };

    enum OverwriteType {
        NO_OVERWRITE,  
        OVERWRITE,     
        MAX_OVERWRITE_TYPE
    };

    enum SeekType {
        RELATIVE,  
        ABSOLUTE,  
        MAX_SEEK_TYPE
    };

    enum WaitType {
        NO_WAIT,  
        WAIT,     
        MAX_WAIT_TYPE
    };

    virtual ~FileInterface() = default;

    virtual Status open(const char* path, Mode mode, OverwriteType overwrite) = 0;

    virtual void close() = 0;

    virtual Status size(FwSizeType& size_result) = 0;

    virtual Status position(FwSizeType& position_result) = 0;

    virtual Status preallocate(FwSizeType offset, FwSizeType length) = 0;

    virtual Status seek(FwSignedSizeType offset, SeekType seekType) = 0;

    virtual Status flush() = 0;

    virtual Status read(U8* buffer, FwSizeType& size, WaitType wait) = 0;

    virtual Status write(const U8* buffer, FwSizeType& size, WaitType wait) = 0;

    virtual FileHandle* getHandle() = 0;

    static FileInterface* getDelegate(FileHandleStorage& aligned_placement_new_memory,
                                      const FileInterface* to_copy = nullptr);
};

class File final : public FileInterface {
    friend struct Os::Test::FileTest::Tester;

  public:
    File();
    ~File() final;

    File(const File& other);

    File& operator=(const File& other);

    bool isOpen() const;

    // ------------------------------------
    // Functions supplying default values
    // ------------------------------------

    Os::FileInterface::Status open(const char* path, Mode mode);

    Os::FileInterface::Status open(const char* path, FwSizeType length, Mode mode);

    Os::FileInterface::Status open(const Fw::ConstStringBase& path, Mode mode);

    Os::FileInterface::Status open(const Fw::ConstStringBase& path, Mode mode, OverwriteType overwrite);

    Status read(U8* buffer, FwSizeType& size);

    Status write(const U8* buffer, FwSizeType& size);

    // ------------------------------------
    // Functions overrides
    // ------------------------------------

    Os::FileInterface::Status open(const char* path, Mode mode, OverwriteType overwrite) override;

    Os::FileInterface::Status open(const char* path, FwSizeType length, Mode mode, OverwriteType overwrite);

    void close() override;

    Status size(FwSizeType& size_result) override;

    Status position(FwSizeType& position_result) override;

    Status preallocate(FwSizeType offset, FwSizeType length) override;

    Status seek(FwSignedSizeType offset, SeekType seekType) override;

    Status seek_absolute(FwSizeType offset_unsigned);

    Status flush() override;


    Status read(U8* buffer, FwSizeType& size, WaitType wait) override;

    Status readline(U8* buffer, FwSizeType& size, WaitType wait);

    Status write(const U8* buffer, FwSizeType& size, WaitType wait) override;

    FileHandle* getHandle() override;

    Status calculateCrc(U32& crc);

    Status incrementalCrc(FwSizeType& size);

    Status finalizeCrc(U32& crc);

  private:
    static const U32 INITIAL_CRC = 0xFFFFFFFF;  

    Mode m_mode = Mode::OPEN_NO_MODE;  

    Utils::Hash m_hash;  
    U8 m_crc_buffer[FW_FILE_CHUNK_SIZE];

    // This section is used to store the implementation-defined file handle. To Os::File and fprime, this type is
    // opaque and thus normal allocation cannot be done. Instead, we allow the implementor to store then handle in
    // the byte-array here and set `handle` to that address for storage.
    //
    alignas(FW_HANDLE_ALIGNMENT) FileHandleStorage m_handle_storage;  
    FileInterface& m_delegate;                                        
};
}  // namespace Os
#endif