net/socket/client_socket_handle.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 #ifndef NET_SOCKET_CLIENT_SOCKET_HANDLE_H_
   6 #define NET_SOCKET_CLIENT_SOCKET_HANDLE_H_
   7
   8 #include <string>
   9
  10 #include "base/logging.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "base/memory/scoped_ptr.h"
  13 #include "base/time.h"
  14 #include "net/base/completion_callback.h"
  15 #include "net/base/load_states.h"
  16 #include "net/base/net_errors.h"
  17 #include "net/base/net_export.h"
  18 #include "net/base/net_log.h"
  19 #include "net/base/request_priority.h"
  20 #include "net/http/http_response_info.h"
  21 #include "net/socket/client_socket_pool.h"
  22 #include "net/socket/stream_socket.h"
  23
  24 namespace net {
  25
  26 // A container for a StreamSocket.
  27 //
  28 // The handle's |group_name| uniquely identifies the origin and type of the
  29 // connection.  It is used by the ClientSocketPool to group similar connected
  30 // client socket objects.
  31 //
  32 class NET_EXPORT ClientSocketHandle {
  33  public:
  34   enum SocketReuseType {
  35     UNUSED = 0,   // unused socket that just finished connecting
  36     UNUSED_IDLE,  // unused socket that has been idle for awhile
  37     REUSED_IDLE,  // previously used socket
  38     NUM_TYPES,
  39   };
  40
  41   ClientSocketHandle();
  42   ~ClientSocketHandle();
  43
  44   // Initializes a ClientSocketHandle object, which involves talking to the
  45   // ClientSocketPool to obtain a connected socket, possibly reusing one.  This
  46   // method returns either OK or ERR_IO_PENDING.  On ERR_IO_PENDING, |priority|
  47   // is used to determine the placement in ClientSocketPool's wait list.
  48   //
  49   // If this method succeeds, then the socket member will be set to an existing
  50   // connected socket if an existing connected socket was available to reuse,
  51   // otherwise it will be set to a new connected socket.  Consumers can then
  52   // call is_reused() to see if the socket was reused.  If not reusing an
  53   // existing socket, ClientSocketPool may need to establish a new
  54   // connection using |socket_params|.
  55   //
  56   // This method returns ERR_IO_PENDING if it cannot complete synchronously, in
  57   // which case the consumer will be notified of completion via |callback|.
  58   //
  59   // If the pool was not able to reuse an existing socket, the new socket
  60   // may report a recoverable error.  In this case, the return value will
  61   // indicate an error and the socket member will be set.  If it is determined
  62   // that the error is not recoverable, the Disconnect method should be used
  63   // on the socket, so that it does not get reused.
  64   //
  65   // A non-recoverable error may set additional state in the ClientSocketHandle
  66   // to allow the caller to determine what went wrong.
  67   //
  68   // Init may be called multiple times.
  69   //
  70   // Profiling information for the request is saved to |net_log| if non-NULL.
  71   //
  72   template <typename SocketParams, typename PoolType>
  73   int Init(const std::string& group_name,
  74            const scoped_refptr<SocketParams>& socket_params,
  75            RequestPriority priority,
  76            const CompletionCallback& callback,
  77            PoolType* pool,
  78            const BoundNetLog& net_log);
  79
  80   // An initialized handle can be reset, which causes it to return to the
  81   // un-initialized state.  This releases the underlying socket, which in the
  82   // case of a socket that still has an established connection, indicates that
  83   // the socket may be kept alive for use by a subsequent ClientSocketHandle.
  84   //
  85   // NOTE: To prevent the socket from being kept alive, be sure to call its
  86   // Disconnect method.  This will result in the ClientSocketPool deleting the
  87   // StreamSocket.
  88   void Reset();
  89
  90   // Used after Init() is called, but before the ClientSocketPool has
  91   // initialized the ClientSocketHandle.
  92   LoadState GetLoadState() const;
  93
  94   bool IsPoolStalled() const;
  95
  96   void AddLayeredPool(LayeredPool* layered_pool);
  97
  98   void RemoveLayeredPool(LayeredPool* layered_pool);
  99
 100   // Returns true when Init() has completed successfully.
 101   bool is_initialized() const { return is_initialized_; }
 102
 103   // Returns the time tick when Init() was called.
 104   base::TimeTicks init_time() const { return init_time_; }
 105
 106   // Returns the time between Init() and when is_initialized() becomes true.
 107   base::TimeDelta setup_time() const { return setup_time_; }
 108
 109   // Used by ClientSocketPool to initialize the ClientSocketHandle.
 110   void set_is_reused(bool is_reused) { is_reused_ = is_reused; }
 111   void set_socket(StreamSocket* s) { socket_.reset(s); }
 112   void set_idle_time(base::TimeDelta idle_time) { idle_time_ = idle_time; }
 113   void set_pool_id(int id) { pool_id_ = id; }
 114   void set_is_ssl_error(bool is_ssl_error) { is_ssl_error_ = is_ssl_error; }
 115   void set_ssl_error_response_info(const HttpResponseInfo& ssl_error_state) {
 116     ssl_error_response_info_ = ssl_error_state;
 117   }
 118   void set_pending_http_proxy_connection(ClientSocketHandle* connection) {
 119     pending_http_proxy_connection_.reset(connection);
 120   }
 121
 122   // Only valid if there is no |socket_|.
 123   bool is_ssl_error() const {
 124     DCHECK(socket_.get() == NULL);
 125     return is_ssl_error_;
 126   }
 127   // On an ERR_PROXY_AUTH_REQUESTED error, the |headers| and |auth_challenge|
 128   // fields are filled in. On an ERR_SSL_CLIENT_AUTH_CERT_NEEDED error,
 129   // the |cert_request_info| field is set.
 130   const HttpResponseInfo& ssl_error_response_info() const {
 131     return ssl_error_response_info_;
 132   }
 133   ClientSocketHandle* release_pending_http_proxy_connection() {
 134     return pending_http_proxy_connection_.release();
 135   }
 136
 137   // These may only be used if is_initialized() is true.
 138   const std::string& group_name() const { return group_name_; }
 139   int id() const { return pool_id_; }
 140   StreamSocket* socket() { return socket_.get(); }
 141   StreamSocket* release_socket() { return socket_.release(); }
 142   bool is_reused() const { return is_reused_; }
 143   base::TimeDelta idle_time() const { return idle_time_; }
 144   SocketReuseType reuse_type() const {
 145     if (is_reused()) {
 146       return REUSED_IDLE;
 147     } else if (idle_time() == base::TimeDelta()) {
 148       return UNUSED;
 149     } else {
 150       return UNUSED_IDLE;
 151     }
 152   }
 153
 154  private:
 155   // Called on asynchronous completion of an Init() request.
 156   void OnIOComplete(int result);
 157
 158   // Called on completion (both asynchronous & synchronous) of an Init()
 159   // request.
 160   void HandleInitCompletion(int result);
 161
 162   // Resets the state of the ClientSocketHandle.  |cancel| indicates whether or
 163   // not to try to cancel the request with the ClientSocketPool.  Does not
 164   // reset the supplemental error state.
 165   void ResetInternal(bool cancel);
 166
 167   // Resets the supplemental error state.
 168   void ResetErrorState();
 169
 170   bool is_initialized_;
 171   ClientSocketPool* pool_;
 172   LayeredPool* layered_pool_;
 173   scoped_ptr<StreamSocket> socket_;
 174   std::string group_name_;
 175   bool is_reused_;
 176   CompletionCallback callback_;
 177   CompletionCallback user_callback_;
 178   base::TimeDelta idle_time_;
 179   int pool_id_;  // See ClientSocketPool::ReleaseSocket() for an explanation.
 180   bool is_ssl_error_;
 181   HttpResponseInfo ssl_error_response_info_;
 182   scoped_ptr<ClientSocketHandle> pending_http_proxy_connection_;
 183   base::TimeTicks init_time_;
 184   base::TimeDelta setup_time_;
 185
 186   NetLog::Source requesting_source_;
 187
 188   DISALLOW_COPY_AND_ASSIGN(ClientSocketHandle);
 189 };
 190
 191 // Template function implementation:
 192 template <typename SocketParams, typename PoolType>
 193 int ClientSocketHandle::Init(const std::string& group_name,
 194                              const scoped_refptr<SocketParams>& socket_params,
 195                              RequestPriority priority,
 196                              const CompletionCallback& callback,
 197                              PoolType* pool,
 198                              const BoundNetLog& net_log) {
 199   requesting_source_ = net_log.source();
 200
 201   CHECK(!group_name.empty());
 202   // Note that this will result in a compile error if the SocketParams has not
 203   // been registered for the PoolType via REGISTER_SOCKET_PARAMS_FOR_POOL
 204   // (defined in client_socket_pool.h).
 205   CheckIsValidSocketParamsForPool<PoolType, SocketParams>();
 206   ResetInternal(true);
 207   ResetErrorState();
 208   pool_ = pool;
 209   group_name_ = group_name;
 210   init_time_ = base::TimeTicks::Now();
 211   int rv = pool_->RequestSocket(
 212       group_name, &socket_params, priority, this, callback_, net_log);
 213   if (rv == ERR_IO_PENDING) {
 214     user_callback_ = callback;
 215   } else {
 216     HandleInitCompletion(rv);
 217   }
 218   return rv;
 219 }
 220
 221 }  // namespace net
 222
 223 #endif  // NET_SOCKET_CLIENT_SOCKET_HANDLE_H_