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 14 namespace net { 15 16 class AuthCredentials; 17 class BoundNetLog; 18 class HttpRequestHeaders; 19 struct HttpRequestInfo; 20 class HttpResponseInfo; 21 class IOBuffer; 22 struct LoadTimingInfo; 23 class X509Certificate; 24 25 // Represents a single HTTP transaction (i.e., a single request/response pair). 26 // HTTP redirects are not followed and authentication challenges are not 27 // answered. Cookies are assumed to be managed by the caller. 28 class NET_EXPORT_PRIVATE HttpTransaction { 29 public: 30 // Stops any pending IO and destroys the transaction object. 31 virtual ~HttpTransaction() {} 32 33 // Starts the HTTP transaction (i.e., sends the HTTP request). 34 // 35 // Returns OK if the transaction could be started synchronously, which means 36 // that the request was served from the cache. ERR_IO_PENDING is returned to 37 // indicate that the CompletionCallback will be notified once response info is 38 // available or if an IO error occurs. Any other return value indicates that 39 // the transaction could not be started. 40 // 41 // Regardless of the return value, the caller is expected to keep the 42 // request_info object alive until Destroy is called on the transaction. 43 // 44 // NOTE: The transaction is not responsible for deleting the callback object. 45 // 46 // Profiling information for the request is saved to |net_log| if non-NULL. 47 virtual int Start(const HttpRequestInfo* request_info, 48 const CompletionCallback& callback, 49 const BoundNetLog& net_log) = 0; 50 51 // Restarts the HTTP transaction, ignoring the last error. This call can 52 // only be made after a call to Start (or RestartIgnoringLastError) failed. 53 // Once Read has been called, this method cannot be called. This method is 54 // used, for example, to continue past various SSL related errors. 55 // 56 // Not all errors can be ignored using this method. See error code 57 // descriptions for details about errors that can be ignored. 58 // 59 // NOTE: The transaction is not responsible for deleting the callback object. 60 // 61 virtual int RestartIgnoringLastError(const CompletionCallback& callback) = 0; 62 63 // Restarts the HTTP transaction with a client certificate. 64 virtual int RestartWithCertificate(X509Certificate* client_cert, 65 const CompletionCallback& callback) = 0; 66 67 // Restarts the HTTP transaction with authentication credentials. 68 virtual int RestartWithAuth(const AuthCredentials& credentials, 69 const CompletionCallback& callback) = 0; 70 71 // Returns true if auth is ready to be continued. Callers should check 72 // this value anytime Start() completes: if it is true, the transaction 73 // can be resumed with RestartWithAuth(L"", L"", callback) to resume 74 // the automatic auth exchange. This notification gives the caller a 75 // chance to process the response headers from all of the intermediate 76 // restarts needed for authentication. 77 virtual bool IsReadyToRestartForAuth() = 0; 78 79 // Once response info is available for the transaction, response data may be 80 // read by calling this method. 81 // 82 // Response data is copied into the given buffer and the number of bytes 83 // copied is returned. ERR_IO_PENDING is returned if response data is not 84 // yet available. The CompletionCallback is notified when the data copy 85 // completes, and it is passed the number of bytes that were successfully 86 // copied. Or, if a read error occurs, the CompletionCallback is notified of 87 // the error. Any other negative return value indicates that the transaction 88 // could not be read. 89 // 90 // NOTE: The transaction is not responsible for deleting the callback object. 91 // If the operation is not completed immediately, the transaction must acquire 92 // a reference to the provided buffer. 93 // 94 virtual int Read(IOBuffer* buf, int buf_len, 95 const CompletionCallback& callback) = 0; 96 97 // Stops further caching of this request by the HTTP cache, if there is any. 98 virtual void StopCaching() = 0; 99 100 // Gets the full request headers sent to the server. This is guaranteed to 101 // work only if Start returns success and the underlying transaction supports 102 // it. (Right now, this is only network transactions, not cache ones.) 103 // 104 // Returns true and overwrites headers if it can get the request headers; 105 // otherwise, returns false and does not modify headers. 106 virtual bool GetFullRequestHeaders(HttpRequestHeaders* headers) const = 0; 107 108 // Called to tell the transaction that we have successfully reached the end 109 // of the stream. This is equivalent to performing an extra Read() at the end 110 // that should return 0 bytes. This method should not be called if the 111 // transaction is busy processing a previous operation (like a pending Read). 112 virtual void DoneReading() = 0; 113 114 // Returns the response info for this transaction or NULL if the response 115 // info is not available. 116 virtual const HttpResponseInfo* GetResponseInfo() const = 0; 117 118 // Returns the load state for this transaction. 119 virtual LoadState GetLoadState() const = 0; 120 121 // Returns the upload progress in bytes. If there is no upload data, 122 // zero will be returned. This does not include the request headers. 123 virtual UploadProgress GetUploadProgress() const = 0; 124 125 // Populates all of load timing, except for request start times and receive 126 // headers time. 127 // |load_timing_info| must have all null times when called. Returns false and 128 // does not modify |load_timing_info| if there's no timing information to 129 // provide. 130 virtual bool GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const = 0; 131 132 // Called when the priority of the parent job changes. 133 virtual void SetPriority(RequestPriority priority) = 0; 134 }; 135 136 } // namespace net 137 138 #endif // NET_HTTP_HTTP_TRANSACTION_H_ 139
