sf::TcpSocket Class Reference

Specialized socket using the TCP protocol. More...

#include <SFML/Network/TcpSocket.hpp>

Inheritance diagram for sf::TcpSocket:

Public Types
enum	Status {   Done , NotReady , Partial , Disconnected ,   Error }
	Status codes that may be returned by socket functions. More...
enum	{ AnyPort = 0 }
	Some special values used by sockets. More...

Public Member Functions
	TcpSocket ()
	Default constructor.
unsigned short	getLocalPort () const
	Get the port to which the socket is bound locally.
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 (const 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.

Protected Types
enum	Type { Tcp , Udp }
	Types of protocols that the socket can use. More...

Protected Member Functions
SocketHandle	getHandle () 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 informations 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
char buffer[1024];
std::size_t received = 0;
socket.receive(buffer, sizeof(buffer), received);
std::cout << "The server said: " << buffer << 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() << std::endl;
 
// Receive a message from the client
char buffer[1024];
std::size_t received = 0;
socket.receive(buffer, sizeof(buffer), received);
std::cout << "The client said: " << buffer << std::endl;
 
// Send an answer
std::string message = "Welcome, client";
socket.send(message.c_str(), message.size() + 1);

See also

sf::Socket, sf::UdpSocket, sf::Packet

Definition at line 46 of file TcpSocket.hpp.

Member Enumeration Documentation

anonymous enum

anonymous enum

inherited

Some special values used by sockets.

Enumerator
AnyPort	Special value that tells the system to pick any available port.

Definition at line 66 of file Socket.hpp.

Status

enum sf::Socket::Status

inherited

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 53 of file Socket.hpp.

Type

enum sf::Socket::Type

protectedinherited

Types of protocols that the socket can use.

Enumerator
Tcp	TCP protocol.
Udp	UDP protocol.

Definition at line 114 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	(	const IpAddress &	remoteAddress,
		unsigned short	remotePort,
		Time	timeout = Time::Zero
	)

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

getHandle()

SocketHandle sf::Socket::getHandle ( ) const

protectedinherited

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

getLocalPort()

unsigned short sf::TcpSocket::getLocalPort

(

)

const

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

getRemoteAddress()

IpAddress sf::TcpSocket::getRemoteAddress

(

)

const

Get the address of the connected peer.

If the socket is not connected, this function returns sf::IpAddress::None.

Returns

Address of the remote peer

See also

getRemotePort

getRemotePort()

unsigned short sf::TcpSocket::getRemotePort

(

)

const

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

inherited

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

)

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
	)

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
	)

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
	)

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

)

Send a formatted packet of data to the remote peer.

In non-blocking mode, if this function returns sf::Socket::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 Function Documentation

TcpListener

friend class TcpListener

friend

Definition at line 213 of file TcpSocket.hpp.

---

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

• TcpSocket.hpp