OLD | NEW |
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 1 // Copyright 2014 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef WEBKIT_BROWSER_FILEAPI_FILE_SYSTEM_OPERATION_H_ | 5 #include "storage/browser/fileapi/file_system_operation.h" |
6 #define WEBKIT_BROWSER_FILEAPI_FILE_SYSTEM_OPERATION_H_ | |
7 | |
8 #include <vector> | |
9 | |
10 #include "base/callback.h" | |
11 #include "base/files/file.h" | |
12 #include "base/files/file_path.h" | |
13 #include "base/process/process.h" | |
14 #include "webkit/browser/fileapi/file_system_operation_context.h" | |
15 #include "webkit/browser/storage_browser_export.h" | |
16 #include "webkit/common/fileapi/directory_entry.h" | |
17 | |
18 namespace base { | |
19 class Time; | |
20 } | |
21 | |
22 namespace net { | |
23 class URLRequest; | |
24 } | |
25 | |
26 namespace storage { | |
27 class ShareableFileReference; | |
28 } | |
29 | |
30 class GURL; | |
31 | |
32 namespace storage { | |
33 | |
34 class FileSystemContext; | |
35 class FileSystemURL; | |
36 class FileWriterDelegate; | |
37 | |
38 // The interface class for FileSystemOperation implementations. | |
39 // | |
40 // This interface defines file system operations required to implement | |
41 // "File API: Directories and System" | |
42 // http://www.w3.org/TR/file-system-api/ | |
43 // | |
44 // DESIGN NOTES | |
45 // | |
46 // This class is designed to | |
47 // | |
48 // 1) Serve one-time file system operation per instance. Only one | |
49 // method(CreateFile, CreateDirectory, Copy, Move, DirectoryExists, | |
50 // GetMetadata, ReadDirectory and Remove) may be called during the | |
51 // lifetime of this object and it should be called no more than once. | |
52 // | |
53 // 2) Deliver the results of operations to the client via the callback function | |
54 // passed as the last parameter of the method. | |
55 // | |
56 // Note that it is valid to delete an operation while it is running. | |
57 // The callback will NOT be fired if the operation is deleted before | |
58 // it gets called. | |
59 class FileSystemOperation { | |
60 public: | |
61 STORAGE_EXPORT static FileSystemOperation* Create( | |
62 const FileSystemURL& url, | |
63 FileSystemContext* file_system_context, | |
64 scoped_ptr<FileSystemOperationContext> operation_context); | |
65 | |
66 virtual ~FileSystemOperation() {} | |
67 | |
68 // Used for CreateFile(), etc. |result| is the return code of the operation. | |
69 typedef base::Callback<void(base::File::Error result)> StatusCallback; | |
70 | |
71 // Used for GetMetadata(). |result| is the return code of the operation, | |
72 // |file_info| is the obtained file info. | |
73 typedef base::Callback< | |
74 void(base::File::Error result, | |
75 const base::File::Info& file_info)> GetMetadataCallback; | |
76 | |
77 // Used for OpenFile(). |on_close_callback| will be called after the file is | |
78 // closed in the child process. It can be null, if no operation is needed on | |
79 // closing a file. | |
80 typedef base::Callback< | |
81 void(base::File file, | |
82 const base::Closure& on_close_callback)> OpenFileCallback; | |
83 | |
84 // Used for ReadDirectoryCallback. | |
85 typedef std::vector<DirectoryEntry> FileEntryList; | |
86 | |
87 // Used for ReadDirectory(). |result| is the return code of the operation, | |
88 // |file_list| is the list of files read, and |has_more| is true if some files | |
89 // are yet to be read. | |
90 typedef base::Callback< | |
91 void(base::File::Error result, | |
92 const FileEntryList& file_list, | |
93 bool has_more)> ReadDirectoryCallback; | |
94 | |
95 // Used for CreateSnapshotFile(). (Please see the comment at | |
96 // CreateSnapshotFile() below for how the method is called) | |
97 // |result| is the return code of the operation. | |
98 // |file_info| is the metadata of the snapshot file created. | |
99 // |platform_path| is the path to the snapshot file created. | |
100 // | |
101 // The snapshot file could simply be of the local file pointed by the given | |
102 // filesystem URL in local filesystem cases; remote filesystems | |
103 // may want to download the file into a temporary snapshot file and then | |
104 // return the metadata of the temporary file. | |
105 // | |
106 // |file_ref| is used to manage the lifetime of the returned | |
107 // snapshot file. It can be set to let the chromium backend take | |
108 // care of the life time of the snapshot file. Otherwise (if the returned | |
109 // file does not require any handling) the implementation can just | |
110 // return NULL. In a more complex case, the implementaiton can manage | |
111 // the lifetime of the snapshot file on its own (e.g. by its cache system) | |
112 // but also can be notified via the reference when the file becomes no | |
113 // longer necessary in the javascript world. | |
114 // Please see the comment for ShareableFileReference for details. | |
115 // | |
116 typedef base::Callback< | |
117 void(base::File::Error result, | |
118 const base::File::Info& file_info, | |
119 const base::FilePath& platform_path, | |
120 const scoped_refptr<storage::ShareableFileReference>& file_ref)> | |
121 SnapshotFileCallback; | |
122 | |
123 // Used for progress update callback for Copy(). | |
124 // | |
125 // BEGIN_COPY_ENTRY is fired for each copy creation beginning (for both | |
126 // file and directory). | |
127 // The |source_url| is the URL of the source entry. |size| should not be | |
128 // used. | |
129 // | |
130 // END_COPY_ENTRY is fired for each copy creation finishing (for both | |
131 // file and directory). | |
132 // The |source_url| is the URL of the source entry. The |destination_url| is | |
133 // the URL of the destination entry. |size| should not be used. | |
134 // | |
135 // PROGRESS is fired periodically during file copying (not fired for | |
136 // directory copy). | |
137 // The |source_url| is the URL of the source file. |size| is the number | |
138 // of cumulative copied bytes for the currently copied file. | |
139 // Both at beginning and ending of file copying, PROGRESS event should be | |
140 // called. At beginning, |size| should be 0. At ending, |size| should be | |
141 // the size of the file. | |
142 // | |
143 // Here is an example callback sequence of recursive copy. Suppose | |
144 // there are a/b/c.txt (100 bytes) and a/b/d.txt (200 bytes), and trying to | |
145 // copy a to x recursively, then the progress update sequence will be: | |
146 // | |
147 // BEGIN_COPY_ENTRY a (starting create "a" directory in x/). | |
148 // END_COPY_ENTRY a x/a (creating "a" directory in x/ is finished). | |
149 // | |
150 // BEGIN_COPY_ENTRY a/b (starting create "b" directory in x/a). | |
151 // END_COPY_ENTRY a/b x/a/b (creating "b" directory in x/a/ is finished). | |
152 // | |
153 // BEGIN_COPY_ENTRY a/b/c.txt (starting to copy "c.txt" in x/a/b/). | |
154 // PROGRESS a/b/c.txt 0 (The first PROGRESS's |size| should be 0). | |
155 // PROGRESS a/b/c.txt 10 | |
156 // : | |
157 // PROGRESS a/b/c.txt 90 | |
158 // PROGRESS a/b/c.txt 100 (The last PROGRESS's |size| should be the size of | |
159 // the file). | |
160 // END_COPY_ENTRY a/b/c.txt x/a/b/c.txt (copying "c.txt" is finished). | |
161 // | |
162 // BEGIN_COPY_ENTRY a/b/d.txt (starting to copy "d.txt" in x/a/b). | |
163 // PROGRESS a/b/d.txt 0 (The first PROGRESS's |size| should be 0). | |
164 // PROGRESS a/b/d.txt 10 | |
165 // : | |
166 // PROGRESS a/b/d.txt 190 | |
167 // PROGRESS a/b/d.txt 200 (The last PROGRESS's |size| should be the size of | |
168 // the file). | |
169 // END_COPY_ENTRY a/b/d.txt x/a/b/d.txt (copy "d.txt" is finished). | |
170 // | |
171 // Note that event sequence of a/b/c.txt and a/b/d.txt can be interlaced, | |
172 // because they can be done in parallel. Also PROGRESS events are optional, | |
173 // so they may not be appeared. | |
174 // All the progress callback invocation should be done before StatusCallback | |
175 // given to the Copy is called. Especially if an error is found before first | |
176 // progres callback invocation, the progress callback may NOT invoked for the | |
177 // copy. | |
178 // | |
179 // Note for future extension. Currently this callback is only supported on | |
180 // Copy(). We can extend this to Move(), because Move() is sometimes | |
181 // implemented as "copy then delete." | |
182 // In more precise, Move() usually can be implemented either 1) by updating | |
183 // the metadata of resource (e.g. root of moving directory tree), or 2) by | |
184 // copying directory tree and them removing the source tree. | |
185 // For 1)'s case, we can simply add BEGIN_MOVE_ENTRY and END_MOVE_ENTRY | |
186 // for root directory. | |
187 // For 2)'s case, we can add BEGIN_DELETE_ENTRY and END_DELETE_ENTRY for each | |
188 // entry. | |
189 // For both cases, we probably won't need to use PROGRESS event because | |
190 // these operations should be done quickly (at least much faster than copying | |
191 // usually). | |
192 enum CopyProgressType { | |
193 BEGIN_COPY_ENTRY, | |
194 END_COPY_ENTRY, | |
195 PROGRESS, | |
196 }; | |
197 typedef base::Callback<void(CopyProgressType type, | |
198 const FileSystemURL& source_url, | |
199 const FileSystemURL& destination_url, | |
200 int64 size)> | |
201 CopyProgressCallback; | |
202 | |
203 // Used for CopyFileLocal() to report progress update. | |
204 // |size| is the cumulative copied bytes for the copy. | |
205 // At the beginning the progress callback should be called with |size| = 0, | |
206 // and also at the ending the progress callback should be called with |size| | |
207 // set to the copied file size. | |
208 typedef base::Callback<void(int64 size)> CopyFileProgressCallback; | |
209 | |
210 // The option for copy or move operation. | |
211 enum CopyOrMoveOption { | |
212 // No additional operation. | |
213 OPTION_NONE, | |
214 | |
215 // Preserves last modified time if possible. If the operation to update | |
216 // last modified time is not supported on the file system for the | |
217 // destination file, this option would be simply ignored (i.e. Copy would | |
218 // be successfully done without preserving last modified time). | |
219 OPTION_PRESERVE_LAST_MODIFIED, | |
220 }; | |
221 | |
222 // Used for Write(). | |
223 typedef base::Callback<void(base::File::Error result, | |
224 int64 bytes, | |
225 bool complete)> WriteCallback; | |
226 | |
227 // Creates a file at |path|. If |exclusive| is true, an error is raised | |
228 // in case a file is already present at the URL. | |
229 virtual void CreateFile(const FileSystemURL& path, | |
230 bool exclusive, | |
231 const StatusCallback& callback) = 0; | |
232 | |
233 // Creates a directory at |path|. If |exclusive| is true, an error is | |
234 // raised in case a directory is already present at the URL. If | |
235 // |recursive| is true, create parent directories as needed just like | |
236 // mkdir -p does. | |
237 virtual void CreateDirectory(const FileSystemURL& path, | |
238 bool exclusive, | |
239 bool recursive, | |
240 const StatusCallback& callback) = 0; | |
241 | |
242 // Copies a file or directory from |src_path| to |dest_path|. If | |
243 // |src_path| is a directory, the contents of |src_path| are copied to | |
244 // |dest_path| recursively. A new file or directory is created at | |
245 // |dest_path| as needed. | |
246 // |option| specifies the minor behavior of Copy(). See CopyOrMoveOption's | |
247 // comment for details. | |
248 // |progress_callback| is periodically called to report the progress | |
249 // update. See also the comment of CopyProgressCallback. This callback is | |
250 // optional. | |
251 // | |
252 // For recursive case this internally creates new FileSystemOperations and | |
253 // calls: | |
254 // - ReadDirectory, CopyFileLocal and CreateDirectory | |
255 // for same-filesystem case, or | |
256 // - ReadDirectory and CreateSnapshotFile on source filesystem and | |
257 // CopyInForeignFile and CreateDirectory on dest filesystem | |
258 // for cross-filesystem case. | |
259 // | |
260 virtual void Copy(const FileSystemURL& src_path, | |
261 const FileSystemURL& dest_path, | |
262 CopyOrMoveOption option, | |
263 const CopyProgressCallback& progress_callback, | |
264 const StatusCallback& callback) = 0; | |
265 | |
266 // Moves a file or directory from |src_path| to |dest_path|. A new file | |
267 // or directory is created at |dest_path| as needed. | |
268 // |option| specifies the minor behavior of Copy(). See CopyOrMoveOption's | |
269 // comment for details. | |
270 // | |
271 // For recursive case this internally creates new FileSystemOperations and | |
272 // calls: | |
273 // - ReadDirectory, MoveFileLocal, CreateDirectory and Remove | |
274 // for same-filesystem case, or | |
275 // - ReadDirectory, CreateSnapshotFile and Remove on source filesystem and | |
276 // CopyInForeignFile and CreateDirectory on dest filesystem | |
277 // for cross-filesystem case. | |
278 // | |
279 virtual void Move(const FileSystemURL& src_path, | |
280 const FileSystemURL& dest_path, | |
281 CopyOrMoveOption option, | |
282 const StatusCallback& callback) = 0; | |
283 | |
284 // Checks if a directory is present at |path|. | |
285 virtual void DirectoryExists(const FileSystemURL& path, | |
286 const StatusCallback& callback) = 0; | |
287 | |
288 // Checks if a file is present at |path|. | |
289 virtual void FileExists(const FileSystemURL& path, | |
290 const StatusCallback& callback) = 0; | |
291 | |
292 // Gets the metadata of a file or directory at |path|. | |
293 virtual void GetMetadata(const FileSystemURL& path, | |
294 const GetMetadataCallback& callback) = 0; | |
295 | |
296 // Reads contents of a directory at |path|. | |
297 virtual void ReadDirectory(const FileSystemURL& path, | |
298 const ReadDirectoryCallback& callback) = 0; | |
299 | |
300 // Removes a file or directory at |path|. If |recursive| is true, remove | |
301 // all files and directories under the directory at |path| recursively. | |
302 virtual void Remove(const FileSystemURL& path, bool recursive, | |
303 const StatusCallback& callback) = 0; | |
304 | |
305 // Writes the data read from |blob_request| using |writer_delegate|. | |
306 virtual void Write( | |
307 const FileSystemURL& url, | |
308 scoped_ptr<FileWriterDelegate> writer_delegate, | |
309 scoped_ptr<net::URLRequest> blob_request, | |
310 const WriteCallback& callback) = 0; | |
311 | |
312 // Truncates a file at |path| to |length|. If |length| is larger than | |
313 // the original file size, the file will be extended, and the extended | |
314 // part is filled with null bytes. | |
315 virtual void Truncate(const FileSystemURL& path, int64 length, | |
316 const StatusCallback& callback) = 0; | |
317 | |
318 // Tries to cancel the current operation [we support cancelling write or | |
319 // truncate only]. Reports failure for the current operation, then reports | |
320 // success for the cancel operation itself via the |cancel_dispatcher|. | |
321 // | |
322 // E.g. a typical cancel implementation would look like: | |
323 // | |
324 // virtual void SomeOperationImpl::Cancel( | |
325 // const StatusCallback& cancel_callback) { | |
326 // // Abort the current inflight operation first. | |
327 // ... | |
328 // | |
329 // // Dispatch ABORT error for the current operation by invoking | |
330 // // the callback function for the ongoing operation, | |
331 // operation_callback.Run(base::File::FILE_ERROR_ABORT, ...); | |
332 // | |
333 // // Dispatch 'success' for the cancel (or dispatch appropriate | |
334 // // error code with DidFail() if the cancel has somehow failed). | |
335 // cancel_callback.Run(base::File::FILE_OK); | |
336 // } | |
337 // | |
338 // Note that, for reporting failure, the callback function passed to a | |
339 // cancellable operations are kept around with the operation instance | |
340 // (as |operation_callback_| in the code example). | |
341 virtual void Cancel(const StatusCallback& cancel_callback) = 0; | |
342 | |
343 // Modifies timestamps of a file or directory at |path| with | |
344 // |last_access_time| and |last_modified_time|. The function DOES NOT | |
345 // create a file unlike 'touch' command on Linux. | |
346 // | |
347 // This function is used only by Pepper as of writing. | |
348 virtual void TouchFile(const FileSystemURL& path, | |
349 const base::Time& last_access_time, | |
350 const base::Time& last_modified_time, | |
351 const StatusCallback& callback) = 0; | |
352 | |
353 // Opens a file at |path| with |file_flags|, where flags are OR'ed | |
354 // values of base::File::Flags. | |
355 // | |
356 // This function is used only by Pepper as of writing. | |
357 virtual void OpenFile(const FileSystemURL& path, | |
358 int file_flags, | |
359 const OpenFileCallback& callback) = 0; | |
360 | |
361 // Creates a local snapshot file for a given |path| and returns the | |
362 // metadata and platform path of the snapshot file via |callback|. | |
363 // In local filesystem cases the implementation may simply return | |
364 // the metadata of the file itself (as well as GetMetadata does), | |
365 // while in remote filesystem case the backend may want to download the file | |
366 // into a temporary snapshot file and return the metadata of the | |
367 // temporary file. Or if the implementaiton already has the local cache | |
368 // data for |path| it can simply return the path to the cache. | |
369 virtual void CreateSnapshotFile(const FileSystemURL& path, | |
370 const SnapshotFileCallback& callback) = 0; | |
371 | |
372 // Copies in a single file from a different filesystem. | |
373 // | |
374 // This returns: | |
375 // - File::FILE_ERROR_NOT_FOUND if |src_file_path| | |
376 // or the parent directory of |dest_url| does not exist. | |
377 // - File::FILE_ERROR_INVALID_OPERATION if |dest_url| exists and | |
378 // is not a file. | |
379 // - File::FILE_ERROR_FAILED if |dest_url| does not exist and | |
380 // its parent path is a file. | |
381 // | |
382 virtual void CopyInForeignFile(const base::FilePath& src_local_disk_path, | |
383 const FileSystemURL& dest_url, | |
384 const StatusCallback& callback) = 0; | |
385 | |
386 // Removes a single file. | |
387 // | |
388 // This returns: | |
389 // - File::FILE_ERROR_NOT_FOUND if |url| does not exist. | |
390 // - File::FILE_ERROR_NOT_A_FILE if |url| is not a file. | |
391 // | |
392 virtual void RemoveFile(const FileSystemURL& url, | |
393 const StatusCallback& callback) = 0; | |
394 | |
395 // Removes a single empty directory. | |
396 // | |
397 // This returns: | |
398 // - File::FILE_ERROR_NOT_FOUND if |url| does not exist. | |
399 // - File::FILE_ERROR_NOT_A_DIRECTORY if |url| is not a directory. | |
400 // - File::FILE_ERROR_NOT_EMPTY if |url| is not empty. | |
401 // | |
402 virtual void RemoveDirectory(const FileSystemURL& url, | |
403 const StatusCallback& callback) = 0; | |
404 | |
405 // Copies a file from |src_url| to |dest_url|. | |
406 // This must be called for files that belong to the same filesystem | |
407 // (i.e. type() and origin() of the |src_url| and |dest_url| must match). | |
408 // |option| specifies the minor behavior of Copy(). See CopyOrMoveOption's | |
409 // comment for details. | |
410 // |progress_callback| is periodically called to report the progress | |
411 // update. See also the comment of CopyFileProgressCallback. This callback is | |
412 // optional. | |
413 // | |
414 // This returns: | |
415 // - File::FILE_ERROR_NOT_FOUND if |src_url| | |
416 // or the parent directory of |dest_url| does not exist. | |
417 // - File::FILE_ERROR_NOT_A_FILE if |src_url| exists but is not a file. | |
418 // - File::FILE_ERROR_INVALID_OPERATION if |dest_url| exists and | |
419 // is not a file. | |
420 // - File::FILE_ERROR_FAILED if |dest_url| does not exist and | |
421 // its parent path is a file. | |
422 // | |
423 virtual void CopyFileLocal(const FileSystemURL& src_url, | |
424 const FileSystemURL& dest_url, | |
425 CopyOrMoveOption option, | |
426 const CopyFileProgressCallback& progress_callback, | |
427 const StatusCallback& callback) = 0; | |
428 | |
429 // Moves a local file from |src_url| to |dest_url|. | |
430 // This must be called for files that belong to the same filesystem | |
431 // (i.e. type() and origin() of the |src_url| and |dest_url| must match). | |
432 // |option| specifies the minor behavior of Copy(). See CopyOrMoveOption's | |
433 // comment for details. | |
434 // | |
435 // This returns: | |
436 // - File::FILE_ERROR_NOT_FOUND if |src_url| | |
437 // or the parent directory of |dest_url| does not exist. | |
438 // - File::FILE_ERROR_NOT_A_FILE if |src_url| exists but is not a file. | |
439 // - File::FILE_ERROR_INVALID_OPERATION if |dest_url| exists and | |
440 // is not a file. | |
441 // - File::FILE_ERROR_FAILED if |dest_url| does not exist and | |
442 // its parent path is a file. | |
443 // | |
444 virtual void MoveFileLocal(const FileSystemURL& src_url, | |
445 const FileSystemURL& dest_url, | |
446 CopyOrMoveOption option, | |
447 const StatusCallback& callback) = 0; | |
448 | |
449 // Synchronously gets the platform path for the given |url|. | |
450 // This may fail if the given |url|'s filesystem type is neither | |
451 // temporary nor persistent. | |
452 // In such a case, base::File::FILE_ERROR_INVALID_OPERATION will be | |
453 // returned. | |
454 virtual base::File::Error SyncGetPlatformPath( | |
455 const FileSystemURL& url, | |
456 base::FilePath* platform_path) = 0; | |
457 | |
458 protected: | |
459 // Used only for internal assertions. | |
460 enum OperationType { | |
461 kOperationNone, | |
462 kOperationCreateFile, | |
463 kOperationCreateDirectory, | |
464 kOperationCreateSnapshotFile, | |
465 kOperationCopy, | |
466 kOperationCopyInForeignFile, | |
467 kOperationMove, | |
468 kOperationDirectoryExists, | |
469 kOperationFileExists, | |
470 kOperationGetMetadata, | |
471 kOperationReadDirectory, | |
472 kOperationRemove, | |
473 kOperationWrite, | |
474 kOperationTruncate, | |
475 kOperationTouchFile, | |
476 kOperationOpenFile, | |
477 kOperationCloseFile, | |
478 kOperationGetLocalPath, | |
479 kOperationCancel, | |
480 }; | |
481 }; | |
482 | |
483 } // namespace storage | |
484 | |
485 #endif // WEBKIT_BROWSER_FILEAPI_FILE_SYSTEM_OPERATION_H_ | |
OLD | NEW |