blob: 5dfc71164092726eb1d52d2e5f4851681b2a04a6 [file] [log] [blame]
// Copyright (c) 2006-2008 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 NET_URL_REQUEST_URL_REQUEST_H_
#define NET_URL_REQUEST_URL_REQUEST_H_
#include <string>
#include <vector>
#include "base/basictypes.h"
#include "base/logging.h"
#include "base/ref_counted.h"
#include "base/time.h"
#include "googleurl/src/gurl.h"
#include "net/base/load_states.h"
#include "net/base/ssl_info.h"
#include "net/base/upload_data.h"
#include "net/base/x509_certificate.h"
#include "net/http/http_response_info.h"
#include "net/url_request/url_request_context.h"
#include "net/url_request/url_request_status.h"
class URLRequestJob;
// This stores the values of the Set-Cookie headers received during the request.
// Each item in the vector corresponds to a Set-Cookie: line received,
// excluding the "Set-Cookie:" part.
typedef std::vector<std::string> ResponseCookies;
//-----------------------------------------------------------------------------
// A class representing the asynchronous load of a data stream from an URL.
//
// The lifetime of an instance of this class is completely controlled by the
// consumer, and the instance is not required to live on the heap or be
// allocated in any special way. It is also valid to delete an URLRequest
// object during the handling of a callback to its delegate. Of course, once
// the URLRequest is deleted, no further callbacks to its delegate will occur.
//
// NOTE: All usage of all instances of this class should be on the same thread.
//
class URLRequest {
public:
// Derive from this class and add your own data members to associate extra
// information with a URLRequest. Use user_data() and set_user_data()
class UserData {
public:
UserData() {}
virtual ~UserData() {}
};
// Callback function implemented by protocol handlers to create new jobs.
// The factory may return NULL to indicate an error, which will cause other
// factories to be queried. If no factory handles the request, then the
// default job will be used.
typedef URLRequestJob* (ProtocolFactory)(URLRequest* request,
const std::string& scheme);
// This class handles network interception. Use with
// (Un)RegisterRequestInterceptor.
class Interceptor {
public:
virtual ~Interceptor() {}
// Called for every request made. Should return a new job to handle the
// request if it should be intercepted, or NULL to allow the request to
// be handled in the normal manner.
virtual URLRequestJob* MaybeIntercept(URLRequest* request) = 0;
};
// The delegate's methods are called from the message loop of the thread
// on which the request's Start() method is called. See above for the
// ordering of callbacks.
//
// The callbacks will be called in the following order:
// Start()
// - OnReceivedRedirect* (zero or more calls, for the number of redirects)
// - OnAuthRequired* (zero or more calls, for the number of
// authentication failures)
// - OnResponseStarted
// Read() initiated by delegate
// - OnReadCompleted* (zero or more calls until all data is read)
//
// Read() must be called at least once. Read() returns true when it completed
// immediately, and false if an IO is pending or if there is an error. When
// Read() returns false, the caller can check the Request's status() to see
// if an error occurred, or if the IO is just pending. When Read() returns
// true with zero bytes read, it indicates the end of the response.
//
class Delegate {
public:
virtual ~Delegate() {}
// Called upon a server-initiated redirect. The delegate may call the
// request's Cancel method to prevent the redirect from being followed.
// Since there may be multiple chained redirects, there may also be more
// than one redirect call.
//
// When this function is called, the request will still contain the
// original URL, the destination of the redirect is provided in 'new_url'.
// If the request is not canceled the redirect will be followed and the
// request's URL will be changed to the new URL.
virtual void OnReceivedRedirect(URLRequest* request,
const GURL& new_url) = 0;
// Called when we receive an authentication failure. The delegate should
// call request->SetAuth() with the user's credentials once it obtains them,
// or request->CancelAuth() to cancel the login and display the error page.
// When it does so, the request will be reissued, restarting the sequence
// of On* callbacks.
virtual void OnAuthRequired(URLRequest* request,
net::AuthChallengeInfo* auth_info) {
request->CancelAuth();
}
// Called when using SSL and the server responds with a certificate with
// an error, for example, whose common name does not match the common name
// we were expecting for that host. The delegate should either do the
// safe thing and Cancel() the request or decide to proceed by calling
// ContinueDespiteLastError(). cert_error is a net::ERR_* error code
// indicating what's wrong with the certificate.
virtual void OnSSLCertificateError(URLRequest* request,
int cert_error,
net::X509Certificate* cert) {
request->Cancel();
}
// After calling Start(), the delegate will receive an OnResponseStarted
// callback when the request has completed. If an error occurred, the
// request->status() will be set. On success, all redirects have been
// followed and the final response is beginning to arrive. At this point,
// meta data about the response is available, including for example HTTP
// response headers if this is a request for a HTTP resource.
virtual void OnResponseStarted(URLRequest* request) = 0;
// Called when the a Read of the response body is completed after an
// IO_PENDING status from a Read() call.
// The data read is filled into the buffer which the caller passed
// to Read() previously.
//
// If an error occurred, request->status() will contain the error,
// and bytes read will be -1.
virtual void OnReadCompleted(URLRequest* request, int bytes_read) = 0;
};
// Initialize an URL request.
URLRequest(const GURL& url, Delegate* delegate);
// If destroyed after Start() has been called but while IO is pending,
// then the request will be effectively canceled and the delegate
// will not have any more of its methods called.
~URLRequest();
// The user data allows the owner to associate data with this request.
// This request will TAKE OWNERSHIP of the given pointer, and will delete
// the object if it is changed or the request is destroyed.
UserData* user_data() const {
return user_data_;
}
void set_user_data(UserData* user_data) {
if (user_data_)
delete user_data_;
user_data_ = user_data;
}
// Registers a new protocol handler for the given scheme. If the scheme is
// already handled, this will overwrite the given factory. To delete the
// protocol factory, use NULL for the factory BUT this WILL NOT put back
// any previously registered protocol factory. It will have returned
// the previously registered factory (or NULL if none is registered) when
// the scheme was first registered so that the caller can manually put it
// back if desired.
//
// The scheme must be all-lowercase ASCII. See the ProtocolFactory
// declaration for its requirements.
//
// The registered protocol factory may return NULL, which will cause the
// regular "built-in" protocol factory to be used.
//
static ProtocolFactory* RegisterProtocolFactory(const std::string& scheme,
ProtocolFactory* factory);
// Registers or unregisters a network interception class.
static void RegisterRequestInterceptor(Interceptor* interceptor);
static void UnregisterRequestInterceptor(Interceptor* interceptor);
// Returns true if the scheme can be handled by URLRequest. False otherwise.
static bool IsHandledProtocol(const std::string& scheme);
// Returns true if the url can be handled by URLRequest. False otherwise.
// The function returns true for invalid urls because URLRequest knows how
// to handle those.
static bool IsHandledURL(const GURL& url);
// The original url is the url used to initialize the request, and it may
// differ from the url if the request was redirected.
const GURL& original_url() const { return original_url_; }
const GURL& url() const { return url_; }
// The URL that should be consulted for the third-party cookie blocking
// policy.
const GURL& policy_url() const { return policy_url_; }
void set_policy_url(const GURL& policy_url) {
DCHECK(!is_pending_);
policy_url_ = policy_url;
}
// The request method, as an uppercase string. "GET" is the default value.
// The request method may only be changed before Start() is called and
// should only be assigned an uppercase value.
const std::string& method() const { return method_; }
void set_method(const std::string& method) {
DCHECK(!is_pending_);
method_ = method;
}
// The referrer URL for the request. This header may actually be suppressed
// from the underlying network request for security reasons (e.g., a HTTPS
// URL will not be sent as the referrer for a HTTP request). The referrer
// may only be changed before Start() is called.
const std::string& referrer() const { return referrer_; }
void set_referrer(const std::string& referrer) {
DCHECK(!is_pending_);
referrer_ = referrer;
}
// The delegate of the request. This value may be changed at any time,
// and it is permissible for it to be null.
Delegate* delegate() const { return delegate_; }
void set_delegate(Delegate* delegate) { delegate_ = delegate; }
// The data comprising the request message body is specified as a sequence of
// data segments and/or files containing data to upload. These methods may
// be called to construct the data sequence to upload, and they may only be
// called before Start() is called. For POST requests, the user must call
// SetRequestHeaderBy{Id,Name} to set the Content-Type of the request to the
// appropriate value before calling Start().
//
// When uploading data, bytes_len must be non-zero.
// When uploading a file range, length must be non-zero. If length
// exceeds the end-of-file, the upload is clipped at end-of-file.
void AppendBytesToUpload(const char* bytes, int bytes_len);
void AppendFileRangeToUpload(const std::wstring& file_path,
uint64 offset, uint64 length);
void AppendFileToUpload(const std::wstring& file_path) {
AppendFileRangeToUpload(file_path, 0, kuint64max);
}
// Set the upload data directly.
void set_upload(net::UploadData* upload) { upload_ = upload; }
// Returns true if the request has a non-empty message body to upload.
bool has_upload() const { return upload_ != NULL; }
// Set an extra request header by ID or name. These methods may only be
// called before Start() is called. It is an error to call it later.
void SetExtraRequestHeaderById(int header_id, const std::string& value,
bool overwrite);
void SetExtraRequestHeaderByName(const std::string& name,
const std::string& value, bool overwrite);
// Sets all extra request headers, from a \r\n-delimited string. Any extra
// request headers set by other methods are overwritten by this method. This
// method may only be called before Start() is called. It is an error to
// call it later.
void SetExtraRequestHeaders(const std::string& headers);
// Returns the current load state for the request.
net::LoadState GetLoadState() const;
// Returns the current upload progress in bytes.
uint64 GetUploadProgress() const;
// Get response header(s) by ID or name. These methods may only be called
// once the delegate's OnResponseStarted method has been called. Headers
// that appear more than once in the response are coalesced, with values
// separated by commas (per RFC 2616). This will not work with cookies since
// comma can be used in cookie values.
// TODO(darin): add API to enumerate response headers.
void GetResponseHeaderById(int header_id, std::string* value);
void GetResponseHeaderByName(const std::string& name, std::string* value);
// Get all response headers, \n-delimited and \n\0-terminated. This includes
// the response status line. Restrictions on GetResponseHeaders apply.
void GetAllResponseHeaders(std::string* headers);
// The time at which the returned response was requested. For cached
// responses, this may be a time well in the past.
const base::Time& request_time() const {
return response_info_.request_time;
}
// The time at which the returned response was generated. For cached
// responses, this may be a time well in the past.
const base::Time& response_time() const {
return response_info_.response_time;
}
// Indicate if this response was fetched from disk cache.
bool was_cached() const { return response_info_.was_cached; }
// Get all response headers, as a HttpResponseHeaders object. See comments
// in HttpResponseHeaders class as to the format of the data.
net::HttpResponseHeaders* response_headers() const {
return response_info_.headers.get();
}
// Get the SSL connection info.
const net::SSLInfo& ssl_info() const {
return response_info_.ssl_info;
}
// Returns the cookie values included in the response, if the request is one
// that can have cookies. Returns true if the request is a cookie-bearing
// type, false otherwise. This method may only be called once the
// delegate's OnResponseStarted method has been called.
bool GetResponseCookies(ResponseCookies* cookies);
// Get the mime type. This method may only be called once the delegate's
// OnResponseStarted method has been called.
void GetMimeType(std::string* mime_type);
// Get the charset (character encoding). This method may only be called once
// the delegate's OnResponseStarted method has been called.
void GetCharset(std::string* charset);
// Returns the HTTP response code (e.g., 200, 404, and so on). This method
// may only be called once the delegate's OnResponseStarted method has been
// called. For non-HTTP requests, this method returns -1.
int GetResponseCode();
// Access the net::LOAD_* flags modifying this request (see load_flags.h).
int load_flags() const { return load_flags_; }
void set_load_flags(int flags) { load_flags_ = flags; }
// Accessors to the pid of the process this request originated from.
int origin_pid() const { return origin_pid_; }
void set_origin_pid(int proc_id) {
origin_pid_ = proc_id;
}
// Returns true if the request is "pending" (i.e., if Start() has been called,
// and the response has not yet been called).
bool is_pending() const { return is_pending_; }
// Returns the error status of the request. This value is 0 if there is no
// error. Otherwise, it is a value defined by the operating system (e.g., an
// error code returned by GetLastError() on windows).
const URLRequestStatus& status() const { return status_; }
// This method is called to start the request. The delegate will receive
// a OnResponseStarted callback when the request is started.
void Start();
// This method may be called at any time after Start() has been called to
// cancel the request. This method may be called many times, and it has
// no effect once the response has completed.
void Cancel();
// Similar to Cancel but sets the error to |os_error| (see net_error_list.h
// for values) instead of net::ERR_ABORTED.
// Used to attach a reason for canceling a request.
void CancelWithError(int os_error);
// Read initiates an asynchronous read from the response, and must only
// be called after the OnResponseStarted callback is received with a
// successful status.
// If data is available, Read will return true, and the data and length will
// be returned immediately. If data is not available, Read returns false,
// and an asynchronous Read is initiated. The caller guarantees the
// buffer provided will be available until the Read is finished. The
// Read is finished when the caller receives the OnReadComplete
// callback. OnReadComplete will be always be called, even if there
// was a failure.
//
// The buf parameter is a buffer to receive the data. Once the read is
// initiated, the caller guarantees availability of this buffer until
// the OnReadComplete is received. The buffer must be at least
// max_bytes in length.
//
// The max_bytes parameter is the maximum number of bytes to read.
//
// The bytes_read parameter is an output parameter containing the
// the number of bytes read. A value of 0 indicates that there is no
// more data available to read from the stream.
//
// If a read error occurs, Read returns false and the request->status
// will be set to an error.
bool Read(char* buf, int max_bytes, int *bytes_read);
// One of the following two methods should be called in response to an
// OnAuthRequired() callback (and only then).
// SetAuth will reissue the request with the given credentials.
// CancelAuth will give up and display the error page.
void SetAuth(const std::wstring& username, const std::wstring& password);
void CancelAuth();
// This method can be called after some error notifications to instruct this
// URLRequest to ignore the current error and continue with the request. To
// cancel the request instead, call Cancel().
void ContinueDespiteLastError();
// HTTP request/response header IDs (via some preprocessor fun) for use with
// SetRequestHeaderById and GetResponseHeaderById.
enum {
#define HTTP_ATOM(x) HTTP_ ## x,
#include "net/http/http_atom_list.h"
#undef HTTP_ATOM
};
// Returns true if performance profiling should be enabled on the
// URLRequestJob serving this request.
bool enable_profiling() const { return enable_profiling_; }
void set_enable_profiling(bool profiling) { enable_profiling_ = profiling; }
// Used to specify the context (cookie store, cache) for this request.
URLRequestContext* context() { return context_.get(); }
void set_context(URLRequestContext* context) { context_ = context; }
// Returns the expected content size if available
int64 GetExpectedContentSize() const;
protected:
// Allow the URLRequestJob class to control the is_pending() flag.
void set_is_pending(bool value) { is_pending_ = value; }
// Allow the URLRequestJob class to set our status too
void set_status(const URLRequestStatus &value) { status_ = value; }
// Allow the URLRequestJob to redirect this request. Returns net::OK if
// successful, otherwise an error code is returned.
int Redirect(const GURL& location, int http_status_code);
private:
friend class URLRequestJob;
// Detaches the job from this request in preparation for this object going
// away or the job being replaced. The job will not call us back when it has
// been orphaned.
void OrphanJob();
// Discard headers which have meaning in POST (Content-Length, Content-Type,
// Origin).
static std::string StripPostSpecificHeaders(const std::string& headers);
scoped_refptr<URLRequestJob> job_;
scoped_refptr<net::UploadData> upload_;
GURL url_;
GURL original_url_;
GURL policy_url_;
std::string method_; // "GET", "POST", etc. Should be all uppercase.
std::string referrer_;
std::string extra_request_headers_;
int load_flags_; // Flags indicating the request type for the load;
// expected values are LOAD_* enums above.
// The pid of the process that initiated this request. Initialized to the id
// of the current process.
int origin_pid_;
Delegate* delegate_;
// Current error status of the job. When no error has been encountered, this
// will be SUCCESS. If multiple errors have been encountered, this will be
// the first non-SUCCESS status seen.
URLRequestStatus status_;
// The HTTP response info, lazily initialized.
net::HttpResponseInfo response_info_;
// Tells us whether the job is outstanding. This is true from the time
// Start() is called to the time we dispatch RequestComplete and indicates
// whether the job is active.
bool is_pending_;
// Externally-defined data associated with this request
UserData* user_data_;
// Whether to enable performance profiling on the job serving this request.
bool enable_profiling_;
// Number of times we're willing to redirect. Used to guard against
// infinite redirects.
int redirect_limit_;
// Contextual information used for this request (can be NULL).
scoped_refptr<URLRequestContext> context_;
// Cached value for use after we've orphaned the job handling the
// first transaction in a request involving redirects.
uint64 final_upload_progress_;
DISALLOW_EVIL_CONSTRUCTORS(URLRequest);
};
//-----------------------------------------------------------------------------
// To help ensure that all requests are cleaned up properly, we keep static
// counters of live objects. TODO(darin): Move this leak checking stuff into
// a common place and generalize it so it can be used everywhere (Bug 566229).
#ifndef NDEBUG
struct URLRequestMetrics {
int object_count;
URLRequestMetrics() : object_count(0) {}
~URLRequestMetrics() {
DLOG_IF(WARNING, object_count != 0) <<
"Leaking " << object_count << " URLRequest object(s)";
}
};
extern URLRequestMetrics url_request_metrics;
#define URLREQUEST_COUNT_CTOR() url_request_metrics.object_count++
#define URLREQUEST_COUNT_DTOR() url_request_metrics.object_count--
#else // disable leak checking in release builds...
#define URLREQUEST_COUNT_CTOR()
#define URLREQUEST_COUNT_DTOR()
#endif
#endif // NET_URL_REQUEST_URL_REQUEST_H_