stream_socket.h 6.8 KB

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