]>
Commit | Line | Data |
---|---|---|
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 | ||
9 | /** | |
10 | @class wxFFile | |
11 | @wxheader{ffile.h} | |
7c913512 | 12 | |
23324ae1 FM |
13 | wxFFile implements buffered file I/O. This is a very small class designed to |
14 | minimize the overhead of using it - in fact, there is hardly any overhead at | |
15 | all, but using it brings you automatic error checking and hides differences | |
16 | between platforms and compilers. It wraps inside it a @c FILE * handle used | |
17 | by standard C IO library (also known as @c stdio). | |
7c913512 | 18 | |
23324ae1 FM |
19 | @library{wxbase} |
20 | @category{file} | |
7c913512 | 21 | |
e54c96f1 | 22 | @see wxFFile::IsOpened |
23324ae1 | 23 | */ |
7c913512 | 24 | class wxFFile |
23324ae1 FM |
25 | { |
26 | public: | |
27 | //@{ | |
28 | /** | |
29 | Opens a file with the given file pointer, which has already been opened. | |
3c4f71cc | 30 | |
7c913512 | 31 | @param filename |
4cc4bfaf | 32 | The filename. |
7c913512 | 33 | @param mode |
4cc4bfaf FM |
34 | The mode in which to open the file using standard C strings. |
35 | Note that you should use "b" flag if you use binary files under Windows | |
36 | or the results might be unexpected due to automatic newline conversion done | |
37 | for the text files. | |
7c913512 | 38 | @param fp |
4cc4bfaf | 39 | An existing file descriptor, such as stderr. |
23324ae1 FM |
40 | */ |
41 | wxFFile(); | |
7c913512 FM |
42 | wxFFile(const wxString& filename, const wxString& mode = "r"); |
43 | wxFFile(FILE* fp); | |
23324ae1 FM |
44 | //@} |
45 | ||
46 | /** | |
47 | Destructor will close the file. | |
23324ae1 FM |
48 | NB: it is not virtual so you should @e not derive from wxFFile! |
49 | */ | |
50 | ~wxFFile(); | |
51 | ||
52 | /** | |
53 | Attaches an existing file pointer to the wxFFile object. | |
23324ae1 FM |
54 | The descriptor should be already opened and it will be closed by wxFFile |
55 | object. | |
56 | */ | |
57 | void Attach(FILE* fp); | |
58 | ||
59 | /** | |
60 | Closes the file and returns @true on success. | |
61 | */ | |
62 | bool Close(); | |
63 | ||
64 | /** | |
65 | Get back a file pointer from wxFFile object -- the caller is responsible for | |
66 | closing the file if this | |
67 | descriptor is opened. IsOpened() will return @false after call to Detach(). | |
68 | */ | |
69 | void Detach(); | |
70 | ||
71 | /** | |
72 | Returns @true if the an attempt has been made to read @e past | |
7c913512 | 73 | the end of the file. |
23324ae1 FM |
74 | Note that the behaviour of the file descriptor based class |
75 | wxFile is different as wxFile::Eof | |
76 | will return @true here as soon as the last byte of the file has been | |
77 | read. | |
23324ae1 FM |
78 | Also note that this method may only be called for opened files and may crash if |
79 | the file is not opened. | |
3c4f71cc | 80 | |
4cc4bfaf | 81 | @see IsOpened() |
23324ae1 | 82 | */ |
328f5751 | 83 | bool Eof() const; |
23324ae1 FM |
84 | |
85 | /** | |
86 | Returns @true if an error has occurred on this file, similar to the standard | |
87 | @c ferror() function. | |
23324ae1 FM |
88 | Please note that this method may only be called for opened files and may crash |
89 | if the file is not opened. | |
3c4f71cc | 90 | |
4cc4bfaf | 91 | @see IsOpened() |
23324ae1 FM |
92 | */ |
93 | ||
94 | ||
95 | /** | |
96 | Flushes the file and returns @true on success. | |
97 | */ | |
98 | bool Flush(); | |
99 | ||
100 | /** | |
101 | Returns the type of the file. Possible return values are: | |
102 | */ | |
328f5751 | 103 | wxFileKind GetKind() const; |
23324ae1 FM |
104 | |
105 | /** | |
106 | Returns @true if the file is opened. Most of the methods of this class may | |
107 | only | |
108 | be used for an opened file. | |
109 | */ | |
328f5751 | 110 | bool IsOpened() const; |
23324ae1 FM |
111 | |
112 | /** | |
113 | Returns the length of the file. | |
114 | */ | |
328f5751 | 115 | wxFileOffset Length() const; |
23324ae1 FM |
116 | |
117 | /** | |
118 | Opens the file, returning @true if successful. | |
3c4f71cc | 119 | |
7c913512 | 120 | @param filename |
4cc4bfaf | 121 | The filename. |
7c913512 | 122 | @param mode |
4cc4bfaf | 123 | The mode in which to open the file. |
23324ae1 FM |
124 | */ |
125 | bool Open(const wxString& filename, const wxString& mode = "r"); | |
126 | ||
127 | /** | |
128 | Reads the specified number of bytes into a buffer, returning the actual number | |
129 | read. | |
3c4f71cc | 130 | |
7c913512 | 131 | @param buffer |
4cc4bfaf | 132 | A buffer to receive the data. |
7c913512 | 133 | @param count |
4cc4bfaf | 134 | The number of bytes to read. |
3c4f71cc | 135 | |
23324ae1 FM |
136 | @returns The number of bytes read. |
137 | */ | |
138 | size_t Read(void* buffer, size_t count); | |
139 | ||
140 | /** | |
141 | ) | |
23324ae1 | 142 | Reads the entire contents of the file into a string. |
3c4f71cc | 143 | |
7c913512 | 144 | @param str |
4cc4bfaf | 145 | String to read data into. |
7c913512 | 146 | @param conv |
4cc4bfaf FM |
147 | Conversion object to use in Unicode build; by default supposes |
148 | that file contents is encoded in UTF-8. | |
3c4f71cc | 149 | |
23324ae1 FM |
150 | @returns @true if file was read successfully, @false otherwise. |
151 | */ | |
4cc4bfaf | 152 | bool ReadAll(wxString* str); |
23324ae1 FM |
153 | |
154 | /** | |
155 | Seeks to the specified position and returns @true on success. | |
3c4f71cc | 156 | |
7c913512 | 157 | @param ofs |
4cc4bfaf | 158 | Offset to seek to. |
7c913512 | 159 | @param mode |
4cc4bfaf | 160 | One of wxFromStart, wxFromEnd, wxFromCurrent. |
23324ae1 FM |
161 | */ |
162 | bool Seek(wxFileOffset ofs, wxSeekMode mode = wxFromStart); | |
163 | ||
164 | /** | |
165 | Moves the file pointer to the specified number of bytes before the end of the | |
166 | file | |
167 | and returns @true on success. | |
3c4f71cc | 168 | |
7c913512 | 169 | @param ofs |
4cc4bfaf | 170 | Number of bytes before the end of the file. |
23324ae1 FM |
171 | */ |
172 | bool SeekEnd(wxFileOffset ofs = 0); | |
173 | ||
174 | /** | |
175 | Returns the current position. | |
176 | */ | |
328f5751 | 177 | wxFileOffset Tell() const; |
23324ae1 FM |
178 | |
179 | /** | |
180 | ) | |
23324ae1 | 181 | Writes the contents of the string to the file, returns @true on success. |
23324ae1 | 182 | The second argument is only meaningful in Unicode build of wxWidgets when |
4cc4bfaf | 183 | @e conv is used to convert @a s to multibyte representation. |
23324ae1 FM |
184 | */ |
185 | bool Write(const wxString& s); | |
186 | ||
187 | /** | |
188 | Returns the file pointer associated with the file. | |
189 | */ | |
328f5751 | 190 | FILE* fp() const; |
23324ae1 | 191 | }; |
e54c96f1 | 192 |