SFML - Simple and Fast Multimedia Library

SFML 3.0.1

- Main Page
- Topics
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Attributes | Protected Types | Protected Member Functions | Friends | List of all members
sf::TcpSocket Class Reference
Network module

Specialized socket using the TCP protocol. More...

`#include <SFML/Network/TcpSocket.hpp>`

Inheritance diagram for sf::TcpSocket:

## Public Types
enum class | Status { Done , NotReady , Partial , Disconnected , Error }
| Status codes that may be returned by socket functions. More...

## Public Member Functions
| TcpSocket ()
| Default constructor.
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.
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 ()
| 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:

// ----- The client -----
// Create a socket and connect it to 192.168.1.50 on port 55001
sf::TcpSocket socket;
socket.connect("192.168.1.50", 55001);
// Send a message to the connected host
std::string message = "Hi, I am a client";
socket.send(message.c_str(), message.size() + 1);
// Receive an answer from the server
std::array<char, 1024> buffer;
std::size_t received = 0;
socket.receive(buffer.data(), buffer.size(), received);
std::cout << "The server said: " << buffer.data() << std::endl;
// ----- The server -----
// Create a listener to wait for incoming connections on port 55001
sf::TcpListener listener;
listener.listen(55001);
// Wait for a connection
sf::TcpSocket socket;
listener.accept(socket);
std::cout << "New client connected: " << socket.getRemoteAddress().value() << std::endl;
// Receive a message from the client
std::array<char, 1024> buffer;
std::size_t received = 0;
socket.receive(buffer.data(), buffer.size(), received);
std::cout << "The client said: " << buffer.data() << std::endl;
// Send an answer
std::string message = "Welcome, client";
socket.send(message.c_str(), message.size() + 1);
sf::TcpListener
Socket that listens to new TCP connections.
Definition TcpListener.hpp:45
sf::TcpListener::listen
Status listen(unsigned short port, IpAddress address=IpAddress::Any)
Start listening for incoming connection attempts.
sf::TcpListener::accept
Status accept(TcpSocket &socket)
Accept a new connection.
sf::TcpSocket
Specialized socket using the TCP protocol.
Definition TcpSocket.hpp:54
sf::TcpSocket::getRemoteAddress
std::optional< IpAddress > getRemoteAddress() const
Get the address of the connected peer.
sf::TcpSocket::connect
Status connect(IpAddress remoteAddress, unsigned short remotePort, Time timeout=Time::Zero)
Connect the socket to a remote peer.
sf::TcpSocket::receive
Status receive(void *data, std::size_t size, std::size_t &received)
Receive raw data from the remote peer.
sf::TcpSocket::send
Status send(const void *data, std::size_t size)
Send raw data to the remote peer.

See also
  `sf::Socket`, `sf::UdpSocket`, `sf::Packet`

Definition at line 53 of file TcpSocket.hpp.

## Member Enumeration Documentation

## ◆ Status

enum class sf::Socket::Status
| stronginherited

Status codes that may be returned by socket functions.

Enumerator
Done | The socket has sent / received the data.
NotReady | The socket is not ready to send / receive data yet.
Partial | The socket sent a part of the data.
Disconnected | The TCP socket has been disconnected.
Error | An unexpected error happened.

Definition at line 48 of file Socket.hpp.

## ◆ Type

enum class sf::Socket::Type
| strongprotectedinherited

Types of protocols that the socket can use.

Enumerator
Tcp | TCP protocol.
Udp | UDP protocol.

Definition at line 128 of file Socket.hpp.

## Constructor & Destructor Documentation

## ◆ TcpSocket()

sf::TcpSocket::TcpSocket | ( |  | ) |

Default constructor.

## Member Function Documentation

## ◆ close()

void sf::Socket::close | ( |  | ) |
| protectedinherited

Close the socket gracefully.

This function can only be accessed by derived classes.

## ◆ connect()

Status sf::TcpSocket::connect | ( | IpAddress | remoteAddress,
|  | unsigned short | remotePort,
|  | Time | timeout = Time::Zero )
| 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]

void sf::Socket::create | ( |  | ) |
| protectedinherited

Create the internal representation of the socket.

This function can only be accessed by derived classes.

## ◆ create() [2/2]

void sf::Socket::create | ( | SocketHandle | handle | ) |
| 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`

## ◆ getLocalPort()

unsigned short sf::TcpSocket::getLocalPort | ( |  | ) | const
| 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()

SocketHandle sf::Socket::getNativeHandle | ( |  | ) | const
| 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()

std::optional< IpAddress > sf::TcpSocket::getRemoteAddress | ( |  | ) | const
| 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()

unsigned short sf::TcpSocket::getRemotePort | ( |  | ) | const
| 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()

bool sf::Socket::isBlocking | ( |  | ) | const
| nodiscardinherited

Tell whether the socket is in blocking or non-blocking mode.

Returns
  `true` if the socket is blocking, `false` otherwise

See also
  `setBlocking`

## ◆ receive() [1/2]

Status sf::TcpSocket::receive | ( | Packet & | packet | ) |
| nodiscard

Receive a formatted packet of data from the remote peer.

In blocking mode, this function will wait until the whole packet has been received. This function will fail if the socket is not connected.

Parameters

  packet | Packet to fill with the received data

Returns
  Status code

See also
  `send`

## ◆ receive() [2/2]

Status sf::TcpSocket::receive | ( | void * | data,
|  | std::size_t | size,
|  | std::size_t & | received )
| 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]

Status sf::TcpSocket::send | ( | const void * | data,
|  | std::size_t | size )
| 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]

Status sf::TcpSocket::send | ( | const void * | data,
|  | std::size_t | size,
|  | std::size_t & | sent )
| nodiscard

Send raw data to the remote peer.

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
  sent | The number of bytes sent will be written here

Returns
  Status code

See also
  `receive`

## ◆ send() [3/3]

Status sf::TcpSocket::send | ( | Packet & | packet | ) |
| nodiscard

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()

void sf::Socket::setBlocking | ( | bool | blocking | ) |
| 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`

## Friends And Related Symbol Documentation

## ◆ TcpListener

friend class TcpListener
| friend

Definition at line 218 of file TcpSocket.hpp.

## Member Data Documentation

## ◆ AnyPort

unsigned short sf::Socket::AnyPort {0}
| staticconstexprinherited

Some special values used by sockets.

Special value that tells the system to pick any available port

Definition at line 62 of file Socket.hpp.

The documentation for this class was generated from the following file:

- TcpSocket.hpp