#include <flexiport/port.h>

Inheritance diagram for flexiport::Port:

Collaboration diagram for flexiport::Port:

Public Member Functions
virtual	~Port ()
virtual void	Open ()=0
	Open the port.
virtual void	Close ()=0
	Close the port.
virtual ssize_t	Read (void *const buffer, size_t count)=0
	Read from the port.
virtual ssize_t	ReadFull (void *const buffer, size_t count)=0
	Read the requested quantity of data from the port.
virtual ssize_t	ReadString (std::string &buffer)
	Read a string.
virtual ssize_t	ReadUntil (void *const buffer, size_t count, uint8_t terminator)
	Read data until a specified termination byte is received.
virtual ssize_t	ReadStringUntil (std::string &buffer, char terminator)
	Read a string until the specified termination character is received.
virtual ssize_t	ReadLine (char *const buffer, size_t count)
	Read a new-line terminated string of data.
virtual ssize_t	ReadLine (std::string &buffer)
	Read a new-line terminated string of data.
virtual ssize_t	Skip (size_t count)
	Dump data until the specified number of bytes have been read.
virtual ssize_t	SkipUntil (uint8_t terminator, unsigned int count)
	Read and dump data until the specified termination character has been seen count times.
virtual ssize_t	BytesAvailable ()=0
	Get the number of bytes waiting to be read at the port.
virtual ssize_t	BytesAvailableWait ()=0
	Get the number of bytes waiting after blocking for the timeout.
virtual ssize_t	Write (const void *const buffer, size_t count)=0
	Write data to the port.
virtual ssize_t	WriteFull (const void *const buffer, size_t count)
	Write all the data to the port.
virtual ssize_t	WriteString (const char *const buffer)
	Write a string to the port.
virtual ssize_t	WriteString (const std::string &buffer)
virtual void	Flush ()=0
	Flush the port's input and output buffers, discarding all data.
virtual void	Drain ()=0
	Drain the port's output buffers.
virtual std::string	GetStatus () const
	Get the status of the port (type, device, etc).
std::string	GetPortType () const
	Get the port type.
void	SetDebug (int debug)
	Set the debug level.
int	GetDebug () const
	Get the debug level.
virtual void	SetTimeout (Timeout timeout)=0
	Set the timeout value.
virtual Timeout	GetTimeout () const
	Get the timeout.
virtual bool	IsBlocking () const
	Get the blocking property of the port.
virtual void	SetCanRead (bool canRead)=0
	Set the read permissions of the port.
virtual bool	CanRead () const
	Get the read permissions of the port.
virtual void	SetCanWrite (bool canWrite)=0
	Set the write permissions of the port.
virtual bool	CanWrite () const
	Get the write permissions of the port.
virtual bool	IsOpen () const =0
	Check if the port is open.
Protected Member Functions
	Port ()
	Port (unsigned int debug, Timeout timeout, bool canRead, bool canWrite, bool alwaysOpen)
void	ProcessOptions (const std::map< std::string, std::string > &options)
virtual bool	ProcessOption (const std::string &option, const std::string &value)
virtual void	CheckPort (bool read)=0
Protected Attributes
std::string	_type
unsigned int	_debug
Timeout	_timeout
bool	_canRead
bool	_canWrite
bool	_alwaysOpen

Detailed Description

Base Port class.

This provides the base object from which specific port type implementations inherit.

All functions may throw exceptions of type PortException.

Options

debug <integer>
- Debug level. Higher numbers give more information.
- Default: 0 (no debug information)
timeout <float>
- Time out on read/write, in seconds.microseconds.
- A timeout of -1 disables timeouts, creating a port that will block forever.
- Default: -1
readonly, writeonly, readwrite
- Specify one type of permissions.
- Default: readwrite
alwaysopen
- The port should be open for as long as the object exists. It will be opened when constructed and if it closes unexpectedly, an attempt will be made to reopen it.
- Default: off

Definition at line 81 of file port.h.

Constructor & Destructor Documentation

virtual flexiport::Port::~Port ( ) [virtual]

flexiport::Port::Port ( ) [protected]

flexiport::Port::Port	(	unsigned int	debug,
		Timeout	timeout,
		bool	canRead,
		bool	canWrite,
		bool	alwaysOpen
	)		`[protected]`

Member Function Documentation

virtual ssize_t flexiport::Port::BytesAvailable ( ) [pure virtual]

Get the number of bytes waiting to be read at the port.

Returns immediatly.

Returns:: The number of bytes available. Will not return less than zero.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual ssize_t flexiport::Port::BytesAvailableWait ( ) [pure virtual]

Get the number of bytes waiting after blocking for the timeout.

Unlike BytesAvailable, this function will wait for the timeout to occur if no data is available straight away.

Returns:: The number of bytes waiting to be read, or -1 if a timeout occured.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual bool flexiport::Port::CanRead ( ) const [inline, virtual]

Get the read permissions of the port.

Definition at line 318 of file port.h.

virtual bool flexiport::Port::CanWrite ( ) const [inline, virtual]

Get the write permissions of the port.

Definition at line 322 of file port.h.

virtual void flexiport::Port::CheckPort ( bool read ) [protected, pure virtual]

virtual void flexiport::Port::Close ( ) [pure virtual]

Close the port.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual void flexiport::Port::Drain ( ) [pure virtual]

Drain the port's output buffers.

Waits until timeout for the port to finish transmitting data in its output buffer.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual void flexiport::Port::Flush ( ) [pure virtual]

Flush the port's input and output buffers, discarding all data.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

int flexiport::Port::GetDebug ( ) const [inline]

Get the debug level.

Definition at line 300 of file port.h.

std::string flexiport::Port::GetPortType ( ) const [inline]

Get the port type.

Definition at line 296 of file port.h.

virtual std::string flexiport::Port::GetStatus ( ) const [virtual]

Get the status of the port (type, device, etc).

Reimplemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual Timeout flexiport::Port::GetTimeout ( ) const [inline, virtual]

Get the timeout.

Definition at line 310 of file port.h.

virtual bool flexiport::Port::IsBlocking ( ) const [inline, virtual]

Get the blocking property of the port.

If the timeout is non-zero, the port will block.

Definition at line 313 of file port.h.

virtual bool flexiport::Port::IsOpen ( ) const [pure virtual]

Check if the port is open.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual void flexiport::Port::Open ( ) [pure virtual]

Open the port.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual bool flexiport::Port::ProcessOption	(	const std::string &	option,
		const std::string &	value
	)		`[protected, virtual]`

void flexiport::Port::ProcessOptions ( const std::map< std::string, std::string > & options ) [protected]

virtual ssize_t flexiport::Port::Read	(	void *const	buffer,
		size_t	count
	)		`[pure virtual]`

Read from the port.

Reads up to count bytes from the port into buffer. The exact behaviour of this function depends on the value of _timeout.

When the timeout is non-zero, it will block until data is received or the timeout occurs.
When the timeout is zero, it will timeout immediatly if no data is available.
When the timeout is -1, it will block forever.

Returns:: The number of bytes actually read, or -1 if a timeout occured. If zero is returned, this indicates that the port closed (and possibly reopened if set to do so).

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual ssize_t flexiport::Port::ReadFull	(	void *const	buffer,
		size_t	count
	)		`[pure virtual]`

Read the requested quantity of data from the port.

Reads count bytes from the port into buffer. Similar to Read, but with the important difference that, rather than returning as soon as any data is received, it will continue trying to receive data until buffer is full or an error occurs. This function ignores the timeout setting and blocks anyway.

Returns:: The number of bytes actually read. Timeouts will cause an exception (because they shouldn't happen).

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual ssize_t flexiport::Port::ReadLine ( std::string & buffer ) [inline, virtual]

Read a new-line terminated string of data.

A convenience function that reads until a newline character (\n, 0x0A) is received and stores the received data in a string, buffer. Good for text-based protocols that use newlines as message terminators.

Note:: This function makes many calls to Read, each of which has an individual timeout. The maximum length of time this function make take may therefore be longer than one timeout.; If the port is set to non-blocking mode (by setting the timeout to zero), this will effectively timeout immediatly when there is no data available, returning -1 irrespective of the quantity of data actually received before that point.

Returns:: The length of the string (including the new line), or -1 if a timeout occured.

Definition at line 217 of file port.h.

virtual ssize_t flexiport::Port::ReadLine	(	char *const	buffer,
		size_t	count
	)		`[virtual]`

Read a new-line terminated string of data.

A convenience function that reads until a newline character (\n, 0x0A) is received and stores the received data in a caller-provided buffer, buffer. Good for text-based protocols that use newlines as message terminators. Will not read more than count bytes.

buffer should include space for a NULL byte. count should reflect this. e.g. if you are expecting to receive a string "abcd\n", you should send a buffer that is 6 bytes long and make count = 6. This function will take into account the need for a NULL terminator when it receives data, receiving at most one less than count bytes. This NULL byte will not be included in the length of the received string returned from this function (just like strlen ()).

Note:: This function makes many calls to Read, each of which has an individual timeout. The maximum length of time this function may take may therefore be longer than one timeout.; If the port is set to non-blocking mode (by setting the timeout to zero), this will effectively timeout immediately when there is no data available, returning -1 irrespective of the quantity of data actually received before that point.

Returns:: The length of the string (including the new line), or -1 if a timeout occured.

virtual ssize_t flexiport::Port::ReadString ( std::string & buffer ) [virtual]

Read a string.

A convenience function that reads data from the port and returns it in a string. Behaves the same as Read.

Returns:: The length of the string, or -1 if a timeout occured.

virtual ssize_t flexiport::Port::ReadStringUntil	(	std::string &	buffer,
		char	terminator
	)		`[virtual]`

Read a string until the specified termination character is received.

A convenience function that is similar to ReadUntil. The result is stored in a string. The terminator character is included in the returned string. Good for text-based protocols with a known message termination character.

Note:: This function makes many calls to Read, each of which has an individual timeout. The maximum length of time this function make take may therefore be longer than one timeout.; If the port is set to non-blocking mode (by setting the timeout to zero), this will effectively timeout immediatly when there is no data available, returning -1 irrespective of the quantity of data actually received before that point.

Returns:: The number of bytes actually read (including the terminator), or -1 if a timeout occured.

Reimplemented in flexiport::UDPPort.

virtual ssize_t flexiport::Port::ReadUntil	(	void *const	buffer,
		size_t	count,
		uint8_t	terminator
	)		`[virtual]`

Read data until a specified termination byte is received.

Reads up to count bytes from the port into buffer, stopping when a byte matching terminator is received (included in the returned data). Otherwise behaves the same as Read.

Note:: This function makes many calls to Read, each of which has an individual timeout. The maximum length of time this function make take may therefore be longer than one timeout.; If the port is set to non-blocking mode (by setting the timeout to zero), this will effectively timeout immediatly when there is no data available, returning -1 irrespective of the quantity of data actually received before that point.

Returns:: The number of bytes actually read (including the terminator), or -1 if a timeout occured.

Reimplemented in flexiport::UDPPort.

virtual void flexiport::Port::SetCanRead ( bool canRead ) [pure virtual]

Set the read permissions of the port.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual void flexiport::Port::SetCanWrite ( bool canWrite ) [pure virtual]

Set the write permissions of the port.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

void flexiport::Port::SetDebug ( int debug ) [inline]

Set the debug level.

Definition at line 298 of file port.h.

virtual void flexiport::Port::SetTimeout ( Timeout timeout ) [pure virtual]

Set the timeout value.

Set seconds to -1 to disable timeouts and block forever.

Note:: On Mac OS X, the timer is reset each time data is received, making the timeout an inactivity timer in that there must be no data at all for the length of the timeout for it to trigger. This can potentially lead to very long blocking if the sender is sending data slightly faster than the timeout.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual ssize_t flexiport::Port::Skip ( size_t count ) [virtual]

Dump data until the specified number of bytes have been read.

Returns:: The number of bytes that were skipped, or -1 if a timeout occured.

Reimplemented in flexiport::LogWriterPort, and flexiport::UDPPort.

virtual ssize_t flexiport::Port::SkipUntil	(	uint8_t	terminator,
		unsigned int	count
	)		`[virtual]`

Read and dump data until the specified termination character has been seen count times.

Returns:: The number of bytes that were skipped, or -1 if a timeout occured.

Reimplemented in flexiport::LogWriterPort, and flexiport::UDPPort.

virtual ssize_t flexiport::Port::Write	(	const void *const	buffer,
		size_t	count
	)		`[pure virtual]`

Write data to the port.

Simply writes count bytes of data from buffer to the port. If the port is blocking, this will block until it can write more when the port's output buffer is full, or until a timeout occurs. The buffer may become full during the write, in which case less than count bytes may be written.

Returns:: The number of bytes actually written. May be 0 if the port's output buffer is already full and a timeout occurs.

Implemented in flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, and flexiport::UDPPort.

virtual ssize_t flexiport::Port::WriteFull	(	const void *const	buffer,
		size_t	count
	)		`[virtual]`

Write all the data to the port.

Similar to Write, but will keep trying until all data is written to the port rather than just writing what it can and returning, even if a timeout occurs.

Returns:: The number of bytes actually written.

virtual ssize_t flexiport::Port::WriteString ( const std::string & buffer ) [inline, virtual]

Definition at line 279 of file port.h.

virtual ssize_t flexiport::Port::WriteString ( const char *const buffer ) [virtual]

Write a string to the port.

A convenience function that writes a null-terminated string to the port. Behaves identically to Write. The NULL-terminator is *not* written to the port. If you want one, use Write to send the whole string, or use this function followed by a call to Write to write the NULL terminator.