/** * @file include/ActivMiddleware/ActivBase/IFile.h * * @brief Header file for file class. */ #if (!defined ACTIV_BASE_IFILE_H) #define ACTIV_BASE_IFILE_H #include "ActivMiddleware/ActivBase/External.h" #include "ActivMiddleware/ActivBase/ActivFileTypes.h" #include "ActivMiddleware/Misc/TypeSafeFlags.h" #include ACTIV_BOOST_INCLUDE(move/move.hpp) #include ACTIV_BOOST_INCLUDE(container/vector.hpp) #include #include //! Activ namespace. namespace Activ { /** * @brief IFile class. */ class IFile { ACTIV_BOOST_MOVABLE_BUT_NOT_COPYABLE(IFile) public: typedef int32_t CompressionLevel; ///< The compression level typedef. //! Activ compression level defines. static const CompressionLevel COMPRESSION_LEVEL_NONE = Boost::integer_traits::const_max; static const CompressionLevel COMPRESSION_LEVEL_BEST = COMPRESSION_LEVEL_NONE - 1; static const CompressionLevel COMPRESSION_LEVEL_FAST = COMPRESSION_LEVEL_NONE - 2; static const CompressionLevel COMPRESSION_LEVEL_DEFAULT = COMPRESSION_LEVEL_NONE - 3; //! Access flags. class AccessFlags : public TypeSafeFlags::Underlying { public: typedef TypeSafeFlags::Value None; typedef TypeSafeFlags::Value Read; ///< Open/create file with read access. typedef TypeSafeFlags::Value Write; ///< Open/create file with write access. typedef TypeSafeFlags::Value Append; ///< Open/create file with append access. This flag contains the Write bit typedef TypeSafeFlags::Type Type; }; //! Share flags. class ShareFlags : public TypeSafeFlags::Underlying { public: typedef TypeSafeFlags::Value None; typedef TypeSafeFlags::Value Read; ///< Open/create file with read sharing access. typedef TypeSafeFlags::Value Write; ///< Open/create file with write sharing access. typedef TypeSafeFlags::Type Type; }; //! Seek method. enum SeekMethod { SEEK_METHOD_BEGIN, SEEK_METHOD_END, SEEK_METHOD_CURRENT }; #if (defined ACTIV_PLATFORM_POSIX) //! Actions for ModifyMode(). enum ModifyModeAction { MODIFY_MODE_ACTION_SET, ///< Set permission bits to provided value. MODIFY_MODE_ACTION_ADD, ///< Add permission bits to existing. MODIFY_MODE_ACTION_REMOVE ///< Remove permission bits from existing. }; #endif //! Helper class that will delete an open IFile when this object goes out of scope. class ScopedDelete { public: /** * @brief Constructor. * * @param file the IFile to delete. */ ACTIV_BASE_API ScopedDelete(IFile &file); /** * @brief Destructor. * * If the IFile passed to the constructor is open, delete it. */ ACTIV_BASE_API ~ScopedDelete(); private: IFile &m_file; }; //! Destructor. ACTIV_BASE_API virtual ~IFile(); /** * @brief Create the file. * * Derived implementations need to handle cleaning up the base file descriptor upon failure. * * @param fileName the file name. * @param accessFlags the file access flags. * @param shareFlags the file sharing flags. * @param shouldFailIfExists if true, fail if the file already exists. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_ALREADY_OPEN * @retval STATUS_CODE_ALREADY_EXISTS if shouldFailIfExists true and the file exists. * @retval ... */ ACTIV_BASE_API virtual StatusCode Create(const String &fileName, const AccessFlags::Type accessFlags, const ShareFlags::Type shareFlags, const bool shouldFailIfExists = false); /** * @brief Create the file if it doesn't exist, otherwise open it. * * @param fileName the file name. * @param accessFlags the file access flags. * @param shareFlags the file sharing flags. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_ALREADY_OPEN * @retval ... */ ACTIV_BASE_API StatusCode CreateOrOpen(const String &fileName, const AccessFlags::Type accessFlags, const ShareFlags::Type shareFlags); /** * @brief Open the file. * * Derived implementations need to handle cleaning up the base file descriptor upon failure. * * @param fileName the file name. * @param accessFlags the file access flags. * @param shareFlags the file sharing flags. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_ALREADY_OPEN * @retval ... */ ACTIV_BASE_API virtual StatusCode Open(const String &fileName, const AccessFlags::Type accessFlags, const ShareFlags::Type shareFlags); /** * @brief Close the file. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API virtual StatusCode Close(); #if (defined ACTIV_PLATFORM_POSIX) /** * @brief Modify the permission mode of the file. * * @param modifyModeAction whether to set, add or remove permission bits. * @param mode the permission bits to add or remove. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API StatusCode ModifyMode(const ModifyModeAction modifyModeAction, const mode_t mode); /** * @brief Modify the permission mode of a file or directory. * * @param path the path to the file or directory. * @param modifyModeAction whether to set, add or remove permission bits. * @param mode the permission bits to add or remove. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode ModifyMode(const String &path, const ModifyModeAction modifyModeAction, const mode_t mode); #endif /** * @brief Read from a file. * * @param pBuffer the buffer to read into. * @param nBytesToRead the number of bytes to read. * @param nBytesRead the number of bytes read. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API StatusCode Read(void *pBuffer, const size_t nBytesToRead, size_t &nBytesRead); /** * @brief Read from a file. * * @param pBuffer the buffer to read into. * @param nBytesToRead the number of bytes to read. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval STATUS_CODE_FAILURE * @retval ... */ ACTIV_BASE_API StatusCode Read(void *pBuffer, const size_t nBytesToRead); /** * @brief Read a line from a file. * * @param line the buffer to read the line into. * @param endOfLine the buffer to read the end of line into. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval STATUS_CODE_END_OF_DATA * @retval STATUS_CODE_NOT_SUPPORTED * @retval ... */ ACTIV_BASE_API StatusCode ReadLine(String &line, String &endOfLine); /** * @brief Read a line from a file. * * @param line the buffer to read the line into. End of line characters are not stored. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval STATUS_CODE_END_OF_DATA * @retval ... */ ACTIV_BASE_API StatusCode ReadLine(String &line); /** * @brief Write to a file. * * @param pBuffer the buffer to write from. * @param nBytesToWrite the number of bytes to write. * @param nBytesWritten the number of bytes written. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API StatusCode Write(const void *pBuffer, const size_t nBytesToWrite, size_t &nBytesWritten); /** * @brief Write to a file. * * @param pBuffer the buffer to write from. * @param nBytesToWrite the number of bytes to write. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval STATUS_CODE_FAILURE * @retval ... */ ACTIV_BASE_API StatusCode Write(const void *pBuffer, const size_t nBytesToWrite); /** * @brief Flush a file to disk. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval STATUS_CODE_FAILURE * @retval ... */ ACTIV_BASE_API virtual StatusCode Flush(); /** * @brief Get the current position within the file. * * This might not include any unflushed data and must offset the return value * with data in the ReadLine buffer. * * @param position the position within the file. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API StatusCode GetPosition(uint64_t &position) const; /** * @brief Get the decoded position. * * This might not include any unflushed data and must offset the return value * with data in the ReadLine buffer. * * @param position the position within the codec. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API virtual StatusCode GetDecodedPosition(uint64_t &position) const; /** * @brief Set the current position within the file. * * The return value must handle the data in the ReadLine buffer. * * @param position the position within the file. * @param seekMethod the seek method. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval STATUS_CODE_INVALID_PARAMETER * @retval ... */ ACTIV_BASE_API virtual StatusCode SetPosition(int64_t position, const SeekMethod seekMethod = SEEK_METHOD_BEGIN); /** * @brief Get the size of the file. * * If gzip compression is enabled, this does not include any unflushed data buffered inside the compressor * * @param size the size of the file. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval STATUS_CODE_FAILURE * @retval ... */ ACTIV_BASE_API StatusCode GetSize(uint64_t &size) const; /** * @brief Set the size of the file. * * Not supported in Gzip compression mode. * * @param size the size of the file. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval STATUS_CODE_NOT_SUPPORTED * @retval ... */ ACTIV_BASE_API StatusCode SetSize(uint64_t size); /** * @brief Get the last write date time of the file. * * @param tm reference to a tm structure to receive the UTC date / time. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API StatusCode GetLastWriteDateTime(std::tm &tm) const; /** * @brief Get the creation date time of the file. * * @param tm reference to a tm structure to receive the UTC date / time. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API StatusCode GetCreationDateTime(std::tm &tm) const; /** * @brief Get the last access date time of the file. * * @param tm reference to a tm structure to receive the UTC date / time. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API StatusCode GetLastAccessDateTime(std::tm &tm) const; /** * @brief Get the file name. * * @param fileName the file name. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN */ ACTIV_BASE_API StatusCode GetFileName(String &fileName) const; //! Get the underlying file handle HANDLE GetHandle() const; //! Is the file open? bool IsOpen() const; //! Get the file type FileType GetFileType() const; /** * @brief Get the file type of the file. * * @param fileName the name of the file. * @param fileType the file type. * * @retval STATUS_CODE_SUCCESS * @retval ... */ ACTIV_BASE_API static StatusCode GetFileTypeFromFile(const String& fileName, FileType &fileType); /** * @brief Get the file type of the file. * * @param fileName the name of the file. * * @return the file type/ * * @throws StatusCodeException */ ACTIV_BASE_API static FileType GetFileTypeFromFile(const String& fileName); protected: /** * @brief Constructor. * * @param fileType the file type. */ ACTIV_BASE_API explicit IFile(const FileType fileType); /** * @brief Move constructor. * * @param rhs transfer ownership of the underlying file managed by @a rhs to this. */ IFile(ACTIV_BOOST_RV_REF(IFile) rhs) : m_fileHandle(rhs.m_fileHandle), m_fileType(rhs.m_fileType), m_accessFlags(rhs.m_accessFlags), m_readLineBuffer(CxxYZ::move(rhs.m_readLineBuffer)), m_bufferOffset(rhs.m_bufferOffset), m_bufferLength(rhs.m_bufferLength) #if (defined ACTIV_PLATFORM_WINDOWS) ,m_shouldDeleteOnClose(false) #endif // (defined ACTIV_PLATFORM_WINDOWS) { // Inline here for G++. m_fileName.swap(rhs.m_fileName), rhs.m_fileHandle = INVALID_HANDLE_VALUE; rhs.m_bufferOffset = 0; rhs.m_bufferLength = 0; } /** * @brief Move assignment operator. * * Transfer ownership of a file from another IFile object to this. * * If this object has a file open, it is closed. The underlying file associated with rhs is transferred to this object, * and no file is then associated with rhs. * * @param rhs the file to transfer to this object. * * @return *this */ IFile &operator=(ACTIV_BOOST_RV_REF(IFile) rhs) { // Inline here for G++. if (this != &rhs) { (void) Close(); m_fileName.clear(); m_fileName.swap(rhs.m_fileName); m_fileHandle = rhs.m_fileHandle; m_fileType = rhs.m_fileType; m_accessFlags = rhs.m_accessFlags; m_readLineBuffer = CxxYZ::move(rhs.m_readLineBuffer); m_bufferOffset = rhs.m_bufferOffset; m_bufferLength = rhs.m_bufferLength; rhs.m_fileHandle = INVALID_HANDLE_VALUE; rhs.m_accessFlags = AccessFlags::None(); rhs.m_bufferOffset = 0; rhs.m_bufferLength = 0; // Not transferring m_shouldDeleteOnClose; it is specific to the IFile passed to the ScopedDelete object. } return *this; } /** * @brief Duplicate the a file handle into a C runtime file descriptor. * * @param fileHandle the file handle to duplicate. * @param accessFlags the current access flags. * @param fileDescriptor the duplicated C runtime file descriptor. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_INITIALIZED */ ACTIV_BASE_API static StatusCode DuplicateFileHandle(const HANDLE fileHandle, const AccessFlags::Type accessFlags, int &fileDescriptor); /** * @brief Decode data and read to a buffer. * * @param pBuffer the buffer to read into. * @param nBytesToRead the number of bytes to read. * @param nBytesRead the number of bytes read. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API virtual StatusCode Decode(void *pBuffer, const size_t nBytesToRead, size_t &nBytesRead) = 0; /** * @brief Encode and write buffer. * * @param pBuffer the buffer to write from. * @param nBytesToWrite the number of bytes to write. * @param nBytesWritten the number of bytes written. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_NOT_OPEN * @retval ... */ ACTIV_BASE_API virtual StatusCode Encode(const void *pBuffer, const size_t nBytesToWrite, size_t &nBytesWritten) = 0; typedef Boost::container::vector DataBuffer; ///< The data buffer type definition. String m_fileName; HANDLE m_fileHandle; FileType m_fileType; AccessFlags::Type m_accessFlags; DataBuffer m_readLineBuffer; size_t m_bufferOffset; size_t m_bufferLength; #if (defined ACTIV_PLATFORM_WINDOWS) bool m_shouldDeleteOnClose; #endif // (defined ACTIV_PLATFORM_WINDOWS) }; // --------------------------------------------------------------------------------------------------------------------------------- inline HANDLE IFile::GetHandle() const { return m_fileHandle; } // --------------------------------------------------------------------------------------------------------------------------------- inline bool IFile::IsOpen() const { return (INVALID_HANDLE_VALUE != m_fileHandle); } // --------------------------------------------------------------------------------------------------------------------------------- inline FileType IFile::GetFileType() const { return m_fileType; } } // namespace Activ #endif // (!defined ACTIV_BASE_IFILE_H)