Detailed Description

This class provides platform independent access to common file and directory related methods.

Note

If you are not using the version of Visual Studio that MapLink was built with then may not be able to use the following methods from this class:

fopen
fclose
ftell
fseek

The issue is that FILE definition may be different between the C Runtimes.

Public Types
typedef void(*	FilenameCallback) (const TSLSimpleString &foundFile, const TSLSimpleString &directory, void *userData)

typedef void(*	DirectoryCallback) (const TSLSimpleString &foundDirectory, void *userData)

Static Public Member Functions
static bool	buildDirectory (TSLSimpleString &path, const char baseDir, const char subDir)

static bool	createDirectory (const char *dirname)

static bool	copyFile (const char sourceFile, const char destinationFile)

static bool	composePathname (TSLSimpleString &fullPath, const char directory, const char basename, const char *extension)

static bool	compareFilenames (const char first, const char second, const bool removeTrailingWhitespace=true)

static bool	decomposePathname (const char *fullPath, TSLSimpleString &directory, TSLSimpleString &basename, TSLSimpleString &extension)

static int	deleteFile (const char *filename)

static int	deleteDirectory (const char *dirName)

static bool	directoryExists (const char *dirname)

static int	fileAccess (const char *path, int mode)

static bool	fileExists (const char *filename)

static bool	fileModificationTime (char const *filePath, TSLTimeType &lastModificationTime)

static TSLFileLength	fileSize (const char *path)

static int	fclose (FILE *stream)

static FILE *	fopen (const char filename, const char mode)

static TSLFileOffset	ftell (FILE *stream)

static int	fseek (FILE *stream, TSLFileOffset offset, int origin)

static TSLTextEncoding	legacyGetEncodingOverride ()

static void	legacySetEncodingOverride (TSLTextEncoding encoding)

static bool	listDirectory (const char directory, FilenameCallback filenameCallback, void userData=NULL, const char pattern="")

static bool	listSubDirectories (const char directory, DirectoryCallback directoryCallback, void userData=NULL, const char pattern="")

static bool	rename (const char oldName, const char newName)

Member Typedef Documentation

◆ DirectoryCallback

typedef void(* TSLFileHelper::DirectoryCallback) (const TSLSimpleString &foundDirectory, void *userData)

Function typedef.

This function typedef defines the signature of a function that the user can pass to the listSubDirectories() method.

Implementation:

static void directoryCallback(const TSLSimpleString &foundDirectory, void *userData);

TSLSimpleString

Definition tslsimplestring.h:43

The callback will be called for each directory found. The user should copy the directory string passed in.

Parameters

foundDirectory	The full path of a sub-directory found in the requested directory.
userData	The userData pointer that was passed to the listSubDirectories() method.

◆ FilenameCallback

typedef void(* TSLFileHelper::FilenameCallback) (const TSLSimpleString &foundFile, const TSLSimpleString &directory, void *userData)

Function typedef.

This function typedef defines the signature of a function that the user can pass to the listDirectory() method.

Implementation:

static void filenameCallback(const TSLSimpleString &foundFile, const TSLSimpleString &directory, void *userData);

The callback will be called for each file found. The user should copy the filename passed in and potentially the associated directory string too.

Parameters

foundFile	The name of a file found in the directory passed to listDirectory(). This does not contain the directory path, just the filename.
directory	The base directory passed to listDirectory().
userData	The userData pointer that was passed to the listDirectory() method.

Member Function Documentation

◆ buildDirectory()

static bool TSLFileHelper::buildDirectory	(	TSLSimpleString &	path,
		const char *	baseDir,
		const char *	subDir )

static

Composes a full pathname from directory and subdirectory.

Parameters

path	The returned full pathname
baseDir	The base directory.
subDir	The sub directory.

Returns: True if successful, False otherwise.

◆ compareFilenames()

static bool TSLFileHelper::compareFilenames	(	const char *	first,
		const char *	second,
		const bool	removeTrailingWhitespace = true )

static

This method compares filenames.

The comparison is carried out against the full string in both parameters. So if a partial path is passed in it is assumed that the same partial path is passed in.

On windows it will be case-insensitive and on all other OS's it will be case sensitive.

The directory path separators will be correctly altered for the relevant platforms before comparison.

The filename's are not returned.

Parameters

first	The first filename to compare.
second	The second filename to compare.
removeTrailingWhitespace	If true any trailing white space is removed before the comparison occurs.

Returns: True if the path's and name are equivalent.

◆ composePathname()

static bool TSLFileHelper::composePathname	(	TSLSimpleString &	fullPath,
		const char *	directory,
		const char *	basename,
		const char *	extension )

static

composes a full pathname from directory, basename and extension components.

If particular components are not required then NULL may be passed as the appropriate parameter.

Parameters

fullPath	The full path created from the other parameters.
directory	The directory the file is contained in.
basename	The first part of the filename.
extension	The file extension. The '.' is not required.

Returns: True if successful, False otherwise.

◆ copyFile()

static bool TSLFileHelper::copyFile	(	const char *	sourceFile,
		const char *	destinationFile )

static

Copies the specified source file to the given destination.

Parameters

sourceFile	The full path to the source file to copy
destinationFile	The full path including filename to where the file should be copied to. Any directories specified as part of the destination file path should already exist.

Returns: true if the operation succeeded, false otherwise.

◆ createDirectory()

static bool TSLFileHelper::createDirectory ( const char * dirname )

static

Creates specified directory.

Parameters

dirname The name of the directory to create.

Returns: True on success, False on failure.

◆ decomposePathname()

static bool TSLFileHelper::decomposePathname	(	const char *	fullPath,
		TSLSimpleString &	directory,
		TSLSimpleString &	basename,
		TSLSimpleString &	extension )

static

This method decomposes the specified full pathname into directory, basename and extension components.

Arguments

fullPath : the full path to the filename.

directory : The directory containing the file.

basename : The base part of the filename.

extension : The extension of the filename. The '.' is not returned.

Returns True if successful, False otherwise.

◆ deleteDirectory()

static int TSLFileHelper::deleteDirectory ( const char * dirName )

static

This recursive method deletes the current directory (and any directories and files below it).

Parameters

dirName the directory to delete

Returns: 0 if successful, -1 otherwise.

◆ deleteFile()

static int TSLFileHelper::deleteFile ( const char * filename )

static

Deletes the specified file.

Parameters

filename the file to delete.

Returns: 0 if successful, -1 otherwise.

◆ directoryExists()

static bool TSLFileHelper::directoryExists ( const char * dirname )

static

Checks to see if a directory exists.

Parameters

dirname directory path to check for exists of.

Returns: True if exists, false otherwise.

◆ fclose()

static int TSLFileHelper::fclose ( FILE * stream )

static

Calls the correct fclose on different platforms.

stream : a FILE* opened via TSLFileHelper::fopen

Returns: 0 if the stream was successfully closed.

◆ fileAccess()

static int TSLFileHelper::fileAccess	(	const char *	path,
		int	mode )

static

This method checks the file access of the specified file. This is a simple access check.

This method calls _access under NT, access under X11. Determines the accessibility (read-only etc.) of the file passed.

Parameters

path	path to check access rights too.
mode	The mode of access to check for.

The mode may be OR'd together. The values are defined below

00 (F_OK) Check for existence.
02 (W_OK) Check for write access.
04 (R_OK) Check for read access.

Returns: 0 if successful, -1 otherwise.

◆ fileExists()

static bool TSLFileHelper::fileExists ( const char * filename )

static

Checks to see if a file exists.

Returns True if exists, false otherwise.

◆ fileModificationTime()

static bool TSLFileHelper::fileModificationTime	(	char const *	filePath,
		TSLTimeType &	lastModificationTime )

static

Queries the file for its last modification time.

Parameters

filePath	filename and path to the file to query.
lastModificationTime	The last modification time is returned in this parameter.

Returns: True if successful, false otherwise.

◆ fileSize()

static TSLFileLength TSLFileHelper::fileSize ( const char * path )

static

Determines the file size of the file passed.

Parameters

path	the filename to query the size of.

Returns: the size of the file in bytes.

◆ fopen()

static FILE * TSLFileHelper::fopen	(	const char *	filename,
		const char *	mode )

static

Performs an open which is where possible to the underlying OS large file fopen.

You can use this for large and small files.

Parameters

filename	the file to open
mode	the mode to open the file (see the fopen manual page for your system).

Returns: a pointer to the open file. A null pointer is returned if an error occurred.

◆ fseek()

static int TSLFileHelper::fseek	(	FILE *	stream,
		TSLFileOffset	offset,
		int	origin )

static

fseek for large files (where the OS supports large files).

You can use this for large and small files.

Parameters

stream	The FILE pointer returned by TSLFileHelper::fopen
offset	The offset returned by a call to TSLFileHelper::ftell
origin	The initial position

The origin may be one of the following

SEEK_CUR Current position of the file pointer
SEEK_END End of file.
SEEK_SET Beginning of file.
Returns
0 if successful.

◆ ftell()

static TSLFileOffset TSLFileHelper::ftell ( FILE * stream )

static

ftell for large file support (where the OS supports large files).

You can use this for large and small files.

stream : The FILE pointer returned by TSLFileHelper::fopen

Returns: the current position in the file.

◆ legacyGetEncodingOverride()

static TSLTextEncoding TSLFileHelper::legacyGetEncodingOverride ( )

static

Get the legacy text encoding override.

If set, this override specifies the encoding of filenames passed to and from the TSLFileHelper.

This function is only for use with legacy applications, and will be removed in a future release.

Returns the legacy text encoding override.

◆ legacySetEncodingOverride()

static void TSLFileHelper::legacySetEncodingOverride ( TSLTextEncoding encoding )

static

Set the legacy text encoding override. If set, this override specifies the encoding of filenames passed to and from TSLFileHelper.

This function is only for use with legacy applications, and will be removed in a future release. Applications are strongly discouraged from using this function as changing the value may cause errors to occur elsewhere in MapLink when working with Unicode filenames.

If an application changes the value in order to pass non-UTF8 strings to a method on this class, it must restore the original encoding (TSLTextEncodingUTF8) immediately after the method has returned to avoid errors occurring in other parts of MapLink.

This function is not thread safe.

Parameters

encoding The text encoding to use.

◆ listDirectory()

static bool TSLFileHelper::listDirectory	(	const char *	directory,
		FilenameCallback	filenameCallback,
		void *	userData = NULL,
		const char *	pattern = "*" )

static

This method queries the contents of the specified directory and calls the user supplied callback for each item found.

Parameters

directory	Directory to search.
filenameCallback	Callback to call for each file found in the directory.
userData	A pointer to user supplied data. This is passed to the user supplied callback.
pattern	Search pattern.

Returns: True on success, False otherwise. Note that True would be returned if the directory was valid, but empty.

◆ listSubDirectories()

static bool TSLFileHelper::listSubDirectories	(	const char *	directory,
		DirectoryCallback	directoryCallback,
		void *	userData = NULL,
		const char *	pattern = "*" )

static

This method queries the sub-directories of the specified directory and calls the user supplied callback for each item found.

Parameters

directory	Directory to search.
directoryCallback	Callback to call for each sub-directory found in the directory.
userData	A pointer to user supplied data. This is passed to the user supplied callback.
pattern	Search pattern.

Returns: True on success, False otherwise. Note that True would be returned if the directory was valid, but empty.

◆ rename()

static bool TSLFileHelper::rename	(	const char *	oldName,
		const char *	newName )

static

Renames a file or directory.

The method renames the file or directory specified by oldName to the name given by newName. The old name must be the path of an existing file or directory. The new name must not be the name of an existing file or directory. You can use rename to move a file from one directory or device to another by giving a different path in the newName argument. However, you cannot use rename to move a directory. Directories can be renamed, but not moved.

Parameters

oldName	The old name.
newName	The new name.

Returns: True if successful, False otherwise.

Detailed Description

Public Types

Static Public Member Functions

Member Typedef Documentation

◆ DirectoryCallback

◆ FilenameCallback

Member Function Documentation

◆ buildDirectory()

◆ compareFilenames()

◆ composePathname()

◆ copyFile()

◆ createDirectory()

◆ decomposePathname()

◆ deleteDirectory()

◆ deleteFile()

◆ directoryExists()

◆ fclose()

◆ fileAccess()

◆ fileExists()

◆ fileModificationTime()

◆ fileSize()

◆ fopen()

◆ fseek()

◆ ftell()

◆ legacyGetEncodingOverride()

◆ legacySetEncodingOverride()

◆ listDirectory()

◆ listSubDirectories()

◆ rename()