1 // Copyright (c) 2011 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_HTTP_HTTP_TRANSACTION_H_ 6 #define NET_HTTP_HTTP_TRANSACTION_H_ 7 8 #include "net/base/completion_callback.h" 9 #include "net/base/load_states.h" 10 #include "net/base/net_export.h" 11 #include "net/base/request_priority.h" 12 #include "net/base/upload_progress.h" 13 #include "net/websockets/websocket_handshake_stream_base.h" 14 15 namespace net { 16 17 class AuthCredentials; 18 class BoundNetLog; 19 class HttpRequestHeaders; 20 struct HttpRequestInfo; 21 class HttpResponseInfo; 22 class IOBuffer; 23 struct LoadTimingInfo; 24 class ProxyInfo; 25 class QuicServerInfo; 26 class X509Certificate; 27 28 // Represents a single HTTP transaction (i.e., a single request/response pair). 29 // HTTP redirects are not followed and authentication challenges are not 30 // answered. Cookies are assumed to be managed by the caller. 31 class NET_EXPORT_PRIVATE HttpTransaction { 32 public: 33 // If |*defer| is set to true, the transaction will wait until 34 // ResumeNetworkStart is called before establishing a connection. 35 typedef base::Callback<void(bool* defer)> BeforeNetworkStartCallback; 36 37 // Provides an opportunity to add proxy-specific request headers. Called after 38 // it is determined that a proxy is being used and before the request headers 39 // are sent. |proxy_info| contains information about the proxy being used, 40 // and additional headers may be added to |request_headers|. 41 typedef base::Callback<void( 42 const ProxyInfo& proxy_info, 43 HttpRequestHeaders* request_headers)> BeforeProxyHeadersSentCallback; 44 45 // Stops any pending IO and destroys the transaction object. 46 virtual ~HttpTransaction() {} 47 48 // Starts the HTTP transaction (i.e., sends the HTTP request). 49 // 50 // Returns OK if the transaction could be started synchronously, which means 51 // that the request was served from the cache. ERR_IO_PENDING is returned to 52 // indicate that the CompletionCallback will be notified once response info is 53 // available or if an IO error occurs. Any other return value indicates that 54 // the transaction could not be started. 55 // 56 // Regardless of the return value, the caller is expected to keep the 57 // request_info object alive until Destroy is called on the transaction. 58 // 59 // NOTE: The transaction is not responsible for deleting the callback object. 60 // 61 // Profiling information for the request is saved to |net_log| if non-NULL. 62 virtual int Start(const HttpRequestInfo* request_info, 63 const CompletionCallback& callback, 64 const BoundNetLog& net_log) = 0; 65 66 // Restarts the HTTP transaction, ignoring the last error. This call can 67 // only be made after a call to Start (or RestartIgnoringLastError) failed. 68 // Once Read has been called, this method cannot be called. This method is 69 // used, for example, to continue past various SSL related errors. 70 // 71 // Not all errors can be ignored using this method. See error code 72 // descriptions for details about errors that can be ignored. 73 // 74 // NOTE: The transaction is not responsible for deleting the callback object. 75 // 76 virtual int RestartIgnoringLastError(const CompletionCallback& callback) = 0; 77 78 // Restarts the HTTP transaction with a client certificate. 79 virtual int RestartWithCertificate(X509Certificate* client_cert, 80 const CompletionCallback& callback) = 0; 81 82 // Restarts the HTTP transaction with authentication credentials. 83 virtual int RestartWithAuth(const AuthCredentials& credentials, 84 const CompletionCallback& callback) = 0; 85 86 // Returns true if auth is ready to be continued. Callers should check 87 // this value anytime Start() completes: if it is true, the transaction 88 // can be resumed with RestartWithAuth(L"", L"", callback) to resume 89 // the automatic auth exchange. This notification gives the caller a 90 // chance to process the response headers from all of the intermediate 91 // restarts needed for authentication. 92 virtual bool IsReadyToRestartForAuth() = 0; 93 94 // Once response info is available for the transaction, response data may be 95 // read by calling this method. 96 // 97 // Response data is copied into the given buffer and the number of bytes 98 // copied is returned. ERR_IO_PENDING is returned if response data is not 99 // yet available. The CompletionCallback is notified when the data copy 100 // completes, and it is passed the number of bytes that were successfully 101 // copied. Or, if a read error occurs, the CompletionCallback is notified of 102 // the error. Any other negative return value indicates that the transaction 103 // could not be read. 104 // 105 // NOTE: The transaction is not responsible for deleting the callback object. 106 // If the operation is not completed immediately, the transaction must acquire 107 // a reference to the provided buffer. 108 // 109 virtual int Read(IOBuffer* buf, int buf_len, 110 const CompletionCallback& callback) = 0; 111 112 // Stops further caching of this request by the HTTP cache, if there is any. 113 virtual void StopCaching() = 0; 114 115 // Gets the full request headers sent to the server. This is guaranteed to 116 // work only if Start returns success and the underlying transaction supports 117 // it. (Right now, this is only network transactions, not cache ones.) 118 // 119 // Returns true and overwrites headers if it can get the request headers; 120 // otherwise, returns false and does not modify headers. 121 virtual bool GetFullRequestHeaders(HttpRequestHeaders* headers) const = 0; 122 123 // Get the number of bytes received from network. 124 virtual int64 GetTotalReceivedBytes() const = 0; 125 126 // Called to tell the transaction that we have successfully reached the end 127 // of the stream. This is equivalent to performing an extra Read() at the end 128 // that should return 0 bytes. This method should not be called if the 129 // transaction is busy processing a previous operation (like a pending Read). 130 // 131 // DoneReading may also be called before the first Read() to notify that the 132 // entire response body is to be ignored (e.g., in a redirect). 133 virtual void DoneReading() = 0; 134 135 // Returns the response info for this transaction or NULL if the response 136 // info is not available. 137 virtual const HttpResponseInfo* GetResponseInfo() const = 0; 138 139 // Returns the load state for this transaction. 140 virtual LoadState GetLoadState() const = 0; 141 142 // Returns the upload progress in bytes. If there is no upload data, 143 // zero will be returned. This does not include the request headers. 144 virtual UploadProgress GetUploadProgress() const = 0; 145 146 // SetQuicServerInfo sets a object which reads and writes public information 147 // about a QUIC server. 148 virtual void SetQuicServerInfo(QuicServerInfo* quic_server_info) = 0; 149 150 // Populates all of load timing, except for request start times and receive 151 // headers time. 152 // |load_timing_info| must have all null times when called. Returns false and 153 // does not modify |load_timing_info| if there's no timing information to 154 // provide. 155 virtual bool GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const = 0; 156 157 // Called when the priority of the parent job changes. 158 virtual void SetPriority(RequestPriority priority) = 0; 159 160 // Set the WebSocketHandshakeStreamBase::CreateHelper to be used for the 161 // request. Only relevant to WebSocket transactions. Must be called before 162 // Start(). Ownership of |create_helper| remains with the caller. 163 virtual void SetWebSocketHandshakeStreamCreateHelper( 164 WebSocketHandshakeStreamBase::CreateHelper* create_helper) = 0; 165 166 // Set the callback to receive notification just before network use. 167 virtual void SetBeforeNetworkStartCallback( 168 const BeforeNetworkStartCallback& callback) = 0; 169 170 // Set the callback to receive notification just before a proxy request 171 // is to be sent. 172 virtual void SetBeforeProxyHeadersSentCallback( 173 const BeforeProxyHeadersSentCallback& callback) = 0; 174 175 // Resumes the transaction after being deferred. 176 virtual int ResumeNetworkStart() = 0; 177 }; 178 179 } // namespace net 180 181 #endif // NET_HTTP_HTTP_TRANSACTION_H_ 182
