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 xiiOSFile sends. More...

Public Types
using	Event = xiiEvent<const EventData&, xiiMutex>

Public Member Functions
xiiResult	Open (xiiStringView sFile, xiiFileOpenMode::Enum openMode, xiiFileShareMode::Enum fileShareMode=xiiFileShareMode::Default)
	Opens a file for reading or writing. Returns XII_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.

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

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

xiiUInt64	ReadAll (xiiDynamicArray< xiiUInt8 > &out_fileContent)
	Reads the entire file content into the given array.

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

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

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

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

const xiiOSFileData &	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 xiiString	GetCurrentWorkingDirectory ()
	Returns the processes current working directory (CWD).

static const xiiString	MakePathAbsoluteWithCWD (xiiStringView sPath)
	If sPath is a relative path, this function prepends GetCurrentWorkingDirectory().

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

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

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

static xiiResult	DeleteFile (xiiStringView sFile)
	Deletes the given file. Returns XII_SUCCESS, if the file was deleted or did not exist in the first place. Returns XII_FAILURE.

static xiiResult	CreateDirectoryStructure (xiiStringView 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 xiiResult	MoveFileOrDirectory (xiiStringView sFrom, xiiStringView sTo)
	Renames / Moves an existing directory. The file / directory at sFrom must exist. The parent directory of sTo must exist. Returns XII_FAILURE if the move failed.

static xiiResult	CopyFile (xiiStringView sSource, xiiStringView sDestination)
	Copies the source file into the destination file.

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

static xiiResult	GetFileCasing (xiiStringView sFileOrFolder, xiiStringBuilder &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 (xiiDynamicArray< xiiFileStats > &out_itemList, xiiStringView sFolder, xiiBitflags< xiiFileSystemIteratorFlags > flags=xiiFileSystemIteratorFlags::Default)
	Returns the xiiFileStats for all files and folders in the given folder.

static xiiResult	CopyFolder (xiiStringView sSourceFolder, xiiStringView sDestinationFolder, xiiDynamicArray< xiiString > *out_pFilesCopied=nullptr)
	Copies sSourceFolder to sDestinationFolder. Overwrites existing files.

static xiiResult	DeleteFolder (xiiStringView sFolder)
	Deletes all files recursively in sFolder.

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

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

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

static xiiString	GetTempDataFolder (xiiStringView sSubFolder={})
	Returns the folder into which temp data may be written.

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

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 xiiOSFile 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 xiiResult xiiOSFile::CopyFolder	(	xiiStringView	sSourceFolder,
		xiiStringView	sDestinationFolder,
		xiiDynamicArray< xiiString > *	out_pFilesCopied = nullptr )

static

Copies sSourceFolder to sDestinationFolder. Overwrites existing files.

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

◆ FindFreeFilename()

void xiiOSFile::FindFreeFilename	(	xiiStringBuilder &	inout_sPath,
		xiiStringView	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 xiiString xiiOSFile::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: XII 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()

xiiString xiiOSFile::GetTempDataFolder ( xiiStringView 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 sSubFolder is specified, it will be appended to the result.

◆ GetUserDataFolder()

xiiString xiiOSFile::GetUserDataFolder ( xiiStringView 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 sSubFolder is specified, it will be appended to the result.

◆ GetUserDocumentsFolder()

xiiString xiiOSFile::GetUserDocumentsFolder ( xiiStringView 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 sSubFolder is specified, it will be appended to the result.

◆ MakePathAbsoluteWithCWD()

const xiiString xiiOSFile::MakePathAbsoluteWithCWD ( xiiStringView sPath )

static

If sPath 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/XII/XII/Source/Engine/Foundation/IO/OSFile.h
/home/runner/work/XII/XII/Source/Engine/Foundation/IO/Implementation/OSFile.cpp
/home/runner/work/XII/XII/Source/Engine/Foundation/Platform/Implementation/Posix/OSFile_posix.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Platform/Implementation/Windows/OSFile_win.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ CopyFolder()

◆ FindFreeFilename()

◆ GetCurrentWorkingDirectory()

◆ GetTempDataFolder()

◆ GetUserDataFolder()

◆ GetUserDocumentsFolder()

◆ MakePathAbsoluteWithCWD()