interface/wx/ffile.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        ffile.h
   3 // Purpose:     interface of wxFFile
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 /**
  10     @class wxFFile
  11
  12     wxFFile implements buffered file I/O.
  13
  14     This is a very small class designed to minimize the overhead of using it - in fact,
  15     there is hardly any overhead at all, but using it brings you automatic error checking
  16     and hides differences between platforms and compilers.
  17
  18     It wraps inside it a @c FILE * handle used by standard C IO library (also known as @c stdio).
  19
  20     @library{wxbase}
  21     @category{file}
  22
  23     @see wxFFile::IsOpened
  24 */
  25 class wxFFile
  26 {
  27 public:
  28     wxFFile();
  29
  30     /**
  31         Opens a file with the given file pointer, which has already been opened.
  32
  33         @param fp
  34             An existing file descriptor, such as stderr.
  35     */
  36     wxFFile(FILE* fp);
  37
  38     /**
  39         Opens a file with the given mode.
  40         As there is no way to return whether the operation was successful or not from
  41         the constructor you should test the return value of IsOpened() to check that it
  42         didn't fail.
  43
  44         @param filename
  45             The filename.
  46         @param mode
  47             The mode in which to open the file using standard C strings.
  48             Note that you should use "b" flag if you use binary files under Windows
  49             or the results might be unexpected due to automatic newline conversion done
  50             for the text files.
  51     */
  52     wxFFile(const wxString& filename, const wxString& mode = "r");
  53
  54
  55     /**
  56         Destructor will close the file.
  57
  58         @note it is not virtual so you should @e not derive from wxFFile!
  59     */
  60     ~wxFFile();
  61
  62     /**
  63         Attaches an existing file pointer to the wxFFile object.
  64
  65         The descriptor should be already opened and it will be closed by wxFFile object.
  66     */
  67     void Attach(FILE* fp, const wxString& name = wxEmptyString);
  68
  69     /**
  70         Closes the file and returns @true on success.
  71     */
  72     bool Close();
  73
  74     /**
  75         Get back a file pointer from wxFFile object -- the caller is responsible for
  76         closing the file if this descriptor is opened.
  77
  78         IsOpened() will return @false after call to Detach().
  79
  80         @return The FILE pointer (this is new since wxWidgets 3.0.0, in the
  81         previous versions this method didn't return anything).
  82     */
  83     FILE* Detach();
  84
  85     /**
  86         Returns @true if an attempt has been made to read @e past
  87         the end of the file.
  88
  89         Note that the behaviour of the file descriptor based class  wxFile is different as
  90         wxFile::Eof() will return @true here as soon as the last byte of the file has been read.
  91
  92         Also note that this method may only be called for opened files and may crash if
  93         the file is not opened.
  94
  95         @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
  96
  97         @see IsOpened()
  98     */
  99     bool Eof() const;
 100
 101     /**
 102         Returns @true if an error has occurred on this file, similar to the standard
 103         @c ferror() function.
 104
 105         Please note that this method may only be called for opened files and may crash
 106         if the file is not opened.
 107
 108         @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
 109
 110         @see IsOpened()
 111     */
 112     bool Error() const;
 113
 114     /**
 115         Flushes the file and returns @true on success.
 116     */
 117     bool Flush();
 118
 119     /**
 120         Returns the type of the file.
 121
 122         @see wxFileKind
 123     */
 124     wxFileKind GetKind() const;
 125
 126     /**
 127         Returns the file name.
 128
 129         This is the name that was specified when the object was constructed or
 130         to the last call to Open(). Notice that it may be empty if Attach() was
 131         called without specifying the name.
 132      */
 133     const wxString& GetName() const;
 134
 135     /**
 136         Returns @true if the file is opened.
 137
 138         Most of the methods of this class may only be used for an opened file.
 139     */
 140     bool IsOpened() const;
 141
 142     /**
 143         Returns the length of the file.
 144     */
 145     wxFileOffset Length() const;
 146
 147     /**
 148         Opens the file, returning @true if successful.
 149
 150         @param filename
 151             The filename.
 152         @param mode
 153             The mode in which to open the file.
 154     */
 155     bool Open(const wxString& filename, const wxString& mode = "r");
 156
 157     /**
 158         Reads the specified number of bytes into a buffer, returning the actual number read.
 159
 160         @param buffer
 161             A buffer to receive the data.
 162         @param count
 163             The number of bytes to read.
 164
 165         @return The number of bytes read.
 166     */
 167     size_t Read(void* buffer, size_t count);
 168
 169     /**
 170         Reads the entire contents of the file into a string.
 171
 172         @param str
 173             String to read data into.
 174         @param conv
 175             Conversion object to use in Unicode build; by default supposes
 176             that file contents is encoded in UTF-8.
 177
 178         @return @true if file was read successfully, @false otherwise.
 179     */
 180     bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto());
 181
 182     /**
 183         Seeks to the specified position and returns @true on success.
 184
 185         @param ofs
 186             Offset to seek to.
 187         @param mode
 188             One of wxFromStart, wxFromEnd, wxFromCurrent.
 189     */
 190     bool Seek(wxFileOffset ofs, wxSeekMode mode = wxFromStart);
 191
 192     /**
 193         Moves the file pointer to the specified number of bytes before the end of the
 194         file and returns @true on success.
 195
 196         @param ofs
 197             Number of bytes before the end of the file.
 198     */
 199     bool SeekEnd(wxFileOffset ofs = 0);
 200
 201     /**
 202         Returns the current position.
 203     */
 204     wxFileOffset Tell() const;
 205
 206     /**
 207         Writes the contents of the string to the file, returns @true on success.
 208
 209         The second argument is only meaningful in Unicode build of wxWidgets when
 210         @a conv is used to convert @a str to multibyte representation.
 211     */
 212     bool Write(const wxString& str, const wxMBConv& conv = wxConvAuto());
 213
 214     /**
 215         Writes the specified number of bytes from a buffer.
 216
 217         @param buffer
 218             A buffer containing the data.
 219         @param count
 220             The number of bytes to write.
 221
 222         @return The number of bytes written.
 223     */
 224     size_t Write(const void* buffer, size_t count);
 225
 226     /**
 227         Returns the file pointer associated with the file.
 228     */
 229     FILE* fp() const;
 230 };
 231