async_file_util.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360
  1. // Copyright (c) 2013 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. #ifndef STORAGE_BROWSER_FILE_SYSTEM_ASYNC_FILE_UTIL_H_
  5. #define STORAGE_BROWSER_FILE_SYSTEM_ASYNC_FILE_UTIL_H_
  6. #include <stdint.h>
  7. #include <memory>
  8. #include <vector>
  9. #include "base/callback_forward.h"
  10. #include "base/component_export.h"
  11. #include "base/files/file.h"
  12. #include "components/services/filesystem/public/mojom/types.mojom.h"
  13. #include "storage/browser/file_system/file_system_operation.h"
  14. namespace base {
  15. class Time;
  16. }
  17. namespace storage {
  18. class ShareableFileReference;
  19. }
  20. namespace storage {
  21. class FileSystemOperationContext;
  22. class FileSystemURL;
  23. // An interface which provides filesystem-specific file operations for
  24. // FileSystemOperationImpl.
  25. //
  26. // Each filesystem which needs to be dispatched from FileSystemOperationImpl
  27. // must implement this interface or a synchronous version of interface:
  28. // FileSystemFileUtil.
  29. //
  30. // As far as an instance of this class is owned by a FileSystemBackend
  31. // (which is owned by FileSystemContext), it's guaranteed that this instance's
  32. // alive while FileSystemOperationContext given to each operation is kept
  33. // alive. (Note that this instance might be freed on different thread
  34. // from the thread it is created.)
  35. //
  36. // It is NOT valid to give null callback to this class, and implementors
  37. // can assume that they don't get any null callbacks.
  38. //
  39. class AsyncFileUtil {
  40. public:
  41. using StatusCallback = base::OnceCallback<void(base::File::Error result)>;
  42. // Used for CreateOrOpen(). File util implementations can specify an
  43. // `on_close_callback` if an operation is needed after closing a file. If
  44. // non-null, CreateOrOpen() callers must run the callback (on the IO thread)
  45. // after the file closes. If the file is duped, the callback should not be run
  46. // until all dups of the file have been closed.
  47. using CreateOrOpenCallback =
  48. base::OnceCallback<void(base::File file,
  49. base::OnceClosure on_close_callback)>;
  50. using EnsureFileExistsCallback =
  51. base::OnceCallback<void(base::File::Error result, bool created)>;
  52. using GetFileInfoCallback =
  53. base::OnceCallback<void(base::File::Error result,
  54. const base::File::Info& file_info)>;
  55. using EntryList = std::vector<filesystem::mojom::DirectoryEntry>;
  56. using ReadDirectoryCallback = base::RepeatingCallback<
  57. void(base::File::Error result, EntryList file_list, bool has_more)>;
  58. using CreateSnapshotFileCallback =
  59. base::OnceCallback<void(base::File::Error result,
  60. const base::File::Info& file_info,
  61. const base::FilePath& platform_path,
  62. scoped_refptr<ShareableFileReference> file_ref)>;
  63. using CopyFileProgressCallback = base::RepeatingCallback<void(int64_t size)>;
  64. using CopyOrMoveOptionSet = FileSystemOperation::CopyOrMoveOptionSet;
  65. using GetMetadataField = FileSystemOperation::GetMetadataField;
  66. // Creates an AsyncFileUtil instance which performs file operations on local
  67. // file system. The created instance assumes FileSystemURL::path() has the
  68. // target platform path.
  69. COMPONENT_EXPORT(STORAGE_BROWSER)
  70. static AsyncFileUtil* CreateForLocalFileSystem();
  71. AsyncFileUtil() = default;
  72. AsyncFileUtil(const AsyncFileUtil&) = delete;
  73. AsyncFileUtil& operator=(const AsyncFileUtil&) = delete;
  74. virtual ~AsyncFileUtil() = default;
  75. // Creates or opens a file with the given flags.
  76. // If File::FLAG_CREATE is set in |file_flags| it always tries to create
  77. // a new file at the given |url| and calls back with
  78. // File::FILE_ERROR_FILE_EXISTS if the |url| already exists.
  79. //
  80. // FileSystemOperationImpl::OpenFile calls this.
  81. // This is used only by Pepper/NaCl File API.
  82. //
  83. virtual void CreateOrOpen(std::unique_ptr<FileSystemOperationContext> context,
  84. const FileSystemURL& url,
  85. uint32_t file_flags,
  86. CreateOrOpenCallback callback) = 0;
  87. // Ensures that the given |url| exist. This creates a empty new file
  88. // at |url| if the |url| does not exist.
  89. //
  90. // FileSystemOperationImpl::CreateFile calls this.
  91. //
  92. // This reports following error code via |callback|:
  93. // - File::FILE_OK and created==true if a file has not existed and
  94. // is created at |url|.
  95. // - File::FILE_OK and created==false if the file already exists.
  96. // - Other error code (with created=false) if a file hasn't existed yet
  97. // and there was an error while creating a new file.
  98. //
  99. virtual void EnsureFileExists(
  100. std::unique_ptr<FileSystemOperationContext> context,
  101. const FileSystemURL& url,
  102. EnsureFileExistsCallback callback) = 0;
  103. // Creates directory at given url.
  104. //
  105. // FileSystemOperationImpl::CreateDirectory calls this.
  106. //
  107. // This reports following error code via |callback|:
  108. // - File::FILE_ERROR_NOT_FOUND if the |url|'s parent directory
  109. // does not exist and |recursive| is false.
  110. // - File::FILE_ERROR_EXISTS if a directory already exists at |url|
  111. // and |exclusive| is true.
  112. // - File::FILE_ERROR_EXISTS if a file already exists at |url|
  113. // (regardless of |exclusive| value).
  114. // - Other error code if it failed to create a directory.
  115. //
  116. virtual void CreateDirectory(
  117. std::unique_ptr<FileSystemOperationContext> context,
  118. const FileSystemURL& url,
  119. bool exclusive,
  120. bool recursive,
  121. StatusCallback callback) = 0;
  122. // Retrieves the information about a file.
  123. //
  124. // FileSystemOperationImpl::GetMetadata calls this.
  125. //
  126. // This reports following error code via |callback|:
  127. // - File::FILE_ERROR_NOT_FOUND if the file doesn't exist.
  128. // - Other error code if there was an error while retrieving the file info.
  129. //
  130. virtual void GetFileInfo(std::unique_ptr<FileSystemOperationContext> context,
  131. const FileSystemURL& url,
  132. int fields,
  133. GetFileInfoCallback callback) = 0;
  134. // Reads contents of a directory at |path|.
  135. //
  136. // FileSystemOperationImpl::ReadDirectory calls this.
  137. //
  138. // Note that the |name| field of each entry in |file_list|
  139. // returned by |callback| should have a base file name
  140. // of the entry relative to the directory, but not an absolute path.
  141. //
  142. // (E.g. if ReadDirectory is called for a directory
  143. // 'path/to/dir' and the directory has entries 'a' and 'b',
  144. // the returned |file_list| should include entries whose names
  145. // are 'a' and 'b', but not '/path/to/dir/a' and '/path/to/dir/b'.)
  146. //
  147. // This reports following error code via |callback|:
  148. // - File::FILE_ERROR_NOT_FOUND if the target directory doesn't exist.
  149. // - File::FILE_ERROR_NOT_A_DIRECTORY if an entry exists at |url| but
  150. // is a file (not a directory).
  151. //
  152. virtual void ReadDirectory(
  153. std::unique_ptr<FileSystemOperationContext> context,
  154. const FileSystemURL& url,
  155. ReadDirectoryCallback callback) = 0;
  156. // Modifies timestamps of a file or directory at |url| with
  157. // |last_access_time| and |last_modified_time|. The function DOES NOT
  158. // create a file unlike 'touch' command on Linux.
  159. //
  160. // FileSystemOperationImpl::TouchFile calls this.
  161. // This is used only by Pepper/NaCl File API.
  162. //
  163. virtual void Touch(std::unique_ptr<FileSystemOperationContext> context,
  164. const FileSystemURL& url,
  165. const base::Time& last_access_time,
  166. const base::Time& last_modified_time,
  167. StatusCallback callback) = 0;
  168. // Truncates a file at |path| to |length|. If |length| is larger than
  169. // the original file size, the file will be extended, and the extended
  170. // part is filled with null bytes.
  171. //
  172. // FileSystemOperationImpl::Truncate calls this.
  173. //
  174. // This reports following error code via |callback|:
  175. // - File::FILE_ERROR_NOT_FOUND if the file doesn't exist.
  176. //
  177. virtual void Truncate(std::unique_ptr<FileSystemOperationContext> context,
  178. const FileSystemURL& url,
  179. int64_t length,
  180. StatusCallback callback) = 0;
  181. // Copies a file from |src_url| to |dest_url|.
  182. // This must be called for files that belong to the same filesystem
  183. // (i.e. type() and origin() of the |src_url| and |dest_url| must match).
  184. // |progress_callback| is a callback to report the progress update.
  185. // See file_system_operations.h for details. This should be called on the
  186. // same thread as where the method's called (IO thread). Calling this
  187. // is optional. It is recommended to use this callback for heavier operations
  188. // (such as file network downloading), so that, e.g., clients (UIs) can
  189. // update its state to show progress to users. This may be a null callback.
  190. //
  191. // FileSystemOperationImpl::Copy calls this for same-filesystem copy case.
  192. //
  193. // This reports following error code via |callback|:
  194. // - File::FILE_ERROR_NOT_FOUND if |src_url|
  195. // or the parent directory of |dest_url| does not exist.
  196. // - File::FILE_ERROR_NOT_A_FILE if |src_url| exists but is not a file.
  197. // - File::FILE_ERROR_INVALID_OPERATION if |dest_url| exists and
  198. // is not a file.
  199. // - File::FILE_ERROR_FAILED if |dest_url| does not exist and
  200. // its parent path is a file.
  201. //
  202. virtual void CopyFileLocal(
  203. std::unique_ptr<FileSystemOperationContext> context,
  204. const FileSystemURL& src_url,
  205. const FileSystemURL& dest_url,
  206. CopyOrMoveOptionSet options,
  207. CopyFileProgressCallback progress_callback,
  208. StatusCallback callback) = 0;
  209. // Moves a local file from |src_url| to |dest_url|.
  210. // This must be called for files that belong to the same filesystem
  211. // (i.e. type() and origin() of the |src_url| and |dest_url| must match).
  212. //
  213. // FileSystemOperationImpl::Move calls this for same-filesystem move case.
  214. //
  215. // This reports following error code via |callback|:
  216. // - File::FILE_ERROR_NOT_FOUND if |src_url|
  217. // or the parent directory of |dest_url| does not exist.
  218. // - File::FILE_ERROR_NOT_A_FILE if |src_url| exists but is not a file.
  219. // - File::FILE_ERROR_INVALID_OPERATION if |dest_url| exists and
  220. // is not a file.
  221. // - File::FILE_ERROR_FAILED if |dest_url| does not exist and
  222. // its parent path is a file.
  223. //
  224. virtual void MoveFileLocal(
  225. std::unique_ptr<FileSystemOperationContext> context,
  226. const FileSystemURL& src_url,
  227. const FileSystemURL& dest_url,
  228. CopyOrMoveOptionSet options,
  229. StatusCallback callback) = 0;
  230. // Copies in a single file from a different filesystem.
  231. //
  232. // FileSystemOperationImpl::Copy or Move calls this for cross-filesystem
  233. // cases.
  234. //
  235. // This reports following error code via |callback|:
  236. // - File::FILE_ERROR_NOT_FOUND if |src_file_path|
  237. // or the parent directory of |dest_url| does not exist.
  238. // - File::FILE_ERROR_INVALID_OPERATION if |dest_url| exists and
  239. // is not a file.
  240. // - File::FILE_ERROR_FAILED if |dest_url| does not exist and
  241. // its parent path is a file.
  242. //
  243. virtual void CopyInForeignFile(
  244. std::unique_ptr<FileSystemOperationContext> context,
  245. const base::FilePath& src_file_path,
  246. const FileSystemURL& dest_url,
  247. StatusCallback callback) = 0;
  248. // Deletes a single file.
  249. //
  250. // FileSystemOperationImpl::RemoveFile calls this.
  251. //
  252. // This reports following error code via |callback|:
  253. // - File::FILE_ERROR_NOT_FOUND if |url| does not exist.
  254. // - File::FILE_ERROR_NOT_A_FILE if |url| is not a file.
  255. //
  256. virtual void DeleteFile(std::unique_ptr<FileSystemOperationContext> context,
  257. const FileSystemURL& url,
  258. StatusCallback callback) = 0;
  259. // Removes a single empty directory.
  260. //
  261. // FileSystemOperationImpl::RemoveDirectory calls this.
  262. //
  263. // This reports following error code via |callback|:
  264. // - File::FILE_ERROR_NOT_FOUND if |url| does not exist.
  265. // - File::FILE_ERROR_NOT_A_DIRECTORY if |url| is not a directory.
  266. // - File::FILE_ERROR_NOT_EMPTY if |url| is not empty.
  267. //
  268. virtual void DeleteDirectory(
  269. std::unique_ptr<FileSystemOperationContext> context,
  270. const FileSystemURL& url,
  271. StatusCallback callback) = 0;
  272. // Removes a single file or a single directory with its contents
  273. // (i.e. files/subdirectories under the directory).
  274. //
  275. // FileSystemOperationImpl::Remove calls this.
  276. // On some platforms, such as Chrome OS Drive File System, recursive file
  277. // deletion can be implemented more efficiently than calling DeleteFile() and
  278. // DeleteDirectory() for each files/directories.
  279. // This method is optional, so if not supported,
  280. // File::FILE_ERROR_INVALID_OPERATION should be returned via |callback|.
  281. //
  282. // This reports following error code via |callback|:
  283. // - File::FILE_ERROR_NOT_FOUND if |url| does not exist.
  284. // - File::FILE_ERROR_INVALID_OPERATION if this operation is not supported.
  285. virtual void DeleteRecursively(
  286. std::unique_ptr<FileSystemOperationContext> context,
  287. const FileSystemURL& url,
  288. StatusCallback callback) = 0;
  289. // Creates a local snapshot file for a given |url| and returns the
  290. // metadata and platform path of the snapshot file via |callback|.
  291. // In regular filesystem cases the implementation may simply return
  292. // the metadata of the file itself (as well as GetMetadata does),
  293. // while in non-regular filesystem case the backend may create a
  294. // temporary snapshot file which holds the file data and return
  295. // the metadata of the temporary file.
  296. //
  297. // In the callback, it returns:
  298. // |file_info| is the metadata of the snapshot file created.
  299. // |platform_path| is the full absolute platform path to the snapshot
  300. // file created. If a file is not backed by a real local file in
  301. // the implementor's FileSystem, the implementor must create a
  302. // local snapshot file and return the path of the created file.
  303. //
  304. // If implementors creates a temporary file for snapshotting and wants
  305. // FileAPI backend to take care of the lifetime of the file (so that
  306. // it won't get deleted while JS layer has any references to the created
  307. // File/Blob object), it should return non-empty |file_ref|.
  308. // Via the |file_ref| implementors can schedule a file deletion
  309. // or arbitrary callbacks when the last reference of File/Blob is dropped.
  310. //
  311. // FileSystemOperationImpl::CreateSnapshotFile calls this.
  312. //
  313. // This reports following error code via |callback|:
  314. // - File::FILE_ERROR_NOT_FOUND if |url| does not exist.
  315. // - File::FILE_ERROR_NOT_A_FILE if |url| exists but is a directory.
  316. //
  317. // The field values of |file_info| are undefined (implementation
  318. // dependent) in error cases, and the caller should always
  319. // check the return code.
  320. virtual void CreateSnapshotFile(
  321. std::unique_ptr<FileSystemOperationContext> context,
  322. const FileSystemURL& url,
  323. CreateSnapshotFileCallback callback) = 0;
  324. };
  325. } // namespace storage
  326. #endif // STORAGE_BROWSER_FILE_SYSTEM_ASYNC_FILE_UTIL_H_