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