GenericPlatformFile.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
 
/*=============================================================================================
    GenericPlatformFile.h: Generic platform file interfaces
==============================================================================================*/
 
#pragma once
 
#include "Containers/Array.h"
#include "Containers/StringView.h"
#include "Containers/UnrealString.h"
#include "CoreTypes.h"
#include "HAL/PlatformMemory.h"
#include "Math/NumericLimits.h"
#include "Misc/AssertionMacros.h"
#include "Misc/DateTime.h"
#include "Misc/EnumClassFlags.h"
#include "Templates/Function.h"
#include "Templates/ValueOrError.h"
 
class FArchive;
class IMappedFileHandle;
class IAsyncReadFileHandle;
namespace ELogVerbosity { enum Type : uint8; }
 
enum EAsyncIOPriorityAndFlags 
{
    AIOP_PRIORITY_MASK = 0x000000ff,
 
    // Flags - combine with priorities if needed
    AIOP_FLAG_PRECACHE          = 0x00000100,
    AIOP_FLAG_DONTCACHE         = 0x00000200,
    // Use it to specify memory where read from cpu can be slow
    AIOP_FLAG_HW_TARGET_MEMORY  = 0x00000400,   
 
    // Priorities
    AIOP_MIN = 0,
    AIOP_Low,
    AIOP_BelowNormal,
    AIOP_Normal,
    AIOP_High,
    AIOP_CriticalPath,
    AIOP_MAX = AIOP_CriticalPath,
    AIOP_NUM,
 
    // Legacy (for back-compat). Better to specify priority and AIOP_FLAG_PRECACHE separately
    AIOP_Precache = AIOP_MIN | AIOP_FLAG_PRECACHE,
};
ENUM_CLASS_FLAGS(EAsyncIOPriorityAndFlags);
 
enum class EPlatformFileRead : uint8
{
    None = 0x0,
    AllowWrite = 0x01   // attempts to open for read while allowing others to write
};
 
ENUM_CLASS_FLAGS(EPlatformFileRead);
 
enum class EPlatformFileWrite : uint8
{
    None = 0x0,
    AllowRead = 0x01    // attempts to open for write while allowing others to read
};
 
ENUM_CLASS_FLAGS(EPlatformFileWrite);
 
enum class EDirectoryVisitorFlags : uint8
{
    None = 0x0,
    ThreadSafe = 0x01   // should be set when the Visit function can be called from multiple threads at once.
};
 
enum class ESymlinkResult : int8
{
    Unimplemented = -1,
    NonSymlink = 0,
    Symlink = 1,
};
 
ENUM_CLASS_FLAGS(EDirectoryVisitorFlags);
 
enum class EFileJournalResult
{
    Success,
    InvalidPlatform,
    InvalidVolumeName,
    JournalNotActive,
    JournalWrapped,
    FailedOpenJournal,
    FailedDescribeJournal,
    FailedReadJournal,
    JournalInternalError,
    UnhandledJournalVersion,
};
 
class IFileHandle
{
public:
    virtual ~IFileHandle()
    {
    }
 
    virtual int64       Tell() = 0;
    virtual bool        Seek(int64 NewPosition) = 0;
 
    virtual bool        SeekFromEnd(int64 NewPositionRelativeToEnd = 0) = 0;
 
    virtual bool        Read(uint8* Destination, int64 BytesToRead) = 0;
 
    virtual bool        ReadAt(uint8* Destination, int64 BytesToRead, int64 Offset) = 0;
 
    virtual bool        Write(const uint8* Source, int64 BytesToWrite) = 0;
 
    virtual bool        Flush(const bool bFullFlush = false) = 0;
 
    virtual bool        Truncate(int64 NewSize) = 0;
 
    virtual void        ShrinkBuffers()
    {
    }
 
public:
 
    CORE_API virtual int64      Size();
};
 
 
struct FFileStatData
{
    FFileStatData()
        : CreationTime(FDateTime::MinValue())
        , AccessTime(FDateTime::MinValue())
        , ModificationTime(FDateTime::MinValue())
        , FileSize(-1)
        , bIsDirectory(false)
        , bIsReadOnly(false)
        , bIsValid(false)
    {
    }
 
    FFileStatData(FDateTime InCreationTime, FDateTime InAccessTime, FDateTime InModificationTime, const int64 InFileSize, const bool InIsDirectory, const bool InIsReadOnly)
        : CreationTime(InCreationTime)
        , AccessTime(InAccessTime)
        , ModificationTime(InModificationTime)
        , FileSize(InFileSize)
        , bIsDirectory(InIsDirectory)
        , bIsReadOnly(InIsReadOnly)
        , bIsValid(true)
    {
    }
 
    FDateTime CreationTime;
 
    FDateTime AccessTime;
 
    FDateTime ModificationTime;
 
    int64 FileSize;
 
    bool bIsDirectory : 1;
 
    bool bIsReadOnly : 1;
 
    bool bIsValid : 1;
};
 
 
typedef uint64 FFileJournalId;
inline constexpr FFileJournalId FileJournalIdInvalid = static_cast<FFileJournalId>(MAX_uint64);
 
typedef uint64 FFileJournalEntryHandle;
inline constexpr FFileJournalEntryHandle FileJournalEntryHandleInvalid = static_cast<FFileJournalEntryHandle>(MAX_uint64);
 
struct FFileJournalFileHandle
{
    bool operator==(const FFileJournalFileHandle& Other) const;
    bool operator!=(const FFileJournalFileHandle& Other) const;
    CORE_API FString ToString();
 
    uint8 Bytes[20];
};
uint32 GetTypeHash(const FFileJournalFileHandle&);
CORE_API extern const FFileJournalFileHandle FileJournalFileHandleInvalid;
 
struct FFileJournalData
{
    FFileJournalData();
 
    FDateTime ModificationTime;
    FFileJournalFileHandle JournalHandle = FileJournalFileHandleInvalid;
    bool bIsValid : 1;
    bool bIsDirectory : 1;
    bool bIsReparsePoint : 1;
    bool bIsReadOnly : 1;
};
 
class FFileSystemError
{
public:
    FFileSystemError() = delete;
 
    FFileSystemError(const FFileSystemError&) = delete;
    FFileSystemError(FFileSystemError&&) = default; 
    FFileSystemError& operator=(const FFileSystemError&) = delete;
    FFileSystemError& operator=(FFileSystemError&&) = default;
 
    explicit FFileSystemError(FString&& InErrorMessage, int32 InSystemErrorCode = 0)
        : ErrorMessage(MoveTemp(InErrorMessage))
        , SystemErrorCode(InSystemErrorCode)
    {
    }
 
    FString GetMessage()
    {
        if (SystemErrorCode != 0)
        {
            TCHAR FormattedErrorMsg[MAX_SPRINTF] = { 0 };
            FPlatformMisc::GetSystemErrorMessage(FormattedErrorMsg, UE_ARRAY_COUNT(FormattedErrorMsg), SystemErrorCode);
 
            return FString::Printf(TEXT("%s [%s (%d)]"), *ErrorMessage, FormattedErrorMsg, SystemErrorCode);
        }
        else
        {
            return ErrorMessage;
        }
    }
 
    template <typename CharType>
    friend inline TStringBuilderBase<CharType>& operator<<(TStringBuilderBase<CharType>& Builder, const FFileSystemError& Error)
    {
        TCHAR FormattedErrorMsg[MAX_SPRINTF] = { 0 };
        FPlatformMisc::GetSystemErrorMessage(FormattedErrorMsg, UE_ARRAY_COUNT(FormattedErrorMsg), Error.SystemErrorCode);
 
        Builder << Error.ErrorMessage << TEXT(" [") << FormattedErrorMsg << TEXT(" (") << Error.SystemErrorCode << TEXT(")]");
        return Builder;
    }
 
private:
    FString ErrorMessage;
    int32 SystemErrorCode;
};
 
using FFileOpenResult = TValueOrError<TUniquePtr<IFileHandle>, FFileSystemError>;
using FFileOpenAsyncResult = TValueOrError<TUniquePtr<IAsyncReadFileHandle>, FFileSystemError>;
 
using FOpenMappedResult = TValueOrError<TUniquePtr<IMappedFileHandle>, FFileSystemError>;
 
class IPlatformFile
{
public:
    static CORE_API IPlatformFile& GetPlatformPhysical();
    static CORE_API const TCHAR* GetPhysicalTypeName();
    CORE_API IPlatformFile();
    CORE_API virtual ~IPlatformFile();
 
    virtual void SetSandboxEnabled(bool bInEnabled)
    {
    }
 
    virtual bool IsSandboxEnabled() const
    {
        return false;
    }
 
    virtual bool ShouldBeUsed(IPlatformFile* Inner, const TCHAR* CmdLine) const
    {
        return false;
    }
 
    virtual bool        Initialize(IPlatformFile* Inner, const TCHAR* CmdLine) = 0;
 
    virtual void        InitializeAfterSetActive() { }
 
    virtual void        InitializeAfterProjectFilePath() { }
 
    virtual void        MakeUniquePakFilesForTheseFiles(const TArray<TArray<FString>>& InFiles) { }
 
    virtual void        InitializeNewAsyncIO() { }
 
    virtual void        AddLocalDirectories(TArray<FString> &LocalDirectories)
    {
        if (GetLowerLevel())
        {
            GetLowerLevel()->AddLocalDirectories(LocalDirectories);
        }
    }
 
    virtual void        BypassSecurity(bool bInBypass)
    {
        if (GetLowerLevel() != nullptr)
        {
            GetLowerLevel()->BypassSecurity(bInBypass);
        }
    }
 
    virtual void Tick() { }
    virtual IPlatformFile* GetLowerLevel() = 0;
    virtual void SetLowerLevel(IPlatformFile* NewLowerLevel) = 0;
    virtual const TCHAR* GetName() const = 0;
    virtual bool        FileExists(const TCHAR* Filename) = 0;
    virtual int64       FileSize(const TCHAR* Filename) = 0;
    virtual bool        DeleteFile(const TCHAR* Filename) = 0;
    virtual bool        DeleteFiles(const TArrayView<const TCHAR*>& Filenames)
    {
        bool bOneFailed = false;
 
        for (const TCHAR* File : Filenames)
        {
            bOneFailed |= !DeleteFile(File);
        }
 
        return !bOneFailed;
    }
    virtual bool        IsReadOnly(const TCHAR* Filename) = 0;
    virtual bool        MoveFile(const TCHAR* To, const TCHAR* From) = 0;
    virtual bool        SetReadOnly(const TCHAR* Filename, bool bNewReadOnlyValue) = 0;
    virtual FDateTime   GetTimeStamp(const TCHAR* Filename) = 0;
    virtual void        SetTimeStamp(const TCHAR* Filename, FDateTime DateTime) = 0;
    virtual FDateTime   GetAccessTimeStamp(const TCHAR* Filename) = 0;
    virtual FString GetFilenameOnDisk(const TCHAR* Filename) = 0;
 
    virtual ESymlinkResult IsSymlink(const TCHAR* Filename) { return ESymlinkResult::Unimplemented; }
 
    virtual bool HasMarkOfTheWeb(FStringView Filename, FString* OutSourceURL = nullptr) { return false; }
 
    virtual bool SetMarkOfTheWeb(FStringView Filename, bool bNewStatus, const FString* InSourceURL = nullptr) { return false; }
 
    enum class EOpenReadFlags : uint8
    {
        None = 0,
        AllowWrite  = 1 << 0,
        AllowDelete = 1 << 1,
        NoBuffering = 1 << 2
    };
 
    CORE_API virtual FFileOpenResult OpenRead(const TCHAR* Filename, EOpenReadFlags Flags);
 
    virtual IFileHandle*    OpenRead(const TCHAR* Filename, bool bAllowWrite = false) = 0;
 
    virtual FFileOpenResult OpenReadNoBuffering(const TCHAR* Filename, EOpenReadFlags Flags)
    {
        return OpenRead(Filename, Flags);
    }
 
    virtual IFileHandle* OpenReadNoBuffering(const TCHAR* Filename, bool bAllowWrite = false)
    {
        return OpenRead(Filename, bAllowWrite);
    }
 
    enum class EOpenWriteFlags : uint8
    {
        None        = 0,
        AllowRead   = 1 << 0,
        Append      = 1 << 1,
    };
 
    virtual IFileHandle* OpenWrite(const TCHAR* Filename, bool bAppend = false, bool bAllowRead = false) = 0;
    CORE_API virtual FFileOpenResult OpenWrite(const TCHAR* Filename, EOpenWriteFlags Flags);
 
    virtual bool        DirectoryExists(const TCHAR* Directory) = 0;
    virtual bool        CreateDirectory(const TCHAR* Directory) = 0;
    virtual bool        DeleteDirectory(const TCHAR* Directory) = 0;
 
    virtual FFileStatData GetStatData(const TCHAR* FilenameOrDirectory) = 0;
 
    class FDirectoryVisitor
    {
    public:
        FDirectoryVisitor(EDirectoryVisitorFlags InDirectoryVisitorFlags = EDirectoryVisitorFlags::None)
            : DirectoryVisitorFlags(InDirectoryVisitorFlags)
        {
        }
 
        virtual ~FDirectoryVisitor() { }
 
        virtual bool ShouldVisitLeafPathname(FStringView LeafPathname)
        {
            return true;
        }
 
        virtual bool Visit(const TCHAR* FilenameOrDirectory, bool bIsDirectory) = 0;
 
        CORE_API bool CallShouldVisitAndVisit(const TCHAR* FilenameOrDirectory, bool bIsDirectory);
 
        UE_FORCEINLINE_HINT bool IsThreadSafe() const
        {
            return (DirectoryVisitorFlags & EDirectoryVisitorFlags::ThreadSafe) != EDirectoryVisitorFlags::None;
        }
 
        EDirectoryVisitorFlags DirectoryVisitorFlags;
    };
 
    typedef TFunctionRef<bool(const TCHAR*, bool)> FDirectoryVisitorFunc;
 
    class FDirectoryStatVisitor
    {
    public:
        virtual ~FDirectoryStatVisitor() { }
 
        virtual bool ShouldVisitLeafPathname(FStringView LeafPathname)
        {
            return true;
        }
 
        virtual bool Visit(const TCHAR* FilenameOrDirectory, const FFileStatData& StatData) = 0;
 
        CORE_API bool CallShouldVisitAndVisit(const TCHAR* FilenameOrDirectory, const FFileStatData& StatData);
    };
 
    typedef TFunctionRef<bool(const TCHAR*, const FFileStatData&)> FDirectoryStatVisitorFunc;
 
    virtual bool        IterateDirectory(const TCHAR* Directory, FDirectoryVisitor& Visitor) = 0;
 
    virtual bool        IterateDirectoryStat(const TCHAR* Directory, FDirectoryStatVisitor& Visitor) = 0;
 
    CORE_API virtual bool FileJournalIsAvailable(const TCHAR* VolumeOrPath = nullptr,
        ELogVerbosity::Type* OutErrorLevel = nullptr, FString* OutError = nullptr);
 
    CORE_API virtual uint64 FileJournalGetMaximumSize(const TCHAR* VolumeOrPath = nullptr,
        ELogVerbosity::Type* OutErrorLevel = nullptr, FString* OutError = nullptr) const;
 
    CORE_API virtual EFileJournalResult FileJournalGetLatestEntry(const TCHAR* VolumeName,
        FFileJournalId& OutJournalId, FFileJournalEntryHandle& OutEntryHandle, FString* OutError = nullptr);
 
    typedef TFunctionRef<bool(const TCHAR*, const FFileJournalData&)> FDirectoryJournalVisitorFunc;
 
    CORE_API virtual bool FileJournalIterateDirectory(const TCHAR* Directory, FDirectoryJournalVisitorFunc Visitor, FString* OutError = nullptr);
 
    CORE_API virtual FFileJournalData FileJournalGetFileData(const TCHAR* FilenameOrDirectory, FString* OutError = nullptr);
 
    CORE_API virtual EFileJournalResult FileJournalReadModified(const TCHAR* VolumeName,
        const FFileJournalId& JournalIdOfStartingEntry, const FFileJournalEntryHandle& StartingJournalEntry,
        TMap<FFileJournalFileHandle, FString>& KnownDirectories, TSet<FString>& OutModifiedDirectories,
        FFileJournalEntryHandle& OutNextJournalEntry, FString* OutError = nullptr);
 
    CORE_API virtual FString FileJournalGetVolumeName(FStringView InPath);
 
 
    CORE_API virtual FFileOpenAsyncResult OpenAsyncRead(const TCHAR* Filename, EOpenReadFlags Flags);
 
    CORE_API virtual IAsyncReadFileHandle* OpenAsyncRead(const TCHAR* Filename, bool bAllowWrite = false);
 
    virtual void SetAsyncMinimumPriority(EAsyncIOPriorityAndFlags MinPriority)
    {
    }
 
    UE_DEPRECATED(5.6, "Please use OpenMappedEx instead")
    CORE_API virtual IMappedFileHandle* OpenMapped(const TCHAR* Filename);
 
    CORE_API virtual FOpenMappedResult OpenMappedEx(const TCHAR* Filename, EOpenReadFlags OpenOptions = EOpenReadFlags::None, int64 MaximumSize = 0);
 
    CORE_API virtual void GetTimeStampPair(const TCHAR* PathA, const TCHAR* PathB, FDateTime& OutTimeStampA, FDateTime& OutTimeStampB);
 
    CORE_API virtual FDateTime  GetTimeStampLocal(const TCHAR* Filename);
 
    CORE_API virtual bool IterateDirectory(const TCHAR* Directory, FDirectoryVisitorFunc Visitor);
 
    CORE_API virtual bool IterateDirectoryStat(const TCHAR* Directory, FDirectoryStatVisitorFunc Visitor);
 
    CORE_API virtual bool IterateDirectoryRecursively(const TCHAR* Directory, FDirectoryVisitor& Visitor);
 
    CORE_API virtual bool IterateDirectoryStatRecursively(const TCHAR* Directory, FDirectoryStatVisitor& Visitor);
 
    CORE_API virtual bool IterateDirectoryRecursively(const TCHAR* Directory, FDirectoryVisitorFunc Visitor);
 
    CORE_API virtual bool IterateDirectoryStatRecursively(const TCHAR* Directory, FDirectoryStatVisitorFunc Visitor);
        
    CORE_API virtual void FindFiles(TArray<FString>& FoundFiles, const TCHAR* Directory, const TCHAR* FileExtension);
 
    CORE_API virtual void FindFilesRecursively(TArray<FString>& FoundFiles, const TCHAR* Directory, const TCHAR* FileExtension);
 
    CORE_API virtual bool DeleteDirectoryRecursively(const TCHAR* Directory);
 
    CORE_API virtual bool CreateDirectoryTree(const TCHAR* Directory);
 
    CORE_API virtual bool CopyFile(const TCHAR* To, const TCHAR* From, EPlatformFileRead ReadFlags = EPlatformFileRead::None, EPlatformFileWrite WriteFlags = EPlatformFileWrite::None);
 
    CORE_API virtual bool CopyDirectoryTree(const TCHAR* DestinationDirectory, const TCHAR* Source, bool bOverwriteAllExisting);
 
    CORE_API virtual FString ConvertToAbsolutePathForExternalAppForRead( const TCHAR* Filename );
 
    CORE_API virtual FString ConvertToAbsolutePathForExternalAppForWrite( const TCHAR* Filename );
 
    class IFileServerMessageHandler
    {
    public:
        virtual ~IFileServerMessageHandler() { }
 
        virtual void FillPayload(FArchive& Payload) = 0;
 
        virtual void ProcessResponse(FArchive& Response) = 0;
    };
 
    virtual bool SendMessageToServer(const TCHAR* Message, IFileServerMessageHandler* Handler)
    {
        // by default, IPlatformFile's can't talk to a server
        return false;
    }
    
    virtual bool DoesCreatePublicFiles()
    {
        return false;
    }
    
    virtual void SetCreatePublicFiles(bool bCreatePublicFiles)
    {
    }
 
    virtual int64 GetAllowedBytesToWriteThrottledStorage(const TCHAR* DestinationPath = nullptr)
    {
        return INT64_MAX;
    }
};
 
class IWrappedFileHandle : public IFileHandle
{
public:
    virtual void SetLowerLevel(IFileHandle* LowerLevelHandle) = 0;
};
 
class IPhysicalPlatformFile : public IPlatformFile
{
public:
    //~ Begin IPlatformFile Interface
    virtual bool ShouldBeUsed(IPlatformFile* Inner, const TCHAR* CmdLine) const override
    {
        return true;
    }
    CORE_API virtual bool Initialize(IPlatformFile* Inner, const TCHAR* CmdLine) override;
    virtual IPlatformFile* GetLowerLevel() override
    {
        return nullptr;
    }
    virtual void SetLowerLevel(IPlatformFile* NewLowerLevel) override
    {
        check(false); // can't override wrapped platform file for physical platform file
    }
    virtual const TCHAR* GetName() const override
    {
        return IPlatformFile::GetPhysicalTypeName();
    }
    //~ End IPlatformFile Interface
};
 
/* Interface class for FPakFile to allow usage from modules that cannot have a compile dependency on FPakFile. See FCoreDelegates */
class IPakFile
{
public:
    virtual const FString& PakGetPakFilename() const = 0;
    virtual bool PakContains(const FString& Filename) const = 0;
    virtual int32 PakGetPakchunkIndex() const = 0;
    virtual void PakVisitPrunedFilenames(IPlatformFile::FDirectoryVisitor& Visitor) const = 0;
    virtual const FString& PakGetMountPoint() const = 0;
 
    virtual int32 GetNumFiles() const = 0;
};
 
/* Pak Mount Options allow usage from modules that cannot have a compile dependency on FPakFile. See FCoreDelegates. */
struct FPakMountOptions
{
    enum class EMountFlags : uint32
    {
        None                    = 0,
        WithSoftReferences      = 1 << 0,
        ReportDecryptionFailure = 1 << 1,
        SkipContainerFile       = 1 << 2,
    };
 
    EMountFlags MountFlags = EMountFlags::None;
};
ENUM_CLASS_FLAGS(FPakMountOptions::EMountFlags);
 
inline uint32 GetTypeHash(const FFileJournalFileHandle& A)
{
    constexpr uint32 Mult = 103;
    uint32 Hash = 0;
    const uint8* EndA = reinterpret_cast<const uint8*>(&A) + sizeof(FFileJournalFileHandle);
    for (const uint8* PA = reinterpret_cast<const uint8*>(&A); PA < EndA; ++PA)
    {
        Hash = Hash * Mult + *PA;
    }
    return Hash;
}
 
inline bool FFileJournalFileHandle::operator==(const FFileJournalFileHandle& Other) const
{
    return 0 == FPlatformMemory::Memcmp(this, &Other, sizeof(FFileJournalFileHandle));
}
 
inline bool FFileJournalFileHandle::operator!=(const FFileJournalFileHandle& Other) const
{
    return 0 != FPlatformMemory::Memcmp(this, &Other, sizeof(FFileJournalFileHandle));
}
 
inline FFileJournalData::FFileJournalData()
    : bIsValid(false)
    , bIsDirectory(false)
    , bIsReparsePoint(false)
    , bIsReadOnly(false)
{
}
 
ENUM_CLASS_FLAGS(IPlatformFile::EOpenReadFlags);
ENUM_CLASS_FLAGS(IPlatformFile::EOpenWriteFlags);