/*
* filepath.h
*
* File system path string abstraction class.
*
* Portable Windows Library
*
* Copyright (c) 1993-1998 Equivalence Pty. Ltd.
*
* The contents of this file are subject to the Mozilla Public License
* Version 1.0 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
* the License for the specific language governing rights and limitations
* under the License.
*
* The Original Code is Portable Windows Library.
*
* The Initial Developer of the Original Code is Equivalence Pty. Ltd.
*
* Portions are Copyright (C) 1993 Free Software Foundation, Inc.
* All Rights Reserved.
*
* Contributor(s): ______________________________________.
*
* $Log: filepath.h,v $
* Revision 1.22 2005/11/25 03:43:47 csoutheren
* Fixed function argument comments to be compatible with Doxygen
*
* Revision 1.21 2003/09/17 05:41:58 csoutheren
* Removed recursive includes
*
* Revision 1.20 2003/09/17 01:18:02 csoutheren
* Removed recursive include file system and removed all references
* to deprecated coooperative threading support
*
* Revision 1.19 2002/11/19 10:32:26 robertj
* Changed PFilePath so can be empty string, indicating illegal path.
*
* Revision 1.18 2002/09/16 01:08:59 robertj
* Added #define so can select if #pragma interface/implementation is used on
* platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
*
* Revision 1.17 2001/05/22 12:49:32 robertj
* Did some seriously wierd rewrite of platform headers to eliminate the
* stupid GNU compiler warning about braces not matching.
*
* Revision 1.16 2001/02/13 04:39:08 robertj
* Fixed problem with operator= in container classes. Some containers will
* break unless the copy is virtual (eg PStringStream's buffer pointers) so
* needed to add a new AssignContents() function to all containers.
*
* Revision 1.15 1999/03/09 02:59:49 robertj
* Changed comments to doc++ compatible documentation.
*
* Revision 1.14 1999/02/16 08:07:11 robertj
* MSVC 6.0 compatibility changes.
*
* Revision 1.13 1998/11/30 08:57:16 robertj
* Fixed problem where if += is used on PFilePath, it no longer may be normalised.
*
* Revision 1.12 1998/09/23 06:20:37 robertj
* Added open source copyright license.
*
* Revision 1.11 1998/02/16 00:14:57 robertj
* Added functions to validate characters in a filename.
*
* Revision 1.10 1995/07/31 12:03:37 robertj
* Added copy constructor and assignment operator for right types.
*
* Revision 1.9 1995/04/22 00:43:43 robertj
* Added Move() function and changed semantics of Rename().
* Changed all file name strings to PFilePath objects.
*
* Revision 1.8 1995/03/14 12:41:25 robertj
* Updated documentation to use HTML codes.
*
* Revision 1.7 1994/12/21 11:52:57 robertj
* Documentation and variable normalisation.
*
* Revision 1.6 1994/10/24 00:06:58 robertj
* Changed PFilePath and PDirectory so descends from either PString or
* PCaselessString depending on the platform.
*
* Revision 1.5 1994/08/23 11:32:52 robertj
* Oops
*
* Revision 1.4 1994/08/22 00:46:48 robertj
* Added pragma fro GNU C++ compiler.
*
* Revision 1.3 1994/08/21 23:43:02 robertj
* Changed parameter before variable argument list to NOT be a reference.
*
* Revision 1.2 1994/06/25 11:55:15 robertj
* Unix version synchronisation.
*
* Revision 1.1 1994/04/20 12:17:44 robertj
* Initial revision
*
*/
#ifndef _PFILEPATH
#define _PFILEPATH
#ifdef P_USE_PRAGMA
#pragma interface
#endif
#ifdef DOC_PLUS_PLUS
/** Base string type for a file path.
For platforms where filenames are case significant (eg Unix) this class
is a synonym for #PString#. If it is for a platform where case is not
significant (eg Win32, Mac) then this is a synonym for #PCaselessString#.
*/
class PFilePathString : public PString { };
#endif
///////////////////////////////////////////////////////////////////////////////
// File Specification
/**This class describes a full description for a file on the particular
platform. This will always uniquely identify the file on currently mounted
volumes.
An empty string for a PFilePath indicates an illegal path.
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 PFilePath : public PFilePathString
{
PCLASSINFO(PFilePath, PFilePathString);
public:
/**@name Construction */
//@{
/**Create a file specification object.
*/
PFilePath();
/**Create a file specification object with the specified file name.
The string passed in may be a full or partial specification for a file
as determined by the platform. It is unusual for this to be a literal
string, unless only the file title is specified, as that would be
platform specific.
The partial file specification is translated into a canonical form
which always absolutely references the file.
*/
PFilePath(
const char * cstr ///< Partial C string for file name.
);
/**Create a file specification object with the specified file name.
The string passed in may be a full or partial specification for a file
as determined by the platform. It is unusual for this to be a literal
string, unless only the file title is specified, as that would be
platform specific.
The partial file specification is translated into a canonical form
which always absolutely references the file.
*/
PFilePath(
const PString & str ///< Partial PString for file name.
);
/**Create a file specification object with the specified file name.
*/
PFilePath(
const PFilePath & path ///< Previous path for file name.
);
/**Create a file spec object with a generated temporary name. The first
parameter is a prefix for the filename to which a unique number is
appended. The second parameter is the directory in which the file is to
be placed. If this is NULL a system standard directory is used.
*/
PFilePath(
const char * prefix, ///< Prefix string for file title.
const char * dir ///< Directory in which to place the file.
);
/**Change the file specification object to the specified file name.
*/
PFilePath & operator=(
const PFilePath & path ///< Previous path for file name.
);
/**Change the file specification object to the specified file name.
The string passed in may be a full or partial specifiaction for a file
as determined by the platform. It is unusual for this to be a literal
string, unless only the file title is specified, as that would be
platform specific.
The partial file specification is translated into a canonical form
which always absolutely references the file.
*/
PFilePath & operator=(
const PString & str ///< Partial PString for file name.
);
/**Change the file specification object to the specified file name.
The string passed in may be a full or partial specifiaction for a file
as determined by the platform. It is unusual for this to be a literal
string, unless only the file title is specified, as that would be
platform specific.
The partial file specification is translated into a canonical form
which always absolutely references the file.
*/
PFilePath & operator=(
const char * cstr ///< Partial "C" string for file name.
);
//@}
/**@name Path addition functions */
//@{
/**Concatenate a string to the file path, modifiying that path.
@return
reference to string that was concatenated to.
*/
PFilePath & operator+=(
const PString & str ///< String to concatenate.
);
/**Concatenate a C string to a path, modifiying that path. The
#cstr# parameter is typically a literal string, eg:
\begin{verbatim}
myStr += "fred";
\end{verbatim}
@return
reference to string that was concatenated to.
*/
PFilePath & operator+=(
const char * cstr ///< C string to concatenate.
);
/**Concatenate a single character to a path. The #ch#
parameter is typically a literal, eg:
\begin{verbatim}
myStr += '!';
\end{verbatim}
@return
new string with concatenation of the object and parameter.
*/
PFilePath & operator+=(
char ch // Character to concatenate.
);
//@}
/**@name Path decoding access functions */
//@{
/**Get the drive/volume name component of the full file specification. This
is very platform specific. For example in DOS & NT it is the drive
letter followed by a colon ("C:"), for Macintosh it is the volume name
("Untitled") and for Unix it is empty ("").
@return
string for the volume name part of the file specification..
*/
PFilePathString GetVolume() const;
/**Get the directory path component of the full file specification. This
will include leading and trailing directory separators. For example
on DOS this could be "\SRC\PWLIB\", for Macintosh ":Source:PwLib:" and
for Unix "/users/equivalence/src/pwlib/".
@return
string for the path part of the file specification.
*/
PFilePathString GetPath() const;
/**Get the title component of the full file specification, eg for the DOS
file "C:\SRC\PWLIB\FRED.DAT" this would be "FRED".
@return
string for the title part of the file specification.
*/
PFilePathString GetTitle() const;
/**Get the file type of the file. Note that on some platforms this may
actually be part of the full name string. eg for DOS file
"C:\SRC\PWLIB\FRED.TXT" this would be ".TXT" but on the Macintosh this
might be "TEXT".
Note there are standard translations from file extensions, eg ".TXT"
and some Macintosh file types, eg "TEXT".
@return
string for the type part of the file specification.
*/
PFilePathString GetType() const;
/**Get the actual directory entry name component of the full file
specification. This may be identical to
#GetTitle() + GetType()# or simply #GetTitle()#
depending on the platform. eg for DOS file "C:\SRC\PWLIB\FRED.TXT" this
would be "FRED.TXT".
@return
string for the file name part of the file specification.
*/
PFilePathString GetFileName() const;
/**Get the the directory that the file is contained in. This may be
identical to #GetVolume() + GetPath()# depending on the
platform. eg for DOS file "C:\SRC\PWLIB\FRED.TXT" this would be
"C:\SRC\PWLIB\".
Note that for Unix platforms, this returns the {\bf physical} path
of the directory. That is all symlinks are resolved. Thus the directory
returned may not be the same as the value of #GetPath()#.
@return
Directory that the file is contained in.
*/
PDirectory GetDirectory() const;
/**Set the type component of the full file specification, eg for the DOS
file "C:\SRC\PWLIB\FRED.DAT" would become "C:\SRC\PWLIB\FRED.TXT".
*/
void SetType(
const PFilePathString & type ///< New type of the file.
);
//@}
/**@name Miscellaneous functions */
//@{
/**Test if the character is valid in a filename.
@return
TRUE if the character is valid for a filename.
*/
static BOOL IsValid(
char c ///< Character to test for validity.
);
/**Test if all the characters are valid in a filename.
@return
TRUE if the character is valid for a filename.
*/
static BOOL IsValid(
const PString & str ///< String to test for validity.
);
//@}
protected:
virtual void AssignContents(const PContainer & cont);
// Include platform dependent part of class
#ifdef _WIN32
#include "msos/ptlib/filepath.h"
#else
#include "unix/ptlib/filepath.h"
#endif
};
#endif
// End Of File ///////////////////////////////////////////////////////////////
syntax highlighted by Code2HTML, v. 0.9.1