Back to index

lightning-sunbird  0.9+nobinonly
nsFileSpec.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either of the GNU General Public License Version 2 or later (the "GPL"),
00026  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 
00039 
00040 
00041 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
00042     THESE CLASSES ARE DEPRECATED AND UNSUPPORTED!  USE |nsIFile| and |nsILocalFile|.
00043  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00044 
00045 
00046 
00047 
00048 
00049 
00050 
00051 
00052 
00053 
00054 //    First checked in on 98/11/20 by John R. McMullen in the wrong directory.
00055 //    Checked in again 98/12/04.
00056 //    Polished version 98/12/08.
00057 
00058 //========================================================================================
00059 //
00060 //  Classes defined:
00061 //
00062 //      nsFilePath, nsFileURL, nsFileSpec, nsPersistentFileDescriptor
00063 //      nsDirectoryIterator.
00064 //
00065 //  Q.  How should I represent files at run time?
00066 //  A.  Use nsFileSpec.  Using char* will lose information on some platforms.
00067 //
00068 //  Q.  Then what are nsFilePath and nsFileURL for?
00069 //  A.  Only when you need a char* parameter for legacy code.
00070 //
00071 //  Q.  How should I represent files in a persistent way (eg, in a disk file)?
00072 //  A.  Use nsPersistentFileDescriptor.  Convert to and from nsFileSpec at run time.
00073 //
00074 //  This suite provides the following services:
00075 //
00076 //      1.  Encapsulates all platform-specific file details, so that files can be
00077 //          described correctly without any platform #ifdefs
00078 //
00079 //      2.  Type safety.  This will fix the problems that used to occur because people
00080 //          confused file paths.  They used to use const char*, which could mean three
00081 //          or four different things.  Bugs were introduced as people coded, right up
00082 //          to the moment Communicator 4.5 shipped.
00083 //
00084 //      3.  Used in conjunction with nsFileStream.h (q.v.), this supports all the power
00085 //          and readability of the ansi stream syntax.
00086 //
00087 //          Basic example:
00088 //
00089 //              nsFilePath myPath("/Development/iotest.txt");
00090 //
00091 //              nsOutputFileStream testStream(nsFileSpec(myPath));
00092 //              testStream << "Hello World" << nsEndl;
00093 //
00094 //      4.  Handy methods for manipulating file specifiers safely, e.g. MakeUnique(),
00095 //          SetLeafName(), Exists().
00096 //
00097 //      5.  Easy cross-conversion.
00098 //
00099 //          Examples:
00100 //
00101 //              Initialize a URL from a string
00102 //
00103 //                  nsFileURL fileURL("file:///Development/MPW/MPW%20Shell");
00104 //
00105 //              Initialize a Unix-style path from a URL
00106 //
00107 //                  nsFilePath filePath(fileURL);
00108 //
00109 //              Initialize a file spec from a URL
00110 //
00111 //                  nsFileSpec fileSpec(fileURL);
00112 //
00113 //              Make the spec unique.
00114 //
00115 //                  fileSpec.MakeUnique();
00116 //
00117 //              Assign the spec to a URL (causing conversion)
00118 //
00119 //                  fileURL = fileSpec;
00120 //
00121 //              Assign a unix path using a string
00122 //
00123 //                  filePath = "/Development/MPW/SysErrs.err";
00124 //
00125 //              Assign to a file spec using a unix path (causing conversion).
00126 //
00127 //                  fileSpec = filePath;
00128 //
00129 //              Make this unique.
00130 //
00131 //                  fileSpec.MakeUnique();
00132 //
00133 //      6.  Fixes a bug that have been there for a long time, and
00134 //          is inevitable if you use NSPR alone, where files are described as paths.
00135 //
00136 //          The problem affects platforms (Macintosh) in which a path does not fully
00137 //          specify a file, because two volumes can have the same name.  This
00138 //          is solved by holding a "private" native file spec inside the
00139 //          nsFilePath and nsFileURL classes, which is used when appropriate.
00140 //
00141 //========================================================================================
00142 
00143 #ifndef _FILESPEC_H_
00144 #define _FILESPEC_H_
00145 
00146 #include "xpcomobsolete.h"
00147 #include "nsError.h"
00148 #include "nsString.h"
00149 #include "nsReadableUtils.h"
00150 #include "nsCRT.h"
00151 #include "prtypes.h"
00152 
00153 //========================================================================================
00154 //                          Compiler-specific macros, as needed
00155 //========================================================================================
00156 #if !defined(NS_USING_NAMESPACE) && (defined(__MWERKS__) || defined(_MSC_VER))
00157 #define NS_USING_NAMESPACE
00158 #endif
00159 
00160 #ifdef NS_USING_NAMESPACE
00161 
00162 #define NS_NAMESPACE_PROTOTYPE
00163 #define NS_NAMESPACE namespace
00164 #define NS_NAMESPACE_END
00165 #define NS_EXPLICIT explicit
00166 #else
00167 
00168 #define NS_NAMESPACE_PROTOTYPE static
00169 #define NS_NAMESPACE struct
00170 #define NS_NAMESPACE_END ;
00171 #define NS_EXPLICIT
00172 
00173 #endif
00174 //=========================== End Compiler-specific macros ===============================
00175 
00176 #include "nsILocalFile.h"
00177 #include "nsCOMPtr.h"
00178 
00179 #if defined(XP_MAC)
00180 #include <Files.h>
00181 #include "nsILocalFileMac.h"
00182 #elif defined(XP_UNIX) || defined(XP_BEOS)
00183 #include <dirent.h>
00184 #elif defined(XP_WIN)
00185 
00186 // This clashes with some of the Win32 system headers (specifically,
00187 // winbase.h). Hopefully they'll have been included first; else we may
00188 // have problems. We could include winbase.h before doing this;
00189 // unfortunately, it's bring in too much crap and'd slow stuff down
00190 // more than it's worth doing.
00191 #ifdef CreateDirectory
00192 #undef CreateDirectory
00193 #endif
00194 
00195 #include "prio.h"
00196 #elif defined(XP_OS2)
00197 #define INCL_DOS
00198 #define INCL_DOSERRORS
00199 #define INCL_WIN
00200 #define INCL_GPI
00201 #include <os2.h>
00202 #include "prio.h"
00203 #endif
00204 
00205 //========================================================================================
00206 // Here are the allowable ways to describe a file.
00207 //========================================================================================
00208 
00209 class nsFileSpec;             // Preferred.  For i/o use nsInputFileStream, nsOutputFileStream
00210 class nsFilePath;
00211 class nsFileURL;
00212 class nsNSPRPath;             // This can be passed to NSPR file I/O routines, if you must.
00213 class nsPersistentFileDescriptor; // Used for storage across program launches.
00214 
00215 #define kFileURLPrefix "file://"
00216 #define kFileURLPrefixLength (7)
00217 
00218 class nsOutputStream;
00219 class nsInputStream;
00220 class nsIOutputStream;
00221 class nsIInputStream;
00222 class nsOutputFileStream;
00223 class nsInputFileStream;
00224 class nsOutputConsoleStream;
00225 
00226 class nsIUnicodeEncoder;
00227 class nsIUnicodeDecoder;
00228 
00229 //========================================================================================
00230 // Conversion of native file errors to nsresult values. These are really only for use
00231 // in the file module, clients of this interface shouldn't really need them.
00232 // Error results returned from this interface have, in the low-order 16 bits,
00233 // native errors that are masked to 16 bits.  Assumption: a native error of 0 is success
00234 // on all platforms. Note the way we define this using an inline function.  This
00235 // avoids multiple evaluation if people go NS_FILE_RESULT(function_call()).
00236 #define NS_FILE_RESULT(x) ns_file_convert_result((PRInt32)x)
00237 nsresult ns_file_convert_result(PRInt32 nativeErr);
00238 #define NS_FILE_FAILURE NS_FILE_RESULT(-1)
00239 
00240 //========================================================================================
00241 class nsSimpleCharString
00242 //  An envelope for char*: reference counted. Used internally by all the nsFileSpec
00243 //  classes below.
00244 //========================================================================================
00245 {
00246 public:
00247                                  nsSimpleCharString();
00248                                  nsSimpleCharString(const char*);
00249                                  nsSimpleCharString(const nsString&);
00250                                  nsSimpleCharString(const nsSimpleCharString&);
00251                                  nsSimpleCharString(const char* inData, PRUint32 inLength);
00252                                  
00253                                  ~nsSimpleCharString();
00254                                  
00255     void                         operator = (const char*);
00256     void                         operator = (const nsString&);
00257     void                         operator = (const nsSimpleCharString&);
00258                                  
00259                                  operator const char*() const { return mData ? mData->mString : 0; }
00260                                  operator char* ()
00261                                  {
00262                                      ReallocData(Length()); // requires detaching if shared...
00263                                      return mData ? mData->mString : 0;
00264                                  }
00265     PRBool                       operator == (const char*);
00266     PRBool                       operator == (const nsString&);
00267     PRBool                       operator == (const nsSimpleCharString&);
00268 
00269     void                         operator += (const char* inString);
00270     nsSimpleCharString           operator + (const char* inString) const;
00271     
00272     char                         operator [](int i) const { return mData ? mData->mString[i] : '\0'; }
00273     char&                        operator [](int i)
00274                                  {
00275                                      if (i >= (int)Length())
00276                                          ReallocData((PRUint32)i + 1);
00277                                      return mData->mString[i]; // caveat appelator
00278                                  }
00279     char&                        operator [](unsigned int i) { return (*this)[(int)i]; }
00280     
00281     void                         Catenate(const char* inString1, const char* inString2);
00282    
00283     void                         SetToEmpty(); 
00284     PRBool                       IsEmpty() const { return Length() == 0; }
00285     
00286     PRUint32                     Length() const { return mData ? mData->mLength : 0; }
00287     void                         SetLength(PRUint32 inLength) { ReallocData(inLength); }
00288     void                         CopyFrom(const char* inData, PRUint32 inLength);
00289     void                         LeafReplace(char inSeparator, const char* inLeafName);
00290     char*                        GetLeaf(char inSeparator) const; // use PR_Free()
00291     void                         Unescape();
00292 
00293 protected:
00294 
00295     void                         AddRefData();
00296     void                         ReleaseData();
00297     void                         ReallocData(PRUint32 inLength);
00298 
00299     //--------------------------------------------------
00300     // Data
00301     //--------------------------------------------------
00302 
00303 protected:
00304 
00305     struct Data {
00306         int         mRefCount;
00307         PRUint32    mLength;
00308         char        mString[1];
00309         };
00310     Data*                        mData;
00311 }; // class nsSimpleCharString
00312 
00313 //========================================================================================
00314 class NS_COM_OBSOLETE nsFileSpec
00315 //    This is whatever each platform really prefers to describe files as.  Declared first
00316 //  because the other two types have an embedded nsFileSpec object.
00317 //========================================================================================
00318 {
00319     public:
00320                                 nsFileSpec();
00321                                 
00322                                 // These two meathods take *native* file paths.
00323         NS_EXPLICIT             nsFileSpec(const char* inNativePath, PRBool inCreateDirs = PR_FALSE);
00324         NS_EXPLICIT             nsFileSpec(const nsString& inNativePath, PRBool inCreateDirs = PR_FALSE);
00325                                 
00326         
00327         NS_EXPLICIT             nsFileSpec(const nsFilePath& inPath);
00328         NS_EXPLICIT             nsFileSpec(const nsFileURL& inURL);
00329                                 nsFileSpec(const nsFileSpec& inPath);
00330         virtual                 ~nsFileSpec();
00331 
00332                                 // These two operands take *native* file paths.
00333         void                    operator = (const char* inNativePath);
00334 
00335         void                    operator = (const nsFilePath& inPath);
00336         void                    operator = (const nsFileURL& inURL);
00337         void                    operator = (const nsFileSpec& inOther);
00338         void                    operator = (const nsPersistentFileDescriptor& inOther);
00339 
00340         PRBool                  operator ==(const nsFileSpec& inOther) const;
00341         PRBool                  operator !=(const nsFileSpec& inOther) const;
00342 
00343 
00344                                 // Returns a native path, and allows the
00345                                 // path to be "passed" to legacy code.  This practice
00346                                 // is VERY EVIL and should only be used to support legacy
00347                                 // code.  Using it guarantees bugs on Macintosh.
00348                                 // The path is cached and freed by the nsFileSpec destructor
00349                                 // so do not delete (or free) it. See also nsNSPRPath below,
00350                                 // if you really must pass a string  to PR_OpenFile().
00351                                 // Doing so will introduce two automatic bugs.
00352        const char*              GetCString() const;
00353 
00354                                 // Same as GetCString (please read the comments).
00355                                 // Do not try to free this!
00356                                 operator const char* () const { return GetCString(); }
00357 
00358                                 // Same as GetCString (please read the comments).
00359                                 // Do not try to free this!
00360        const char*              GetNativePathCString() const { return GetCString(); }
00361 
00362        PRBool                   IsChildOf(nsFileSpec &possibleParent);
00363 
00364 #if defined(XP_MAC)
00365         // For Macintosh people, this is meant to be useful in its own right as a C++ version
00366         // of the FSSpec struct.        
00367                                 nsFileSpec(
00368                                     short vRefNum,
00369                                     long parID,
00370                                     ConstStr255Param name,
00371                                     PRBool resolveAlias = PR_TRUE);
00372 
00373                                 nsFileSpec(const FSSpec& inSpec, PRBool resolveAlias = PR_TRUE);
00374         void                    operator = (const FSSpec& inSpec);
00375 
00376                                 operator FSSpec* () { return &mSpec; }
00377                                 operator const FSSpec* const () { return &mSpec; }
00378                                 operator  FSSpec& () { return mSpec; }
00379                                 operator const FSSpec& () const { return mSpec; }
00380                                 
00381         const FSSpec&           GetFSSpec() const { return mSpec; }
00382         FSSpec&                 GetFSSpec() { return mSpec; }
00383         ConstFSSpecPtr          GetFSSpecPtr() const { return &mSpec; }
00384         FSSpecPtr               GetFSSpecPtr() { return &mSpec; }
00385         void                    MakeAliasSafe();
00386         void                    MakeUnique(ConstStr255Param inSuggestedLeafName);
00387         StringPtr               GetLeafPName() { return mSpec.name; }
00388         ConstStr255Param        GetLeafPName() const { return mSpec.name; }
00389 
00390         OSErr                   GetCatInfo(CInfoPBRec& outInfo) const;
00391 
00392         OSErr                   SetFileTypeAndCreator(OSType type, OSType creator);
00393         OSErr                   GetFileTypeAndCreator(OSType* type, OSType* creator);
00394 
00395 #endif // end of Macintosh utility methods.
00396 
00397         PRBool                  Valid() const { return NS_SUCCEEDED(Error()); }
00398         nsresult                Error() const
00399                                 {
00400 #if !defined(XP_MAC)
00401                                     if (mPath.IsEmpty() && NS_SUCCEEDED(mError)) 
00402                                         ((nsFileSpec*)this)->mError = NS_ERROR_NOT_INITIALIZED; 
00403 #endif 
00404                                     return mError;
00405                                 }
00406         PRBool                  Failed() const { return (PRBool)NS_FAILED(Error()); }
00407 
00408     //--------------------------------------------------
00409     // Queries and path algebra.  These do not modify the disk.
00410     //--------------------------------------------------
00411 
00412         char*                   GetLeafName() const; // Allocated.  Use nsCRT::free().
00413                                 // inLeafName can be a relative path, so this allows
00414                                 // one kind of concatenation of "paths".
00415         void                    SetLeafName(const char* inLeafName);
00416 
00417                                 // Return the filespec of the parent directory. Used
00418                                 // in conjunction with GetLeafName(), this lets you
00419                                 // parse a path into a list of node names.  Beware,
00420                                 // however, that the top node is still not a name,
00421                                 // but a spec.  Volumes on Macintosh can have identical
00422                                 // names.  Perhaps could be used for an operator --() ?
00423         void                    GetParent(nsFileSpec& outSpec) const;
00424 
00425 
00426                                 // ie nsFileSpec::TimeStamp.  This is 32 bits now,
00427                                 // but might change, eg, to a 64-bit class.  So use the
00428                                 // typedef, and use a streaming operator to convert
00429                                 // to a string, so that your code won't break.  It's
00430                                 // none of your business what the number means.  Don't
00431                                 // rely on the implementation.
00432         typedef PRUint32        TimeStamp;
00433 
00434                                 // This will return different values on different
00435                                 // platforms, even for the same file (eg, on a server).
00436                                 // But if the platform is constant, it will increase after
00437                                 // every file modification.
00438         void                    GetModDate(TimeStamp& outStamp) const;
00439 
00440         PRBool                  ModDateChanged(const TimeStamp& oldStamp) const
00441                                 {
00442                                     TimeStamp newStamp;
00443                                     GetModDate(newStamp);
00444                                     return newStamp != oldStamp;
00445                                 }
00446         
00447         PRUint32                GetFileSize() const;
00448         PRInt64                 GetDiskSpaceAvailable() const;
00449         
00450         nsFileSpec              operator + (const char* inRelativeUnixPath) const;
00451 
00452                                 // Concatenate the relative path to this directory.
00453                                 // Used for constructing the filespec of a descendant.
00454                                 // This must be a directory for this to work.  This differs
00455                                 // from SetLeafName(), since the latter will work
00456                                 // starting with a sibling of the directory and throws
00457                                 // away its leaf information, whereas this one assumes
00458                                 // this is a directory, and the relative path starts
00459                                 // "below" this.
00460         void                    operator += (const char* inRelativeUnixPath);
00461 
00462 
00463                                
00464         PRBool                  IsDirectory() const;          // More stringent than Exists()                               
00465         PRBool                  IsFile() const;               // More stringent than Exists()
00466         PRBool                  Exists() const;
00467 
00468         PRBool                  IsHidden() const;
00469         
00470         PRBool                  IsSymlink() const;
00471 
00472     //--------------------------------------------------
00473     // Creation and deletion of objects.  These can modify the disk.
00474     //--------------------------------------------------
00475 
00476     // For security reasons, these create the file.
00477         void                    MakeUnique(PRBool inCreateFile = PR_TRUE);
00478         void                    MakeUnique(const char* inSuggestedLeafName, PRBool inCreateFile = PR_TRUE);
00479     
00480                                 // Called for the spec of an alias.  Modifies the spec to
00481                                 // point to the original.  Sets mError.
00482         nsresult                ResolveSymlink(PRBool& wasSymlink);
00483 
00484         void                    CreateDirectory(int mode = 0775 /* for unix */);
00485         void                    CreateDir(int mode = 0775) { CreateDirectory(mode); }
00486                                    // workaround for yet another VC++ bug with long identifiers.
00487         void                    Delete(PRBool inRecursive) const;
00488         nsresult                Truncate(PRInt32 aNewLength) const;
00489         void                    RecursiveCopy(nsFileSpec newDir) const;
00490         
00491         nsresult                Rename(const char* inNewName); // not const: gets updated
00492         nsresult                CopyToDir(const nsFileSpec& inNewParentDirectory) const;
00493         nsresult                MoveToDir(const nsFileSpec& inNewParentDirectory);
00494         nsresult                Execute(const char* args) const;
00495 
00496     protected:
00497 
00498     //--------------------------------------------------
00499     // Data
00500     //--------------------------------------------------
00501 
00502     protected:
00503     
00504                                 // Clear the nsFileSpec contents, resetting it
00505                                 // to the uninitialized state;
00506        void                     Clear();
00507        
00508                                 friend class nsFilePath;
00509                                 friend class nsFileURL;
00510                                 friend class nsDirectoryIterator;
00511 #if defined(XP_MAC)
00512         FSSpec                  mSpec;
00513 #endif
00514         nsSimpleCharString      mPath;
00515         nsresult                mError;
00516 
00517 private:
00518         NS_EXPLICIT             nsFileSpec(const nsPersistentFileDescriptor& inURL);
00519   
00520 }; // class nsFileSpec
00521 
00522 // FOR HISTORICAL REASONS:
00523 
00524 typedef nsFileSpec nsNativeFileSpec;
00525 
00526 //========================================================================================
00527 class NS_COM_OBSOLETE nsFileURL
00528 //    This is an escaped string that looks like "file:///foo/bar/mumble%20fish".  Since URLs
00529 //    are the standard way of doing things in mozilla, this allows a string constructor,
00530 //    which just stashes the string with no conversion.
00531 //========================================================================================
00532 {
00533     public:
00534                                 nsFileURL(const nsFileURL& inURL);
00535         NS_EXPLICIT             nsFileURL(const char* inURLString, PRBool inCreateDirs = PR_FALSE);
00536         NS_EXPLICIT             nsFileURL(const nsString& inURLString, PRBool inCreateDirs = PR_FALSE);
00537         NS_EXPLICIT             nsFileURL(const nsFilePath& inPath);
00538         NS_EXPLICIT             nsFileURL(const nsFileSpec& inPath);
00539         virtual                 ~nsFileURL();
00540 
00541 //        nsString             GetString() const { return mPath; }
00542                                     // may be needed for implementation reasons,
00543                                     // but should not provide a conversion constructor.
00544 
00545         void                    operator = (const nsFileURL& inURL);
00546         void                    operator = (const char* inURLString);
00547         void                    operator = (const nsString& inURLString)
00548                                 {
00549                                     *this = NS_LossyConvertUCS2toASCII(inURLString).get();
00550                                 }
00551         void                    operator = (const nsFilePath& inOther);
00552         void                    operator = (const nsFileSpec& inOther);
00553 
00554         void                    operator +=(const char* inRelativeUnixPath);
00555         nsFileURL               operator +(const char* inRelativeUnixPath) const;
00556                                 operator const char* () const { return (const char*)mURL; } // deprecated.
00557         const char*             GetURLString() const { return (const char*)mURL; }
00558                                                         // Not allocated, so don't free it.
00559         const char*             GetAsString() const { return (const char*)mURL; }
00560                                                         // Not allocated, so don't free it.
00561 
00562 #if defined(XP_MAC)
00563                                 // Accessor to allow quick assignment to a mFileSpec
00564         const nsFileSpec&       GetFileSpec() const { return mFileSpec; }
00565 #endif
00566 
00567     //--------------------------------------------------
00568     // Data
00569     //--------------------------------------------------
00570 
00571     protected:
00572                                 friend class nsFilePath; // to allow construction of nsFilePath
00573         nsSimpleCharString      mURL;
00574 
00575 #if defined(XP_MAC)
00576         // Since the path on the macintosh does not uniquely specify a file (volumes
00577         // can have the same name), stash the secret nsFileSpec, too.
00578         nsFileSpec              mFileSpec;
00579 #endif
00580 }; // class nsFileURL
00581 
00582 //========================================================================================
00583 class NS_COM_OBSOLETE nsFilePath
00584 //    This is a string that looks like "/foo/bar/mumble fish".  Same as nsFileURL, but
00585 //    without the "file:// prefix", and NOT %20 ENCODED! Strings passed in must be
00586 //    valid unix-style paths in this format.
00587 //========================================================================================
00588 {
00589     public:
00590                                 nsFilePath(const nsFilePath& inPath);
00591         NS_EXPLICIT             nsFilePath(const char* inUnixPathString, PRBool inCreateDirs = PR_FALSE);
00592         NS_EXPLICIT             nsFilePath(const nsString& inUnixPathString, PRBool inCreateDirs = PR_FALSE);
00593         NS_EXPLICIT             nsFilePath(const nsFileURL& inURL);
00594         NS_EXPLICIT             nsFilePath(const nsFileSpec& inPath);
00595         virtual                 ~nsFilePath();
00596 
00597                                 
00598                                 operator const char* () const { return mPath; }
00599                                     // This will return a UNIX string.  If you
00600                                     // need a string that can be passed into
00601                                     // NSPR, take a look at the nsNSPRPath class.
00602 
00603         void                    operator = (const nsFilePath& inPath);
00604         void                    operator = (const char* inUnixPathString);
00605         void                    operator = (const nsString& inUnixPathString)
00606                                 {
00607                                     *this = NS_LossyConvertUCS2toASCII(inUnixPathString).get();
00608                                 }
00609         void                    operator = (const nsFileURL& inURL);
00610         void                    operator = (const nsFileSpec& inOther);
00611 
00612         void                    operator +=(const char* inRelativeUnixPath);
00613         nsFilePath              operator +(const char* inRelativeUnixPath) const;
00614 
00615 #if defined(XP_MAC)
00616     public:
00617                                 // Accessor to allow quick assignment to a mFileSpec
00618         const nsFileSpec&       GetFileSpec() const { return mFileSpec; }
00619 #endif
00620 
00621     //--------------------------------------------------
00622     // Data
00623     //--------------------------------------------------
00624 
00625     private:
00626 
00627         nsSimpleCharString       mPath;
00628 #if defined(XP_MAC)
00629         // Since the path on the macintosh does not uniquely specify a file (volumes
00630         // can have the same name), stash the secret nsFileSpec, too.
00631         nsFileSpec               mFileSpec;
00632 #endif
00633 }; // class nsFilePath
00634 
00635 //========================================================================================
00636 class nsPersistentFileDescriptor
00637 // To save information about a file's location in another file, initialize
00638 // one of these from your nsFileSpec, and then write this out to your output stream.
00639 // To retrieve the info, create one of these, read its value from an input stream.
00640 // and then make an nsFileSpec from it.
00641 //========================================================================================
00642 {
00643     public:
00644                                 nsPersistentFileDescriptor() {}
00645                                     // For use prior to reading in from a stream
00646                                 nsPersistentFileDescriptor(const nsPersistentFileDescriptor& inEncodedData);
00647         virtual                 ~nsPersistentFileDescriptor();
00648         void                              operator = (const nsPersistentFileDescriptor& inEncodedData);
00649         
00650         // Conversions
00651         NS_EXPLICIT             nsPersistentFileDescriptor(const nsFileSpec& inSpec);
00652         void                              operator = (const nsFileSpec& inSpec);
00653         
00654               // The following four functions are declared here (as friends). Their implementations
00655               // are in mozilla/base/src/nsFileSpecStreaming.cpp.
00656        
00657        friend nsresult         Read(nsIInputStream* aStream, nsPersistentFileDescriptor&);
00658        friend nsresult         Write(nsIOutputStream* aStream, const nsPersistentFileDescriptor&);
00659            // writes the data to a file
00660        friend NS_COM_OBSOLETE nsInputStream& operator >> (nsInputStream&, nsPersistentFileDescriptor&);
00661               // reads the data from a file
00662        friend NS_COM_OBSOLETE nsOutputStream& operator << (nsOutputStream&, const nsPersistentFileDescriptor&);
00663            // writes the data to a file
00664         friend class nsFileSpec;
00665 
00666         void                    GetData(nsAFlatCString& outData) const;
00667         void                    SetData(const nsAFlatCString& inData);
00668         void                    SetData(const char* inData, PRInt32 inSize);
00669 
00670     //--------------------------------------------------
00671     // Data
00672     //--------------------------------------------------
00673 
00674     protected:
00675 
00676         nsSimpleCharString      mDescriptorString;
00677 
00678 }; // class nsPersistentFileDescriptor
00679 
00680 //========================================================================================
00681 class NS_COM_OBSOLETE nsDirectoryIterator
00682 //  Example:
00683 //
00684 //       nsFileSpec parentDir(...); // directory over whose children we shall iterate
00685 //       for (nsDirectoryIterator i(parentDir, PR_FALSE); i.Exists(); i++)
00686 //       {
00687 //              // do something with i.Spec()
00688 //       }
00689 //
00690 //            - or -
00691 //
00692 //       for (nsDirectoryIterator i(parentDir, PR_TRUE); i.Exists(); i--)
00693 //       {
00694 //              // do something with i.Spec()
00695 //       }
00696 //       This one passed the PR_TRUE flag which will resolve any symlink encountered.
00697 //========================================================================================
00698 {
00699        public:
00700                                    nsDirectoryIterator( const nsFileSpec& parent,
00701                                                            PRBool resoveSymLinks);
00702 #if !defined(XP_MAC)
00703        // Macintosh currently doesn't allocate, so needn't clean up.
00704            virtual                 ~nsDirectoryIterator();
00705 #endif
00706            PRBool                  Exists() const { return mExists; }
00707            nsDirectoryIterator&    operator ++(); // moves to the next item, if any.
00708            nsDirectoryIterator&    operator ++(int) { return ++(*this); } // post-increment.
00709            nsDirectoryIterator&    operator --(); // moves to the previous item, if any.
00710            nsDirectoryIterator&    operator --(int) { return --(*this); } // post-decrement.
00711                                    operator nsFileSpec&() { return mCurrent; }
00712            
00713            nsFileSpec&             Spec() { return mCurrent; }
00714             
00715        private:
00716 
00717 #if defined(XP_MAC)
00718         OSErr                   SetToIndex();
00719 #endif
00720 
00721     //--------------------------------------------------
00722     // Data
00723     //--------------------------------------------------
00724 
00725        private:
00726 
00727            nsFileSpec              mCurrent;
00728            PRBool                  mExists;
00729         PRBool                  mResoveSymLinks;
00730 
00731 #if (defined(XP_UNIX) || defined(XP_BEOS) || defined (XP_WIN) || defined(XP_OS2))
00732            nsFileSpec                      mStarting;
00733 #endif
00734         
00735 #if defined(XP_MAC)
00736            short                                       mVRefNum;
00737            long                                        mParID;
00738            short         mIndex;
00739            short         mMaxIndex;
00740 #elif defined(XP_UNIX) || defined(XP_BEOS)
00741            DIR*                    mDir;
00742 #elif defined(XP_WIN) || defined(XP_OS2)
00743         PRDir*                  mDir; // XXX why not use PRDir for Unix too?
00744 #endif
00745 }; // class nsDirectoryIterator
00746 
00747 //========================================================================================
00748 class NS_COM_OBSOLETE nsNSPRPath
00749 //  This class will allow you to pass any one of the nsFile* classes directly into NSPR
00750 //  without the need to worry about whether you have the right kind of filepath or not.
00751 //  It will also take care of cleaning up any allocated memory. 
00752 //========================================================================================
00753 {
00754 public:
00755     NS_EXPLICIT                  nsNSPRPath(const nsFileSpec& inSpec)
00756                                      : mFilePath(inSpec), modifiedNSPRPath(nsnull) {}
00757     NS_EXPLICIT                  nsNSPRPath(const nsFileURL& inURL)
00758                                      : mFilePath(inURL), modifiedNSPRPath(nsnull) {}
00759     NS_EXPLICIT                  nsNSPRPath(const nsFilePath& inUnixPath)
00760                                      : mFilePath(inUnixPath), modifiedNSPRPath(nsnull) {}
00761     
00762     virtual                      ~nsNSPRPath();    
00763  
00764                                  operator const char*() const;
00765                                     // Returns the path
00766                                     // that NSPR file routines expect on each platform.
00767                                     // Concerning constness, this can modify
00768                                     // modifiedNSPRPath, but it's really just "mutable". 
00769 
00770     //--------------------------------------------------
00771     // Data
00772     //--------------------------------------------------
00773 
00774 private:
00775 
00776     nsFilePath                   mFilePath;
00777     char*                        modifiedNSPRPath; // Currently used only on XP_WIN,XP_OS2
00778 }; // class nsNSPRPath
00779 
00780 
00781 NS_COM_OBSOLETE nsresult NS_FileSpecToIFile(nsFileSpec* fileSpec, nsILocalFile* *result);
00782 
00783 #endif //  _FILESPEC_H_