]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/file.h
When registering editor, try wxRTTI class name in additon to result of wxPGEditor...
[wxWidgets.git] / interface / wx / file.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: file.h
0b70c946 3// Purpose: interface of wxTempFile, wxFile
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
23b7f0cb 9
23b7f0cb 10/**
f41d6c8c
FM
11 We redefine these constants here because S_IREAD &c are _not_ standard
12 however, we do assume that the values correspond to the Unix umask bits.
23b7f0cb 13*/
f41d6c8c
FM
14enum wxPosixPermissions
15{
16 /// standard Posix names for these permission flags
17 //@{
18 wxS_IRUSR = 00400,
19 wxS_IWUSR = 00200,
20 wxS_IXUSR = 00100,
21
22 wxS_IRGRP = 00040,
23 wxS_IWGRP = 00020,
24 wxS_IXGRP = 00010,
25
26 wxS_IROTH = 00004,
27 wxS_IWOTH = 00002,
28 wxS_IXOTH = 00001,
29 //@}
30
31 /// longer but more readable synonims for the constants above
32 //@{
33 wxPOSIX_USER_READ = wxS_IRUSR,
34 wxPOSIX_USER_WRITE = wxS_IWUSR,
35 wxPOSIX_USER_EXECUTE = wxS_IXUSR,
36
37 wxPOSIX_GROUP_READ = wxS_IRGRP,
38 wxPOSIX_GROUP_WRITE = wxS_IWGRP,
39 wxPOSIX_GROUP_EXECUTE = wxS_IXGRP,
40
41 wxPOSIX_OTHERS_READ = wxS_IROTH,
42 wxPOSIX_OTHERS_WRITE = wxS_IWOTH,
43 wxPOSIX_OTHERS_EXECUTE = wxS_IXOTH,
44 //@}
45
46 /// Default mode for the new files: allow reading/writing them to everybody but
47 /// the effective file mode will be set after anding this value with umask and
48 /// so won't include wxS_IW{GRP,OTH} for the default 022 umask value
49 wxS_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | \
50 wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | \
51 wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE),
52
53 /// Default mode for the new directories (see wxFileName::Mkdir): allow
54 /// reading/writing/executing them to everybody, but just like wxS_DEFAULT
55 /// the effective directory mode will be set after anding this value with umask
56 wxS_DIR_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | wxPOSIX_USER_EXECUTE | \
57 wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | wxPOSIX_GROUP_EXECUTE | \
58 wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE | wxPOSIX_OTHERS_EXECUTE)
59};
23b7f0cb
FM
60
61
62
23324ae1
FM
63/**
64 @class wxTempFile
7c913512 65
23324ae1
FM
66 wxTempFile provides a relatively safe way to replace the contents of the
67 existing file. The name is explained by the fact that it may be also used as
68 just a temporary file if you don't replace the old file contents.
7c913512 69
23324ae1 70 Usually, when a program replaces the contents of some file it first opens it for
23b7f0cb
FM
71 writing, thus losing all of the old data and then starts recreating it.
72 This approach is not very safe because during the regeneration of the file bad
73 things may happen: the program may find that there is an internal error preventing
74 it from completing file generation, the user may interrupt it (especially if file
23324ae1
FM
75 generation takes long time) and, finally, any other external interrupts (power
76 supply failure or a disk error) will leave you without either the original file
77 or the new one.
7c913512 78
23324ae1
FM
79 wxTempFile addresses this problem by creating a temporary file which is meant to
80 replace the original file - but only after it is fully written. So, if the user
81 interrupts the program during the file generation, the old file won't be lost.
82 Also, if the program discovers itself that it doesn't want to replace the old
83 file there is no problem - in fact, wxTempFile will @b not replace the old
23b7f0cb
FM
84 file by default, you should explicitly call wxTempFile::Commit() to do it.
85 Calling wxTempFile::Discard() explicitly discards any modifications: it
86 closes and deletes the temporary file and leaves the original file unchanged.
87 If you don't call neither of Commit() and Discard(), the destructor will
88 call Discard() automatically.
7c913512 89
23324ae1 90 To summarize: if you want to replace another file, create an instance of
23b7f0cb
FM
91 wxTempFile passing the name of the file to be replaced to the constructor
92 (you may also use default constructor and pass the file name to wxTempFile::Open).
93 Then you can write to wxTempFile using wxFile-like functions and later call
94 wxTempFile::Commit() to replace the old file (and close this one) or call
95 wxTempFile::Discard() to cancel the modifications.
7c913512 96
23324ae1
FM
97 @library{wxbase}
98 @category{file}
99*/
7c913512 100class wxTempFile
23324ae1
FM
101{
102public:
103 /**
23b7f0cb
FM
104 Associates wxTempFile with the file to be replaced and opens it.
105 You should use IsOpened() to verify if the constructor succeeded.
23324ae1
FM
106 */
107 wxTempFile(const wxString& strName);
108
109 /**
23b7f0cb 110 Destructor calls Discard() if temporary file is still opened.
23324ae1
FM
111 */
112 ~wxTempFile();
113
114 /**
115 Validate changes: deletes the old file of name m_strName and renames the new
23b7f0cb
FM
116 file to the old name. Returns @true if both actions succeeded.
117
118 If @false is returned it may unfortunately mean two quite different things:
119 either that either the old file couldn't be deleted or that the new file
120 couldn't be renamed to the old name.
23324ae1
FM
121 */
122 bool Commit();
123
124 /**
125 Discard changes: the old file contents is not changed, temporary file is
126 deleted.
127 */
128 void Discard();
129
130 /**
131 Returns @true if the file was successfully opened.
132 */
328f5751 133 bool IsOpened() const;
23324ae1
FM
134
135 /**
136 Returns the length of the file.
41f6f17d
VZ
137
138 This method may return wxInvalidOffset if the length couldn't be
139 determined or also 0 even for non-empty files if the file is not
23b7f0cb
FM
140 seekable.
141
142 In general, the only way to determine if the file for which this function
143 returns 0 is really empty or not is to try reading from it.
23324ae1 144 */
328f5751 145 wxFileOffset Length() const;
23324ae1
FM
146
147 /**
148 Open the temporary file, returns @true on success, @false if an error
149 occurred.
4cc4bfaf 150 @a strName is the name of file to be replaced. The temporary file is always
23b7f0cb
FM
151 created in the directory where @a strName is. In particular, if @a strName
152 doesn't include the path, it is created in the current directory and the
153 program should have write access to it for the function to succeed.
23324ae1
FM
154 */
155 bool Open(const wxString& strName);
156
157 /**
158 Seeks to the specified position.
159 */
160 wxFileOffset Seek(wxFileOffset ofs,
161 wxSeekMode mode = wxFromStart);
162
163 /**
23b7f0cb
FM
164 Returns the current position or wxInvalidOffset if file is not opened or
165 if another error occurred.
23324ae1 166 */
328f5751 167 wxFileOffset Tell() const;
23324ae1
FM
168
169 /**
170 Write to the file, return @true on success, @false on failure.
23324ae1 171 The second argument is only meaningful in Unicode build of wxWidgets when
4cc4bfaf 172 @a conv is used to convert @a str to multibyte representation.
23324ae1
FM
173 */
174 bool Write(const wxString& str,
175 const wxMBConv& conv = wxConvUTF8);
176};
177
178
e54c96f1 179
23324ae1
FM
180/**
181 @class wxFile
7c913512 182
23b7f0cb
FM
183 A wxFile performs raw file I/O.
184
185 This is a very small class designed to minimize the overhead of using it - in fact,
186 there is hardly any overhead at all, but using it brings you automatic error
187 checking and hides differences between platforms and compilers.
188
189 wxFile also automatically closes the file in its destructor making it unnecessary
190 to worry about forgetting to do it.
191
23324ae1
FM
192 A wxFile performs raw file I/O. This is a very small class designed to
193 minimize the overhead of using it - in fact, there is hardly any overhead at
194 all, but using it brings you automatic error checking and hides differences
195 between platforms and compilers. wxFile also automatically closes the file in
196 its destructor making it unnecessary to worry about forgetting to do it.
23b7f0cb
FM
197 wxFile is a wrapper around @c file descriptor. - see also wxFFile for a
198 wrapper around @c FILE structure.
7c913512 199
23b7f0cb
FM
200 ::wxFileOffset is used by the wxFile functions which require offsets as
201 parameter or return them. If the platform supports it, wxFileOffset is a
202 typedef for a native 64 bit integer, otherwise a 32 bit integer is used for
203 ::wxFileOffset.
7c913512 204
23324ae1
FM
205 @library{wxbase}
206 @category{file}
207*/
7c913512 208class wxFile
23324ae1
FM
209{
210public:
23b7f0cb 211
23324ae1 212 /**
23b7f0cb
FM
213 The OpenMode enumeration defines the different modes for opening a file with wxFile.
214 It is also used with wxFile::Access function.
c1d97593 215 */
23b7f0cb
FM
216 enum OpenMode {
217
218 /** Open file for reading or test if it can be opened for reading with Access() */
219 read,
220
221 /** Open file for writing deleting the contents of the file if it already exists
222 or test if it can be opened for writing with Access(). */
223 write,
224
225 /** Open file for reading and writing; can not be used with Access() */
226 read_write,
227
228 /** Open file for appending: the file is opened for writing, but the old contents
229 of the file is not erased and the file pointer is initially placed at the end
230 of the file; can not be used with Access().
231
232 This is the same as OpenMode::write if the file doesn't exist.
233 */
234 write_append,
235
236 /**
237 Open the file securely for writing (Uses O_EXCL | O_CREAT).
238 Will fail if the file already exists, else create and open it atomically.
239 Useful for opening temporary files without being vulnerable to race exploits.
240 */
241 write_excl
242 };
243
244 /**
c1d97593
RR
245 Standard file descriptors
246 */
247 enum { fd_invalid = -1, fd_stdin, fd_stdout, fd_stderr };
248
23b7f0cb 249 /**
c1d97593
RR
250 Default constructor.
251 */
252 wxFile();
23b7f0cb 253
c1d97593
RR
254 /**
255 Opens a file with a filename.
3c4f71cc 256
7c913512 257 @param filename
4cc4bfaf 258 The filename.
7c913512 259 @param mode
23b7f0cb 260 The mode in which to open the file.
23324ae1 261 */
7c913512
FM
262 wxFile(const wxString& filename,
263 wxFile::OpenMode mode = wxFile::read);
23b7f0cb 264
c1d97593
RR
265 /**
266 Associates the file with the given file descriptor, which has already been
267 opened. See Attach() for the list of predefined descriptors.
23b7f0cb 268
c1d97593 269 @param fd
23b7f0cb 270 An existing file descriptor.
c1d97593 271 */
7c913512 272 wxFile(int fd);
23324ae1
FM
273
274 /**
275 Destructor will close the file.
1f1d2182 276 @note it is not virtual so you should not use wxFile polymorphically.
23324ae1
FM
277 */
278 ~wxFile();
279
280 /**
c1d97593
RR
281 This function verifies if we may access the given file in specified mode.
282 Only values of @c wxFile::read or @c wxFile::write really make sense here.
23324ae1 283 */
23b7f0cb 284 static bool Access(const wxString& name, wxFile::OpenMode mode);
23324ae1
FM
285
286 /**
23b7f0cb
FM
287 Attaches an existing file descriptor to the wxFile object.
288 Example of predefined file descriptors are 0, 1 and 2 which correspond to
289 stdin, stdout and stderr (and have symbolic names of @c wxFile::fd_stdin,
c1d97593 290 @c wxFile::fd_stdout and @c wxFile::fd_stderr).
23b7f0cb 291
23324ae1
FM
292 The descriptor should be already opened and it will be closed by wxFile
293 object.
294 */
295 void Attach(int fd);
296
297 /**
298 Closes the file.
299 */
300 void Close();
301
302 /**
23b7f0cb
FM
303 Creates a file for writing.
304
305 If the file already exists, setting @b overwrite to @true will ensure
306 it is overwritten.
307
f41d6c8c
FM
308 @a access may be an OR combination of the ::wxPosixPermissions enumeration
309 values.
23324ae1 310 */
23b7f0cb
FM
311 bool Create(const wxString& filename,
312 bool overwrite = false,
23324ae1
FM
313 int access = wxS_DEFAULT);
314
315 /**
316 Get back a file descriptor from wxFile object - the caller is responsible for
23b7f0cb
FM
317 closing the file if this descriptor is opened.
318 IsOpened() will return @false after call to Detach().
23324ae1
FM
319 */
320 void Detach();
321
322 /**
323 Returns @true if the end of the file has been reached.
23b7f0cb
FM
324 Note that the behaviour of the file pointer based class wxFFile is
325 different as wxFFile::Eof() will return @true here only if an
c1d97593
RR
326 attempt has been made to read @b past the last byte of the file, while
327 wxFile::Eof() will return @true even before such attempt is made if the
328 file pointer is at the last position in the file.
23b7f0cb 329
23324ae1
FM
330 Note also that this function doesn't work on unseekable file descriptors
331 (examples include pipes, terminals and sockets under Unix) and an attempt to
23b7f0cb
FM
332 use it will result in an error message in such case.
333
334 So, to read the entire file into memory, you should write a loop which uses
335 Read() repeatedly and tests its return condition instead of using Eof()
336 as this will not work for special files under Unix.
23324ae1 337 */
328f5751 338 bool Eof() const;
23324ae1
FM
339
340 /**
23b7f0cb
FM
341 Returns @true if the given name specifies an existing regular file
342 (not a directory or a link)
23324ae1
FM
343 */
344 static bool Exists(const wxString& filename);
345
346 /**
347 Flushes the file descriptor.
23b7f0cb
FM
348
349 Note that Flush() is not implemented on some Windows compilers due to a
350 missing fsync function, which reduces the usefulness of this function
23324ae1
FM
351 (it can still be called but it will do nothing on unsupported compilers).
352 */
353 bool Flush();
354
355 /**
23b7f0cb 356 Returns the type of the file.
23324ae1 357 */
328f5751 358 wxFileKind GetKind() const;
23324ae1
FM
359
360 /**
361 Returns @true if the file has been opened.
362 */
328f5751 363 bool IsOpened() const;
23324ae1
FM
364
365 /**
366 Returns the length of the file.
367 */
328f5751 368 wxFileOffset Length() const;
23324ae1
FM
369
370 /**
371 Opens the file, returning @true if successful.
3c4f71cc 372
7c913512 373 @param filename
4cc4bfaf 374 The filename.
7c913512 375 @param mode
23b7f0cb 376 The mode in which to open the file.
f41d6c8c
FM
377 @param access
378 An OR-combination of wxPosixPermissions enumeration values.
23324ae1
FM
379 */
380 bool Open(const wxString& filename,
f41d6c8c
FM
381 wxFile::OpenMode mode = wxFile::read,
382 int access = wxS_DEFAULT);
23324ae1 383
23324ae1 384 /**
23b7f0cb
FM
385 Reads from the file into a memory buffer.
386
c1d97593
RR
387 @param buffer
388 Buffer to write in
389 @param count
23b7f0cb
FM
390 Bytes to read
391
392 @return The number of bytes read, or the symbol wxInvalidOffset.
23324ae1
FM
393 */
394 size_t Read(void* buffer, size_t count);
23324ae1
FM
395
396 /**
397 Seeks to the specified position.
3c4f71cc 398
7c913512 399 @param ofs
4cc4bfaf 400 Offset to seek to.
7c913512 401 @param mode
4cc4bfaf 402 One of wxFromStart, wxFromEnd, wxFromCurrent.
3c4f71cc 403
d29a9a8a 404 @return The actual offset position achieved, or wxInvalidOffset on
23b7f0cb 405 failure.
23324ae1
FM
406 */
407 wxFileOffset Seek(wxFileOffset ofs,
408 wxSeekMode mode = wxFromStart);
409
410 /**
23b7f0cb
FM
411 Moves the file pointer to the specified number of bytes relative to the
412 end of the file. For example, @c SeekEnd(-5) would position the pointer 5
23324ae1 413 bytes before the end.
3c4f71cc 414
7c913512 415 @param ofs
4cc4bfaf 416 Number of bytes before the end of the file.
3c4f71cc 417
d29a9a8a 418 @return The actual offset position achieved, or wxInvalidOffset on
23b7f0cb 419 failure.
23324ae1
FM
420 */
421 wxFileOffset SeekEnd(wxFileOffset ofs = 0);
422
423 /**
c1d97593 424 Returns the current position or wxInvalidOffset if file is not opened or
23b7f0cb 425 if another error occurred.
23324ae1 426 */
328f5751 427 wxFileOffset Tell() const;
23324ae1 428
c1d97593
RR
429 /**
430 Write data to the file (descriptor).
23b7f0cb 431
4050e98d 432 @param buffer
c1d97593
RR
433 Buffer from which to read data
434 @param count
435 Number of bytes to write
23b7f0cb 436
c1d97593
RR
437 @return The number of bytes written.
438 */
439 size_t Write(const void *buffer, size_t count);
440
23324ae1
FM
441 /**
442 Writes the contents of the string to the file, returns @true on success.
23324ae1 443 The second argument is only meaningful in Unicode build of wxWidgets when
c1d97593 444 @a conv is used to convert @a s to a multibyte representation.
23b7f0cb 445
23324ae1 446 Note that this method only works with @c NUL-terminated strings, if you want
7c913512 447 to write data with embedded @c NULs to the file you should use the other
c1d97593 448 Write() overload.
23324ae1
FM
449 */
450 bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8);
451
452 /**
453 Returns the file descriptor associated with the file.
454 */
328f5751 455 int fd() const;
23324ae1 456};
e54c96f1 457