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