579 lines
16 KiB
C++
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)
|