filepath.h

Go to the documentation of this file.

/****
 * \file mi32/filepath.h
 * \brief Class FILEPATH - Handle filenames (directories and files) on supported platforms
 *
 * Definitions:
 *              
 * Name - The string after the last directory separator (SepMark).
 * Extn - The string after the 'Name' separated by the last extension separator (ExtnMark)
 * Path - The string representing the entire directory path up to 'Name'.
 *
 * Implementation notes:
 *
 * This class is not thread safe.  Most of the time the instance is specific to a 
 *    thread therefore the resource sharing issues are not involved.  If this class is
 *    a shared resource, it is up to the user of the class to guard it using the 
 *    appropriate locking method.
 *
 * \if NODOC
 * $Id: filepath.h_v 1.53 2004/10/15 16:07:36 dwilliss Exp $
 *
 * $Log: filepath.h_v $
 * Revision 1.53  2004/10/15 16:07:36  dwilliss
 * Added new PATHTYPE for logs
 *
 * Revision 1.52  2003/10/03 20:46:58  dwilliss
 * Changed static member from an MISTRING to a poitner to MISTRING.
 *
 * Revision 1.51  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.50  2003/07/09 17:20:34  scowan
 * Removed mac 9 stuff and methods that are not used.
 *
 * Revision 1.49  2003/07/03 20:35:41  scowan
 * Removed mac native code.
 *
 * Revision 1.48  2003/06/18 19:31:35  scowan
 * Added convert name static method.
 *
 * Revision 1.47  2003/05/19 15:43:30  mju
 * Add pathtype_InstallationFolder.
 * Remove deprecated pathtype value.
 *
 * Revision 1.46  2003/05/16 17:50:54  mju
 * Add PATHTYPE_Settings values.
 *
 * Revision 1.45  2003/05/15 14:30:21  mju
 * Rename PATHTYPE_Documents enums.
 *
 * Revision 1.44  2003/02/25 22:48:57  mju
 * Make PATHTYPE names consistent and more complete and eliminate obsolete ones.
 *
 * Revision 1.43  2003/02/17 21:05:00  scowan
 * Added new path types.
 *
 * Revision 1.42  2003/02/13 23:22:52  scowan
 * Added static method.
 *
 * Revision 1.41  2002/11/20 16:39:40  mju
 * Add PATHTYPE_MicroImages.
 *
 * Revision 1.40  2002/09/09 16:05:28  mju
 * nc.
 *
 * Revision 1.39  2002/09/04 21:46:37  dwilliss
 * Just a see also on GetOSPath()
 *
 * Revision 1.38  2002/08/27 13:55:59  scowan
 * Allow set mac file type for osx.
 *
 * Revision 1.37  2002/08/21 15:52:38  scowan
 * Minor changes.
 *
 * Revision 1.36  2002/07/03 22:10:01  dwilliss
 * Work around stupid Mac problem with struct tm sometimes being std::tm
 *
 * Revision 1.35  2002/06/28 17:03:29  dwilliss
 * Damn Mac!  Can't get it to stop doing a "using std::tm"
 *
 * Revision 1.32  2002/06/17 14:24:50  mju
 * Remove 'struct' from use of 'tm' as not needed to hopefully fix MacOS9.
 *
 * Revision 1.30  2002/06/07 15:30:16  scowan
 * Added method to get encoded char poath.
 *
 * Revision 1.28  2002/03/27 17:04:38  mju
 * Add operator<< to put filepath 'display string' into MISTRING.
 *
 * Revision 1.27  2002/03/18 16:32:43  scowan
 * Added assign method.
 *
 * Revision 1.26  2002/01/16 18:13:39  scowan
 * Do stupid thing for MAC.
 *
 * Revision 1.25  2002/01/14 17:50:00  scowan
 * Limit use of set module filename to UNIX only.
 *
 * Revision 1.24  2002/01/14 16:29:45  scowan
 * Added strip to folder.
 *
 * Revision 1.23  2001/12/06 17:43:04  scowan
 * Added generate temp file method.
 *
 * Revision 1.22  2001/08/03 21:05:14  mju
 * Add GetQuotedPath implementing old GetOSPath() behavior.
 *
 * Revision 1.21  2001/05/03 19:43:28  scowan
 * Added Haschildren method().
 *
 * Revision 1.20  2001/03/14 15:23:48  scowan
 * Added set osd path for windows.
 *
 * Revision 1.18  2000/09/21 19:33:44  scowan
 * Added is same extn methods.
 *
 * Revision 1.16  2000/08/09 16:48:40  scowan
 * Updated relative path code.
 *
 * Revision 1.15  2000/08/08 13:39:10  mju
 * Don't have Genitor document "removed" and unimplemented methods.
 *
 * Revision 1.14  2000/07/19 16:13:10  scowan
 * Make cosnt versions of Get Relative Path and comment out old versions.
 *
 * Revision 1.13  2000/07/11 17:34:41  mju
 * Need to undef CLASSLIBEXPORT at end.
 *
 * Revision 1.12  2000/07/06 17:53:40  mju
 * Add IsFile and IsFolder methods.
 *
 * Revision 1.11  2000/06/13 14:20:48  mju
 * Use inclusion guards.
 *
 * \endif
****/

#ifndef  INC_MI32_FILEPATH_H
#define  INC_MI32_FILEPATH_H

#ifndef  INC_MI32_STDDEFNS_H
#include <mi32/stddefns.h>
#endif

#ifndef  INC_MI32_UCSTRING_H
#include <mi32/ucstring.h>
#endif

#ifndef  INC_MI32_MISTRING_H
#include <mi32/mistring.h>
#endif

#ifndef  INC_TIME_H
#include <time.h>
#define  INC_TIME_H
#endif

#ifdef MISYSTEMDLL
   #define CLASSLIBEXPORT MI_DLLCLASSEXPORT
#else
   #define CLASSLIBEXPORT MI_DLLCLASSIMPORT
#endif

#ifndef GENERATING_DOXYGEN_OUTPUT
class FILE_RAW;         // Forward declaration
#endif // GENERATING_DOXYGEN_OUTPUT

//! System file and directory services class.
class CLASSLIBEXPORT FILEPATH {     
   public:

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

      //! Possible file permissions to set or check for.
      enum PERMISSION {                   
         PERMISSION_Invalid = 0,
         PERMISSION_Exists = 1,
         PERMISSION_Read = 2,
         PERMISSION_Write = 3,
         PERMISSION_ReadWrite = 4,
         PERMISSION_Execute = 5
         };

      //! File system types as can be determined.
      enum FILESYSTYPE {                  
         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
         };

      //! Common file path types.
      enum PATHTYPE {
         PATHTYPE_Current = 0,                     //!< Current system path, usually same as installation folder
         PATHTYPE_Home = 1,                        //!< Users home directory if it exists
         PATHTYPE_ExecutableFile = 2,              //!< Path to the executable file
         PATHTYPE_Desktop = 3,
         PATHTYPE_Font = 4,
         #if defined(WIN32)
            PATHTYPE_Windows = 5,                  //!< Windows install path location
            PATHTYPE_WindowsSystem = 6,            //!< Windows system path location
         #endif
         PATHTYPE_InstallationFolder = 7,          //!< Folder where product is "installed"
         PATHTYPE_ExecutableFolder = 8,            //!< Folder containing current process executable
         PATHTYPE_Documents_AllUsers = 9,          //!< All-users "Documents" folder
         PATHTYPE_MicroImages_Shared = 10,         //!< Shared "MicroImages" folder
         PATHTYPE_Documents_CurrentUser = 11,      //!< Current-user "Documents" folder
         PATHTYPE_MicroImages_User = 12,           //!< Current-user "MicroImages" folder
         PATHTYPE_Settings_CurInst_CurUser = 13,   //!< Settings for current 'installation', current user
         PATHTYPE_Settings_CurInst_AllUsers = 14,  //!< Settings for current 'installation', all users
         PATHTYPE_Settings_AllInst_CurUser = 15,   //!< Settings for all 'installations', current user
         PATHTYPE_Settings_AllInst_AllUsers = 16,  //!< Settings for all 'installations', all users
         PATHTYPE_MicroImages_Logs = 17,           //!< Place to put log files (same as MicroImages_User except on Macs where it's (HOME)/Logs/MicroImages
         };

      //! Type of children to select in GetChildren calls.
      enum CHILDTYPE {                    
         CHILDTYPE_Directory = 1,
         CHILDTYPE_File
         };

      //! 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       
      static MISTRING ConvertNameToDisplay (
         const MISTRING& name
         );

      //! Determine list of drives / volumes for this OS.
      static int GetDriveList (           
         MISTRINGLIST& DriveList
         );

      //! Get an environment variable as a path (or paths) and convert using the correct OS encoding
      static bool GetEnvPath (            
         const char *name,
         MISTRING& EnvPathStr
         );
         
   #if 0
      #ifndef GENERATING_DOXYGEN_OUTPUT
      //! Get maximum amount of characters allowed for an operating system's path segment.
      //! @return The operating system's limit for a path segment / filename.
      static UINT32 GetNameSizeLimit (    
         );

      //! Get maximum amount of characters allowed for an operating system's full path.
      //!
      //! @return The operating system's limit for a full path.
      static UINT32 GetPathSizeLimit (    
         );
      #endif //!< GENERATING_DOXYGEN_OUTPUT
   #endif

      //! 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
      //!         }
      //!
      //! @return 'true' if path is a relative path, false if not
      static bool IsRelativePath (
         const UNICODE *path              //!< String to determine if a relative path
         );

      #if !defined(WIN32)
      //! Set application executable name so that PATHTYPE_Executable for SetSystemPath() can work.
      //! For UNIX systems only!
      static void SetModuleFileName (
         const char *name,                //!< Name of executable (argv[0] for most systems)
         CHAR_ENCODING encoding           //!< String encoding (CHAR_ENCODING_ASCII for most systems)
         );
      #endif

      //! Default constructor, empty path.
      FILEPATH (                       
         );

      //! Copy constructor.
      FILEPATH (                       
         const FILEPATH& p
         );

      //! Concatenation constructor, 'dir' must be a directory.
      FILEPATH (                       
         const FILEPATH& dir,
         const MISTRING& name
         );

      //! Concatenation constructor, 'dir' must be a directory.
      FILEPATH (                       
         const FILEPATH& dir,
         const UNICODE *name
         );

      //! Concatenation constructor, 'dir' must be a directory.
      FILEPATH (                       
         const FILEPATH& dir,
         const char *name,
         CHAR_ENCODING encoding = CHAR_ENCODING_ASCII
         );

      //! Constructor, inialize with a system path.
      explicit FILEPATH (                 
         PATHTYPE type
         );

      //! Constructor, initialize with MISTRING.
      explicit FILEPATH (                 
         const MISTRING& p
         );

      //! Constructor, initialize with UNICODE*, for compatibility.
      FILEPATH (                       
         const UNICODE *p
         );

      //! Constructor, initialize with C string, for efficiency.
      explicit FILEPATH (                 
         const char *p,
         CHAR_ENCODING encoding = CHAR_ENCODING_ASCII
         );

      //! Initialize a FILEPATH with an entry from an INI file.
      FILEPATH (                          
         void *IniHandle,                 //!< Handle to INI file to read from, 0 for default file "tntproc.ini"
         const char *group,               //!< INI group to read path from
         const char *field                //!< INI field to read path from
         );

      //! Destructor.
      ~FILEPATH (                         
         );

      //! Assignment operator.
      FILEPATH& operator= (               
         const FILEPATH& q
         );

      //! Assignment from MISTRING.
      FILEPATH& operator= (               
         const MISTRING& q
         );

      //! Assignment from UNICODE*.
      FILEPATH& operator= (               
         const UNICODE* q
         );

      //! Concatenate from MISTRING, adding separator.
      FILEPATH& operator+= (              
         const MISTRING& q
         );

      //! Concatenate from UNICODE*, adding separator.
      FILEPATH& operator+= (              
         const UNICODE* q
         );

      //! Concatenate from C string, for efficiency.
      FILEPATH& operator+= (              
         const char *q                    //!< ASCII encoded string
         );

      //! Append a string to FILEPATH, adding separator.
      FILEPATH& Append (                  
         const char *q,                   //!< String to append with
         CHAR_ENCODING encoding           //!< Encoding of the string
         );

      //! Assign a character string representation of a path to FILEPATH using the character encoding.
      //! @return Reference to 'this'
      FILEPATH& Assign (
         const char *p,
         CHAR_ENCODING encoding = CHAR_ENCODING_ASCII
         );
         
      //! Check access permissions on the file / directory. 
      //! @return 0 if access permitted, < 0 if error or EFileNotFound
      ERRVALUE CheckAccess (
         const PERMISSION perm = PERMISSION_Read      //!< Access permission to check for
         ) const;

      //! Clear the path representation.  
      void Clear (                     
         );

      //! Check if path contains "subpath" given.
      bool Contains (                     
         const FILEPATH& SubPath          //!< Subpath to check against
         ) const;

      //! Copy contents from SourcePath.
      ERRVALUE CopyFileFrom (             
         const FILEPATH& SourcePath,      //!< Source file to ccopy from
         StatusCallback StatusCB = 0,     //!< Callback to report file copy status
         void *udata = 0                  //!< Callback data passed to status callback
         ) const;

      //! Check if file exists.
      bool Exists (                    
         ) const;

      //! Generate a temp file given a basepath and a basename for the temp file
      //! Called by FILEFIND::MakeTempFile()
      ERRVALUE GenerateTempFile (
         const FILEPATH& BasePath,
         const MISTRING& Basename
         );
         
      //! 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.
      //! @return Encoded OS filepath, Caller MUST free.
      char* GenerateEncodedOSPath (
         ) const;

      //! Returns the amount of free space on the volume that the path represents.
      INT64 GetAvailableSpace (           
         ) const;

      //! Obtain a list of child directories or files that exist under this path.
      //! @return Number of children found.
      int GetChildren (
         MISTRINGLIST& ChildList,         //!< List of child names found after search
         CHILDTYPE ChildType              //!< Type of children to search for CHILDTYPE_Directory or CHILDTYPE_File.
         ) const;
      
      //! Obtain a list of child directories or files that exist under this path using a pattern to select which children to find.
      //! @return Number of children found.
      int GetChildren (
         MISTRINGLIST& ChildList,         //!< List of child names found after search
         const MISTRING& pattern,         //!< Pattern to match
         CHILDTYPE ChildType              //!< Type of children to search for CHILDTYPE_Directory or CHILDTYPE_File.
         ) const;

      //! Separate path into individual components, returns number of components.
      int GetComponents (
         MISTRINGLIST& CompList           //!< List of components RETURNED
         ) const;

      //! Get the display string representation for the path.
      //!
      //! Used to get a string that is to be displayed to the end user.
      MISTRING GetDisplay (
         ) 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.
      MISTRING GetEncoded (
         ) 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.
      MISTRING GetExtension (
         ) const;

      //! Get type of system drive the path represents.
      //! @return Type of system drive the path represents.
      FILESYSTYPE GetFileSysType (     
         ) const;

   #if defined(MAC_OSX)
      //! Obtain the Macintosh Creator and type fields based on the file extension.
      ERRVALUE GetMacFileType (       
         char *creator, 
         char *type
         ) const;
   #endif
      
      //! Get the Mio...() encoded string representation for the path.
      //! Used in legacy code where the function requires a const UNICODE* string.
      MISTRING GetMioPath (
         ) const;

      //! Get the last component name (file or folder) with extension (if exists).
      //! @return Last component name
      MISTRING GetName (                  
         ) 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 GetNameOnly (
         ) 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 GetQuotedPath, GenerateEncodedOSPath
      MISTRING GetOSPath (
         ) const;

      //! Get the path representation only.
      FILEPATH GetPathOnly (              
         ) const;

      //! Get access permissions on the file / directory.
      PERMISSION GetPermission (         
         ) const;

      //! Get path with quotes inserted around components containing spaces.
      //! Used to generate a valid string to use command lines.
      //! @see GetOSPath
      MISTRING GetQuotedPath (
         ) 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().   
      //!
      //! @return Relative path string
      MISTRING GetRelativePath (          
         const FILEPATH& BasePath      //!< Base path which the instance is compared to and the relative path is generated against
         ) const;

      //! Generate an encoded relative path from a system default path.
      //!
      //! @return Relative path string, see other GetRelativePath() for complete docs
      MISTRING GetRelativePath (
         const PATHTYPE ft = PATHTYPE_Current
         ) const;

      //! Return size of the file.
      INT64 GetSize (                     
         ) const;

      //! Return maximum size of a file on the drive represented.
      INT64 GetSystemMaxSize (            
         ) const;

      //! Get the creation time for the file.
      ERRVALUE GetTimeCreated (           
         time_t *rettime                  //!< UTC time
         ) const;

      //! Get the modification time for the file.
      ERRVALUE GetTimeModified (          
         time_t *rettime                  //!< UTC time
         ) const;

      //! Does the path have children of a specific type?
      //! @return "True' if children of the correct type found
      bool HasChildren (
         CHILDTYPE ChildType              //!< Type of children to search for CHILDTYPE_Directory or CHILDTYPE_File.
         ) const;
      
      //! Does the Name part of the path have an extension?
      bool HasExtension (                 
         ) const;

      //! Initialize a FILEPATH with an entry from an INI file.
      //! @return 'true' if the entry exists.
      bool IniRead (                   
         void *IniHandle,                 //!< Handle to INI file to read from, 0 for default file "tntproc.ini"
         const char *group,               //!< INI group to read path from
         const char *field                //!< INI field to read path from
         );

      //! Write encoded filepath to .ini file.
      void IniWrite (                     
         void *IniHandle,                 //!< Handle to INI file to write to, 0 for default file "tntproc.ini"
         const char *group,               //!< INI group to write encoded path to
         const char *field                //!< INI field to write encoded path to
         ) const;

      //! Is the path a child path of 'BasePath'
      bool IsChildPath (
         const FILEPATH& BasePath
         ) const;
      
      //! Is FILEPATH empty?
      bool IsEmpty (                   
         ) const;

      //! Are the paths equal?
      //!
      //! Case insensitive check for WIN32, MAC.
      bool IsEqual (                     
         const FILEPATH& TestPath
         ) const;

      //! Is FILEPATH an existing file?
      bool IsFile (
         ) const;

      //! Is FILEPATH an existing folder (directory)?
      bool IsFolder (
         ) const;

      //! Is "this" less than testpath?
      //!
      //! Case insensitive check for WIN32, MAC.
      bool IsLessThan (                  
         const FILEPATH& TestPath
         ) const;

      //! Is the file referenced a directory?
      //!
      //! A non-existant path is a directory.
      bool IsPathOnly (                  
         ) const;

      //! Is the path / file readable?
      bool IsReadable (                
         ) const;

      //! Is the path a root path?
      bool IsRootOnly (                
         ) 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
      //! @return True if extensions match or if path has no extension and '0' or "" is passed for 'extn'
      bool IsSameExtn (
         const char *extn        //!< Do not prepend extension marker '.'
         ) 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
      //! @return True if extensions match or if path has no extension and '0' or "" is passed for 'extn'
      bool IsSameExtn (
         const MISTRING& extn       //!< Do not prepend extension marker '.'
         ) const;

      // Note: back slashes in the comment below are doubled up for Doxygen
      //! Is the path a UNC host path only? (\\\\Machine).
      bool IsUNCHostOnly (             
         ) const;

      // Note: back slashes in the comment below are doubled up for Doxygen
      //! Is the path a UNC root path? (\\\\Machine\\share).
      bool IsUNCRoot (                 
         ) const;

      //! Is the path / file writable?
      //!
      //! (Writable is correct spelling).
      bool IsWritable (                   
         ) 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.
      ERRVALUE Make (                     
         bool MakeTree = false              
         ) const;

      //! Remove a file from the system, does not remove directories.
      ERRVALUE Remove (                
         ) const;

      //! Rename an existing file with a new name, FILEPATH changed after sucessful operation.
      ERRVALUE Rename (                
         const MISTRING& newname          //!< Name to change to
         );                                  

      //! Rename an existing file with a new name extracted from 'newname', FILEPATH not changed.
      ERRVALUE Rename (
         const FILEPATH& newname          //!< Name to change to, path is ignored
         ) const;

      //! Replace root of the path with a new root.
      FILEPATH& ReplaceRoot (             
         const FILEPATH& SourcePath       //!< Path that contains new root path
         );

      //! Search for file by changing path case incrementally.
      //! @return "true" if found and FILEPATH will be modified.
      bool SearchCase (
         );

      //! Search path for file using reference path iteratively.
      //! @return "true" if found and FILEPATH will be modified.
      bool SearchIterative (
         const FILEPATH& RefPath
         );

      //! Set extension of the path.
      FILEPATH& SetExtension (            
         const MISTRING& extn
         );

      //! Set extension of the path.
      FILEPATH& SetExtension (            
         const char* extn,
         CHAR_ENCODING encoding = CHAR_ENCODING_ASCII
         );
         
   #if defined(MAC_OSX)
      //! Set Macintosh file type based on creator and type fields.
      ERRVALUE SetMacFileType (        
         const char *creator, 
         const char *type
         ) const;
   #endif

      //! Replace FILEPATH name.
      FILEPATH& SetName (                 
         const MISTRING& name
         );

      //! Replace FILEPATH name, overloaded for efficiency.
      FILEPATH& SetName (                
         const char* name,
         CHAR_ENCODING encoding = CHAR_ENCODING_ASCII
         );

   #if defined(WIN32)
      //! Set the path from the OS string representation
      //!
      //! Used to set the path from a OS specific function
      void SetOSPath (
         const char* path
         );

      //! Set the path from the OS string representation
      //!
      //! Used to set the path from a OS specific function
      void SetOSPath (
         const UNICODE* path
         );
   #endif

      //! Set access permissions on the file / directory.
      ERRVALUE SetPermission (
         PERMISSION perm                  //!< Permission to set file / directory to
         ) const;

      //! Sets FILEPATH to a system path.
      void SetSystemPath (
         PATHTYPE pt                      //!< System path to set FILEPATH to
         );

      //! Change creation time for a file, if possible.
      ERRVALUE SetTimeCreated (
         const tm*const timeval     //!< UTC based time value
         ) const;

      //! Change creation time for a file, if possible.
      ERRVALUE SetTimeCreated (
         time_t value                     //!< UTC based time value
         ) const;

      //! Change modification time for a file, if possible.
      ERRVALUE SetTimeModified (
         const tm*const timeval     //!< UTC based time value
         ) const;

      //! Change modification time for a file, if possible.
      ERRVALUE SetTimeModified (
         time_t value                     //!< UTC based time value
         ) const;

      //! Strips the extension, if it exists, off of Name.
      FILEPATH& StripExtension (
         );

      //! Strips the last component off of the path.
      FILEPATH& StripLastComponent (
         );

      //! Strips off components until the remaining path exists.
      FILEPATH& StripToExisting (
         );

      //! Strips off components until the remaining folder path exists.
      FILEPATH& StripToFolder (
         );

      //! Strips everything off except the root path.
      FILEPATH& StripToRoot (
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      void AppendPath (const MISTRING& name);      //! Appends name to the end of the FILEPATH
      ERRVALUE GenerateErrorCode (ERRVALUE DftErrCode) const;        //!< Generate a MicroImages error code based on system error code
      char *GenerateOSPath () const;      //!< Generate Operating system specific path
      int GetExtnPosn () const;           //!< Returns the position of the extn marker
      int GetRootEndPosn () const;        //!< Return position of end of the root path
      void GetWindowsFolderPath (int folder);
      void JoinRelativePath (const MISTRING& str);             //! Join relative path to stored path
      ERRVALUE MakePath () const;         //!< Creates a path using the end path name

      MISTRING *m_path;                   //!< Allocated pointer to the string that holds the path

      static const UNICODE s_ExtnMark;    //!< System extension marker (.)
      static const UNICODE s_SepMark;     //!< System path separator marker (\\, /, :)
      static const UNICODE s_RelMark;     //!< System path relative marker (., :, .)
      static const char *s_BackTagStr;    //!< System directory backup string (..\\, ../, :)
      static const char *s_SameDirStr;    //!< System directory same directory string (.\\, ./, Invalid for the MAC)
      static const char *s_EncodeStr;     //!< Encode system marker
      static MISTRING *s_argv0;           //!< Internal module path stored for SetSystemPath()
      
      friend class FILE_RAW;              //!< To give FILE_RAW access to GenerateOSPath()

      CHECKSIZE(sizeof(void*));
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

DEFINE_ENUM_OPERATORS(FILEPATH::PERMISSION)

#if defined(WIN32)
#if !defined(MISYSTEMDLL) && !defined(NODLLLINKAGE)
#pragma warning(disable:4231)          /* the extern before template is a non-standard extension */

extern template class CLASSLIBEXPORT MILIST<FILEPATH>;      //! Template instantiation

#pragma warning(default:4231)          /* restore previous warning */
#endif      // _DLL
#endif      // WIN32

typedef MILIST<FILEPATH>   FILEPATHLIST;     //!< Easier to type

/*
* Overloaded operators for this class, inlined to prevent multiple copies
*/

//! Compare two FILEPATHS for equality.
inline bool operator== (               
   const FILEPATH& p,
   const FILEPATH& q
   ) { return (p.IsEqual(q)); }

//! Compare two FILEPATHS for inequality.
inline bool operator!= (               
   const FILEPATH& p,
   const FILEPATH& q
   ) { return (!p.IsEqual(q)); }

//! Compare two FILEPATHS for less than.
inline bool operator< (                
   const FILEPATH& p,
   const FILEPATH& q
   ) { return (p.IsLessThan(q)); }

//! Compare two FILEPATHS for greater than.
inline bool operator> (                
   const FILEPATH& p,
   const FILEPATH& q
   ) { return (!p.IsLessThan(q) && !p.IsEqual(q)); }

//! Compare two FILEPATHS for less than or equality.
inline bool operator<= (               
   const FILEPATH& p,
   const FILEPATH& q
   ) { return (p.IsLessThan(q) || p.IsEqual(q)); }

//! Compare two FILEPATHS for greater than or equality.
inline bool operator>= (               
   const FILEPATH& p,
   const FILEPATH& q
   ) { return (!p.IsLessThan(q)); }

//! Append a name to a path.
inline FILEPATH operator+ (            
   const FILEPATH& q,
   const MISTRING& p
   ) {
   FILEPATH temp(q);
   return (temp += p);
   }

inline MISTRING& operator<< (
   MISTRING& lhs,
   const FILEPATH& rhs
   ) { return (lhs.operator<<(rhs.GetDisplay())); }

#undef   CLASSLIBEXPORT

#endif

---