interface/file.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        file.h
   3 // Purpose:     interface of wxTempFile
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTempFile
  11     @wxheader{file.h}
  12
  13     wxTempFile provides a relatively safe way to replace the contents of the
  14     existing file. The name is explained by the fact that it may be also used as
  15     just a temporary file if you don't replace the old file contents.
  16
  17     Usually, when a program replaces the contents of some file it first opens it for
  18     writing, thus losing all of the old data and then starts recreating it. This
  19     approach is not very safe because during the regeneration of the file bad things
  20     may happen: the program may find that there is an internal error preventing it
  21     from completing file generation, the user may interrupt it (especially if file
  22     generation takes long time) and, finally, any other external interrupts (power
  23     supply failure or a disk error) will leave you without either the original file
  24     or the new one.
  25
  26     wxTempFile addresses this problem by creating a temporary file which is meant to
  27     replace the original file - but only after it is fully written. So, if the user
  28     interrupts the program during the file generation, the old file won't be lost.
  29     Also, if the program discovers itself that it doesn't want to replace the old
  30     file there is no problem - in fact, wxTempFile will @b not replace the old
  31     file by default, you should explicitly call wxTempFile::Commit
  32     to do it. Calling wxTempFile::Discard explicitly discards any
  33     modifications: it closes and deletes the temporary file and leaves the original
  34     file unchanged. If you don't call neither of Commit() and Discard(), the
  35     destructor will call Discard() automatically.
  36
  37     To summarize: if you want to replace another file, create an instance of
  38     wxTempFile passing the name of the file to be replaced to the constructor (you
  39     may also use default constructor and pass the file name to
  40     wxTempFile::Open). Then you can wxTempFile::write
  41     to wxTempFile using wxFile-like functions and later call
  42     Commit() to replace the old file (and close this one) or call Discard() to
  43     cancel
  44     the modifications.
  45
  46     @library{wxbase}
  47     @category{file}
  48 */
  49 class wxTempFile
  50 {
  51 public:
  52     /**
  53         Associates wxTempFile with the file to be replaced and opens it. You should use
  54         IsOpened() to verify if the constructor succeeded.
  55     */
  56     wxTempFile(const wxString& strName);
  57
  58     /**
  59         Destructor calls Discard() if temporary file
  60         is still opened.
  61     */
  62     ~wxTempFile();
  63
  64     /**
  65         Validate changes: deletes the old file of name m_strName and renames the new
  66         file to the old name. Returns @true if both actions succeeded. If @false is
  67         returned it may unfortunately mean two quite different things: either that
  68         either the old file couldn't be deleted or that the new file couldn't be renamed
  69         to the old name.
  70     */
  71     bool Commit();
  72
  73     /**
  74         Discard changes: the old file contents is not changed, temporary file is
  75         deleted.
  76     */
  77     void Discard();
  78
  79     /**
  80         Returns @true if the file was successfully opened.
  81     */
  82     bool IsOpened() const;
  83
  84     /**
  85         Returns the length of the file.
  86     */
  87     wxFileOffset Length() const;
  88
  89     /**
  90         Open the temporary file, returns @true on success, @false if an error
  91         occurred.
  92         @a strName is the name of file to be replaced. The temporary file is always
  93         created in the directory where @a strName is. In particular, if
  94         @a strName doesn't include the path, it is created in the current directory
  95         and the program should have write access to it for the function to succeed.
  96     */
  97     bool Open(const wxString& strName);
  98
  99     /**
 100         Seeks to the specified position.
 101     */
 102     wxFileOffset Seek(wxFileOffset ofs,
 103                       wxSeekMode mode = wxFromStart);
 104
 105     /**
 106         Returns the current position or wxInvalidOffset if file is not opened or if
 107         another
 108         error occurred.
 109     */
 110     wxFileOffset Tell() const;
 111
 112     /**
 113         Write to the file, return @true on success, @false on failure.
 114         The second argument is only meaningful in Unicode build of wxWidgets when
 115         @a conv is used to convert @a str to multibyte representation.
 116     */
 117     bool Write(const wxString& str,
 118                const wxMBConv& conv = wxConvUTF8);
 119 };
 120
 121
 122
 123 /**
 124     @class wxFile
 125     @wxheader{file.h}
 126
 127     A wxFile performs raw file I/O. This is a very small class designed to
 128     minimize the overhead of using it - in fact, there is hardly any overhead at
 129     all, but using it brings you automatic error checking and hides differences
 130     between platforms and compilers. wxFile also automatically closes the file in
 131     its destructor making it unnecessary to worry about forgetting to do it.
 132     wxFile is a wrapper around @c file descriptor. - see also
 133     wxFFile for a wrapper around @c FILE structure.
 134
 135     @c wxFileOffset is used by the wxFile functions which require offsets as
 136     parameter or return them. If the platform supports it, wxFileOffset is a typedef
 137     for a native 64 bit integer, otherwise a 32 bit integer is used for
 138     wxFileOffset.
 139
 140     @library{wxbase}
 141     @category{file}
 142 */
 143 class wxFile
 144 {
 145 public:
 146     //@{
 147     /**
 148         Associates the file with the given file descriptor, which has already been
 149         opened.
 150
 151         @param filename
 152             The filename.
 153         @param mode
 154             The mode in which to open the file. May be one of read(), write() and
 155         wxFile::read_write.
 156         @param fd
 157             An existing file descriptor (see Attach() for the list of predefined
 158         descriptors)
 159     */
 160     wxFile();
 161     wxFile(const wxString& filename,
 162            wxFile::OpenMode mode = wxFile::read);
 163     wxFile(int fd);
 164     //@}
 165
 166     /**
 167         Destructor will close the file.
 168         @b NB: it is not virtual so you should not use wxFile polymorphically.
 169     */
 170     ~wxFile();
 171
 172     /**
 173         This function verifies if we may access the given file in specified mode. Only
 174         values of read() or write() really make sense here.
 175     */
 176     static bool Access(const wxString& name, OpenMode mode);
 177
 178     /**
 179         Attaches an existing file descriptor to the wxFile object. Example of predefined
 180         file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr
 181         (and
 182         have symbolic names of @b wxFile::fd_stdin, @b wxFile::fd_stdout and @b
 183         wxFile::fd_stderr).
 184         The descriptor should be already opened and it will be closed by wxFile
 185         object.
 186     */
 187     void Attach(int fd);
 188
 189     /**
 190         Closes the file.
 191     */
 192     void Close();
 193
 194     /**
 195         Creates a file for writing. If the file already exists, setting @b overwrite to
 196         @true
 197         will ensure it is overwritten.
 198     */
 199     bool Create(const wxString& filename, bool overwrite = false,
 200                 int access = wxS_DEFAULT);
 201
 202     /**
 203         Get back a file descriptor from wxFile object - the caller is responsible for
 204         closing the file if this
 205         descriptor is opened. IsOpened() will return @false after call to Detach().
 206     */
 207     void Detach();
 208
 209     /**
 210         Returns @true if the end of the file has been reached.
 211         Note that the behaviour of the file pointer based class
 212         wxFFile is different as wxFFile::Eof
 213         will return @true here only if an attempt has been made to read
 214         @e past the last byte of the file, while wxFile::Eof() will return @true
 215         even before such attempt is made if the file pointer is at the last position
 216         in the file.
 217         Note also that this function doesn't work on unseekable file descriptors
 218         (examples include pipes, terminals and sockets under Unix) and an attempt to
 219         use it will result in an error message in such case. So, to read the entire
 220         file into memory, you should write a loop which uses
 221         Read() repeatedly and tests its return condition instead
 222         of using Eof() as this will not work for special files under Unix.
 223     */
 224     bool Eof() const;
 225
 226     /**
 227         Returns @true if the given name specifies an existing regular file (not a
 228         directory or a link)
 229     */
 230     static bool Exists(const wxString& filename);
 231
 232     /**
 233         Flushes the file descriptor.
 234         Note that Flush() is not implemented on some Windows compilers
 235         due to a missing fsync function, which reduces the usefulness of this function
 236         (it can still be called but it will do nothing on unsupported compilers).
 237     */
 238     bool Flush();
 239
 240     /**
 241         Returns the type of the file. Possible return values are:
 242     */
 243     wxFileKind GetKind() const;
 244
 245     /**
 246         Returns @true if the file has been opened.
 247     */
 248     bool IsOpened() const;
 249
 250     /**
 251         Returns the length of the file.
 252     */
 253     wxFileOffset Length() const;
 254
 255     /**
 256         Opens the file, returning @true if successful.
 257
 258         @param filename
 259             The filename.
 260         @param mode
 261             The mode in which to open the file. May be one of read(), write() and
 262         wxFile::read_write.
 263     */
 264     bool Open(const wxString& filename,
 265               wxFile::OpenMode mode = wxFile::read);
 266
 267     //@{
 268     /**
 269         if there was an error.
 270     */
 271     size_t Read(void* buffer, size_t count);
 272     Parameters Return value
 273     The number of bytes read, or the symbol wxInvalidOffset();
 274     //@}
 275
 276     /**
 277         Seeks to the specified position.
 278
 279         @param ofs
 280             Offset to seek to.
 281         @param mode
 282             One of wxFromStart, wxFromEnd, wxFromCurrent.
 283
 284         @returns The actual offset position achieved, or wxInvalidOffset on
 285                  failure.
 286     */
 287     wxFileOffset Seek(wxFileOffset ofs,
 288                       wxSeekMode mode = wxFromStart);
 289
 290     /**
 291         Moves the file pointer to the specified number of bytes relative to the end of
 292         the file. For example, @c SeekEnd(-5) would position the pointer 5
 293         bytes before the end.
 294
 295         @param ofs
 296             Number of bytes before the end of the file.
 297
 298         @returns The actual offset position achieved, or wxInvalidOffset on
 299                  failure.
 300     */
 301     wxFileOffset SeekEnd(wxFileOffset ofs = 0);
 302
 303     /**
 304         Returns the current position or wxInvalidOffset if file is not opened or if
 305         another
 306         error occurred.
 307     */
 308     wxFileOffset Tell() const;
 309
 310     /**
 311         Writes the contents of the string to the file, returns @true on success.
 312         The second argument is only meaningful in Unicode build of wxWidgets when
 313         @a conv is used to convert @a s to multibyte representation.
 314         Note that this method only works with @c NUL-terminated strings, if you want
 315         to write data with embedded @c NULs to the file you should use the other
 316         @ref write() "Write() overload".
 317     */
 318     bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8);
 319
 320     /**
 321         Returns the file descriptor associated with the file.
 322     */
 323     int fd() const;
 324 };
 325