pdirect.h

pwlib源码库

   The directory may be opened to gain access to the list of files that it
   contains. Note that the directory does {\bf not} contain the "." and ".."
   entries that some platforms support.

   The ancestor class is dependent on the platform. For file systems that are
   case sensitive, eg Unix, the ancestor is #PString#. For other
   platforms, the ancestor class is #PCaselessString#.
 */
class PDirectory : public PFilePathString
{
  PCONTAINERINFO(PDirectory, PFilePathString);

  public:
  /**@name Construction */
  //@{
    /// Create a directory object of the current working directory
    PDirectory();
      
    /**Create a directory object of the specified directory. The
       #pathname# parameter may be a relative directory which is
       made absolute by the creation of the #PDirectory# object.
     */
    PDirectory(
      const char * cpathname      /// Directory path name for new object.
    );

    /**Create a directory object of the specified directory. The
       #pathname# parameter may be a relative directory which is
       made absolute by the creation of the #PDirectory# object.
     */
    PDirectory(
      const PString & pathname    /// Directory path name for new object.
    );

    /**Set the directory to the specified path.
     */
    PDirectory & operator=(
      const PString & pathname    /// Directory path name for new object.
    );

    /**Set the directory to the specified path.
     */
    PDirectory & operator=(
      const char * cpathname      /// Directory path name for new object.
    );
  //@}

  /**@name Access functions */
  //@{
    /**Get the directory for the parent to the current directory. If the
       directory is already the root directory it returns the root directory
       again.

       @return
       parent directory.
     */
    PDirectory GetParent() const;

    /**Get the volume name that the directory is in.
    
       This is platform dependent, for example for MS-DOS it is the 11
       character volume name for the drive, eg "DOS_DISK", and for Macintosh it
       is the disks volume name eg "Untitled". For a unix platform it is the
       device name for the file system eg "/dev/sda1".

       @return
       string for the directory volume.
     */
    PFilePathString GetVolume() const;

    /**Determine if the directory is the root directory of a volume.
    
       @return
       TRUE if the object is a root directory.
     */
    BOOL IsRoot() const;

    /**Get the root directory of a volume.
    
       @return
       root directory.
     */
    PDirectory GetRoot() const;

    /**Get the directory path as an array of strings.
       The first element in the array is the volume string, eg under Win32 it
       is "c:" or "\\machine", while under unix it is an empty string.
      */
    PStringArray GetPath() const;

    /**Determine if the character #ch# is a directory path
       separator.

       @return
       TRUE if may be used to separate directories in a path.
     */
    PINLINE static BOOL IsSeparator(
      char ch    /// Character to check as being a separator.
    );

    /**Determine the total number of bytes and number of bytes free on the
       volume that this directory is contained on.

       Note that the free space will be the physical limit and if user quotas
       are in force by the operating system, the use may not actually be able
       to use all of these bytes.

       @return
       TRUE if the information could be determined.
     */
    BOOL GetVolumeSpace(
      PInt64 & total,     /// Total number of bytes available on volume
      PInt64 & free,      /// Number of bytes unused on the volume
      DWORD & clusterSize /// "Quantisation factor" in bytes for files on volume
    ) const;
  //@}

  /**@name File system functions */
  //@{
    /**Test for if the directory exists.

       @return
       TRUE if directory exists.
     */
    BOOL Exists() const;

    /**Test for if the specified directory exists.

       @return
       TRUE if directory exists.
     */
    static BOOL Exists(
      const PString & path   /// Directory file path.
    );
      
    /**Change the current working directory to the objects location.

       @return
       TRUE if current working directory was changed.
     */
    BOOL Change() const;

    /**Change the current working directory to that specified..

       @return
       TRUE if current working directory was changed.
     */
    static BOOL Change(
      const PString & path   /// Directory file path.
    );
      
    /**Create a new directory with the specified permissions.

       @return
       TRUE if directory created.
     */
    BOOL Create(
      int perm = PFileInfo::DefaultDirPerms    // Permission on new directory.
    ) const;
    /**Create a new directory as specified with the specified permissions.

       @return
       TRUE if directory created.
     */
    static BOOL Create(
      const PString & p,   /// Directory file path.
      int perm = PFileInfo::DefaultDirPerms    /// Permission on new directory.
    );

    /**Delete the directory.

       @return
       TRUE if directory was deleted.
     */
    BOOL Remove();

    /**Delete the specified directory.

       @return
       TRUE if directory was deleted.
     */
    static BOOL Remove(
      const PString & path   /// Directory file path.
    );
  //@}

  /**@name Directory listing functions */
  //@{
    /**Open the directory for scanning its list of files. Once opened the
       #GetEntryName()# function may be used to get the current directory
       entry and the #Next()# function used to move to the next directory
       entry.
       
       Only files that are of a type that is specified in the mask will be
       returned.
       
       Note that the directory scan will {\bf not} return the "." and ".."
       entries that some platforms support.

       @return
       TRUE if directory was successfully opened, and there was at least one
       file in it of the specified types.
     */
    virtual BOOL Open(
      int scanMask = PFileInfo::AllFiles    /// Mask of files to provide.
    );
      
    /**Restart file list scan from the beginning of directory. This is similar
       to the #Open()# command but does not require that the directory be
       closed (using #Close()#) first.

       Only files that are of a type that is specified in the mask will be
       returned.

       Note that the directory scan will {\bf not} return the "." and ".."
       entries that some platforms support.

       @return
       TRUE if directory was successfully opened, and there was at least one
       file in it of the specified types.
     */
    virtual BOOL Restart(
      int scanMask = PFileInfo::AllFiles    /// Mask of files to provide.
    );
      
    /**Move to the next file in the directory scan.
    
       Only files that are of a type that is specified in the mask passed to
       the #Open()# or #Restart()# functions will be returned.

       Note that the directory scan will {\bf not} return the "." and ".."
       entries that some platforms support.

       @return
       TRUE if there is another valid file in the directory.
     */
    BOOL Next();
      
    /// Close the directory during or after a file list scan.
    virtual void Close();

    /**Get the name (without the volume or directory path) of the current
       entry in the directory scan. This may be the name of a file or a
       subdirectory or even a link or device for operating systems that support
       them.
       
       To get a full path name concatenate the PDirectory object itself with
       the entry name.
       
       Note that the directory scan will {\bf not} return the "." and ".."
       entries that some platforms support.

       @return
       string for directory entry.
     */
    virtual PFilePathString GetEntryName() const;

    /**Determine if the directory entry currently being scanned is itself
       another directory entry.
       
       Note that the directory scan will {\bf not} return the "." and ".."
       entries that some platforms support.

       @return
       TRUE if entry is a subdirectory.
     */
    virtual BOOL IsSubDir() const;

    /**Get file information on the current directory entry.
    
       @return
       TRUE if file information was successfully retrieved.
     */
    virtual BOOL GetInfo(
      PFileInfo & info    /// Object to receive the file information.
    ) const;
  //@}


  protected:
    // New functions for class
    void Construct();
    void Destruct()
    { Close(); PFilePathString::Destruct(); }

    // Member variables
    /// Mask of file types that the directory scan will return.
    int scanMask;

// Include platform dependent part of class
#ifdef _WIN32
#include "msos/ptlib/pdirect.h"
#else
#include "unix/ptlib/pdirect.h"
#endif

};

#endif

// End Of File ///////////////////////////////////////////////////////////////