Flexiport  2.0.0
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
flexiport::Port Class Referenceabstract

Base Port class. More...

#include <flexiport/port.h>

Inheritance diagram for flexiport::Port:
Inheritance graph
[legend]
Collaboration diagram for flexiport::Port:
Collaboration graph
[legend]

Public Member Functions

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

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::UDPPort, flexiport::LogReaderPort, flexiport::LogWriterPort, flexiport::SerialPort, and flexiport::TCPPort.

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::UDPPort, flexiport::LogReaderPort, flexiport::SerialPort, flexiport::LogWriterPort, and flexiport::TCPPort.

virtual bool flexiport::Port::CanRead ( ) const
inlinevirtual

Get the read permissions of the port.

Definition at line 318 of file port.h.

virtual bool flexiport::Port::CanWrite ( ) const
inlinevirtual

Get the write permissions of the port.

Definition at line 322 of file port.h.

virtual void flexiport::Port::CheckPort ( bool  read)
protectedpure virtual
virtual void flexiport::Port::Close ( )
pure virtual
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::UDPPort, flexiport::LogReaderPort, flexiport::SerialPort, flexiport::LogWriterPort, and flexiport::TCPPort.

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

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

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

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::UDPPort, flexiport::LogReaderPort, flexiport::SerialPort, flexiport::LogWriterPort, and flexiport::TCPPort.

virtual Timeout flexiport::Port::GetTimeout ( ) const
inlinevirtual

Get the timeout.

Definition at line 310 of file port.h.

virtual bool flexiport::Port::IsBlocking ( ) const
inlinevirtual

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
virtual void flexiport::Port::Open ( )
pure virtual
virtual bool flexiport::Port::ProcessOption ( const std::string &  option,
const std::string &  value 
)
protectedvirtual
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::UDPPort, flexiport::LogReaderPort, flexiport::SerialPort, flexiport::LogWriterPort, and flexiport::TCPPort.

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::UDPPort, flexiport::LogReaderPort, flexiport::SerialPort, flexiport::LogWriterPort, and flexiport::TCPPort.

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::ReadLine ( std::string &  buffer)
inlinevirtual

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::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
virtual void flexiport::Port::SetCanWrite ( bool  canWrite)
pure virtual
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::UDPPort, flexiport::LogReaderPort, flexiport::SerialPort, flexiport::LogWriterPort, and flexiport::TCPPort.

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::UDPPort, and flexiport::LogWriterPort.

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::UDPPort, and flexiport::LogWriterPort.

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::UDPPort, flexiport::LogReaderPort, flexiport::SerialPort, flexiport::LogWriterPort, and flexiport::TCPPort.

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 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.
virtual ssize_t flexiport::Port::WriteString ( const std::string &  buffer)
inlinevirtual

Definition at line 279 of file port.h.

Member Data Documentation

bool flexiport::Port::_alwaysOpen
protected

Definition at line 332 of file port.h.

bool flexiport::Port::_canRead
protected

Definition at line 330 of file port.h.

bool flexiport::Port::_canWrite
protected

Definition at line 331 of file port.h.

unsigned int flexiport::Port::_debug
protected

Definition at line 328 of file port.h.

Timeout flexiport::Port::_timeout
protected

Definition at line 329 of file port.h.

std::string flexiport::Port::_type
protected

Definition at line 327 of file port.h.


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