it presents a real or virtual file in ParaEngine. More...

#include <ParaFile.h>

Public Types
enum	PARAENGINE_DIRECTORY { APP_ROOT_DIR = 0, APP_SCRIPT_DIR = 1, APP_ARCHIVE_DIR = 2, APP_MODEL_DIR = 3, APP_SHADER_DIR = 4, APP_DATABASE_DIR = 5, APP_TEMP_DIR = 6, APP_USER_DIR = 7, APP_BACKUP_DIR = 8, APP_SCREENSHOT_DIR = 9, APP_PLUGIN_DIR = 10, APP_CONFIG_DIR = 11, APP_CHARACTER_DIR = 12, APP_SH_DESKTOP_DIR = 13, APP_SH_DESKTOP_FOLDER_DIR = 14, APP_SH_MYDOC_DIR = 15, APP_SH_FAV_DIR = 16, APP_SH_MUSIC_DIR = 17, APP_SH_PICTURE_DIR = 18, APP_SH_VIDEO_DIR = 19, APP_DEV_DIR = 20, APP_EXECUTABLE_DIR = 21, APP_LAST_DIR }

Public Member Functions
PE_CORE_DECL	CParaFile ()
	create an undefined file. More...

PE_CORE_DECL	CParaFile (char *buf, int nBufferSize, bool bCopyBuffer=false)
	create a memory file from a given buffer. More...

PE_CORE_DECL	CParaFile (const char *filename)
	Open a file for immediate reading. More...

PE_CORE_DECL	CParaFile (const char filename, const char relativePath)
	Open a file for immediate reading. More...

PE_CORE_DECL bool	OpenFile (const char filename, bool bReadyOnly=true, const char relativePath=NULL, bool bUseCompressed=false, uint32 dwWhereToOpen=FILE_ON_DISK\|FILE_ON_ZIP_ARCHIVE\|FILE_ON_SEARCH_PATH)
	Open a file for immediate reading.If the file name begins with ':', it is treated as a win32 resource. More...

PE_CORE_DECL bool	OpenFile (CArchive pArchive, const char filename, bool bUseCompressed=false)
	mostly used for reading from an archive file handle

PE_CORE_DECL int	OpenAssetFile (const char filename, bool bDownloadIfNotUpToDate=true, const char relativePath=NULL)
	This is rather similar to OpenFile() method, except that it will first look in the AssetManifest to see if the file exit. More...

PE_CORE_DECL bool	Decompress ()
	decompress the file if it is currently compressed. More...

PE_CORE_DECL bool	IsCompressed ()
	get whether the buffer and size is a zip compressed. More...

PE_CORE_DECL void	SetIsCompressed (bool bCompressed)
	set whether the buffer and size is a zip compressed. More...

PE_CORE_DECL bool	CreateNewFile (const char *filename, bool bAutoMakeFilePath=true)
	create a new file for writing More...

PE_CORE_DECL void	GiveupBufferOwnership ()
	no longer release the file buffer when this file object is destroyed.

PE_CORE_DECL void	TakeBufferOwnership ()

PE_CORE_DECL bool	ExtractFileToDisk (const string &filenameDest, bool bReplace)
	extract this para file to disk More...

PE_CORE_DECL int	write (const void *src, int bytes)
	Write byte stream to file the file must be opened with write access.

PE_CORE_DECL int	WriteString (const string &sStr)
	write string to file. More...

PE_CORE_DECL int	WriteString (const char *sStr, int nLen=0)
	write string to file. More...

PE_CORE_DECL int	WriteFormated (const char *,...)
	the string length can not exceed 1024

int	WriteDWORD (DWORD data)

int	WriteWORD (WORD data)

void	SetFilePointer (int lDistanceToMove, int dwMoveMethod)
	The SetFilePointer function moves the file pointer of an open file. More...

bool	SetEndOfFile ()
	The SetEndOfFile function moves the end-of-file (EOF) position for the specified file to the current position of the file pointer.This function can be used to truncate or extend a file. More...

PE_CORE_DECL size_t	read (void *dest, size_t bytes)
	read byte stream from file at its current location. More...

DWORD	ReadDWORD ()
	read DWORD

WORD	ReadWORD ()
	read WORD

BYTE	ReadByte ()
	read WORD

int	WriteByte (BYTE data)

DWORD	ReadDWORD_LE ()
	read DWORD: little endian byte order

WORD	ReadWORD_LE ()
	read WORD: little endian byte order

uint32_t	ReadEncodedUInt ()
	read compressed unsigned int (16, 32, 64, etc) More...

int	WriteEncodedUInt (uint32_t value)
	return the number bytes written

PE_CORE_DECL int	GetNextLine (char *buf, int sizeBuf)
	return the next line of text string from the current file position. More...

PE_CORE_DECL int	SkipComment ()
	advancing file pointer, skipping all comment lines, blank lines, and blank spaces. More...

PE_CORE_DECL int	SkipEqualMark ()
	advancing file pointer, skipping all occurrences of ' ' and '=' mark More...

PE_CORE_DECL int	SkipString (const char *sName)
	advancing file pointer, skipping the sName. More...

PE_CORE_DECL int	SkipCurrentLine ()
	skip the current line. More...

PE_CORE_DECL bool	GetNextAttribute (const char *sName, string &output)
	in order to call this method. More...

PE_CORE_DECL bool	GetNextAttribute (const char *sName, float &output)

PE_CORE_DECL bool	GetNextAttribute (const char *sName, double &output)

PE_CORE_DECL bool	GetNextAttribute (const char *sName, int &output)

PE_CORE_DECL bool	GetNextAttribute (const char *sName, bool &output)

PE_CORE_DECL bool	GetNextAttribute (const char *sName)
	read a single word from the next line. More...

template<class TYPE_ARG1 >
bool	GetNextFormatted (const char *sFormat, TYPE_ARG1 a1)
	this is similar to GetNextAttribute(). More...

template<class TYPE_ARG1 , class TYPE_ARG2 >
bool	GetNextFormatted (const char *sFormat, TYPE_ARG1 a1, TYPE_ARG2 a2)

template<class TYPE_ARG1 , class TYPE_ARG2 , class TYPE_ARG3 >
bool	GetNextFormatted (const char *sFormat, TYPE_ARG1 a1, TYPE_ARG2 a2, TYPE_ARG3 a3)

PE_CORE_DECL const string &	GetFileName ()
	get the file name

PE_CORE_DECL size_t	getSize ()

PE_CORE_DECL size_t	getPos ()

PE_CORE_DECL char *	getBuffer ()

PE_CORE_DECL char *	getPointer ()

PE_CORE_DECL bool	isEof ()

PE_CORE_DECL void	seek (int offset)

PE_CORE_DECL void	seekRelative (int offset)

PE_CORE_DECL void	close ()

PE_CORE_DECL void	synchBits ()
	Reset the bit buffer. More...

PE_CORE_DECL unsigned int	readUBits (int numBits)
	Read an unsigned value from the given number of bits.

PE_CORE_DECL int	readSBits (int numBits)
	Read a signed value from the given number of bits.

void *	GetHandlePtr ()
	get handle ptr

Static Public Member Functions
static PE_CORE_DECL bool	CreateDirectory (const char *filename)
	same as MakeDirectoryFromFilePath. More...

static PE_CORE_DECL bool	MakeDirectoryFromFilePath (const char *filename)
	make directory More...

static PE_CORE_DECL void	ToCanonicalFilePath (string &output, const string &input, bool bBackSlash=false)
	convert a file name to canonical file path More...

static PE_CORE_DECL void	ToCanonicalFilePath (char output, const char input, bool bBackSlash=false)
	save as above More...

static PE_CORE_DECL bool	DoesFileExist (const char *filename, bool bSearchZipFiles=false, bool bUseSearchPath=false)
	Check whether a given file exists on disk. More...

static int32	DoesFileExist2 (const char filename, uint32 dwWhereToSearch=FILE_ON_DISK, std::string pDiskFilePath=NULL)
	check file exist based on file location. More...

static bool	IsAbsolutePath (const std::string &path)
	Checks whether the path is an absolute path. More...

static PE_CORE_DECL int	DeleteTempFile (const string &sFilePattern)
	delete temporary file. More...

static PE_CORE_DECL int	DeleteFile (const string &sFilePattern, bool bSecureFolderOnly=true)
	delete a given file. More...

static PE_CORE_DECL bool	MoveFile (const char src, const char dest)
	The MoveFile function will move (rename) either a file or a directory (including its children) either in the same directory or across directories. More...

static PE_CORE_DECL bool	BackupFile (const char *filename)
	backup a specified file, if the file exists. More...

static PE_CORE_DECL unsigned long	CRC32 (const char *filename)
	Get the CRC 32 code of a given file. More...

static PE_CORE_DECL bool	CopyFile (const char src, const char dest, bool bOverride)
	The CopyFile function copies an existing file to a new file. More...

static PE_CORE_DECL string	GetParentDirectoryFromPath (const string &sfilename, int nParentCounts=0)
	trim the sFile by nParentCounts number of parent directories. More...

static PE_CORE_DECL string	AutoFindParaEngineRootPath (const string &sFile)
	This will find the root path from a given directory path using the following rule: find a file called "ParaEngine.sig" in the parent directories of sFile, from near to far. More...

static PE_CORE_DECL string	ChangeFileExtension (const string &sFile, const string &sExt)
	change the file extension. More...

static PE_CORE_DECL string	GetFileExtension (const string &sFile)
	get the file extension. More...

static PE_CORE_DECL string	GetRelativePath (const string &sAbsolutePath, const string &sRootPath)
	Get the relative file path by stripping the root path from the beginning. More...

static PE_CORE_DECL string	GetAbsolutePath (const string &sRelativePath, const string &sRootPath)
	Get the absolute file path by appending the root path before the relative path. More...

static PE_CORE_DECL string	GetFileName (const string &sFilePath)
	get only the file name from the file path. More...

static PE_CORE_DECL bool	IsFileName (const string &sFilePath)
	return whether the given path is only a file name which contains no directory information. More...

static PE_CORE_DECL int	GetFileSize (const char *sFilePath)
	get file size of a disk file in bytes. More...

static PE_CORE_DECL const std::string &	GetWritablePath ()
	in win32, this is the root directory, Gets the writable path. More...

static PE_CORE_DECL void	SetWritablePath (const std::string &writable_path)
	Note: NOT thread safe, only set at startup when there is just one thread running. More...

static PE_CORE_DECL bool	IsWritablePath (const std::string &filepath, bool bLogWarning=true)
	whether the given file is a writable path. More...

static PE_CORE_DECL const string &	GetCurDirectory (DWORD dwDirectoryType)
	get the current directory of the application. More...

static PE_CORE_DECL void	SetDevDirectory (const string &sFilePath)
	set developer path. More...

static PE_CORE_DECL const string &	GetDevDirectory ()

static void	SetDiskFilePriority (int nPriority)
	set the disk file priority. More...

static int	GetDiskFilePriority ()
	set the disk file priority. More...

static PE_CORE_DECL bool	GetFileInfo (const char *filename, CParaFileInfo &fileInfo, uint32 dwWhereToOpen=FILE_ON_DISK\|FILE_ON_ZIP_ARCHIVE\|FILE_ON_SEARCH_PATH)
	get file attributes like file type, where the file is found, absolute path, modification time, size, etc. More...

static PE_CORE_DECL bool	DoesAssetFileExist (const char *filename)
	check to see whether we have a up to date version of an asset file. More...

static PE_CORE_DECL bool	DoesAssetFileExist2 (const char *filename, bool bSearchZipFile=false)

static PE_CORE_DECL void	SetExtractFileProperty (bool bExtractFile)
	set whether to extract file to disk. More...

static PE_CORE_DECL bool	GetExtractFileProperty ()
	check whether to extract file. More...

static PE_CORE_DECL bool	UnzipMemToFile (const char buffer, int nSize, const char destFilename, bool bAutoMakeDirectory)
	upzip the first file in a memory zip file to a given destFileName. More...

Detailed Description

it presents a real or virtual file in ParaEngine.

The most simple use is CParaFile file("a.x"); char* pBuf = file.GetBuffer(); It is very important to release the file object or call Close() method to read the memory allocated during file loading. Currently it is automatically called in the destructor

Constructor & Destructor Documentation

§ CParaFile() [1/4]

CParaFile::CParaFile ( )

create an undefined file.

This is usually for creating a new file. Call CreateNewFile() after this.

§ CParaFile() [2/4]

CParaFile::CParaFile	(	char *	buf,
		int	nBufferSize,
		bool	bCopyBuffer = `false`
	)

create a memory file from a given buffer.

The memory file is usually read only.

Parameters

buf	: buffer input
nBufferSize	: sizes of input buffer in bytes.
bCopyBuffer	if false, this file object will not release the buffer when the file is closed. so the caller has to do it after CParaFile is released. if true, it will immediately make an internal copy of the buffer and release the newly created buffer when file closes. one can later on use TakeBufferOwnership() when this is false.

§ CParaFile() [3/4]

CParaFile::CParaFile ( const char * filename )

Open a file for immediate reading.

this is an alternative way to use CParaFile. filenames are not case sensitive. Release the object will release the file.

§ CParaFile() [4/4]

CParaFile::CParaFile	(	const char *	filename,
		const char *	relativePath
	)

Open a file for immediate reading.

this is an alternative way to use CParaFile. filenames are not case sensitive. Release the object will release the file.

Parameters

relativePath a relative path file name, such as "terrain/data/", or "terrain/data/abc.txt" in the latter case, "abc.txt" is ignored automatically. please note that it will first search the file as "filename", and if failed, it will search for "relativePath..filename"

Member Function Documentation

§ AutoFindParaEngineRootPath()

string CParaFile::AutoFindParaEngineRootPath ( const string & sFile )

static

This will find the root path from a given directory path using the following rule: find a file called "ParaEngine.sig" in the parent directories of sFile, from near to far.

e.g. if sFile is "c:/a/b/c/xxx.x", then it will search for "c:/a/b/c/","c:/a/b/","c:/a/" and "c:/". the function will return the first parent directory that contains the file, otherwise "" is returned.

§ BackupFile()

bool CParaFile::BackupFile ( const char * filename )

static

backup a specified file, if the file exists.

A new file with an extension ".bak" appended to the end of the original file will be created, whose content is identical to the original file.

Parameters

filename file name to back up

Returns: : return true if the file is backed up. return false, if the file does not exist or some error occurs during backup.

§ ChangeFileExtension()

string CParaFile::ChangeFileExtension	(	const string &	sFile,
		const string &	sExt
	)

static

change the file extension.

Parameters

sFile	the file whose extension to change.
sExt	the file extension to change to. such as "dds","x"

Returns: : return the file with the changed extension. the input file does not contain a valid file extension, the returned string will be identical to the input file.

§ CopyFile()

bool CParaFile::CopyFile	(	const char *	src,
		const char *	dest,
		bool	bOverride
	)

static

The CopyFile function copies an existing file to a new file.

Parameters

src	specifies the name of an existing file
dest	specifies the name of the new file
bOverride	[in] If this parameter is false and the new file specified by src already exists, the function fails. If this parameter is true and the new file already exists, the function overwrites the existing file and succeeds.

Returns: true if succeeds

§ CRC32()

unsigned long CParaFile::CRC32 ( const char * filename )

static

Get the CRC 32 code of a given file.

Returns: : return 0 if not succeed, otherwise the CRC32 code is returned.

§ CreateDirectory()

bool CParaFile::CreateDirectory ( const char * filename )

static

same as MakeDirectoryFromFilePath.

except that file name need not to be a Canonical File Path

§ CreateNewFile()

bool CParaFile::CreateNewFile	(	const char *	filename,
		bool	bAutoMakeFilePath = `true`
	)

create a new file for writing

Parameters

bAutoMakeFilePath if true, the file path will be created, if not exists

§ Decompress()

bool CParaFile::Decompress ( )

decompress the file if it is currently compressed.

This function is usually used by the content streaming architecture, where the IO thread load compressed data to memory and one of the worker thread decompress it.

§ DeleteFile()

int CParaFile::DeleteFile	(	const string &	sFilePattern,
		bool	bSecureFolderOnly = `true`
	)

static

delete a given file.

It will reject any system files outside the application directory. after all, this function is of high security level.

Parameters

sFilePattern	such as "*.dds", "temp.txt", etc
bSecureFolderOnly	if true, we only allow user to delete allowed folders.

Returns: : the number of files deleted.

§ DeleteTempFile()

int CParaFile::DeleteTempFile ( const string & sFilePattern )

static

delete temporary file.

temporary files are file in the ./temp/ directory of the ParaEngine's root dir. this function is general used to delete temporary texture file generated during the game.

Parameters

sFilePattern such as "*.dds", "temp.txt", etc

Returns: : the number of file deleted.

§ DoesAssetFileExist()

bool CParaFile::DoesAssetFileExist ( const char * filename )

static

check to see whether we have a up to date version of an asset file.

if the asset file does not appear in asset manifest list, it will return the result of DoesFileExist() instead.

§ DoesFileExist()

bool CParaFile::DoesFileExist	(	const char *	filename,
		bool	bSearchZipFiles = `false`,
		bool	bUseSearchPath = `false`
	)

static

Check whether a given file exists on disk.

Parameters

filename	file name to check
bSearchZipFiles	if false, not disk file is searched. If true, both the disk file and zip file will be searched.
bUseSearchPath	true to use search path. please note this function will NOT be thread thead if this is true. It must be in the same thread as the AddSearchPath.

§ DoesFileExist2()

int32 CParaFile::DoesFileExist2	(	const char *	filename,
		uint32	dwWhereToSearch = `FILE_ON_DISK`,
		std::string *	pDiskFilePath = `NULL`
	)

static

check file exist based on file location.

similar to DoesFileExist, but gives more info on where the file is first found.

Parameters

dwWhereToSearch	bitwise field of FileLocation, default to FILE_ON_DISK
pDiskFilePath	if not NULL, it will contain the actual disk file path. In case it is on search path, it is different from filename.

Returns: int32: enum of FileLocation. return 0 if not found.

§ ExtractFileToDisk()

bool CParaFile::ExtractFileToDisk	(	const string &	filenameDest,
		bool	bReplace
	)

extract this para file to disk

Parameters

filenameDest	destination file name.
bReplace	replace file if the file already exists.

§ GetAbsolutePath()

string CParaFile::GetAbsolutePath	(	const string &	sRelativePath,
		const string &	sRootPath
	)

static

Get the absolute file path by appending the root path before the relative path.

please note that all paths should uses slash "/", instead of backslash "\", in the path name. letter case is ignored

Parameters

sRelativePath	the relative path. it also begin with "../../", "./", etc.
sRootPath	the parent root path, it may end with "/".

Returns: : the relative path is returned. If the absolute path does not math the root path, the absolute path is returned unchanged. e.g. "c:/lxzsrc/a/b.x" = GetAbsolutePath("a/b.x", "c:/lxzsrc/");

§ GetCurDirectory()

const string & CParaFile::GetCurDirectory ( DWORD dwDirectoryType )

static

get the current directory of the application.

it allows querying a number of standard directories. please note that all directory are returned as absolute path with slash "/" between two level of directories. and that it always ends with "/". e.g. "c:/lxzsrc/paraengineSDK/" or "c:/lxzsrc/paraengineSDK/script/"

Parameters

dwDirectoryType it can be one of the PARAENGINE_DIRECTORY enumeration type

Returns: : the directory is returned.

§ GetDiskFilePriority()

int CParaFile::GetDiskFilePriority ( )

static

set the disk file priority.

it affects whether the disk will be searched first or the one in the archive files. default disk file will be searched first.

Returns: : 0 is the same priority as the disk file. so 0 or above will cause the disk file to be searched before archive files. below 0, such as -1 will cause the archive files go first.

§ GetExtractFileProperty()

bool CParaFile::GetExtractFileProperty ( )

static

check whether to extract file.

§ GetFileExtension()

string CParaFile::GetFileExtension ( const string & sFile )

static

get the file extension.

this function may return "" if no file extension is found

§ GetFileInfo()

bool ParaEngine::CParaFile::GetFileInfo	(	const char *	filename,
		CParaFileInfo &	fileInfo,
		uint32	dwWhereToOpen = `FILE_ON_DISK \| FILE_ON_ZIP_ARCHIVE \| FILE_ON_SEARCH_PATH`
	)

static

get file attributes like file type, where the file is found, absolute path, modification time, size, etc.

Parameters

ParaFileInfo file info.

load from Zip files, if the file does not exist on disk

§ GetFileName()

string CParaFile::GetFileName ( const string & sFilePath )

static

get only the file name from the file path.

"a.x" = GetFileName("c:/lxzsrc/a.x");

§ GetFileSize()

int CParaFile::GetFileSize ( const char * sFilePath )

static

get file size of a disk file in bytes.

§ GetNextAttribute() [1/6]

bool CParaFile::GetNextAttribute	(	const char *	sName,
		string &	output
	)

in order to call this method.

The file must be a text based file containing comments "--" and <attribute = value> pair in each line. the supported format is given by example: – a comment line
Name1 = 1024
Name2 = ParaEngine Tech Studio @ STI
Please note that there must be a line delimiter'
' or '
' inbetween each attribute,value pair. Now that one can call this function GetNextAttribute("Name1", nValue), where nValue will be 1024. GetNextAttribute("Name1", sValue), where sValue will be "ParaEngine Tech Studio @ STI".

Parameters

sName	: name of the attribute
output	: output value

Returns: true if the attribute name is found and that the output is successfully parsed, the current file pointer will be right after the line delimiter; if return value is false, the current file pointer will be set to the beginning of the current line, ready for a second try; however if the sName is found, yet the value is unable to be parsed. the file pointer will skip the current line.

Remarks: : line length should not exceed 1024

§ GetNextAttribute() [2/6]

bool CParaFile::GetNextAttribute	(	const char *	sName,
		float &	output
	)

See also: GetNextAttribute(const char * sName, string& output)

§ GetNextAttribute() [3/6]

bool CParaFile::GetNextAttribute	(	const char *	sName,
		double &	output
	)

See also: GetNextAttribute(const char * sName, string& output)

§ GetNextAttribute() [4/6]

bool CParaFile::GetNextAttribute	(	const char *	sName,
		int &	output
	)

See also: GetNextAttribute(const char * sName, string& output)

§ GetNextAttribute() [5/6]

bool CParaFile::GetNextAttribute	(	const char *	sName,
		bool &	output
	)

See also: GetNextAttribute(const char * sName, string& output)

§ GetNextAttribute() [6/6]

bool CParaFile::GetNextAttribute ( const char * sName )

read a single word from the next line.

See also: GetNextAttribute(const char * sName, string& output)

§ GetNextFormatted()

template<class TYPE_ARG1 >

bool ParaEngine::CParaFile::GetNextFormatted	(	const char *	sFormat,
		TYPE_ARG1	a1
	)

inline

this is similar to GetNextAttribute().

I used to prefer bool GetNextFormatted(const char * sFormat, ...) however, visual C++ 2003 does not have vsnscanf() which accept va_list parameter.

Parameters

sFormat a format as passed to scanf()

Returns: : true if the attribute name is found and that the output is successfully parsed, the current file pointer will be right after the line delimiter; if return value is false, the current file pointer will be set to the beginning of the current line, ready for a second try.

Remarks: : there must at least be one argument in the argument list. If not use GetNextAttribute(const char * sName) instead. this function will return true if one or more arguments are parsed. However, it does not ensure all argument in format string are parsed successfully.

§ GetNextLine()

int CParaFile::GetNextLine	(	char *	buf,
		int	sizeBuf
	)

return the next line of text string from the current file position.

if a line begins with "--", it is automatically recognized as a comment line and will be skipped. a blank line will also be skipped

Parameters

buf	output buffer
sizeBuf	size of the output buffer in bytes. TODO: if this is 0, this function return the number of bytes required.

Returns: number of bytes read

§ GetParentDirectoryFromPath()

std::string CParaFile::GetParentDirectoryFromPath	(	const string &	sfilename,
		int	nParentCounts = `0`
	)

static

trim the sFile by nParentCounts number of parent directories.

Parameters

nParentCounts number of parent directory to remove. 0 means the current directory,which is also the default value

Returns: : return "" if the input directory does not have that many parent directories. e.g. "C:/abc/" = GetDirectoryFromPath("C:/abc/aaa",0); "C:/" = GetDirectoryFromPath("C:/abc/",1);

§ GetRelativePath()

string CParaFile::GetRelativePath	(	const string &	sAbsolutePath,
		const string &	sRootPath
	)

static

Get the relative file path by stripping the root path from the beginning.

please note that all paths should uses slash "/", instead of backslash "\", in the path name.letter case is ignored

Parameters

sAbsolutePath	the absolute path from which to obtain the relative path.
sRootPath	the parent root path, which will be removed from the absolute path. It should end with "/"

Returns: : the relative path is returned. If the absolute path does not math the root path, the absolute path is returned unchanged. the relative path does not begin with "/" e.g. "a/b.x" = GetRelativePath("c:/lxzsrc/a/b.x", "c:/lxzsrc/"); "c:/lxzsrc/a/b.x" = GetRelativePath("c:/lxzsrc/a/b.x", "c:/srclxz/"); // not match

§ GetWritablePath()

const std::string & CParaFile::GetWritablePath ( )

static

in win32, this is the root directory, Gets the writable path.

Returns: The path that can be write/read a file in

§ IsAbsolutePath()

bool ParaEngine::CParaFile::IsAbsolutePath ( const std::string & path )

static

Checks whether the path is an absolute path.

Note: On Android, if the parameter passed in is relative to "assets/", this method will treat it as an absolute path. Also on Blackberry, path starts with "app/native/Resources/" is treated as an absolute path.

Parameters

strPath The path that needs to be checked.

Returns: true if it's an absolute path, otherwise it will return false.

§ IsCompressed()

bool CParaFile::IsCompressed ( )

get whether the buffer and size is a zip compressed.

§ IsFileName()

bool CParaFile::IsFileName ( const string & sFilePath )

static

return whether the given path is only a file name which contains no directory information.

§ IsWritablePath()

bool ParaEngine::CParaFile::IsWritablePath	(	const std::string &	filepath,
		bool	bLogWarning = `true`
	)

static

whether the given file is a writable path.

For absolute file path, we only allow files in initial working directory and writable path.

§ MakeDirectoryFromFilePath()

bool CParaFile::MakeDirectoryFromFilePath ( const char * filename )

static

make directory

Parameters

filename file name should be a Canonical File Path. Use ,ToCanonicalFilePath

Returns: : true if the directory is made or already exists

§ MoveFile()

bool CParaFile::MoveFile	(	const char *	src,
		const char *	dest
	)

static

The MoveFile function will move (rename) either a file or a directory (including its children) either in the same directory or across directories.

Parameters

src	specifies the name of an existing file
dest	specifies the name of the new file

Returns: true if succeeds

§ OpenAssetFile()

int CParaFile::OpenAssetFile	(	const char *	filename,
		bool	bDownloadIfNotUpToDate = `true`,
		const char *	relativePath = `NULL`
	)

This is rather similar to OpenFile() method, except that it will first look in the AssetManifest to see if the file exit.

If the file does appear in manifest list, we will download the latest version from the current asset server, if not done before. the download process is SYNCHRONOUS. If the file does not appear in AssetManifest list, this function is equivalent to OpenFile()

Parameters

filename	the asset file key to open. The actual file opened may from the temp/cache/ folder.
bDownloadIfNotUpToDate	default to true. if true, we will download the latest version from the current asset server. the download process is synchronous. If false, the function will return 0 immediately, when the caller may consider download the file asynchronously, and then open the file again.
relativePath	a relative path file name. it can be NULL, in which case filename is treated as a root path name

Returns: : 1 if succeed. 0, if file is not downloaded successfully.

§ OpenFile()

bool CParaFile::OpenFile	(	const char *	filename,
		bool	bReadyOnly = `true`,
		const char *	relativePath = `NULL`,
		bool	bUseCompressed = `false`,
		uint32	dwWhereToOpen = `FILE_ON_DISK \| FILE_ON_ZIP_ARCHIVE \| FILE_ON_SEARCH_PATH`
	)

Open a file for immediate reading.If the file name begins with ':', it is treated as a win32 resource.

e.g.":IDR_FX_OCEANWATER". loads data from a resource of type "TEXTFILE". See MSDN for more information about Windows resources. Caller calls getBuffer() to retrieval the data

Parameters

filename	the file name to open. if it is "<memory>" and bReadOnly is false. it is a memory file.
bReadyOnly	if true, the file is loaded for read-only access. The disk file is searched, then the ZIP files are searched. If false, only the disk file is searched, and that the file is a write-only file. NOTE1: Calling any of the write method in read-only mode or calling any read method in write-only mode will lead to unexpected result. NOTE2: for opening write-only file, check the file existence first to prevent file overridden the file will be opened with OPEN_ALWAYS tag by Windows API CreateFile(). The file pointer is the end of file.
relativePath	a relative path file name. it can be NULL, in which case filename is treated as a root path name
bUseCompressed	default to false. if this is true and the file is stored compressed on disk, it will be loaded as raw compressed file. getBuffer() will return raw compressed data buffer. One needs to manually call Decompress() at a later time, in order to access the uncompressed data. this feature is usually used by the content streaming architecture, where the IO thread load compressed data to memory and one of the worker thread decompress it.

Returns: : true if succeeded.

append the relative path

for ready-only file, we will read everything in to the buffer, and close the file handle

load from Zip files, if the file does not exist on disk

extract file to disk for debugging purposes.

If the file name begins with ':' or FILE_ON_EXECUTABLE is specified, it is treated as a win32 resource.

e.g.":IDR_FX_OCEANWATER". loads data from a resource of type "TEXTFILE". See MSDN for more information about Windows resources. we also support C++ embedded binary file as external global variables in this way.

for write-only file, we will save file handle.

set end of file to prevent read access.

§ read()

size_t CParaFile::read	(	void *	dest,
		size_t	bytes
	)

read byte stream from file at its current location.

The buffer pointer will be advanced.

§ ReadEncodedUInt()

uint32_t CParaFile::ReadEncodedUInt ( )

read compressed unsigned int (16, 32, 64, etc)

Parameters

nByteRead number of bytes read

§ SetDevDirectory()

void CParaFile::SetDevDirectory ( const string & sFilePath )

static

set developer path.

the developer directory is a readonly path that is searched first for all file reading operations.

§ SetDiskFilePriority()

void CParaFile::SetDiskFilePriority ( int nPriority )

static

set the disk file priority.

it affects whether the disk will be searched first or the one in the archive files. default disk file will be searched first.

Parameters

nPriority 0 is the same priority as the disk file. so 0 or above will cause the disk file to be searched before archive files. below 0, such as -1 will cause the archive files go first.

§ SetEndOfFile()

bool CParaFile::SetEndOfFile ( )

The SetEndOfFile function moves the end-of-file (EOF) position for the specified file to the current position of the file pointer.This function can be used to truncate or extend a file.

If the file is extended, the contents of the file between the old EOF position and the new position are not defined.

Returns

§ SetExtractFileProperty()

void CParaFile::SetExtractFileProperty ( bool bExtractFile )

static

set whether to extract file to disk.

This is only for debugging purposes, where one can export all files used during a game session to disk.

§ SetFilePointer()

void CParaFile::SetFilePointer	(	int	lDistanceToMove,
		int	dwMoveMethod
	)

The SetFilePointer function moves the file pointer of an open file.

this function only works when the ParaFile object is an actual windows file, instead of a virtual file. for virtual file, use the seek and seekRelative function.

Parameters

lDistanceToMove
dwMoveMethod	0: FILE_BEGIN The starting point is 0 (zero) or the beginning of the file. 1: FILE_CURRENT The starting point is the current value of the file pointer. 2: FILE_END The starting point is the current end-of-file position.

§ SetIsCompressed()

void CParaFile::SetIsCompressed ( bool bCompressed )

set whether the buffer and size is a zip compressed.

if true, one can use Decompress() function to turn the buffer to uncompressed data.

§ SetWritablePath()

void CParaFile::SetWritablePath ( const std::string & writable_path )

static

Note: NOT thread safe, only set at startup when there is just one thread running.

§ SkipComment()

int CParaFile::SkipComment ( )

advancing file pointer, skipping all comment lines, blank lines, and blank spaces.

Returns: the number of bytes skipped.

§ SkipCurrentLine()

int CParaFile::SkipCurrentLine ( )

skip the current line.

the file position will be at the beginning of the next line. if the line terminator is
. the file pos is at
.

§ SkipEqualMark()

int CParaFile::SkipEqualMark ( )

advancing file pointer, skipping all occurrences of ' ' and '=' mark

Returns: the number of bytes skipped.

§ SkipString()

int CParaFile::SkipString ( const char * sName )

advancing file pointer, skipping the sName.

Parameters

sName the string to skip.

Returns: the number of bytes skipped. if the sName is not matched with the file buffer, the file position will not be changed.

§ synchBits()

void CParaFile::synchBits ( )

Reset the bit buffer.

Since ParaFile is not designed for bit wise reading in general, one need to manually call synchBits() between the calls to a bit and a byte reading functions.

§ ToCanonicalFilePath() [1/2]

void CParaFile::ToCanonicalFilePath	(	string &	output,
		const string &	input,
		bool	bBackSlash = `false`
	)

static

convert a file name to canonical file path

Parameters

output	the output converted string. it can be the same string as input string
input	the input file name. it is assumed that strlen(filename) <= MAX_PATH
bBackSlash	if true, the file will use '\'; otherwise use '/'. '\' is win32 compatible. '/' is more user friendly.

Returns: : the canonical file path name returned.

§ ToCanonicalFilePath() [2/2]

void CParaFile::ToCanonicalFilePath	(	char *	output,
		const char *	input,
		bool	bBackSlash = `false`
	)

static

save as above

Parameters

output should be char output[MAX_PARAFILE_LINE_LENGTH]

§ UnzipMemToFile()

bool CParaFile::UnzipMemToFile	(	const char *	buffer,
		int	nSize,
		const char *	destFilename,
		bool	bAutoMakeDirectory
	)

static

upzip the first file in a memory zip file to a given destFileName.

this function is mostly used when we downloaded a ziped file from network, and write its unzipped version to disk cache

§ WriteString() [1/2]

int CParaFile::WriteString ( const string & sStr )

write string to file.

the file must be opened with write access.

§ WriteString() [2/2]

int CParaFile::WriteString	(	const char *	sStr,
		int	nLen = `0`
	)

write string to file.

the file must be opened with write access.

Parameters

sStr	string which should be terminated with '\0'
nLen	always gives a string length, unless you are sure that sStr be terminated with '\0'

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

Client/trunk/ParaEngineClient/IO/ParaFile.h
Client/trunk/ParaEngineClient/IO/ParaFile.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

§ CParaFile() [1/4]

§ CParaFile() [2/4]

§ CParaFile() [3/4]

§ CParaFile() [4/4]

Member Function Documentation

§ AutoFindParaEngineRootPath()

§ BackupFile()

§ ChangeFileExtension()

§ CopyFile()

§ CRC32()

§ CreateDirectory()

§ CreateNewFile()

§ Decompress()

§ DeleteFile()

§ DeleteTempFile()

§ DoesAssetFileExist()

§ DoesFileExist()

§ DoesFileExist2()

§ ExtractFileToDisk()

§ GetAbsolutePath()

§ GetCurDirectory()

§ GetDiskFilePriority()

§ GetExtractFileProperty()

§ GetFileExtension()

§ GetFileInfo()

§ GetFileName()

§ GetFileSize()

§ GetNextAttribute() [1/6]

§ GetNextAttribute() [2/6]

§ GetNextAttribute() [3/6]

§ GetNextAttribute() [4/6]

§ GetNextAttribute() [5/6]

§ GetNextAttribute() [6/6]

§ GetNextFormatted()

§ GetNextLine()

§ GetParentDirectoryFromPath()

§ GetRelativePath()

§ GetWritablePath()

§ IsAbsolutePath()

§ IsCompressed()

§ IsFileName()

§ IsWritablePath()

§ MakeDirectoryFromFilePath()

§ MoveFile()

§ OpenAssetFile()

§ OpenFile()

§ read()

§ ReadEncodedUInt()

§ SetDevDirectory()

§ SetDiskFilePriority()

§ SetEndOfFile()

§ SetExtractFileProperty()

§ SetFilePointer()

§ SetIsCompressed()

§ SetWritablePath()

§ SkipComment()

§ SkipCurrentLine()

§ SkipEqualMark()

§ SkipString()

§ synchBits()

§ ToCanonicalFilePath() [1/2]

§ ToCanonicalFilePath() [2/2]

§ UnzipMemToFile()

§ WriteString() [1/2]

§ WriteString() [2/2]