Ocean::Network::PackagedSocket Class Reference

This class is the base class for all packaged sockets. More...

#include <PackagedSocket.h>

Inheritance diagram for Ocean::Network::PackagedSocket:

Data Structures
class	MemoryBlock
	This class implements a memory block. More...
class	PackageHeader
	This class implements the header of a packaged stream message. More...

Public Types
using	MessageId = uint32_t
	Definition of a message id.
Public Types inherited from Ocean::Network::Socket
enum	SocketResult { SR_SUCCEEDED = 0 , SR_FAILED , SR_BUSY , SR_NOT_CONNECTED }
	Definition of individual result values. More...
using	SocketId = SOCKET
	Definition of a socket id.
using	SocketId = int
	Definition of a socket id.
using	Buffer = std::vector< uint8_t >
	Definition of a vector holding 8 bit values.

Static Public Member Functions
static constexpr MessageId	invalidMessageId ()
	Returns an invalid message id.
static constexpr size_t	packageManagmentHeaderSize ()
	Returns the size of the package management header in bytes.
static constexpr size_t	maximalPackagedMessageSize ()
	Returns the maximal size of a packaged message.
Static Public Member Functions inherited from Ocean::Network::Socket
static constexpr SocketId	invalidSocketId ()
	Returns an invalid socket id.
static bool	setBlockingMode (const SocketId socketId, const bool blocking)
	Sets the blocking mode of a socket.

Protected Types
using	MemoryBlockQueue = std::queue< MemoryBlock >
	Definition of a queue holding memory blocks.

Protected Member Functions
	PackagedSocket ()
	Creates a new packaged socket.
Protected Member Functions inherited from Ocean::Network::Socket
	Socket ()
	Creates a new socket object.
	Socket (const Socket &object)=delete
	Disabled copy constructor.
bool	setBlockingMode (const bool blocking)
	Sets the blocking mode of this socket.
size_t	maximalMessageSize (const size_t defaultSize=65536)
	Returns the maximal message size in bytes.
bool	releaseSocket ()
	Releases the socket.
virtual bool	onScheduler ()
	The scheduler event function.
Socket &	operator= (const Socket &object)=delete
	Disabled copy operator.

Static Protected Member Functions
static bool	extractNextPackage (MemoryBlockQueue &sourceQueue, MemoryBlock &targetMemory)
	Extracts a memory block from a queue with memory block.

Additional Inherited Members
Public Member Functions inherited from Ocean::Network::Socket
virtual	~Socket ()
	Destructs a socket object.
SocketId	id () const
	Returns the socket id.
Address4	address () const
	Returns the own address of this socket.
Port	port () const
	Returns the own port of this socket.
virtual bool	setAddress (const Address4 &address)
	Sets the own address of this socket.
virtual bool	setPort (const Port &port)
	Sets the own port of this socket.
	operator bool () const
	Returns whether this socket is valid.
Protected Attributes inherited from Ocean::Network::Socket
SocketId	socketId_ = invalidSocketId()
	Socket id.
Lock	lock_
	Socket lock.
NetworkResource	networkResource_
	The network resource object.

Detailed Description

This class is the base class for all packaged sockets.

Packaged sockets add a framing layer on top of the raw socket, so that a message survives being split or merged in transit. Two independent and mutually incompatible formats exist, both defined here:

• the stream oriented PackageHeader, used by PackagedTCPClient and PackagedTCPServer
• the datagram oriented package management header, used by PackagedConnectionlessClient and PackagedConnectionlessServer, see packageManagmentHeaderSize()

Member Typedef Documentation

MemoryBlockQueue

using Ocean::Network::PackagedSocket::MemoryBlockQueue = std::queue<MemoryBlock>

protected

Definition of a queue holding memory blocks.

MessageId

using Ocean::Network::PackagedSocket::MessageId = uint32_t

Definition of a message id.

Constructor & Destructor Documentation

PackagedSocket()

Ocean::Network::PackagedSocket::PackagedSocket ( )

protected

Creates a new packaged socket.

Member Function Documentation

extractNextPackage()

static bool Ocean::Network::PackagedSocket::extractNextPackage ( MemoryBlockQueue &  sourceQueue, MemoryBlock &  targetMemory  )

staticprotected

Extracts a memory block from a queue with memory block.

Parameters

sourceQueue	The queue from which the memory will be extracted
targetMemory	The target memory block to be filled, must be valid, must have remaining bytes

Returns

True, if the target memory block has been filled and no byte is remaining anymore

invalidMessageId()

constexpr PackagedSocket::MessageId Ocean::Network::PackagedSocket::invalidMessageId ( )

staticconstexpr

Returns an invalid message id.

Returns

Invalid message id

maximalPackagedMessageSize()

constexpr size_t Ocean::Network::PackagedSocket::maximalPackagedMessageSize ( )

staticconstexpr

Returns the maximal size of a packaged message.

Returns

The maximal size of a packaged message in bytes

packageManagmentHeaderSize()

constexpr size_t Ocean::Network::PackagedSocket::packageManagmentHeaderSize ( )

staticconstexpr

Returns the size of the package management header in bytes.

Unlike the stream oriented PackageHeader, this header describes one fragment of a message which the sender has split across several datagrams:

|<-------------------- 20 byte package management header -------------------->|<-------- payload --------->|
+------------+-------------+-------------------+--------------+---------------+----------------------------+
| messageId  | messageSize | dataStartPosition | packageIndex | totalPackages | payload                    |
| uint32_t   | uint32_t    | uint32_t          | uint32_t     | uint32_t      | at most maximalPackageSize |
| big endian | big endian  | big endian        | big endian   | big endian    | minus 20 byte              |
+------------+-------------+-------------------+--------------+---------------+----------------------------+

messageId is a counter which the sender increments for every message it sends, and it is what ties the fragments of one message together. It is unique per sender only, so a message is identified by (sender address, sender port, messageId). messageSize is the size of the whole message rather than of the fragment carrying it. Every fragment repeats it, which lets the receiver allocate the reassembly buffer from whichever fragment happens to arrive first. dataStartPosition is the byte offset of this fragment's payload within the whole message. It allows the receiver to place a fragment without knowing which ones came before it. packageIndex is the index of this fragment, with range [0, totalPackages). It identifies the fragment itself, which is what allows a duplicate to be recognized as one. totalPackages is the number of fragments the message was split into, and the message is complete once every index has been seen. The last three fields are what makes the format order independent, as UDP may deliver fragments out of order, duplicated, or not at all.

Returns

The header's size in bytes

---

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

• PackagedSocket.h