X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0b70c946a39362f054e0248d759dd2e6eb1137d9..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/file.h diff --git a/interface/wx/file.h b/interface/wx/file.h index 0b41f1c4b8..8eeab558c5 100644 --- a/interface/wx/file.h +++ b/interface/wx/file.h @@ -2,33 +2,10 @@ // Name: file.h // Purpose: interface of wxTempFile, wxFile // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -//@{ -/** - These constants define the file access rights and are used with wxFile::Create and wxFile::Open. -*/ -#define wxS_IRUSR 00400 -#define wxS_IWUSR 00200 -#define wxS_IXUSR 00100 - -#define wxS_IRGRP 00040 -#define wxS_IWGRP 00020 -#define wxS_IXGRP 00010 - -#define wxS_IROTH 00004 -#define wxS_IWOTH 00002 -#define wxS_IXOTH 00001 - -/** Default mode for the new files: corresponds to umask 022 */ -#define wxS_DEFAULT (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH) -//@} - - - /** @class wxTempFile @@ -53,12 +30,12 @@ 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 don't call neither of Commit() and Discard(), the destructor will + 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). + 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. @@ -71,12 +48,14 @@ class wxTempFile public: /** Associates wxTempFile with the file to be replaced and opens it. - You should use IsOpened() to verify if the constructor succeeded. + + @warning + You should use IsOpened() to verify that the constructor succeeded. */ wxTempFile(const wxString& strName); /** - Destructor calls Discard() if temporary file is still opened. + Destructor calls Discard() if temporary file is still open. */ ~wxTempFile(); @@ -85,17 +64,29 @@ public: 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 either the old file couldn't be deleted or that the new file + either that the old file couldn't be deleted or that the new file couldn't be renamed to the old name. */ bool Commit(); /** - Discard changes: the old file contents is not changed, temporary file is - deleted. + Discard changes: the old file contents are not changed, the temporary + file is deleted. */ void Discard(); + /** + 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 Flush(); + /** Returns @true if the file was successfully opened. */ @@ -104,9 +95,8 @@ public: /** Returns the length of the file. - This method may return wxInvalidOffset if the length couldn't be - determined or also 0 even for non-empty files if the file is not - seekable. + 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. @@ -130,7 +120,7 @@ public: wxSeekMode mode = wxFromStart); /** - Returns the current position or wxInvalidOffset if file is not opened or + Returns the current position or ::wxInvalidOffset if file is not opened or if another error occurred. */ wxFileOffset Tell() const; @@ -149,20 +139,11 @@ public: /** @class wxFile - A wxFile performs raw file I/O. - - This is a very small class designed to minimize the overhead of using it - in fact, - there is hardly any overhead at all, but using it brings you automatic error - checking and hides differences between platforms and compilers. - - wxFile also automatically closes the file in its destructor making it unnecessary - to worry about forgetting to do it. - A wxFile performs raw file I/O. This is a very small class designed to minimize the overhead of using it - in fact, there is hardly any overhead at all, but using it brings you automatic error checking and hides differences between platforms and compilers. wxFile also automatically closes the file in - its destructor making it unnecessary to worry about forgetting to do it. + its destructor so you won't forget to do so. wxFile is a wrapper around @c file descriptor. - see also wxFFile for a wrapper around @c FILE structure. @@ -191,12 +172,12 @@ public: or test if it can be opened for writing with Access(). */ write, - /** Open file for reading and writing; can not be used with Access() */ + /** Open file for reading and writing; cannot be used with Access() */ read_write, /** Open file for appending: the file is opened for writing, but the old contents - of the file is not erased and the file pointer is initially placed at the end - of the file; can not be used with Access(). + of the file are not erased and the file pointer is initially placed at the end + of the file; cannot be used with Access(). This is the same as OpenMode::write if the file doesn't exist. */ @@ -227,6 +208,9 @@ public: The filename. @param mode The mode in which to open the file. + + @warning + You should use IsOpened() to verify that the constructor succeeded. */ wxFile(const wxString& filename, wxFile::OpenMode mode = wxFile::read); @@ -242,10 +226,36 @@ public: /** Destructor will close the file. - @note it is not virtual so you should not use wxFile polymorphically. + @note This destructor is not virtual so you should not use wxFile polymorphically. */ ~wxFile(); + /** + Returns the error code for the last unsuccessful operation. + + The error code is system-dependent and corresponds to the value of the + standard @c errno variable when the last error occurred. + + Notice that only simple accessors such as IsOpened() and Eof() (and + this method itself) don't modify the last error value, all other + methods can potentially change it if an error occurs, including the + const ones such as Tell() or Length(). + + @since 2.9.2 + + @see ClearLastError() + */ + int GetLastError() const; + + /** + Resets the error code. + + GetLastError() will return 0 until the next error occurs. + + @since 2.9.2 + */ + void ClearLastError(); + /** This function verifies if we may access the given file in specified mode. Only values of @c wxFile::read or @c wxFile::write really make sense here. @@ -254,7 +264,7 @@ public: /** Attaches an existing file descriptor to the wxFile object. - Example of predefined file descriptors are 0, 1 and 2 which correspond to + Examples of predefined file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and have symbolic names of @c wxFile::fd_stdin, @c wxFile::fd_stdout and @c wxFile::fd_stderr). @@ -266,7 +276,7 @@ public: /** Closes the file. */ - void Close(); + bool Close(); /** Creates a file for writing. @@ -274,8 +284,8 @@ public: If the file already exists, setting @b overwrite to @true will ensure it is overwritten. - @a access may be an OR combination of the file access values - like ::wxS_IRUSR, ::wxS_IWUSR, etc, etc. + @a access may be an OR combination of the ::wxPosixPermissions enumeration + values. */ bool Create(const wxString& filename, bool overwrite = false, @@ -290,7 +300,7 @@ public: /** Returns @true if the end of the file has been reached. - Note that the behaviour of the file pointer based class wxFFile is + Note that the behaviour of the file pointer-based class wxFFile is different as wxFFile::Eof() will return @true here only if an attempt has been made to read @b past the last byte of the file, while wxFile::Eof() will return @true even before such attempt is made if the @@ -298,7 +308,7 @@ public: Note also that this function doesn't work on unseekable file descriptors (examples include pipes, terminals and sockets under Unix) and an attempt to - use it will result in an error message in such case. + use it will result in an error message. So, to read the entire file into memory, you should write a loop which uses Read() repeatedly and tests its return condition instead of using Eof() @@ -308,7 +318,7 @@ public: /** Returns @true if the given name specifies an existing regular file - (not a directory or a link) + (not a directory or a link). */ static bool Exists(const wxString& filename); @@ -343,9 +353,11 @@ public: The filename. @param mode The mode in which to open the file. + @param access + An OR-combination of ::wxPosixPermissions enumeration values. */ - bool Open(const wxString& filename, - wxFile::OpenMode mode = wxFile::read); + bool Open(const wxString& filename, wxFile::OpenMode mode = wxFile::read, + int access = wxS_DEFAULT); /** Reads from the file into a memory buffer. @@ -355,9 +367,26 @@ public: @param count Bytes to read - @return The number of bytes read, or the symbol wxInvalidOffset. + @return The number of bytes read, or the symbol ::wxInvalidOffset. + */ + ssize_t Read(void* buffer, size_t count); + + /** + Reads the entire contents of the file into a string. + + @param str + Non-@NULL pointer to a string to read data into. + @param conv + Conversion object to use in Unicode build; by default supposes + that file contents is encoded in UTF-8 but falls back to the + current locale encoding (or Latin-1 if it is UTF-8 too) if it is + not. + + @return @true if file was read successfully, @false otherwise. + + @since 2.9.5 */ - size_t Read(void* buffer, size_t count); + bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto()); /** Seeks to the specified position. @@ -367,7 +396,7 @@ public: @param mode One of wxFromStart, wxFromEnd, wxFromCurrent. - @return The actual offset position achieved, or wxInvalidOffset on + @return The actual offset position achieved, or ::wxInvalidOffset on failure. */ wxFileOffset Seek(wxFileOffset ofs, @@ -381,13 +410,13 @@ public: @param ofs Number of bytes before the end of the file. - @return The actual offset position achieved, or wxInvalidOffset on + @return The actual offset position achieved, or ::wxInvalidOffset on failure. */ wxFileOffset SeekEnd(wxFileOffset ofs = 0); /** - Returns the current position or wxInvalidOffset if file is not opened or + Returns the current position or ::wxInvalidOffset if file is not opened or if another error occurred. */ wxFileOffset Tell() const;