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

#include <visiontransfer/datablockprotocol.h>

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 transferSize)
	Sets a user-defined header that shall be transmitted with the next transfer. More...

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

void	setTransferValidBytes (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...

Static Public Attributes
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

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 42 of file datablockprotocol.h.

Constructor & Destructor Documentation

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 34 of file datablockprotocol.cpp.

Member Function Documentation

int DataBlockProtocol::getDroppedReceptions ( ) const

inline

Returns the internal counter of dropped transfers during reception.

Definition at line 198 of file datablockprotocol.h.

int DataBlockProtocol::getMaxReceptionSize ( ) const

Returns the maximum payload size that can be received.

Definition at line 201 of file datablockprotocol.cpp.

const unsigned char * 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 514 of file datablockprotocol.cpp.

unsigned char * 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 209 of file datablockprotocol.cpp.

int DataBlockProtocol::getProtocolOverhead ( ) const

inline

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

Definition at line 68 of file datablockprotocol.h.

unsigned char * 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 427 of file datablockprotocol.cpp.

unsigned char * 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 435 of file datablockprotocol.cpp.

const unsigned char * 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 119 of file datablockprotocol.cpp.

bool 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 503 of file datablockprotocol.cpp.

bool 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 573 of file datablockprotocol.cpp.

void 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 217 of file datablockprotocol.cpp.

void 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 414 of file datablockprotocol.cpp.

void DataBlockProtocol::resetTransfer ( )

Resets all transfer related internal variables.

Definition at line 58 of file datablockprotocol.cpp.

void DataBlockProtocol::setTransferData	(	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 97 of file datablockprotocol.cpp.

void DataBlockProtocol::setTransferHeader	(	unsigned char *	data,
		int	headerSize,
		int	transferSize
	)

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 66 of file datablockprotocol.cpp.

void DataBlockProtocol::setTransferValidBytes ( 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.