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