|
Version: 3.1.0 |
#include <wx/file.h>
Detailed Description
wxTempFile provides a relatively safe way to replace the contents of the existing file.
The name is explained by the fact that it may be also used as just a temporary file if you don't replace the old file contents.
Usually, when a program replaces the contents of some file it first opens it for writing, thus losing all of the old data and then starts recreating it. This approach is not very safe because during the regeneration of the file bad things may happen: the program may find that there is an internal error preventing it from completing file generation, the user may interrupt it (especially if file generation takes long time) and, finally, any other external interrupts (power supply failure or a disk error) will leave you without either the original file or the new one.
wxTempFile addresses this problem by creating a temporary file which is meant to replace the original file - but only after it is fully written. So, if the user interrupts the program during the file generation, the old file won't be lost. Also, if the program discovers itself that it doesn't want to replace the old file there is no problem - in fact, wxTempFile will not replace the old file by default, you should explicitly call wxTempFile::Commit() to do it. Calling wxTempFile::Discard() explicitly discards any modifications: it closes and deletes the temporary file and leaves the original file unchanged. If you call neither Commit() nor Discard(), the destructor will call Discard() automatically.
To summarize: if you want to replace another file, create an instance of wxTempFile passing the name of the file to be replaced to the constructor. (You may also use default constructor and pass the file name to wxTempFile::Open.) Then you can write to wxTempFile using wxFile-like functions and later call wxTempFile::Commit() to replace the old file (and close this one) or call wxTempFile::Discard() to cancel the modifications.
Public Member Functions | |
| wxTempFile (const wxString &strName) | |
| Associates wxTempFile with the file to be replaced and opens it. More... | |
| ~wxTempFile () | |
| Destructor calls Discard() if temporary file is still open. More... | |
| bool | Commit () |
| Validate changes: deletes the old file of name m_strName and renames the new file to the old name. More... | |
| void | Discard () |
| Discard changes: the old file contents are not changed, the temporary file is deleted. More... | |
| bool | Flush () |
| Flush the data written to the file to disk. More... | |
| bool | IsOpened () const |
| Returns true if the file was successfully opened. More... | |
| wxFileOffset | Length () const |
| Returns the length of the file. More... | |
| bool | Open (const wxString &strName) |
| Open the temporary file, returns true on success, false if an error occurred. More... | |
| wxFileOffset | Seek (wxFileOffset ofs, wxSeekMode mode=wxFromStart) |
| Seeks to the specified position. More... | |
| wxFileOffset | Tell () const |
| Returns the current position or wxInvalidOffset if file is not opened or if another error occurred. More... | |
| bool | Write (const wxString &str, const wxMBConv &conv=wxConvUTF8) |
| Write to the file, return true on success, false on failure. More... | |
Constructor & Destructor Documentation
| wxTempFile::wxTempFile | ( | const wxString & | strName | ) |
Associates wxTempFile with the file to be replaced and opens it.
- Warning
- You should use IsOpened() to verify that the constructor succeeded.
| wxTempFile::~wxTempFile | ( | ) |
Destructor calls Discard() if temporary file is still open.
Member Function Documentation
| bool wxTempFile::Commit | ( | ) |
Validate changes: deletes the old file of name m_strName and renames the new file to the old name.
Returns true if both actions succeeded.
If false is returned it may unfortunately mean two quite different things: either that the old file couldn't be deleted or that the new file couldn't be renamed to the old name.
| void wxTempFile::Discard | ( | ) |
Discard changes: the old file contents are not changed, the temporary file is deleted.
| bool wxTempFile::Flush | ( | ) |
Flush the data written to the file to disk.
This simply calls wxFile::Flush() for the underlying file and may be necessary with file systems such as XFS and Ext4 under Linux. Calling this function may however have serious performance implications and also is not necessary with many other file systems so it is not done by default – but you can call it before calling Commit() to absolutely ensure that the data was indeed written to the disk correctly.
| bool wxTempFile::IsOpened | ( | ) | const |
Returns true if the file was successfully opened.
| wxFileOffset wxTempFile::Length | ( | ) | const |
Returns the length of the file.
This method may return wxInvalidOffset if the length couldn't be determined or 0 even for non-empty files if the file is not seekable.
In general, the only way to determine if the file for which this function returns 0 is really empty or not is to try reading from it.
| bool wxTempFile::Open | ( | const wxString & | strName | ) |
Open the temporary file, returns true on success, false if an error occurred.
strName is the name of file to be replaced. The temporary file is always created in the directory where strName is. In particular, if strName doesn't include the path, it is created in the current directory and the program should have write access to it for the function to succeed.
| wxFileOffset wxTempFile::Seek | ( | wxFileOffset | ofs, |
| wxSeekMode | mode = wxFromStart |
||
| ) |
Seeks to the specified position.
| wxFileOffset wxTempFile::Tell | ( | ) | const |
Returns the current position or wxInvalidOffset if file is not opened or if another error occurred.