Files

579 lines
16 KiB
C++

/**
* @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 <ctime>
#include <sys/stat.h>
//! 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<CompressionLevel>::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<uint32_t>
{
public:
typedef TypeSafeFlags::Value<AccessFlags, 0x00000000> None;
typedef TypeSafeFlags::Value<AccessFlags, 0x00000001> Read; ///< Open/create file with read access.
typedef TypeSafeFlags::Value<AccessFlags, 0x00000002> Write; ///< Open/create file with write access.
typedef TypeSafeFlags::Value<AccessFlags, 0x00000006> Append; ///< Open/create file with append access. This flag contains the Write bit
typedef TypeSafeFlags::Type<AccessFlags, None> Type;
};
//! Share flags.
class ShareFlags : public TypeSafeFlags::Underlying<uint32_t>
{
public:
typedef TypeSafeFlags::Value<ShareFlags, 0x00000000> None;
typedef TypeSafeFlags::Value<ShareFlags, 0x00000001> Read; ///< Open/create file with read sharing access.
typedef TypeSafeFlags::Value<ShareFlags, 0x00000002> Write; ///< Open/create file with write sharing access.
typedef TypeSafeFlags::Type<ShareFlags, None> 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<byte_t> 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)