X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9cfebe8ccc68d126a5a85bd63e21940a2bdc01d0..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/file.h?ds=sidebyside diff --git a/interface/wx/file.h b/interface/wx/file.h index bc1fc15016..8eeab558c5 100644 --- a/interface/wx/file.h +++ b/interface/wx/file.h @@ -2,64 +2,10 @@ // Name: file.h // Purpose: interface of wxTempFile, wxFile // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/** - We redefine these constants here because S_IREAD &c are _not_ standard. - However, we do assume that the values correspond to the Unix umask bits. -*/ -enum wxPosixPermissions -{ - /// standard Posix names for these permission flags - //@{ - wxS_IRUSR = 00400, - wxS_IWUSR = 00200, - wxS_IXUSR = 00100, - - wxS_IRGRP = 00040, - wxS_IWGRP = 00020, - wxS_IXGRP = 00010, - - wxS_IROTH = 00004, - wxS_IWOTH = 00002, - wxS_IXOTH = 00001, - //@} - - /// longer but more readable synonims for the constants above - //@{ - wxPOSIX_USER_READ = wxS_IRUSR, - wxPOSIX_USER_WRITE = wxS_IWUSR, - wxPOSIX_USER_EXECUTE = wxS_IXUSR, - - wxPOSIX_GROUP_READ = wxS_IRGRP, - wxPOSIX_GROUP_WRITE = wxS_IWGRP, - wxPOSIX_GROUP_EXECUTE = wxS_IXGRP, - - wxPOSIX_OTHERS_READ = wxS_IROTH, - wxPOSIX_OTHERS_WRITE = wxS_IWOTH, - wxPOSIX_OTHERS_EXECUTE = wxS_IXOTH, - //@} - - /// Default mode for the new files: allow reading/writing them to everybody but - /// the effective file mode will be set after ANDing this value with umask and - /// so won't include wxS_IW{GRP,OTH} for the default 022 umask value - wxS_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | \ - wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | \ - wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE), - - /// Default mode for the new directories (see wxFileName::Mkdir): allow - /// reading/writing/executing them to everybody, but just like wxS_DEFAULT - /// the effective directory mode will be set after ANDing this value with umask - wxS_DIR_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | wxPOSIX_USER_EXECUTE | \ - wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | wxPOSIX_GROUP_EXECUTE | \ - wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE | wxPOSIX_OTHERS_EXECUTE) -}; - - - /** @class wxTempFile @@ -102,6 +48,8 @@ class wxTempFile public: /** Associates wxTempFile with the file to be replaced and opens it. + + @warning You should use IsOpened() to verify that the constructor succeeded. */ wxTempFile(const wxString& strName); @@ -127,6 +75,18 @@ public: */ 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. */ @@ -135,7 +95,7 @@ public: /** Returns the length of the file. - This method may return wxInvalidOffset if the length couldn't be + 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 @@ -160,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; @@ -212,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 are not erased and the file pointer is initially placed at the end - of the file; can not be used with Access(). + of the file; cannot be used with Access(). This is the same as OpenMode::write if the file doesn't exist. */ @@ -248,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); @@ -267,6 +230,32 @@ public: */ ~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. @@ -365,7 +354,7 @@ public: @param mode The mode in which to open the file. @param access - An OR-combination of wxPosixPermissions enumeration values. + An OR-combination of ::wxPosixPermissions enumeration values. */ bool Open(const wxString& filename, wxFile::OpenMode mode = wxFile::read, int access = wxS_DEFAULT); @@ -378,10 +367,27 @@ 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 + */ + bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto()); + /** Seeks to the specified position. @@ -390,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, @@ -404,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;