Home | History | Annotate | Download | only in http 
      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 // HttpStream is an interface for reading and writing data to an HttpStream that
      6 // keeps the client agnostic of the actual underlying transport layer.  This
      7 // provides an abstraction for both a basic http stream as well as http
      8 // pipelining implementations.  The HttpStream subtype is expected to manage the
      9 // underlying transport appropriately.  For example, a non-pipelined HttpStream
     10 // would return the transport socket to the pool for reuse.  SPDY streams on the
     11 // other hand leave the transport socket management to the SpdySession.
     12 
     13 #ifndef NET_HTTP_HTTP_STREAM_H_
     14 #define NET_HTTP_HTTP_STREAM_H_
     15 #pragma once
     16 
     17 #include <string>
     18 
     19 #include "base/basictypes.h"
     20 #include "net/base/completion_callback.h"
     21 
     22 namespace net {
     23 
     24 class BoundNetLog;
     25 class HttpRequestHeaders;
     26 struct HttpRequestInfo;
     27 class HttpResponseInfo;
     28 class IOBuffer;
     29 class SSLCertRequestInfo;
     30 class SSLInfo;
     31 class UploadDataStream;
     32 
     33 class HttpStream {
     34  public:
     35   HttpStream() {}
     36   virtual ~HttpStream() {}
     37 
     38   // Initialize stream.  Must be called before calling SendRequest().
     39   // Returns a net error code, possibly ERR_IO_PENDING.
     40   virtual int InitializeStream(const HttpRequestInfo* request_info,
     41                                const BoundNetLog& net_log,
     42                                CompletionCallback* callback) = 0;
     43 
     44   // Writes the headers and uploads body data to the underlying socket.
     45   // ERR_IO_PENDING is returned if the operation could not be completed
     46   // synchronously, in which case the result will be passed to the callback
     47   // when available. Returns OK on success. The HttpStream takes ownership
     48   // of the request_body.
     49   virtual int SendRequest(const HttpRequestHeaders& request_headers,
     50                           UploadDataStream* request_body,
     51                           HttpResponseInfo* response,
     52                           CompletionCallback* callback) = 0;
     53 
     54   // Queries the UploadDataStream for its progress (bytes sent).
     55   virtual uint64 GetUploadProgress() const = 0;
     56 
     57   // Reads from the underlying socket until the response headers have been
     58   // completely received. ERR_IO_PENDING is returned if the operation could
     59   // not be completed synchronously, in which case the result will be passed
     60   // to the callback when available. Returns OK on success.  The response
     61   // headers are available in the HttpResponseInfo returned by GetResponseInfo
     62   virtual int ReadResponseHeaders(CompletionCallback* callback) = 0;
     63 
     64   // Provides access to HttpResponseInfo (owned by HttpStream).
     65   virtual const HttpResponseInfo* GetResponseInfo() const = 0;
     66 
     67   // Reads response body data, up to |buf_len| bytes. |buf_len| should be a
     68   // reasonable size (<2MB). The number of bytes read is returned, or an
     69   // error is returned upon failure.  0 indicates that the request has been
     70   // fully satisfied and there is no more data to read.
     71   // ERR_CONNECTION_CLOSED is returned when the connection has been closed
     72   // prematurely.  ERR_IO_PENDING is returned if the operation could not be
     73   // completed synchronously, in which case the result will be passed to the
     74   // callback when available. If the operation is not completed immediately,
     75   // the socket acquires a reference to the provided buffer until the callback
     76   // is invoked or the socket is destroyed.
     77   virtual int ReadResponseBody(IOBuffer* buf, int buf_len,
     78                                CompletionCallback* callback) = 0;
     79 
     80   // Closes the stream.
     81   // |not_reusable| indicates if the stream can be used for further requests.
     82   // In the case of HTTP, where we re-use the byte-stream (e.g. the connection)
     83   // this means we need to close the connection; in the case of SPDY, where the
     84   // underlying stream is never reused, it has no effect.
     85   // TODO(mbelshe): We should figure out how to fold the not_reusable flag
     86   //                into the stream implementation itself so that the caller
     87   //                does not need to pass it at all.  We might also be able to
     88   //                eliminate the SetConnectionReused() below.
     89   virtual void Close(bool not_reusable) = 0;
     90 
     91   // Returns a new (not initialized) stream using the same underlying
     92   // connection and invalidates the old stream - no further methods should be
     93   // called on the old stream.  The caller should ensure that the response body
     94   // from the previous request is drained before calling this method.  If the
     95   // subclass does not support renewing the stream, NULL is returned.
     96   virtual HttpStream* RenewStreamForAuth() = 0;
     97 
     98   // Indicates if the response body has been completely read.
     99   virtual bool IsResponseBodyComplete() const = 0;
    100 
    101   // Indicates that the end of the response is detectable. This means that
    102   // the response headers indicate either chunked encoding or content length.
    103   // If neither is sent, the server must close the connection for us to detect
    104   // the end of the response.
    105   virtual bool CanFindEndOfResponse() const = 0;
    106 
    107   // After the response headers have been read and after the response body
    108   // is complete, this function indicates if more data (either erroneous or
    109   // as part of the next pipelined response) has been read from the socket.
    110   virtual bool IsMoreDataBuffered() const = 0;
    111 
    112   // A stream exists on top of a connection.  If the connection has been used
    113   // to successfully exchange data in the past, error handling for the
    114   // stream is done differently.  This method returns true if the underlying
    115   // connection is reused or has been connected and idle for some time.
    116   virtual bool IsConnectionReused() const = 0;
    117   virtual void SetConnectionReused() = 0;
    118 
    119   // Checks whether the current state of the underlying connection
    120   // allows it to be reused.
    121   virtual bool IsConnectionReusable() const = 0;
    122 
    123   // Get the SSLInfo associated with this stream's connection.  This should
    124   // only be called for streams over SSL sockets, otherwise the behavior is
    125   // undefined.
    126   virtual void GetSSLInfo(SSLInfo* ssl_info) = 0;
    127 
    128   // Get the SSLCertRequestInfo associated with this stream's connection.
    129   // This should only be called for streams over SSL sockets, otherwise the
    130   // behavior is undefined.
    131   virtual void GetSSLCertRequestInfo(SSLCertRequestInfo* cert_request_info) = 0;
    132 
    133   // HACK(willchan): Really, we should move the HttpResponseDrainer logic into
    134   // the HttpStream implementation. This is just a quick hack.
    135   virtual bool IsSpdyHttpStream() const = 0;
    136 
    137  private:
    138   DISALLOW_COPY_AND_ASSIGN(HttpStream);
    139 };
    140 
    141 }  // namespace net
    142 
    143 #endif  // NET_HTTP_HTTP_STREAM_H_
    144