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