Home

C-Bits Package Documentation

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:

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

Hosted by

cbits::Socket Class Reference

Public Methods

Static Public Methods

Protected Methods

Protected Attributes

Static Protected Attributes

Private Methods

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation