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 <optional> 11 #include <string_view> 12 13 #include "base/functional/bind.h" 14 #include "base/notreached.h" 15 #include "net/base/net_errors.h" 16 #include "net/base/net_export.h" 17 #include "net/dns/public/resolve_error_info.h" 18 #include "net/socket/next_proto.h" 19 #include "net/socket/socket.h" 20 21 namespace net { 22 23 class IPEndPoint; 24 class NetLogWithSource; 25 class SSLCertRequestInfo; 26 class SSLInfo; 27 class SocketTag; 28 29 class NET_EXPORT StreamSocket : public Socket { 30 public: 31 using BeforeConnectCallback = base::RepeatingCallback<int()>; 32 33 ~StreamSocket() override = default; 34 35 // Sets a callback to be invoked before establishing a connection. This allows 36 // setting options, like receive and send buffer size, when they will take 37 // effect. The callback should return net::OK on success, and an error on 38 // failure. It must not return net::ERR_IO_PENDING. 39 // 40 // If multiple connection attempts are made, the callback will be invoked for 41 // each one. 42 virtual void SetBeforeConnectCallback( 43 const BeforeConnectCallback& before_connect_callback); 44 45 // Called to establish a connection. Returns OK if the connection could be 46 // established synchronously. Otherwise, ERR_IO_PENDING is returned and the 47 // given callback will run asynchronously when the connection is established 48 // or when an error occurs. The result is some other error code if the 49 // connection could not be established. 50 // 51 // The socket's Read and Write methods may not be called until Connect 52 // succeeds. 53 // 54 // It is valid to call Connect on an already connected socket, in which case 55 // OK is simply returned. 56 // 57 // Connect may also be called again after a call to the Disconnect method. 58 // 59 virtual int Connect(CompletionOnceCallback callback) = 0; 60 61 // Called to confirm the TLS handshake, if any, indicating that replay 62 // protection is ready. Returns OK if the handshake could complete 63 // synchronously or had already been confirmed. Otherwise, ERR_IO_PENDING is 64 // returned and the given callback will run asynchronously when the connection 65 // is established or when an error occurs. The result is some other error 66 // code if the connection could not be completed. 67 // 68 // This operation is only needed if TLS early data is enabled, in which case 69 // Connect returns early and Write initially sends early data, which does not 70 // have TLS's usual security properties. The caller must call this function 71 // and wait for handshake confirmation before sending data that is not 72 // replay-safe. 73 // 74 // ConfirmHandshake may run concurrently with Read or Write, but, as with Read 75 // and Write, at most one pending ConfirmHandshake operation may be in 76 // progress at a time. 77 virtual int ConfirmHandshake(CompletionOnceCallback callback); 78 79 // Called to disconnect a socket. Does nothing if the socket is already 80 // disconnected. After calling Disconnect it is possible to call Connect 81 // again to establish a new connection. 82 // 83 // If IO (Connect, Read, or Write) is pending when the socket is 84 // disconnected, the pending IO is cancelled, and the completion callback 85 // will not be called. 86 virtual void Disconnect() = 0; 87 88 // Called to test if the connection is still alive. Returns false if a 89 // connection wasn't established or the connection is dead. True is returned 90 // if the connection was terminated, but there is unread data in the incoming 91 // buffer. 92 virtual bool IsConnected() const = 0; 93 94 // Called to test if the connection is still alive and idle. Returns false 95 // if a connection wasn't established, the connection is dead, or there is 96 // unread data in the incoming buffer. 97 virtual bool IsConnectedAndIdle() const = 0; 98 99 // Copies the peer address to |address| and returns a network error code. 100 // ERR_SOCKET_NOT_CONNECTED will be returned if the socket is not connected. 101 virtual int GetPeerAddress(IPEndPoint* address) const = 0; 102 103 // Copies the local address to |address| and returns a network error code. 104 // ERR_SOCKET_NOT_CONNECTED will be returned if the socket is not bound. 105 virtual int GetLocalAddress(IPEndPoint* address) const = 0; 106 107 // Gets the NetLog for this socket. 108 virtual const NetLogWithSource& NetLog() const = 0; 109 110 // Returns true if the socket ever had any reads or writes. StreamSockets 111 // layered on top of transport sockets should return if their own Read() or 112 // Write() methods had been called, not the underlying transport's. 113 virtual bool WasEverUsed() 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 std::optional<std::string_view> 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 NOTREACHED(). 150 virtual void ApplySocketTag(const SocketTag& tag) = 0; 151 }; 152 153 } // namespace net 154 155 #endif // NET_SOCKET_STREAM_SOCKET_H_ 156