libvisiontransfer  6.0.0
Classes | Public Types | Public Member Functions | Static Public Attributes | List of all members
DataBlockProtocol Class Reference

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
serverIf set to true, this object will be a communication server.
protTypeThe network transport protocol that is used.
maxUdpPacketSizeMaximum 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
lengthWill 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
maxLengthThe 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
lengthWill 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
lengthWill 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
lengthThe 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
lengthLength of the received network message.
transferCompleteSet 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
droppedIf 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
dataPointer to the data that should be transferred.
validBytesThe 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
dataPointer to the data of the header that should be transferred.
headerSizeSize of the data in data.
transferSizeTotal 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
validBytesThe 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 109 of file datablockprotocol.cpp.

bool DataBlockProtocol::transferComplete ( )

Returns true if the current transfer has been completed.

Definition at line 197 of file datablockprotocol.cpp.


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