1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_FILES_FILE_ENUMERATOR_H_ 6 #define BASE_FILES_FILE_ENUMERATOR_H_ 7 8 #include <stddef.h> 9 #include <stdint.h> 10 11 #include <vector> 12 13 #include "base/base_export.h" 14 #include "base/containers/stack.h" 15 #include "base/files/file_path.h" 16 #include "base/macros.h" 17 #include "base/time/time.h" 18 #include "build/build_config.h" 19 20 #if defined(OS_WIN) 21 #include <windows.h> 22 #elif defined(OS_POSIX) || defined(OS_FUCHSIA) 23 #include <sys/stat.h> 24 #include <unistd.h> 25 #endif 26 27 namespace base { 28 29 // A class for enumerating the files in a provided path. The order of the 30 // results is not guaranteed. 31 // 32 // This is blocking. Do not use on critical threads. 33 // 34 // Example: 35 // 36 // base::FileEnumerator enum(my_dir, false, base::FileEnumerator::FILES, 37 // FILE_PATH_LITERAL("*.txt")); 38 // for (base::FilePath name = enum.Next(); !name.empty(); name = enum.Next()) 39 // ... 40 class BASE_EXPORT FileEnumerator { 41 public: 42 // Note: copy & assign supported. 43 class BASE_EXPORT FileInfo { 44 public: 45 FileInfo(); 46 ~FileInfo(); 47 48 bool IsDirectory() const; 49 50 // The name of the file. This will not include any path information. This 51 // is in constrast to the value returned by FileEnumerator.Next() which 52 // includes the |root_path| passed into the FileEnumerator constructor. 53 FilePath GetName() const; 54 55 int64_t GetSize() const; 56 Time GetLastModifiedTime() const; 57 58 #if defined(OS_WIN) 59 // Note that the cAlternateFileName (used to hold the "short" 8.3 name) 60 // of the WIN32_FIND_DATA will be empty. Since we don't use short file 61 // names, we tell Windows to omit it which speeds up the query slightly. find_data()62 const WIN32_FIND_DATA& find_data() const { return find_data_; } 63 #elif defined(OS_POSIX) || defined(OS_FUCHSIA) stat()64 const struct stat& stat() const { return stat_; } 65 #endif 66 67 private: 68 friend class FileEnumerator; 69 70 #if defined(OS_WIN) 71 WIN32_FIND_DATA find_data_; 72 #elif defined(OS_POSIX) || defined(OS_FUCHSIA) 73 struct stat stat_; 74 FilePath filename_; 75 #endif 76 }; 77 78 enum FileType { 79 FILES = 1 << 0, 80 DIRECTORIES = 1 << 1, 81 INCLUDE_DOT_DOT = 1 << 2, 82 #if defined(OS_POSIX) || defined(OS_FUCHSIA) 83 SHOW_SYM_LINKS = 1 << 4, 84 #endif 85 }; 86 87 // Search policy for intermediate folders. 88 enum class FolderSearchPolicy { 89 // Recursive search will pass through folders whose names match the 90 // pattern. Inside each one, all files will be returned. Folders with names 91 // that do not match the pattern will be ignored within their interior. 92 MATCH_ONLY, 93 // Recursive search will pass through every folder and perform pattern 94 // matching inside each one. 95 ALL, 96 }; 97 98 // |root_path| is the starting directory to search for. It may or may not end 99 // in a slash. 100 // 101 // If |recursive| is true, this will enumerate all matches in any 102 // subdirectories matched as well. It does a breadth-first search, so all 103 // files in one directory will be returned before any files in a 104 // subdirectory. 105 // 106 // |file_type|, a bit mask of FileType, specifies whether the enumerator 107 // should match files, directories, or both. 108 // 109 // |pattern| is an optional pattern for which files to match. This 110 // works like shell globbing. For example, "*.txt" or "Foo???.doc". 111 // However, be careful in specifying patterns that aren't cross platform 112 // since the underlying code uses OS-specific matching routines. In general, 113 // Windows matching is less featureful than others, so test there first. 114 // If unspecified, this will match all files. 115 FileEnumerator(const FilePath& root_path, 116 bool recursive, 117 int file_type); 118 FileEnumerator(const FilePath& root_path, 119 bool recursive, 120 int file_type, 121 const FilePath::StringType& pattern); 122 FileEnumerator(const FilePath& root_path, 123 bool recursive, 124 int file_type, 125 const FilePath::StringType& pattern, 126 FolderSearchPolicy folder_search_policy); 127 ~FileEnumerator(); 128 129 // Returns the next file or an empty string if there are no more results. 130 // 131 // The returned path will incorporate the |root_path| passed in the 132 // constructor: "<root_path>/file_name.txt". If the |root_path| is absolute, 133 // then so will be the result of Next(). 134 FilePath Next(); 135 136 // Write the file info into |info|. 137 FileInfo GetInfo() const; 138 139 private: 140 // Returns true if the given path should be skipped in enumeration. 141 bool ShouldSkip(const FilePath& path); 142 143 bool IsTypeMatched(bool is_dir) const; 144 145 bool IsPatternMatched(const FilePath& src) const; 146 147 #if defined(OS_WIN) 148 // True when find_data_ is valid. 149 bool has_find_data_ = false; 150 WIN32_FIND_DATA find_data_; 151 HANDLE find_handle_ = INVALID_HANDLE_VALUE; 152 #elif defined(OS_POSIX) || defined(OS_FUCHSIA) 153 // The files in the current directory 154 std::vector<FileInfo> directory_entries_; 155 156 // The next entry to use from the directory_entries_ vector 157 size_t current_directory_entry_; 158 #endif 159 FilePath root_path_; 160 const bool recursive_; 161 const int file_type_; 162 FilePath::StringType pattern_; 163 const FolderSearchPolicy folder_search_policy_; 164 165 // A stack that keeps track of which subdirectories we still need to 166 // enumerate in the breadth-first search. 167 base::stack<FilePath> pending_paths_; 168 169 DISALLOW_COPY_AND_ASSIGN(FileEnumerator); 170 }; 171 172 } // namespace base 173 174 #endif // BASE_FILES_FILE_ENUMERATOR_H_ 175