[Downloads] Allow acquiring dangerous download file.

content/public/browser/download_item.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.
 //
 // Each download is represented by a DownloadItem, and all DownloadItems
 // are owned by the DownloadManager which maintains a global list of all
 // downloads. DownloadItems are created when a user initiates a download,
 // and exist for the duration of the browser life time.
 //
 // Download observers:
 //   DownloadItem::Observer:
 //     - allows observers to receive notifications about one download from start
 //       to completion
 // Use AddObserver() / RemoveObserver() on the appropriate download object to
 // receive state updates.
 
 #ifndef CONTENT_PUBLIC_BROWSER_DOWNLOAD_ITEM_H_
 #define CONTENT_PUBLIC_BROWSER_DOWNLOAD_ITEM_H_
 
 #include <map>
 #include <string>
 #include <vector>
 
+#include "base/callback_forward.h"
 #include "base/files/file_path.h"
 #include "base/string16.h"
 #include "base/supports_user_data.h"
 #include "content/public/browser/download_danger_type.h"
 #include "content/public/browser/download_interrupt_reasons.h"
 #include "content/public/common/page_transition_types.h"
 
 class GURL;
 
 namespace base {
@@ skipping 40 matching lines @@
   };
 
   // How the final target path should be used.
   enum TargetDisposition {
     TARGET_DISPOSITION_OVERWRITE, // Overwrite if the target already exists.
     TARGET_DISPOSITION_PROMPT     // Prompt the user for the actual
                                   // target. Implies
                                   // TARGET_DISPOSITION_OVERWRITE.
   };
 
+  // Callback used with AcquireFileAndDeleteDownload().
+  typedef base::Callback<void(const base::FilePath&)> AcquireFileCallback;
+
   static const char kEmptyFileHash[];
 
   // Interface that observers of a particular download must implement in order
   // to receive updates to the download's status.
   class CONTENT_EXPORT Observer {
    public:
     virtual void OnDownloadUpdated(DownloadItem* download) {}
     virtual void OnDownloadOpened(DownloadItem* download) {}
     virtual void OnDownloadRemoved(DownloadItem* download) {}
 
@@ skipping 39 matching lines @@
   // exit to prevent this crash. This may result in a difference between the
   // downloaded file's size on disk, and what the history system's last record
   // of it is. At worst, we'll end up re-downloading a small portion of the file
   // when resuming a download (assuming the server supports byte ranges).
   virtual void Cancel(bool user_cancel) = 0;
 
   // Deletes the file from disk and removes the download from the views and
   // history.
   virtual void Delete(DeleteReason reason) = 0;
 
+  // Acquires the download file and deletes the download. Equivalent to calling
+  // |Delete(DELETE_DUE_TO_USER_DISCARD)| with the exception that the download
+  // file isn't deleted. The path to the file is passed to the |callback|. If
+  // the downloaded file is not available, then returned path will be empty.
+  virtual void AcquireFileAndDeleteDownload(

[benjhayden, 2013/05/14 20:48:05]

Method names containing "And" generally signal to me that the interface might be
cleaner if they were split up. In this case, why not let the caller call
AcquireFile() then Delete()?
In order to enforce the invariant !!download_file_ <=> IsInProgress(),
AcquireFile might call Cancel() or require callers to ensure that the item is
not in progress and DCHECK(!IsInProgress()).

[asanka, 2013/05/14 21:14:34]

The intention is for this operation to be atomic. This method would be called on
an IN_PROGRESS dangerous download to discard the DownloadItem but not the
download file.

Although, 'AcquireFileAndRemove' is probably a better name.

+      const AcquireFileCallback& callback) = 0;
+
   // Removes the download from the views and history.
   virtual void Remove() = 0;
 
   // Open the file associated with this download.  If the download is
   // still in progress, marks the download to be opened when it is complete.
   virtual void OpenDownload() = 0;
 
   // Show the download via the OS shell.
   virtual void ShowDownloadInShell() = 0;
 
@@ skipping 171 matching lines @@
   // return |name|. Has no effect on the final target filename.
   virtual void SetDisplayName(const base::FilePath& name) = 0;
 
   // Debug/testing -------------------------------------------------------------
   virtual std::string DebugString(bool verbose) const = 0;
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_DOWNLOAD_ITEM_H_