This concrete class defines the interface for handling and manipulating entries in the System's File system. More...

Detailed Description

This concrete class defines the interface for handling and manipulating entries in the System's File system.

The directory separator is ALWAYS '/'. If necessary it will be internally converted to the OS/platform specific delimiter. Directory paths can contain drive designators, but ONLY if the native OS supports it.

#include <Api.h>

Classes
class	DirectoryWalker
	This abstract class defines the client interface for walking the contents of a directory, i.e. More...

struct	Info
	This data structure defines status attributes for a file system entry. More...

Static Public Member Functions
static char	directorySep ()
	Standardized Directory separator.

static char	nativeDirectorySep ()
	Returns the native Directory separator.

static void	splitDrive (const char *fsEntryName, Cpl::Text::String &drive, char driveSeparator=':')
	Extracts the drive letter from the complete name.

static void	splitFullpath (const char *fsEntryName, Cpl::Text::String &fullpath, char dirSeparator=directorySep(), char extensionSeparator='.', char driveSeparator=':')
	Extracts the full path (drive+path) from the complete name.

static void	splitPath (const char *fsEntryName, Cpl::Text::String &path, char dirSeparator=directorySep(), char extensionSeparator='.', char driveSeparator=':')
	Extracts the path (no drive) from the complete name.

static void	splitFullname (const char *fsEntryName, Cpl::Text::String &fullname, char dirSeparator=directorySep(), char extensionSeparator='.', char driveSeparator=':')
	Extracts the full file name (name+extension) from the complete name.

static void	splitName (const char *fsEntryName, Cpl::Text::String &name, char dirSeparator=directorySep(), char extensionSeparator='.', char driveSeparator=':')
	Extracts the file name from the complete name.

static void	splitExtension (const char *fsEntryName, Cpl::Text::String &extension, char dirSeparator=directorySep(), char extensionSeparator='.', char driveSeparator=':')
	Extracts the file extension from the complete name.

static void	splitFullpathFullName (const char *fsEntryName, Cpl::Text::String &fullpath, Cpl::Text::String &fullname, char dirSeparator=directorySep(), char extensionSeparator='.', char driveSeparator=':')
	Extracts the full path and name from the complete name.

static void	split (const char fsEntryName, Cpl::Text::String fullPath, Cpl::Text::String drive, Cpl::Text::String path, Cpl::Text::String fullName, Cpl::Text::String name, Cpl::Text::String *extension, char dirSeparator=directorySep(), char extensionSeparator='.', char driveSeparator=':')
	This method breaks the specified File System Entry name into it's individual components.

static bool	canonicalPath (const char *relPath, Cpl::Text::String &absPath)
	This method expands the relative path name in 'relPath' to its 'absPath'.

static bool	getCwd (Cpl::Text::String &cwd)
	This method returns the canonical/absolute path of the current working directory.

static const char *	getNative (const char *fsEntryName)
	Returns the file system entry name in its in native format.

static const char *	getStandard (const char *fsEntryName)
	Returns the file system entry name in the 'Standard' format.

static const char *	dos2unix (const char *fsEntryName)
	This method converts the DOS directory separator to the UNIX directory separator.

static const char *	unix2dos (const char *fsEntryName)
	This method converts the UNIX directory separator to the DOS directory separator.

static bool	exists (const char *fsEntryName)
	Returns true if the File Entry exists physically exists in the OS's file system.

static bool	isFile (const char *fsEntryName)
	Returns true if the File Entry is a file.

static bool	isDirectory (const char *fsEntryName)
	Returns true if the File Entry is a directory.

static bool	isReadable (const char *fsEntryName)
	Return true if the user has read permission for the file system entry.

static bool	isWriteable (const char *fsEntryName)
	Return true if the user has write permission for the file system entry.

static unsigned long	size (const char *fsEntryName)
	Returns the size, in bytes, of the file.

static time_t	timeModified (const char *fsEntryName)
	Returns the time/date the file entry was last modified.

static bool	getInfo (const char *fsEntryName, Info &infoOut)
	Returns information about the file system entry.

static bool	createFile (const char *fileName)
	Creates the 'fileName' as an empty file.

static bool	createDirectory (const char *dirName)
	Creates the 'dirName' as a directory.

static bool	renameInPlace (const char oldName, const char newName)
	Renames the file system entry name in the OS's file system.

static bool	moveFile (const char oldFileName, const char newFileName)
	Moves and/or renames the specified file.

static bool	remove (const char *fsEntryName)
	Deletes the file system entry from the OS's file system.

static bool	copyFile (const char srcName, const char dstName)
	Copies the context of the 'srcName' file to the specified 'dstName' file.

static bool	appendFile (const char srcName, const char destFile)
	Appends the context of the 'srcName' file to the specified 'dstName' file.

static bool	walkDirectory (const char *dirToList, DirectoryWalker &callback, int depth=1, bool filesOnly=false, bool dirsOnly=false)
	This method allows the caller to walk the contents of the 'dirToList' directory (assuming the entry is a directory).

Static Protected Member Functions
static Cpl::Text::String &	getWorkBuffer (void)
	Helper method. Returns an internal work buffer large enough to 'max path'.

Class Documentation

◆ Cpl::Io::File::Api::Info

struct Cpl::Io::File::Api::Info

This data structure defines status attributes for a file system entry.

Class Members
bool	m_isDir	True if the file entry is a directory.
bool	m_isFile	True if the file entry is a file.
time_t	m_mtime	Time the file entry was last modified/written.
bool	m_readable	True if the file entry is readable by the application.
unsigned long	m_size	Size, in bytes, of the file entry.
bool	m_writeable	True if the file entry is writable by the application.

Member Function Documentation

◆ appendFile()

static bool Cpl::Io::File::Api::appendFile	(	const char *	srcName,
		const char *	destFile
	)

static

Appends the context of the 'srcName' file to the specified 'dstName' file.

Returns true if successful. NOTE: Obviously this method will fail if both names are NOT files.

◆ canonicalPath()

static bool Cpl::Io::File::Api::canonicalPath	(	const char *	relPath,
		Cpl::Text::String &	absPath
	)

static

This method expands the relative path name in 'relPath' to its 'absPath'.

Returns true if successful, else false if an error occurred (bad relative path, not enough buffer space to hold the complete path, etc.)

◆ copyFile()

static bool Cpl::Io::File::Api::copyFile	(	const char *	srcName,
		const char *	dstName
	)

static

Copies the context of the 'srcName' file to the specified 'dstName' file.

Returns true if successful. NOTE: Obviously this method will fail if both names are NOT files.

◆ createDirectory()

static bool Cpl::Io::File::Api::createDirectory ( const char * dirName )

static

Creates the 'dirName' as a directory.

The parent directory must exist. Returns true if successful.

◆ createFile()

static bool Cpl::Io::File::Api::createFile ( const char * fileName )

static

Creates the 'fileName' as an empty file.

The parent directory must exist. Returns true if successful.

◆ directorySep()

static char Cpl::Io::File::Api::directorySep ( )

inlinestatic

Standardized Directory separator.

◆ dos2unix()

static const char * Cpl::Io::File::Api::dos2unix ( const char * fsEntryName )

static

This method converts the DOS directory separator to the UNIX directory separator.

The scope of the returned value is limited, i.e. the value needs to be consumed BEFORE any other call to this interface and/or methods in the Cpl::Io::File* namespaces. Note: This method IS thread safe in that each thread has it own internal storage that is used for the translation.

◆ exists()

static bool Cpl::Io::File::Api::exists ( const char * fsEntryName )

static

Returns true if the File Entry exists physically exists in the OS's file system.

◆ getCwd()

static bool Cpl::Io::File::Api::getCwd ( Cpl::Text::String & cwd )

static

This method returns the canonical/absolute path of the current working directory.

Returns true if successful, else false if an error occurred (not enough buffer space to hold the path, etc.).

◆ getInfo()

static bool Cpl::Io::File::Api::getInfo	(	const char *	fsEntryName,
		Info &	infoOut
	)

static

Returns information about the file system entry.

If there is any error, the function returns false; else true is returned.

◆ getNative()

static const char * Cpl::Io::File::Api::getNative ( const char * fsEntryName )

static

Returns the file system entry name in its in native format.

The scope of the returned value is limited, i.e. the value needs to be consumed BEFORE any other call to this interface and/or methods in the Cpl::Io::File* namespaces. Note: This method IS thread safe in that each thread has it own internal storage that is used for the translation.

◆ getStandard()

static const char * Cpl::Io::File::Api::getStandard ( const char * fsEntryName )

static

Returns the file system entry name in the 'Standard' format.

The scope of the returned value is limited, i.e. the value needs to be consumed BEFORE any other call to this interface and/or methods in the Cpl::Io::File* namespaces. Note: This method IS thread safe in that each thread has it own internal storage that is used for the translation.

◆ getWorkBuffer()

static Cpl::Text::String & Cpl::Io::File::Api::getWorkBuffer ( void )

staticprotected

Helper method. Returns an internal work buffer large enough to 'max path'.

◆ isDirectory()

static bool Cpl::Io::File::Api::isDirectory ( const char * fsEntryName )

static

Returns true if the File Entry is a directory.

◆ isFile()

static bool Cpl::Io::File::Api::isFile ( const char * fsEntryName )

static

Returns true if the File Entry is a file.

◆ isReadable()

static bool Cpl::Io::File::Api::isReadable ( const char * fsEntryName )

static

Return true if the user has read permission for the file system entry.

◆ isWriteable()

static bool Cpl::Io::File::Api::isWriteable ( const char * fsEntryName )

static

Return true if the user has write permission for the file system entry.

◆ moveFile()

static bool Cpl::Io::File::Api::moveFile	(	const char *	oldFileName,
		const char *	newFileName
	)

static

Moves and/or renames the specified file.

The method returns true if successful; else false is returned. When false is returned the state of the 'srcName' and 'dstName' files is undetermined (more specifically the state of files of failed moveFile() command is platform specific).

NOTE: This method can NOT be used to move directories.

◆ nativeDirectorySep()

static char Cpl::Io::File::Api::nativeDirectorySep ( )

inlinestatic

Returns the native Directory separator.

◆ remove()

static bool Cpl::Io::File::Api::remove ( const char * fsEntryName )

static

Deletes the file system entry from the OS's file system.

If the entry is an directory, the directory must be empty before it is deleted.
Returns true if successful.

◆ renameInPlace()

static bool Cpl::Io::File::Api::renameInPlace	(	const char *	oldName,
		const char *	newName
	)

static

Renames the file system entry name in the OS's file system.

NOTE: This is NOT a general purpose 'move' that can change the path as well as the name. This method only effects the entry's name ->no changes to its path is made. Returns true if successful.

◆ size()

static unsigned long Cpl::Io::File::Api::size ( const char * fsEntryName )

static

Returns the size, in bytes, of the file.

If the File Entry is not a file or an error occurs, then 0 is returned.

◆ split()

static void Cpl::Io::File::Api::split	(	const char *	fsEntryName,
		Cpl::Text::String *	fullPath,
		Cpl::Text::String *	drive,
		Cpl::Text::String *	path,
		Cpl::Text::String *	fullName,
		Cpl::Text::String *	name,
		Cpl::Text::String *	extension,
		char	dirSeparator = `directorySep()`,
		char	extensionSeparator = `'.'`,
		char	driveSeparator = `':'`
	)

static

This method breaks the specified File System Entry name into it's individual components.

If the specific component is not need, then specify 0 as the argument and it will be skipped. The fullPath argument contains the drive+path. Path only contains the path. The fullName argument contains the file name+extension.
Name only contains the file name. On return, fullPath string (if specified and drive exists) will contain the driver separator. The drive string will NOT 'include' the drive separator. The fullName parameter will contain the extensionSeperator. The name and extension will NOT 'include' the extensionSeperator.

Note: 'fullPath' and 'path' WILL contain the trailing directory separator.

◆ splitDrive()

static void Cpl::Io::File::Api::splitDrive	(	const char *	fsEntryName,
		Cpl::Text::String &	drive,
		char	driveSeparator = `':'`
	)

inlinestatic

Extracts the drive letter from the complete name.

The drive letter will NOT contain the drive separator character.

◆ splitExtension()

static void Cpl::Io::File::Api::splitExtension	(	const char *	fsEntryName,
		Cpl::Text::String &	extension,
		char	dirSeparator = `directorySep()`,
		char	extensionSeparator = `'.'`,
		char	driveSeparator = `':'`
	)

inlinestatic

Extracts the file extension from the complete name.

◆ splitFullname()

static void Cpl::Io::File::Api::splitFullname	(	const char *	fsEntryName,
		Cpl::Text::String &	fullname,
		char	dirSeparator = `directorySep()`,
		char	extensionSeparator = `'.'`,
		char	driveSeparator = `':'`
	)

inlinestatic

Extracts the full file name (name+extension) from the complete name.

◆ splitFullpath()

static void Cpl::Io::File::Api::splitFullpath	(	const char *	fsEntryName,
		Cpl::Text::String &	fullpath,
		char	dirSeparator = `directorySep()`,
		char	extensionSeparator = `'.'`,
		char	driveSeparator = `':'`
	)

inlinestatic

Extracts the full path (drive+path) from the complete name.

◆ splitFullpathFullName()

static void Cpl::Io::File::Api::splitFullpathFullName	(	const char *	fsEntryName,
		Cpl::Text::String &	fullpath,
		Cpl::Text::String &	fullname,
		char	dirSeparator = `directorySep()`,
		char	extensionSeparator = `'.'`,
		char	driveSeparator = `':'`
	)

inlinestatic

Extracts the full path and name from the complete name.

◆ splitName()

static void Cpl::Io::File::Api::splitName	(	const char *	fsEntryName,
		Cpl::Text::String &	name,
		char	dirSeparator = `directorySep()`,
		char	extensionSeparator = `'.'`,
		char	driveSeparator = `':'`
	)

inlinestatic

Extracts the file name from the complete name.

◆ splitPath()

static void Cpl::Io::File::Api::splitPath	(	const char *	fsEntryName,
		Cpl::Text::String &	path,
		char	dirSeparator = `directorySep()`,
		char	extensionSeparator = `'.'`,
		char	driveSeparator = `':'`
	)

inlinestatic

Extracts the path (no drive) from the complete name.

◆ timeModified()

static time_t Cpl::Io::File::Api::timeModified ( const char * fsEntryName )

static

Returns the time/date the file entry was last modified.

If an error occurred, then ((time_t)-1) is returned.

◆ unix2dos()

static const char * Cpl::Io::File::Api::unix2dos ( const char * fsEntryName )

static

This method converts the UNIX directory separator to the DOS directory separator.

The scope of the returned value is limited, i.e. the value needs to be consumed BEFORE any other call to this interface and/or methods in the Cpl::Io::File* namespaces. Note: This method IS thread safe in that each thread has it own internal storage that is used for the translation.

◆ walkDirectory()

static bool Cpl::Io::File::Api::walkDirectory	(	const char *	dirToList,
		DirectoryWalker &	callback,
		int	depth = `1`,
		bool	filesOnly = `false`,
		bool	dirsOnly = `false`
	)

static

This method allows the caller to walk the contents of the 'dirToList' directory (assuming the entry is a directory).

The default behavior is to list only the current directory. The Caller can override the depth of the traversal. Also, by default only the file name without its path is returned. The caller can optionally have the traverse call only return the name of files (omitting any directory names found) OR names of directories (omitting any file names found). Returns true when successfully and the entire traversal complete; else false is return if their is an error (e.g. 'dirToList' is a file or does not exist) or the 'walker' aborted the traversal.

NOTE: The is no guaranteed order to the traversal, only that all items per the specified depth will be traversed.

WARNING: On most platforms, the underlying OS calls dynamically allocate memory. The OS clean-up after itself but there still is the risk of failure do to lack of memory. Memory failures are handled silently - but will not crash traversal.

WARNING: Be careful when recursing into subdirectories. There are typically OS limits on how many directories may be 'opened'.
Extremely deep directory trees run the risk of exceeding these limits.

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

Cpl/Io/File/Api.h

Detailed Description

Classes

Static Public Member Functions

Static Protected Member Functions

Class Documentation

◆ Cpl::Io::File::Api::Info

Member Function Documentation

◆ appendFile()

◆ canonicalPath()

◆ copyFile()

◆ createDirectory()

◆ createFile()

◆ directorySep()

◆ dos2unix()

◆ exists()

◆ getCwd()

◆ getInfo()

◆ getNative()

◆ getStandard()

◆ getWorkBuffer()

◆ isDirectory()

◆ isFile()

◆ isReadable()

◆ isWriteable()

◆ moveFile()

◆ nativeDirectorySep()

◆ remove()

◆ renameInPlace()

◆ size()

◆ split()

◆ splitDrive()

◆ splitExtension()

◆ splitFullname()

◆ splitFullpath()

◆ splitFullpathFullName()

◆ splitName()

◆ splitPath()

◆ timeModified()

◆ unix2dos()

◆ walkDirectory()