Make storing non-trivial data in wxThreadSpecificInfo possible.

[wxWidgets.git] / interface / wx / file.h

diff --git a/interface/wx/file.h b/interface/wx/file.h
index 6b32e84dca1d95820ded6c9544b0e20c40317660..31ea6bdd4f9c26311a59d309b3aff0951c2096dc 100644 (file)
--- 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
 // 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
 
 /**
     @class wxTempFile
 


@@ -102,6 +48,8 @@ class wxTempFile
 public:
     /**
         Associates wxTempFile with the file to be replaced and opens it.
 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);
         You should use IsOpened() to verify that the constructor succeeded.
     */
     wxTempFile(const wxString& strName);


@@ -127,6 +75,18 @@ public:
     */
     void Discard();
 
     */
     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.
     */
     /**
         Returns @true if the file was successfully opened.
     */


@@ -135,7 +95,7 @@ public:
     /**
         Returns the length of the file.
 
     /**
         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
         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);
 
     /**
                       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;
         if another error occurred.
     */
     wxFileOffset Tell() const;


@@ -212,12 +172,12 @@ public:
             or test if it can be opened for writing with Access(). */
         write,
 
             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
         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.
         */
 
             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.
             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);
     */
     wxFile(const wxString& filename,
            wxFile::OpenMode mode = wxFile::read);


@@ -267,6 +230,32 @@ public:
     */
     ~wxFile();
 
     */
     ~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.
     /**
         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.


@@ -306,8 +295,11 @@ public:
         Get back a file descriptor from wxFile object - the caller is responsible for
         closing the file if this descriptor is opened.
         IsOpened() will return @false after call to Detach().
         Get back a file descriptor from wxFile object - the caller is responsible for
         closing the file if this descriptor is opened.
         IsOpened() will return @false after call to Detach().

+
+        @return The file descriptor (this is new since wxWidgets 3.0.0, in the
+        previous versions this method didn't return anything).

     */
     */

-    void Detach();
+    int Detach();

 
     /**
         Returns @true if the end of the file has been reached.
 
     /**
         Returns @true if the end of the file has been reached.


@@ -378,10 +370,27 @@ public:
         @param count
            Bytes to read
 
         @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);
 
     */
     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.
 
     /**
         Seeks to the specified position.
 


@@ -390,7 +399,7 @@ public:
         @param mode
             One of wxFromStart, wxFromEnd, wxFromCurrent.
 
         @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,
                 failure.
     */
     wxFileOffset Seek(wxFileOffset ofs,


@@ -404,13 +413,13 @@ public:
         @param ofs
             Number of bytes before the end of the file.
 
         @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);
 
     /**
                 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;
         if another error occurred.
     */
     wxFileOffset Tell() const;