blob: eb9422c7947abf8c32573cfdbf1f8e6ab16f8e1e [file] [log] [blame]
// Copyright 2018 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.
#include <stdint.h>
#include <memory>
#include <string>
#include <utility>
#include <vector>
#include "base/callback.h"
#include "base/macros.h"
#include "base/optional.h"
#include "components/download/public/common/download_interrupt_reasons.h"
#include "components/download/public/common/download_save_info.h"
#include "components/download/public/common/download_source.h"
#include "net/traffic_annotation/network_traffic_annotation.h"
#include "net/url_request/url_request.h"
#include "services/network/public/cpp/resource_request_body.h"
#include "storage/browser/blob/blob_data_handle.h"
#include "url/gurl.h"
#include "url/origin.h"
namespace download {
class DownloadItem;
// Pass an instance of DownloadUrlParameters to DownloadManager::DownloadUrl()
// to download the content at |url|. All parameters with setters are optional.
// |referrer| and |referrer_encoding| are the referrer for the download. If
// |prefer_cache| is true, then if the response to |url| is in the HTTP cache it
// will be used without revalidation. If |post_id| is non-negative, then it
// identifies the post transaction used to originally retrieve the |url|
// resource - it also requires |prefer_cache| to be |true| since re-post'ing is
// not done. |save_info| specifies where the downloaded file should be saved,
// and whether the user should be prompted about the download. If not null,
// |callback| will be called when the download starts, or if an error occurs
// that prevents a download item from being created. We send a pointer to
// content::ResourceContext instead of the usual reference so that a copy of the
// object isn't made.
class COMPONENTS_DOWNLOAD_EXPORT DownloadUrlParameters {
// An OnStartedCallback is invoked when a response is available for the
// download request. For new downloads, this callback is invoked after the
// OnDownloadCreated notification is issued by the DownloadManager. If the
// download fails, then the DownloadInterruptReason parameter will indicate
// the failure.
// DownloadItem* may be nullptr if no DownloadItem was created. DownloadItems
// are not created when a resource throttle or a resource handler blocks the
// download request. I.e. the download triggered a warning of some sort and
// the user chose to not to proceed with the download as a result.
typedef base::Callback<void(DownloadItem*, DownloadInterruptReason)>
typedef std::pair<std::string, std::string> RequestHeadersNameValuePair;
typedef std::vector<RequestHeadersNameValuePair> RequestHeadersType;
using BlobStorageContextGetter =
using UploadProgressCallback =
base::RepeatingCallback<void(uint64_t bytes_uploaded)>;
// Constructs a download not associated with a frame.
// It is not safe to have downloads not associated with a frame and
// this should only be done in a limited set of cases where the download URL
// has been previously vetted. A download that's initiated without
// associating it with a frame don't receive the same security checks
// as a request that's associated with one. Hence, downloads that are not
// associated with a frame should only be made for URLs that are either
// trusted or URLs that have previously been successfully issued using a
// non-privileged frame.
const GURL& url,
const net::NetworkTrafficAnnotationTag& traffic_annotation);
// The RenderView routing ID must correspond to the RenderView of the
// RenderFrame, both of which share the same RenderProcess. This may be a
// different RenderView than the WebContents' main RenderView.
const GURL& url,
int render_process_host_id,
int render_view_host_routing_id,
int render_frame_host_routing_id,
const net::NetworkTrafficAnnotationTag& traffic_annotation);
// Should be set to true if the download was initiated by a script or a web
// page. I.e. if the download request cannot be attributed to an explicit user
// request for a download, then set this value to true.
void set_content_initiated(bool content_initiated) {
content_initiated_ = content_initiated;
void add_request_header(const std::string& name, const std::string& value) {
request_headers_.push_back(make_pair(name, value));
// HTTP Referrer, referrer policy and encoding.
void set_referrer(const GURL& referrer) { referrer_ = referrer; }
void set_referrer_policy(net::URLRequest::ReferrerPolicy referrer_policy) {
referrer_policy_ = referrer_policy;
void set_referrer_encoding(const std::string& referrer_encoding) {
referrer_encoding_ = referrer_encoding;
// The origin of the context which initiated the request. See
// net::URLRequest::initiator().
void set_initiator(const base::Optional<url::Origin>& initiator) {
initiator_ = initiator;
// If this is a request for resuming an HTTP/S download, |last_modified|
// should be the value of the last seen Last-Modified response header.
void set_last_modified(const std::string& last_modified) {
last_modified_ = last_modified;
// If this is a request for resuming an HTTP/S download, |etag| should be the
// last seen Etag response header.
void set_etag(const std::string& etag) { etag_ = etag; }
// If the "If-Range" header is used in a partial request.
void set_use_if_range(bool use_if_range) { use_if_range_ = use_if_range; }
// HTTP method to use.
void set_method(const std::string& method) { method_ = method; }
// Body of the HTTP POST request.
void set_post_body(scoped_refptr<network::ResourceRequestBody> post_body) {
post_body_ = post_body;
// The blob storage context to be used for uploading blobs, if any.
void set_blob_storage_context_getter(BlobStorageContextGetter blob_getter) {
blob_storage_context_getter_ = std::move(blob_getter);
// If |prefer_cache| is true and the response to |url| is in the HTTP cache,
// it will be used without validation. If |method| is POST, then |post_id_|
// shoud be set via |set_post_id()| below to the identifier of the POST
// transaction used to originally retrieve the resource.
void set_prefer_cache(bool prefer_cache) { prefer_cache_ = prefer_cache; }
// See set_prefer_cache() above.
void set_post_id(int64_t post_id) { post_id_ = post_id; }
// See OnStartedCallback above.
void set_callback(const OnStartedCallback& callback) { callback_ = callback; }
// If not empty, specifies the full target path for the download. This value
// overrides the filename suggested by a Content-Disposition headers. It
// should only be set for programmatic downloads where the caller can verify
// the safety of the filename and the resulting download.
void set_file_path(const base::FilePath& file_path) {
save_info_.file_path = file_path;
// Suggested filename for the download. The suggestion can be overridden by
// either a Content-Disposition response header or a |file_path|.
void set_suggested_name(const base::string16& suggested_name) {
save_info_.suggested_name = suggested_name;
// If |offset| is non-zero, then a byte range request will be issued to fetch
// the range of bytes starting at |offset|.
// Use |set_length| to specify the last byte position, or the range
// request will be "Range:bytes={offset}-" to retrieve the rest of the file.
void set_offset(int64_t offset) { save_info_.offset = offset; }
// When |length| > 0, the range of bytes will be from
// |save_info_.offset| to |save_info_.offset| + |length| - 1.
// See |DownloadSaveInfo.length|.
void set_length(int64_t length) { save_info_.length = length; }
// If |offset| is non-zero, then |hash_of_partial_file| contains the raw
// SHA-256 hash of the first |offset| bytes of the target file. Only
// meaningful if a partial file exists and is identified by either the
// |file_path()| or |file()|.
void set_hash_of_partial_file(const std::string& hash_of_partial_file) {
save_info_.hash_of_partial_file = hash_of_partial_file;
// If |offset| is non-zero, then |hash_state| indicates the SHA-256 hash state
// of the first |offset| bytes of the target file. In this case, the prefix
// hash will be ignored since the |hash_state| is assumed to be correct if
// provided.
void set_hash_state(std::unique_ptr<crypto::SecureHash> hash_state) {
save_info_.hash_state = std::move(hash_state);
// If |prompt| is true, then the user will be prompted for a filename. Ignored
// if |file_path| is non-empty.
void set_prompt(bool prompt) { save_info_.prompt_for_save_location = prompt; }
void set_file(base::File file) { save_info_.file = std::move(file); }
void set_do_not_prompt_for_login(bool do_not_prompt) {
do_not_prompt_for_login_ = do_not_prompt;
// If |follow_cross_origin_redirects| is true, we will follow cross origin
// redirects while downloading, otherwise, we'll attempt to navigate to the
// URL or cancel the download.
void set_follow_cross_origin_redirects(bool follow_cross_origin_redirects) {
follow_cross_origin_redirects_ = follow_cross_origin_redirects;
// Sets whether to download the response body even if the server returns
// non-successful HTTP response code, like "HTTP NOT FOUND".
void set_fetch_error_body(bool fetch_error_body) {
fetch_error_body_ = fetch_error_body;
// A transient download will not be shown in the UI, and will not prompt
// to user for target file path determination. Transient download should be
// cleared properly through DownloadManager to avoid the database and
// in-memory DownloadItem objects accumulated for the user.
void set_transient(bool transient) { transient_ = transient; }
// Sets the optional guid for the download, the guid serves as the unique
// identitfier for the download item. If no guid is provided, download
// system will automatically generate one.
void set_guid(const std::string& guid) { guid_ = guid; }
// For downloads originating from custom tabs, this records the origin
// of the custom tab.
void set_request_origin(const std::string& origin) {
request_origin_ = origin;
// Sets the download source, which will be used in metrics recording.
void set_download_source(DownloadSource download_source) {
download_source_ = download_source;
// Sets the callback to run if there are upload progress updates.
void set_upload_progress_callback(
const UploadProgressCallback& upload_callback) {
upload_callback_ = upload_callback;
// Sets whether the download will require safety checks for its URL chain and
// downloaded content.
void set_require_safety_checks(bool require_safety_checks) {
require_safety_checks_ = require_safety_checks;
const OnStartedCallback& callback() const { return callback_; }
bool content_initiated() const { return content_initiated_; }
const std::string& last_modified() const { return last_modified_; }
const std::string& etag() const { return etag_; }
bool use_if_range() const { return use_if_range_; }
const std::string& method() const { return method_; }
scoped_refptr<network::ResourceRequestBody> post_body() { return post_body_; }
int64_t post_id() const { return post_id_; }
bool prefer_cache() const { return prefer_cache_; }
const GURL& referrer() const { return referrer_; }
net::URLRequest::ReferrerPolicy referrer_policy() const {
return referrer_policy_;
const std::string& referrer_encoding() const { return referrer_encoding_; }
const base::Optional<url::Origin>& initiator() const { return initiator_; }
const std::string& request_origin() const { return request_origin_; }
BlobStorageContextGetter get_blob_storage_context_getter() {
return std::move(blob_storage_context_getter_);
// These will be -1 if the request is not associated with a frame. See
// the constructors for more.
int render_process_host_id() const { return render_process_host_id_; }
int render_view_host_routing_id() const {
return render_view_host_routing_id_;
int render_frame_host_routing_id() const {
return render_frame_host_routing_id_;
void set_frame_tree_node_id(int id) { frame_tree_node_id_ = id; }
int frame_tree_node_id() const { return frame_tree_node_id_; }
const RequestHeadersType& request_headers() const { return request_headers_; }
const base::FilePath& file_path() const { return save_info_.file_path; }
const base::string16& suggested_name() const {
return save_info_.suggested_name;
int64_t offset() const { return save_info_.offset; }
int64_t length() const { return save_info_.length; }
const std::string& hash_of_partial_file() const {
return save_info_.hash_of_partial_file;
bool prompt() const { return save_info_.prompt_for_save_location; }
const GURL& url() const { return url_; }
bool do_not_prompt_for_login() const { return do_not_prompt_for_login_; }
bool follow_cross_origin_redirects() const {
return follow_cross_origin_redirects_;
bool fetch_error_body() const { return fetch_error_body_; }
bool is_transient() const { return transient_; }
std::string guid() const { return guid_; }
bool require_safety_checks() const { return require_safety_checks_; }
// STATE CHANGING: All save_info_ sub-objects will be in an indeterminate
// state following this call.
DownloadSaveInfo GetSaveInfo() { return std::move(save_info_); }
const net::NetworkTrafficAnnotationTag& GetNetworkTrafficAnnotation() {
return traffic_annotation_;
DownloadSource download_source() const { return download_source_; }
const UploadProgressCallback& upload_callback() const {
return upload_callback_;
OnStartedCallback callback_;
bool content_initiated_;
RequestHeadersType request_headers_;
std::string last_modified_;
std::string etag_;
bool use_if_range_;
std::string method_;
scoped_refptr<network::ResourceRequestBody> post_body_;
BlobStorageContextGetter blob_storage_context_getter_;
int64_t post_id_;
bool prefer_cache_;
GURL referrer_;
net::URLRequest::ReferrerPolicy referrer_policy_;
base::Optional<url::Origin> initiator_;
std::string referrer_encoding_;
int render_process_host_id_;
int render_view_host_routing_id_;
int render_frame_host_routing_id_;
int frame_tree_node_id_;
DownloadSaveInfo save_info_;
GURL url_;
bool do_not_prompt_for_login_;
bool follow_cross_origin_redirects_;
bool fetch_error_body_;
bool transient_;
std::string guid_;
const net::NetworkTrafficAnnotationTag traffic_annotation_;
std::string request_origin_;
DownloadSource download_source_;
UploadProgressCallback upload_callback_;
bool require_safety_checks_;
} // namespace download