NPL Scripting Reference for ParaEngine: ParaScripting::ParaIO Class Reference


Static Public Member Functions
static const char *	DecodePath (const char *input)
	replace variables in input path and return the result path.
static const char *	EncodePath (const char *input)
	this does reverse of DecodePath.
static const char *	EncodePath2 (const char input, const char varNames)
	same as EncodePath, except that it will only replace variables who name appears in varNames.
static bool	AddPathVariable (const char sVarName, const char sVarValue)
	add a new variable to the replaceable pool
static bool	AddSearchPath (const char *sFile)
	add a search path to the search path pool.
static bool	AddSearchPath2 (const char *sFile, int nPriority)
static bool	RemoveSearchPath (const char *sFile)
	remove a search path from the search path pool.
static bool	ClearAllSearchPath ()
	clear all search paths.
static unsigned long	CRC32 (const char *filename)
	Get the CRC 32 code of a given file.
static void	UpdateMirrorFiles (const char *dirName, bool bOverwrite)
	this function is equivalent to calling the following functions.
static ParaZipWriter	CreateZip (const char fn, const char password)
	call this to start the creation of a zip file.
static int	DeleteFile (const char *sFilePattern)
	delete a given file.
static 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.
static bool	CopyFile (const char src, const char dest, bool bOverride)
	The CopyFile function copies an existing file to a new file.
static bool	CreateNewFile (const char *filename)
	create a new file for writing.
static bool	OpenFileWrite (const char *filename)
	open a new file for write-only access.
static bool	OpenFile (const char *filename)
	Open a file for read-only access.
static ParaFileObject	open (const char filename, const char mode)
	Open or create a file e.g.
static ParaFileObject	openimage (const char filename, const char mode)
	open an image file.
static bool	CreateDirectory (const char *filename)
	make directory
static void	CloseFile ()
	Close the current file.
static void	WriteString (const char *str)
	write a string to the current file.
static const char *	readline ()
	read line as a string.
static void	write (const char *buffer, int nSize)
	write a buffer to the current file.
static bool	DoesFileExist (const char *filename, bool bSearchZipFiles)
	Check whether a given file exists on disk.
static bool	DoesFileExist_ (const char *filename)
	see DoesFileExist().
static bool	BackupFile (const char *filename)
	backup a specified file, if the file exists.
static ParaSearchResult	SearchFiles (const char sRootPath, const char sFilePattern, const char *sZipArchive, int nSubLevel, int nMaxFilesNum, int nFrom)
	search files at once.
static ParaSearchResult	SearchFiles_c (const char sRootPath, const char sFilePattern, const char *sZipArchive, int nSubLevel)
static string	GetCurDirectory (DWORD dwDirectoryType)
	get the current directory of the application.
static const char *	GetCurDirectory_ (DWORD dwDirectoryType)
	this should never be called from the scripting interface.
static string	GetParentDirectoryFromPath (const char *sfilename, int nParentCounts)
	trim the sFile by nParentCounts number of parent directories.
static const char *	GetParentDirectoryFromPath_ (const char *sfilename, int nParentCounts)
	this should never be called from the scripting interface.
static string	AutoFindParaEngineRootPath (const char *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.
static const char *	AutoFindParaEngineRootPath_ (const char *sFile)
	this should never be called from the scripting interface.
static string	ChangeFileExtension (const char *sFile, const string &sExt)
	change the file extension.
static const char *	ChangeFileExtension_ (const char *sFile, const string &sExt)
	this should never be called from the scripting interface.
static string	GetFileExtension (const char *sFile)
	get the file extension.
static const char *	GetFileExtension_ (const char *sFile)
	this should never be called from the scripting interface.
static string	GetRelativePath (const char sAbsolutePath, const char sRootPath)
	Get the relative file path by stripping the root path from the beginning.
static const char *	GetRelativePath_ (const char sAbsolutePath, const char sRootPath)
	this should never be called from the scripting interface.
static string	GetAbsolutePath (const char sRelativePath, const char sRootPath)
	Get the absolute file path by appending the root path before the relative path.
static const char *	GetAbsolutePath_ (const char sRelativePath, const char sRootPath)
	this should never be called from the scripting interface.
static string	GetFileName (const char *sFilePath)
	get only the file name from the file path.
static const char *	GetFileName_ (const char *sFilePath)
	this should never be called from the scripting interface.
static int	GetFileSize (const char *sFilePath)
	The GetFileSize function retrieves the size of the specified file.
static string	ToCanonicalFilePath (const char *sfilename, bool bBackSlash)
	convert a file name to canonical file path
static const char *	ToCanonicalFilePath__ (const char *sfilename, bool bBackSlash)
	this should never be called from the scripting interface.
static void	SetDiskFilePriority (int nPriority)
	set the disk file priority.
static int	GetDiskFilePriority ()
	set the disk file priority.

Member Function Documentation

const char * ParaScripting::ParaIO::DecodePath ( const char * input ) [static]

replace variables in input path and return the result path.

see AddPathVariable

Parameters:

input,:

a path with or without replaceable. make sure you have called ToCanonicalFilePath() to canonicalize the input before calling this function

Returns:: the resulting path. Please note that the return value is the input itself if nothing is replaced. otherwise, it is a static string reference containing the result. therefore the result is NOT thread safe.

const char * ParaScripting::ParaIO::EncodePath ( const char * input ) [static]

this does reverse of DecodePath.

see AddPathVariable

Parameters:

input,:

a path with or without replaceable. make sure you have called ToCanonicalFilePath() to canonicalize the input before calling this function

const char * ParaScripting::ParaIO::EncodePath2	(	const char *	input,
		const char *	varNames
	)			`[static]`

same as EncodePath, except that it will only replace variables who name appears in varNames.

varNames is a comma separated list of variable names.

Parameters:

varNames,:

a comma separated list of variable names. like "WORLD,USERID", etc.

bool ParaScripting::ParaIO::AddPathVariable	(	const char *	sVarName,
		const char *	sVarValue
	)			`[static]`

add a new variable to the replaceable pool

Parameters:

	sVarName,:	the variable name without enclosing %%, such as "WORLD", "USERID", usually uppercase.
	sVarValue,:	the path that the variable expands to. If nil, it will remove the variable.

Returns:: : true if succeed. it may return false, if a protected variable with the same name already exist but it not editable via scripting interface.

bool ParaScripting::ParaIO::AddSearchPath ( const char * sFile ) [static]

add a search path to the search path pool.

It will internally normalize the path and check for duplicates note: this function shall not be called by an untrusted client, since it will secretly swap files. : shall we support remote http zip file as a valid search path?

unsigned long ParaScripting::ParaIO::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.

void ParaScripting::ParaIO::UpdateMirrorFiles	(	const char *	dirName,
		bool	bOverwrite
	)			`[static]`

this function is equivalent to calling the following functions.

LoadLogFromFile("InstallFiles.txt"); LoadLogFromFile("temp/filelog.txt"); MirrorFiles(dirName, bOverwrite);

e.g. UpdateMirrorFiles("_InstallFiles/", true);

Parameters:

	dirName,:	such as "_InstallFiles/"
	bOverwrite,:	if this is true, existing files will be overridden.

int ParaScripting::ParaIO::DeleteFile ( const char * sFilePattern ) [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

Returns:: : the number of files deleted.

bool ParaScripting::ParaIO::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

bool ParaScripting::ParaIO::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

bool ParaScripting::ParaIO::CreateNewFile ( const char * filename ) [static]

create a new file for writing.

it will make all necessary directories in order to create the file.

bool ParaScripting::ParaIO::OpenFileWrite ( const char * filename ) [static]

open a new file for write-only access.

If the file does not exist, it will be created. if the file exists, the file pointer is at the end of file.

bool ParaScripting::ParaIO::OpenFile ( const char * filename ) [static]

Open a file for read-only access.

ParaFileObject ParaScripting::ParaIO::open	(	const char *	filename,
		const char *	mode
	)			`[static]`

Open or create a file e.g.

ParaIO.open("temp/test.txt", "w");

Parameters:

	filename
	mode	: access mode "r" Opens for reading. If the file does not exist or cannot be found, the call fails. "w" Opens an empty file for writing. If the given file exists, its contents are destroyed.If not, file will be created. "a" append to the end of an existing file. if file does not exist, a new one is created.

Returns:: file object is returned.

ParaScripting::ParaFileObject ParaScripting::ParaIO::openimage	(	const char *	filename,
		const char *	mode
	)			`[static]`

open an image file.

The r,g,b can then be retrieved as bytes arrays using ReadBytes() function.

Parameters:

	filename,:	such as BMP, DDS, JPG, etc. It must be a square image. The size of the image can thus be calculated by file size.
	mode	: access mode "r8g8b8": each pixel is a three bytes of R,G,B "a8r8g8b8": each pixel is a four bytes of A,R,G,B "float32": each pixel is a four bytes of float. [Not supported yet]

bool ParaScripting::ParaIO::CreateDirectory ( const char * filename ) [static]

make directory

Parameters:

filename,:

director path. file portion will be automatically striped off. So it is ok to pass in file name, instead of directory name.

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

void ParaScripting::ParaIO::CloseFile ( ) [static]

Close the current file.

void ParaScripting::ParaIO::WriteString ( const char * str ) [static]

write a string to the current file.

const char * ParaScripting::ParaIO::readline ( ) [static]

read line as a string.

The string is guaranteed to be ended with ''. if end of file is reached, it will return NULL. which is nil in the script. if a line begins with "--", it is automatically recognized as a comment line and will be skipped. a blank line will also be skipped.

void ParaScripting::ParaIO::write	(	const char *	buffer,
		int	nSize
	)			`[static]`

write a buffer to the current file.

bool ParaScripting::ParaIO::DoesFileExist	(	const char *	filename,
		bool	bSearchZipFiles
	)			`[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. currently bSearchZipFiles can only be false. Because it is not efficient to check existence of ZIPPED files. Use OpenFile() and check for return value instead.

bool ParaScripting::ParaIO::DoesFileExist_ ( const char * filename ) [static]

see DoesFileExist().

This version is same as DoesFileExist(filename, false);

bool ParaScripting::ParaIO::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.

ParaSearchResult ParaScripting::ParaIO::SearchFiles	(	const char *	sRootPath,
		const char *	sFilePattern,
		const char *	sZipArchive,
		int	nSubLevel,
		int	nMaxFilesNum,
		int	nFrom
	)			`[static]`

search files at once.

See also:: CSearchResult the current version of this function can support only one query at a time. The search result is invalid if called intermitantly

Parameters:

	sRootPath,:	the root path. for example: "", "xmodel/","xmodel/models/". Other format is not acceptable
	sFilePattern,:	file pattern, e.g. ".x" (all files with x extension), "" (any files), "."(directories only) if sZipArchive is non-empty, sFilePattern support both regular expression and wild card search. it performs wild cards search by default, where "/\\" matches to directory. " "matches to anything except "/\\.", and "." matches to "." itself. e.g.. ".", ".", "worlds/.abc", "abc/.jpg", etc it sFilePattern begins with ":", things after ":" is treated like a regular expression. It has the same syntax with the perl regular expression and uses full match. e.g.. ":.*\\.jpg", etc.
	sZipArchive,:	it can be "" or a zip archive file name. if it is "", only disk files are searched. if it is not, only that archive files are saved.
	nSubLevel,:	how many sub folders of sRootPath to look into. default value is 0, which only searches the sRootPath folder.
	nMaxFilesNum,:	one can limit the total number of files in the search result. Default value is 50. the search will stop at this value even there are more matching files.
	nFrom,:	only contains results from nFrom to (nFrom+nMaxFilesNum)

Returns:: : one should manually release the search result.

string ParaScripting::ParaIO::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 enum PARAENGINE_DIRECTORY{ APP_ROOT_DIR=0, APP_SCRIPT_DIR=1, APP_ARCHIVE_DIR=2, // xmodels 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, };

Returns:: : the directory is returned.

const char * ParaScripting::ParaIO::GetCurDirectory_ ( DWORD dwDirectoryType ) [static]

this should never be called from the scripting interface.

it is only for API exportation. it uses a static string for the output. so it is not thread-safe.

string ParaScripting::ParaIO::GetParentDirectoryFromPath	(	const char *	sfilename,
		int	nParentCounts
	)			`[static]`

trim the sFile by nParentCounts number of parent directories.

Parameters:

nParentCounts,:

number of parent directory to remove

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);

const char * ParaScripting::ParaIO::GetParentDirectoryFromPath_	(	const char *	sfilename,
		int	nParentCounts
	)			`[static]`

this should never be called from the scripting interface.

it is only for API exportation. it uses a static string for the output. so it is not thread-safe.

string ParaScripting::ParaIO::AutoFindParaEngineRootPath ( const char * 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.

const char * ParaScripting::ParaIO::AutoFindParaEngineRootPath_ ( const char * sFile ) [static]

this should never be called from the scripting interface.

it is only for API exportation. it uses a static string for the output. so it is not thread-safe.

string ParaScripting::ParaIO::ChangeFileExtension	(	const char *	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.

const char * ParaScripting::ParaIO::ChangeFileExtension_	(	const char *	sFile,
		const string &	sExt
	)			`[static]`

this should never be called from the scripting interface.

it is only for API exportation. it uses a static string for the output. so it is not thread-safe.

string ParaScripting::ParaIO::GetFileExtension ( const char * sFile ) [static]

get the file extension.

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

const char * ParaScripting::ParaIO::GetFileExtension_ ( const char * sFile ) [static]

this should never be called from the scripting interface.

it is only for API exportation. it uses a static string for the output. so it is not thread-safe.

string ParaScripting::ParaIO::GetRelativePath	(	const char *	sAbsolutePath,
		const char *	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

const char * ParaScripting::ParaIO::GetRelativePath_	(	const char *	sAbsolutePath,
		const char *	sRootPath
	)			`[static]`

this should never be called from the scripting interface.

it is only for API exportation. it uses a static string for the output. so it is not thread-safe.

string ParaScripting::ParaIO::GetAbsolutePath	(	const char *	sRelativePath,
		const char *	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 absolute path from which to obtain the relative path. It should not begin with "/"
	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. e.g. "c:/lxzsrc/a/b.x" = GetAbsolutePath("a/b.x", "c:/lxzsrc/");

const char * ParaScripting::ParaIO::GetAbsolutePath_	(	const char *	sRelativePath,
		const char *	sRootPath
	)			`[static]`

this should never be called from the scripting interface.

it is only for API exportation. it uses a static string for the output. so it is not thread-safe.

string ParaScripting::ParaIO::GetFileName ( const char * sFilePath ) [static]

get only the file name from the file path.

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

const char * ParaScripting::ParaIO::GetFileName_ ( const char * sFilePath ) [static]

this should never be called from the scripting interface.

it is only for API exportation. it uses a static string for the output. so it is not thread-safe.

int ParaScripting::ParaIO::GetFileSize ( const char * sFilePath ) [static]

The GetFileSize function retrieves the size of the specified file.

The file size that can be reported by this function is limited to a DWORD value

Returns:: : size of the file. If the file does not exist or the file size is 0, the return value is 0.

Note:: : only disk file is searched.files inside zip file are ignored.

string ParaScripting::ParaIO::ToCanonicalFilePath	(	const char *	sfilename,
		bool	bBackSlash
	)			`[static]`

convert a file name to canonical file path

Parameters:

	sfilename,:	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.

const char * ParaScripting::ParaIO::ToCanonicalFilePath__	(	const char *	sfilename,
		bool	bBackSlash
	)			`[static]`

this should never be called from the scripting interface.

it is only for API exportation. it uses a static string for the output. so it is not thread-safe.

void ParaScripting::ParaIO::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.

int ParaScripting::ParaIO::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.

ParaScripting::ParaIO Class Reference
[ParaIO]

Detailed Description

Static Public Member Functions

Member Function Documentation

ParaScripting::ParaIO Class Reference [ParaIO]

Detailed Description

Static Public Member Functions

Member Function Documentation

ParaScripting::ParaIO Class Reference
[ParaIO]