1//
2// File.h
3//
4// Library: Foundation
5// Package: Filesystem
6// Module: File
7//
8// Definition of the File class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef Foundation_File_INCLUDED
18#define Foundation_File_INCLUDED
19
20
21#include "Poco/Foundation.h"
22#include "Poco/Timestamp.h"
23#include <vector>
24
25
26#if defined(POCO_OS_FAMILY_WINDOWS)
27#if defined(_WIN32_WCE)
28#include "File_WINCE.h"
29#else
30#include "Poco/File_WIN32.h"
31#endif
32#elif defined(POCO_VXWORKS)
33#include "Poco/File_VX.h"
34#elif defined(POCO_OS_FAMILY_UNIX)
35#include "Poco/File_UNIX.h"
36#endif
37
38
39namespace Poco {
40
41
42class Path;
43
44
45class Foundation_API File: private FileImpl
46 /// The File class provides methods for working with a file.
47 ///
48 /// Regarding paths passed to the various methods, note that
49 /// platform-specific limitations regarding maximum length
50 /// of the entire path and its components apply.
51 ///
52 /// On Windows, the implementation tries to work around the rather
53 /// low 260 characters MAX_PATH limit by adding the "\\?\" prefix if
54 /// a path is absolute and exceeds MAX_PATH characters in length.
55 /// Note that various limitations regarding usage of the "\\?\"
56 /// prefix apply in that case, e.g. the path must
57 /// not contain relative components ("." and "..") and must not
58 /// use the forward slash ("/") as directory separator.
59{
60public:
61 typedef FileSizeImpl FileSize;
62
63 enum LinkType
64 /// Type of link for linkTo().
65 {
66 LINK_HARD = 0, /// hard link
67 LINK_SYMBOLIC = 1 /// symbolic link
68 };
69
70 File();
71 /// Creates the file.
72
73 File(const std::string& path);
74 /// Creates the file.
75
76 File(const char* path);
77 /// Creates the file.
78
79 File(const Path& path);
80 /// Creates the file.
81
82 File(const File& file);
83 /// Copy constructor.
84
85 virtual ~File();
86 /// Destroys the file.
87
88 File& operator = (const File& file);
89 /// Assignment operator.
90
91 File& operator = (const std::string& path);
92 /// Assignment operator.
93
94 File& operator = (const char* path);
95 /// Assignment operator.
96
97 File& operator = (const Path& path);
98 /// Assignment operator.
99
100 void swap(File& file);
101 /// Swaps the file with another one.
102
103 const std::string& path() const;
104 /// Returns the path.
105
106 bool exists() const;
107 /// Returns true iff the file exists.
108
109 bool canRead() const;
110 /// Returns true iff the file is readable.
111
112 bool canWrite() const;
113 /// Returns true iff the file is writeable.
114
115 bool canExecute() const;
116 /// Returns true iff the file is executable.
117 ///
118 /// On Windows, the file must have
119 /// the extension ".EXE" to be executable.
120 /// On Unix platforms, the executable permission
121 /// bit must be set.
122
123 bool isFile() const;
124 /// Returns true iff the file is a regular file.
125
126 bool isLink() const;
127 /// Returns true iff the file is a symbolic link.
128
129 bool isDirectory() const;
130 /// Returns true iff the file is a directory.
131
132 bool isDevice() const;
133 /// Returns true iff the file is a device.
134
135 bool isHidden() const;
136 /// Returns true if the file is hidden.
137 ///
138 /// On Windows platforms, the file's hidden
139 /// attribute is set for this to be true.
140 ///
141 /// On Unix platforms, the file name must
142 /// begin with a period for this to be true.
143
144 Timestamp created() const;
145 /// Returns the creation date of the file.
146 ///
147 /// Not all platforms or filesystems (e.g. Linux and most Unix
148 /// platforms with the exception of FreeBSD and Mac OS X)
149 /// maintain the creation date of a file.
150 /// On such platforms, created() returns
151 /// the time of the last inode modification.
152
153 Timestamp getLastModified() const;
154 /// Returns the modification date of the file.
155
156 File& setLastModified(const Timestamp& ts);
157 /// Sets the modification date of the file.
158
159 FileSize getSize() const;
160 /// Returns the size of the file in bytes.
161
162 File& setSize(FileSize size);
163 /// Sets the size of the file in bytes. Can be used
164 /// to truncate a file.
165
166 File& setWriteable(bool flag = true);
167 /// Makes the file writeable (if flag is true), or
168 /// non-writeable (if flag is false) by setting the
169 /// file's flags in the filesystem accordingly.
170
171 File& setReadOnly(bool flag = true);
172 /// Makes the file non-writeable (if flag is true), or
173 /// writeable (if flag is false) by setting the
174 /// file's flags in the filesystem accordingly.
175
176 File& setExecutable(bool flag = true);
177 /// Makes the file executable (if flag is true), or
178 /// non-executable (if flag is false) by setting
179 /// the file's permission bits accordingly.
180 ///
181 /// Does nothing on Windows.
182
183 void copyTo(const std::string& path) const;
184 /// Copies the file (or directory) to the given path.
185 /// The target path can be a directory.
186 ///
187 /// A directory is copied recursively.
188
189 void moveTo(const std::string& path);
190 /// Copies the file (or directory) to the given path and
191 /// removes the original file. The target path can be a directory.
192
193 void renameTo(const std::string& path);
194 /// Renames the file to the new name.
195
196 void linkTo(const std::string& path, LinkType type = LINK_SYMBOLIC) const;
197 /// Creates a link (symbolic or hard, depending on type argument)
198 /// at the given path to the file or directory.
199 ///
200 /// May not be supported on all platforms.
201 /// Furthermore, some operating systems do not allow creating
202 /// hard links to directories.
203
204 void remove(bool recursive = false);
205 /// Deletes the file. If recursive is true and the
206 /// file is a directory, recursively deletes all
207 /// files in the directory.
208
209 bool createFile();
210 /// Creates a new, empty file in an atomic operation.
211 /// Returns true if the file has been created and false
212 /// if the file already exists. Throws an exception if
213 /// an error occurs.
214
215 bool createDirectory();
216 /// Creates a directory. Returns true if the directory
217 /// has been created and false if it already exists.
218 /// Throws an exception if an error occurs.
219
220 void createDirectories();
221 /// Creates a directory (and all parent directories
222 /// if necessary).
223
224 void list(std::vector<std::string>& files) const;
225 /// Fills the vector with the names of all
226 /// files in the directory.
227
228 void list(std::vector<File>& files) const;
229 /// Fills the vector with the names of all
230 /// files in the directory.
231
232 FileSize totalSpace() const;
233 /// Returns the total size in bytes of the partition containing this path.
234
235 FileSize usableSpace() const;
236 /// Returns the number of usable free bytes on the partition containing this path.
237
238 FileSize freeSpace() const;
239 /// Returns the number of free bytes on the partition containing this path.
240
241 bool operator == (const File& file) const;
242 bool operator != (const File& file) const;
243 bool operator < (const File& file) const;
244 bool operator <= (const File& file) const;
245 bool operator > (const File& file) const;
246 bool operator >= (const File& file) const;
247
248 static void handleLastError(const std::string& path);
249 /// For internal use only. Throws an appropriate
250 /// exception for the last file-related error.
251
252protected:
253 void copyDirectory(const std::string& path) const;
254 /// Copies a directory. Used internally by copyTo().
255};
256
257
258//
259// inlines
260//
261inline const std::string& File::path() const
262{
263 return getPathImpl();
264}
265
266
267inline bool File::operator == (const File& file) const
268{
269 return getPathImpl() == file.getPathImpl();
270}
271
272
273inline bool File::operator != (const File& file) const
274{
275 return getPathImpl() != file.getPathImpl();
276}
277
278
279inline bool File::operator < (const File& file) const
280{
281 return getPathImpl() < file.getPathImpl();
282}
283
284
285inline bool File::operator <= (const File& file) const
286{
287 return getPathImpl() <= file.getPathImpl();
288}
289
290
291inline bool File::operator > (const File& file) const
292{
293 return getPathImpl() > file.getPathImpl();
294}
295
296
297inline bool File::operator >= (const File& file) const
298{
299 return getPathImpl() >= file.getPathImpl();
300}
301
302
303inline void swap(File& f1, File& f2)
304{
305 f1.swap(f2);
306}
307
308
309} // namespace Poco
310
311
312#endif // Foundation_File_INCLUDED
313