download_item.h revision 868fa2fe829687343ffae624259930155e16dbd8
1// Copyright (c) 2012 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// Each download is represented by a DownloadItem, and all DownloadItems 6// are owned by the DownloadManager which maintains a global list of all 7// downloads. DownloadItems are created when a user initiates a download, 8// and exist for the duration of the browser life time. 9// 10// Download observers: 11// DownloadItem::Observer: 12// - allows observers to receive notifications about one download from start 13// to completion 14// Use AddObserver() / RemoveObserver() on the appropriate download object to 15// receive state updates. 16 17#ifndef CONTENT_PUBLIC_BROWSER_DOWNLOAD_ITEM_H_ 18#define CONTENT_PUBLIC_BROWSER_DOWNLOAD_ITEM_H_ 19 20#include <map> 21#include <string> 22#include <vector> 23 24#include "base/callback_forward.h" 25#include "base/files/file_path.h" 26#include "base/string16.h" 27#include "base/supports_user_data.h" 28#include "content/public/browser/download_danger_type.h" 29#include "content/public/browser/download_interrupt_reasons.h" 30#include "content/public/common/page_transition_types.h" 31 32class GURL; 33 34namespace base { 35class FilePath; 36class Time; 37class TimeDelta; 38} 39 40namespace content { 41 42class BrowserContext; 43class DownloadId; 44class DownloadManager; 45class WebContents; 46 47// One DownloadItem per download. This is the model class that stores all the 48// state for a download. Multiple views, such as a tab's download shelf and the 49// Destination tab's download view, may refer to a given DownloadItem. 50// 51// This is intended to be used only on the UI thread. 52class CONTENT_EXPORT DownloadItem : public base::SupportsUserData { 53 public: 54 enum DownloadState { 55 // Download is actively progressing. 56 IN_PROGRESS = 0, 57 58 // Download is completely finished. 59 COMPLETE, 60 61 // Download has been cancelled. 62 CANCELLED, 63 64 // This state indicates that the download has been interrupted. 65 INTERRUPTED, 66 67 // Maximum value. 68 MAX_DOWNLOAD_STATE 69 }; 70 71 // How the final target path should be used. 72 enum TargetDisposition { 73 TARGET_DISPOSITION_OVERWRITE, // Overwrite if the target already exists. 74 TARGET_DISPOSITION_PROMPT // Prompt the user for the actual 75 // target. Implies 76 // TARGET_DISPOSITION_OVERWRITE. 77 }; 78 79 // Callback used with AcquireFileAndDeleteDownload(). 80 typedef base::Callback<void(const base::FilePath&)> AcquireFileCallback; 81 82 static const char kEmptyFileHash[]; 83 84 // Interface that observers of a particular download must implement in order 85 // to receive updates to the download's status. 86 class CONTENT_EXPORT Observer { 87 public: 88 virtual void OnDownloadUpdated(DownloadItem* download) {} 89 virtual void OnDownloadOpened(DownloadItem* download) {} 90 virtual void OnDownloadRemoved(DownloadItem* download) {} 91 92 // Called when the download is being destroyed. This happens after 93 // every OnDownloadRemoved() as well as when the DownloadManager is going 94 // down. 95 virtual void OnDownloadDestroyed(DownloadItem* download) {} 96 97 protected: 98 virtual ~Observer() {} 99 }; 100 101 virtual ~DownloadItem() {} 102 103 // Observation --------------------------------------------------------------- 104 105 virtual void AddObserver(DownloadItem::Observer* observer) = 0; 106 virtual void RemoveObserver(DownloadItem::Observer* observer) = 0; 107 virtual void UpdateObservers() = 0; 108 109 // User Actions -------------------------------------------------------------- 110 111 // Called when the user has validated the download of a dangerous file. 112 virtual void ValidateDangerousDownload() = 0; 113 114 // Called to acquire a dangerous download and remove the DownloadItem from 115 // views and history. |callback| will be invoked on the UI thread with the 116 // path to the downloaded file. The caller is responsible for cleanup. 117 // Note: It is important for |callback| to be valid since the downloaded file 118 // will not be cleaned up if the callback fails. 119 virtual void StealDangerousDownload(const AcquireFileCallback& callback) = 0; 120 121 // Pause a download. Will have no effect if the download is already 122 // paused. 123 virtual void Pause() = 0; 124 125 // Resume a download that has been paused or interrupted. Will have no effect 126 // if the download is neither. 127 virtual void Resume() = 0; 128 129 // Cancel the download operation. We need to distinguish between cancels at 130 // exit (DownloadManager destructor) from user interface initiated cancels 131 // because at exit, the history system may not exist, and any updates to it 132 // require AddRef'ing the DownloadManager in the destructor which results in 133 // a DCHECK failure. Set |user_cancel| to false when canceling from at 134 // exit to prevent this crash. This may result in a difference between the 135 // downloaded file's size on disk, and what the history system's last record 136 // of it is. At worst, we'll end up re-downloading a small portion of the file 137 // when resuming a download (assuming the server supports byte ranges). 138 virtual void Cancel(bool user_cancel) = 0; 139 140 // Removes the download from the views and history. If the download was 141 // in-progress or interrupted, then the intermediate file will also be 142 // deleted. 143 virtual void Remove() = 0; 144 145 // Open the file associated with this download. If the download is 146 // still in progress, marks the download to be opened when it is complete. 147 virtual void OpenDownload() = 0; 148 149 // Show the download via the OS shell. 150 virtual void ShowDownloadInShell() = 0; 151 152 // State accessors ----------------------------------------------------------- 153 154 virtual int32 GetId() const = 0; 155 virtual DownloadId GetGlobalId() const = 0; 156 virtual DownloadState GetState() const = 0; 157 158 // Returns the most recent interrupt reason for this download. Returns 159 // DOWNLOAD_INTERRUPT_REASON_NONE if there is no previous interrupt reason. 160 // Cancelled downloads return DOWNLOAD_INTERRUPT_REASON_USER_CANCELLED. If 161 // the download was resumed, then the return value is the interrupt reason 162 // prior to resumption. 163 virtual DownloadInterruptReason GetLastReason() const = 0; 164 165 virtual bool IsPaused() const = 0; 166 virtual bool IsTemporary() const = 0; 167 168 // Returns true if the download can be resumed. A download can be resumed if 169 // an in-progress download was paused or if an interrupted download requires 170 // user-interaction to resume. 171 virtual bool CanResume() const = 0; 172 173 // Returns true if the download is in a terminal state. This includes 174 // completed downloads, cancelled downloads, and interrupted downloads that 175 // can't be resumed. 176 virtual bool IsDone() const = 0; 177 178 // Convenience routines for accessing GetState() results conceptually ----- 179 180 // Returns true if the download is still receiving data. 181 virtual bool IsInProgress() const = 0; 182 183 // Returns true if the download has been cancelled or was interrupted. 184 virtual bool IsCancelled() const = 0; 185 186 // Returns true if the download was interrupted. 187 virtual bool IsInterrupted() const = 0; 188 189 // Returns true if we have all the data and know the final file name. 190 virtual bool IsComplete() const = 0; 191 192 // Origin State accessors ------------------------------------------------- 193 194 virtual const GURL& GetURL() const = 0; 195 virtual const std::vector<GURL>& GetUrlChain() const = 0; 196 virtual const GURL& GetOriginalUrl() const = 0; 197 virtual const GURL& GetReferrerUrl() const = 0; 198 virtual std::string GetSuggestedFilename() const = 0; 199 virtual std::string GetContentDisposition() const = 0; 200 virtual std::string GetMimeType() const = 0; 201 virtual std::string GetOriginalMimeType() const = 0; 202 virtual std::string GetRemoteAddress() const = 0; 203 virtual bool HasUserGesture() const = 0; 204 virtual PageTransition GetTransitionType() const = 0; 205 virtual const std::string& GetLastModifiedTime() const = 0; 206 virtual const std::string& GetETag() const = 0; 207 virtual bool IsSavePackageDownload() const = 0; 208 209 // Destination State accessors -------------------------------------------- 210 211 // Full path to the downloaded or downloading file. This is the path to the 212 // physical file, if one exists. It should be considered a hint; changes to 213 // this value and renames of the file on disk are not atomic with each other. 214 // May be empty if the in-progress path hasn't been determined yet or if the 215 // download was interrupted. 216 // 217 // DO NOT USE THIS METHOD to access the target path of the DownloadItem. Use 218 // GetTargetFilePath() instead. While the download is in progress, the 219 // intermediate file named by GetFullPath() may be renamed or disappear 220 // completely on the FILE thread. The path may also be reset to empty when the 221 // download is interrupted. 222 virtual const base::FilePath& GetFullPath() const = 0; 223 224 // Target path of an in-progress download. We may be downloading to a 225 // temporary or intermediate file (specified by GetFullPath()); this is the 226 // name we will use once the download completes. 227 // May be empty if the target path hasn't yet been determined. 228 virtual const base::FilePath& GetTargetFilePath() const = 0; 229 230 // If the download forced a path rather than requesting name determination, 231 // return the path requested. 232 virtual const base::FilePath& GetForcedFilePath() const = 0; 233 234 // Returns the file-name that should be reported to the user. If a display 235 // name has been explicitly set using SetDisplayName(), this function returns 236 // that display name. Otherwise returns the final target filename. 237 virtual base::FilePath GetFileNameToReportUser() const = 0; 238 239 virtual TargetDisposition GetTargetDisposition() const = 0; 240 241 // Final hash of completely downloaded file; not valid if 242 // GetState() != COMPLETED. 243 virtual const std::string& GetHash() const = 0; 244 245 // Intermediate hash state, for persisting partial downloads. 246 virtual const std::string& GetHashState() const = 0; 247 248 // True if the file associated with the download has been removed by 249 // external action. 250 virtual bool GetFileExternallyRemoved() const = 0; 251 252 // True if the file that will be written by the download is dangerous 253 // and we will require a call to ValidateDangerousDownload() to complete. 254 // False if the download is safe or that function has been called. 255 virtual bool IsDangerous() const = 0; 256 257 // Why |safety_state_| is not SAFE. 258 virtual DownloadDangerType GetDangerType() const = 0; 259 260 // Progress State accessors ----------------------------------------------- 261 262 // Simple calculation of the amount of time remaining to completion. Fills 263 // |*remaining| with the amount of time remaining if successful. Fails and 264 // returns false if we do not have the number of bytes or the speed so can 265 // not estimate. 266 virtual bool TimeRemaining(base::TimeDelta* remaining) const = 0; 267 268 // Simple speed estimate in bytes/s 269 virtual int64 CurrentSpeed() const = 0; 270 271 // Rough percent complete, -1 means we don't know (== we didn't receive a 272 // total size). 273 virtual int PercentComplete() const = 0; 274 275 // Returns true if this download has saved all of its data. 276 virtual bool AllDataSaved() const = 0; 277 278 virtual int64 GetTotalBytes() const = 0; 279 virtual int64 GetReceivedBytes() const = 0; 280 virtual base::Time GetStartTime() const = 0; 281 virtual base::Time GetEndTime() const = 0; 282 283 // Open/Show State accessors ---------------------------------------------- 284 285 // Returns true if it is OK to open a folder which this file is inside. 286 virtual bool CanShowInFolder() = 0; 287 288 // Returns true if it is OK to open the download. 289 virtual bool CanOpenDownload() = 0; 290 291 // Tests if a file type should be opened automatically. 292 virtual bool ShouldOpenFileBasedOnExtension() = 0; 293 294 // Returns true if the download will be auto-opened when complete. 295 virtual bool GetOpenWhenComplete() const = 0; 296 297 // Returns true if the download has been auto-opened by the system. 298 virtual bool GetAutoOpened() = 0; 299 300 // Returns true if the download has been opened. 301 virtual bool GetOpened() const = 0; 302 303 // Misc State accessors --------------------------------------------------- 304 305 virtual BrowserContext* GetBrowserContext() const = 0; 306 virtual WebContents* GetWebContents() const = 0; 307 308 // External state transitions/setters ---------------------------------------- 309 // TODO(rdsmith): These should all be removed; the download item should 310 // control its own state transitions. 311 312 // Called if a check of the download contents was performed and the results of 313 // the test are available. This should only be called after AllDataSaved() is 314 // true. 315 virtual void OnContentCheckCompleted(DownloadDangerType danger_type) = 0; 316 317 // Mark the download to be auto-opened when completed. 318 virtual void SetOpenWhenComplete(bool open) = 0; 319 320 // Mark the download as temporary (not visible in persisted store or 321 // SearchDownloads(), removed from main UI upon completion). 322 virtual void SetIsTemporary(bool temporary) = 0; 323 324 // Mark the download as having been opened (without actually opening it). 325 virtual void SetOpened(bool opened) = 0; 326 327 // Set a display name for the download that will be independent of the target 328 // filename. If |name| is not empty, then GetFileNameToReportUser() will 329 // return |name|. Has no effect on the final target filename. 330 virtual void SetDisplayName(const base::FilePath& name) = 0; 331 332 // Debug/testing ------------------------------------------------------------- 333 virtual std::string DebugString(bool verbose) const = 0; 334}; 335 336} // namespace content 337 338#endif // CONTENT_PUBLIC_BROWSER_DOWNLOAD_ITEM_H_ 339