net/http/http_stream_base.h

   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:
  36   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   // |response| must outlive the HttpStreamBase.
  52   virtual int SendRequest(const HttpRequestHeaders& request_headers,
  53                           HttpResponseInfo* response,
  54                           const CompletionCallback& callback) = 0;
  55
  56   // Reads from the underlying socket until the response headers have been
  57   // completely received. ERR_IO_PENDING is returned if the operation could
  58   // not be completed synchronously, in which case the result will be passed
  59   // to the callback when available. Returns OK on success.  The response
  60   // headers are available in the HttpResponseInfo returned by GetResponseInfo
  61   virtual int ReadResponseHeaders(const CompletionCallback& callback) = 0;
  62
  63   // Provides access to HttpResponseInfo (owned by HttpStream).
  64   virtual const HttpResponseInfo* GetResponseInfo() const = 0;
  65
  66   // Reads response body data, up to |buf_len| bytes. |buf_len| should be a
  67   // reasonable size (<2MB). The number of bytes read is returned, or an
  68   // error is returned upon failure.  0 indicates that the request has been
  69   // fully satisfied and there is no more data to read.
  70   // ERR_CONNECTION_CLOSED is returned when the connection has been closed
  71   // prematurely.  ERR_IO_PENDING is returned if the operation could not be
  72   // completed synchronously, in which case the result will be passed to the
  73   // callback when available. If the operation is not completed immediately,
  74   // the socket acquires a reference to the provided buffer until the callback
  75   // is invoked or the socket is destroyed.
  76   virtual int ReadResponseBody(IOBuffer* buf, int buf_len,
  77                                const CompletionCallback& callback) = 0;
  78
  79   // Closes the stream.
  80   // |not_reusable| indicates if the stream can be used for further requests.
  81   // In the case of HTTP, where we re-use the byte-stream (e.g. the connection)
  82   // this means we need to close the connection; in the case of SPDY, where the
  83   // underlying stream is never reused, it has no effect.
  84   // TODO(mbelshe): We should figure out how to fold the not_reusable flag
  85   //                into the stream implementation itself so that the caller
  86   //                does not need to pass it at all.  We might also be able to
  87   //                eliminate the SetConnectionReused() below.
  88   virtual void Close(bool not_reusable) = 0;
  89
  90   // Indicates if the response body has been completely read.
  91   virtual bool IsResponseBodyComplete() const = 0;
  92
  93   // Indicates that the end of the response is detectable. This means that
  94   // the response headers indicate either chunked encoding or content length.
  95   // If neither is sent, the server must close the connection for us to detect
  96   // the end of the response.
  97   // TODO(rch): Rename this method, so that it is clear why it exists
  98   // particularly as it applies to QUIC and SPDY for which the end of the
  99   // response is always findable.
 100   virtual bool CanFindEndOfResponse() const = 0;
 101
 102   // A stream exists on top of a connection.  If the connection has been used
 103   // to successfully exchange data in the past, error handling for the
 104   // stream is done differently.  This method returns true if the underlying
 105   // connection is reused or has been connected and idle for some time.
 106   virtual bool IsConnectionReused() const = 0;
 107   virtual void SetConnectionReused() = 0;
 108
 109   // Checks whether the current state of the underlying connection
 110   // allows it to be reused.
 111   virtual bool IsConnectionReusable() const = 0;
 112
 113   // Get the total number of bytes received from network for this stream.
 114   virtual int64 GetTotalReceivedBytes() const = 0;
 115
 116   // Populates the connection establishment part of |load_timing_info|, and
 117   // socket ID.  |load_timing_info| must have all null times when called.
 118   // Returns false and does nothing if there is no underlying connection, either
 119   // because one has yet to be assigned to the stream, or because the underlying
 120   // socket has been closed.
 121   //
 122   // In practice, this means that this function will always succeed any time
 123   // between when the full headers have been received and the stream has been
 124   // closed.
 125   virtual bool GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const = 0;
 126
 127   // Get the SSLInfo associated with this stream's connection.  This should
 128   // only be called for streams over SSL sockets, otherwise the behavior is
 129   // undefined.
 130   virtual void GetSSLInfo(SSLInfo* ssl_info) = 0;
 131
 132   // Get the SSLCertRequestInfo associated with this stream's connection.
 133   // This should only be called for streams over SSL sockets, otherwise the
 134   // behavior is undefined.
 135   virtual void GetSSLCertRequestInfo(SSLCertRequestInfo* cert_request_info) = 0;
 136
 137   // HACK(willchan): Really, we should move the HttpResponseDrainer logic into
 138   // the HttpStream implementation. This is just a quick hack.
 139   virtual bool IsSpdyHttpStream() const = 0;
 140
 141   // In the case of an HTTP error or redirect, flush the response body (usually
 142   // a simple error or "this page has moved") so that we can re-use the
 143   // underlying connection. This stream is responsible for deleting itself when
 144   // draining is complete.
 145   virtual void Drain(HttpNetworkSession* session) = 0;
 146
 147   // Called when the priority of the parent transaction changes.
 148   virtual void SetPriority(RequestPriority priority) = 0;
 149
 150  private:
 151   DISALLOW_COPY_AND_ASSIGN(HttpStreamBase);
 152 };
 153
 154 }  // namespace net
 155
 156 #endif  // NET_HTTP_HTTP_STREAM_BASE_H_