sf::TcpSocket Class Reference
[Network module]

Specialized socket using the TCP protocol. More...

#include <TcpSocket.hpp>

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

List of all members.

Classes

struct  PendingPacket
 Structure holding the data of a pending packet.

Public Types

enum  Status {
  Done,
  NotReady,
  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, Uint32 timeout=0)
 Connect the socket to a remote peer.
void Disconnect ()
 Disconnect the socket from its remote peer.
Status Send (const char *data, std::size_t size)
 Send raw data to the remote peer.
Status Receive (char *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 explicitely 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 44 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 64 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.

Disconnected 

The TCP socket has been disconnected.

Error 

An unexpected error happened.

Definition at line 52 of file Socket.hpp.

enum sf::Socket::Type [protected, inherited]

Types of protocols that the socket can use.

Enumerator:
Tcp 

TCP protocol.

Udp 

UDP protocol.

Definition at line 112 of file Socket.hpp.


Constructor & Destructor Documentation

sf::TcpSocket::TcpSocket (  ) 

Default constructor.


Member Function Documentation

void sf::Socket::Close (  )  [protected, inherited]

Close the socket gracefully.

This function can only be accessed by derived classes.

Reimplemented in sf::TcpListener.

Status sf::TcpSocket::Connect ( const IpAddress remoteAddress,
unsigned short  remotePort,
Uint32  timeout = 0 
)

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:
remoteAddress Address of the remote peer
remotePort Port of the remote peer
timeout Optional maximum time to wait, in milliseconds
Returns:
Status code
See also:
Disconnect
void sf::Socket::Create ( SocketHandle  handle  )  [protected, inherited]

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
void sf::Socket::Create (  )  [protected, inherited]

Create the internal representation of the socket.

This function can only be accessed by derived classes.

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 [protected, inherited]

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 ( 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
Status sf::TcpSocket::Receive ( char *  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
Status sf::TcpSocket::Send ( Packet packet  ) 

Send a formatted packet of data to the remote peer.

This function will fail if the socket is not connected.

Parameters:
packet Packet to send
Returns:
Status code
See also:
Receive
Status sf::TcpSocket::Send ( const char *  data,
std::size_t  size 
)

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
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:
blocking True to set the socket as blocking, false for non-blocking
See also:
IsBlocking

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