Specialized socket using the TCP protocol. More...
#include <D:/private/SFML/SFML/include/SFML/Network/TcpSocket.hpp>
Public Types | |
| enum class | TlsStatus { NotConnected , HandshakeStarted , HandshakeComplete , Error } |
| TLS status codes that may be returned by TLS setup. More... | |
| enum class | Status { Done , NotReady , Partial , Disconnected , Error } |
| Status codes that may be returned by socket functions. More... | |
Public Member Functions | |
| TcpSocket () | |
| Default constructor. | |
| ~TcpSocket () override | |
| Destructor. | |
| TcpSocket (const TcpSocket &)=delete | |
| Deleted copy constructor. | |
| TcpSocket & | operator= (const TcpSocket &)=delete |
| Deleted copy assignment. | |
| TcpSocket (TcpSocket &&) noexcept | |
| Move constructor. | |
| TcpSocket & | operator= (TcpSocket &&) noexcept |
| Move assignment. | |
| unsigned short | getLocalPort () const |
| Get the port to which the socket is bound locally. | |
| std::optional< IpAddress > | getRemoteAddress () const |
| Get the address of the connected peer. | |
| unsigned short | getRemotePort () const |
| Get the port of the connected peer to which the socket is connected. | |
| Status | connect (IpAddress remoteAddress, unsigned short remotePort, Time timeout=Time::Zero) |
| Connect the socket to a remote peer. | |
| void | disconnect () |
| Disconnect the socket from its remote peer. | |
| TlsStatus | setupTlsClient (const sf::String &hostname, bool verifyPeer=true) |
| Set up transport layer security as a client. | |
| TlsStatus | setupTlsClient (const sf::String &hostname, const char *certificateChainData) |
| Set up transport layer security as a client. | |
| TlsStatus | setupTlsClient (const sf::String &hostname, const std::byte *certificateChainData, std::size_t certificateChainSize) |
| Set up transport layer security as a client. | |
| TlsStatus | setupTlsClient (const sf::String &hostname, std::string_view certificateChainData) |
| Set up transport layer security as a client. | |
| TlsStatus | setupTlsServer (const std::byte *certificateChainData, std::size_t certificateChainSize, const std::byte *privateKeyData, std::size_t privateKeySize, const std::byte *privateKeyPasswordData, std::size_t privateKeyPasswordSize) |
| Set up transport layer security as a server. | |
| TlsStatus | setupTlsServer (std::string_view certificateChainData, std::string_view privateKeyData, std::string_view privateKeyPasswordData={}) |
| Set up transport layer security as a server. | |
| std::optional< std::string > | getCurrentCiphersuiteName () const |
| Get the name of the TLS ciphersuite currently in use. | |
| Status | send (const void *data, std::size_t size) |
| Send raw data to the remote peer. | |
| Status | send (const void *data, std::size_t size, std::size_t &sent) |
| Send raw data to the remote peer. | |
| Status | receive (void *data, std::size_t size, std::size_t &received) |
| Receive raw data from the remote peer. | |
| Status | send (Packet &packet) |
| Send a formatted packet of data to the remote peer. | |
| Status | receive (Packet &packet) |
| Receive a formatted packet of data from the remote peer. | |
| void | setBlocking (bool blocking) |
| Set the blocking state of the socket. | |
| bool | isBlocking () const |
| Tell whether the socket is in blocking or non-blocking mode. | |
Static Public Attributes | |
| static constexpr unsigned short | AnyPort {0} |
| Some special values used by sockets. | |
Protected Types | |
| enum class | Type { Tcp , Udp } |
| Types of protocols that the socket can use. More... | |
Protected Member Functions | |
| SocketHandle | getNativeHandle () const |
| Return the internal handle of the socket. | |
| void | create (IpAddress::Type addressType=IpAddress::Type::IpV4) |
| Create the internal representation of the socket. | |
| void | create (SocketHandle handle) |
| Create the internal representation of the socket from a socket handle. | |
| void | close () |
| Close the socket gracefully. | |
Friends | |
| class | TcpListener |
Detailed Description
Specialized socket using the TCP protocol.
TCP is a connected protocol, which means that a TCP socket can only communicate with the host it is connected to.
It can't send or receive anything if it is not connected.
The TCP protocol is reliable but adds a slight overhead. It ensures that your data will always be received in order and without errors (no data corrupted, lost or duplicated).
When a socket is connected to a remote host, you can retrieve information about this host with the getRemoteAddress and getRemotePort functions. You can also get the local port to which the socket is bound (which is automatically chosen when the socket is connected), with the getLocalPort function.
Sending and receiving data can use either the low-level or the high-level functions. The low-level functions process a raw sequence of bytes, and cannot ensure that one call to Send will exactly match one call to Receive at the other end of the socket.
The high-level interface uses packets (see sf::Packet), which are easier to use and provide more safety regarding the data that is exchanged. You can look at the sf::Packet class to get more details about how they work.
The socket is automatically disconnected when it is destroyed, but if you want to explicitly close the connection while the socket instance is still alive, you can call disconnect.
Usage example:
- See also
- sf::Socket, sf::UdpSocket, sf::Packet
Definition at line 57 of file TcpSocket.hpp.
Member Enumeration Documentation
◆ Status
|
stronginherited |
Status codes that may be returned by socket functions.
Definition at line 49 of file Socket.hpp.
◆ TlsStatus
|
strong |
TLS status codes that may be returned by TLS setup.
Definition at line 64 of file TcpSocket.hpp.
◆ Type
|
strongprotectedinherited |
Types of protocols that the socket can use.
| Enumerator | |
|---|---|
| Tcp | TCP protocol. |
| Udp | UDP protocol. |
Definition at line 129 of file Socket.hpp.
Constructor & Destructor Documentation
◆ TcpSocket() [1/3]
| sf::TcpSocket::TcpSocket | ( | ) |
Default constructor.
◆ ~TcpSocket()
|
override |
Destructor.
◆ TcpSocket() [2/3]
|
delete |
Deleted copy constructor.
◆ TcpSocket() [3/3]
|
noexcept |
Move constructor.
Member Function Documentation
◆ close()
|
protectedinherited |
Close the socket gracefully.
This function can only be accessed by derived classes.
◆ connect()
|
nodiscard |
Connect the socket to a remote peer.
In blocking mode, this function may take a while, especially if the remote peer is not reachable. The last parameter allows you to stop trying to connect after a given timeout. If the socket is already connected, the connection is forcibly disconnected before attempting to connect again.
- Parameters
-
remoteAddress Address of the remote peer remotePort Port of the remote peer timeout Optional maximum time to wait
- Returns
- Status code
- See also
- disconnect
◆ create() [1/2]
|
protectedinherited |
Create the internal representation of the socket.
This function can only be accessed by derived classes.
- Parameters
-
addressType The address type of the socket
◆ create() [2/2]
|
protectedinherited |
Create the internal representation of the socket from a socket handle.
This function can only be accessed by derived classes.
- Parameters
-
handle OS-specific handle of the socket to wrap
◆ disconnect()
| void sf::TcpSocket::disconnect | ( | ) |
Disconnect the socket from its remote peer.
This function gracefully closes the connection. If the socket is not connected, this function has no effect.
- See also
- connect
◆ getCurrentCiphersuiteName()
|
nodiscard |
Get the name of the TLS ciphersuite currently in use.
- Returns
- TLS ciphersuite currently in use or std::nullopt if TLS is not set up
- See also
- setupTlsClient, setupTlsServer
◆ getLocalPort()
|
nodiscard |
Get the port to which the socket is bound locally.
If the socket is not connected, this function returns 0.
- Returns
- Port to which the socket is bound
- See also
- connect, getRemotePort
◆ getNativeHandle()
|
nodiscardprotectedinherited |
Return the internal handle of the socket.
The returned handle may be invalid if the socket was not created yet (or already destroyed). This function can only be accessed by derived classes.
- Returns
- The internal (OS-specific) handle of the socket
◆ getRemoteAddress()
|
nodiscard |
Get the address of the connected peer.
If the socket is not connected, this function returns an unset optional.
- Returns
- Address of the remote peer
- See also
- getRemotePort
◆ getRemotePort()
|
nodiscard |
Get the port of the connected peer to which the socket is connected.
If the socket is not connected, this function returns 0.
- Returns
- Remote port to which the socket is connected
- See also
- getRemoteAddress
◆ isBlocking()
|
nodiscardinherited |
Tell whether the socket is in blocking or non-blocking mode.
- Returns
- true if the socket is blocking, false otherwise
- See also
- setBlocking
◆ operator=() [1/2]
◆ operator=() [2/2]
◆ receive() [1/2]
◆ receive() [2/2]
|
nodiscard |
Receive raw data from the remote peer.
In blocking mode, this function will wait until some bytes are actually received. This function will fail if the socket is not connected.
- Parameters
-
data Pointer to the array to fill with the received bytes size Maximum number of bytes that can be received received This variable is filled with the actual number of bytes received
- Returns
- Status code
- See also
- send
◆ send() [1/3]
|
nodiscard |
Send raw data to the remote peer.
To be able to handle partial sends over non-blocking sockets, use the send(const void*, std::size_t, std::size_t&) overload instead. This function will fail if the socket is not connected.
- Parameters
-
data Pointer to the sequence of bytes to send size Number of bytes to send
- Returns
- Status code
- See also
- receive
◆ send() [2/3]
|
nodiscard |
◆ send() [3/3]
Send a formatted packet of data to the remote peer.
In non-blocking mode, if this function returns sf::Socket::Status::Partial, you must retry sending the same unmodified packet before sending anything else in order to guarantee the packet arrives at the remote peer uncorrupted. This function will fail if the socket is not connected.
- Parameters
-
packet Packet to send
- Returns
- Status code
- See also
- receive
◆ setBlocking()
|
inherited |
Set the blocking state of the socket.
In blocking mode, calls will not return until they have completed their task. For example, a call to Receive in blocking mode won't return until some data was actually received. In non-blocking mode, calls will always return immediately, using the return code to signal whether there was data available or not. By default, all sockets are blocking.
- Parameters
-
blocking true to set the socket as blocking, false for non-blocking
- See also
- isBlocking
◆ setupTlsClient() [1/4]
| TlsStatus sf::TcpSocket::setupTlsClient | ( | const sf::String & | hostname, |
| bool | verifyPeer = true ) |
Set up transport layer security as a client.
Once the TCP connection is connected, transport layer security can be set up.
All the necessary cryptographic initialization will be performed when this function is called.
If this function is called before the TCP connection is connected, it will return TlsStatus::NotConnected and must be called again once the TCP connection is connected.
If this function started TLS setup but could not finish it within this call e.g. because this socket was set to non-blocking, it will return TlsStatus::HandshakeStarted and this function will have to be called repeatedly until TlsStatus::HandshakeComplete is returned. If this socket is blocking, TlsStatus::HandshakeComplete should be returned within the same function call if TLS setup was successful.
If TlsStatus::Error is returned, something went wrong with TLS setup and the connection must be reconnected and TLS setup reattempted after it is connected again.
If verification is enabled, this function verifies the peer using the system provided certificate store. If the peer does not have a certificate that was signed by a certificate authority i.e. a self-signed certificate, the entire certificate chain can be provided using the alternative overload.
Servers that host multiple services under different names need to know which of those services we want to connect to in order to reply with the correct certificate chain. Server name indication (SNI) is used for this purpose. The hostname provided to this function is sent to the server if it supports SNI in order for it to return the corresponding certificate chain. The hostname is then used to verify the certificate chain that was returned by the server. If the server does not support SNI or only serves a single certificate chain, the hostname will only be used for verification.
- Parameters
-
hostname Hostname of the remote peer, used for verification verifyPeer true to enable peer verification, false to disable it
- Returns
- TLS status code
- See also
- setupTlsServer
◆ setupTlsClient() [2/4]
| TlsStatus sf::TcpSocket::setupTlsClient | ( | const sf::String & | hostname, |
| const char * | certificateChainData ) |
Set up transport layer security as a client.
Once the TCP connection is connected, transport layer security can be set up.
All the necessary cryptographic initialization will be performed when this function is called.
If this function is called before the TCP connection is connected, it will return TlsStatus::NotConnected and must be called again once the TCP connection is connected.
If this function started TLS setup but could not finish it within this call e.g. because this socket was set to non-blocking, it will return TlsStatus::HandshakeStarted and this function will have to be called repeatedly until TlsStatus::HandshakeComplete is returned. If this socket is blocking, TlsStatus::HandshakeComplete should be returned within the same function call if TLS setup was successful.
If TlsStatus::Error is returned, something went wrong with TLS setup and the connection must be reconnected and TLS setup reattempted after it is connected again.
Servers that host multiple services under different names need to know which of those services we want to connect to in order to reply with the correct certificate chain. Server name indication (SNI) is used for this purpose. The hostname provided to this function is sent to the server if it supports SNI in order for it to return the corresponding certificate chain. The hostname is then used to verify the certificate chain that was returned by the server. If the server does not support SNI or only serves a single certificate chain, the hostname will only be used for verification.
When calling this overload, the certificate chain to verify the host with has to be provided. Verification is always enabled when calling this overload.
The certificate data should be provided in PEM format.
This overload is provided to prevent a const char* argument resulting in the bool verifyPeer overload being called instead of the std::string_view overload.
- Parameters
-
hostname Hostname of the remote peer, used for verification certificateChainData Null terminated string containing certificate chain data in PEM encoding
- Returns
- TLS status code
- See also
- setupTlsServer
◆ setupTlsClient() [3/4]
| TlsStatus sf::TcpSocket::setupTlsClient | ( | const sf::String & | hostname, |
| const std::byte * | certificateChainData, | ||
| std::size_t | certificateChainSize ) |
Set up transport layer security as a client.
Once the TCP connection is connected, transport layer security can be set up.
All the necessary cryptographic initialization will be performed when this function is called.
If this function is called before the TCP connection is connected, it will return TlsStatus::NotConnected and must be called again once the TCP connection is connected.
If this function started TLS setup but could not finish it within this call e.g. because this socket was set to non-blocking, it will return TlsStatus::HandshakeStarted and this function will have to be called repeatedly until TlsStatus::HandshakeComplete is returned. If this socket is blocking, TlsStatus::HandshakeComplete should be returned within the same function call if TLS setup was successful.
If TlsStatus::Error is returned, something went wrong with TLS setup and the connection must be reconnected and TLS setup reattempted after it is connected again.
Servers that host multiple services under different names need to know which of those services we want to connect to in order to reply with the correct certificate chain. Server name indication (SNI) is used for this purpose. The hostname provided to this function is sent to the server if it supports SNI in order for it to return the corresponding certificate chain. The hostname is then used to verify the certificate chain that was returned by the server. If the server does not support SNI or only serves a single certificate chain, the hostname will only be used for verification.
When calling this overload, the certificate chain to verify the host with has to be provided. Verification is always enabled when calling this overload.
The certificate data can be provided in PEM or DER format.
- Parameters
-
hostname Hostname of the remote peer, used for verification certificateChainData Certificate chain data in PEM or DER encoding certificateChainSize Size of the certificate chain data
- Returns
- TLS status code
- See also
- setupTlsServer
◆ setupTlsClient() [4/4]
| TlsStatus sf::TcpSocket::setupTlsClient | ( | const sf::String & | hostname, |
| std::string_view | certificateChainData ) |
Set up transport layer security as a client.
Once the TCP connection is connected, transport layer security can be set up.
All the necessary cryptographic initialization will be performed when this function is called.
If this function is called before the TCP connection is connected, it will return TlsStatus::NotConnected and must be called again once the TCP connection is connected.
If this function started TLS setup but could not finish it within this call e.g. because this socket was set to non-blocking, it will return TlsStatus::HandshakeStarted and this function will have to be called repeatedly until TlsStatus::HandshakeComplete is returned. If this socket is blocking, TlsStatus::HandshakeComplete should be returned within the same function call if TLS setup was successful.
If TlsStatus::Error is returned, something went wrong with TLS setup and the connection must be reconnected and TLS setup reattempted after it is connected again.
Servers that host multiple services under different names need to know which of those services we want to connect to in order to reply with the correct certificate chain. Server name indication (SNI) is used for this purpose. The hostname provided to this function is sent to the server if it supports SNI in order for it to return the corresponding certificate chain. The hostname is then used to verify the certificate chain that was returned by the server. If the server does not support SNI or only serves a single certificate chain, the hostname will only be used for verification.
When calling this overload, the certificate chain to verify the host with has to be provided. Verification is always enabled when calling this overload.
The certificate data should be provided in PEM format.
- Parameters
-
hostname Hostname of the remote peer, used for verification certificateChainData Certificate chain data in PEM encoding
- Returns
- TLS status code
- See also
- setupTlsServer
◆ setupTlsServer() [1/2]
| TlsStatus sf::TcpSocket::setupTlsServer | ( | const std::byte * | certificateChainData, |
| std::size_t | certificateChainSize, | ||
| const std::byte * | privateKeyData, | ||
| std::size_t | privateKeySize, | ||
| const std::byte * | privateKeyPasswordData, | ||
| std::size_t | privateKeyPasswordSize ) |
Set up transport layer security as a server.
Once the TCP connection is connected, transport layer security can be set up.
All the necessary cryptographic initialization will be performed when this function is called.
If this function is called before the TCP connection is connected, it will return TlsStatus::NotConnected and must be called again once the TCP connection is connected.
If this function started TLS setup but could not finish it within this call e.g. because this socket was set to non-blocking, it will return TlsStatus::HandshakeStarted and this function will have to be called repeatedly until TlsStatus::HandshakeComplete is returned. If this socket is blocking, TlsStatus::HandshakeComplete should be returned within the same function call if TLS setup was successful.
If TlsStatus::Error is returned, something went wrong with TLS setup and the connection must be disconnected. The client must reconnect and reattempt TLS setup again.
As a server, a certificate chain as well as a private key must be provided.
The certificate and private key data can be provided in PEM or DER format.
If the private key is secured by a password, the password must be provided.
- Parameters
-
certificateChainData Certificate chain data in PEM or DER encoding certificateChainSize Size of the certificate chain data privateKeyData Private key data in PEM or DER encoding privateKeySize Size of the private key data privateKeyPasswordData Private key password data privateKeyPasswordSize Size of the private key password data
- Returns
- TLS status code
- See also
- setupTlsClient
◆ setupTlsServer() [2/2]
| TlsStatus sf::TcpSocket::setupTlsServer | ( | std::string_view | certificateChainData, |
| std::string_view | privateKeyData, | ||
| std::string_view | privateKeyPasswordData = {} ) |
Set up transport layer security as a server.
Once the TCP connection is connected, transport layer security can be set up.
All the necessary cryptographic initialization will be performed when this function is called.
If this function is called before the TCP connection is connected, it will return TlsStatus::NotConnected and must be called again once the TCP connection is connected.
If this function started TLS setup but could not finish it within this call e.g. because this socket was set to non-blocking, it will return TlsStatus::HandshakeStarted and this function will have to be called repeatedly until TlsStatus::HandshakeComplete is returned. If this socket is blocking, TlsStatus::HandshakeComplete should be returned within the same function call if TLS setup was successful.
If TlsStatus::Error is returned, something went wrong with TLS setup and the connection must be disconnected. The client must reconnect and reattempt TLS setup again.
As a server, a certificate chain as well as a private key must be provided.
The certificate and private key data should be provided in PEM format.
If the private key is secured by a password, the password must be provided.
- Parameters
-
certificateChainData Certificate chain data in PEM encoding privateKeyData Private key data in PEM encoding privateKeyPasswordData Private key password if required
- Returns
- TLS status code
- See also
- setupTlsClient
Friends And Related Symbol Documentation
◆ TcpListener
|
friend |
Definition at line 597 of file TcpSocket.hpp.
Member Data Documentation
◆ AnyPort
|
staticconstexprinherited |
Some special values used by sockets.
Special value that tells the system to pick any available port
Definition at line 63 of file Socket.hpp.
The documentation for this class was generated from the following file: