interface/file.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        file.h
   3 // Purpose:     documentation for wxTempFile class
   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     @class wxFile
 124     @wxheader{file.h}
 125
 126     A wxFile performs raw file I/O. This is a very small class designed to
 127     minimize the overhead of using it - in fact, there is hardly any overhead at
 128     all, but using it brings you automatic error checking and hides differences
 129     between platforms and compilers. wxFile also automatically closes the file in
 130     its destructor making it unnecessary to worry about forgetting to do it.
 131     wxFile is a wrapper around @c file descriptor. - see also
 132     wxFFile for a wrapper around @c FILE structure.
 133
 134     @c wxFileOffset is used by the wxFile functions which require offsets as
 135     parameter or return them. If the platform supports it, wxFileOffset is a typedef
 136     for a native 64 bit integer, otherwise a 32 bit integer is used for
 137     wxFileOffset.
 138
 139     @library{wxbase}
 140     @category{file}
 141 */
 142 class wxFile
 143 {
 144 public:
 145     //@{
 146     /**
 147         Associates the file with the given file descriptor, which has already been
 148         opened.
 149
 150         @param filename
 151             The filename.
 152         @param mode
 153             The mode in which to open the file. May be one of read(), write() and
 154         wxFile::read_write.
 155         @param fd
 156             An existing file descriptor (see Attach() for the list of predefined
 157         descriptors)
 158     */
 159     wxFile();
 160     wxFile(const wxString& filename,
 161            wxFile::OpenMode mode = wxFile::read);
 162     wxFile(int fd);
 163     //@}
 164
 165     /**
 166         Destructor will close the file.
 167         @b NB: it is not virtual so you should not use wxFile polymorphically.
 168     */
 169     ~wxFile();
 170
 171     /**
 172         This function verifies if we may access the given file in specified mode. Only
 173         values of read() or write() really make sense here.
 174     */
 175     static bool Access(const wxString& name, OpenMode mode);
 176
 177     /**
 178         Attaches an existing file descriptor to the wxFile object. Example of predefined
 179         file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr
 180         (and
 181         have symbolic names of @b wxFile::fd_stdin, @b wxFile::fd_stdout and @b
 182         wxFile::fd_stderr).
 183         The descriptor should be already opened and it will be closed by wxFile
 184         object.
 185     */
 186     void Attach(int fd);
 187
 188     /**
 189         Closes the file.
 190     */
 191     void Close();
 192
 193     /**
 194         Creates a file for writing. If the file already exists, setting @b overwrite to
 195         @true
 196         will ensure it is overwritten.
 197     */
 198     bool Create(const wxString& filename, bool overwrite = false,
 199                 int access = wxS_DEFAULT);
 200
 201     /**
 202         Get back a file descriptor from wxFile object - the caller is responsible for
 203         closing the file if this
 204         descriptor is opened. IsOpened() will return @false after call to Detach().
 205     */
 206     void Detach();
 207
 208     /**
 209         Returns @true if the end of the file has been reached.
 210         Note that the behaviour of the file pointer based class
 211         wxFFile is different as wxFFile::Eof
 212         will return @true here only if an attempt has been made to read
 213         @e past the last byte of the file, while wxFile::Eof() will return @true
 214         even before such attempt is made if the file pointer is at the last position
 215         in the file.
 216         Note also that this function doesn't work on unseekable file descriptors
 217         (examples include pipes, terminals and sockets under Unix) and an attempt to
 218         use it will result in an error message in such case. So, to read the entire
 219         file into memory, you should write a loop which uses
 220         Read() repeatedly and tests its return condition instead
 221         of using Eof() as this will not work for special files under Unix.
 222     */
 223     bool Eof() const;
 224
 225     /**
 226         Returns @true if the given name specifies an existing regular file (not a
 227         directory or a link)
 228     */
 229     static bool Exists(const wxString& filename);
 230
 231     /**
 232         Flushes the file descriptor.
 233         Note that Flush() is not implemented on some Windows compilers
 234         due to a missing fsync function, which reduces the usefulness of this function
 235         (it can still be called but it will do nothing on unsupported compilers).
 236     */
 237     bool Flush();
 238
 239     /**
 240         Returns the type of the file. Possible return values are:
 241     */
 242     wxFileKind GetKind() const;
 243
 244     /**
 245         Returns @true if the file has been opened.
 246     */
 247     bool IsOpened() const;
 248
 249     /**
 250         Returns the length of the file.
 251     */
 252     wxFileOffset Length() const;
 253
 254     /**
 255         Opens the file, returning @true if successful.
 256
 257         @param filename
 258             The filename.
 259         @param mode
 260             The mode in which to open the file. May be one of read(), write() and
 261         wxFile::read_write.
 262     */
 263     bool Open(const wxString& filename,
 264               wxFile::OpenMode mode = wxFile::read);
 265
 266     //@{
 267     /**
 268         if there was an error.
 269     */
 270     size_t Read(void* buffer, size_t count);
 271     Parameters Return value
 272     The number of bytes read, or the symbol wxInvalidOffset();
 273     //@}
 274
 275     /**
 276         Seeks to the specified position.
 277
 278         @param ofs
 279             Offset to seek to.
 280         @param mode
 281             One of wxFromStart, wxFromEnd, wxFromCurrent.
 282
 283         @returns The actual offset position achieved, or wxInvalidOffset on
 284                  failure.
 285     */
 286     wxFileOffset Seek(wxFileOffset ofs,
 287                       wxSeekMode mode = wxFromStart);
 288
 289     /**
 290         Moves the file pointer to the specified number of bytes relative to the end of
 291         the file. For example, @c SeekEnd(-5) would position the pointer 5
 292         bytes before the end.
 293
 294         @param ofs
 295             Number of bytes before the end of the file.
 296
 297         @returns The actual offset position achieved, or wxInvalidOffset on
 298                  failure.
 299     */
 300     wxFileOffset SeekEnd(wxFileOffset ofs = 0);
 301
 302     /**
 303         Returns the current position or wxInvalidOffset if file is not opened or if
 304         another
 305         error occurred.
 306     */
 307     wxFileOffset Tell() const;
 308
 309     /**
 310         Writes the contents of the string to the file, returns @true on success.
 311         The second argument is only meaningful in Unicode build of wxWidgets when
 312         @a conv is used to convert @a s to multibyte representation.
 313         Note that this method only works with @c NUL-terminated strings, if you want
 314         to write data with embedded @c NULs to the file you should use the other
 315         @ref write() "Write() overload".
 316     */
 317     bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8);
 318
 319     /**
 320         Returns the file descriptor associated with the file.
 321     */
 322     int fd() const;
 323 };