src/CFile.h

   1 //
   2 // This file is part of the aMule Project.
   3 //
   4 // Copyright (c) 2003-2011 aMule Team ( admin@amule.org / http://www.amule.org )
   5 // Copyright (c) 1998-2011 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 #ifdef _MSC_VER  // silly warnings about deprecated functions
  35 #pragma warning(disable:4996)
  36 #endif
  37
  38 /**
  39  * This class is a modified version of the wxFile class.
  40  *
  41  * In addition to implementing the CFileDataIO interface,
  42  * it offers improved support for UTF8 filenames and 64b
  43  * file-IO on both windows and unix-like systems.
  44  *
  45  * @see wxFile
  46  */
  47 class CFile : public CFileDataIO
  48 {
  49 public:
  50         //! Standard values for file descriptor
  51         enum { fd_invalid = -1, fd_stdin, fd_stdout, fd_stderr };
  52
  53         /** @see wxFile::OpenMode */
  54         enum OpenMode { read, write, read_write, write_append, write_excl, write_safe };
  55
  56
  57         /**
  58          * Creates a closed file.
  59          */
  60         CFile();
  61
  62         /**
  63          * Constructor, calls Open on the specified file.
  64          *
  65          * To check if the file was successfully opened, a
  66          * call to IsOpened() is required.
  67          */
  68         CFile(const CPath& path, OpenMode mode = read);
  69         CFile(const wxString& path, OpenMode mode = read);
  70
  71         /**
  72          * Destructor, closes the file if opened.
  73          */
  74         virtual ~CFile();
  75
  76
  77         /**
  78          * Opens a file.
  79          *
  80          * @param path The full or relative path to the file.
  81          * @param mode The opening mode.
  82          * @param accessMode The permissions in case a new file is created.
  83          * @return True if the file was opened, false otherwise.
  84          *
  85          * Calling Open with the openmodes 'write' or 'write_append' will
  86          * create the specified file if it does not already exist.
  87          *
  88          * Calling Open with the openmode 'write_safe' will append ".new"
  89          * to the file name and otherwise work like 'write'.
  90          * On close it will be renamed to the original name.
  91          * Close() has to be called manually - destruct won't rename the file!
  92          *
  93          * If an accessMode is not explicitly specified, the accessmode
  94          * specified via CPreferences::GetFilePermissions will be used.
  95          */
  96         bool Open(const CPath& path, OpenMode mode = read, int accessMode = wxS_DEFAULT);
  97         bool Open(const wxString& path, OpenMode mode = read, int accessMode = wxS_DEFAULT);
  98
  99         /**
 100          * Reopens a file which was opened and closed before.
 101          *
 102          * @param mode The opening mode.
 103          *
 104          * The filename used for last open is used again.
 105          * No return value - function throws on failure.
 106          */
 107         void Reopen(OpenMode mode);
 108
 109         /**
 110          * Calling Create is equivilant of calling open with OpenMode 'write'.
 111          *
 112          * @param overwrite Specifies if the target file should be overwritten,
 113          *                  in case that it already exists.
 114          *
 115          * @see CFile::Open
 116          */
 117         bool Create(const CPath& path, bool overwrite = false, int accessMode = wxS_DEFAULT);
 118         bool Create(const wxString& path, bool overwrite = false, int accessMode = wxS_DEFAULT);
 119
 120         /**
 121          * Closes the file.
 122          *
 123          * Note that calling Close on an closed file
 124          * is an illegal operation.
 125          */
 126         bool Close();
 127
 128
 129         /**
 130          * Returns the file descriptior assosiated with the file.
 131          *
 132          * Note that direct manipulation of the descriptor should
 133          * be avoided! That's what this class is for.
 134          */
 135         int  fd() const;
 136
 137         /**
 138          * Flushes data not yet written.
 139          *
 140          * Note that calling Flush on an closed file
 141          * is an illegal operation.
 142          */
 143         bool Flush();
 144
 145
 146         /**
 147          * @see CSafeFileIO::GetLength
 148          *
 149          * Note that calling GetLength on a closed file
 150          * is an illegal operation.
 151          */
 152         virtual uint64 GetLength() const;
 153
 154         /**
 155          * Resizes the file to the specified length.
 156          */
 157         bool SetLength(uint64 newLength);
 158
 159         /**
 160          * @see CSafeFileIO::GetPosition
 161          *
 162          * Note that calling GetPosition on a closed file
 163          * is an illegal operation.
 164          */
 165         virtual uint64 GetPosition() const;
 166
 167         /**
 168          * Returns the current available bytes to read on the file before EOF
 169          *
 170          */
 171         virtual uint64 GetAvailable() const;
 172
 173         /**
 174          * Returns the path of the currently opened file.
 175          *
 176          */
 177         const CPath& GetFilePath() const;
 178
 179
 180         /**
 181          * Returns true if the file is opened, false otherwise.
 182          */
 183         bool IsOpened() const;
 184
 185 protected:
 186         /** @see CFileDataIO::doRead **/
 187         virtual sint64 doRead(void* buffer, size_t count) const;
 188         /** @see CFileDataIO::doWrite **/
 189         virtual sint64 doWrite(const void* buffer, size_t count);
 190         /** @see CFileDataIO::doSeek **/
 191         virtual sint64 doSeek(sint64 offset) const;
 192
 193 private:
 194         //! A CFile is neither copyable nor assignable.
 195         //@{
 196         CFile(const CFile&);
 197         CFile& operator=(const CFile&);
 198         //@}
 199
 200         //! File descriptor or 'fd_invalid' if not opened
 201         int m_fd;
 202
 203         //! The full path to the current file.
 204         CPath m_filePath;
 205
 206         //! Are we using safe write mode?
 207         bool m_safeWrite;
 208 };
 209
 210
 211 /**
 212  * This exception is thrown by CFile if a seek or tell fails.
 213  */
 214 struct CSeekFailureException : public CIOFailureException {
 215         CSeekFailureException(const wxString& desc);
 216 };
 217
 218
 219 #endif // CFILE_H
 220 // File_checked_for_headers