Adds callbacks to notify progress into Copy's API.

webkit/browser/fileapi/file_system_operation.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef WEBKIT_BROWSER_FILEAPI_FILE_SYSTEM_OPERATION_H_
 #define WEBKIT_BROWSER_FILEAPI_FILE_SYSTEM_OPERATION_H_
 
 #include <vector>
 
 #include "base/callback.h"
@@ skipping 97 matching lines @@
   // longer necessary in the javascript world.
   // Please see the comment for ShareableFileReference for details.
   //
   typedef base::Callback<
       void(base::PlatformFileError result,
            const base::PlatformFileInfo& file_info,
            const base::FilePath& platform_path,
            const scoped_refptr<webkit_blob::ShareableFileReference>& file_ref)>
           SnapshotFileCallback;
 
+  // Used for progress update callback for Copy().
+  //
+  // BEGIN_COPY_ENTRY is fired for each copy creation beginning (for both
+  // file and directory).
+  // The |source_url| is the URL of the source entry. |size| should not be
+  // used.
+  //
+  // END_COPY_ENTRY is fired for each copy creation finishing (for both
+  // file and directory).
+  // The |source_url| is the URL of the source entry. |size| should not be
+  // used.
+  //
+  // PROGRESS is fired periodically during file copying (not fired for
+  // directory copy).
+  // The |source_url| is the URL of the source file. |size| is the number
+  // of cumulative copied bytes for the currently copied file.
+  // Both at beginning and ending of file copying, PROGRESS event should be
+  // called. At beginning, |size| should be 0. At ending, |size| should be
+  // the size of the file.
+  //
+  // Here is an example callback sequence of recursive copy. Suppose
+  // there are a/b/c.txt (100 bytes) and a/b/d.txt (200 bytes), and trying to
+  // copy a to x recursively, then the progress update sequence will be:
+  //
+  // BEGIN_COPY_ENTRY a  (starting create "a" directory in x/).
+  // END_COPY_ENTRY a (creating "a" directory in x/ is finished).
+  //
+  // BEGIN_COPY_ENTRY a/b (starting create "b" directory in x/a).
+  // END_COPY_ENTRY a/b (creating "b" directory in x/a/ is finished).
+  //
+  // BEGIN_COPY_ENTRY a/b/c.txt (starting to copy "c.txt" in x/a/b/).
+  // PROGRESS a/b/c.txt 0 (The first PROGRESS's |size| should be 0).
+  // PROGRESS a/b/c.txt 10
+  //    :
+  // PROGRESS a/b/c.txt 90
+  // PROGRESS a/b/c.txt 100 (The last PROGRESS's |size| should be the size of
+  //                         the file).
+  // END_COPY_ENTRY a/b/c.txt (copying "c.txt" is finished).
+  //
+  // BEGIN_COPY_ENTRY a/b/d.txt (starting to copy "d.txt" in x/a/b).
+  // PROGRESS a/b/d.txt 0 (The first PROGRESS's |size| should be 0).
+  // PROGRESS a/b/d.txt 10
+  //    :
+  // PROGRESS a/b/d.txt 190
+  // PROGRESS a/b/d.txt 200 (The last PROGRESS's |size| should be the size of
+  //                         the file).
+  // END_COPY_ENTRY a/b/d.txt (copy "d.txt" is finished).
+  //
+  // Note that event sequence of a/b/c.txt and a/b/d.txt can be interlaced,
+  // because they can be done in parallel.
+  enum CopyProgressType {
+    BEGIN_COPY_ENTRY,
+    END_COPY_ENTRY,
+    PROGRESS,
+  };
+  typedef base::Callback<void(
+      CopyProgressType type, const FileSystemURL& source_url, int64 size)>
+      CopyProgressCallback;
+
+  // Used for CopyFileLocal() to report progress update.
+  // |size| is the cumulative copied bytes for the copy.
+  // At the beginning the progress callback should be called with |size| = 0,
+  // and also at the ending the progress callback should be called with |size|
+  // set to the copied file size.
+  typedef base::Callback<void(int64 size)> CopyFileProgressCallback;

[kinuko, 2013/09/06 09:55:25]

Question: how difficult would it be (in terms of cost+complexity etc) to add the
same/similar progress callback to Move operation?  It feels a bit weird that
these two have different signature.

[hidehiko, 2013/09/06 10:06:16]

IMHO, it's a bit complicated especially for directory move (recursively).
"Move" may be implemented as just updating the root's metadata. In such a case,
generating progress would be much different from one for the copy-after-delete.
Thus, we need to add more concept to the progress.

[kinuko, 2013/09/09 03:46:31]

Would it need more effort than adding one more progress type, if not firing any
progress event?  In cross-filesystem move we basically need to fall back to
recursive copy + remove, in which case I feel it's more natural to fire progress
callbacks.

Another question-- if the copy fails even before processing one file no progress
events should be fired?  (Asking this because OWP JS APIs tend to have multiple
progress event types and expects UA to fire at least one progress event at the
end of the operation (like 'fooend' for 'foo' operation) even in error case)  In
any case could we add a comment about the behavior?

[hidehiko, 2013/09/09 04:48:15]

Added comments about future extension and on error.

+
   // Used for Write().
   typedef base::Callback<void(base::PlatformFileError result,
                               int64 bytes,
                               bool complete)> WriteCallback;
 
   // Creates a file at |path|. If |exclusive| is true, an error is raised
   // in case a file is already present at the URL.
   virtual void CreateFile(const FileSystemURL& path,
                           bool exclusive,
                           const StatusCallback& callback) = 0;
 
   // Creates a directory at |path|. If |exclusive| is true, an error is
   // raised in case a directory is already present at the URL. If
   // |recursive| is true, create parent directories as needed just like
   // mkdir -p does.
   virtual void CreateDirectory(const FileSystemURL& path,
                                bool exclusive,
                                bool recursive,
                                const StatusCallback& callback) = 0;
 
   // Copies a file or directory from |src_path| to |dest_path|. If
   // |src_path| is a directory, the contents of |src_path| are copied to
   // |dest_path| recursively. A new file or directory is created at
   // |dest_path| as needed.
+  // |progress_callback| is periodically called to report the progress
+  // update. See also the comment of CopyProgressCallback. This callback is
+  // optional.
   //
   // For recursive case this internally creates new FileSystemOperations and
   // calls:
   // - ReadDirectory, CopyFileLocal and CreateDirectory
   //   for same-filesystem case, or
   // - ReadDirectory and CreateSnapshotFile on source filesystem and
   //   CopyInForeignFile and CreateDirectory on dest filesystem
   //   for cross-filesystem case.
   //
   virtual void Copy(const FileSystemURL& src_path,
                     const FileSystemURL& dest_path,
+                    const CopyProgressCallback& progress_callback,
                     const StatusCallback& callback) = 0;
 
   // Moves a file or directory from |src_path| to |dest_path|. A new file
   // or directory is created at |dest_path| as needed.
   //
   // For recursive case this internally creates new FileSystemOperations and
   // calls:
   // - ReadDirectory, MoveFileLocal, CreateDirectory and Remove
   //   for same-filesystem case, or
   // - ReadDirectory, CreateSnapshotFile and Remove on source filesystem and
@@ skipping 125 matching lines @@
   // - PLATFORM_FILE_ERROR_NOT_FOUND if |url| does not exist.
   // - PLATFORM_FILE_ERROR_NOT_A_DIRECTORY if |url| is not a directory.
   // - PLATFORM_FILE_ERROR_NOT_EMPTY if |url| is not empty.
   //
   virtual void RemoveDirectory(const FileSystemURL& url,
                                const StatusCallback& callback) = 0;
 
   // Copies a file from |src_url| to |dest_url|.
   // This must be called for files that belong to the same filesystem
   // (i.e. type() and origin() of the |src_url| and |dest_url| must match).
+  // |progress_callback| is periodically called to report the progress
+  // update. See also the comment of CopyFileProgressCallback. This callback is
+  // optional.
   //
   // This returns:
   // - PLATFORM_FILE_ERROR_NOT_FOUND if |src_url|
   //   or the parent directory of |dest_url| does not exist.
   // - PLATFORM_FILE_ERROR_NOT_A_FILE if |src_url| exists but is not a file.
   // - PLATFORM_FILE_ERROR_INVALID_OPERATION if |dest_url| exists and
   //   is not a file.
   // - PLATFORM_FILE_ERROR_FAILED if |dest_url| does not exist and
   //   its parent path is a file.
   //
   virtual void CopyFileLocal(const FileSystemURL& src_url,
                              const FileSystemURL& dest_url,
+                             const CopyFileProgressCallback& progress_callback,
                              const StatusCallback& callback) = 0;
 
   // Moves a local file from |src_url| to |dest_url|.
   // This must be called for files that belong to the same filesystem
   // (i.e. type() and origin() of the |src_url| and |dest_url| must match).
   //
   // This returns:
   // - PLATFORM_FILE_ERROR_NOT_FOUND if |src_url|
   //   or the parent directory of |dest_url| does not exist.
   // - PLATFORM_FILE_ERROR_NOT_A_FILE if |src_url| exists but is not a file.
@@ skipping 36 matching lines @@
     kOperationOpenFile,
     kOperationCloseFile,
     kOperationGetLocalPath,
     kOperationCancel,
   };
 };
 
 }  // namespace fileapi
 
 #endif  // WEBKIT_BROWSER_FILEAPI_FILE_SYSTEM_OPERATION_H_