This is an abstraction for the most important file operations. More...

#include <OSFile.h>

Classes
struct	EventData
	The data that is sent through the event interface. More...

struct	EventType
	Describes the types of events that ezOSFile sends. More...

Public Types
using	Event = ezEvent< const EventData &, ezMutex >

Public Member Functions
ezResult	Open (ezStringView sFile, ezFileOpenMode::Enum openMode, ezFileShareMode::Enum fileShareMode=ezFileShareMode::Default)
	Opens a file for reading or writing. Returns EZ_SUCCESS if the file could be opened successfully.

bool	IsOpen () const
	Returns true if a file is currently open.

void	Close ()
	Closes the file, if it is currently opened.

ezResult	Write (const void *pBuffer, ezUInt64 uiBytes)
	Writes the given number of bytes from the buffer into the file. Returns true if all data was successfully written.

ezUInt64	Read (void *pBuffer, ezUInt64 uiBytes)
	Reads up to the given number of bytes from the file. Returns the actual number of bytes that was read.

ezUInt64	ReadAll (ezDynamicArray< ezUInt8 > &out_fileContent)
	Reads the entire file content into the given array.

ezStringView	GetOpenFileName () const
	Returns the name of the file that is currently opened. Returns an empty string, if no file is open.

ezUInt64	GetFilePosition () const
	Returns the position in the file at which read/write operations will occur.

void	SetFilePosition (ezInt64 iDistance, ezFileSeekMode::Enum pos) const
	Sets the position where in the file to read/write next.

ezUInt64	GetFileSize () const
	Returns the current total size of the file.

const ezOSFileData &	GetFileData () const
	This will return the platform specific file data (handles etc.), if you really want to be able to wreak havoc.

Static Public Member Functions
static const ezString	GetCurrentWorkingDirectory ()
	Returns the processes current working directory (CWD). More...

static const ezString	MakePathAbsoluteWithCWD (ezStringView sPath)
	If szPath is a relative path, this function prepends GetCurrentWorkingDirectory(). More...

static bool	ExistsFile (ezStringView sFile)
	Checks whether the given file exists.

static bool	ExistsDirectory (ezStringView sDirectory)
	Checks whether the given directory exists.

static void	FindFreeFilename (ezStringBuilder &inout_sPath, ezStringView sSuffix="-")
	If the given file already exists, determines a file path that doesn't exist yet. More...

static ezResult	DeleteFile (ezStringView sFile)
	Deletes the given file. Returns EZ_SUCCESS, if the file was deleted or did not exist in the first place. Returns EZ_FAILURE.

static ezResult	CreateDirectoryStructure (ezStringView sDirectory)
	Creates the given directory structure (meaning all directories in the path, that do not exist). Returns false, if any directory could not be created.

static ezResult	MoveFileOrDirectory (ezStringView sFrom, ezStringView sTo)
	Renames / Moves an existing directory. The file / directory at szFrom must exist. The parent directory of szTo must exist. Returns EZ_FAILURE if the move failed.

static ezResult	CopyFile (ezStringView sSource, ezStringView sDestination)
	Copies the source file into the destination file.

static ezResult	GetFileStats (ezStringView sFileOrFolder, ezFileStats &out_stats)
	Gets the stats about the given file or folder. Returns false, if the stats could not be determined.

static ezResult	GetFileCasing (ezStringView sFileOrFolder, ezStringBuilder &out_sCorrectSpelling)
	Useful on systems that are not strict about the casing of file names. Determines the correct name of a file.

static void	GatherAllItemsInFolder (ezDynamicArray< ezFileStats > &out_itemList, ezStringView sFolder, ezBitflags< ezFileSystemIteratorFlags > flags=ezFileSystemIteratorFlags::Default)
	Returns the ezFileStats for all files and folders in the given folder.

static ezResult	CopyFolder (ezStringView sSourceFolder, ezStringView sDestinationFolder, ezDynamicArray< ezString > *out_pFilesCopied=nullptr)
	Copies szSourceFolder to szDestinationFolder. Overwrites existing files. More...

static ezResult	DeleteFolder (ezStringView sFolder)
	Deletes all files recursively in szFolder.

static ezStringView	GetApplicationPath ()
	Returns the full path to the application binary.

static ezStringView	GetApplicationDirectory ()
	Returns the path to the directory in which the application binary is located.

static ezString	GetUserDataFolder (ezStringView sSubFolder={})
	Returns the folder into which user data may be safely written. Append a sub-folder for your application. More...

static ezString	GetTempDataFolder (ezStringView sSubFolder={})
	Returns the folder into which temp data may be written. More...

static ezString	GetUserDocumentsFolder (ezStringView sSubFolder={})
	Returns the folder into which the user may want to store documents. Append a sub-folder for your application. More...

static void	AddEventHandler (Event::Handler handler)
	Allows to register a function as an event receiver. All receivers will be notified in the order that they registered.

static void	RemoveEventHandler (Event::Handler handler)
	Unregisters a previously registered receiver. It is an error to unregister a receiver that was not registered.

Detailed Description

This is an abstraction for the most important file operations.

Instances of ezOSFile can be used for reading and writing files. All paths must be absolute paths, relative paths and current working directories are not supported, since that cannot be guaranteed to work equally on all platforms under all circumstances. A few static functions allow to query the most important data about files, to delete files and create directories.

Member Function Documentation

◆ CopyFolder()

static ezResult ezOSFile::CopyFolder	(	ezStringView	sSourceFolder,
		ezStringView	sDestinationFolder,
		ezDynamicArray< ezString > *	out_pFilesCopied = `nullptr`
	)

static

Copies szSourceFolder to szDestinationFolder. Overwrites existing files.

If out_FilesCopied is provided, the destination path of every successfully copied file is appended to it.

◆ FindFreeFilename()

void ezOSFile::FindFreeFilename	(	ezStringBuilder &	inout_sPath,
		ezStringView	sSuffix = `"-"`
	)

static

If the given file already exists, determines a file path that doesn't exist yet.

If the original file already exists, sSuffix is appended and then a number starting at 1. Loops until it finds a filename that is not yet taken.

◆ GetCurrentWorkingDirectory()

const ezString ezOSFile::GetCurrentWorkingDirectory ( )

static

Returns the processes current working directory (CWD).

The value typically depends on the directory from which the application was launched. Since this is a process wide global variable, other code can modify it at any time.

Note: ez does not use the CWD for any file resolution. This function is provided to enable tools to work with relative paths from the command-line, but every application has to implement such behavior individually.

◆ GetTempDataFolder()

ezString ezOSFile::GetTempDataFolder ( ezStringView sSubFolder = {} )

static

Returns the folder into which temp data may be written.

On Windows this is the 'localappdata%/Temp' directory. On Posix systems this is the '~/.cache' directory.

If szSubFolder is specified, it will be appended to the result.

◆ GetUserDataFolder()

ezString ezOSFile::GetUserDataFolder ( ezStringView sSubFolder = {} )

static

Returns the folder into which user data may be safely written. Append a sub-folder for your application.

On Windows this is the 'appdata' directory. On Posix systems this is the '~' (home) directory.

If szSubFolder is specified, it will be appended to the result.

◆ GetUserDocumentsFolder()

ezString ezOSFile::GetUserDocumentsFolder ( ezStringView sSubFolder = {} )

static

Returns the folder into which the user may want to store documents. Append a sub-folder for your application.

On Windows this is the 'Documents' directory. On Posix systems this is the '~' (home) directory.

If szSubFolder is specified, it will be appended to the result.

◆ MakePathAbsoluteWithCWD()

const ezString ezOSFile::MakePathAbsoluteWithCWD ( ezStringView sPath )

static

If szPath is a relative path, this function prepends GetCurrentWorkingDirectory().

In either case, MakeCleanPath() is used before the string is returned.

The documentation for this class was generated from the following files:

/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/IO/OSFile.h
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/IO/Implementation/OSFile.cpp
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Platform/Posix/OSFile_Posix.inl

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ CopyFolder()

◆ FindFreeFilename()

◆ GetCurrentWorkingDirectory()

◆ GetTempDataFolder()

◆ GetUserDataFolder()

◆ GetUserDocumentsFolder()

◆ MakePathAbsoluteWithCWD()