Documentation of SFML 2.1

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

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

#include <Packet.hpp>

Public Member Functions

 Packet ()
 Default constructor.
 
virtual ~Packet ()
 Virtual destructor.
 
void append (const void *data, std::size_t sizeInBytes)
 Append data to the end of 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.
 
 operator BoolType () const
 Test the validity of the packet, for reading.
 
Packetoperator>> (bool &data)
 Overloads of operator >> to read data from the packet.
 
Packetoperator>> (Int8 &data)
 
Packetoperator>> (Uint8 &data)
 
Packetoperator>> (Int16 &data)
 
Packetoperator>> (Uint16 &data)
 
Packetoperator>> (Int32 &data)
 
Packetoperator>> (Uint32 &data)
 
Packetoperator>> (float &data)
 
Packetoperator>> (double &data)
 
Packetoperator>> (char *data)
 
Packetoperator>> (std::string &data)
 
Packetoperator>> (wchar_t *data)
 
Packetoperator>> (std::wstring &data)
 
Packetoperator>> (String &data)
 
Packetoperator<< (bool data)
 Overloads of operator << to write data into the packet.
 
Packetoperator<< (Int8 data)
 
Packetoperator<< (Uint8 data)
 
Packetoperator<< (Int16 data)
 
Packetoperator<< (Uint16 data)
 
Packetoperator<< (Int32 data)
 
Packetoperator<< (Uint32 data)
 
Packetoperator<< (float data)
 
Packetoperator<< (double data)
 
Packetoperator<< (const char *data)
 
Packetoperator<< (const std::string &data)
 
Packetoperator<< (const wchar_t *data)
 
Packetoperator<< (const std::wstring &data)
 
Packetoperator<< (const String &data)
 

Protected Member Functions

virtual const void * onSend (std::size_t &size)
 Called before the packet is sent over the network.
 
virtual void onReceive (const void *data, std::size_t size)
 Called after the packet is received over the network.
 

Friends

class TcpSocket
 
class UdpSocket
 

Detailed Description

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 transfering 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 behaviour 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
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
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;
};
sf::Packet& operator <<(sf::Packet& packet, const MyStruct& m)
{
return packet << m.number << m.integer << m.str;
}
sf::Packet& operator >>(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 sf::Packet
{
virtual const void* onSend(std::size_t& size)
{
const void* srcData = getData();
std::size_t srcSize = getDataSize();
return MySuperZipFunction(srcData, srcSize, &size);
}
virtual void onReceive(const void* data, std::size_t size)
{
std::size_t dstSize;
const void* dstData = MySuperUnzipFunction(data, size, &dstSize);
append(dstData, dstSize);
}
};
// Use like regular packets:
ZipPacket packet;
packet << x << s << d;
...
See Also
sf::TcpSocket, sf::UdpSocket

Definition at line 47 of file Packet.hpp.

Constructor & Destructor Documentation

sf::Packet::Packet ( )

Default constructor.

Creates an empty packet.

virtual sf::Packet::~Packet ( )
virtual

Virtual destructor.

Member Function Documentation

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

Append data to the end of the packet.

Parameters
dataPointer to the sequence of bytes to append
sizeInBytesNumber of bytes to append
See Also
clear
void sf::Packet::clear ( )

Clear the packet.

After calling Clear, the packet is empty.

See Also
append
bool sf::Packet::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.

Returns
True if all data was read, false otherwise
See Also
operator bool
const void* sf::Packet::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.

Returns
Pointer to the data
See Also
getDataSize
std::size_t sf::Packet::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.

Returns
Data size, in bytes
See Also
getData
virtual void sf::Packet::onReceive ( const void *  data,
std::size_t  size 
)
protectedvirtual

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

Parameters
dataPointer to the received bytes
sizeNumber of bytes
See Also
onSend
virtual const void* sf::Packet::onSend ( std::size_t &  size)
protectedvirtual

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.

Parameters
sizeVariable to fill with the size of data to send
Returns
Pointer to the array of bytes to send
See Also
onReceive
sf::Packet::operator BoolType ( ) const

Test the validity of the packet, for reading.

This operator allows to test the packet as a boolean variable, to check if a reading operation was successful.

A packet will be in an invalid state if it has no more data to read.

This behaviour is the same as standard C++ streams.

Usage example:

float x;
packet >> x;
if (packet)
{
// ok, x was extracted successfully
}
// -- or --
float x;
if (packet >> x)
{
// ok, x was extracted successfully
}

Don't focus on the return type, it's equivalent to bool but it disallows unwanted implicit conversions to integer or pointer types.

Returns
True if last data extraction from packet was successful
See Also
endOfPacket
Packet& sf::Packet::operator<< ( bool  data)

Overloads of operator << to write data into the packet.

Packet& sf::Packet::operator>> ( bool &  data)

Overloads of operator >> to read data from the packet.


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