Conexus::Endpoint Class Reference
[Conexus]

#include <conexus/endpoint.h>

Inheritance diagram for Conexus::Endpoint:

Inheritance graph
[legend]
List of all members.

Detailed Description

This class is the top level object for all subclasses performing I/O (Input/Output) operations.

read/write methods are pure virtual methods in this base class and it is the responsibility of all children to provide proper implementations that may go beyond the traditional read(2) and write(2) functions standard in Linux/Unix.

Children are also responsible for maintenance of the file descriptor member m_fd and the integer state value m_state.

This class inherits from propertymm::Object and thus makes some properties available via the propertymm framework as well as providing direct accessor methods.

Author:
Rick L Vinyard Jr


Public Types

typedef boost::shared_ptr<
Endpoint
pointer
 Class scope smart pointer typedef.
typedef enum Conexus::Endpoint::EndpointState EndpointState
 These enumerations are used in the socket class methods, and use is also encouraged in children.
enum  EndpointState {
  NOSTATE = 0x00, CLOSED = 1<<0, OPENED = 1<<1, LASTENDPOINTSTATE = OPENED,
  UNCHANGED = ~0x00
}
 These enumerations are used in the socket class methods, and use is also encouraged in children. More...

Public Member Functions

 Endpoint (bool close_on_destruction=true)
 Default constructor setting state to 0 and file descriptor to -1 (which should be an invalid fd on just about every POSIX system.
virtual ~Endpoint ()
 Destructor does nothing.
virtual void open ()=0 throw (open_error)
 Will attempt to open the object without any additional information.
virtual void close (bool force=false)=0 throw (close_error)
virtual ssize_t write (const void *data, size_t size, IOMethod block=BLOCK)=0 throw (write_error)
 A pure virtual method that must be reimplemented by children to perform whatever actions necessary to ensure writing/transmission of a block of data pointed to by data and of size bytes.
virtual ssize_t write (const Data &data, IOMethod block=BLOCK)
 Write data according to virtual method defined by children.
virtual Data read (size_t s=0)=0 throw (read_error)
 A pure virtual method that must be reimplemented by children to perform whatever actions necessary to read a block of data.
virtual void change_state (long new_state) throw (state_error)
 It is intended that children will provide their own implementation of this method to take into account the actions necessary for any additional states they may introduce.
long state ()
 Return this endpoint's current numeric state.
void set_close_on_destruction (bool value)
 If set, calls this endpoint's virtual close() method on destruction.
bool close_on_destruction () const
 True if this endpoint's virtual close() method will be called on destruction.
void close_and_reopen (long state=UNCHANGED)
 Close the I/O point and reopen to a new (or same state).
sigc::signal< void > signal_opened ()
 Signal emitted when this endpoint is opened.
sigc::signal< void > signal_closed ()
 Signal emitted when this endpoint is closed.
sigc::signal< void, bool,
bool > 
signal_read_write_stop_changed ()
 Signal emitted when this endpoint's read/write stop state is changed.
bool is_open ()
 True if this endpoint is in an open state.
bool is_closed ()
 True if this endpoint is in a closed state.
bool is_read_stopped ()
 True if this endpoint's read is currently stopped.
bool is_write_stopped ()
 True if this endpoint's write is currently stopped.
virtual void stop_read (bool read_stop=true)
 Sets the stop-state on this endpoint's read operations.
virtual void stop_write (bool write_stop=true)
 Sets the stop-state on this endpoint's write operations.
virtual void stop_read_write (bool read_stop=true, bool write_stop=true)
 Sets the stop-state on this endpoint's read and write operations.
virtual const std::string & object_type ()
 String identifier of this class.

Protected Member Functions

virtual void set_state_opened ()
virtual void set_state_closed ()

Protected Attributes

bool m_close_on_destruction
long m_state
bool m_readable
bool m_writable
bool m_read_stopped
bool m_write_stopped
sigc::signal< void > m_signal_opened
sigc::signal< void > m_signal_closed
sigc::signal< void, bool,
bool > 
m_signal_read_write_stop_changed


Member Enumeration Documentation

enum Conexus::Endpoint::EndpointState
 

These enumerations are used in the socket class methods, and use is also encouraged in children.

Enumerator:
CLOSED  The Endpoint object is in a closed state.
OPENED  The Endpoint object is in an opened state.
UNCHANGED  setting this mode will keep the mode unchanged


Constructor & Destructor Documentation

Conexus::Endpoint::Endpoint bool  close_on_destruction = true  ) 
 

Default constructor setting state to 0 and file descriptor to -1 (which should be an invalid fd on just about every POSIX system.

This constructor simply sets the values according to the parameters and performs no real actions with the file descriptor.

Conexus::Endpoint::~Endpoint  )  [virtual]
 

Destructor does nothing.

It will not call close() upon the file descriptor or perform any other cleanup; these are the responsibility of the children.


Member Function Documentation

void Conexus::Endpoint::change_state long  new_state  )  throw (state_error) [virtual]
 

It is intended that children will provide their own implementation of this method to take into account the actions necessary for any additional states they may introduce.

This method as implemented recognizes the OPEN, CLOSE and UNCHANGED states and calls the virtual open, close (or no call) as is appropriate.

This method does not actually modify the m_state member. It is the responsibility of the called virtual methods open() and close() to actually perform the modification.

Returns:
true if all requested state changes occurred, false otherwise

void Conexus::Endpoint::close_and_reopen long  state = UNCHANGED  ) 
 

Close the I/O point and reopen to a new (or same state).

If state is UNCHANGED will reopen to the previous state.

close and reopen is accomplished by calling change_state(CLOSED) and then change_state(new_state), not by calling close directly.

virtual Data Conexus::Endpoint::read size_t  s = 0  )  throw (read_error) [pure virtual]
 

A pure virtual method that must be reimplemented by children to perform whatever actions necessary to read a block of data.

Children may utilize the parameter s or may choose to ignore the parameter entirely.

Returns:
A Data object containing the data and size of data in bytes. The data is dynamically allocated via a smart pointer, and deallocated in accordance with the rules for smart pointers. Therefore, if you want to keep the data from being automatically deallocated, keep the returned data object (or a copy of the returned data object) around as long as you need it. Call by value is sufficient to keep the object around, but extracting the pointer to the actual data via the dereference operator or through the smart pointer's get() method is not sufficient to keep the data block from being deallocated (again, keeping a copy around is easier).
Parameters:
s The size of the data block to read. Suggested semantics for children are:
  • s=0: read as much as possible
  • s>0: read up to s bytes

Implemented in Conexus::IPv4::TCP, Conexus::IPv4::UDP, Conexus::IPv6::TCP, Conexus::IPv6::UDP, Conexus::RWFileDescriptor, and Conexus::TTY.

long Conexus::Endpoint::state  ) 
 

Return this endpoint's current numeric state.

The meaning of this value is specific to the endpoint.

void Conexus::Endpoint::stop_read bool  read_stop = true  )  [virtual]
 

Sets the stop-state on this endpoint's read operations.

Does not close the endpoint. If true, the endpoint will not perform read operations. If false, the endpoint will function properly.

void Conexus::Endpoint::stop_read_write bool  read_stop = true,
bool  write_stop = true
[virtual]
 

Sets the stop-state on this endpoint's read and write operations.

Does not close the endpoint.

void Conexus::Endpoint::stop_write bool  write_stop = true  )  [virtual]
 

Sets the stop-state on this endpoint's write operations.

Does not close the endpoint. If true, the endpoint will not perform write operations. If false, the endpoint will function properly.

ssize_t Conexus::Endpoint::write const Data data,
IOMethod  block = BLOCK
[virtual]
 

Write data according to virtual method defined by children.

Returns:
The number of bytes actually written.

virtual ssize_t Conexus::Endpoint::write const void *  data,
size_t  size,
IOMethod  block = BLOCK
throw (write_error) [pure virtual]
 

A pure virtual method that must be reimplemented by children to perform whatever actions necessary to ensure writing/transmission of a block of data pointed to by data and of size bytes.

Returns:
The number of bytes actually written.
Parameters:
data Pointer to the raw data block to be written.
size Size in bytes of the raw data block to write.
block The blocking mechanism to use for this write call: BLOCK or NONBLOCK

Implemented in Conexus::RWFileDescriptor.


The documentation for this class was generated from the following files:
Generated on Sat Aug 26 17:34:54 2006 by  doxygen 1.4.6