Detailed Description

A protocol for transmitting large blocks of data over a network.

The protocol slices the large data block into several smaller chunks that can be transmitted over a network. A user defined header is always transmitted before this large data block.

There are two different implementations for UDP and TCP. In UDP mode, packet loss is handled by performing a packet re-transmission. In TCP mode, data does not have to be received with the same packet size as it is sent out.

This class is intended to be used by ImageProtocol and should normally not be used directly.

Definition at line 70 of file datablockprotocol.h.

#include <visiontransfer/internal/datablockprotocol.h>

Classes
struct	HeaderPreamble

struct	SegmentHeaderTCP

struct	SegmentHeaderUDP

Public Types
enum	ProtocolType { PROTOCOL_TCP, PROTOCOL_UDP }

Public Member Functions
	DataBlockProtocol (bool server, ProtocolType protType, int maxUdpPacketSize)
	Creates a new instance. More...

int	getProtocolOverhead () const
	Returns the size of the overhead data that is required for transferring a single network message. More...

int	getMaxReceptionSize () const
	Returns the maximum payload size that can be received. More...

void	resetTransfer ()
	Resets all transfer related internal variables. More...

void	setTransferHeader (unsigned char *data, int headerSize, int blocks)
	Sets a user-defined header that shall be transmitted with the next transfer. More...

void	setTransferBytes (int block, long bytes)
	Sets the per-block transfer size. More...

void	setTransferData (int block, unsigned char *data, int validBytes=0x7FFFFFFF)
	Sets the payload data for the next transfer. More...

void	setTransferValidBytes (int block, int validBytes)
	Updates the number of valid bytes in a partial transfer. More...

const unsigned char *	getTransferMessage (int &length)
	Gets the next network message for the current transfer. More...

bool	transferComplete ()
	Returns true if the current transfer has been completed. More...

unsigned char *	getNextReceiveBuffer (int maxLength)
	Gets a buffer for receiving the next network message. More...

void	resetReception (bool dropped)
	Resets the message reception. More...

void	processReceivedMessage (int length, bool &transferComplete)
	Handles a received network message. More...

unsigned char *	getReceivedData (int &length)
	Returns the data that has been received for the current transfer. More...

unsigned char *	getReceivedHeader (int &length)
	Returns the header data that has been received for the current transfer. More...

int	getDroppedReceptions () const
	Returns the internal counter of dropped transfers during reception. More...

bool	newClientConnected ()
	Returns true if the last network message has established a new connection from a client. More...

bool	isConnected () const
	Returns true if a remote connection is established. More...

const unsigned char *	getNextControlMessage (int &length)
	If a control message is pending to be transmitted, then the message data will be returned by this method. More...

unsigned char *	getBlockReceiveBuffer (int block)

int	getBlockValidSize (int block)

bool	isBlockDone (int block)

bool	allBlocksDone ()

bool	anyPayloadReceived ()

std::string	statusReport ()

bool	wasHeaderReceived () const

bool	supportsExtendedConnectionStateProtocol () const

Static Public Member Functions
static void	getDisconnectionMessage (const unsigned char *&buf, int &sz)

static void	getHeartbeatMessage (const unsigned char *&buf, int &sz)

Static Public Attributes
static const int	MAX_DATA_BLOCKS = 8

static const int	MAX_TCP_BYTES_TRANSFER = 0xFFFF

static const int	MAX_UDP_RECEPTION = 0x4000

static const int	MAX_OUTSTANDING_BYTES = 2*MAX_TCP_BYTES_TRANSFER

Constructor & Destructor Documentation

◆ DataBlockProtocol()

visiontransfer::internal::DataBlockProtocol::DataBlockProtocol	(	bool	server,
		ProtocolType	protType,
		int	maxUdpPacketSize
	)

Creates a new instance.

Parameters

server	If set to true, this object will be a communication server.
protType	The network transport protocol that is used.
maxUdpPacketSize	Maximum allowed size of a UDP packet when sending data.

Definition at line 44 of file datablockprotocol.cpp.

Member Function Documentation

◆ getDroppedReceptions()

int visiontransfer::internal::DataBlockProtocol::getDroppedReceptions ( ) const

inline

Returns the internal counter of dropped transfers during reception.

Definition at line 268 of file datablockprotocol.h.

◆ getMaxReceptionSize()

int visiontransfer::internal::DataBlockProtocol::getMaxReceptionSize ( ) const

Returns the maximum payload size that can be received.

Definition at line 347 of file datablockprotocol.cpp.

◆ getNextControlMessage()

const unsigned char * visiontransfer::internal::DataBlockProtocol::getNextControlMessage ( int & length )

If a control message is pending to be transmitted, then the message data will be returned by this method.

Parameters

length Will be set to the length of the message.

Returns: Pointer to the message data or NULL if no message is pending.

Control messages are only used if the UDP transfer protocol is selected. For TCP this method always returns a null pointer.

Definition at line 805 of file datablockprotocol.cpp.

◆ getNextReceiveBuffer()

unsigned char * visiontransfer::internal::DataBlockProtocol::getNextReceiveBuffer ( int maxLength )

Gets a buffer for receiving the next network message.

Parameters

maxLength The expected maximum length that is required for receiving a network message.

The returned buffer is a subsection of the internal receive buffer.

Definition at line 355 of file datablockprotocol.cpp.

◆ getProtocolOverhead()

int visiontransfer::internal::DataBlockProtocol::getProtocolOverhead ( ) const

inline

Returns the size of the overhead data that is required for transferring a single network message.

Definition at line 128 of file datablockprotocol.h.

◆ getReceivedData()

unsigned char * visiontransfer::internal::DataBlockProtocol::getReceivedData ( int & length )

Returns the data that has been received for the current transfer.

Parameters

length Will be set to the number of bytes that have been received.

Returns: Pointer to the buffer containing the received data.

The received data is valid until receiving the first network message for a new transfer.

Definition at line 676 of file datablockprotocol.cpp.

◆ getReceivedHeader()

unsigned char * visiontransfer::internal::DataBlockProtocol::getReceivedHeader ( int & length )

Returns the header data that has been received for the current transfer.

Parameters

length Will be set to the length of the header data in bytes.

Returns: Pointer to the buffer containing the received header data.

The received header data is valid until receiving the first network message for a new transfer.

Definition at line 681 of file datablockprotocol.cpp.

◆ getTransferMessage()

const unsigned char * visiontransfer::internal::DataBlockProtocol::getTransferMessage ( int & length )

Gets the next network message for the current transfer.

Parameters

length The length of the network message.

Returns: Pointer to the network message data.

If the transfer has already been completed or if there are currently no more valid bytes to be transmitted, a null pointer is returned.

Definition at line 202 of file datablockprotocol.cpp.

◆ isConnected()

bool visiontransfer::internal::DataBlockProtocol::isConnected ( ) const

Returns true if a remote connection is established.

For TCP this method always returns true as connections are handled by the transport protocol.

Definition at line 785 of file datablockprotocol.cpp.

◆ newClientConnected()

bool visiontransfer::internal::DataBlockProtocol::newClientConnected ( )

Returns true if the last network message has established a new connection from a client.

For TCP this method always returns false as connections are handled by the transport protocol.

Definition at line 867 of file datablockprotocol.cpp.

◆ processReceivedMessage()

void visiontransfer::internal::DataBlockProtocol::processReceivedMessage	(	int	length,
		bool &	transferComplete
	)

Handles a received network message.

Parameters

length	Length of the received network message.
transferComplete	Set to true if a new transfer is complete after receiving the current packet

Please see ImageProtocol::processReceivedMessage() for further details.

Definition at line 362 of file datablockprotocol.cpp.

◆ resetReception()

void visiontransfer::internal::DataBlockProtocol::resetReception ( bool dropped )

Resets the message reception.

Parameters

dropped If true, then this reset is rated as an error and internal counter for dropped transfers is increased.

Definition at line 656 of file datablockprotocol.cpp.

◆ resetTransfer()

void visiontransfer::internal::DataBlockProtocol::resetTransfer ( )

Resets all transfer related internal variables.

Definition at line 105 of file datablockprotocol.cpp.

◆ setTransferBytes()

void visiontransfer::internal::DataBlockProtocol::setTransferBytes	(	int	block,
		long	bytes
	)

Sets the per-block transfer size.

Parameters

bytes Size of the data pointed to with the matching setTransferData()

Replaces the old single-buffer total size that was prepended to the second-level header alongside the header size.

Definition at line 115 of file datablockprotocol.cpp.

◆ setTransferData()

void visiontransfer::internal::DataBlockProtocol::setTransferData	(	int	block,
		unsigned char *	data,
		int	validBytes = `0x7FFFFFFF`
	)

Sets the payload data for the next transfer.

Parameters

data	Pointer to the data that should be transferred.
validBytes	The number of bytes that are currently valid in `data`.

Part of data will be overwritten. There must be at least 4 additional allocated bytes at the end of data.

If validBytes is set to a value smaller than the total transfer size, only a partial transfer is performed. Subsequent calls to setTransferValidBytes() are then necessary.

Definition at line 168 of file datablockprotocol.cpp.

◆ setTransferHeader()

void visiontransfer::internal::DataBlockProtocol::setTransferHeader	(	unsigned char *	data,
		int	headerSize,
		int	blocks
	)

Sets a user-defined header that shall be transmitted with the next transfer.

Parameters

data	Pointer to the data of the header that should be transferred.
headerSize	Size of the data in `data`.
transferSize	Total size of the payload for the next transfer.

This method must be called before setTransferData(). A call before the start of each transfer is necessary. There must be at least 6 additional bytes of reserved memory after the end and before the beginning of data.

Definition at line 126 of file datablockprotocol.cpp.

◆ setTransferValidBytes()

void visiontransfer::internal::DataBlockProtocol::setTransferValidBytes	(	int	block,
		int	validBytes
	)

Updates the number of valid bytes in a partial transfer.

Parameters

validBytes The number of already valid bytes in the previously set data pointer.

This method has to be called whenever new data is available in a partial transfer.

See also: setTransferData()

Definition at line 182 of file datablockprotocol.cpp.

◆ transferComplete()

bool visiontransfer::internal::DataBlockProtocol::transferComplete ( )

Returns true if the current transfer has been completed.

Definition at line 340 of file datablockprotocol.cpp.

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

visiontransfer/internal/datablockprotocol.h
visiontransfer/internal/datablockprotocol.cpp

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Constructor & Destructor Documentation

◆ DataBlockProtocol()

Member Function Documentation

◆ getDroppedReceptions()

◆ getMaxReceptionSize()

◆ getNextControlMessage()

◆ getNextReceiveBuffer()

◆ getProtocolOverhead()

◆ getReceivedData()

◆ getReceivedHeader()

◆ getTransferMessage()

◆ isConnected()

◆ newClientConnected()

◆ processReceivedMessage()

◆ resetReception()

◆ resetTransfer()

◆ setTransferBytes()

◆ setTransferData()

◆ setTransferHeader()

◆ setTransferValidBytes()

◆ transferComplete()