]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/file.h
implement wxNativeFontInfo::SetFamily for wxGTK with the same logic used by wxMSW...
[wxWidgets.git] / interface / wx / file.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: file.h
3// Purpose: interface of wxTempFile, wxFile
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9
10/**
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.
13*/
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};
60
61
62
63/**
64 @class wxTempFile
65
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.
69
70 Usually, when a program replaces the contents of some file it first opens it for
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
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.
78
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
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 call neither Commit() nor Discard(), the destructor will
88 call Discard() automatically.
89
90 To summarize: if you want to replace another file, create an instance of
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.
96
97 @library{wxbase}
98 @category{file}
99*/
100class wxTempFile
101{
102public:
103 /**
104 Associates wxTempFile with the file to be replaced and opens it.
105
106 @warning
107 You should use IsOpened() to verify that the constructor succeeded.
108 */
109 wxTempFile(const wxString& strName);
110
111 /**
112 Destructor calls Discard() if temporary file is still open.
113 */
114 ~wxTempFile();
115
116 /**
117 Validate changes: deletes the old file of name m_strName and renames the new
118 file to the old name. Returns @true if both actions succeeded.
119
120 If @false is returned it may unfortunately mean two quite different things:
121 either that the old file couldn't be deleted or that the new file
122 couldn't be renamed to the old name.
123 */
124 bool Commit();
125
126 /**
127 Discard changes: the old file contents are not changed, the temporary
128 file is deleted.
129 */
130 void Discard();
131
132 /**
133 Returns @true if the file was successfully opened.
134 */
135 bool IsOpened() const;
136
137 /**
138 Returns the length of the file.
139
140 This method may return ::wxInvalidOffset if the length couldn't be
141 determined or 0 even for non-empty files if the file is not seekable.
142
143 In general, the only way to determine if the file for which this function
144 returns 0 is really empty or not is to try reading from it.
145 */
146 wxFileOffset Length() const;
147
148 /**
149 Open the temporary file, returns @true on success, @false if an error
150 occurred.
151 @a strName is the name of file to be replaced. The temporary file is always
152 created in the directory where @a strName is. In particular, if @a strName
153 doesn't include the path, it is created in the current directory and the
154 program should have write access to it for the function to succeed.
155 */
156 bool Open(const wxString& strName);
157
158 /**
159 Seeks to the specified position.
160 */
161 wxFileOffset Seek(wxFileOffset ofs,
162 wxSeekMode mode = wxFromStart);
163
164 /**
165 Returns the current position or ::wxInvalidOffset if file is not opened or
166 if another error occurred.
167 */
168 wxFileOffset Tell() const;
169
170 /**
171 Write to the file, return @true on success, @false on failure.
172 The second argument is only meaningful in Unicode build of wxWidgets when
173 @a conv is used to convert @a str to multibyte representation.
174 */
175 bool Write(const wxString& str,
176 const wxMBConv& conv = wxConvUTF8);
177};
178
179
180
181/**
182 @class wxFile
183
184 A wxFile performs raw file I/O. This is a very small class designed to
185 minimize the overhead of using it - in fact, there is hardly any overhead at
186 all, but using it brings you automatic error checking and hides differences
187 between platforms and compilers. wxFile also automatically closes the file in
188 its destructor so you won't forget to do so.
189 wxFile is a wrapper around @c file descriptor. - see also wxFFile for a
190 wrapper around @c FILE structure.
191
192 ::wxFileOffset is used by the wxFile functions which require offsets as
193 parameter or return them. If the platform supports it, wxFileOffset is a
194 typedef for a native 64 bit integer, otherwise a 32 bit integer is used for
195 ::wxFileOffset.
196
197 @library{wxbase}
198 @category{file}
199*/
200class wxFile
201{
202public:
203
204 /**
205 The OpenMode enumeration defines the different modes for opening a file with wxFile.
206 It is also used with wxFile::Access function.
207 */
208 enum OpenMode {
209
210 /** Open file for reading or test if it can be opened for reading with Access() */
211 read,
212
213 /** Open file for writing deleting the contents of the file if it already exists
214 or test if it can be opened for writing with Access(). */
215 write,
216
217 /** Open file for reading and writing; can not be used with Access() */
218 read_write,
219
220 /** Open file for appending: the file is opened for writing, but the old contents
221 of the file are not erased and the file pointer is initially placed at the end
222 of the file; can not be used with Access().
223
224 This is the same as OpenMode::write if the file doesn't exist.
225 */
226 write_append,
227
228 /**
229 Open the file securely for writing (Uses O_EXCL | O_CREAT).
230 Will fail if the file already exists, else create and open it atomically.
231 Useful for opening temporary files without being vulnerable to race exploits.
232 */
233 write_excl
234 };
235
236 /**
237 Standard file descriptors
238 */
239 enum { fd_invalid = -1, fd_stdin, fd_stdout, fd_stderr };
240
241 /**
242 Default constructor.
243 */
244 wxFile();
245
246 /**
247 Opens a file with a filename.
248
249 @param filename
250 The filename.
251 @param mode
252 The mode in which to open the file.
253
254 @warning
255 You should use IsOpened() to verify that the constructor succeeded.
256 */
257 wxFile(const wxString& filename,
258 wxFile::OpenMode mode = wxFile::read);
259
260 /**
261 Associates the file with the given file descriptor, which has already been
262 opened. See Attach() for the list of predefined descriptors.
263
264 @param fd
265 An existing file descriptor.
266 */
267 wxFile(int fd);
268
269 /**
270 Destructor will close the file.
271 @note This destructor is not virtual so you should not use wxFile polymorphically.
272 */
273 ~wxFile();
274
275 /**
276 This function verifies if we may access the given file in specified mode.
277 Only values of @c wxFile::read or @c wxFile::write really make sense here.
278 */
279 static bool Access(const wxString& name, wxFile::OpenMode mode);
280
281 /**
282 Attaches an existing file descriptor to the wxFile object.
283 Examples of predefined file descriptors are 0, 1 and 2 which correspond to
284 stdin, stdout and stderr (and have symbolic names of @c wxFile::fd_stdin,
285 @c wxFile::fd_stdout and @c wxFile::fd_stderr).
286
287 The descriptor should be already opened and it will be closed by wxFile
288 object.
289 */
290 void Attach(int fd);
291
292 /**
293 Closes the file.
294 */
295 bool Close();
296
297 /**
298 Creates a file for writing.
299
300 If the file already exists, setting @b overwrite to @true will ensure
301 it is overwritten.
302
303 @a access may be an OR combination of the ::wxPosixPermissions enumeration
304 values.
305 */
306 bool Create(const wxString& filename,
307 bool overwrite = false,
308 int access = wxS_DEFAULT);
309
310 /**
311 Get back a file descriptor from wxFile object - the caller is responsible for
312 closing the file if this descriptor is opened.
313 IsOpened() will return @false after call to Detach().
314 */
315 void Detach();
316
317 /**
318 Returns @true if the end of the file has been reached.
319 Note that the behaviour of the file pointer-based class wxFFile is
320 different as wxFFile::Eof() will return @true here only if an
321 attempt has been made to read @b past the last byte of the file, while
322 wxFile::Eof() will return @true even before such attempt is made if the
323 file pointer is at the last position in the file.
324
325 Note also that this function doesn't work on unseekable file descriptors
326 (examples include pipes, terminals and sockets under Unix) and an attempt to
327 use it will result in an error message.
328
329 So, to read the entire file into memory, you should write a loop which uses
330 Read() repeatedly and tests its return condition instead of using Eof()
331 as this will not work for special files under Unix.
332 */
333 bool Eof() const;
334
335 /**
336 Returns @true if the given name specifies an existing regular file
337 (not a directory or a link).
338 */
339 static bool Exists(const wxString& filename);
340
341 /**
342 Flushes the file descriptor.
343
344 Note that Flush() is not implemented on some Windows compilers due to a
345 missing fsync function, which reduces the usefulness of this function
346 (it can still be called but it will do nothing on unsupported compilers).
347 */
348 bool Flush();
349
350 /**
351 Returns the type of the file.
352 */
353 wxFileKind GetKind() const;
354
355 /**
356 Returns @true if the file has been opened.
357 */
358 bool IsOpened() const;
359
360 /**
361 Returns the length of the file.
362 */
363 wxFileOffset Length() const;
364
365 /**
366 Opens the file, returning @true if successful.
367
368 @param filename
369 The filename.
370 @param mode
371 The mode in which to open the file.
372 @param access
373 An OR-combination of ::wxPosixPermissions enumeration values.
374 */
375 bool Open(const wxString& filename, wxFile::OpenMode mode = wxFile::read,
376 int access = wxS_DEFAULT);
377
378 /**
379 Reads from the file into a memory buffer.
380
381 @param buffer
382 Buffer to write in
383 @param count
384 Bytes to read
385
386 @return The number of bytes read, or the symbol ::wxInvalidOffset.
387 */
388 ssize_t Read(void* buffer, size_t count);
389
390 /**
391 Seeks to the specified position.
392
393 @param ofs
394 Offset to seek to.
395 @param mode
396 One of wxFromStart, wxFromEnd, wxFromCurrent.
397
398 @return The actual offset position achieved, or ::wxInvalidOffset on
399 failure.
400 */
401 wxFileOffset Seek(wxFileOffset ofs,
402 wxSeekMode mode = wxFromStart);
403
404 /**
405 Moves the file pointer to the specified number of bytes relative to the
406 end of the file. For example, @c SeekEnd(-5) would position the pointer 5
407 bytes before the end.
408
409 @param ofs
410 Number of bytes before the end of the file.
411
412 @return The actual offset position achieved, or ::wxInvalidOffset on
413 failure.
414 */
415 wxFileOffset SeekEnd(wxFileOffset ofs = 0);
416
417 /**
418 Returns the current position or ::wxInvalidOffset if file is not opened or
419 if another error occurred.
420 */
421 wxFileOffset Tell() const;
422
423 /**
424 Write data to the file (descriptor).
425
426 @param buffer
427 Buffer from which to read data
428 @param count
429 Number of bytes to write
430
431 @return The number of bytes written.
432 */
433 size_t Write(const void *buffer, size_t count);
434
435 /**
436 Writes the contents of the string to the file, returns @true on success.
437 The second argument is only meaningful in Unicode build of wxWidgets when
438 @a conv is used to convert @a s to a multibyte representation.
439
440 Note that this method only works with @c NUL-terminated strings, if you want
441 to write data with embedded @c NULs to the file you should use the other
442 Write() overload.
443 */
444 bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8);
445
446 /**
447 Returns the file descriptor associated with the file.
448 */
449 int fd() const;
450};
451