include/ptlib/filepath.h

   1 /*
   2  * filepath.h
   3  *
   4  * File system path string abstraction class.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.21  2003/09/17 05:41:58  csoutheren
  31  * Removed recursive includes
  32  *
  33  * Revision 1.20  2003/09/17 01:18:02  csoutheren
  34  * Removed recursive include file system and removed all references
  35  * to deprecated coooperative threading support
  36  *
  37  * Revision 1.19  2002/11/19 10:32:26  robertj
  38  * Changed PFilePath so can be empty string, indicating illegal path.
  39  *
  40  * Revision 1.18  2002/09/16 01:08:59  robertj
  41  * Added #define so can select if #pragma interface/implementation is used on
  42  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  43  *
  44  * Revision 1.17  2001/05/22 12:49:32  robertj
  45  * Did some seriously wierd rewrite of platform headers to eliminate the
  46  *   stupid GNU compiler warning about braces not matching.
  47  *
  48  * Revision 1.16  2001/02/13 04:39:08  robertj
  49  * Fixed problem with operator= in container classes. Some containers will
  50  *   break unless the copy is virtual (eg PStringStream's buffer pointers) so
  51  *   needed to add a new AssignContents() function to all containers.
  52  *
  53  * Revision 1.15  1999/03/09 02:59:49  robertj
  54  * Changed comments to doc++ compatible documentation.
  55  *
  56  * Revision 1.14  1999/02/16 08:07:11  robertj
  57  * MSVC 6.0 compatibility changes.
  58  *
  59  * Revision 1.13  1998/11/30 08:57:16  robertj
  60  * Fixed problem where if += is used on PFilePath, it no longer may be normalised.
  61  *
  62  * Revision 1.12  1998/09/23 06:20:37  robertj
  63  * Added open source copyright license.
  64  *
  65  * Revision 1.11  1998/02/16 00:14:57  robertj
  66  * Added functions to validate characters in a filename.
  67  *
  68  * Revision 1.10  1995/07/31 12:03:37  robertj
  69  * Added copy constructor and assignment operator for right types.
  70  *
  71  * Revision 1.9  1995/04/22 00:43:43  robertj
  72  * Added Move() function and changed semantics of Rename().
  73  * Changed all file name strings to PFilePath objects.
  74  *
  75  * Revision 1.8  1995/03/14 12:41:25  robertj
  76  * Updated documentation to use HTML codes.
  77  *
  78  * Revision 1.7  1994/12/21  11:52:57  robertj
  79  * Documentation and variable normalisation.
  80  *
  81  * Revision 1.6  1994/10/24  00:06:58  robertj
  82  * Changed PFilePath and PDirectory so descends from either PString or
  83  *     PCaselessString depending on the platform.
  84  *
  85  * Revision 1.5  1994/08/23  11:32:52  robertj
  86  * Oops
  87  *
  88  * Revision 1.4  1994/08/22  00:46:48  robertj
  89  * Added pragma fro GNU C++ compiler.
  90  *
  91  * Revision 1.3  1994/08/21  23:43:02  robertj
  92  * Changed parameter before variable argument list to NOT be a reference.
  93  *
  94  * Revision 1.2  1994/06/25  11:55:15  robertj
  95  * Unix version synchronisation.
  96  *
  97  * Revision 1.1  1994/04/20  12:17:44  robertj
  98  * Initial revision
  99  *
 100  */
 101
 102 #ifndef _PFILEPATH
 103 #define _PFILEPATH
 104
 105 #ifdef P_USE_PRAGMA
 106 #pragma interface
 107 #endif
 108
 109
 110 #ifdef DOC_PLUS_PLUS
 111 /** Base string type for a file path.
 112     For platforms where filenames are case significant (eg Unix) this class
 113     is a synonym for #PString#. If it is for a platform where case is not
 114     significant (eg Win32, Mac) then this is a synonym for #PCaselessString#.
 115  */
 116 class PFilePathString : public PString { };
 117 #endif
 118
 119
 120 ///////////////////////////////////////////////////////////////////////////////
 121 // File Specification
 122
 123 /**This class describes a full description for a file on the particular
 124    platform. This will always uniquely identify the file on currently mounted
 125    volumes.
 126
 127    An empty string for a PFilePath indicates an illegal path.
 128
 129    The ancestor class is dependent on the platform. For file systems that are
 130    case sensitive, eg Unix, the ancestor is #PString#. For other
 131    platforms, the ancestor class is #PCaselessString#.
 132  */
 133 class PFilePath : public PFilePathString
 134 {
 135   PCLASSINFO(PFilePath, PFilePathString);
 136
 137   public:
 138   /**@name Construction */
 139   //@{
 140     /**Create a file specification object.
 141      */
 142     PFilePath();
 143
 144     /**Create a file specification object with the specified file name.
 145
 146        The string passed in may be a full or partial specification for a file
 147        as determined by the platform. It is unusual for this to be a literal
 148        string, unless only the file title is specified, as that would be
 149        platform specific.
 150
 151        The partial file specification is translated into a canonical form
 152        which always absolutely references the file.
 153      */
 154     PFilePath(
 155       const char * cstr   /// Partial C string for file name.
 156     );
 157
 158     /**Create a file specification object with the specified file name.
 159
 160        The string passed in may be a full or partial specification for a file
 161        as determined by the platform. It is unusual for this to be a literal
 162        string, unless only the file title is specified, as that would be
 163        platform specific.
 164
 165        The partial file specification is translated into a canonical form
 166        which always absolutely references the file.
 167      */
 168     PFilePath(
 169       const PString & str /// Partial PString for file name.
 170     );
 171
 172     /**Create a file specification object with the specified file name.
 173      */
 174     PFilePath(
 175       const PFilePath & path /// Previous path for file name.
 176     );
 177
 178     /**Create a file spec object with a generated temporary name. The first
 179        parameter is a prefix for the filename to which a unique number is
 180        appended. The second parameter is the directory in which the file is to
 181        be placed. If this is NULL a system standard directory is used.
 182      */
 183     PFilePath(
 184       const char * prefix,  /// Prefix string for file title.
 185       const char * dir      /// Directory in which to place the file.
 186     );
 187
 188     /**Change the file specification object to the specified file name.
 189      */
 190     PFilePath & operator=(
 191       const PFilePath & path /// Previous path for file name.
 192     );
 193     /**Change the file specification object to the specified file name.
 194
 195        The string passed in may be a full or partial specifiaction for a file
 196        as determined by the platform. It is unusual for this to be a literal
 197        string, unless only the file title is specified, as that would be
 198        platform specific.
 199
 200        The partial file specification is translated into a canonical form
 201        which always absolutely references the file.
 202      */
 203     PFilePath & operator=(
 204       const PString & str /// Partial PString for file name.
 205     );
 206     /**Change the file specification object to the specified file name.
 207
 208        The string passed in may be a full or partial specifiaction for a file
 209        as determined by the platform. It is unusual for this to be a literal
 210        string, unless only the file title is specified, as that would be
 211        platform specific.
 212
 213        The partial file specification is translated into a canonical form
 214        which always absolutely references the file.
 215      */
 216     PFilePath & operator=(
 217       const char * cstr /// Partial "C" string for file name.
 218     );
 219   //@}
 220
 221   /**@name Path addition functions */
 222   //@{
 223     /**Concatenate a string to the file path, modifiying that path.
 224
 225        @return
 226        reference to string that was concatenated to.
 227      */
 228     PFilePath & operator+=(
 229       const PString & str   /// String to concatenate.
 230     );
 231
 232     /**Concatenate a C string to a path, modifiying that path. The
 233        #cstr# parameter is typically a literal string, eg:
 234 \begin{verbatim}
 235         myStr += "fred";
 236 \end{verbatim}
 237
 238        @return
 239        reference to string that was concatenated to.
 240      */
 241     PFilePath & operator+=(
 242       const char * cstr  /// C string to concatenate.
 243     );
 244
 245     /**Concatenate a single character to a path. The #ch#
 246        parameter is typically a literal, eg:
 247 \begin{verbatim}
 248         myStr += '!';
 249 \end{verbatim}
 250
 251        @return
 252        new string with concatenation of the object and parameter.
 253      */
 254     PFilePath & operator+=(
 255       char ch   // Character to concatenate.
 256     );
 257   //@}
 258
 259   /**@name Path decoding access functions */
 260   //@{
 261     /**Get the drive/volume name component of the full file specification. This
 262        is very platform specific. For example in DOS & NT it is the drive
 263        letter followed by a colon ("C:"), for Macintosh it is the volume name
 264        ("Untitled") and for Unix it is empty ("").
 265
 266        @return
 267        string for the volume name part of the file specification..
 268      */
 269     PFilePathString GetVolume() const;
 270
 271     /**Get the directory path component of the full file specification. This
 272        will include leading and trailing directory separators. For example
 273        on DOS this could be "\SRC\PWLIB\", for Macintosh ":Source:PwLib:" and
 274        for Unix "/users/equivalence/src/pwlib/".
 275
 276        @return
 277        string for the path part of the file specification.
 278      */
 279     PFilePathString GetPath() const;
 280
 281     /**Get the title component of the full file specification, eg for the DOS
 282        file "C:\SRC\PWLIB\FRED.DAT" this would be "FRED".
 283
 284        @return
 285        string for the title part of the file specification.
 286      */
 287     PFilePathString GetTitle() const;
 288
 289     /**Get the file type of the file. Note that on some platforms this may
 290        actually be part of the full name string. eg for DOS file
 291        "C:\SRC\PWLIB\FRED.TXT" this would be ".TXT" but on the Macintosh this
 292        might be "TEXT".
 293
 294        Note there are standard translations from file extensions, eg ".TXT"
 295        and some Macintosh file types, eg "TEXT".
 296
 297        @return
 298        string for the type part of the file specification.
 299      */
 300     PFilePathString GetType() const;
 301
 302     /**Get the actual directory entry name component of the full file
 303        specification. This may be identical to
 304        #GetTitle() + GetType()# or simply #GetTitle()#
 305        depending on the platform. eg for DOS file "C:\SRC\PWLIB\FRED.TXT" this
 306        would be "FRED.TXT".
 307
 308        @return
 309        string for the file name part of the file specification.
 310      */
 311     PFilePathString GetFileName() const;
 312
 313     /**Get the the directory that the file is contained in.  This may be
 314        identical to #GetVolume() + GetPath()# depending on the
 315        platform. eg for DOS file "C:\SRC\PWLIB\FRED.TXT" this would be
 316        "C:\SRC\PWLIB\".
 317
 318        Note that for Unix platforms, this returns the {\bf physical} path
 319        of the directory. That is all symlinks are resolved. Thus the directory
 320        returned may not be the same as the value of #GetPath()#.
 321
 322        @return
 323        Directory that the file is contained in.
 324      */
 325     PDirectory GetDirectory() const;
 326
 327     /**Set the type component of the full file specification, eg for the DOS
 328        file "C:\SRC\PWLIB\FRED.DAT" would become "C:\SRC\PWLIB\FRED.TXT".
 329      */
 330     void SetType(
 331       const PFilePathString & type  /// New type of the file.
 332     );
 333   //@}
 334
 335   /**@name Miscellaneous functions */
 336   //@{
 337     /**Test if the character is valid in a filename.
 338
 339        @return
 340        TRUE if the character is valid for a filename.
 341      */
 342     static BOOL IsValid(
 343       char c    /// Character to test for validity.
 344     );
 345
 346     /**Test if all the characters are valid in a filename.
 347
 348        @return
 349        TRUE if the character is valid for a filename.
 350      */
 351     static BOOL IsValid(
 352       const PString & str   /// String to test for validity.
 353     );
 354   //@}
 355
 356
 357   protected:
 358     virtual void AssignContents(const PContainer & cont);
 359
 360
 361 // Include platform dependent part of class
 362 #ifdef _WIN32
 363 #include "msos/ptlib/filepath.h"
 364 #else
 365 #include "unix/ptlib/filepath.h"
 366 #endif
 367 };
 368
 369 #endif
 370
 371 // End Of File ///////////////////////////////////////////////////////////////