Detailed Description

Class for synchronous transfer of image sets.

This class opens a network socket for delivering or receiving image sets. All operations are performed synchronously, which means that they might block. The class encapsulates ImageProtocol.

This class is thread safe for as long as sending and receiving data each has its dedicated thread.

Note: For normal applications and typical use cases, we recommend using AsyncTransfer instead, which places network operations into an automatic background thread, decoupled from your own loop timing.

Definition at line 57 of file imagetransfer.h.

#include <visiontransfer/imagetransfer.h>

Classes
class	Pimpl

Public Types
enum	TransferStatus { ALL_TRANSFERRED, PARTIAL_TRANSFER, NO_VALID_DATA, WOULD_BLOCK, NOT_CONNECTED }
	The result of a partial image transfer. More...

Public Member Functions
	ImageTransfer (const char address, const char service="7681", ImageProtocol::ProtocolType protType=ImageProtocol::PROTOCOL_UDP, bool server=false, int bufferSize=16 *1048576, int maxUdpPacketSize=1472, int autoReconnectDelay=1)
	Creates a new transfer object by manually specifying the target address. More...

	ImageTransfer (const DeviceInfo &device, int bufferSize=16 *1048576, int maxUdpPacketSize=1472, int autoReconnectDelay=1)
	Creates a new transfer object by using the device information from device enumeration. More...

void	setRawTransferData (const ImageSet &metaData, const std::vector< unsigned char * > &rawData, int firstTileWidth=0, int middleTileWidth=0, int lastTileWidth=0)
	Sets the raw pixel data for a partial image transmission. More...

void	setRawValidBytes (const std::vector< int > &validBytes)
	Updates the number of valid bytes in a partial raw transmission. More...

void	setTransferImageSet (const ImageSet &imageSet)
	Sets a new image set that shall be transmitted. More...

TransferStatus	transferData ()
	Performs a partial (or full) image transmission. More...

bool	receiveImageSet (ImageSet &imageSet)
	Waits for and receives a new image set. More...

bool	receivePartialImageSet (ImageSet &imageSet, int &validRows, bool &complete)
	Returns the received image set, even if it is not yet complete. More...

int	getNumDroppedFrames () const
	Returns the number of frames that have been dropped since connecting to the current remote host. More...

bool	tryAccept ()
	Tries to accept a client connection. More...

bool	isConnected () const
	Returns true if a remote connection is established (and not temporarily disconnected). For event-driven signaling of this state, see also setConnectionStateChangeCallback() More...

void	disconnect ()
	Terminates the current connection. More...

std::string	getRemoteAddress () const
	Returns the address of the remote host. More...

void	setConnectionStateChangeCallback (std::function< void(visiontransfer::ConnectionState)> callback)
	Install a handler that will be called when the connection state changes (e.g. socket is disconnected). [C++11] More...

void	setAutoReconnect (int secondsBetweenRetries=1)

Member Enumeration Documentation

◆ TransferStatus

enum visiontransfer::ImageTransfer::TransferStatus

The result of a partial image transfer.

Enumerator
ALL_TRANSFERRED	The image set has been transferred completely.
PARTIAL_TRANSFER	The image set has been transferred partially. Further transfers are necessary.
NO_VALID_DATA	There is currently no more data that could be transmitted.
WOULD_BLOCK	The operation would block and blocking as been disabled.
NOT_CONNECTED	No network connection has been established.

Definition at line 72 of file imagetransfer.h.

Constructor & Destructor Documentation

◆ ImageTransfer() [1/2]

visiontransfer::ImageTransfer::ImageTransfer	(	const char *	address,
		const char *	service = `"7681"`,
		ImageProtocol::ProtocolType	protType = `ImageProtocol::PROTOCOL_UDP`,
		bool	server = `false`,
		int	bufferSize = `16*1048576`,
		int	maxUdpPacketSize = `1472`,
		int	autoReconnectDelay = `1`
	)

Creates a new transfer object by manually specifying the target address.

Parameters

address	Address of the remote host to which a connection should be established. In server mode this can be a local interface address or NULL.
service	The port number that should be used as string or as textual service name.
protType	Specifies whether the UDP or TCP transport protocol shall be used.
server	If set to true, this object will be a communication server.
bufferSize	Buffer size for sending / receiving network data.
maxUdpPacketSize	Maximum allowed size of a UDP packet when sending data.
autoReconnectDelay	Auto-reconnection behavior, see setAutoReconnect

Definition at line 114 of file imagetransfer.cpp.

◆ ImageTransfer() [2/2]

visiontransfer::ImageTransfer::ImageTransfer	(	const DeviceInfo &	device,
		int	bufferSize = `16 * 1048576`,
		int	maxUdpPacketSize = `1472`,
		int	autoReconnectDelay = `1`
	)

Creates a new transfer object by using the device information from device enumeration.

Parameters

device	Information on the device to which a connection should be established.
bufferSize	Buffer size for sending / receiving network data.
maxUdpPacketSize	Maximum allowed size of a UDP packet when sending data.
autoReconnectDelay	Auto-reconnection behavior, see setAutoReconnect

Definition at line 122 of file imagetransfer.cpp.

Member Function Documentation

◆ disconnect()

void visiontransfer::ImageTransfer::disconnect ( )

Terminates the current connection.

If connected to a remote host this connection will be closed.

Definition at line 166 of file imagetransfer.cpp.

◆ getNumDroppedFrames()

int visiontransfer::ImageTransfer::getNumDroppedFrames ( ) const

Returns the number of frames that have been dropped since connecting to the current remote host.

Dropped frames are caused by dropped packets due to a poor network connection

Definition at line 158 of file imagetransfer.cpp.

◆ getRemoteAddress()

std::string visiontransfer::ImageTransfer::getRemoteAddress ( ) const

Returns the address of the remote host.

Returns: Remote address or "" if no connection has been established.

Definition at line 172 of file imagetransfer.cpp.

◆ isConnected()

bool visiontransfer::ImageTransfer::isConnected ( ) const

Returns true if a remote connection is established (and not temporarily disconnected). For event-driven signaling of this state, see also setConnectionStateChangeCallback()

Definition at line 162 of file imagetransfer.cpp.

◆ receiveImageSet()

bool visiontransfer::ImageTransfer::receiveImageSet ( ImageSet & imageSet )

Waits for and receives a new image set.

Parameters

imageSet Will be set to the received image set.

Returns: Returns true if a new image set has been received. Otherwise false.

The received image set is only valid until the next call of receiveImageSet(). The method will not block indefinitely, but return after a short timeout.

Note: The call frequency of this function should be regular, and not be used to limit the frame rate (use the device settings for that.)

See also: ImageProtocol::getReceivedImageSet()

Definition at line 150 of file imagetransfer.cpp.

◆ receivePartialImageSet()

bool visiontransfer::ImageTransfer::receivePartialImageSet	(	ImageSet &	imageSet,
		int &	validRows,
		bool &	complete
	)

Returns the received image set, even if it is not yet complete.

The received image set is only valid until calling receivePartialImageSet() for the first time after the current image set has been received completely. The method returns false if no image data has been received.

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

Definition at line 154 of file imagetransfer.cpp.

◆ setConnectionStateChangeCallback()

void visiontransfer::ImageTransfer::setConnectionStateChangeCallback ( std::function< void(visiontransfer::ConnectionState)> callback )

Install a handler that will be called when the connection state changes (e.g. socket is disconnected). [C++11]

Definition at line 180 of file imagetransfer.cpp.

◆ setRawTransferData()

void visiontransfer::ImageTransfer::setRawTransferData	(	const ImageSet &	metaData,
		const std::vector< unsigned char * > &	rawData,
		int	firstTileWidth = `0`,
		int	middleTileWidth = `0`,
		int	lastTileWidth = `0`
	)

Sets the raw pixel data for a partial image transmission.

This method has to be used in conjunction with transferData(). Please see ImageProtocol::setRawTransferData() for further details.

Definition at line 133 of file imagetransfer.cpp.

◆ setRawValidBytes()

void visiontransfer::ImageTransfer::setRawValidBytes ( const std::vector< int > & validBytes )

Updates the number of valid bytes in a partial raw transmission.

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

Definition at line 138 of file imagetransfer.cpp.

◆ setTransferImageSet()

void visiontransfer::ImageTransfer::setTransferImageSet ( const ImageSet & imageSet )

Sets a new image set that shall be transmitted.

Parameters

imageSet The image set that shall be transmitted.

After setting the image set, subsequent calls to transferData() are necessary for performing the image transmission.

See also: ImageProtocol::setTransferImageSet()

Definition at line 142 of file imagetransfer.cpp.

◆ transferData()

ImageTransfer::TransferStatus visiontransfer::ImageTransfer::transferData ( )

Performs a partial (or full) image transmission.

Parameters

block If set to true, the method will block when the network send buffers are full.

Returns: Status of the transmission. See below.

The method transfers up to the specified number of valid bytes. It has to be called in cycles in order to transfer a full image set. If there is no more data to be transferred, it will return TransferStatus::NO_VALID_DATA.

If the transfer is compete, the method will return TransferStatus::ALL_TRANSFERRED. If there remains outstanding data for this transfer, the return value will be TransferStatus::PARTIAL_TRANSFER. If the connection is no longer open, TransferStatus::CONNECTION_CLOSED is returned.

Even after a complete transfer this method should be continued to be called in case a packed needs to be retransmitted due to an unreliable network connection. Also for a communication server this method should be called frequently to accept incoming connections.

Definition at line 146 of file imagetransfer.cpp.

◆ tryAccept()

bool visiontransfer::ImageTransfer::tryAccept ( )

Tries to accept a client connection.

Returns: True if a client has connected.

This method can only be used in TCP server mode. It shall be called in regular intervals to allow for client connections. The method is always non-blocking.

Definition at line 176 of file imagetransfer.cpp.

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

visiontransfer/imagetransfer.h
visiontransfer/imagetransfer.cpp

Detailed Description

Classes

Public Types

Public Member Functions

Member Enumeration Documentation

◆ TransferStatus

Constructor & Destructor Documentation

◆ ImageTransfer() [1/2]

◆ ImageTransfer() [2/2]

Member Function Documentation

◆ disconnect()

◆ getNumDroppedFrames()

◆ getRemoteAddress()

◆ isConnected()

◆ receiveImageSet()

◆ receivePartialImageSet()

◆ setConnectionStateChangeCallback()

◆ setRawTransferData()

◆ setRawValidBytes()

◆ setTransferImageSet()

◆ transferData()

◆ tryAccept()