Home C-Bits Package Documentation Project Page

Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members   File Members  

cbits::Socket Class Reference

This class represents a network socket endpoint. More...

#include <Socket.h>

Inheritance diagram for cbits::Socket:

[legend]
List of all members.

Public Methods

 Socket (const std::string &host, const int port, const bool now=true) throw (SocketException)
 Construct a socket that may be used to connect to the application executing on the specified host, bound to the specified port. More...

 Socket (const char *host, const int port, const bool now=true) throw (SocketException)
 Socket (const int port, const bool now=true) throw (SocketException)
virtual ~Socket ()
 Drops the network connection and destroys the Socket instance. More...

virtual void connect () throw (SocketException)
 Complete (establish) the network connection. More...

virtual const ssize_t readLine (std::string &buffer, const std::string &delim, int *const error=0, const long int msec=0) throw ( SocketException )
 Read from the network connection until a specified delimiter string is encountered. More...

virtual const ssize_t read (char *const buffer, const int buflen, int *const error=0, const long msec=0) throw ( SocketException )
 Read data from the network connection into a user-supplied buffer. More...

virtual const ssize_t receive (char *const buffer, const int buflen, const long int msec=0, int *const error=0) throw ( SocketException )
 Synonym for cbits::Socket::read with the error and msec argument positions reversed. More...

virtual const ssize_t write (const char *buffer, const long buflen, int *const error=0, const long int msec=0) throw ( SocketException )
 Write a buffer of data to the network connection. More...

virtual const ssize_t send (const char *buffer, const long buflen, const long int msec=0, int *const error=0) throw ( SocketException )
 Synonym for cbits::Socket::write with the error and msec argument positions reversed. More...

const socket_t getHandle () const
 Get a handle to the underlying BSD socket connection. More...

std::iostream & get_iostream () throw (SocketException)
 Get a std::iostream instance that can be used to write to or read from the socket. More...

const struct sockaddr_in & get_addr () const
 Access the socket address that this cbits::Socket is bound to. More...

virtual const bool isError () const
 Check the error status of thenetwork connection. More...

const std::string & getError () const
 Access a human readable description of the socket error condition, if any. More...

virtual const bool isReadable (long int *msec=0, int *const error=0) const
 Determine if the socket has data. More...

virtual const bool isWritable (long int *msec=0, int *const error=0) const
 Determine if the socket can accept data. More...

 operator std::ostream & ()
 Type conversion operator for when cbits::Socket needs to be used as a std::ostream instance. More...

 operator std::istream & ()
 Type conversion operator for when cbits::Socket needs to be used as a std::istream instance. More...

virtual const bool set_blocking_on ()
 Configure the network connection such that calls to read data will block if none is available and calls to write data will block if the network connection can not immediately accept the data. More...

virtual const bool set_blocking_off ()
 set_blocking_off. More...

virtual const int getSockOpt (const int level, const int op_name, char *buffer, int *buflen) const
 Access the value of a socket option. More...

std::ostream * getLogger () const
 Access this Socket's debug logging stream. More...

std::ostream * getLocalLogger () const
 Access this Sockets individual logging stream, set via cbits::setLocalLogger, if any. More...

void setLocalLogger (std::ostream *os) const
 Set a instance debug logging stream for this Socket. More...

void closeLocalLogger () const
 Close this Socket's individually set debug log stream, set via cbits::Socket::setLocalLogger, if any. More...


Static Public Methods

Socket * create (const socket_t s)
 Wrap a pre-existing low-level BSD socket in a cbits::Socket. More...

std::ostream * getGlobalLogger ()
 Access the global debug logging stream for all Socket instances that don't have an individual logging stream. More...

void setGlobalLogger (std::ostream *os)
 Set a global debug logging stream to be used by all Socket instances. More...

void closeGlobalLogger ()
 Close the globally set debug log stream, set via cbits::Socket::setGlobalLogger, if any. More...


Protected Methods

 Socket ()
 Protected default constructor. More...

const bool isAvailable (fd_set *rd, fd_set *wr, long int *msec=0, int *error=0) const
 Use the 'select' system call to determine if any of a set of file descriptors are available for reading or writing. More...


Protected Attributes

socket_t _sockfd
 The BSD socket descriptor. More...

sockaddr_in _host
 Address of remote host. More...

int _port
 Port of remote host application. More...

std::iostream * _iostream
 <iostream> rep of this Socket. More...

bool _error
 Last error that occurred. More...

std::string _errstr
 Human readable descripton of _error. More...

bool _is_connected
 true if socket is connected. More...

bool _is_bound
std::ostream * _llogr
 instance-scoped logging stream. More...


Static Protected Attributes

std::ostream * _glogr = 0
 class-scoped logging stream. More...


Private Methods

void set_bound (const bool val)
void invalid_host (const char *) const throw ( SocketException )
 Convenicne method to throws an exception if an invalid host is specified in a cbits::Socket constructor. More...

socket_t make_socket (const char *name, const int port, const bool now) throw ( SocketException )
 Convenience method to instantiate a BSD socket. More...

unsigned long resolve_name (const char *)
 Convenience method to convert a host name into an IP address. More...

void bind_address (struct sockaddr_in *inout_address, unsigned long in_IP, const int in_port)
 Convenience method to bind an IP address to a BSD socket endpoint. More...

void ignore_epipe (const bool)
 Convenience method to install or de-install signal handler for SIGPIPE signal.. More...

 Socket (const Socket &)
Socket & operator= (const Socket &)

Private Attributes

CriticalSection _write_csect
 Critical section used to disallow more than one thread from writing to the socket at a time. More...

CriticalSection _read_csect
 Critical section used to disallow more than one thread from reading data from the socket at a time. More...

CriticalSection _csect
 Critical section used so synchronize non-read/write specific sections of code. More...


Friends

class ServerSocket
 Must be able to set _is_bound state. More...


Detailed Description

This class represents a network socket endpoint.

It may be directly instantiated in order to establish a network connection to a sever application running on the same or a different host.

Instances of this class are also manufactured by a cbits::ServerSocket as it accepts network connections remote clients, each produced cbits::Socket instance representing a socket connection to a specific client.

Sockets are byte-stream oriented. As a byte is written to a Socket endpoint, it becomes available to be read on the mate Socket endpoint in the remote process. Structured data has to be serialized into a sequence of bytes by the application code as it is written to the Socket and reconstructed by the application reading the data from the other Socket endpoint.

Sockets are full duplex network connections. Data may be transmitted in both directions simultaneously and independently; both Socket endpoints may be used for reading and writing.

The primary Socket methods for reading and writing byte data are cbits:Socket::read and cbits::Socket::write. However, as a convenience, cbits::Socket supports std::iostream semantics via type conversion operators that allow a Socket instance to be used wherever a std::ostream& or std:istream& is used.


Constructor & Destructor Documentation

Socket::Socket const std::string &    host,
const int    port,
const bool    now = true
throw (SocketException)
 

Construct a socket that may be used to connect to the application executing on the specified host, bound to the specified port.

Exceptions:
cbits::SocketException  if the IP of the remote hostname can not be found, or an OS-level error occurs.
Parameters:
h  DNS or 'dot-IP' name of remote
p  remote port
now  if false, don't connect to the remote until the connect method is invoked.

Socket::Socket const char *    host,
const int    port,
const bool    now = true
throw (SocketException)
 

Socket::Socket const int    port,
const bool    now = true
throw (SocketException)
 

Socket::~Socket   [virtual]
 

Drops the network connection and destroys the Socket instance.

Socket::Socket   [protected]
 

Protected default constructor.

cbits::Socket::Socket const Socket &    [private]
 


Member Function Documentation

void Socket::bind_address struct sockaddr_in *    inout_address,
unsigned long    in_IP,
const int    in_port
[private]
 

Convenience method to bind an IP address to a BSD socket endpoint.

Parameters:
hent  sock address struct
ip  IP address to bind
p  port to bind

void Socket::closeGlobalLogger   [static]
 

Close the globally set debug log stream, set via cbits::Socket::setGlobalLogger, if any.

Since the output stream supplied to cbits::Socket::setGlobalLogger is externally created, the output stream itself is not closed by this action.

void Socket::closeLocalLogger   const
 

Close this Socket's individually set debug log stream, set via cbits::Socket::setLocalLogger, if any.

Since the output stream supplied to cbits::Socket::setLocalLogger is externally created, the output stream itself is not closed by this action.

void Socket::connect   throw (SocketException) [virtual]
 

Complete (establish) the network connection.

Exceptions:
SocketException  if the connection could not be established.

Reimplemented in cbits::SSLSocket.

Socket * Socket::create const socket_t    s [static]
 

Wrap a pre-existing low-level BSD socket in a cbits::Socket.

Returns:
A pointer to a new cits::Socket instance.
Parameters:
s  Pre-existing BSD socket.

const struct sockaddr_in& cbits::Socket::get_addr   const [inline]
 

Access the socket address that this cbits::Socket is bound to.

Returns:
reference to sockaddr_in structure.

std::iostream & Socket::get_iostream   throw (SocketException)
 

Get a std::iostream instance that can be used to write to or read from the socket.

All of the rules related to use of a std::iostream instance apply, including the need to check the stream flags for errors.

Returns:
a std:iostream instance.
Exceptions:
SocketException 
FIXME Socket.h why does Socket::get_iostream throw SocketException?

const std::string& cbits::Socket::getError   const [inline]
 

Access a human readable description of the socket error condition, if any.

@Returns A non-empty string if an error exists on the socket; otherwise an empty string is returned.

std::ostream * Socket::getGlobalLogger   [static]
 

Access the global debug logging stream for all Socket instances that don't have an individual logging stream.

This only accesses the logging stream that is used by Socket instances that haven't been individually configured with their own logging stream via cbits::Socket::setLocalLogger.

Returns:
pointer to std::ostream instance or 0 if no global logger has been set.

const socket_t Socket::getHandle   const
 

Get a handle to the underlying BSD socket connection.

Returns:
socket handle.

std::ostream * Socket::getLocalLogger   const
 

Access this Sockets individual logging stream, set via cbits::setLocalLogger, if any.

Returns:
a pointer to std::ostream, or 0 if not set.

std::ostream * Socket::getLogger   const
 

Access this Socket's debug logging stream.

A pointer to a stream is always returned. Logging statements that use this method should perform runtime checks to determine if application debug logging is enabled.

Returns:
pointer to std::ostream instance.
  • If the Socket has been configured with an individual logging stream, via cbits::Socket::setLocalLogger, then that logging stream is returned.
  • If the Socket has no local logger but has a global logging stream, set via setGlobalLogger, then the global stream is returned.
  • If the socket has neither a local nor a global logging stream set then a pointer to std::cerr is returned.

const int Socket::getSockOpt const int    level,
const int    op_name,
char *    buffer,
int *    buflen
const [virtual]
 

Access the value of a socket option.

Returns:
0 if successful; otherwise an error code is returned. Under Windows, consult the WINSOCK documentation, and under Unix, consult the 'getsockopt' manpage.
Parameters:
level  SOL_SOCKET or IPPROTO_TCP
op_name  option value to retrieve
buffer  result buffer to save value
buflen  length of result buffer

void Socket::ignore_epipe const    bool [private]
 

Convenience method to install or de-install signal handler for SIGPIPE signal..

A SIGPIPE is generated when data is written to a socket that has been disconnected at the remote endpoint.

Parameters:
bool  if true, install; otherwise de-install.

void Socket::invalid_host const char *    const throw ( SocketException ) [private]
 

Convenicne method to throws an exception if an invalid host is specified in a cbits::Socket constructor.

Exceptions:
SocketException 

const bool Socket::isAvailable fd_set *    rd,
fd_set *    wr,
long int *    msec = 0,
int *    error = 0
const [protected]
 

Use the 'select' system call to determine if any of a set of file descriptors are available for reading or writing.

Returns:
true if the socket is available for the action (read or write) specified by the input file descriptor sets.
Parameters:
rdset  File descriptor set to check for readability
wrset  file descriptor set to check for writability
mmsec  The maximum number of milliseconds to wait for any of the descriptors to become available. zero or a negative number is interpreted to mean 'wait forever'.
error  An optional pointer to an integer that may hold the errno value of an error that occcurred, if any.

const bool Socket::isError   const [virtual]
 

Check the error status of thenetwork connection.

Generally, any error on a cbits::Socket should invalidate it.

Returns:
true if the network is not readable or writable due to an error condition. cbits::Socket::getError may be used to retrieve a human readable description of the error.

virtual const bool cbits::Socket::isReadable long int *    msec = 0,
int *const    error = 0
const [virtual]
 

Determine if the socket has data.

Arguments: -----------

error - optional pointer to an error flag that is updated to a non-zero value if an error occurs during the call.

Returns: ------------ true if the socket is readble (as determined by 'select'); otherwise, false.

Exceptions: ----------- none.

Parameters:
msec  An optional pointer to the maximum time to wait for the socket to become readable, in milliseconds. If provided, the method will not block for longer than the time specified and is adjusted for the time remaining (if any) when the call returns. If not specified, the method will block until the socket becomes readable.
error  An optional pointer to an integer that may hold the errno value of an error (if any) that occurred during the read.

virtual const bool cbits::Socket::isWritable long int *    msec = 0,
int *const    error = 0
const [virtual]
 

Determine if the socket can accept data.

Returns:
true if the socket is writable; otherwise, false.
Parameters:
msec  An optional pointer to the maximum time to wait for the socket to become writable, in milliseconds. If provided, the method will not block for longer than the time specified and is adjusted for the time remaining (if any) when the call returns. If not specified, the method will block until the socket becomes writable.
error  An optional pointer to an integer that may hold the errno value of an error (if any) that occurred during the read.

socket_t Socket::make_socket const char *    name,
const int    port,
const bool    now
throw ( SocketException ) [private]
 

Convenience method to instantiate a BSD socket.

Returns:
BSD socket descriptor.
Parameters:
h  hostname
p  port
connect_now  true if connect in this method

cbits::Socket::operator std::istream &   [inline]
 

Type conversion operator for when cbits::Socket needs to be used as a std::istream instance.

cbits::Socket::operator std::ostream &   [inline]
 

Type conversion operator for when cbits::Socket needs to be used as a std::ostream instance.

Socket& cbits::Socket::operator= const Socket &    [private]
 

const ssize_t Socket::read char *const    buffer,
const int    buflen,
int *const    error = 0,
const long    msec = 0
throw ( SocketException ) [virtual]
 

Read data from the network connection into a user-supplied buffer.

Returns:
0 if call timed out waiting for data; negative if an error occurred and no data was read (see error argument); otherwise, a positive integer indicating the number of bytes read. Even if data was successfully read from the socket, the error argument should be checked for errors.
Exceptions:
SocketException  if any invalid arguments are passed in.
Parameters:
buffer  User-supplied input buffer
buflen  Length of input buffer
error  An optional pointer to an integer that may hold the errno value of an error (if any) that occurred during the read.
msec  The maximum number of milliseconds to wait for data if no or insufficient data is available on the socket. An interval of 0 (zero) or less is interpreted as 'wait forever'.

Reimplemented in cbits::SSLSocket.

const ssize_t Socket::readLine std::string &    buffer,
const std::string &    delim,
int *const    error = 0,
const long int    msec = 0
throw ( SocketException ) [virtual]
 

Read from the network connection until a specified delimiter string is encountered.

For instance, readLine("\r
") would read from the socket up to the next CR-LF sequence.

set to the specific 'errno' value returned by the OS.

Returns:
0 if no data was read or the call timed out; a negative number if no bytes were read and an error occurred (if so, use the error parameter to determine the error); otherwise, a positive integer is returned indicating the number of bytes read.
Exceptions:
SocketException  if an error occurred while reading from the socket.
FIXME Socket.h readLine is not implemented. FIXME Socket.h Is it really necessary for readLine to throw a SocketException?
Parameters:
buffer  User-suplied buffer to hold data read from the socket.
delim  line delimiter; e.g. '
'
error  An optional pointer to an integer that may hold the errno value of an error (if any) that occurred during the read.
msec  The maximum number of milliseconds to wait for data if no or insufficient data is available on the socket. An interval of 0 (zero) or less is interpreted as 'wait forever'.

Reimplemented in cbits::SSLSocket.

virtual const ssize_t cbits::Socket::receive char *const    buffer,
const int    buflen,
const long int    msec = 0,
int *const    error = 0
throw ( SocketException ) [virtual]
 

Synonym for cbits::Socket::read with the error and msec argument positions reversed.

Reimplemented in cbits::SSLSocket.

unsigned long Socket::resolve_name const char *    [private]
 

Convenience method to convert a host name into an IP address.

Returns:
IP address of the host, or 0 if resolution fails.
Parameters:
h  DNS name or 'dot-IP' to resolve

const ssize_t Socket::send const char *    buffer,
const long    buflen,
const long int    msec = 0,
int *const    error = 0
throw ( SocketException ) [virtual]
 

Synonym for cbits::Socket::write with the error and msec argument positions reversed.

const bool Socket::set_blocking_off   [virtual]
 

set_blocking_off.

Configure the network connection such that calls to read data will not block if none is available and calls to write data will not block if the network connection can not immediately accept the data.

Returns:
true if the socket was configured to not block.

const bool Socket::set_blocking_on   [virtual]
 

Configure the network connection such that calls to read data will block if none is available and calls to write data will block if the network connection can not immediately accept the data.

Returns:
true if the socket was configured to block.

void cbits::Socket::set_bound const bool    val [inline, private]
 

void Socket::setGlobalLogger std::ostream *    os [static]
 

Set a global debug logging stream to be used by all Socket instances.

This does not override a Socket instance's specific logging stream if any.

This method is a useful way to provide a default logging stream to all Socket instances, without having to configure each instance separately, but still be able to set the logging stream for specific Socket instances.

void Socket::setLocalLogger std::ostream *    os const
 

Set a instance debug logging stream for this Socket.

Parameters:
os  output stream to log to.

const ssize_t Socket::write const char *    buffer,
const long    buflen,
int *const    error = 0,
const long int    msec = 0
throw ( SocketException ) [virtual]
 

Write a buffer of data to the network connection.

Returns:
the number of bytes written or a negative number if an error occurred,
Exceptions:
SocketException 
FIXME Socket.h does write() really need to throw a SocketException?
Parameters:
buffer  User-supplied buffer of data
buflen  Buffer length
error  An optional pointer to an integer that may hold the errno value of an error (if any) that occurred during the read.
msec  The maximum number of milliseconds to wait for data if no or insufficient data is available on the socket. An interval of 0 (zero) or less is interpreted as 'wait forever'.

Reimplemented in cbits::SSLSocket.


Friends And Related Function Documentation

friend class ServerSocket [friend]
 

Must be able to set _is_bound state.


Member Data Documentation

CriticalSection cbits::Socket::_csect [private]
 

Critical section used so synchronize non-read/write specific sections of code.

Reimplemented in cbits::SSLSocket.

bool cbits::Socket::_error [protected]
 

Last error that occurred.

std::string cbits::Socket::_errstr [protected]
 

Human readable descripton of _error.

std::ostream * Socket::_glogr = 0 [static, protected]
 

class-scoped logging stream.

struct sockaddr_in cbits::Socket::_host [protected]
 

Address of remote host.

std::iostream* cbits::Socket::_iostream [protected]
 

<iostream> rep of this Socket.

bool cbits::Socket::_is_bound [protected]
 

bool cbits::Socket::_is_connected [protected]
 

true if socket is connected.

std::ostream* cbits::Socket::_llogr [protected]
 

instance-scoped logging stream.

int cbits::Socket::_port [protected]
 

Port of remote host application.

CriticalSection cbits::Socket::_read_csect [private]
 

Critical section used to disallow more than one thread from reading data from the socket at a time.

Reimplemented in cbits::SSLSocket.

socket_t cbits::Socket::_sockfd [protected]
 

The BSD socket descriptor.

CriticalSection cbits::Socket::_write_csect [private]
 

Critical section used to disallow more than one thread from writing to the socket at a time.

Reimplemented in cbits::SSLSocket.


The documentation for this class was generated from the following files:
Generated by
doxygen
Hosted by
SourceForge