#include <Driver.hpp>

Inheritance diagram for iodrivers_base::Driver:

Public Types
enum	SERIAL_RATES { SERIAL_1200 = 1200, SERIAL_2400 = 2400, SERIAL_4800 = 4800, SERIAL_9600 = 9600, SERIAL_19200 = 19200, SERIAL_38400 = 38400, SERIAL_57600 = 57600, SERIAL_115200 = 115200, SERIAL_230400 = 230400, SERIAL_460800 = 460800, SERIAL_576000 = 576000, SERIAL_921600 = 921600, SERIAL_1152000 = 1152000 }

typedef iodrivers_base::Status	Statistics

Public Member Functions
	Driver (int max_packet_size, bool extract_last=false)

virtual	~Driver ()

void	setReadTimeout (base::Time const &t)

base::Time	getReadTimeout () const

void	setWriteTimeout (base::Time const &t)

base::Time	getWriteTimeout () const

void	clear ()

Status	getStatus () const

void	resetStatus ()

Status	getStats () const

void	resetStats ()

void	setExtractLastPacket (bool flag)

bool	getExtractLastPacket () const

virtual void	openURI (std::string const &uri)

bool	openInet (const char *hostname, int port)

void	openTCP (std::string const &hostname, int port)

void	openUDP (std::string const &hostname, int remote_port)

void	openUDPBidirectional (std::string const &hostname, int out_port, int in_port)

bool	openSerial (std::string const &port, int baudrate)

void	openFile (std::string const &path)

void	setFileDescriptor (int fd, bool auto_close=true)

int	getFileDescriptor () const

bool	isValid () const

bool	setSerialBaudrate (int rate)

virtual void	close ()

bool	hasPacket () const

int	readPacket (uint8_t *buffer, int bufsize)

int	readPacket (uint8_t *buffer, int bufsize, base::Time const &packet_timeout)

int	readPacket (uint8_t *buffer, int bufsize, int packet_timeout, int first_byte_timeout=-1)

int	readPacket (uint8_t *buffer, int bufsize, base::Time const &packet_timeout, base::Time const &first_byte_timeout)

bool	writePacket (uint8_t const *buffer, int bufsize)

bool	writePacket (uint8_t const *buffer, int bufsize, int timeout)

bool	writePacket (uint8_t const *buffer, int bufsize, base::Time const &timeout)

virtual int	extractPacket (uint8_t const *buffer, size_t buffer_size) const =0

void	setMainStream (IOStream *stream)

IOStream *	getMainStream () const

void	openTestMode ()

void	addListener (IOListener *stream)

void	removeListener (IOListener *stream)

Static Public Member Functions
static int	openSerialIO (std::string const &port, int baudrate)

static bool	setNonBlockingFlag (int fd)

static bool	setSerialBaudrate (int fd, int rate)

static std::string	printable_com (std::string const &buffer)

static std::string	printable_com (uint8_t const *buffer, size_t buffer_size)

static std::string	printable_com (char const *buffer, size_t buffer_size)

static std::string	binary_com (std::string const &str)

static std::string	binary_com (uint8_t const *str, size_t str_size)

static std::string	binary_com (char const *str, size_t str_size)

Public Attributes
int const	MAX_PACKET_SIZE

Static Public Attributes
static const int	INVALID_FD = -1

Protected Member Functions
std::pair< int, bool >	readPacketInternal (uint8_t *buffer, int bufsize)

std::pair< uint8_t const *, int >	findPacket (uint8_t const *buffer, int buffer_size) const

std::pair< int, bool >	extractPacketFromInternalBuffer (uint8_t *buffer, int out_buffer_size)

int	doPacketExtraction (uint8_t *buffer)

void	openIPClient (std::string const &hostname, int port, addrinfo const &hints)

Protected Attributes
IOStream *	m_stream

std::set< IOListener * >	m_listeners

bool	m_auto_close

bool	m_extract_last

base::Time	m_read_timeout

base::Time	m_write_timeout

Status	m_stats

Detailed Description

A generic implementation of a packet extraction algorithm on an I/O device.

This class provides the basic service or reading an I/O device until a full packet has been read, and returning that packet. It does so while maintaining a proper read and write timeout.

To use this class:

subclass it
give to the Driver constructor the maximum packet size that it can expect
implement extractPacket (see below)

Then, you can freely use writePacket and readPacket to write/read data from the device.

The issue that this class is trying to solve in a generic way is that, when reading on I/O, one will seldom read a full packet at once. What this class does is to accumulate data in readPacket, until the subclass-provided extractPacket implementation finds a packet in the buffer. When a packet is found, it is copied into the buffer given to readPacket and the packet size is returned.

See extractPacket for more information on how to implement this method.

Member Typedef Documentation

typedef iodrivers_base::Status iodrivers_base::Driver::Statistics

For backward compatibility only

Member Enumeration Documentation

enum iodrivers_base::Driver::SERIAL_RATES

Enumerator
SERIAL_1200
SERIAL_2400
SERIAL_4800
SERIAL_9600
SERIAL_19200
SERIAL_38400
SERIAL_57600
SERIAL_115200
SERIAL_230400
SERIAL_460800
SERIAL_576000
SERIAL_921600
SERIAL_1152000

Constructor & Destructor Documentation

Driver::Driver	(	int	max_packet_size,
		bool	extract_last = `false`
	)

Creates an Driver class for a packet-based protocol

max_packet_size the maximum packet size in bytes
extract_last if true, readPacket will return only the latest packet found in the buffer, discarding oldest packets. This flag can be changed with setExtractLastPacket

Driver::~Driver ( )

virtual

Member Function Documentation

void Driver::addListener ( IOListener * stream )

Add a listener stream. The object's ownership is taken by the Driver object.

string Driver::binary_com ( std::string const & str )

static

string Driver::binary_com	(	uint8_t const *	str,
		size_t	str_size
	)

static

string Driver::binary_com	(	char const *	str,
		size_t	str_size
	)

static

void Driver::clear ( )

Removes all data that is pending on the file descriptor

void Driver::close ( )

virtual

Closes the file descriptor

int Driver::doPacketExtraction ( uint8_t * buffer )

protected

Internal helper method which copies in buffer the appropriate packet found in the internal buffer, and returns its size. It returns 0 if no packet has been found.

virtual int iodrivers_base::Driver::extractPacket	(	uint8_t const *	buffer,
		size_t	buffer_size
	)		const

pure virtual

Find a packet into the currently accumulated data.

This method should be provided by subclasses. The buffer argument is the data that has been read until now, and buffer_size how many bytes there is in buffer.

There is four possible cases:

there is no packet in the buffer. In that case, return -buffer_size to discard all the data that has been gathered until now.
there is the beginning of a packet but it is not starting at the first byte of buffer. In that case, return -position_packet_start, where position_packet_start is the position of the packet in buffer.
a packet begins at the first byte of buffer, but the end of the packet is not in buffer yet. Return 0.
there is a full packet in buffer, starting at the first buffer byte. Return the packet size. That data will be copied back to the buffer given to readPacket.

Implemented in iodrivers_base::Bus.

pair< int, bool > Driver::extractPacketFromInternalBuffer	(	uint8_t *	buffer,
		int	out_buffer_size
	)

protected

Internal helper method which reads packets only from the internal buffer (does not access any file descriptor)

std::pair< uint8_t const *, int > Driver::findPacket	(	uint8_t const *	buffer,
		int	buffer_size
	)		const

protected

Internal helper which extracts the packet to be returned by readPacketInternal (and therefore readPacket) in the provided buffer. This method takes into account the negative values that can be returned by extractPacket() and the m_extract_last flag.

The first element of the returned pair is the start of either a full packet, if one has been found, or of the start of a packet if a partial packet is in buffer. This pointer is buffer + buffer_size (i.e. end-of-buffer) if no packet is present at all.

The second element of the returned pair is the packet size if a full packet has been found, and 0 in all other cases.

bool Driver::getExtractLastPacket ( ) const

Returns the current packet extraction mode. If true, readPacket will only return the last packet found in the buffer. Otherwise, always returns the first packet found

int Driver::getFileDescriptor ( ) const

Returns the file descriptor associated with this object. If no file descriptor is assigned, returns INVALID_FD

IOStream * Driver::getMainStream ( ) const

Gets the main IO stream

base::Time Driver::getReadTimeout ( ) const

Get the default read timeout

Status iodrivers_base::Driver::getStats ( ) const

inline

Deprecated:

Use getStatus() instead

Status Driver::getStatus ( ) const

Returns the I/O statistics

Use resetStats() to set them back to 0

base::Time Driver::getWriteTimeout ( ) const

Get the default read timeout

bool Driver::hasPacket ( ) const

True if a packet is already present in the internal buffer

bool Driver::isValid ( ) const

True if a valid file descriptor is assigned to this object

void Driver::openFile ( std::string const & path )

Opens a file from a path. It can be used for read-only tests of a driver, or to connect to a named FIFO or an already-created Unix socket

bool Driver::openInet	(	const char *	hostname,
		int	port
	)

Deprecated:

Use openTCP

void Driver::openIPClient	(	std::string const &	hostname,
		int	port,
		addrinfo const &	hints
	)

protected

bool Driver::openSerial	(	std::string const &	port,
		int	baudrate
	)

Opens a serial port and sets it up to a sane configuration. Use then setSerialBaudrate() to change the actual baudrate of the connection on this side.

Throws UnixError on error

The return value is kept here for backward compatibility only.

int Driver::openSerialIO	(	std::string const &	port,
		int	baudrate
	)

static

Opens a serial port and sets it up to a sane configuration

Returns INVALID_FD on failure, or the file descriptor on success

void Driver::openTCP	(	std::string const &	hostname,
		int	port
	)

Opens a TCP connection to foreign host,

void Driver::openTestMode ( )

Open the IO in test mode

It is mostly equivalent to openURI("test://"), but is not meant to be overloaded, allowing to test openURI:

openTestMode() // Feed data to the driver openURI();

Moreover, it will always create a new test "channel", while openURI will create a new one only if the current main stream is not a test stream already.

void Driver::openUDP	(	std::string const &	hostname,
		int	remote_port
	)

Opens a UDP connection

If hostname and write port are given, the driver will be available to write data to a specified host. Otherwise, it is open in read-only mode.

The read_port port can be 0 if the local port does not need to be fixed.

void Driver::openUDPBidirectional	(	std::string const &	hostname,
		int	out_port,
		int	in_port
	)

Opens a UDP connection

All parameters are required. The driver will be available to write data to a specified host and output port. Data will be read from the input port.

void Driver::openURI ( std::string const & uri )

virtual

Opens an URI to a device

The following formats are recognized:

serial://path/to/device:baudrate
tcp://hostname:port
udp://hostname:remote_port[:local_port]
udpserver://port

string Driver::printable_com ( std::string const & buffer )

static

string Driver::printable_com	(	uint8_t const *	buffer,
		size_t	buffer_size
	)

static

string Driver::printable_com	(	char const *	buffer,
		size_t	buffer_size
	)

static

int Driver::readPacket	(	uint8_t *	buffer,
		int	bufsize
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Calls readPacket using the default timeout as packet timeout, and no first byte timeout

int Driver::readPacket	(	uint8_t *	buffer,
		int	bufsize,
		base::Time const &	packet_timeout
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Calls readPacket without a first byte timeout

int Driver::readPacket	(	uint8_t *	buffer,
		int	bufsize,
		int	packet_timeout,
		int	first_byte_timeout = `-1`
	)

int Driver::readPacket	(	uint8_t *	buffer,
		int	bufsize,
		base::Time const &	packet_timeout,
		base::Time const &	first_byte_timeout
	)

Tries to read a packet from the file descriptor and to save it in the provided buffer. +packet_timeout+ is the timeout to receive a complete packet. There is no infinite timeout value, and 0 is non-blocking at all (but might throw without data)

first_byte_timeout defines the timeout to receive at least one byte. Set to a value greater than packet_timeout (or call the readPacket variant without fourth argument) to disable. with a packet_timeout of 0, a TimeoutError exception is thrown when there is no data to read.

Timeout values are used only if a valid file descriptor has been provided to the class. Otherwise, if the pushInputData() interface is being used, it will raise TimeoutError if no packets are currently present in the internal buffer.

Exceptions

TimeoutError on timeout or no data, and UnixError on reading problems

Returns: the size of the packet

pair< int, bool > Driver::readPacketInternal	(	uint8_t *	buffer,
		int	bufsize
	)

protected

Internal helper method for readPacket. This one is purely non-blocking.

The first element of the pair is -1 on error, 0 if no data is available and >0 if a packet has been read

The second element of the pair is true if data has actually been read on the file descriptor, and false otherwise.

void Driver::removeListener ( IOListener * stream )

Removes a listener stream. The object's ownership is passed to the caller

void iodrivers_base::Driver::resetStats ( )

inline

Deprecated:

void Driver::resetStatus ( )

Reset the I/O statistics to 0

void Driver::setExtractLastPacket ( bool flag )

Changes the packet extraction mode

See also: getExtractLastPacket

void Driver::setFileDescriptor	(	int	fd,
		bool	auto_close = `true`
	)

Initializes the file descriptor with the given value. If auto_close is true (the default), then the file descriptor will be automatically closed on exit.

The provided file descriptor must be non-blocking for the timeout functionality to work.

void Driver::setMainStream ( IOStream * stream )

Sets the main IO stream

The Driver object takes ownership of the stream

The current I/O stream will be deleted by this operation

static bool iodrivers_base::Driver::setNonBlockingFlag ( int fd )

static

Sets the O_NONBLOCK flag on a file descriptor

Returns true if the flag was not already set and false otherwise

Throws UnixError if the flag could not be set

void Driver::setReadTimeout ( base::Time const & t )

Sets the default read timeout in milliseconds. Used in readPacket calls without timeout parameters

bool Driver::setSerialBaudrate ( int rate )

Sets the baud rate value for the serial connection

the baud rate. It can be one of the values in SERIAL_RATES
Returns
true on success, false on failure

bool Driver::setSerialBaudrate	(	int	fd,
		int	rate
	)

static

Sets the baud rate value for the given file descriptor

the baud rate. It can be one of the values in SERIAL_RATES
Returns
true on success, false on failure

void Driver::setWriteTimeout ( base::Time const & t )

Sets the default write timeout in milliseconds. Used in writePacket calls without timeout parameters

bool Driver::writePacket	(	uint8_t const *	buffer,
		int	bufsize
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Calls writePacket using the default write timeout

bool Driver::writePacket	(	uint8_t const *	buffer,
		int	bufsize,
		int	timeout
	)

bool Driver::writePacket	(	uint8_t const *	buffer,
		int	bufsize,
		base::Time const &	timeout
	)

Tries to write a packet to the file descriptor. +timeout+ is the timeout in milliseconds. There is not infinite timeout value, and 0 is non-blocking at all

Exceptions

timeout_error on timeout and unix_error on reading problems

Returns: always true. The return value is kept for backward compatibility only

Member Data Documentation

const int iodrivers_base::Driver::INVALID_FD = -1

static

bool iodrivers_base::Driver::m_auto_close

protected

True if fd should be closed on exit

See also: setFileDescriptor

bool iodrivers_base::Driver::m_extract_last

protected

True if readPacket should return the last packet found in the buffer

See also: getExtractLastPacket

std::set<IOListener*> iodrivers_base::Driver::m_listeners

protected

Set of listener that are passed the data that goes through this driver

base::Time iodrivers_base::Driver::m_read_timeout

protected

Default read timeout for readPacket

See also: getReadTimeout setReadTimeout readPacket

Status iodrivers_base::Driver::m_stats

mutableprotected

IOStream* iodrivers_base::Driver::m_stream

protected

The underlying object that gives us access to the actual I/O stream

base::Time iodrivers_base::Driver::m_write_timeout

protected

Default write timeout for writePacket

See also: getWriteTimeout setWriteTimeout writePacket

int const iodrivers_base::Driver::MAX_PACKET_SIZE

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

/build/rock-master-18.09-drivers-iodrivers-base-0.20170901/src/Driver.hpp
/build/rock-master-18.09-drivers-iodrivers-base-0.20170901/src/Driver.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation