src/CFile.h

   1 //
   2 // This file is part of the aMule Project.
   3 //
   4 // Copyright (c) 2003-2008 aMule Team ( admin@amule.org / http://www.amule.org )
   5 // Copyright (c) 1998 Vadim Zeitlin ( zeitlin@dptmaths.ens-cachan.fr )
   6 //
   7 // Any parts of this program derived from the xMule, lMule or eMule project,
   8 // or contributed by third-party developers are copyrighted by their
   9 // respective authors.
  10 //
  11 // This program is free software; you can redistribute it and/or modify
  12 // it under the terms of the GNU General Public License as published by
  13 // the Free Software Foundation; either version 2 of the License, or
  14 // (at your option) any later version.
  15 //
  16 // This program is distributed in the hope that it will be useful,
  17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 // GNU General Public License for more details.
  20 //
  21 // You should have received a copy of the GNU General Public License
  22 // along with this program; if not, write to the Free Software
  23 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
  24 //
  25
  26 #ifndef CFILE_H
  27 #define CFILE_H
  28
  29 #include <common/Path.h>        // Needed for CPath
  30 #include "SafeFile.h"           // Needed for CFileDataIO
  31
  32 #include <wx/file.h>            // Needed for constants
  33
  34
  35 /**
  36  * This class is a modified version of the wxFile class.
  37  *
  38  * In addition to implementing the CFileDataIO interface,
  39  * it offers improved support for UTF8 filenames and 64b
  40  * file-IO on both windows and unix-like systems.
  41  *
  42  * @see wxFile
  43  */
  44 class CFile : public CFileDataIO
  45 {
  46 public:
  47         //! Standard values for file descriptor
  48         enum { fd_invalid = -1, fd_stdin, fd_stdout, fd_stderr };
  49
  50         /** @see wxFile::OpenMode */
  51         enum OpenMode { read, write, read_write, write_append, write_excl };
  52
  53
  54         /**
  55          * Creates a closed file.
  56          */
  57         CFile();
  58
  59         /**
  60          * Constructor, calls Open on the specified file.
  61          *
  62          * To check if the file was successfully opened, a
  63          * call to IsOpened() is required.
  64          */
  65         CFile(const CPath& path, OpenMode mode = read);
  66         CFile(const wxString& path, OpenMode mode = read);
  67
  68         /**
  69          * Destructor, closes the file if opened.
  70          */
  71         virtual ~CFile();
  72
  73
  74         /**
  75          * Opens a file.
  76          *
  77          * @param path The full or relative path to the file.
  78          * @param mode The opening mode.
  79          * @param accessMode The permissions in case a new file is created.
  80          * @return True if the file was opened, false otherwise.
  81          *
  82          * Calling Open with the openmodes 'write' or 'write_append' will
  83          * create the specified file if it does not already exist.
  84          *
  85          * If an accessMode is not explicitly specified, the accessmode
  86          * specified via CPreferences::GetFilePermissions will be used.
  87          */
  88         bool Open(const CPath& path, OpenMode mode = read, int accessMode = wxS_DEFAULT);
  89         bool Open(const wxString& path, OpenMode mode = read, int accessMode = wxS_DEFAULT);
  90
  91         /**
  92          * Calling Create is equivilant of calling open with OpenMode 'write'.
  93          *
  94          * @param overwrite Specifies if the target file should be overwritten,
  95          *                  in case that it already exists.
  96          *
  97          * @see CFile::Open
  98          */
  99         bool Create(const CPath& path, bool overwrite = false, int accessMode = wxS_DEFAULT);
 100         bool Create(const wxString& path, bool overwrite = false, int accessMode = wxS_DEFAULT);
 101
 102         /**
 103          * Closes the file.
 104          *
 105          * Note that calling Close on an closed file
 106          * is an illegal operation.
 107          */
 108         bool Close();
 109
 110
 111         /**
 112          * Returns the file descriptior assosiated with the file.
 113          *
 114          * Note that direct manipulation of the descriptor should
 115          * be avoided! That's what this class is for.
 116          */
 117         int  fd() const;
 118
 119         /**
 120          * Flushes data not yet written.
 121          *
 122          * Note that calling Flush on an closed file
 123          * is an illegal operation.
 124          */
 125         bool Flush();
 126
 127
 128         /**
 129          * @see CSafeFileIO::GetLength
 130          *
 131          * Note that calling GetLength on a closed file
 132          * is an illegal operation.
 133          */
 134         virtual uint64 GetLength() const;
 135
 136         /**
 137          * Resizes the file to the specified length.
 138          */
 139         bool SetLength(size_t newLength);
 140
 141         /**
 142          * @see CSafeFileIO::GetPosition
 143          *
 144          * Note that calling GetPosition on a closed file
 145          * is an illegal operation.
 146          */
 147         virtual uint64 GetPosition() const;
 148
 149         /**
 150          * Returns the current available bytes to read on the file before EOF
 151          *
 152          */
 153         virtual uint64 GetAvailable() const;
 154
 155         /**
 156          * Returns the path of the currently opened file.
 157          *
 158          * Calling this function on an closed file is
 159          * an illegal operation.
 160          */
 161         const CPath& GetFilePath() const;
 162
 163
 164         /**
 165          * Returns true if the file is opened, false otherwise.
 166          */
 167         bool IsOpened() const;
 168
 169 protected:
 170         /** @see CFileDataIO::doRead **/
 171         virtual sint64 doRead(void* buffer, size_t count) const;
 172         /** @see CFileDataIO::doWrite **/
 173         virtual sint64 doWrite(const void* buffer, size_t count);
 174         /** @see CFileDataIO::doSeek **/
 175         virtual sint64 doSeek(sint64 offset) const;
 176
 177 private:
 178         //! A CFile is neither copyable nor assignable.
 179         //@{
 180         CFile(const CFile&);
 181         CFile& operator=(const CFile&);
 182         //@}
 183
 184         //! File descriptor or 'fd_invalid' if not opened
 185         int m_fd;
 186
 187         //! The full path to the current file.
 188         CPath m_filePath;
 189 };
 190
 191
 192 /**
 193  * This exception is thrown by CFile if a seek or tell fails.
 194  */
 195 struct CSeekFailureException : public CIOFailureException {
 196         CSeekFailureException(const wxString& desc);
 197 };
 198
 199
 200 #endif // CFILE_H
 201 // File_checked_for_headers