url_request.h revision 1e9bf3e0803691d0a228da41fc608347b6db4340
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#ifndef NET_URL_REQUEST_URL_REQUEST_H_ 6#define NET_URL_REQUEST_URL_REQUEST_H_ 7 8#include <string> 9#include <vector> 10 11#include "base/debug/leak_tracker.h" 12#include "base/logging.h" 13#include "base/memory/ref_counted.h" 14#include "base/strings/string16.h" 15#include "base/supports_user_data.h" 16#include "base/threading/non_thread_safe.h" 17#include "base/time/time.h" 18#include "net/base/auth.h" 19#include "net/base/completion_callback.h" 20#include "net/base/load_states.h" 21#include "net/base/load_timing_info.h" 22#include "net/base/net_export.h" 23#include "net/base/net_log.h" 24#include "net/base/network_delegate.h" 25#include "net/base/request_priority.h" 26#include "net/base/upload_progress.h" 27#include "net/cookies/canonical_cookie.h" 28#include "net/http/http_request_headers.h" 29#include "net/http/http_response_info.h" 30#include "net/url_request/url_request_status.h" 31#include "url/gurl.h" 32 33// Temporary layering violation to allow existing users of a deprecated 34// interface. 35class ChildProcessSecurityPolicyTest; 36class TestAutomationProvider; 37class URLRequestAutomationJob; 38 39namespace base { 40class Value; 41 42namespace debug { 43class StackTrace; 44} // namespace debug 45} // namespace base 46 47// Temporary layering violation to allow existing users of a deprecated 48// interface. 49namespace appcache { 50class AppCacheInterceptor; 51class AppCacheRequestHandlerTest; 52class AppCacheURLRequestJobTest; 53} 54 55// Temporary layering violation to allow existing users of a deprecated 56// interface. 57namespace content { 58class ResourceDispatcherHostTest; 59} 60 61// Temporary layering violation to allow existing users of a deprecated 62// interface. 63namespace fileapi { 64class FileSystemDirURLRequestJobTest; 65class FileSystemURLRequestJobTest; 66class FileWriterDelegateTest; 67} 68 69// Temporary layering violation to allow existing users of a deprecated 70// interface. 71namespace webkit_blob { 72class BlobURLRequestJobTest; 73} 74 75namespace net { 76 77class CookieOptions; 78class HostPortPair; 79class IOBuffer; 80struct LoadTimingInfo; 81class SSLCertRequestInfo; 82class SSLInfo; 83class UploadDataStream; 84class URLRequestContext; 85class URLRequestJob; 86class X509Certificate; 87 88// This stores the values of the Set-Cookie headers received during the request. 89// Each item in the vector corresponds to a Set-Cookie: line received, 90// excluding the "Set-Cookie:" part. 91typedef std::vector<std::string> ResponseCookies; 92 93//----------------------------------------------------------------------------- 94// A class representing the asynchronous load of a data stream from an URL. 95// 96// The lifetime of an instance of this class is completely controlled by the 97// consumer, and the instance is not required to live on the heap or be 98// allocated in any special way. It is also valid to delete an URLRequest 99// object during the handling of a callback to its delegate. Of course, once 100// the URLRequest is deleted, no further callbacks to its delegate will occur. 101// 102// NOTE: All usage of all instances of this class should be on the same thread. 103// 104class NET_EXPORT URLRequest : NON_EXPORTED_BASE(public base::NonThreadSafe), 105 public base::SupportsUserData { 106 public: 107 // Callback function implemented by protocol handlers to create new jobs. 108 // The factory may return NULL to indicate an error, which will cause other 109 // factories to be queried. If no factory handles the request, then the 110 // default job will be used. 111 typedef URLRequestJob* (ProtocolFactory)(URLRequest* request, 112 NetworkDelegate* network_delegate, 113 const std::string& scheme); 114 115 // HTTP request/response header IDs (via some preprocessor fun) for use with 116 // SetRequestHeaderById and GetResponseHeaderById. 117 enum { 118#define HTTP_ATOM(x) HTTP_ ## x, 119#include "net/http/http_atom_list.h" 120#undef HTTP_ATOM 121 }; 122 123 // Referrer policies (see set_referrer_policy): During server redirects, the 124 // referrer header might be cleared, if the protocol changes from HTTPS to 125 // HTTP. This is the default behavior of URLRequest, corresponding to 126 // CLEAR_REFERRER_ON_TRANSITION_FROM_SECURE_TO_INSECURE. Alternatively, the 127 // referrer policy can be set to never change the referrer header. This 128 // behavior corresponds to NEVER_CLEAR_REFERRER. Embedders will want to use 129 // NEVER_CLEAR_REFERRER when implementing the meta-referrer support 130 // (http://wiki.whatwg.org/wiki/Meta_referrer) and sending requests with a 131 // non-default referrer policy. Only the default referrer policy requires 132 // the referrer to be cleared on transitions from HTTPS to HTTP. 133 enum ReferrerPolicy { 134 CLEAR_REFERRER_ON_TRANSITION_FROM_SECURE_TO_INSECURE, 135 NEVER_CLEAR_REFERRER, 136 }; 137 138 // Used with SetDelegateInfo to indicate how the string should be used. 139 // DELEGATE_INFO_DEBUG_ONLY indicates it should only be used when logged to 140 // NetLog, while DELEGATE_INFO_DISPLAY_TO_USER indicates it should also be 141 // returned by calls to GetLoadState for display to the user. 142 enum DelegateInfoUsage { 143 DELEGATE_INFO_DEBUG_ONLY, 144 DELEGATE_INFO_DISPLAY_TO_USER, 145 }; 146 147 // This class handles network interception. Use with 148 // (Un)RegisterRequestInterceptor. 149 class NET_EXPORT Interceptor { 150 public: 151 virtual ~Interceptor() {} 152 153 // Called for every request made. Should return a new job to handle the 154 // request if it should be intercepted, or NULL to allow the request to 155 // be handled in the normal manner. 156 virtual URLRequestJob* MaybeIntercept( 157 URLRequest* request, NetworkDelegate* network_delegate) = 0; 158 159 // Called after having received a redirect response, but prior to the 160 // the request delegate being informed of the redirect. Can return a new 161 // job to replace the existing job if it should be intercepted, or NULL 162 // to allow the normal handling to continue. If a new job is provided, 163 // the delegate never sees the original redirect response, instead the 164 // response produced by the intercept job will be returned. 165 virtual URLRequestJob* MaybeInterceptRedirect( 166 URLRequest* request, 167 NetworkDelegate* network_delegate, 168 const GURL& location); 169 170 // Called after having received a final response, but prior to the 171 // the request delegate being informed of the response. This is also 172 // called when there is no server response at all to allow interception 173 // on dns or network errors. Can return a new job to replace the existing 174 // job if it should be intercepted, or NULL to allow the normal handling to 175 // continue. If a new job is provided, the delegate never sees the original 176 // response, instead the response produced by the intercept job will be 177 // returned. 178 virtual URLRequestJob* MaybeInterceptResponse( 179 URLRequest* request, NetworkDelegate* network_delegate); 180 }; 181 182 // Deprecated interfaces in net::URLRequest. They have been moved to 183 // URLRequest's private section to prevent new uses. Existing uses are 184 // explicitly friended here and should be removed over time. 185 class NET_EXPORT Deprecated { 186 private: 187 // TODO(willchan): Kill off these friend declarations. 188 friend class ::ChildProcessSecurityPolicyTest; 189 friend class ::TestAutomationProvider; 190 friend class ::URLRequestAutomationJob; 191 friend class TestInterceptor; 192 friend class URLRequestFilter; 193 friend class appcache::AppCacheInterceptor; 194 friend class appcache::AppCacheRequestHandlerTest; 195 friend class appcache::AppCacheURLRequestJobTest; 196 friend class content::ResourceDispatcherHostTest; 197 friend class fileapi::FileSystemDirURLRequestJobTest; 198 friend class fileapi::FileSystemURLRequestJobTest; 199 friend class fileapi::FileWriterDelegateTest; 200 friend class webkit_blob::BlobURLRequestJobTest; 201 202 // Use URLRequestJobFactory::ProtocolHandler instead. 203 static ProtocolFactory* RegisterProtocolFactory(const std::string& scheme, 204 ProtocolFactory* factory); 205 206 // TODO(pauljensen): Remove this when AppCacheInterceptor is a 207 // ProtocolHandler, see crbug.com/161547. 208 static void RegisterRequestInterceptor(Interceptor* interceptor); 209 static void UnregisterRequestInterceptor(Interceptor* interceptor); 210 211 DISALLOW_IMPLICIT_CONSTRUCTORS(Deprecated); 212 }; 213 214 // The delegate's methods are called from the message loop of the thread 215 // on which the request's Start() method is called. See above for the 216 // ordering of callbacks. 217 // 218 // The callbacks will be called in the following order: 219 // Start() 220 // - OnCertificateRequested* (zero or more calls, if the SSL server and/or 221 // SSL proxy requests a client certificate for authentication) 222 // - OnSSLCertificateError* (zero or one call, if the SSL server's 223 // certificate has an error) 224 // - OnReceivedRedirect* (zero or more calls, for the number of redirects) 225 // - OnAuthRequired* (zero or more calls, for the number of 226 // authentication failures) 227 // - OnResponseStarted 228 // Read() initiated by delegate 229 // - OnReadCompleted* (zero or more calls until all data is read) 230 // 231 // Read() must be called at least once. Read() returns true when it completed 232 // immediately, and false if an IO is pending or if there is an error. When 233 // Read() returns false, the caller can check the Request's status() to see 234 // if an error occurred, or if the IO is just pending. When Read() returns 235 // true with zero bytes read, it indicates the end of the response. 236 // 237 class NET_EXPORT Delegate { 238 public: 239 // Called upon a server-initiated redirect. The delegate may call the 240 // request's Cancel method to prevent the redirect from being followed. 241 // Since there may be multiple chained redirects, there may also be more 242 // than one redirect call. 243 // 244 // When this function is called, the request will still contain the 245 // original URL, the destination of the redirect is provided in 'new_url'. 246 // If the delegate does not cancel the request and |*defer_redirect| is 247 // false, then the redirect will be followed, and the request's URL will be 248 // changed to the new URL. Otherwise if the delegate does not cancel the 249 // request and |*defer_redirect| is true, then the redirect will be 250 // followed once FollowDeferredRedirect is called on the URLRequest. 251 // 252 // The caller must set |*defer_redirect| to false, so that delegates do not 253 // need to set it if they are happy with the default behavior of not 254 // deferring redirect. 255 virtual void OnReceivedRedirect(URLRequest* request, 256 const GURL& new_url, 257 bool* defer_redirect); 258 259 // Called when we receive an authentication failure. The delegate should 260 // call request->SetAuth() with the user's credentials once it obtains them, 261 // or request->CancelAuth() to cancel the login and display the error page. 262 // When it does so, the request will be reissued, restarting the sequence 263 // of On* callbacks. 264 virtual void OnAuthRequired(URLRequest* request, 265 AuthChallengeInfo* auth_info); 266 267 // Called when we receive an SSL CertificateRequest message for client 268 // authentication. The delegate should call 269 // request->ContinueWithCertificate() with the client certificate the user 270 // selected, or request->ContinueWithCertificate(NULL) to continue the SSL 271 // handshake without a client certificate. 272 virtual void OnCertificateRequested( 273 URLRequest* request, 274 SSLCertRequestInfo* cert_request_info); 275 276 // Called when using SSL and the server responds with a certificate with 277 // an error, for example, whose common name does not match the common name 278 // we were expecting for that host. The delegate should either do the 279 // safe thing and Cancel() the request or decide to proceed by calling 280 // ContinueDespiteLastError(). cert_error is a ERR_* error code 281 // indicating what's wrong with the certificate. 282 // If |fatal| is true then the host in question demands a higher level 283 // of security (due e.g. to HTTP Strict Transport Security, user 284 // preference, or built-in policy). In this case, errors must not be 285 // bypassable by the user. 286 virtual void OnSSLCertificateError(URLRequest* request, 287 const SSLInfo& ssl_info, 288 bool fatal); 289 290 // After calling Start(), the delegate will receive an OnResponseStarted 291 // callback when the request has completed. If an error occurred, the 292 // request->status() will be set. On success, all redirects have been 293 // followed and the final response is beginning to arrive. At this point, 294 // meta data about the response is available, including for example HTTP 295 // response headers if this is a request for a HTTP resource. 296 virtual void OnResponseStarted(URLRequest* request) = 0; 297 298 // Called when the a Read of the response body is completed after an 299 // IO_PENDING status from a Read() call. 300 // The data read is filled into the buffer which the caller passed 301 // to Read() previously. 302 // 303 // If an error occurred, request->status() will contain the error, 304 // and bytes read will be -1. 305 virtual void OnReadCompleted(URLRequest* request, int bytes_read) = 0; 306 307 protected: 308 virtual ~Delegate() {} 309 }; 310 311 // TODO(shalev): Get rid of this constructor in favour of the one below it. 312 // Initialize an URL request. 313 URLRequest(const GURL& url, 314 Delegate* delegate, 315 const URLRequestContext* context); 316 317 URLRequest(const GURL& url, 318 Delegate* delegate, 319 const URLRequestContext* context, 320 NetworkDelegate* network_delegate); 321 322 // If destroyed after Start() has been called but while IO is pending, 323 // then the request will be effectively canceled and the delegate 324 // will not have any more of its methods called. 325 virtual ~URLRequest(); 326 327 // Changes the default cookie policy from allowing all cookies to blocking all 328 // cookies. Embedders that want to implement a more flexible policy should 329 // change the default to blocking all cookies, and provide a NetworkDelegate 330 // with the URLRequestContext that maintains the CookieStore. 331 // The cookie policy default has to be set before the first URLRequest is 332 // started. Once it was set to block all cookies, it cannot be changed back. 333 static void SetDefaultCookiePolicyToBlock(); 334 335 // Returns true if the scheme can be handled by URLRequest. False otherwise. 336 static bool IsHandledProtocol(const std::string& scheme); 337 338 // Returns true if the url can be handled by URLRequest. False otherwise. 339 // The function returns true for invalid urls because URLRequest knows how 340 // to handle those. 341 // NOTE: This will also return true for URLs that are handled by 342 // ProtocolFactories that only work for requests that are scoped to a 343 // Profile. 344 static bool IsHandledURL(const GURL& url); 345 346 // The original url is the url used to initialize the request, and it may 347 // differ from the url if the request was redirected. 348 const GURL& original_url() const { return url_chain_.front(); } 349 // The chain of urls traversed by this request. If the request had no 350 // redirects, this vector will contain one element. 351 const std::vector<GURL>& url_chain() const { return url_chain_; } 352 const GURL& url() const { return url_chain_.back(); } 353 354 // The URL that should be consulted for the third-party cookie blocking 355 // policy. 356 // 357 // WARNING: This URL must only be used for the third-party cookie blocking 358 // policy. It MUST NEVER be used for any kind of SECURITY check. 359 // 360 // For example, if a top-level navigation is redirected, the 361 // first-party for cookies will be the URL of the first URL in the 362 // redirect chain throughout the whole redirect. If it was used for 363 // a security check, an attacker might try to get around this check 364 // by starting from some page that redirects to the 365 // host-to-be-attacked. 366 const GURL& first_party_for_cookies() const { 367 return first_party_for_cookies_; 368 } 369 // This method may be called before Start() or FollowDeferredRedirect() is 370 // called. 371 void set_first_party_for_cookies(const GURL& first_party_for_cookies); 372 373 // The request method, as an uppercase string. "GET" is the default value. 374 // The request method may only be changed before Start() is called and 375 // should only be assigned an uppercase value. 376 const std::string& method() const { return method_; } 377 void set_method(const std::string& method); 378 379 // Determines the new method of the request afer following a redirect. 380 // |method| is the method used to arrive at the redirect, 381 // |http_status_code| is the status code associated with the redirect. 382 static std::string ComputeMethodForRedirect(const std::string& method, 383 int http_status_code); 384 385 // The referrer URL for the request. This header may actually be suppressed 386 // from the underlying network request for security reasons (e.g., a HTTPS 387 // URL will not be sent as the referrer for a HTTP request). The referrer 388 // may only be changed before Start() is called. 389 const std::string& referrer() const { return referrer_; } 390 // Referrer is sanitized to remove URL fragment, user name and password. 391 void SetReferrer(const std::string& referrer); 392 393 // The referrer policy to apply when updating the referrer during redirects. 394 // The referrer policy may only be changed before Start() is called. 395 void set_referrer_policy(ReferrerPolicy referrer_policy); 396 397 // Sets the delegate of the request. This value may be changed at any time, 398 // and it is permissible for it to be null. 399 void set_delegate(Delegate* delegate); 400 401 // Indicates that the request body should be sent using chunked transfer 402 // encoding. This method may only be called before Start() is called. 403 void EnableChunkedUpload(); 404 405 // Appends the given bytes to the request's upload data to be sent 406 // immediately via chunked transfer encoding. When all data has been sent, 407 // call MarkEndOfChunks() to indicate the end of upload data. 408 // 409 // This method may be called only after calling EnableChunkedUpload(). 410 void AppendChunkToUpload(const char* bytes, 411 int bytes_len, 412 bool is_last_chunk); 413 414 // Sets the upload data. 415 void set_upload(scoped_ptr<UploadDataStream> upload); 416 417 // Gets the upload data. 418 const UploadDataStream* get_upload() const; 419 420 // Returns true if the request has a non-empty message body to upload. 421 bool has_upload() const; 422 423 // Set an extra request header by ID or name, or remove one by name. These 424 // methods may only be called before Start() is called, or before a new 425 // redirect in the request chain. 426 void SetExtraRequestHeaderById(int header_id, const std::string& value, 427 bool overwrite); 428 void SetExtraRequestHeaderByName(const std::string& name, 429 const std::string& value, bool overwrite); 430 void RemoveRequestHeaderByName(const std::string& name); 431 432 // Sets all extra request headers. Any extra request headers set by other 433 // methods are overwritten by this method. This method may only be called 434 // before Start() is called. It is an error to call it later. 435 void SetExtraRequestHeaders(const HttpRequestHeaders& headers); 436 437 const HttpRequestHeaders& extra_request_headers() const { 438 return extra_request_headers_; 439 } 440 441 // Gets the full request headers sent to the server. 442 // 443 // Return true and overwrites headers if it can get the request headers; 444 // otherwise, returns false and does not modify headers. (Always returns 445 // false for request types that don't have headers, like file requests.) 446 // 447 // This is guaranteed to succeed if: 448 // 449 // 1. A redirect or auth callback is currently running. Once it ends, the 450 // headers may become unavailable as a new request with the new address 451 // or credentials is made. 452 // 453 // 2. The OnResponseStarted callback is currently running or has run. 454 bool GetFullRequestHeaders(HttpRequestHeaders* headers) const; 455 456 // Returns the current load state for the request. |param| is an optional 457 // parameter describing details related to the load state. Not all load states 458 // have a parameter. 459 LoadStateWithParam GetLoadState() const; 460 461 // Returns a partial representation of the request's state as a value, for 462 // debugging. Caller takes ownership of returned value. 463 base::Value* GetStateAsValue() const; 464 465 // Logs information about the delegate currently blocking the request. 466 // The delegate info must be cleared by sending NULL before resuming a 467 // request. |delegate_info| will be copied as needed. |delegate_info_usage| 468 // is used to indicate whether the value should be returned in the param field 469 // of GetLoadState. |delegate_info_usage_| is ignored when |delegate_info| is 470 // NULL. 471 void SetDelegateInfo(const char* delegate_info, 472 DelegateInfoUsage delegate_info_usage); 473 474 // Returns the current upload progress in bytes. When the upload data is 475 // chunked, size is set to zero, but position will not be. 476 UploadProgress GetUploadProgress() const; 477 478 // Get response header(s) by ID or name. These methods may only be called 479 // once the delegate's OnResponseStarted method has been called. Headers 480 // that appear more than once in the response are coalesced, with values 481 // separated by commas (per RFC 2616). This will not work with cookies since 482 // comma can be used in cookie values. 483 // TODO(darin): add API to enumerate response headers. 484 void GetResponseHeaderById(int header_id, std::string* value); 485 void GetResponseHeaderByName(const std::string& name, std::string* value); 486 487 // Get all response headers, \n-delimited and \n\0-terminated. This includes 488 // the response status line. Restrictions on GetResponseHeaders apply. 489 void GetAllResponseHeaders(std::string* headers); 490 491 // The time when |this| was constructed. 492 base::TimeTicks creation_time() const { return creation_time_; } 493 494 // The time at which the returned response was requested. For cached 495 // responses, this is the last time the cache entry was validated. 496 const base::Time& request_time() const { 497 return response_info_.request_time; 498 } 499 500 // The time at which the returned response was generated. For cached 501 // responses, this is the last time the cache entry was validated. 502 const base::Time& response_time() const { 503 return response_info_.response_time; 504 } 505 506 // Indicate if this response was fetched from disk cache. 507 bool was_cached() const { return response_info_.was_cached; } 508 509 // Returns true if the URLRequest was delivered through a proxy. 510 bool was_fetched_via_proxy() const { 511 return response_info_.was_fetched_via_proxy; 512 } 513 514 // Returns the host and port that the content was fetched from. See 515 // http_response_info.h for caveats relating to cached content. 516 HostPortPair GetSocketAddress() const; 517 518 // Get all response headers, as a HttpResponseHeaders object. See comments 519 // in HttpResponseHeaders class as to the format of the data. 520 HttpResponseHeaders* response_headers() const; 521 522 // Get the SSL connection info. 523 const SSLInfo& ssl_info() const { 524 return response_info_.ssl_info; 525 } 526 527 // Gets timing information related to the request. Events that have not yet 528 // occurred are left uninitialized. After a second request starts, due to 529 // a redirect or authentication, values will be reset. 530 // 531 // LoadTimingInfo only contains ConnectTiming information and socket IDs for 532 // non-cached HTTP responses. 533 void GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const; 534 535 // Returns the cookie values included in the response, if the request is one 536 // that can have cookies. Returns true if the request is a cookie-bearing 537 // type, false otherwise. This method may only be called once the 538 // delegate's OnResponseStarted method has been called. 539 bool GetResponseCookies(ResponseCookies* cookies); 540 541 // Get the mime type. This method may only be called once the delegate's 542 // OnResponseStarted method has been called. 543 void GetMimeType(std::string* mime_type); 544 545 // Get the charset (character encoding). This method may only be called once 546 // the delegate's OnResponseStarted method has been called. 547 void GetCharset(std::string* charset); 548 549 // Returns the HTTP response code (e.g., 200, 404, and so on). This method 550 // may only be called once the delegate's OnResponseStarted method has been 551 // called. For non-HTTP requests, this method returns -1. 552 int GetResponseCode() const; 553 554 // Get the HTTP response info in its entirety. 555 const HttpResponseInfo& response_info() const { return response_info_; } 556 557 // Access the LOAD_* flags modifying this request (see load_flags.h). 558 int load_flags() const { return load_flags_; } 559 void set_load_flags(int flags) { load_flags_ = flags; } 560 561 // Returns true if the request is "pending" (i.e., if Start() has been called, 562 // and the response has not yet been called). 563 bool is_pending() const { return is_pending_; } 564 565 // Returns true if the request is in the process of redirecting to a new 566 // URL but has not yet initiated the new request. 567 bool is_redirecting() const { return is_redirecting_; } 568 569 // Returns the error status of the request. 570 const URLRequestStatus& status() const { return status_; } 571 572 // Returns a globally unique identifier for this request. 573 uint64 identifier() const { return identifier_; } 574 575 // This method is called to start the request. The delegate will receive 576 // a OnResponseStarted callback when the request is started. 577 void Start(); 578 579 // This method may be called at any time after Start() has been called to 580 // cancel the request. This method may be called many times, and it has 581 // no effect once the response has completed. It is guaranteed that no 582 // methods of the delegate will be called after the request has been 583 // cancelled, except that this may call the delegate's OnReadCompleted() 584 // during the call to Cancel itself. 585 void Cancel(); 586 587 // Cancels the request and sets the error to |error| (see net_error_list.h 588 // for values). 589 void CancelWithError(int error); 590 591 // Cancels the request and sets the error to |error| (see net_error_list.h 592 // for values) and attaches |ssl_info| as the SSLInfo for that request. This 593 // is useful to attach a certificate and certificate error to a canceled 594 // request. 595 void CancelWithSSLError(int error, const SSLInfo& ssl_info); 596 597 // Read initiates an asynchronous read from the response, and must only 598 // be called after the OnResponseStarted callback is received with a 599 // successful status. 600 // If data is available, Read will return true, and the data and length will 601 // be returned immediately. If data is not available, Read returns false, 602 // and an asynchronous Read is initiated. The Read is finished when 603 // the caller receives the OnReadComplete callback. Unless the request was 604 // cancelled, OnReadComplete will always be called, even if the read failed. 605 // 606 // The buf parameter is a buffer to receive the data. If the operation 607 // completes asynchronously, the implementation will reference the buffer 608 // until OnReadComplete is called. The buffer must be at least max_bytes in 609 // length. 610 // 611 // The max_bytes parameter is the maximum number of bytes to read. 612 // 613 // The bytes_read parameter is an output parameter containing the 614 // the number of bytes read. A value of 0 indicates that there is no 615 // more data available to read from the stream. 616 // 617 // If a read error occurs, Read returns false and the request->status 618 // will be set to an error. 619 bool Read(IOBuffer* buf, int max_bytes, int* bytes_read); 620 621 // If this request is being cached by the HTTP cache, stop subsequent caching. 622 // Note that this method has no effect on other (simultaneous or not) requests 623 // for the same resource. The typical example is a request that results in 624 // the data being stored to disk (downloaded instead of rendered) so we don't 625 // want to store it twice. 626 void StopCaching(); 627 628 // This method may be called to follow a redirect that was deferred in 629 // response to an OnReceivedRedirect call. 630 void FollowDeferredRedirect(); 631 632 // One of the following two methods should be called in response to an 633 // OnAuthRequired() callback (and only then). 634 // SetAuth will reissue the request with the given credentials. 635 // CancelAuth will give up and display the error page. 636 void SetAuth(const AuthCredentials& credentials); 637 void CancelAuth(); 638 639 // This method can be called after the user selects a client certificate to 640 // instruct this URLRequest to continue with the request with the 641 // certificate. Pass NULL if the user doesn't have a client certificate. 642 void ContinueWithCertificate(X509Certificate* client_cert); 643 644 // This method can be called after some error notifications to instruct this 645 // URLRequest to ignore the current error and continue with the request. To 646 // cancel the request instead, call Cancel(). 647 void ContinueDespiteLastError(); 648 649 // Used to specify the context (cookie store, cache) for this request. 650 const URLRequestContext* context() const; 651 652 const BoundNetLog& net_log() const { return net_log_; } 653 654 // Returns the expected content size if available 655 int64 GetExpectedContentSize() const; 656 657 // Returns the priority level for this request. 658 RequestPriority priority() const { return priority_; } 659 660 // Sets the priority level for this request and any related jobs. 661 void SetPriority(RequestPriority priority); 662 663 // Returns true iff this request would be internally redirected to HTTPS 664 // due to HSTS. If so, |redirect_url| is rewritten to the new HTTPS URL. 665 bool GetHSTSRedirect(GURL* redirect_url) const; 666 667 // TODO(willchan): Undo this. Only temporarily public. 668 bool has_delegate() const { return delegate_ != NULL; } 669 670 // NOTE(willchan): This is just temporary for debugging 671 // http://crbug.com/90971. 672 // Allows to setting debug info into the URLRequest. 673 void set_stack_trace(const base::debug::StackTrace& stack_trace); 674 const base::debug::StackTrace* stack_trace() const; 675 676 void set_received_response_content_length(int64 received_content_length) { 677 received_response_content_length_ = received_content_length; 678 } 679 int64 received_response_content_length() { 680 return received_response_content_length_; 681 } 682 683 protected: 684 // Allow the URLRequestJob class to control the is_pending() flag. 685 void set_is_pending(bool value) { is_pending_ = value; } 686 687 // Allow the URLRequestJob class to set our status too 688 void set_status(const URLRequestStatus& value) { status_ = value; } 689 690 // Allow the URLRequestJob to redirect this request. Returns OK if 691 // successful, otherwise an error code is returned. 692 int Redirect(const GURL& location, int http_status_code); 693 694 // Called by URLRequestJob to allow interception when a redirect occurs. 695 void NotifyReceivedRedirect(const GURL& location, bool* defer_redirect); 696 697 // Allow an interceptor's URLRequestJob to restart this request. 698 // Should only be called if the original job has not started a response. 699 void Restart(); 700 701 private: 702 friend class URLRequestJob; 703 704 // Registers a new protocol handler for the given scheme. If the scheme is 705 // already handled, this will overwrite the given factory. To delete the 706 // protocol factory, use NULL for the factory BUT this WILL NOT put back 707 // any previously registered protocol factory. It will have returned 708 // the previously registered factory (or NULL if none is registered) when 709 // the scheme was first registered so that the caller can manually put it 710 // back if desired. 711 // 712 // The scheme must be all-lowercase ASCII. See the ProtocolFactory 713 // declaration for its requirements. 714 // 715 // The registered protocol factory may return NULL, which will cause the 716 // regular "built-in" protocol factory to be used. 717 // 718 static ProtocolFactory* RegisterProtocolFactory(const std::string& scheme, 719 ProtocolFactory* factory); 720 721 // Registers or unregisters a network interception class. 722 static void RegisterRequestInterceptor(Interceptor* interceptor); 723 static void UnregisterRequestInterceptor(Interceptor* interceptor); 724 725 // Resumes or blocks a request paused by the NetworkDelegate::OnBeforeRequest 726 // handler. If |blocked| is true, the request is blocked and an error page is 727 // returned indicating so. This should only be called after Start is called 728 // and OnBeforeRequest returns true (signalling that the request should be 729 // paused). 730 void BeforeRequestComplete(int error); 731 732 void StartJob(URLRequestJob* job); 733 734 // Restarting involves replacing the current job with a new one such as what 735 // happens when following a HTTP redirect. 736 void RestartWithJob(URLRequestJob* job); 737 void PrepareToRestart(); 738 739 // Detaches the job from this request in preparation for this object going 740 // away or the job being replaced. The job will not call us back when it has 741 // been orphaned. 742 void OrphanJob(); 743 744 // Cancels the request and set the error and ssl info for this request to the 745 // passed values. 746 void DoCancel(int error, const SSLInfo& ssl_info); 747 748 // Called by the URLRequestJob when the headers are received, before any other 749 // method, to allow caching of load timing information. 750 void OnHeadersComplete(); 751 752 // Notifies the network delegate that the request has been completed. 753 // This does not imply a successful completion. Also a canceled request is 754 // considered completed. 755 void NotifyRequestCompleted(); 756 757 // Called by URLRequestJob to allow interception when the final response 758 // occurs. 759 void NotifyResponseStarted(); 760 761 // These functions delegate to |delegate_| and may only be used if 762 // |delegate_| is not NULL. See URLRequest::Delegate for the meaning 763 // of these functions. 764 void NotifyAuthRequired(AuthChallengeInfo* auth_info); 765 void NotifyAuthRequiredComplete(NetworkDelegate::AuthRequiredResponse result); 766 void NotifyCertificateRequested(SSLCertRequestInfo* cert_request_info); 767 void NotifySSLCertificateError(const SSLInfo& ssl_info, bool fatal); 768 void NotifyReadCompleted(int bytes_read); 769 770 // These functions delegate to |network_delegate_| if it is not NULL. 771 // If |network_delegate_| is NULL, cookies can be used unless 772 // SetDefaultCookiePolicyToBlock() has been called. 773 bool CanGetCookies(const CookieList& cookie_list) const; 774 bool CanSetCookie(const std::string& cookie_line, 775 CookieOptions* options) const; 776 bool CanEnablePrivacyMode() const; 777 778 // Called just before calling a delegate that may block a request. 779 void OnCallToDelegate(); 780 // Called when the delegate lets a request continue. Also called on 781 // cancellation. 782 void OnCallToDelegateComplete(); 783 784 // Contextual information used for this request. Cannot be NULL. This contains 785 // most of the dependencies which are shared between requests (disk cache, 786 // cookie store, socket pool, etc.) 787 const URLRequestContext* context_; 788 789 NetworkDelegate* network_delegate_; 790 791 // Tracks the time spent in various load states throughout this request. 792 BoundNetLog net_log_; 793 794 scoped_refptr<URLRequestJob> job_; 795 scoped_ptr<UploadDataStream> upload_data_stream_; 796 std::vector<GURL> url_chain_; 797 GURL first_party_for_cookies_; 798 GURL delegate_redirect_url_; 799 std::string method_; // "GET", "POST", etc. Should be all uppercase. 800 std::string referrer_; 801 ReferrerPolicy referrer_policy_; 802 HttpRequestHeaders extra_request_headers_; 803 int load_flags_; // Flags indicating the request type for the load; 804 // expected values are LOAD_* enums above. 805 806 // Never access methods of the |delegate_| directly. Always use the 807 // Notify... methods for this. 808 Delegate* delegate_; 809 810 // Current error status of the job. When no error has been encountered, this 811 // will be SUCCESS. If multiple errors have been encountered, this will be 812 // the first non-SUCCESS status seen. 813 URLRequestStatus status_; 814 815 // The HTTP response info, lazily initialized. 816 HttpResponseInfo response_info_; 817 818 // Tells us whether the job is outstanding. This is true from the time 819 // Start() is called to the time we dispatch RequestComplete and indicates 820 // whether the job is active. 821 bool is_pending_; 822 823 // Indicates if the request is in the process of redirecting to a new 824 // location. It is true from the time the headers complete until a 825 // new request begins. 826 bool is_redirecting_; 827 828 // Number of times we're willing to redirect. Used to guard against 829 // infinite redirects. 830 int redirect_limit_; 831 832 // Cached value for use after we've orphaned the job handling the 833 // first transaction in a request involving redirects. 834 UploadProgress final_upload_progress_; 835 836 // The priority level for this request. Objects like ClientSocketPool use 837 // this to determine which URLRequest to allocate sockets to first. 838 RequestPriority priority_; 839 840 // TODO(battre): The only consumer of the identifier_ is currently the 841 // web request API. We need to match identifiers of requests between the 842 // web request API and the web navigation API. As the URLRequest does not 843 // exist when the web navigation API is triggered, the tracking probably 844 // needs to be done outside of the URLRequest anyway. Therefore, this 845 // identifier should be deleted here. http://crbug.com/89321 846 // A globally unique identifier for this request. 847 const uint64 identifier_; 848 849 // True if this request is currently calling a delegate, or is blocked waiting 850 // for the URL request or network delegate to resume it. 851 bool calling_delegate_; 852 853 // An optional parameter that provides additional information about the 854 // delegate |this| is currently blocked on. 855 std::string delegate_info_; 856 DelegateInfoUsage delegate_info_usage_; 857 858 base::debug::LeakTracker<URLRequest> leak_tracker_; 859 860 // Callback passed to the network delegate to notify us when a blocked request 861 // is ready to be resumed or canceled. 862 CompletionCallback before_request_callback_; 863 864 // Safe-guard to ensure that we do not send multiple "I am completed" 865 // messages to network delegate. 866 // TODO(battre): Remove this. http://crbug.com/89049 867 bool has_notified_completion_; 868 869 // Authentication data used by the NetworkDelegate for this request, 870 // if one is present. |auth_credentials_| may be filled in when calling 871 // |NotifyAuthRequired| on the NetworkDelegate. |auth_info_| holds 872 // the authentication challenge being handled by |NotifyAuthRequired|. 873 AuthCredentials auth_credentials_; 874 scoped_refptr<AuthChallengeInfo> auth_info_; 875 876 int64 received_response_content_length_; 877 878 base::TimeTicks creation_time_; 879 880 // Timing information for the most recent request. Its start times are 881 // populated during Start(), and the rest are populated in OnResponseReceived. 882 LoadTimingInfo load_timing_info_; 883 884 scoped_ptr<const base::debug::StackTrace> stack_trace_; 885 886 DISALLOW_COPY_AND_ASSIGN(URLRequest); 887}; 888 889} // namespace net 890 891#endif // NET_URL_REQUEST_URL_REQUEST_H_ 892