flexiport::Port Class Reference

#include <port.h>

Inherited by flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, flexiport::TCPPort, flexiport::UDPPort, and PortWrap.

List of all members.

Public Member Functions

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. Returns immediatly.

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 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. Set seconds to -1 to disable timeouts and block forever.

virtual Timeout GetTimeout () const

Get the timeout.

virtual bool IsBlocking () const

Get the blocking property of the port. If the timeout is non-zero, the port will block.

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.

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

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.

Referenced by flexiport::LogWriterPort::BytesAvailable().

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.

Referenced by flexiport::LogWriterPort::BytesAvailableWait(), and ReadString().

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.

Referenced by flexiport::LogWriterPort::Drain().

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.

Referenced by flexiport::LogWriterPort::Read(), ReadString(), ReadStringUntil(), ReadUntil(), Skip(), and SkipUntil().

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.

Referenced by flexiport::LogWriterPort::ReadFull().

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, . 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.

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.

References ReadUntil().

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.

References BytesAvailableWait(), and Read().

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.

References IsBlocking(), and Read().

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.

References IsBlocking(), and Read().

Referenced by ReadLine().

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.

Referenced by flexiport::LogWriterPort::SetTimeout().

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.

References IsBlocking(), and Read().

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.

References IsBlocking(), and Read().

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.

Referenced by flexiport::LogWriterPort::Write(), WriteFull(), and WriteString().

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.

References IsOpen(), and Write().

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.

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

References Write().

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

port.h
port.cpp