1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
|
// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef BASE_FILES_FILE_ENUMERATOR_H_
#define BASE_FILES_FILE_ENUMERATOR_H_
#include <stddef.h>
#include <stdint.h>
#include <vector>
#include "base/base_export.h"
#include "base/containers/stack.h"
#include "base/files/file.h"
#include "base/files/file_path.h"
#include "base/functional/function_ref.h"
#include "base/time/time.h"
#include "build/build_config.h"
#if BUILDFLAG(IS_WIN)
#include "base/win/windows_types.h"
#elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
#include <sys/stat.h>
#include <unistd.h>
#include <unordered_map>
#include <unordered_set>
#endif
namespace base {
// A class for enumerating the files in a provided path. The order of the
// results is not guaranteed.
//
// This is blocking. Do not use on critical threads.
//
// Example:
//
// base::FileEnumerator e(my_dir, false, base::FileEnumerator::FILES,
// FILE_PATH_LITERAL("*.txt"));
// Using `ForEach` with a lambda:
// e.ForEach([](const base::FilePath& item) {...});
// Using a `for` loop:
// for (base::FilePath name = e.Next(); !name.empty(); name = e.Next())
// ...
class BASE_EXPORT FileEnumerator {
public:
// Note: copy & assign supported.
class BASE_EXPORT FileInfo {
public:
FileInfo();
#if BUILDFLAG(IS_ANDROID)
// Android has both posix paths, and Content-URIs. It will use the linux /
// posix code for posix paths where a FileInfo() object is constructed and
// then `stat_` is populated via fstat() and used for IsDirectory(),
// GetSize(), GetLastModifiedTime(). Content-URIs provide all values in this
// constructor and writes `is_directory`, `size` and `time` to `stat_`.
FileInfo(base::FilePath content_uri,
base::FilePath filename,
bool is_directory,
off_t size,
Time time);
#endif
FileInfo(const FileInfo& that);
FileInfo& operator=(const FileInfo& that);
FileInfo(FileInfo&& that);
FileInfo& operator=(FileInfo&& that);
~FileInfo();
bool IsDirectory() const;
// The name of the file. This will not include any path information. This
// is in constrast to the value returned by FileEnumerator.Next() which
// includes the |root_path| passed into the FileEnumerator constructor.
FilePath GetName() const;
#if BUILDFLAG(IS_ANDROID)
// Display names of subdirs.
const std::vector<std::string>& subdirs() const { return subdirs_; }
#endif
int64_t GetSize() const;
// On POSIX systems, this is rounded down to the second.
Time GetLastModifiedTime() const;
#if BUILDFLAG(IS_WIN)
// Note that the cAlternateFileName (used to hold the "short" 8.3 name)
// of the WIN32_FIND_DATA will be empty. Since we don't use short file
// names, we tell Windows to omit it which speeds up the query slightly.
const WIN32_FIND_DATA& find_data() const {
return *ChromeToWindowsType(&find_data_);
}
#elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
const stat_wrapper_t& stat() const { return stat_; }
#endif
private:
friend class FileEnumerator;
#if BUILDFLAG(IS_ANDROID)
FilePath content_uri_;
std::vector<std::string> subdirs_;
#endif
#if BUILDFLAG(IS_WIN)
CHROME_WIN32_FIND_DATA find_data_;
#elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
stat_wrapper_t stat_;
FilePath filename_;
#endif
};
enum FileType {
FILES = 1 << 0,
DIRECTORIES = 1 << 1,
INCLUDE_DOT_DOT = 1 << 2,
// Report only the names of entries and not their type, size, or
// last-modified time. May only be used for non-recursive enumerations, and
// implicitly includes both files and directories (neither of which may be
// specified). When used, an enumerator's `GetInfo()` method must not be
// called.
NAMES_ONLY = 1 << 3,
#if BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
SHOW_SYM_LINKS = 1 << 4,
#endif
};
// Search policy for intermediate folders.
enum class FolderSearchPolicy {
// Recursive search will pass through folders whose names match the
// pattern. Inside each one, all files will be returned. Folders with names
// that do not match the pattern will be ignored within their interior.
MATCH_ONLY,
// Recursive search will pass through every folder and perform pattern
// matching inside each one.
ALL,
};
// Determines how a FileEnumerator handles errors encountered during
// enumeration. When no ErrorPolicy is explicitly set, FileEnumerator defaults
// to IGNORE_ERRORS.
enum class ErrorPolicy {
// Errors are ignored if possible and FileEnumerator returns as many files
// as it is able to enumerate.
IGNORE_ERRORS,
// Any error encountered during enumeration will terminate the enumeration
// immediately. An error code indicating the nature of a failure can be
// retrieved from |GetError()|.
STOP_ENUMERATION,
};
// |root_path| is the starting directory to search for. It may or may not end
// in a slash.
//
// If |recursive| is true, this will enumerate all matches in any
// subdirectories matched as well. It does a breadth-first search, so all
// files in one directory will be returned before any files in a
// subdirectory.
//
// |file_type|, a bit mask of FileType, specifies whether the enumerator
// should match files, directories, or both.
//
// |pattern| is an optional pattern for which files to match. This
// works like shell globbing. For example, "*.txt" or "Foo???.doc".
// However, be careful in specifying patterns that aren't cross platform
// since the underlying code uses OS-specific matching routines. In general,
// Windows matching is less featureful than others, so test there first.
// If unspecified, this will match all files.
//
// |folder_search_policy| optionally specifies a search behavior. Refer to
// |FolderSearchPolicy| for a list of folder search policies and the meaning
// of them. If |recursive| is false, this parameter has no effect.
//
// |error_policy| optionally specifies the behavior when an error occurs.
// Refer to |ErrorPolicy| for a list of error policies and the meaning of
// them.
FileEnumerator(const FilePath& root_path, bool recursive, int file_type);
FileEnumerator(const FilePath& root_path,
bool recursive,
int file_type,
const FilePath::StringType& pattern);
FileEnumerator(const FilePath& root_path,
bool recursive,
int file_type,
const FilePath::StringType& pattern,
FolderSearchPolicy folder_search_policy);
FileEnumerator(const FilePath& root_path,
bool recursive,
int file_type,
const FilePath::StringType& pattern,
FolderSearchPolicy folder_search_policy,
ErrorPolicy error_policy);
FileEnumerator(const FileEnumerator&) = delete;
FileEnumerator& operator=(const FileEnumerator&) = delete;
~FileEnumerator();
// Calls `ref` synchronously for each path found by the `FileEnumerator`. Each
// path will incorporate the `root_path` passed in the constructor:
// "<root_path>/file_name.txt". If the `root_path` is absolute, then so will
// be the paths provided in the `ref` invocations.
void ForEach(FunctionRef<void(const FilePath& path)> ref);
// Returns the next file or an empty string if there are no more results.
//
// The returned path will incorporate the |root_path| passed in the
// constructor: "<root_path>/file_name.txt". If the |root_path| is absolute,
// then so will be the result of Next().
FilePath Next();
// Returns info about the file last returned by Next(). Note that on Windows
// and Fuchsia, GetInfo() does not play well with INCLUDE_DOT_DOT. In
// particular, the GetLastModifiedTime() for the .. directory is 1601-01-01
// on Fuchsia (https://crbug.com/1106172) and is equal to the last modified
// time of the current directory on Windows (https://crbug.com/1119546).
// Must not be used with FileType::NAMES_ONLY.
FileInfo GetInfo() const;
// Once |Next()| returns an empty path, enumeration has been terminated. If
// termination was normal (i.e. no more results to enumerate) or ErrorPolicy
// is set to IGNORE_ERRORS, this returns FILE_OK. Otherwise it returns an
// error code reflecting why enumeration was stopped early.
File::Error GetError() const { return error_; }
private:
// Returns true if the given path should be skipped in enumeration.
bool ShouldSkip(const FilePath& path);
bool IsTypeMatched(bool is_dir) const;
bool IsPatternMatched(const FilePath& src) const;
#if BUILDFLAG(IS_WIN)
const WIN32_FIND_DATA& find_data() const {
return *ChromeToWindowsType(&find_data_);
}
// True when find_data_ is valid.
bool has_find_data_ = false;
CHROME_WIN32_FIND_DATA find_data_;
HANDLE find_handle_ = INVALID_HANDLE_VALUE;
#elif BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
// Marks the given inode as visited. Returns true if it is the first time that
// it got marked as visited.
bool MarkVisited(const stat_wrapper_t& st) {
return visited_[st.st_dev].insert(st.st_ino).second;
}
// The files in the current directory
std::vector<FileInfo> directory_entries_;
#if BUILDFLAG(IS_ANDROID)
// The Android NDK (r23) does not declare `st_dev` as a `dev_t`, nor `st_ino`
// as an `ino_t`, hence the need for these decltypes.
using dev_t = decltype(stat_wrapper_t::st_dev);
using ino_t = decltype(stat_wrapper_t::st_ino);
#endif
// Set of visited directories. Used to prevent infinite looping along circular
// symlinks and bind-mounts.
std::unordered_map<dev_t, std::unordered_set<ino_t>> visited_;
// The next entry to use from the directory_entries_ vector
size_t current_directory_entry_;
#endif
FilePath root_path_;
const bool recursive_;
int file_type_;
FilePath::StringType pattern_;
const FolderSearchPolicy folder_search_policy_;
const ErrorPolicy error_policy_;
File::Error error_ = File::FILE_OK;
// A stack that keeps track of which subdirectories we still need to
// enumerate in the breadth-first search.
base::stack<FilePath> pending_paths_;
#if BUILDFLAG(IS_ANDROID)
// Matches pending_paths_, but with display names.
base::stack<std::vector<std::string>> pending_subdirs_;
// Display names of subdirs of the current entry.
std::vector<std::string> subdirs_;
#endif
};
} // namespace base
#endif // BASE_FILES_FILE_ENUMERATOR_H_
|