___              _ _ ____
   /   |  __________(_|_) __ \____  _  ____  __
  / /| | / ___/ ___/ / / / / / __ \| |/_/ / / /
 / ___ |(__  ) /__/ / / /_/ / /_/ />  </ /_/ /
/_/  |_/____/\___/_/_/_____/\____/_/|_|\__, /
                                      /____/

[ Home | What is AsciiDoxy? | Getting started | Reference documentation | Examples | Contributing | Changelog | GitHub ]

C++

This is an example demonstrating documentation for a C++ project. The used source code files come from the SFML project.

This is not meant to be complete documentation. Some links in the documentation may not work due to missing documentation.
Doxygen configuration
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.

OUTPUT_DIRECTORY       = $(OUTPUT_DIR)

# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
# The default value is: YES.

GENERATE_HTML          = NO

# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
# The default value is: YES.

GENERATE_LATEX         = NO

# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that
# captures the structure of the code including all documentation.
# The default value is: NO.

GENERATE_XML           = YES
AsciiDoxy directives
${insert("sf::UdpSocket")}
${insert("sf::Packet")}
${insert("sf::IpAddress")}

UdpSocket

#include <UdpSocket.hpp>

class sf::UdpSocket

Specialized socket using the UDP protocol.

A UDP socket is a connectionless socket. Instead of connecting once to a remote host, like TCP sockets, it can send to and receive from any host at any time.

It is a datagram protocol: bounded blocks of data (datagrams) are transfered over the network rather than a continuous stream of data (TCP). Therefore, one call to send will always match one call to receive (if the datagram is not lost), with the same data that was sent.

The UDP protocol is lightweight but unreliable. Unreliable means that datagrams may be duplicated, be lost or arrive reordered. However, if a datagram arrives, its data is guaranteed to be valid.

UDP is generally used for real-time communication (audio or video streaming, real-time games, etc.) where speed is crucial and lost data doesn’t matter much.

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

It is important to note that UdpSocket is unable to send datagrams bigger than MaxDatagramSize. In this case, it returns an error and doesn’t send anything. This applies to both raw data and packets. Indeed, even packets are unable to split and recompose data, due to the unreliability of the protocol (dropped, mixed or duplicated datagrams may lead to a big mess when trying to recompose a packet).

If the socket is bound to a port, it is automatically unbound from it when the socket is destroyed. However, you can unbind the socket explicitly with the Unbind function if necessary, to stop receiving messages or make the port available for other sockets.

Usage example:

// ----- The client -----

// Create a socket and bind it to the port 55001
<<cpp-classsf_1_1UdpSocket,sf::UdpSocket>> socket;
socket.<<cpp-classsf_1_1UdpSocket_1ad764c3d06d90b4714dcc97a0d1647bcc,bind>>(55001);

// Send a message to 192.168.1.50 on port 55002
std::string message = "Hi, I am " + <<cpp-classsf_1_1IpAddress_1a4c31622ad87edca48adbb8e8ed00ee4a,sf::IpAddress::getLocalAddress>>().<<cpp-classsf_1_1IpAddress_1a88507954142d7fc2176cce7f36422340,toString>>();
socket.<<cpp-classsf_1_1UdpSocket_1a664ab8f26f37c21cc4de1b847c2efcca,send>>(message.c_str(), message.size() + 1, "192.168.1.50", 55002);

// Receive an answer (most likely from 192.168.1.50, but could be anyone else)
char buffer[1024];
std::size_t received = 0;
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> sender;
unsigned short port;
socket.<<cpp-classsf_1_1UdpSocket_1ade9ca0f7ed7919136917b0b997a9833a,receive>>(buffer, sizeof(buffer), received, sender, port);
std::cout << sender.ToString() << " said: " << buffer << std::endl;

// ----- The server -----

// Create a socket and bind it to the port 55002
<<cpp-classsf_1_1UdpSocket,sf::UdpSocket>> socket;
socket.<<cpp-classsf_1_1UdpSocket_1ad764c3d06d90b4714dcc97a0d1647bcc,bind>>(55002);

// Receive a message from anyone
char buffer[1024];
std::size_t received = 0;
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> sender;
unsigned short port;
socket.<<cpp-classsf_1_1UdpSocket_1ade9ca0f7ed7919136917b0b997a9833a,receive>>(buffer, sizeof(buffer), received, sender, port);
std::cout << sender.ToString() << " said: " << buffer << std::endl;

// Send an answer
std::string message = "Welcome " + sender.<<cpp-classsf_1_1IpAddress_1a88507954142d7fc2176cce7f36422340,toString>>();
socket.<<cpp-classsf_1_1UdpSocket_1a664ab8f26f37c21cc4de1b847c2efcca,send>>(message.c_str(), message.size() + 1, sender, port);
See

sf::Socket, sf::TcpSocket, sf::Packet

Public Enclosed Types
@0

Public Constructors
UdpSocket()

Default constructor.

Public Methods
unsigned short getLocalPort() const

Get the port to which the socket is bound locally.

Status bind(unsigned short, const IpAddress &)

Bind the socket to a specific port.

void unbind()

Unbind the socket from the local port to which it is bound.

Status send(const void *, std::size_t, const IpAddress &, unsigned short)

Send raw data to a remote peer.

Status receive(void *, std::size_t, std::size_t &, IpAddress &, unsigned short &)

Receive raw data from a remote peer.

Status send(Packet &, const IpAddress &, unsigned short)

Send a formatted packet of data to a remote peer.

Status receive(Packet &, IpAddress &, unsigned short &)

Receive a formatted packet of data from a remote peer.

@0

#include <UdpSocket.hpp>

enum sf::UdpSocket::@0

MaxDatagramSize = 65507

The maximum number of bytes that can be sent in a single UDP datagram.

Members

UdpSocket

UdpSocket()

Default constructor.

getLocalPort

unsigned short getLocalPort() const

Get the port to which the socket is bound locally.

If the socket is not bound to a port, this function returns 0.

See

bind

Returns
unsigned short

Port to which the socket is bound

bind

Status bind(unsigned short port,
            const IpAddress & address)

Bind the socket to a specific port.

Binding the socket to a port is necessary for being able to receive data on that port.

When providing sf::Socket::AnyPort as port, the listener will request an available port from the system. The chosen port can be retrieved by calling getLocalPort().

Since the socket can only be bound to a single port at any given moment, if it is already bound when this function is called, it will be unbound from the previous port before being bound to the new one.

See

unbind, getLocalPort

Parameters
unsigned short port

Port to bind the socket to

const IpAddress & address

Address of the interface to bind to

Returns
Status

Status code

unbind

void unbind()

Unbind the socket from the local port to which it is bound.

The port that the socket was previously bound to is immediately made available to the operating system after this function is called. This means that a subsequent call to bind() will be able to re-bind the port if no other process has done so in the mean time. If the socket is not bound to a port, this function has no effect.

See

bind

send

Status send(const void * data,
            std::size_t size,
            const IpAddress & remoteAddress,
            unsigned short remotePort)

Send raw data to a remote peer.

Make sure that size is not greater than UdpSocket::MaxDatagramSize, otherwise this function will fail and no data will be sent.

See

receive

Parameters
const void * data

Pointer to the sequence of bytes to send

std::size_t size

Number of bytes to send

const IpAddress & remoteAddress

Address of the receiver

unsigned short remotePort

Port of the receiver to send the data to

Returns
Status

Status code

receive

Status receive(void * data,
               std::size_t size,
               std::size_t & received,
               IpAddress & remoteAddress,
               unsigned short & remotePort)

Receive raw data from a remote peer.

In blocking mode, this function will wait until some bytes are actually received. Be careful to use a buffer which is large enough for the data that you intend to receive, if it is too small then an error will be returned and all the data will be lost.

See

send

Parameters
void * data

Pointer to the array to fill with the received bytes

std::size_t size

Maximum number of bytes that can be received

std::size_t & received

This variable is filled with the actual number of bytes received

IpAddress & remoteAddress

Address of the peer that sent the data

unsigned short & remotePort

Port of the peer that sent the data

Returns
Status

Status code

send

Status send(Packet & packet,
            const IpAddress & remoteAddress,
            unsigned short remotePort)

Send a formatted packet of data to a remote peer.

Make sure that the packet size is not greater than UdpSocket::MaxDatagramSize, otherwise this function will fail and no data will be sent.

See

receive

Parameters
Packet & packet

Packet to send

const IpAddress & remoteAddress

Address of the receiver

unsigned short remotePort

Port of the receiver to send the data to

Returns
Status

Status code

receive

Status receive(Packet & packet,
               IpAddress & remoteAddress,
               unsigned short & remotePort)

Receive a formatted packet of data from a remote peer.

In blocking mode, this function will wait until the whole packet has been received.

See

send

Parameters
Packet & packet

Packet to fill with the received data

IpAddress & remoteAddress

Address of the peer that sent the data

unsigned short & remotePort

Port of the peer that sent the data

Returns
Status

Status code

Packet

#include <Packet.hpp>

class sf::Packet

Utility class to build blocks of data to transfer over the network.

Packets provide a safe and easy way to serialize data, in order to send it over the network using sockets (sf::TcpSocket, sf::UdpSocket).

Packets solve 2 fundamental problems that arise when transferring data over the network:

  • data is interpreted correctly according to the endianness

  • the bounds of the packet are preserved (one send == one receive)

The sf::Packet class provides both input and output modes. It is designed to follow the behavior of standard C++ streams, using operators >> and << to extract and insert data.

It is recommended to use only fixed-size types (like sf::Int32, etc.), to avoid possible differences between the sender and the receiver. Indeed, the native C++ types may have different sizes on two platforms and your data may be corrupted if that happens.

Usage example:

sf::Uint32 x = 24;
std::string s = "hello";
double d = 5.89;

// Group the variables to send into a packet
<<cpp-classsf_1_1Packet,sf::Packet>> packet;
packet << x << s << d;

// Send it over the network (socket is a valid sf::TcpSocket)
socket.send(packet);

-----------------------------------------------------------------

// Receive the packet at the other end
<<cpp-classsf_1_1Packet,sf::Packet>> packet;
socket.receive(packet);

// Extract the variables contained in the packet
sf::Uint32 x;
std::string s;
double d;
if (packet >> x >> s >> d)
{
    // Data extracted successfully...
}

Packets have built-in operator >> and << overloads for standard types:

  • bool

  • fixed-size integer types (sf::Int8/16/32, sf::Uint8/16/32)

  • floating point numbers (float, double)

  • string types (char*, wchar_t*, std::string, std::wstring, sf::String)

Like standard streams, it is also possible to define your own overloads of operators >> and << in order to handle your custom types.

struct MyStruct
{
    float       number;
    sf::Int8    integer;
    std::string str;
};

<<cpp-classsf_1_1Packet,sf::Packet>>& <<cpp-classsf_1_1Packet_1ae02c874e0aac18a0497fca982a8f9083,operator <<>>(<<cpp-classsf_1_1Packet,sf::Packet>>& packet, const MyStruct& m)
{
    return packet << m.number << m.integer << m.str;
}

<<cpp-classsf_1_1Packet,sf::Packet>>& <<cpp-classsf_1_1Packet_1a8b6403506fec6b69f033278de33c8145,operator >>>>(<<cpp-classsf_1_1Packet,sf::Packet>>& packet, MyStruct& m)
{
    return packet >> m.number >> m.integer >> m.str;
}

Packets also provide an extra feature that allows to apply custom transformations to the data before it is sent, and after it is received. This is typically used to handle automatic compression or encryption of the data. This is achieved by inheriting from sf::Packet, and overriding the onSend and onReceive functions.

Here is an example:

class ZipPacket : public <<cpp-classsf_1_1Packet,sf::Packet>>
{
    virtual const void* <<cpp-classsf_1_1Packet_1af0003506bcb290407dcf5fe7f13a887d,onSend>>(std::size_t& size)
    {
        const void* srcData = <<cpp-classsf_1_1Packet_1a998b70df024bee4792e2ecdc915ae46e,getData>>();
        std::size_t srcSize = <<cpp-classsf_1_1Packet_1a0fae6eccf2ca704fc5099cd90a9f56f7,getDataSize>>();

        return MySuperZipFunction(srcData, srcSize, &size);
    }

    virtual void <<cpp-classsf_1_1Packet_1ab71a31ef0f1d5d856de6f9fc75434128,onReceive>>(const void* data, std::size_t size)
    {
        std::size_t dstSize;
        const void* dstData = MySuperUnzipFunction(data, size, &dstSize);

        <<cpp-classsf_1_1Packet_1a7dd6e429b87520008326c4d71f1cf011,append>>(dstData, dstSize);
    }
};

// Use like regular packets:
ZipPacket packet;
packet << x << s << d;
...
See

sf::TcpSocket, sf::UdpSocket

Public Constructors
Packet()

Default constructor.

Public Destructors
~Packet()

Virtual destructor.

Public Operators
operator>>(bool &)

Overload of operator >> to read data from the packet

operator>>(Int8 &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(Uint8 &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(Int16 &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(Uint16 &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(Int32 &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(Uint32 &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(Int64 &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(Uint64 &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(float &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(double &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(char *)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(std::string &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(wchar_t *)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(std::wstring &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator>>(String &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(bool)

Overload of operator << to write data into the packet

operator<<(Int8)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(Uint8)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(Int16)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(Uint16)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(Int32)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(Uint32)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(Int64)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(Uint64)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(float)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(double)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(const char *)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(const std::string &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(const wchar_t *)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(const std::wstring &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

operator<<(const String &)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Public Methods
void append(const void *, std::size_t)

Append data to the end of the packet.

std::size_t getReadPosition() const

Get the current reading position in the packet.

void clear()

Clear the packet.

const void * getData() const

Get a pointer to the data contained in the packet.

std::size_t getDataSize() const

Get the size of the data contained in the packet.

bool endOfPacket() const

Tell if the reading position has reached the end of the packet.

Protected Methods
const void * onSend(std::size_t &)

Called before the packet is sent over the network.

void onReceive(const void *, std::size_t)

Called after the packet is received over the network.

Members

Packet

Packet()

Default constructor.

Creates an empty packet.

~Packet

~Packet()

Virtual destructor.

operator>>

Packet & operator>>(bool & data)

Overload of operator >> to read data from the packet

Parameters
bool & data

Returns
Packet &

operator>>

Packet & operator>>(Int8 & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Int8 & data

Returns
Packet &

operator>>

Packet & operator>>(Uint8 & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Uint8 & data

Returns
Packet &

operator>>

Packet & operator>>(Int16 & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Int16 & data

Returns
Packet &

operator>>

Packet & operator>>(Uint16 & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Uint16 & data

Returns
Packet &

operator>>

Packet & operator>>(Int32 & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Int32 & data

Returns
Packet &

operator>>

Packet & operator>>(Uint32 & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Uint32 & data

Returns
Packet &

operator>>

Packet & operator>>(Int64 & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Int64 & data

Returns
Packet &

operator>>

Packet & operator>>(Uint64 & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Uint64 & data

Returns
Packet &

operator>>

Packet & operator>>(float & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
float & data

Returns
Packet &

operator>>

Packet & operator>>(double & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
double & data

Returns
Packet &

operator>>

Packet & operator>>(char * data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
char * data

Returns
Packet &

operator>>

Packet & operator>>(std::string & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
std::string & data

Returns
Packet &

operator>>

Packet & operator>>(wchar_t * data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
wchar_t * data

Returns
Packet &

operator>>

Packet & operator>>(std::wstring & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
std::wstring & data

Returns
Packet &

operator>>

Packet & operator>>(String & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
String & data

Returns
Packet &

operator<<

Packet & operator<<(bool data)

Overload of operator << to write data into the packet

Parameters
bool data

Returns
Packet &

operator<<

Packet & operator<<(Int8 data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Int8 data

Returns
Packet &

operator<<

Packet & operator<<(Uint8 data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Uint8 data

Returns
Packet &

operator<<

Packet & operator<<(Int16 data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Int16 data

Returns
Packet &

operator<<

Packet & operator<<(Uint16 data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Uint16 data

Returns
Packet &

operator<<

Packet & operator<<(Int32 data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Int32 data

Returns
Packet &

operator<<

Packet & operator<<(Uint32 data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Uint32 data

Returns
Packet &

operator<<

Packet & operator<<(Int64 data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Int64 data

Returns
Packet &

operator<<

Packet & operator<<(Uint64 data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
Uint64 data

Returns
Packet &

operator<<

Packet & operator<<(float data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
float data

Returns
Packet &

operator<<

Packet & operator<<(double data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
double data

Returns
Packet &

operator<<

Packet & operator<<(const char * data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
const char * data

Returns
Packet &

operator<<

Packet & operator<<(const std::string & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
const std::string & data

Returns
Packet &

operator<<

Packet & operator<<(const wchar_t * data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
const wchar_t * data

Returns
Packet &

operator<<

Packet & operator<<(const std::wstring & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
const std::wstring & data

Returns
Packet &

operator<<

Packet & operator<<(const String & data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
const String & data

Returns
Packet &

append

void append(const void * data,
            std::size_t sizeInBytes)

Append data to the end of the packet.

See

clear
See

getReadPosition

Parameters
const void * data

Pointer to the sequence of bytes to append

std::size_t sizeInBytes

Number of bytes to append

getReadPosition

std::size_t getReadPosition() const

Get the current reading position in the packet.

The next read operation will read data from this position

See

append

Returns
std::size_t

The byte offset of the current read position

clear

void clear()

Clear the packet.

After calling Clear, the packet is empty.

See

append

getData

const void * getData() const

Get a pointer to the data contained in the packet.

Warning: the returned pointer may become invalid after you append data to the packet, therefore it should never be stored. The return pointer is NULL if the packet is empty.

See

getDataSize

getDataSize

std::size_t getDataSize() const

Get the size of the data contained in the packet.

This function returns the number of bytes pointed to by what getData returns.

See

getData

Returns
std::size_t

Data size, in bytes

endOfPacket

bool endOfPacket() const

Tell if the reading position has reached the end of the packet.

This function is useful to know if there is some data left to be read, without actually reading it.

See

operator bool

Returns
bool

True if all data was read, false otherwise

onSend

const void * onSend(std::size_t & size)

Called before the packet is sent over the network.

This function can be defined by derived classes to transform the data before it is sent; this can be used for compression, encryption, etc. The function must return a pointer to the modified data, as well as the number of bytes pointed. The default implementation provides the packet’s data without transforming it.

See

onReceive

Parameters
std::size_t & size

Variable to fill with the size of data to send

onReceive

void onReceive(const void * data,
               std::size_t size)

Called after the packet is received over the network.

This function can be defined by derived classes to transform the data after it is received; this can be used for decompression, decryption, etc. The function receives a pointer to the received data, and must fill the packet with the transformed bytes. The default implementation fills the packet directly without transforming the data.

See

onSend

Parameters
const void * data

Pointer to the received bytes

std::size_t size

Number of bytes

IpAddress

#include <IpAddress.hpp>

class sf::IpAddress

Encapsulate an IPv4 network address.

sf::IpAddress is a utility class for manipulating network addresses. It provides a set a implicit constructors and conversion functions to easily build or transform an IP address from/to various representations.

Usage example:

<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a0;                                     // an invalid address
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a1 = <<cpp-classsf_1_1IpAddress_1a4619b4abbe3c8fef056e7299db967404,sf::IpAddress::None>>;               // an invalid address (same as a0)
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a2("127.0.0.1");                        // the local host address
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a3 = <<cpp-classsf_1_1IpAddress_1aa93d1d57b65d243f2baf804b6035465c,sf::IpAddress::Broadcast>>;          // the broadcast address
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a4(192, 168, 1, 56);                    // a local address
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a5("my_computer");                      // a local address created from a network name
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a6("89.54.1.169");                      // a distant address
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a7("www.google.com");                   // a distant address created from a network name
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a8 = <<cpp-classsf_1_1IpAddress_1a4c31622ad87edca48adbb8e8ed00ee4a,sf::IpAddress::getLocalAddress>>();  // my address on the local network
<<cpp-classsf_1_1IpAddress,sf::IpAddress>> a9 = <<cpp-classsf_1_1IpAddress_1a5c5cbf67e4aacf23c24f2ad991df4c55,sf::IpAddress::getPublicAddress>>(); // my address on the internet

Note that sf::IpAddress currently doesn’t support IPv6 nor other types of network addresses.

Public Constructors
IpAddress()

Default constructor.

IpAddress(const std::string &)

Construct the address from a string.

IpAddress(const char *)

Construct the address from a string.

IpAddress(Uint8, Uint8, Uint8, Uint8)

Construct the address from 4 bytes.

IpAddress(Uint32)

Construct the address from a 32-bits integer.

Public Variables
None

Value representing an empty/invalid address.

Any

Value representing any address (0.0.0.0)

LocalHost

The "localhost" address (for connecting a computer to itself locally)

Broadcast

The "broadcast" address (for sending UDP messages to everyone on a local network)

Public Static Methods
static IpAddress getLocalAddress()

Get the computer’s local address.

static IpAddress getPublicAddress(Time)

Get the computer’s public address.

Public Methods
std::string toString() const

Get a string representation of the address.

Uint32 toInteger() const

Get an integer representation of the address.

Members

IpAddress

IpAddress()

Default constructor.

This constructor creates an empty (invalid) address

IpAddress

IpAddress(const std::string & address)

Construct the address from a string.

Here address can be either a decimal address (ex: "192.168.1.56") or a network name (ex: "localhost").

Parameters
const std::string & address

IP address or network name

IpAddress

IpAddress(const char * address)

Construct the address from a string.

Here address can be either a decimal address (ex: "192.168.1.56") or a network name (ex: "localhost"). This is equivalent to the constructor taking a std::string parameter, it is defined for convenience so that the implicit conversions from literal strings to IpAddress work.

Parameters
const char * address

IP address or network name

IpAddress

IpAddress(Uint8 byte0,
          Uint8 byte1,
          Uint8 byte2,
          Uint8 byte3)

Construct the address from 4 bytes.

Calling IpAddress(a, b, c, d) is equivalent to calling IpAddress("a.b.c.d"), but safer as it doesn’t have to parse a string to get the address components.

Parameters
Uint8 byte0

First byte of the address

Uint8 byte1

Second byte of the address

Uint8 byte2

Third byte of the address

Uint8 byte3

Fourth byte of the address

IpAddress

IpAddress(Uint32 address)

Construct the address from a 32-bits integer.

This constructor uses the internal representation of the address directly. It should be used for optimization purposes, and only if you got that representation from IpAddress::toInteger().

See

toInteger

Parameters
Uint32 address

4 bytes of the address packed into a 32-bits integer

 
const IpAddress None

Value representing an empty/invalid address.

const IpAddress Any

Value representing any address (0.0.0.0)

const IpAddress LocalHost

The "localhost" address (for connecting a computer to itself locally)

const IpAddress Broadcast

The "broadcast" address (for sending UDP messages to everyone on a local network)

getLocalAddress

static IpAddress getLocalAddress()

Get the computer’s local address.

The local address is the address of the computer from the LAN point of view, i.e. something like 192.168.1.56. It is meaningful only for communications over the local network. Unlike getPublicAddress, this function is fast and may be used safely anywhere.

See

getPublicAddress

Returns
IpAddress

Local IP address of the computer

getPublicAddress

static IpAddress getPublicAddress(Time timeout = Time::Zero)

Get the computer’s public address.

The public address is the address of the computer from the internet point of view, i.e. something like 89.54.1.169. It is necessary for communications over the world wide web. The only way to get a public address is to ask it to a distant website; as a consequence, this function depends on both your network connection and the server, and may be very slow. You should use it as few as possible. Because this function depends on the network connection and on a distant server, you may use a time limit if you don’t want your program to be possibly stuck waiting in case there is a problem; this limit is deactivated by default.

See

getLocalAddress

Parameters
Time timeout

Maximum time to wait

Default value: Time::Zero

Returns
IpAddress

Public IP address of the computer

toString

std::string toString() const

Get a string representation of the address.

The returned string is the decimal representation of the IP address (like "192.168.1.56"), even if it was constructed from a host name.

See

toInteger

Returns
std::string

String representation of the address

toInteger

Uint32 toInteger() const

Get an integer representation of the address.

The returned number is the internal representation of the address, and should be used for optimization purposes only (like sending the address through a socket). The integer produced by this function can then be converted back to a sf::IpAddress with the proper constructor.

See

toString

Returns
Uint32

32-bits unsigned integer representation of the address
AsciiDoxy