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