Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members

Dv::Net::Socket Class Reference

Provide a network connection as an iostream. More...

#include <socket.h>

List of all members.

Public Types

enum  SOCKET_ERRORS {
  OK = 0, UNKNOWN_HOST = -1, CLOSED = -2, ACCEPT_ERROR = -3,
  WRONG_FAMILY = -4, EOFBIT = -5, BADBIT = -6, FAILBIT = -7,
  MAX_ERRNO = -7
}
 Status codes, positive numbers are reserved for copies of the system errno. More...

Public Member Functions

 Socket (const std::string &host, int port, size_t bufsz=1024, time_t delay=0, bool non_blocking=false, std::ostream *dbg=0)
 Set up a client connection to a host:port.
 Socket (const Socket &so)
 Copy ctor.
Dv::Util::ref< Socketdup ()
 See the copy constructor.
 ~Socket ()
 Also closes socket using close().
void close ()
 Close underlying socket.
bool connect (unsigned int delay=0)
 Try to (re)connect to the same host/port.
bool timedout () const
bool timedout (bool new_timedout_status)
 Set timedout flag.
int port () const
const std::string & host () const
bool connected () const
int error () const
virtual std::string strerror () const
 Return string representation of error().
Dv::Util::fdstreambufrdbuf () const
int sfd () const
std::ostream * debug (std::ostream *dbg)
 Set a stream to write debug information to.
std::ostream * debug ()

Static Public Member Functions

int mksocketfd (int &syserr)
 Create a new socket descriptor.

Protected Member Functions

int mkfd ()
 Create a new socket and return associated fd, or -1 upon failure.
void error (int e)
 Set error status.
 Socket (const std::string &host, int port, Dv::Util::fdstreambuf *buffer, std::ostream *dbg=0)
 Constructor for use by derived classes.
 Socket (Dv::Util::fdstreambuf *buffer, std::ostream *dbg=0)
 Constructor for use by derived classes.

Private Member Functions

Socketoperator= (const Socket &)
 No assignment.
bool get_peer ()
 Set host_ and port_.

Static Private Member Functions

Dv::Util::ref< Socketbuf2socket (Dv::Util::fdstreambuf *)
 Used by ServerSocket.

Private Attributes

std::string host_
 Host this socket refers to.
int port_
 Port number this socket refers to.
int errno_
 Error status of socket.
bool connected_
 Whether socket is connected.
std::ostream * debug_
 Pointer to debug output stream.


Detailed Description

Provide a network connection as an iostream.

Example usage:

   Socket       so("tinf2.vub.ac.be",8000)
   if (so) {
     so << "request" << endl;
     string line;
     while (getline(so,line))
       process_answer(line);
     if (so.timedout())
       cerr << "Connection timed out";
     }
   else {
     cerr << so.strerror() << endl;
     }

Definition at line 33 of file socket.h.


Member Enumeration Documentation

enum Dv::Net::Socket::SOCKET_ERRORS
 

Status codes, positive numbers are reserved for copies of the system errno.

Enumeration values:
OK 
UNKNOWN_HOST 
CLOSED 
ACCEPT_ERROR 
WRONG_FAMILY 
EOFBIT 
BADBIT 
FAILBIT 
MAX_ERRNO 
Definition at line 38 of file socket.h.


Constructor & Destructor Documentation

Dv::Net::Socket::Socket const std::string &  host,
int  port,
size_t  bufsz = 1024,
time_t  delay = 0,
bool  non_blocking = false,
std::ostream *  dbg = 0
 

Set up a client connection to a host:port.

Parameters:
host name of host to connect to.
port number of port to connect to.
bufsz size (in bytes) of input and output buffers.
delay (in milliseconds) time allowed for any I/O operation to complete. A value of 0 means ``wait forever''. Note that timedout() makes no sense if delay is 0.
non_blocking if true, the underlying fdstreambuf will be non-blocking which prevents some cases of blocking I/O operations.
dbg pointer to stream to write debug to or 0
See also:
timedout, connected, Dv::Util::fdstreambuf, debug

Dv::Net::Socket::Socket const Socket so  ) 
 

Copy ctor.

This function constructs a new Socket (iostream) and associated fdstreambuf, based a new filedescriptor, obtained from this Socket's file descriptor This function was introduced to allow concurrent reading and writing to a connection (from different threads). Experiments to do this failed when using the same Socket object. If the writer uses a copy of the original (which is used by the reader), the experiment works fine.

Parameters:
so socket whose file descriptor will be used to construct a ``copy''
Warning:
Closing a socket also shuts it down using shutdown(2) with the SHUT_RDWR option, making all copies of this Socket unusable. However, the underlying file descriptors of these copies are not closed. To avoid a memory leak, they should be closed as well.

Dv::Net::Socket::~Socket  ) 
 

Also closes socket using close().

See also:
close()

Dv::Net::Socket::Socket const std::string &  host,
int  port,
Dv::Util::fdstreambuf buffer,
std::ostream *  dbg = 0
[protected]
 

Constructor for use by derived classes.

This constructor can e.g. be used by a Dv::Socket specialization that encrypts the data traffic (by means of a class derived from fdstreambuf). This function does not attempt to connect to the given host/port.

Parameters:
host name of host to connect to.
port number of port to connect to.
buffer fdstreambuf to use. This buffer must have been dynamically allocated because Socket::~Socket() will delete it.
dbg pointer to stream to write debug to or 0
See also:
Socket::Socket, debug

Dv::Net::Socket::Socket Dv::Util::fdstreambuf buffer,
std::ostream *  dbg = 0
[protected]
 

Constructor for use by derived classes.

This constructor can e.g. be used by a Dv::Socket specialization that encrypts the data traffic (by means of a class derived from fdstreambuf). Socket::get_peer() will be used to fill in host and port.

Parameters:
buffer fdstreambuf to use. This buffer must have been dynamically allocated because Socket::~Socket() will delete it.
dbg pointer to stream to write debug to or 0
See also:
get_peer, debug


Member Function Documentation

Dv::Util::ref<Socket> Dv::Net::Socket::dup  ) 
 

See the copy constructor.

Returns:
reference to copy of this Socket
See also:
Socket::Socket(const Socket& so)

void Dv::Net::Socket::close  ) 
 

Close underlying socket.

This also does a shutdown(2) with the SHUT_RDWR which prevents any transmissions and should make all pending I/O calls return with an error.

See also:
~Socket

bool Dv::Net::Socket::connect unsigned int  delay = 0  ) 
 

Try to (re)connect to the same host/port.

Parameters:
delay (in milliseconds) time allowed for the connection to complete. A value of 0 means ``wait forever''.
Returns:
true iff the connect operation succeeded.
If the constructor failed, it is possible to retry using connect(). This may occur e.g. if the client is able to launch the server. Note the delay parameter: when launching the server, at least Solaris 7 needs a delay (e.g. 3 seems to work find).

bool Dv::Net::Socket::timedout  )  const
 

Returns:
true iff last operation timed out
See also:
Socket::Socket()

bool Dv::Net::Socket::timedout bool  new_timedout_status  ) 
 

Set timedout flag.

Usually, the argument will be "false", such that further I/O on the socket becomes possible.

Parameters:
new_timedout_status: true or (usually) false
Returns:
true iff status change succeeded. It will fail e.g. if the argument is "false" and the socket had not actually timed out, or if the argument is "true" and socket status was not Socket::OK.
 ref<Socket> s;
 size_t try(0);

 while ( (! getline(*s, line) ) && (++try <3) )
   if (s->timedout()) {
     s->timedout(false);
   else {
         std::cerr << "I/O error: " << s->strerror() << std::endl;
     break;
     } 
See also:
Socket::Socket() Socket::timedout()

int Dv::Net::Socket::port  )  const [inline]
 

Returns:
port number of Socket.
Definition at line 141 of file socket.h.

References port_.

const std::string& Dv::Net::Socket::host  )  const [inline]
 

Returns:
host name of Socket.
Definition at line 145 of file socket.h.

References host_.

bool Dv::Net::Socket::connected  )  const [inline]
 

Returns:
true iff last call to connect() was succesful.
See also:
connect, Socket::Socket
Definition at line 150 of file socket.h.

References connected_.

int Dv::Net::Socket::error  )  const
 

Returns:
status of Socket, only 0 is ok.
A status of 0 means ok, positive integers correspond to system errno values (man 2 errno). Negative numbers correspond to ``specific'' errors for the Socket class (or its subclasses).

The values EOFBIT, FAILBIT or BADBIT will be returned if the corresponding bit in iostate is turned on and no other specific error was detected.

See also:
SOCKET_ERRORS

virtual std::string Dv::Net::Socket::strerror  )  const [virtual]
 

Return string representation of error().

This function is virtual because subclasses may want to add their own error messages (but the convention of using negative numbers for local error codes and positive ones for ::errno values should be adhered to).

Dv::Util::fdstreambuf* Dv::Net::Socket::rdbuf  )  const [inline]
 

Returns:
fdstreambuf associated with this socket or 0 if none.
Definition at line 176 of file socket.h.

Referenced by sfd().

int Dv::Net::Socket::sfd  )  const [inline]
 

Returns:
underlying file descriptor (may be <0 if no connection).
Definition at line 181 of file socket.h.

References Dv::Util::fdstreambuf::fd(), and rdbuf().

int Dv::Net::Socket::mksocketfd int &  syserr  )  [static]
 

Create a new socket descriptor.

Parameters:
syserr will contain system errorcode (::errno) if the socket could not be created (and the return value is -1).
Returns:
descriptor of a new socket or -1.
See also:
socket(2)

std::ostream* Dv::Net::Socket::debug std::ostream *  dbg  ) 
 

Set a stream to write debug information to.

A parameter 0 is allowed and will turn off debugging. Note that this debug status is independent of the Socket::rdbuf()->debug() facility which can be used independently.

Parameters:
dbg pointer to stream to write debug to or 0
Returns:
previous value of debug()

std::ostream* Dv::Net::Socket::debug  ) 
 

Returns:
pointer to current debug stream or 0.

int Dv::Net::Socket::mkfd  )  [protected]
 

Create a new socket and return associated fd, or -1 upon failure.

Upon failure, error will be set to the systems's errno.

Returns:
descriptor of a new socket or -1.
See also:
mksocketfd, error

void Dv::Net::Socket::error int  e  )  [protected]
 

Set error status.

Parameters:
e new error status.
See also:
error()

Socket& Dv::Net::Socket::operator= const Socket  )  [private]
 

No assignment.

bool Dv::Net::Socket::get_peer  )  [private]
 

Set host_ and port_.

See also:
getpeername(2).

Dv::Util::ref<Socket> Dv::Net::Socket::buf2socket Dv::Util::fdstreambuf  )  [static, private]
 

Used by ServerSocket.


Member Data Documentation

std::string Dv::Net::Socket::host_ [private]
 

Host this socket refers to.

Definition at line 253 of file socket.h.

Referenced by host().

int Dv::Net::Socket::port_ [private]
 

Port number this socket refers to.

Definition at line 257 of file socket.h.

Referenced by port().

int Dv::Net::Socket::errno_ [mutable, private]
 

Error status of socket.

See also:
error()
Definition at line 262 of file socket.h.

bool Dv::Net::Socket::connected_ [private]
 

Whether socket is connected.

See also:
connected()
Definition at line 267 of file socket.h.

Referenced by connected().

std::ostream* Dv::Net::Socket::debug_ [private]
 

Pointer to debug output stream.

See also:
debug()
Definition at line 272 of file socket.h.


The documentation for this class was generated from the following file:
dvnet-0.9.11 [27 December, 2004]