src/chrome/browser/download/download_target_determiner.h

   1 // Copyright 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
   5 #ifndef CHROME_BROWSER_DOWNLOAD_DOWNLOAD_TARGET_DETERMINER_H_
   6 #define CHROME_BROWSER_DOWNLOAD_DOWNLOAD_TARGET_DETERMINER_H_
   7
   8 #include "base/files/file_path.h"
   9 #include "base/memory/ref_counted.h"
  10 #include "base/memory/scoped_ptr.h"
  11 #include "base/memory/weak_ptr.h"
  12 #include "chrome/browser/common/cancelable_request.h"
  13 #include "chrome/browser/download/download_path_reservation_tracker.h"
  14 #include "chrome/browser/download/download_target_determiner_delegate.h"
  15 #include "content/public/browser/download_danger_type.h"
  16 #include "content/public/browser/download_item.h"
  17 #include "content/public/browser/download_manager_delegate.h"
  18
  19 class ChromeDownloadManagerDelegate;
  20 class Profile;
  21 class DownloadPrefs;
  22
  23 namespace content {
  24 enum DownloadDangerType;
  25 }
  26
  27 // Determines the target of the download.
  28 //
  29 // Terminology:
  30 //   Virtual Path: A path representing the target of the download that may or
  31 //     may not be a physical file path. E.g. if the target of the download is in
  32 //     cloud storage, then the virtual path may be relative to a logical mount
  33 //     point.
  34 //
  35 //   Local Path: A local file system path where the downloads system should
  36 //     write the file to.
  37 //
  38 //   Intermediate Path: Where the data should be written to during the course of
  39 //     the download. Once the download completes, the file could be renamed to
  40 //     Local Path.
  41 //
  42 // DownloadTargetDeterminer is a self owned object that performs the work of
  43 // determining the download target. It observes the DownloadItem and aborts the
  44 // process if the download is removed. DownloadTargetDeterminerDelegate is
  45 // responsible for providing external dependencies and prompting the user if
  46 // necessary.
  47 //
  48 // The only public entrypoint is the static Start() method which creates an
  49 // instance of DownloadTargetDeterminer.
  50 class DownloadTargetDeterminer
  51     : public content::DownloadItem::Observer {
  52  public:
  53   // Start the process of determing the target of |download|.
  54   //
  55   // |initial_virtual_path| if non-empty, defines the initial virtual path for
  56   //   the target determination process. If one isn't specified, one will be
  57   //   generated based on the response data specified in |download| and the
  58   //   users' downloads directory.
  59   //   Note: |initial_virtual_path| is only used if download has prompted the
  60   //       user before and doesn't have a forced path.
  61   // |download_prefs| is required and must outlive |download|. It is used for
  62   //   determining the user's preferences regarding the default downloads
  63   //   directory, prompting and auto-open behavior.
  64   // |delegate| is required and must live until |callback| is invoked.
  65   // |callback| will be scheduled asynchronously on the UI thread after download
  66   //   determination is complete or after |download| is destroyed.
  67   //
  68   // Start() should be called on the UI thread.
  69   static void Start(content::DownloadItem* download,
  70                     const base::FilePath& initial_virtual_path,
  71                     DownloadPrefs* download_prefs,
  72                     DownloadTargetDeterminerDelegate* delegate,
  73                     const content::DownloadTargetCallback& callback);
  74
  75   // Returns a .crdownload intermediate path for the |suggested_path|.
  76   static base::FilePath GetCrDownloadPath(const base::FilePath& suggested_path);
  77
  78  private:
  79   // The main workflow is controlled via a set of state transitions. Each state
  80   // has an associated handler. The handler for STATE_FOO is DoFoo. Each handler
  81   // performs work, determines the next state to transition to and returns a
  82   // Result indicating how the workflow should proceed. The loop ends when a
  83   // handler returns COMPLETE.
  84   enum State {
  85     STATE_GENERATE_TARGET_PATH,
  86     STATE_NOTIFY_EXTENSIONS,
  87     STATE_RESERVE_VIRTUAL_PATH,
  88     STATE_PROMPT_USER_FOR_DOWNLOAD_PATH,
  89     STATE_DETERMINE_LOCAL_PATH,
  90     STATE_CHECK_DOWNLOAD_URL,
  91     STATE_CHECK_VISITED_REFERRER_BEFORE,
  92     STATE_DETERMINE_INTERMEDIATE_PATH,
  93     STATE_NONE,
  94   };
  95
  96   // Result code returned by each step of the workflow below. Controls execution
  97   // of DoLoop().
  98   enum Result {
  99     // Continue processing. next_state_ is required to not be STATE_NONE.
 100     CONTINUE,
 101
 102     // The DoLoop() that invoked the handler should exit. This value is
 103     // typically returned when the handler has invoked an asynchronous operation
 104     // and is expecting a callback. If a handler returns this value, it has
 105     // taken responsibility for ensuring that DoLoop() is invoked. It is
 106     // possible that the handler has invoked another DoLoop() already.
 107     QUIT_DOLOOP,
 108
 109     // Target determination is complete.
 110     COMPLETE
 111   };
 112
 113   // Used with IsDangerousFile to indicate whether the user has visited the
 114   // referrer URL for the download prior to today.
 115   enum PriorVisitsToReferrer {
 116     NO_VISITS_TO_REFERRER,
 117     VISITED_REFERRER,
 118   };
 119
 120   // Construct a DownloadTargetDeterminer object. Constraints on the arguments
 121   // are as per Start() above.
 122   DownloadTargetDeterminer(
 123       content::DownloadItem* download,
 124       const base::FilePath& initial_virtual_path,
 125       DownloadPrefs* download_prefs,
 126       DownloadTargetDeterminerDelegate* delegate,
 127       const content::DownloadTargetCallback& callback);
 128
 129   virtual ~DownloadTargetDeterminer();
 130
 131   // Invoke each successive handler until a handler returns QUIT_DOLOOP or
 132   // COMPLETE. Note that as a result, this object might be deleted. So |this|
 133   // should not be accessed after calling DoLoop().
 134   void DoLoop();
 135
 136   // === Main workflow ===
 137
 138   // Generates an initial target path. This target is based only on the state of
 139   // the download item.
 140   // Next state:
 141   // - STATE_NONE : If the download is not in progress, returns COMPLETE.
 142   // - STATE_NOTIFY_EXTENSIONS : All other downloads.
 143   Result DoGenerateTargetPath();
 144
 145   // Notifies downloads extensions. If any extension wishes to override the
 146   // download filename, it will respond to the OnDeterminingFilename()
 147   // notification.
 148   // Next state:
 149   // - STATE_RESERVE_VIRTUAL_PATH.
 150   Result DoNotifyExtensions();
 151
 152   // Callback invoked after extensions are notified. Updates |virtual_path_| and
 153   // |conflict_action_|.
 154   void NotifyExtensionsDone(
 155       const base::FilePath& new_path,
 156       DownloadPathReservationTracker::FilenameConflictAction conflict_action);
 157
 158   // Invokes ReserveVirtualPath() on the delegate to acquire a reservation for
 159   // the path. See DownloadPathReservationTracker.
 160   // Next state:
 161   // - STATE_PROMPT_USER_FOR_DOWNLOAD_PATH.
 162   Result DoReserveVirtualPath();
 163
 164   // Callback invoked after the delegate aquires a path reservation.
 165   void ReserveVirtualPathDone(const base::FilePath& path, bool verified);
 166
 167   // Presents a file picker to the user if necessary.
 168   // Next state:
 169   // - STATE_DETERMINE_LOCAL_PATH.
 170   Result DoPromptUserForDownloadPath();
 171
 172   // Callback invoked after the file picker completes. Cancels the download if
 173   // the user cancels the file picker.
 174   void PromptUserForDownloadPathDone(const base::FilePath& virtual_path);
 175
 176   // Up until this point, the path that was used is considered to be a virtual
 177   // path. This step determines the local file system path corresponding to this
 178   // virtual path. The translation is done by invoking the DetermineLocalPath()
 179   // method on the delegate.
 180   // Next state:
 181   // - STATE_CHECK_DOWNLOAD_URL.
 182   Result DoDetermineLocalPath();
 183
 184   // Callback invoked when the delegate has determined local path.
 185   void DetermineLocalPathDone(const base::FilePath& local_path);
 186
 187   // Checks whether the downloaded URL is malicious. Invokes the
 188   // DownloadProtectionService via the delegate.
 189   // Next state:
 190   // - STATE_CHECK_VISITED_REFERRER_BEFORE.
 191   Result DoCheckDownloadUrl();
 192
 193   // Callback invoked after the delegate has checked the download URL. Sets the
 194   // danger type of the download to |danger_type|.
 195   void CheckDownloadUrlDone(content::DownloadDangerType danger_type);
 196
 197   // Checks if the user has visited the referrer URL of the download prior to
 198   // today. The actual check is only performed if it would be needed to
 199   // determine the danger type of the download.
 200   // Next state:
 201   // - STATE_DETERMINE_INTERMEDIATE_PATH.
 202   Result DoCheckVisitedReferrerBefore();
 203
 204   // Callback invoked after completion of history check for prior visits to
 205   // referrer URL.
 206   void CheckVisitedReferrerBeforeDone(bool visited_referrer_before);
 207
 208   // Determines the intermediate path. Once this step completes, downloads
 209   // target determination is complete. The determination assumes that the
 210   // intermediate file will never be overwritten (always uniquified if needed).
 211   // Next state:
 212   // - STATE_NONE: Returns COMPLETE.
 213   Result DoDetermineIntermediatePath();
 214
 215   // === End of main workflow ===
 216
 217   // Utilities:
 218
 219   void ScheduleCallbackAndDeleteSelf();
 220
 221   void CancelOnFailureAndDeleteSelf();
 222
 223   Profile* GetProfile();
 224
 225   // Determine whether to prompt the user for the download location. For regular
 226   // downloads, this determination is based on the target disposition, auto-open
 227   // behavior, among other factors. For an interrupted download, this
 228   // determination will be based on the interrupt reason. It is assumed that
 229   // download interruptions always occur after the first round of download
 230   // target determination is complete.
 231   bool ShouldPromptForDownload(const base::FilePath& filename) const;
 232
 233   // Returns true if the user has been prompted for this download at least once
 234   // prior to this target determination operation. This method is only expected
 235   // to return true for a resuming interrupted download that has prompted the
 236   // user before interruption. The return value does not depend on whether the
 237   // user will be or has been prompted during the current target determination
 238   // operation.
 239   bool HasPromptedForPath() const;
 240
 241   // Returns true if this download should show the "dangerous file" warning.
 242   // Various factors are considered, such as the type of the file, whether a
 243   // user action initiated the download, and whether the user has explicitly
 244   // marked the file type as "auto open". Protected virtual for testing.
 245   bool IsDangerousFile(PriorVisitsToReferrer visits);
 246
 247   // content::DownloadItem::Observer
 248   virtual void OnDownloadDestroyed(content::DownloadItem* download) OVERRIDE;
 249
 250   // state
 251   State next_state_;
 252   bool should_prompt_;
 253   bool should_notify_extensions_;
 254   bool create_target_directory_;
 255   DownloadPathReservationTracker::FilenameConflictAction conflict_action_;
 256   content::DownloadDangerType danger_type_;
 257   base::FilePath virtual_path_;
 258   base::FilePath local_path_;
 259   base::FilePath intermediate_path_;
 260
 261   content::DownloadItem* download_;
 262   const bool is_resumption_;
 263   DownloadPrefs* download_prefs_;
 264   DownloadTargetDeterminerDelegate* delegate_;
 265   content::DownloadTargetCallback completion_callback_;
 266   CancelableRequestConsumer history_consumer_;
 267
 268   base::WeakPtrFactory<DownloadTargetDeterminer> weak_ptr_factory_;
 269
 270   DISALLOW_COPY_AND_ASSIGN(DownloadTargetDeterminer);
 271 };
 272
 273 #endif  // CHROME_BROWSER_DOWNLOAD_DOWNLOAD_TARGET_DETERMINER_H_