ncbifile.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: ncbifile.hpp,v $
 * PRODUCTION Revision 1000.5  2004/06/01 19:08:05  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.42
 * PRODUCTION
 * ===========================================================================
 */

#ifndef CORELIB__NCBIFILE__HPP
#define CORELIB__NCBIFILE__HPP

/*  $Id: ncbifile.hpp,v 1000.5 2004/06/01 19:08:05 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Author: Vladimir Ivanov, Denis Vakatov
 *
 *
 */

/// @file ncbifile.hpp
/// Define files and directories accessory functions.
///
/// Defines classes CDirEntry, CFile, CDir, CMemoryFile, CFileException
/// to allow various file and directory operations.


#include <corelib/ncbistd.hpp>
#include <corelib/ncbitime.hpp>
#include <vector>

#if defined(NCBI_OS_MAC)
struct FSSpec;
#endif


/** @addtogroup Files
 *
 * @{
 */


BEGIN_NCBI_SCOPE



/////////////////////////////////////////////////////////////////////////////
///
/// CFileException --
///
/// Define exceptions generated for file operations.
///
/// CFileException inherits its basic functionality from CCoreException
/// and defines additional error codes for file operations.

class NCBI_XNCBI_EXPORT CFileException : public CCoreException
{
public:
    /// Error types that file operations can generate.
    enum EErrCode {
        eMemoryMap,
        eRelativePath
    };

    /// Translate from the error code value to its string representation.
    virtual const char* GetErrCodeString(void) const
    {
        switch (GetErrCode()) {
        case eMemoryMap: return "eMemoryMap";
        default:         return CException::GetErrCodeString();
        }
    }

    // Standard exception boilerplate code.
    NCBI_EXCEPTION_DEFAULT(CFileException, CCoreException);
};


/// Whether to follow symbolic links (aka shortcuts or aliases)
enum EFollowLinks {
    eIgnoreLinks,
    eFollowLinks
};


/////////////////////////////////////////////////////////////////////////////
///
/// CDirEntry --
///
/// Base class to work with files and directories.
///
/// Models the directory entry structure for the file system. Assumes that
/// the path argument has the following form, where any or all components may
/// be missing:
///
/// <dir><title><ext>
///
/// - dir   - file path             ("/usr/local/bin/"  or  "c:\windows\")
/// - title - file name without ext ("autoexec")
/// - ext   - file extension        (".bat" - whatever goes after the last dot)
///
/// Supported filename formats:  MS DOS/Windows, UNIX and MAC.

class NCBI_XNCBI_EXPORT CDirEntry
{
public:
    /// Constructor.
    CDirEntry();

#  ifdef NCBI_OS_MAC
    /// Copy constructor - for Mac file system.
    CDirEntry(const CDirEntry& other);

    /// Constructor with FSSpec argument - for Mac file system.
    CDirEntry(const FSSpec& fss);

    /// Assignment operator - for Mac file system.
    CDirEntry& operator= (const CDirEntry& other);

    /// Equality operator.
    bool operator== (const CDirEntry& other) const;
#  endif

    /// Constructor using specified path string.
    CDirEntry(const string& path);

    /// Reset path string.
    void Reset(const string& path);

    /// Destructor.
    virtual ~CDirEntry(void);

# if defined(NCBI_OS_MAC)
    /// Get FSSpec setting - for Mac file system.
    const FSSpec& FSS() const;
#endif

    /// Get directory entry path.
    string GetPath(void) const;


    //
    // Path processing.
    //

    /// Split the path string into its basic components.
    ///
    /// @param path
    ///   Path string to be split.
    /// @param dir
    ///   The directory component that is returned. This will always have
    ///   a terminating path separator (example: "/usr/local/").
    /// @param ext
    ///   The extension component. This will always start with a dot
    ///   (example: ".bat").
    static void SplitPath(const string& path,
                          string* dir = 0, string* base = 0, string* ext = 0);

    /// Get the Directory component for this directory entry.
    string GetDir (void) const;

    /// Get the base entry name with extension.
    string GetName(void) const;

    /// Get the base entry name without extension.
    string GetBase(void) const;

    /// Get extension name.
    string GetExt (void) const;

    /// Make a path from the basic components.
    ///
    /// @param dir
    ///   The directory component to make the path string. This will always
    ///   have a terminating path separator (example: "/usr/local/").
    /// @param base
    ///   The basename of the file component that is used to make up the path.
    /// @param ext
    ///   The extension component. This will always start with a dot
    ///   (example: ".bat").
    /// @return
    ///   Path built from the components.
    static string MakePath(const string& dir  = kEmptyStr,
                           const string& base = kEmptyStr,
                           const string& ext  = kEmptyStr);

    /// Get path separator symbol specific for the platform.
    static char GetPathSeparator(void);

    /// Check character "c" as path separator symbol specific for the platform.
    static bool IsPathSeparator(const char c);

    /// Add trailing path separator, if needed.
    static string AddTrailingPathSeparator(const string& path);

    /// Delete trailing path separator, if needed.
    static string DeleteTrailingPathSeparator(const string& path);

    /// Convert relative "path" on any OS to current OS dependent relative
    /// path. 
    static string ConvertToOSPath(const string& path);

    /// Check if the "path" is absolute for the current OS.
    ///
    /// Note that the "path" must be for current OS. 
    static bool IsAbsolutePath(const string& path);

    /// Check if the "path" is absolute for any OS.
    ///
    /// Note that the "path" can be for any OS (MSWIN, UNIX, MAC).
    static bool IsAbsolutePathEx(const string& path);

    /// Create relative path from 2 absolute pathes.
    ///
    /// @param path_from 
    ///   Absolute path that defines the start of the relative path.
    /// @param path_to
    ///   Absolute path that defines the endpoint of the relative path.
    /// @return
    ///   Return the relative path (empty string if the paths are the same).
    ///   Throw CFileException on error (e.g. if any of the paths is not
    ///   absolute, or if it is impossible to create relative path, such
    ///   as in case of different disks on MS-Windows).
    static string CreateRelativePath(const string& path_from, 
                                     const string& path_to);

    /// Concatenate the two parts of the path for the current OS.
    ///
    /// Note that the arguments must be for the current OS.
    /// @param first
    ///   The first part of the path which can be either absolute or relative.
    /// @param second
    ///   The second part of the path must always be relative.
    /// @return
    ///   The concatenated path.
    static string ConcatPath(const string& first, const string& second);

    /// Concatenate the two parts of the path for any OS.
    ///
    /// Note that the arguments must be for any OS (MSWIN, UNIX, MAC).
    /// @param first
    ///   The first part of the path which can be either absolute or relative.
    /// @param second
    ///   The second part of the path must always be relative.
    /// @return
    ///   The concatenated path.
    static string ConcatPathEx(const string& first, const string& second);

    /// Normalize path.
    ///
    /// Remove from the "path" all redundancy, convert it to the more
    /// simple form, if possible.
    /// Note that the "path" must be for current OS. 
    /// @param follow_links
    ///   Whether to follow symlinks (shortcuts, aliases)
    static string NormalizePath(const string& path,
                                EFollowLinks  follow_links = eIgnoreLinks);


    //
    // Checks & manipulations
    //

    /// Match "name" against the filename "mask".
    static bool MatchesMask(const char *name, const char *mask);

    /// Check existence of entry "path".
    virtual bool Exists(void) const;

    /// Rename entry to specified "new_path".
    bool Rename(const string& new_path);

    /// Directory remove mode.
    enum EDirRemoveMode {
        eOnlyEmpty,     ///< Remove only empty directory
        eNonRecursive,  ///< Remove all files in directory, but not remove
                        ///< subdirectories and files in it
        eRecursive      ///< Remove all files and subdirectories
    };

    /// Remove directory entry.
    ///
    /// Remove directory using the specified "mode".
    /// @sa
    ///   EDirRemoveMode
    virtual bool Remove(EDirRemoveMode mode = eRecursive) const;
    
    /// Check if directory entry a file.
    /// @sa
    ///   IsDir(), GetType()
    bool IsFile(EFollowLinks follow = eFollowLinks) const;

    /// Check if directory entry a directory.
    /// @sa
    ///   IsFile(), GetType()
    bool IsDir(EFollowLinks follow = eFollowLinks) const;

    /// Which directory entry type.
    enum EType {
        eFile = 0,     ///< Regular file
        eDir,          ///< Directory
        ePipe,         ///< Pipe
        eLink,         ///< Symbolic link     (UNIX only)
        eSocket,       ///< Socket            (UNIX only)
        eDoor,         ///< Door              (UNIX only)
        eBlockSpecial, ///< Block special     (UNIX only)
        eCharSpecial,  ///< Character special
        //
        eUnknown       ///< Unknown type
    };

    /// Get type of directory entry.
    ///
    /// @return
    ///   Return one of the values in EType. If the directory entry does
    ///   not exist return "eUnknown".
    EType GetType(EFollowLinks follow = eIgnoreLinks) const;

    /// Get time stamp of directory entry.
    ///
    /// The "creation" time under MS windows is actual creation time of the
    /// entry. Under UNIX "creation" time is the time of last entry status
    /// change. 
    /// @return
    ///   TRUE if time was acquired or FALSE otherwise.
    /// @sa
    ///   SetTime()
    bool GetTime(CTime *modification, CTime *creation = 0, 
                 CTime *last_access = 0) const;

    /// Set time stamp on directory entry.
    ///
    /// The process must be the owner of the file or have write permissions
    /// in order to change the time. If value of parameters modification or
    /// last access time is zero that current time will be used.
    /// @param modification
    ///   New file modification time.
    /// @param last_access
    ///   New last file access time. It cannot be less than the file
    ///   creation time. In last case it will be set equal to creation time.
    /// @return
    ///   TRUE if time was changed or FALSE otherwise.
    /// @sa
    ///   GetTime()
    bool SetTime(CTime *modification = 0 , CTime *last_access = 0) const;

    //
    // Access permissions.
    //

    /// Directory entry's access permissions.
    enum EMode {
        fExecute = 1,       ///< Execute permission
        fWrite   = 2,       ///< Write permission
        fRead    = 4,       ///< Read permission
        // initial defaults for dirs
        fDefaultDirUser  = fRead | fExecute | fWrite,
                            ///< Default user permission for dir.
        fDefaultDirGroup = fRead | fExecute,
                            ///< Default group permission for dir.
        fDefaultDirOther = fRead | fExecute,
                            ///< Default other permission for dir.
        // initial defaults for non-dir entries (files, etc.)
        fDefaultUser     = fRead | fWrite,
                            ///< Default user permission for file
        fDefaultGroup    = fRead,
                            ///< Default group permission for file
        fDefaultOther    = fRead,
                            ///< Default other permission for file
        fDefault = 8        ///< Special flag:  ignore all other flags,
                            ///< use current default mode
    };
    typedef unsigned int TMode;  ///< Binary OR of "EMode"

    /// Get the directory entry's permission settings.
    ///
    /// On WINDOWS, there is only the "user_mode" permission setting, and
    /// "group_mode" and "other_mode" settings will be ignored.
    /// @return
    ///   TRUE if successful return of permission settings; FALSE, otherwise.
    /// @sa
    ///   SetMode()
    bool GetMode(TMode* user_mode,
                 TMode* group_mode = 0,
                 TMode* other_mode = 0) const;

    /// Set permission mode for the directory entry.
    ///
    /// Permissions are set as specified by the passed values for user_mode,
    /// group_mode and other_mode. The default value for group_mode and
    /// other mode is "fDefault". Setting to "fDefault" will set the mode to
    /// its default permission settings.
    /// @return
    ///   TRUE if permission successfully set;  FALSE, otherwise.
    /// @sa
    ///   SetDefaultMode(), SetDefaultModeGlobal(), GetMode()
    bool SetMode(TMode user_mode,  // e.g. fDefault
                 TMode group_mode = fDefault,
                 TMode other_mode = fDefault) const;

    /// Set default mode globally for all CDirEntry objects.
    ///
    /// The default mode is set globally for all CDirEntry objects except for
    /// those having their own mode set with SetDefaultMode().
    ///
    /// When "fDefault" is passed as value of the mode parameters, the default
    /// mode will be set to the default values defined in EType:
    ///
    /// If user_mode is "fDefault", then default for user mode is set to
    /// - "fDefaultDirUser" if this is a directory or to
    /// - "fDefaultUser" if this is a file.