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

Public Types
using	Event = plEvent<const EventData&, plMutex>

Public Member Functions
plResult	Open (plStringView sFile, plFileOpenMode::Enum openMode, plFileShareMode::Enum fileShareMode=plFileShareMode::Default)
	Opens a file for reading or writing. Returns PL_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.

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

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

plUInt64	ReadAll (plDynamicArray< plUInt8 > &out_fileContent)
	Reads the entire file content into the given array.

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

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

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

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

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

static const plString	MakePathAbsoluteWithCWD (plStringView sPath)
	If szPath is a relative path, this function prepends GetCurrentWorkingDirectory().

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

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

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

static plResult	DeleteFile (plStringView sFile)
	Deletes the given file. Returns PL_SUCCESS, if the file was deleted or did not exist in the first place. Returns PL_FAILURE.

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

static plResult	CopyFile (plStringView sSource, plStringView sDestination)
	Copies the source file into the destination file.

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

static plResult	GetFileCasing (plStringView sFileOrFolder, plStringBuilder &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 (plDynamicArray< plFileStats > &out_itemList, plStringView sFolder, plBitflags< plFileSystemIteratorFlags > flags=plFileSystemIteratorFlags::Default)
	Returns the plFileStats for all files and folders in the given folder.

static plResult	CopyFolder (plStringView sSourceFolder, plStringView sDestinationFolder, plDynamicArray< plString > *out_pFilesCopied=nullptr)
	Copies szSourceFolder to szDestinationFolder. Overwrites existing files.

static plResult	DeleteFolder (plStringView sFolder)
	Deletes all files recursively in szFolder.

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

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

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

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

static plString	GetUserDocumentsFolder (plStringView 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 plOSFile 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 plResult plOSFile::CopyFolder	(	plStringView	sSourceFolder,
		plStringView	sDestinationFolder,
		plDynamicArray< plString > *	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 plOSFile::FindFreeFilename	(	plStringBuilder &	inout_sPath,
		plStringView	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()

static const plString plOSFile::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: pl 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()

static plString plOSFile::GetTempDataFolder ( plStringView 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()

static plString plOSFile::GetUserDataFolder ( plStringView 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()

static plString plOSFile::GetUserDocumentsFolder ( plStringView 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 plString plOSFile::MakePathAbsoluteWithCWD ( plStringView 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:

Code/Engine/Foundation/IO/OSFile.h
Code/Engine/Foundation/IO/Implementation/OSFile.cpp
Code/Engine/Foundation/Platform/Posix/OSFile_Posix.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ CopyFolder()

◆ FindFreeFilename()

◆ GetCurrentWorkingDirectory()

◆ GetTempDataFolder()

◆ GetUserDataFolder()

◆ GetUserDocumentsFolder()

◆ MakePathAbsoluteWithCWD()