Documentation of SFML 2.3.1

Warning: this page refers to an old version of SFML. Click here to switch to the latest version.
sf::TcpSocket Class Reference

Specialized socket using the TCP protocol. More...

#include <TcpSocket.hpp>

Inheritance diagram for sf::TcpSocket:
sf::Socket sf::NonCopyable

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. More...
 
unsigned short getLocalPort () const
 Get the port to which the socket is bound locally. More...
 
IpAddress getRemoteAddress () const
 Get the address of the connected peer. More...
 
unsigned short getRemotePort () const
 Get the port of the connected peer to which the socket is connected. More...
 
Status connect (const IpAddress &remoteAddress, unsigned short remotePort, Time timeout=Time::Zero)
 Connect the socket to a remote peer. More...
 
void disconnect ()
 Disconnect the socket from its remote peer. More...
 
Status send (const void *data, std::size_t size)
 Send raw data to the remote peer. More...
 
Status send (const void *data, std::size_t size, std::size_t &sent)
 Send raw data to the remote peer. More...
 
Status receive (void *data, std::size_t size, std::size_t &received)
 Receive raw data from the remote peer. More...
 
Status send (Packet &packet)
 Send a formatted packet of data to the remote peer. More...
 
Status receive (Packet &packet)
 Receive a formatted packet of data from the remote peer. More...
 
void setBlocking (bool blocking)
 Set the blocking state of the socket. More...
 
bool isBlocking () const
 Tell whether the socket is in blocking or non-blocking mode. More...
 

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. More...
 
void create ()
 Create the internal representation of the socket. More...
 
void create (SocketHandle handle)
 Create the internal representation of the socket from a socket handle. More...
 
void close ()
 Close the socket gracefully. More...
 

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
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
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
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.

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.

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

sf::TcpSocket::TcpSocket ( )

Default constructor.

Member Function Documentation

void sf::Socket::close ( )
protectedinherited

Close the socket gracefully.

This function can only be accessed by derived classes.

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 was previously connected, it is first disconnected.

Parameters
remoteAddressAddress of the remote peer
remotePortPort of the remote peer
timeoutOptional maximum time to wait
Returns
Status code
See also
disconnect
void sf::Socket::create ( )
protectedinherited

Create the internal representation of the socket.

This function can only be accessed by derived classes.

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
handleOS-specific handle of the socket to wrap
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
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
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
IpAddress sf::TcpSocket::getRemoteAddress ( ) const

Get the address of the connected peer.

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

Returns
Address of the remote peer
See also
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
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
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
dataPointer to the array to fill with the received bytes
sizeMaximum number of bytes that can be received
receivedThis variable is filled with the actual number of bytes received
Returns
Status code
See also
send
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
packetPacket to fill with the received data
Returns
Status code
See also
send
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
dataPointer to the sequence of bytes to send
sizeNumber of bytes to send
Returns
Status code
See also
receive
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
dataPointer to the sequence of bytes to send
sizeNumber of bytes to send
sentThe number of bytes sent will be written here
Returns
Status code
See also
receive
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
packetPacket to send
Returns
Status code
See also
receive
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
blockingTrue to set the socket as blocking, false for non-blocking
See also
isBlocking

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