FILEPATH Class Reference

System file and directory services class. More...

#include <mi32/filepath.h>

List of all members.

Public Types

enum  CHILDTYPE { CHILDTYPE_Directory = 1, CHILDTYPE_File }
enum  FILESYSTYPE {
  FILESYSTYPE_Unknown, FILESYSTYPE_NoRootDir, FILESYSTYPE_Removable, FILESYSTYPE_Fixed,
  FILESYSTYPE_Network, FILESYSTYPE_CDROM, FILESYSTYPE_RamDisk, FILESYSTYPE_Tape,
  FILESYSTYPE_URL
}
enum  PATHTYPE {
  PATHTYPE_Current = 0, PATHTYPE_Home = 1, PATHTYPE_ExecutableFile = 2, PATHTYPE_Desktop = 3,
  PATHTYPE_Font = 4, PATHTYPE_InstallationFolder = 7, PATHTYPE_ExecutableFolder = 8, PATHTYPE_Documents_AllUsers = 9,
  PATHTYPE_MicroImages_Shared = 10, PATHTYPE_Documents_CurrentUser = 11, PATHTYPE_MicroImages_User = 12, PATHTYPE_Settings_CurInst_CurUser = 13,
  PATHTYPE_Settings_CurInst_AllUsers = 14, PATHTYPE_Settings_AllInst_CurUser = 15, PATHTYPE_Settings_AllInst_AllUsers = 16, PATHTYPE_MicroImages_Logs = 17
}
enum  PERMISSION {
  PERMISSION_Invalid = 0, PERMISSION_Exists = 1, PERMISSION_Read = 2, PERMISSION_Write = 3,
  PERMISSION_ReadWrite = 4, PERMISSION_Execute = 5
}
typedef ERRVALUE(* StatusCallback )(INT64 FileSize, INT64 BytesLeft, void *udata)

Public Member Functions

FILEPATHAppend (const char *q, CHAR_ENCODING encoding)
FILEPATHAssign (const char *p, CHAR_ENCODING encoding=CHAR_ENCODING_ASCII)
ERRVALUE CheckAccess (const PERMISSION perm=PERMISSION_Read) const
void Clear ()
bool Contains (const FILEPATH &SubPath) const
ERRVALUE CopyFileFrom (const FILEPATH &SourcePath, StatusCallback StatusCB=0, void *udata=0) const
bool Exists () const
 FILEPATH (void *IniHandle, const char *group, const char *field)
 FILEPATH (const char *p, CHAR_ENCODING encoding=CHAR_ENCODING_ASCII)
 FILEPATH (const UNICODE *p)
 FILEPATH (const MISTRING &p)
 FILEPATH (PATHTYPE type)
 FILEPATH (const FILEPATH &dir, const char *name, CHAR_ENCODING encoding=CHAR_ENCODING_ASCII)
 FILEPATH (const FILEPATH &dir, const UNICODE *name)
 FILEPATH (const FILEPATH &dir, const MISTRING &name)
 FILEPATH (const FILEPATH &p)
 FILEPATH ()
char * GenerateEncodedOSPath () const
ERRVALUE GenerateTempFile (const FILEPATH &BasePath, const MISTRING &Basename)
INT64 GetAvailableSpace () const
int GetChildren (MISTRINGLIST &ChildList, const MISTRING &pattern, CHILDTYPE ChildType) const
int GetChildren (MISTRINGLIST &ChildList, CHILDTYPE ChildType) const
int GetComponents (MISTRINGLIST &CompList) const
MISTRING GetDisplay () const
MISTRING GetEncoded () const
MISTRING GetExtension () const
FILESYSTYPE GetFileSysType () const
MISTRING GetMioPath () const
MISTRING GetName () const
MISTRING GetNameOnly () const
MISTRING GetOSPath () const
FILEPATH GetPathOnly () const
PERMISSION GetPermission () const
MISTRING GetQuotedPath () const
MISTRING GetRelativePath (const PATHTYPE ft=PATHTYPE_Current) const
MISTRING GetRelativePath (const FILEPATH &BasePath) const
INT64 GetSize () const
INT64 GetSystemMaxSize () const
ERRVALUE GetTimeCreated (time_t *rettime) const
ERRVALUE GetTimeModified (time_t *rettime) const
bool HasChildren (CHILDTYPE ChildType) const
bool HasExtension () const
bool IniRead (void *IniHandle, const char *group, const char *field)
void IniWrite (void *IniHandle, const char *group, const char *field) const
bool IsChildPath (const FILEPATH &BasePath) const
bool IsEmpty () const
bool IsEqual (const FILEPATH &TestPath) const
bool IsFile () const
bool IsFolder () const
bool IsLessThan (const FILEPATH &TestPath) const
bool IsPathOnly () const
bool IsReadable () const
bool IsRootOnly () const
bool IsSameExtn (const MISTRING &extn) const
bool IsSameExtn (const char *extn) const
bool IsUNCHostOnly () const
bool IsUNCRoot () const
bool IsWritable () const
ERRVALUE Make (bool MakeTree=false) const
FILEPATHoperator+= (const char *q)
FILEPATHoperator+= (const UNICODE *q)
FILEPATHoperator+= (const MISTRING &q)
FILEPATHoperator= (const UNICODE *q)
FILEPATHoperator= (const MISTRING &q)
FILEPATHoperator= (const FILEPATH &q)
ERRVALUE Remove () const
ERRVALUE Rename (const FILEPATH &newname) const
ERRVALUE Rename (const MISTRING &newname)
FILEPATHReplaceRoot (const FILEPATH &SourcePath)
bool SearchCase ()
bool SearchIterative (const FILEPATH &RefPath)
FILEPATHSetExtension (const char *extn, CHAR_ENCODING encoding=CHAR_ENCODING_ASCII)
FILEPATHSetExtension (const MISTRING &extn)
FILEPATHSetName (const char *name, CHAR_ENCODING encoding=CHAR_ENCODING_ASCII)
FILEPATHSetName (const MISTRING &name)
ERRVALUE SetPermission (PERMISSION perm) const
void SetSystemPath (PATHTYPE pt)
ERRVALUE SetTimeCreated (time_t value) const
ERRVALUE SetTimeCreated (const tm *const timeval) const
ERRVALUE SetTimeModified (time_t value) const
ERRVALUE SetTimeModified (const tm *const timeval) const
FILEPATHStripExtension ()
FILEPATHStripLastComponent ()
FILEPATHStripToExisting ()
FILEPATHStripToFolder ()
FILEPATHStripToRoot ()
 ~FILEPATH ()

Static Public Member Functions

MISTRING ConvertNameToDisplay (const MISTRING &name)
int GetDriveList (MISTRINGLIST &DriveList)
bool GetEnvPath (const char *name, MISTRING &EnvPathStr)
bool IsRelativePath (const UNICODE *path)
void SetModuleFileName (const char *name, CHAR_ENCODING encoding)


Detailed Description

System file and directory services class.

Definition at line 168 of file filepath.h.


Member Typedef Documentation

typedef ERRVALUE(* FILEPATH::StatusCallback)(INT64 FileSize, INT64 BytesLeft, void *udata)
 

Definition at line 171 of file filepath.h.


Member Enumeration Documentation

enum FILEPATH::CHILDTYPE
 

Type of children to select in GetChildren calls.

Enumeration values:
CHILDTYPE_Directory 
CHILDTYPE_File 

Definition at line 221 of file filepath.h.

enum FILEPATH::FILESYSTYPE
 

File system types as can be determined.

Enumeration values:
FILESYSTYPE_Unknown 
FILESYSTYPE_NoRootDir  Win32.
FILESYSTYPE_Removable  Zip, Jaz, ...
FILESYSTYPE_Fixed 
FILESYSTYPE_Network 
FILESYSTYPE_CDROM  Read only file systems.
FILESYSTYPE_RamDisk 
FILESYSTYPE_Tape 
FILESYSTYPE_URL 

Definition at line 184 of file filepath.h.

enum FILEPATH::PATHTYPE
 

Common file path types.

Enumeration values:
PATHTYPE_Current  Current system path, usually same as installation folder.
PATHTYPE_Home  Users home directory if it exists.
PATHTYPE_ExecutableFile  Path to the executable file.
PATHTYPE_Desktop 
PATHTYPE_Font 
PATHTYPE_InstallationFolder  Folder where product is "installed".
PATHTYPE_ExecutableFolder  Folder containing current process executable.
PATHTYPE_Documents_AllUsers  All-users "Documents" folder.
PATHTYPE_MicroImages_Shared  Shared "MicroImages" folder.
PATHTYPE_Documents_CurrentUser  Current-user "Documents" folder.
PATHTYPE_MicroImages_User  Current-user "MicroImages" folder.
PATHTYPE_Settings_CurInst_CurUser  Settings for current 'installation', current user.
PATHTYPE_Settings_CurInst_AllUsers  Settings for current 'installation', all users.
PATHTYPE_Settings_AllInst_CurUser  Settings for all 'installations', current user.
PATHTYPE_Settings_AllInst_AllUsers  Settings for all 'installations', all users.
PATHTYPE_MicroImages_Logs  Place to put log files (same as MicroImages_User except on Macs where it's (HOME)/Logs/MicroImages.

Definition at line 197 of file filepath.h.

enum FILEPATH::PERMISSION
 

Possible file permissions to set or check for.

Enumeration values:
PERMISSION_Invalid 
PERMISSION_Exists 
PERMISSION_Read 
PERMISSION_Write 
PERMISSION_ReadWrite 
PERMISSION_Execute 

Definition at line 174 of file filepath.h.


Constructor & Destructor Documentation

FILEPATH::FILEPATH  ) 
 

Default constructor, empty path.

FILEPATH::FILEPATH const FILEPATH p  ) 
 

Copy constructor.

FILEPATH::FILEPATH const FILEPATH dir,
const MISTRING name
 

Concatenation constructor, 'dir' must be a directory.

FILEPATH::FILEPATH const FILEPATH dir,
const UNICODE name
 

Concatenation constructor, 'dir' must be a directory.

FILEPATH::FILEPATH const FILEPATH dir,
const char *  name,
CHAR_ENCODING  encoding = CHAR_ENCODING_ASCII
 

Concatenation constructor, 'dir' must be a directory.

FILEPATH::FILEPATH PATHTYPE  type  )  [explicit]
 

Constructor, inialize with a system path.

FILEPATH::FILEPATH const MISTRING p  )  [explicit]
 

Constructor, initialize with MISTRING.

FILEPATH::FILEPATH const UNICODE p  ) 
 

Constructor, initialize with UNICODE*, for compatibility.

FILEPATH::FILEPATH const char *  p,
CHAR_ENCODING  encoding = CHAR_ENCODING_ASCII
[explicit]
 

Constructor, initialize with C string, for efficiency.

FILEPATH::FILEPATH void *  IniHandle,
const char *  group,
const char *  field
 

Initialize a FILEPATH with an entry from an INI file.

Parameters:
IniHandle  Handle to INI file to read from, 0 for default file "tntproc.ini"
group  INI group to read path from
field  INI field to read path from

FILEPATH::~FILEPATH  ) 
 

Destructor.


Member Function Documentation

FILEPATH& FILEPATH::Append const char *  q,
CHAR_ENCODING  encoding
 

Append a string to FILEPATH, adding separator.

Parameters:
q  String to append with
encoding  Encoding of the string

FILEPATH& FILEPATH::Assign const char *  p,
CHAR_ENCODING  encoding = CHAR_ENCODING_ASCII
 

Assign a character string representation of a path to FILEPATH using the character encoding.

Returns:
Reference to 'this'

ERRVALUE FILEPATH::CheckAccess const PERMISSION  perm = PERMISSION_Read  )  const
 

Check access permissions on the file / directory.

Returns:
0 if access permitted, < 0 if error or EFileNotFound
Parameters:
perm  Access permission to check for

void FILEPATH::Clear  ) 
 

Clear the path representation.

bool FILEPATH::Contains const FILEPATH SubPath  )  const
 

Check if path contains "subpath" given.

Parameters:
SubPath  Subpath to check against

MISTRING FILEPATH::ConvertNameToDisplay const MISTRING name  )  [static]
 

Convert component OS filename passed in to a displayable filename.

Only has an effect on MAC_OSX where the colon ':' is transposed to a slash '/' when displaying

ERRVALUE FILEPATH::CopyFileFrom const FILEPATH SourcePath,
StatusCallback  StatusCB = 0,
void *  udata = 0
const
 

Copy contents from SourcePath.

Parameters:
SourcePath  Source file to ccopy from
StatusCB  Callback to report file copy status
udata  Callback data passed to status callback

bool FILEPATH::Exists  )  const
 

Check if file exists.

char* FILEPATH::GenerateEncodedOSPath  )  const
 

Generate Operating system specific path with the proper encoding for character based IO calls.

Use this method to call functions that take a path ONLY if nothing else can be done and it is a third party library. It is not known if the third party library can handle the multiple encodings if they manipulate the path.

Returns:
Encoded OS filepath, Caller MUST free.

ERRVALUE FILEPATH::GenerateTempFile const FILEPATH BasePath,
const MISTRING Basename
 

Generate a temp file given a basepath and a basename for the temp file Called by FILEFIND::MakeTempFile().

INT64 FILEPATH::GetAvailableSpace  )  const
 

Returns the amount of free space on the volume that the path represents.

int FILEPATH::GetChildren MISTRINGLIST ChildList,
const MISTRING pattern,
CHILDTYPE  ChildType
const
 

Obtain a list of child directories or files that exist under this path using a pattern to select which children to find.

Returns:
Number of children found.
Parameters:
ChildList  List of child names found after search
pattern  Pattern to match
ChildType  Type of children to search for CHILDTYPE_Directory or CHILDTYPE_File.

int FILEPATH::GetChildren MISTRINGLIST ChildList,
CHILDTYPE  ChildType
const
 

Obtain a list of child directories or files that exist under this path.

Returns:
Number of children found.
Parameters:
ChildList  List of child names found after search
ChildType  Type of children to search for CHILDTYPE_Directory or CHILDTYPE_File.

int FILEPATH::GetComponents MISTRINGLIST CompList  )  const
 

Separate path into individual components, returns number of components.

Parameters:
CompList  List of components RETURNED

MISTRING FILEPATH::GetDisplay  )  const
 

Get the display string representation for the path.

Used to get a string that is to be displayed to the end user.

int FILEPATH::GetDriveList MISTRINGLIST DriveList  )  [static]
 

Determine list of drives / volumes for this OS.

MISTRING FILEPATH::GetEncoded  )  const
 

Get the encoded string representation for the path.

Used to get a string that is to be saved to a database / file for later retrieval. The encoding is used in the case of file transfer to different system types, Eg UNIX -> WIN32 or MAC -> WIN32 or any other combination.

bool FILEPATH::GetEnvPath const char *  name,
MISTRING EnvPathStr
[static]
 

Get an environment variable as a path (or paths) and convert using the correct OS encoding.

MISTRING FILEPATH::GetExtension  )  const
 

Get the file name extension, without the extension marker.

The extension is considered to be the string after the last extension marker. Eg. in "test.rvc.txt", 'txt' would be the extension returned.

FILESYSTYPE FILEPATH::GetFileSysType  )  const
 

Get type of system drive the path represents.

Returns:
Type of system drive the path represents.

MISTRING FILEPATH::GetMioPath  )  const
 

Get the Mio...() encoded string representation for the path.

Used in legacy code where the function requires a const UNICODE* string.

MISTRING FILEPATH::GetName  )  const
 

Get the last component name (file or folder) with extension (if exists).

Returns:
Last component name

MISTRING FILEPATH::GetNameOnly  )  const
 

Get the file name only, no extension, unless directory.

A directory is not considered to have an extension, therefore if this path represents a directory, the name with extension is returned.

MISTRING FILEPATH::GetOSPath  )  const
 

Get the OS string representation for the path.

Used to generate valid path string for use in OS-specific file I/O functions. Does not insert quotes around components containing spaces. Note, you probably really want GenerateEncodedOSPath() which will convert the filename to the character encoding of the file system

See also:
GetQuotedPath, GenerateEncodedOSPath

FILEPATH FILEPATH::GetPathOnly  )  const
 

Get the path representation only.

PERMISSION FILEPATH::GetPermission  )  const
 

Get access permissions on the file / directory.

MISTRING FILEPATH::GetQuotedPath  )  const
 

Get path with quotes inserted around components containing spaces.

Used to generate a valid string to use command lines.

See also:
GetOSPath

MISTRING FILEPATH::GetRelativePath const PATHTYPE  ft = PATHTYPE_Current  )  const
 

Generate an encoded relative path from a system default path.

Returns:
Relative path string, see other GetRelativePath() for complete docs

MISTRING FILEPATH::GetRelativePath const FILEPATH BasePath  )  const
 

Generate an encoded relative path from a source path.

The string returned will be one of three types: 1. A string == ".", the current path and the source path are equal 2. An encoded string from GetEncoded() method, the two paths are completely unrelated 3. An encoded string with the relative path.

See also IsRelativePath().

Returns:
Relative path string
Parameters:
BasePath  Base path which the instance is compared to and the relative path is generated against

INT64 FILEPATH::GetSize  )  const
 

Return size of the file.

INT64 FILEPATH::GetSystemMaxSize  )  const
 

Return maximum size of a file on the drive represented.

ERRVALUE FILEPATH::GetTimeCreated time_t *  rettime  )  const
 

Get the creation time for the file.

Parameters:
rettime  UTC time

ERRVALUE FILEPATH::GetTimeModified time_t *  rettime  )  const
 

Get the modification time for the file.

Parameters:
rettime  UTC time

bool FILEPATH::HasChildren CHILDTYPE  ChildType  )  const
 

Does the path have children of a specific type?

Returns:
"True' if children of the correct type found
Parameters:
ChildType  Type of children to search for CHILDTYPE_Directory or CHILDTYPE_File.

bool FILEPATH::HasExtension  )  const
 

Does the Name part of the path have an extension?

bool FILEPATH::IniRead void *  IniHandle,
const char *  group,
const char *  field
 

Initialize a FILEPATH with an entry from an INI file.

Returns:
'true' if the entry exists.
Parameters:
IniHandle  Handle to INI file to read from, 0 for default file "tntproc.ini"
group  INI group to read path from
field  INI field to read path from

void FILEPATH::IniWrite void *  IniHandle,
const char *  group,
const char *  field
const
 

Write encoded filepath to .ini file.

Parameters:
IniHandle  Handle to INI file to write to, 0 for default file "tntproc.ini"
group  INI group to write encoded path to
field  INI field to write encoded path to

bool FILEPATH::IsChildPath const FILEPATH BasePath  )  const
 

Is the path a child path of 'BasePath'.

bool FILEPATH::IsEmpty  )  const
 

Is FILEPATH empty?

bool FILEPATH::IsEqual const FILEPATH TestPath  )  const
 

Are the paths equal?

Case insensitive check for WIN32, MAC.

bool FILEPATH::IsFile  )  const
 

Is FILEPATH an existing file?

bool FILEPATH::IsFolder  )  const
 

Is FILEPATH an existing folder (directory)?

bool FILEPATH::IsLessThan const FILEPATH TestPath  )  const
 

Is "this" less than testpath?

Case insensitive check for WIN32, MAC.

bool FILEPATH::IsPathOnly  )  const
 

Is the file referenced a directory?

A non-existant path is a directory.

bool FILEPATH::IsReadable  )  const
 

Is the path / file readable?

bool FILEPATH::IsRelativePath const UNICODE path  )  [static]
 

Is the string given specify a relative path.

A string is considered a relative path if: 1. The string is empty or the string == "." 2. The string starts with a relative path indicator specific for the platform On all but the MAC, the string can start with either the same directory relative path or the parent directory relative path. The MAC does not have a current directory relative path.

Example: if (FILEPATH::IsRelativePath(RelStr)) { FilePath = BasePath; // Assign base path to dest FilePath += RelStr; // Concatinate relative path onto dest } else { FilePath = RelStr; // Full path, assign to dest }

Returns:
'true' if path is a relative path, false if not
Parameters:
path  String to determine if a relative path

bool FILEPATH::IsRootOnly  )  const
 

Is the path a root path?

bool FILEPATH::IsSameExtn const MISTRING extn  )  const
 

Does the filepath have the same extension as that passed in This method is used to speed up extension checking without creating one or two MISTRINGs This method uses no-case comparisons.

Returns:
True if extensions match or if path has no extension and '0' or "" is passed for 'extn'
Parameters:
extn  Do not prepend extension marker '.'

bool FILEPATH::IsSameExtn const char *  extn  )  const
 

Does the filepath have the same extension as that passed in This method is used to speed up extension checking without creating one or two MISTRINGs This method uses no-case comparisons.

Returns:
True if extensions match or if path has no extension and '0' or "" is passed for 'extn'
Parameters:
extn  Do not prepend extension marker '.'

bool FILEPATH::IsUNCHostOnly  )  const
 

Is the path a UNC host path only? (\Machine).

\

bool FILEPATH::IsUNCRoot  )  const
 

Is the path a UNC root path? (\Machine\share).

\

bool FILEPATH::IsWritable  )  const
 

Is the path / file writable?

(Writable is correct spelling).

ERRVALUE FILEPATH::Make bool  MakeTree = false  )  const
 

Creates a path, returns 0 if path was created or existed, < 0 if error.

If true, will create all non-existant directories listed in its path.

FILEPATH& FILEPATH::operator+= const char *  q  ) 
 

Concatenate from C string, for efficiency.

Parameters:
q  ASCII encoded string

FILEPATH& FILEPATH::operator+= const UNICODE q  ) 
 

Concatenate from UNICODE*, adding separator.

FILEPATH& FILEPATH::operator+= const MISTRING q  ) 
 

Concatenate from MISTRING, adding separator.

FILEPATH& FILEPATH::operator= const UNICODE q  ) 
 

Assignment from UNICODE*.

FILEPATH& FILEPATH::operator= const MISTRING q  ) 
 

Assignment from MISTRING.

FILEPATH& FILEPATH::operator= const FILEPATH q  ) 
 

Assignment operator.

ERRVALUE FILEPATH::Remove  )  const
 

Remove a file from the system, does not remove directories.

ERRVALUE FILEPATH::Rename const FILEPATH newname  )  const
 

Rename an existing file with a new name extracted from 'newname', FILEPATH not changed.

Parameters:
newname  Name to change to, path is ignored

ERRVALUE FILEPATH::Rename const MISTRING newname  ) 
 

Rename an existing file with a new name, FILEPATH changed after sucessful operation.

Parameters:
newname  Name to change to

FILEPATH& FILEPATH::ReplaceRoot const FILEPATH SourcePath  ) 
 

Replace root of the path with a new root.

Parameters:
SourcePath  Path that contains new root path

bool FILEPATH::SearchCase  ) 
 

Search for file by changing path case incrementally.

Returns:
"true" if found and FILEPATH will be modified.

bool FILEPATH::SearchIterative const FILEPATH RefPath  ) 
 

Search path for file using reference path iteratively.

Returns:
"true" if found and FILEPATH will be modified.

FILEPATH& FILEPATH::SetExtension const char *  extn,
CHAR_ENCODING  encoding = CHAR_ENCODING_ASCII
 

Set extension of the path.

FILEPATH& FILEPATH::SetExtension const MISTRING extn  ) 
 

Set extension of the path.

void FILEPATH::SetModuleFileName const char *  name,
CHAR_ENCODING  encoding
[static]
 

Set application executable name so that PATHTYPE_Executable for SetSystemPath() can work.

For UNIX systems only!

Parameters:
name  Name of executable (argv[0] for most systems)
encoding  String encoding (CHAR_ENCODING_ASCII for most systems)

FILEPATH& FILEPATH::SetName const char *  name,
CHAR_ENCODING  encoding = CHAR_ENCODING_ASCII
 

Replace FILEPATH name, overloaded for efficiency.

FILEPATH& FILEPATH::SetName const MISTRING name  ) 
 

Replace FILEPATH name.

ERRVALUE FILEPATH::SetPermission PERMISSION  perm  )  const
 

Set access permissions on the file / directory.

Parameters:
perm  Permission to set file / directory to

void FILEPATH::SetSystemPath PATHTYPE  pt  ) 
<