1 // Copyright 2012 The Chromium Authors 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_STREAM_SOCKET_H_ 6 #define NET_SOCKET_STREAM_SOCKET_H_ 7 8 #include <stdint.h> 9 10 #include "base/functional/bind.h" 11 #include "net/base/net_errors.h" 12 #include "net/base/net_export.h" 13 #include "net/dns/public/resolve_error_info.h" 14 #include "net/socket/next_proto.h" 15 #include "net/socket/socket.h" 16 #include "third_party/abseil-cpp/absl/types/optional.h" 17 18 namespace net { 19 20 class IPEndPoint; 21 class NetLogWithSource; 22 class SSLCertRequestInfo; 23 class SSLInfo; 24 class SocketTag; 25 26 class NET_EXPORT StreamSocket : public Socket { 27 public: 28 using BeforeConnectCallback = base::RepeatingCallback<int()>; 29 30 ~StreamSocket() override = default; 31 32 // Sets a callback to be invoked before establishing a connection. This allows 33 // setting options, like receive and send buffer size, when they will take 34 // effect. The callback should return net::OK on success, and an error on 35 // failure. It must not return net::ERR_IO_PENDING. 36 // 37 // If multiple connection attempts are made, the callback will be invoked for 38 // each one. 39 virtual void SetBeforeConnectCallback( 40 const BeforeConnectCallback& before_connect_callback); 41 42 // Called to establish a connection. Returns OK if the connection could be 43 // established synchronously. Otherwise, ERR_IO_PENDING is returned and the 44 // given callback will run asynchronously when the connection is established 45 // or when an error occurs. The result is some other error code if the 46 // connection could not be established. 47 // 48 // The socket's Read and Write methods may not be called until Connect 49 // succeeds. 50 // 51 // It is valid to call Connect on an already connected socket, in which case 52 // OK is simply returned. 53 // 54 // Connect may also be called again after a call to the Disconnect method. 55 // 56 virtual int Connect(CompletionOnceCallback callback) = 0; 57 58 // Called to confirm the TLS handshake, if any, indicating that replay 59 // protection is ready. Returns OK if the handshake could complete 60 // synchronously or had already been confirmed. Otherwise, ERR_IO_PENDING is 61 // returned and the given callback will run asynchronously when the connection 62 // is established or when an error occurs. The result is some other error 63 // code if the connection could not be completed. 64 // 65 // This operation is only needed if TLS early data is enabled, in which case 66 // Connect returns early and Write initially sends early data, which does not 67 // have TLS's usual security properties. The caller must call this function 68 // and wait for handshake confirmation before sending data that is not 69 // replay-safe. 70 // 71 // ConfirmHandshake may run concurrently with Read or Write, but, as with Read 72 // and Write, at most one pending ConfirmHandshake operation may be in 73 // progress at a time. 74 virtual int ConfirmHandshake(CompletionOnceCallback callback); 75 76 // Called to disconnect a socket. Does nothing if the socket is already 77 // disconnected. After calling Disconnect it is possible to call Connect 78 // again to establish a new connection. 79 // 80 // If IO (Connect, Read, or Write) is pending when the socket is 81 // disconnected, the pending IO is cancelled, and the completion callback 82 // will not be called. 83 virtual void Disconnect() = 0; 84 85 // Called to test if the connection is still alive. Returns false if a 86 // connection wasn't established or the connection is dead. True is returned 87 // if the connection was terminated, but there is unread data in the incoming 88 // buffer. 89 virtual bool IsConnected() const = 0; 90 91 // Called to test if the connection is still alive and idle. Returns false 92 // if a connection wasn't established, the connection is dead, or there is 93 // unread data in the incoming buffer. 94 virtual bool IsConnectedAndIdle() const = 0; 95 96 // Copies the peer address to |address| and returns a network error code. 97 // ERR_SOCKET_NOT_CONNECTED will be returned if the socket is not connected. 98 virtual int GetPeerAddress(IPEndPoint* address) const = 0; 99 100 // Copies the local address to |address| and returns a network error code. 101 // ERR_SOCKET_NOT_CONNECTED will be returned if the socket is not bound. 102 virtual int GetLocalAddress(IPEndPoint* address) const = 0; 103 104 // Gets the NetLog for this socket. 105 virtual const NetLogWithSource& NetLog() const = 0; 106 107 // Returns true if the socket ever had any reads or writes. StreamSockets 108 // layered on top of transport sockets should return if their own Read() or 109 // Write() methods had been called, not the underlying transport's. 110 virtual bool WasEverUsed() const = 0; 111 112 // Returns true if ALPN was negotiated during the connection of this socket. 113 virtual bool WasAlpnNegotiated() const = 0; 114 115 // Returns the protocol negotiated via ALPN for this socket, or 116 // kProtoUnknown will be returned if ALPN is not applicable. 117 virtual NextProto GetNegotiatedProtocol() const = 0; 118 119 // Get data received from peer in ALPS TLS extension. 120 // Returns a (possibly empty) value if a TLS version supporting ALPS was used 121 // and ALPS was negotiated, nullopt otherwise. 122 virtual absl::optional<base::StringPiece> GetPeerApplicationSettings() const; 123 124 // Gets the SSL connection information of the socket. Returns false if 125 // SSL was not used by this socket. 126 virtual bool GetSSLInfo(SSLInfo* ssl_info) = 0; 127 128 // Gets the SSL CertificateRequest info of the socket after Connect failed 129 // with ERR_SSL_CLIENT_AUTH_CERT_NEEDED. Must not be called on a socket that 130 // does not support SSL. 131 virtual void GetSSLCertRequestInfo( 132 SSLCertRequestInfo* cert_request_info) const; 133 134 // Returns the total number of number bytes read by the socket. This only 135 // counts the payload bytes. Transport headers are not counted. Returns 136 // 0 if the socket does not implement the function. The count is reset when 137 // Disconnect() is called. 138 virtual int64_t GetTotalReceivedBytes() const = 0; 139 140 // Apply |tag| to this socket. If socket isn't yet connected, tag will be 141 // applied when socket is later connected. If Connect() fails or socket 142 // is closed, tag is cleared. If this socket is layered upon or wraps an 143 // underlying socket, |tag| will be applied to the underlying socket in the 144 // same manner as if ApplySocketTag() was called on the underlying socket. 145 // The tag can be applied at any time, in other words active sockets can be 146 // retagged with a different tag. Sockets wrapping multiplexed sockets 147 // (e.g. sockets who proxy through a QUIC or Spdy stream) cannot be tagged as 148 // the tag would inadvertently affect other streams; calling ApplySocketTag() 149 // in this case will result in CHECK(false). 150 virtual void ApplySocketTag(const SocketTag& tag) = 0; 151 }; 152 153 } // namespace net 154 155 #endif // NET_SOCKET_STREAM_SOCKET_H_ 156