1// Copyright (c) 2010 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_H_
6#define NET_SOCKET_CLIENT_SOCKET_H_
7#pragma once
8
9#include "net/base/net_log.h"
10#include "net/socket/socket.h"
11
12namespace net {
13
14class AddressList;
15class IPEndPoint;
16
17class ClientSocket : public Socket {
18 public:
19  virtual ~ClientSocket() {}
20
21  // Called to establish a connection.  Returns OK if the connection could be
22  // established synchronously.  Otherwise, ERR_IO_PENDING is returned and the
23  // given callback will run asynchronously when the connection is established
24  // or when an error occurs.  The result is some other error code if the
25  // connection could not be established.
26  //
27  // The socket's Read and Write methods may not be called until Connect
28  // succeeds.
29  //
30  // It is valid to call Connect on an already connected socket, in which case
31  // OK is simply returned.
32  //
33  // Connect may also be called again after a call to the Disconnect method.
34  //
35  virtual int Connect(CompletionCallback* callback
36#ifdef ANDROID
37                      , bool wait_for_connect
38                      , bool valid_uid
39                      , uid_t calling_uid
40#endif
41                     ) = 0;
42
43  // Called to disconnect a socket.  Does nothing if the socket is already
44  // disconnected.  After calling Disconnect it is possible to call Connect
45  // again to establish a new connection.
46  //
47  // If IO (Connect, Read, or Write) is pending when the socket is
48  // disconnected, the pending IO is cancelled, and the completion callback
49  // will not be called.
50  virtual void Disconnect() = 0;
51
52  // Called to test if the connection is still alive.  Returns false if a
53  // connection wasn't established or the connection is dead.
54  virtual bool IsConnected() const = 0;
55
56  // Called to test if the connection is still alive and idle.  Returns false
57  // if a connection wasn't established, the connection is dead, or some data
58  // have been received.
59  virtual bool IsConnectedAndIdle() const = 0;
60
61  // Copies the peer address to |address| and returns a network error code.
62  // ERR_SOCKET_NOT_CONNECTED will be returned if the socket is not connected.
63  // TODO(sergeyu): Use IPEndPoint instead of AddressList.
64  virtual int GetPeerAddress(AddressList* address) const = 0;
65
66  // Copies the local address to |address| and returns a network error code.
67  // ERR_SOCKET_NOT_CONNECTED will be returned if the socket is not connected.
68  virtual int GetLocalAddress(IPEndPoint* address) const = 0;
69
70  // Gets the NetLog for this socket.
71  virtual const BoundNetLog& NetLog() const = 0;
72
73  // Set the annotation to indicate this socket was created for speculative
74  // reasons.  This call is generally forwarded to a basic TCPClientSocket*,
75  // where a UseHistory can be updated.
76  virtual void SetSubresourceSpeculation() = 0;
77  virtual void SetOmniboxSpeculation() = 0;
78
79  // Returns true if the underlying transport socket ever had any reads or
80  // writes.  ClientSockets layered on top of transport sockets should forward
81  // this call to the transport socket.
82  virtual bool WasEverUsed() const = 0;
83
84  // Returns true if the underlying transport socket is using TCP FastOpen.
85  // TCP FastOpen is an experiment with sending data in the TCP SYN packet.
86  virtual bool UsingTCPFastOpen() const = 0;
87
88 protected:
89  // The following class is only used to gather statistics about the history of
90  // a socket.  It is only instantiated and used in basic sockets, such as
91  // TCPClientSocket* instances.  Other classes that are derived from
92  // ClientSocket should forward any potential settings to their underlying
93  // transport sockets.
94  class UseHistory {
95   public:
96    UseHistory();
97    ~UseHistory();
98
99    // Resets the state of UseHistory and emits histograms for the
100    // current state.
101    void Reset();
102
103    void set_was_ever_connected();
104    void set_was_used_to_convey_data();
105
106    // The next two setters only have any impact if the socket has not yet been
107    // used to transmit data.  If called later, we assume that the socket was
108    // reused from the pool, and was NOT constructed to service a speculative
109    // request.
110    void set_subresource_speculation();
111    void set_omnibox_speculation();
112
113    bool was_used_to_convey_data() const;
114
115   private:
116    // Summarize the statistics for this socket.
117    void EmitPreconnectionHistograms() const;
118    // Indicate if this was ever connected.
119    bool was_ever_connected_;
120    // Indicate if this socket was ever used to transmit or receive data.
121    bool was_used_to_convey_data_;
122
123    // Indicate if this socket was first created for speculative use, and
124    // identify the motivation.
125    bool omnibox_speculation_;
126    bool subresource_speculation_;
127    DISALLOW_COPY_AND_ASSIGN(UseHistory);
128  };
129
130  // Logs a SOCKET_BYTES_RECEIVED or SOCKET_BYTES_SENT event to the NetLog.
131  // Determines whether to log the received bytes or not, based on the current
132  // logging level.
133  void LogByteTransfer(const BoundNetLog& net_log, NetLog::EventType event_type,
134                       int byte_count, char* bytes) const;
135};
136
137}  // namespace net
138
139#endif  // NET_SOCKET_CLIENT_SOCKET_H_
140