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 // HttpStreamBase is an interface for reading and writing data to an 6 // HTTP-like stream that keeps the client agnostic of the actual underlying 7 // transport layer. This provides an abstraction for HttpStream and 8 // WebSocketHandshakeStreamBase. 9 10 #ifndef NET_HTTP_HTTP_STREAM_BASE_H_ 11 #define NET_HTTP_HTTP_STREAM_BASE_H_ 12 13 #include <string> 14 15 #include "base/basictypes.h" 16 #include "base/memory/scoped_ptr.h" 17 #include "net/base/completion_callback.h" 18 #include "net/base/net_export.h" 19 #include "net/base/request_priority.h" 20 #include "net/base/upload_progress.h" 21 22 namespace net { 23 24 class BoundNetLog; 25 class HttpNetworkSession; 26 class HttpRequestHeaders; 27 struct HttpRequestInfo; 28 class HttpResponseInfo; 29 class IOBuffer; 30 struct LoadTimingInfo; 31 class SSLCertRequestInfo; 32 class SSLInfo; 33 34 class NET_EXPORT_PRIVATE HttpStreamBase { 35 public: HttpStreamBase()36 HttpStreamBase() {} ~HttpStreamBase()37 virtual ~HttpStreamBase() {} 38 39 // Initialize stream. Must be called before calling SendRequest(). 40 // |request_info| must outlive the HttpStreamBase. 41 // Returns a net error code, possibly ERR_IO_PENDING. 42 virtual int InitializeStream(const HttpRequestInfo* request_info, 43 RequestPriority priority, 44 const BoundNetLog& net_log, 45 const CompletionCallback& callback) = 0; 46 47 // Writes the headers and uploads body data to the underlying socket. 48 // ERR_IO_PENDING is returned if the operation could not be completed 49 // synchronously, in which case the result will be passed to the callback 50 // when available. Returns OK on success. 51 // 52 // The callback will only be invoked once the first full set of headers have 53 // been received, at which point |response| will have been populated with that 54 // set of headers, and is safe to read, until/unless ReadResponseHeaders is 55 // called. 56 // 57 // |response| must remain valid until all sets of headers has been read, or 58 // the HttpStreamBase is destroyed. There's typically only one set of 59 // headers, except in the case of 1xx responses (See ReadResponseHeaders). 60 virtual int SendRequest(const HttpRequestHeaders& request_headers, 61 HttpResponseInfo* response, 62 const CompletionCallback& callback) = 0; 63 64 // Reads from the underlying socket until the next set of response headers 65 // have been completely received. This may only be called on 1xx responses 66 // after SendRequest has completed successfully, to read the next set of 67 // headers. 68 // 69 // ERR_IO_PENDING is returned if the operation could not be completed 70 // synchronously, in which case the result will be passed to the callback when 71 // available. Returns OK on success. The response headers are available in 72 // the HttpResponseInfo passed in to original call to SendRequest. 73 virtual int ReadResponseHeaders(const CompletionCallback& callback) = 0; 74 75 // Reads response body data, up to |buf_len| bytes. |buf_len| should be a 76 // reasonable size (<2MB). The number of bytes read is returned, or an 77 // error is returned upon failure. 0 indicates that the request has been 78 // fully satisfied and there is no more data to read. 79 // ERR_CONNECTION_CLOSED is returned when the connection has been closed 80 // prematurely. ERR_IO_PENDING is returned if the operation could not be 81 // completed synchronously, in which case the result will be passed to the 82 // callback when available. If the operation is not completed immediately, 83 // the socket acquires a reference to the provided buffer until the callback 84 // is invoked or the socket is destroyed. 85 virtual int ReadResponseBody(IOBuffer* buf, int buf_len, 86 const CompletionCallback& callback) = 0; 87 88 // Closes the stream. 89 // |not_reusable| indicates if the stream can be used for further requests. 90 // In the case of HTTP, where we re-use the byte-stream (e.g. the connection) 91 // this means we need to close the connection; in the case of SPDY, where the 92 // underlying stream is never reused, it has no effect. 93 // TODO(mbelshe): We should figure out how to fold the not_reusable flag 94 // into the stream implementation itself so that the caller 95 // does not need to pass it at all. We might also be able to 96 // eliminate the SetConnectionReused() below. 97 virtual void Close(bool not_reusable) = 0; 98 99 // Indicates if the response body has been completely read. 100 virtual bool IsResponseBodyComplete() const = 0; 101 102 // Indicates that the end of the response is detectable. This means that 103 // the response headers indicate either chunked encoding or content length. 104 // If neither is sent, the server must close the connection for us to detect 105 // the end of the response. 106 // TODO(rch): Rename this method, so that it is clear why it exists 107 // particularly as it applies to QUIC and SPDY for which the end of the 108 // response is always findable. 109 virtual bool CanFindEndOfResponse() const = 0; 110 111 // A stream exists on top of a connection. If the connection has been used 112 // to successfully exchange data in the past, error handling for the 113 // stream is done differently. This method returns true if the underlying 114 // connection is reused or has been connected and idle for some time. 115 virtual bool IsConnectionReused() const = 0; 116 virtual void SetConnectionReused() = 0; 117 118 // Checks whether the current state of the underlying connection 119 // allows it to be reused. 120 virtual bool IsConnectionReusable() const = 0; 121 122 // Get the total number of bytes received from network for this stream. 123 virtual int64 GetTotalReceivedBytes() const = 0; 124 125 // Populates the connection establishment part of |load_timing_info|, and 126 // socket ID. |load_timing_info| must have all null times when called. 127 // Returns false and does nothing if there is no underlying connection, either 128 // because one has yet to be assigned to the stream, or because the underlying 129 // socket has been closed. 130 // 131 // In practice, this means that this function will always succeed any time 132 // between when the full headers have been received and the stream has been 133 // closed. 134 virtual bool GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const = 0; 135 136 // Get the SSLInfo associated with this stream's connection. This should 137 // only be called for streams over SSL sockets, otherwise the behavior is 138 // undefined. 139 virtual void GetSSLInfo(SSLInfo* ssl_info) = 0; 140 141 // Get the SSLCertRequestInfo associated with this stream's connection. 142 // This should only be called for streams over SSL sockets, otherwise the 143 // behavior is undefined. 144 virtual void GetSSLCertRequestInfo(SSLCertRequestInfo* cert_request_info) = 0; 145 146 // HACK(willchan): Really, we should move the HttpResponseDrainer logic into 147 // the HttpStream implementation. This is just a quick hack. 148 virtual bool IsSpdyHttpStream() const = 0; 149 150 // In the case of an HTTP error or redirect, flush the response body (usually 151 // a simple error or "this page has moved") so that we can re-use the 152 // underlying connection. This stream is responsible for deleting itself when 153 // draining is complete. 154 virtual void Drain(HttpNetworkSession* session) = 0; 155 156 // Called when the priority of the parent transaction changes. 157 virtual void SetPriority(RequestPriority priority) = 0; 158 159 private: 160 DISALLOW_COPY_AND_ASSIGN(HttpStreamBase); 161 }; 162 163 } // namespace net 164 165 #endif // NET_HTTP_HTTP_STREAM_BASE_H_ 166