]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/ffile.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / ffile.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: ffile.h
e54c96f1 3// Purpose: interface of wxFFile
23324ae1 4// Author: wxWidgets team
526954c5 5// Licence: wxWindows licence
23324ae1
FM
6/////////////////////////////////////////////////////////////////////////////
7
1add55ae 8
23324ae1
FM
9/**
10 @class wxFFile
7c913512 11
1add55ae
FM
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).
7c913512 19
23324ae1
FM
20 @library{wxbase}
21 @category{file}
7c913512 22
e54c96f1 23 @see wxFFile::IsOpened
23324ae1 24*/
7c913512 25class wxFFile
23324ae1
FM
26{
27public:
1add55ae
FM
28 wxFFile();
29
23324ae1
FM
30 /**
31 Opens a file with the given file pointer, which has already been opened.
3c4f71cc 32
1add55ae
FM
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
7c913512 44 @param filename
4cc4bfaf 45 The filename.
7c913512 46 @param mode
4cc4bfaf
FM
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.
23324ae1 51 */
7c913512 52 wxFFile(const wxString& filename, const wxString& mode = "r");
1add55ae 53
23324ae1
FM
54
55 /**
56 Destructor will close the file.
1add55ae
FM
57
58 @note it is not virtual so you should @e not derive from wxFFile!
23324ae1
FM
59 */
60 ~wxFFile();
61
62 /**
63 Attaches an existing file pointer to the wxFFile object.
1add55ae
FM
64
65 The descriptor should be already opened and it will be closed by wxFFile object.
23324ae1 66 */
43c48e1e 67 void Attach(FILE* fp, const wxString& name = wxEmptyString);
23324ae1
FM
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
1add55ae
FM
76 closing the file if this descriptor is opened.
77
78 IsOpened() will return @false after call to Detach().
23324ae1
FM
79 */
80 void Detach();
81
82 /**
d13b34d3 83 Returns @true if an attempt has been made to read @e past
7c913512 84 the end of the file.
1add55ae
FM
85
86 Note that the behaviour of the file descriptor based class wxFile is different as
87 wxFile::Eof() will return @true here as soon as the last byte of the file has been read.
88
23324ae1
FM
89 Also note that this method may only be called for opened files and may crash if
90 the file is not opened.
3c4f71cc 91
1add55ae
FM
92 @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
93
4cc4bfaf 94 @see IsOpened()
23324ae1 95 */
328f5751 96 bool Eof() const;
23324ae1
FM
97
98 /**
99 Returns @true if an error has occurred on this file, similar to the standard
100 @c ferror() function.
1add55ae 101
23324ae1
FM
102 Please note that this method may only be called for opened files and may crash
103 if the file is not opened.
3c4f71cc 104
1add55ae
FM
105 @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
106
4cc4bfaf 107 @see IsOpened()
23324ae1 108 */
1add55ae 109 bool Error() const;
23324ae1
FM
110
111 /**
112 Flushes the file and returns @true on success.
113 */
114 bool Flush();
115
116 /**
1add55ae
FM
117 Returns the type of the file.
118
119 @see wxFileKind
23324ae1 120 */
328f5751 121 wxFileKind GetKind() const;
23324ae1 122
6ea6639c
VZ
123 /**
124 Returns the file name.
125
126 This is the name that was specified when the object was constructed or
127 to the last call to Open(). Notice that it may be empty if Attach() was
128 called without specifying the name.
129 */
130 const wxString& GetName() const;
131
23324ae1 132 /**
1add55ae
FM
133 Returns @true if the file is opened.
134
135 Most of the methods of this class may only be used for an opened file.
23324ae1 136 */
328f5751 137 bool IsOpened() const;
23324ae1
FM
138
139 /**
140 Returns the length of the file.
141 */
328f5751 142 wxFileOffset Length() const;
23324ae1
FM
143
144 /**
145 Opens the file, returning @true if successful.
3c4f71cc 146
7c913512 147 @param filename
4cc4bfaf 148 The filename.
7c913512 149 @param mode
4cc4bfaf 150 The mode in which to open the file.
23324ae1
FM
151 */
152 bool Open(const wxString& filename, const wxString& mode = "r");
153
154 /**
1add55ae 155 Reads the specified number of bytes into a buffer, returning the actual number read.
3c4f71cc 156
7c913512 157 @param buffer
4cc4bfaf 158 A buffer to receive the data.
7c913512 159 @param count
4cc4bfaf 160 The number of bytes to read.
3c4f71cc 161
d29a9a8a 162 @return The number of bytes read.
23324ae1
FM
163 */
164 size_t Read(void* buffer, size_t count);
165
166 /**
23324ae1 167 Reads the entire contents of the file into a string.
3c4f71cc 168
7c913512 169 @param str
4cc4bfaf 170 String to read data into.
7c913512 171 @param conv
4cc4bfaf
FM
172 Conversion object to use in Unicode build; by default supposes
173 that file contents is encoded in UTF-8.
3c4f71cc 174
d29a9a8a 175 @return @true if file was read successfully, @false otherwise.
23324ae1 176 */
1add55ae 177 bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto());
23324ae1
FM
178
179 /**
180 Seeks to the specified position and returns @true on success.
3c4f71cc 181
7c913512 182 @param ofs
4cc4bfaf 183 Offset to seek to.
7c913512 184 @param mode
4cc4bfaf 185 One of wxFromStart, wxFromEnd, wxFromCurrent.
23324ae1
FM
186 */
187 bool Seek(wxFileOffset ofs, wxSeekMode mode = wxFromStart);
188
189 /**
190 Moves the file pointer to the specified number of bytes before the end of the
1add55ae 191 file and returns @true on success.
3c4f71cc 192
7c913512 193 @param ofs
4cc4bfaf 194 Number of bytes before the end of the file.
23324ae1
FM
195 */
196 bool SeekEnd(wxFileOffset ofs = 0);
197
198 /**
199 Returns the current position.
200 */
328f5751 201 wxFileOffset Tell() const;
23324ae1
FM
202
203 /**
23324ae1 204 Writes the contents of the string to the file, returns @true on success.
1add55ae 205
23324ae1 206 The second argument is only meaningful in Unicode build of wxWidgets when
1add55ae
FM
207 @a conv is used to convert @a str to multibyte representation.
208 */
209 bool Write(const wxString& str, const wxMBConv& conv = wxConvAuto());
210
211 /**
212 Writes the specified number of bytes from a buffer.
213
214 @param buffer
215 A buffer containing the data.
216 @param count
217 The number of bytes to write.
218
d29a9a8a 219 @return The number of bytes written.
23324ae1 220 */
1add55ae 221 size_t Write(const void* buffer, size_t count);
23324ae1
FM
222
223 /**
224 Returns the file pointer associated with the file.
225 */
328f5751 226 FILE* fp() const;
23324ae1 227};
e54c96f1 228