psocksxx::sockstreambuf Class Reference

Socket stream buffer class. More...

`#include <sockstreambuf.h>`

Inheritance diagram for psocksxx::sockstreambuf:

## Public Types

enum | eof_t { eof = -1 }
enum | socket_domain_t { pf_local = PF_LOCAL, pf_inet = PF_INET, pf_route = PF_ROUTE, pf_key = PF_KEY, pf_inet6 = PF_INET6 }
enum | socket_type_t { sock_stream = SOCK_STREAM, sock_dgram = SOCK_DGRAM, sock_raw = SOCK_RAW, sock_rdm = SOCK_RDM, sock_seqpacket = SOCK_SEQPACKET }
enum | socket_protocol_t { proto_unspec = 0, ipproto_ip = IPPROTO_IP, ipproto_ipv6 = IPPROTO_IPV6, ipproto_icmp = IPPROTO_ICMP, ipproto_raw = IPPROTO_RAW, ipproto_tcp = IPPROTO_TCP, ipproto_udp = IPPROTO_UDP }
typedef int | socket_t

## Public Member Functions

| sockstreambuf () throw ()
| constructor
virtual | ~sockstreambuf ()
| destructor
| sockstreambuf (socket_t socket) throw ()
| overloaded constructor More...
const socket_t & | socket () const throw ()
| get internal socket data More...
void | open (socket_domain_t domain, socket_type_t type, socket_protocol_t proto=proto_unspec) throw ( sockexception )
| open a socket More...
void | close () throw ()
| close open sockets More...
virtual int | flush () throw ( socktimeoutexception )
| flush the socket output buffer More...
void | connect (const sockaddr *dest_addr, unsigned int timeout=0) throw ( sockexception, socktimeoutexception )
| initiate a connection on a socket More...
void | connect (const sockaddr *dest_addr, timeval *timeout) throw ( sockexception, socktimeoutexception )
| initiate a connection on a socket More...
void | bind (const sockaddr *bind_addr, bool reuse_addr=false) throw ( sockexception )
| bind the socket to a specified address More...
void | listen (int backlog=SOMAXCONN) throw ( sockexception )
| make the socket passive and capable of accepting connections More...
socket_t | accept () throw ( sockexception )
| accept a connection on a listening (passive) socket More...
const timeval * | timeout (time_t sec, suseconds_t usec) throw ()
| set the timeout value for the socket More...
void * | clear_timeout () throw ()
| clear the timeout value for the socket More...
bool | timedout () const throw ()
| get the timed-out status More...

## Protected Member Functions

void | init_buffers () throw ()
| initialise internal buffers
void | cleanup_buffers () throw ()
| cleanup internal buffers
virtual int | sync () throw ()
| sync data with the socket More...
virtual int | overflow (int c=eof) throw ( socktimeoutexception )
| consumes the buffer by writing the contents to the socket More...
virtual int | underflow () throw ( socktimeoutexception )
| read more data into the buffer from the socket More...
bool | ready (timeval *timeout, bool chk_read=true, bool chk_write=true) throw ( sockexception )
| check for the read/write availability on the socket More...

## Detailed Description

Socket stream buffer class.

This buffer class associates its both input and output sequences with an external POSIX socket.

## Member Typedef Documentation

## socket_t

typedef int psocksxx::sockstreambuf::socket_t

socket data type definition

## Member Enumeration Documentation

## eof_t

enum psocksxx::sockstreambuf::eof_t

socket end-of-file type

Enumerator
eof | end of file

## socket_domain_t

enum psocksxx::sockstreambuf::socket_domain_t

socket domains type definition

Enumerator
pf_local | Host-internal protocols
pf_inet | Internet version 4 protocols
pf_route | Internal Routing protocol
pf_key | Internal key-management function
pf_inet6 | Internet version 6 protocols

## socket_protocol_t

enum psocksxx::sockstreambuf::socket_protocol_t

socket protocols type definition

Enumerator
proto_unspec | Unspecified system default
ipproto_ip | Internet protocol
ipproto_ipv6 | Internet Protocol Version 6
ipproto_icmp | Control message protocol
ipproto_raw | Raw IP Packets Protocol
ipproto_tcp | Transmission control protocol
ipproto_udp | User datagram protocol

## socket_type_t

enum psocksxx::sockstreambuf::socket_type_t

socket types type definition

## Constructor & Destructor Documentation

## sockstreambuf()

psocksxx::sockstreambuf::sockstreambuf | ( | socket_t | socket | ) |
throw | ( |
| ) |  |

overloaded constructor

Parameters

  socket | socket data

Create an instance with the passed in sockstreambuf::socket_t type socket. It is assumed that the socket is initialised and ready to use.

## Member Function Documentation

## accept()

sockstreambuf::socket_t psocksxx::sockstreambuf::accept | ( |  | ) |
throw | ( | sockexception
| ) |  |

accept a connection on a listening (passive) socket

Exceptions

  psocksxx::sockexception | socket exception

Returns
  peer socket data structure

This method will accept incoming connections on a socket set to be passive using the listen() method. Upon success this will return the peer socket data structure that can be used to create a socket stream buffer instance to communicate with the accepted socket connection.

## bind()

void psocksxx::sockstreambuf::bind | ( | const sockaddr * | bind_addr,
|  | bool | reuse_addr = `false`
| ) |  |
throw | ( | sockexception
| ) |  |

bind the socket to a specified address

Parameters

  bind_addr | address to bind to
  reuse_addr | allow address to be re-used

Exceptions

  psocksxx::sockexception | socket exception

After a socket is configured using open() this method can be used to assign an address to it. If `reuse_addr` is set to `true` then this will try to re-use the address unless the address is actively listening.

## clear_timeout()

void * psocksxx::sockstreambuf::clear_timeout | ( |  | ) |
throw | ( |
| ) |  |

clear the timeout value for the socket

Returns
  a reference to the internal timeout structure which will always be a null-pointer (`0`) after clearing the timeout

This will clear any timeout values set for the socket affectively making this a blocking socket by default.

## close()

void psocksxx::sockstreambuf::close | ( |  | ) |
throw | ( |
| ) |  |

close open sockets

Close any open socket connections used by this buffer. This will also flush any data in the buffer before closing.

## connect() [1/2]

void psocksxx::sockstreambuf::connect | ( | const sockaddr * | dest_addr,
|  | timeval * | timeout
| ) |  |
throw | ( | sockexception,
|  | socktimeoutexception
| ) |  |

initiate a connection on a socket

Parameters

  dest_addr | destination address to connect to
  timeout | connection timeout value as a reference to a `timeval` structure

Exceptions

  psocksxx::sockexception | socket exception
  psocksxx::socktimeoutexception | connection timeout exception

Initiate a connection on a socket previously opened using open() method.

## connect() [2/2]

void psocksxx::sockstreambuf::connect | ( | const sockaddr * | dest_addr,
|  | unsigned int | timeout = `0`
| ) |  |
throw | ( | sockexception,
|  | socktimeoutexception
| ) |  |

initiate a connection on a socket

Parameters

  dest_addr | destination address to connect to
  timeout | connection timeout value in seconds

Exceptions

  psocksxx::sockexception | socket exception
  psocksxx::socktimeoutexception | connection timeout exception

Initiate a connection on a socket previously opened using open() method. If the timeout value is 0 (default) then the timeouts are ignored.

## flush()

int psocksxx::sockstreambuf::flush | ( |  | ) |
throw | ( | socktimeoutexception
| ) |  |

virtual

flush the socket output buffer

Returns
  number of characters flushed

Exceptions

  psocksxx::socktimeoutexception | on socket timeout

Flush the socket buffer by writing date into the socket and returns the number of characters flushed. If the output buffer is empty sockstreambuf::eof is returned.

## listen()

void psocksxx::sockstreambuf::listen | ( | int | backlog = `SOMAXCONN` | ) |
throw | ( | sockexception
| ) |  |

make the socket passive and capable of accepting connections

Parameters

  backlog | maximum length of the queue for pending connections and defaults to SOMAXCONN (128) defined in `<sys/socket.h>`

Exceptions

  psocksxx::sockexception | socket exception

This method will make the currently opened socket connection to passive and capable of accepting client connections using accept() method.

## open()

void psocksxx::sockstreambuf::open | ( | socket_domain_t | domain,
|  | socket_type_t | type,
|  | socket_protocol_t | proto = `proto_unspec`
| ) |  |
throw | ( | sockexception
| ) |  |

open a socket

Parameters

  domain | communications domain for the socket
  type | socket communications type
  proto | socket communications protocol

Exceptions

  psocksxx::sockexception | socket exception

Open a socket and initialise socket communications.

## overflow()

int psocksxx::sockstreambuf::overflow | ( | int | c = `eof` | ) |
throw | ( | socktimeoutexception
| ) |  |

protected virtual

consumes the buffer by writing the contents to the socket

Parameters

  c | additional character to consume

Returns
  sockstreambuf::eof to indicate failure or c if successful.

Exceptions

  psocksxx::socktimeoutexception | on socket timeout

Consumes the buffer contents and writes to the opened socket. If c is not sockstreambuf::eof then c is also written out.

## ready()

bool psocksxx::sockstreambuf::ready | ( | timeval * | timeout,
|  | bool | chk_read = `true`,
|  | bool | chk_write = `true`
| ) |  |
throw | ( | sockexception
| ) |  |

protected

check for the read/write availability on the socket

Parameters

  timeout | timeout value reference to a `timeval` structure
  chk_read | check for read availability
  chk_write | check for write availability

Exceptions

  psocksxx::sockexception | socket exception

Returns
  boolean `true` to denote availability or `false` if none of the checked actions are available.

This will check the socket for read and/or write availability.

## socket()

const sockstreambuf::socket_t & psocksxx::sockstreambuf::socket | ( |  | ) | const
throw | ( |
| ) |  |

get internal socket data

Returns
  socket data

Returns a read-only reference to the internal POSIX socket data.

## sync()

int psocksxx::sockstreambuf::sync | ( |  | ) |
throw | ( |
| ) |  |

protected virtual

sync data with the socket

Returns
  0 or -1 to denote success or failure

Synchronise the buffer with the associated socket by flushing data from the buffer to the socket.

## timedout()

bool psocksxx::sockstreambuf::timedout | ( |  | ) | const
throw | ( |
| ) |  |

get the timed-out status

Returns
  boolean `true` if timed-out flag is set or `false` otherwise.

Returns the timed-out status.

## timeout()

const timeval * psocksxx::sockstreambuf::timeout | ( | time_t | sec,
|  | suseconds_t | usec
| ) |  |
throw | ( |
| ) |  |

set the timeout value for the socket

Parameters

  sec | seconds
  usec | microseconds

Returns
  a reference to the internal timeout structure

This method will set the timeout for the socket and make this a non-blocking socket. Note that you cannot clear the timeout by passing in a 0 timeout, use clear_timeout() method instead.

## underflow()

int psocksxx::sockstreambuf::underflow | ( |  | ) |
throw | ( | socktimeoutexception
| ) |  |

protected virtual

read more data into the buffer from the socket

Returns
  the first character from the buffer or sockstreambuf::eof if no data is available to read

Exceptions

  psocksxx::socktimeoutexception | on socket timeout

This reads more data into the buffer from the socket when the input buffer is empty and returns the next readable character from the buffer. If the buffer is empty and no data is available through the socket, this returns sockstreambuf::eof.