1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxFFile
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
13 wxFFile implements buffered file I/O.
15 This is a very small class designed to minimize the overhead of using it - in fact,
16 there is hardly any overhead at all, but using it brings you automatic error checking
17 and hides differences between platforms and compilers.
19 It wraps inside it a @c FILE * handle used by standard C IO library (also known as @c stdio).
24 @see wxFFile::IsOpened
32 Opens a file with the given file pointer, which has already been opened.
35 An existing file descriptor, such as stderr.
40 Opens a file with the given mode.
41 As there is no way to return whether the operation was successful or not from
42 the constructor you should test the return value of IsOpened() to check that it
48 The mode in which to open the file using standard C strings.
49 Note that you should use "b" flag if you use binary files under Windows
50 or the results might be unexpected due to automatic newline conversion done
53 wxFFile(const wxString
& filename
, const wxString
& mode
= "r");
57 Destructor will close the file.
59 @note it is not virtual so you should @e not derive from wxFFile!
64 Attaches an existing file pointer to the wxFFile object.
66 The descriptor should be already opened and it will be closed by wxFFile object.
68 void Attach(FILE* fp
, const wxString
& name
= wxEmptyString
);
71 Closes the file and returns @true on success.
76 Get back a file pointer from wxFFile object -- the caller is responsible for
77 closing the file if this descriptor is opened.
79 IsOpened() will return @false after call to Detach().
84 Returns @true if an attempt has been made to read @e past
87 Note that the behaviour of the file descriptor based class wxFile is different as
88 wxFile::Eof() will return @true here as soon as the last byte of the file has been read.
90 Also note that this method may only be called for opened files and may crash if
91 the file is not opened.
93 @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
100 Returns @true if an error has occurred on this file, similar to the standard
101 @c ferror() function.
103 Please note that this method may only be called for opened files and may crash
104 if the file is not opened.
106 @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
113 Flushes the file and returns @true on success.
118 Returns the type of the file.
122 wxFileKind
GetKind() const;
125 Returns the file name.
127 This is the name that was specified when the object was constructed or
128 to the last call to Open(). Notice that it may be empty if Attach() was
129 called without specifying the name.
131 const wxString
& GetName() const;
134 Returns @true if the file is opened.
136 Most of the methods of this class may only be used for an opened file.
138 bool IsOpened() const;
141 Returns the length of the file.
143 wxFileOffset
Length() const;
146 Opens the file, returning @true if successful.
151 The mode in which to open the file.
153 bool Open(const wxString
& filename
, const wxString
& mode
= "r");
156 Reads the specified number of bytes into a buffer, returning the actual number read.
159 A buffer to receive the data.
161 The number of bytes to read.
163 @return The number of bytes read.
165 size_t Read(void* buffer
, size_t count
);
168 Reads the entire contents of the file into a string.
171 String to read data into.
173 Conversion object to use in Unicode build; by default supposes
174 that file contents is encoded in UTF-8.
176 @return @true if file was read successfully, @false otherwise.
178 bool ReadAll(wxString
* str
, const wxMBConv
& conv
= wxConvAuto());
181 Seeks to the specified position and returns @true on success.
186 One of wxFromStart, wxFromEnd, wxFromCurrent.
188 bool Seek(wxFileOffset ofs
, wxSeekMode mode
= wxFromStart
);
191 Moves the file pointer to the specified number of bytes before the end of the
192 file and returns @true on success.
195 Number of bytes before the end of the file.
197 bool SeekEnd(wxFileOffset ofs
= 0);
200 Returns the current position.
202 wxFileOffset
Tell() const;
205 Writes the contents of the string to the file, returns @true on success.
207 The second argument is only meaningful in Unicode build of wxWidgets when
208 @a conv is used to convert @a str to multibyte representation.
210 bool Write(const wxString
& str
, const wxMBConv
& conv
= wxConvAuto());
213 Writes the specified number of bytes from a buffer.
216 A buffer containing the data.
218 The number of bytes to write.
220 @return The number of bytes written.
222 size_t Write(const void* buffer
, size_t count
);
225 Returns the file pointer associated with the file.