GNet::Socket Class Reference

The Socket class encapsulates a non-blocking Unix socket file descriptor or a Windows 'SOCKET' handle. More...

#include <gsocket.h>

Inheritance diagram for GNet::Socket:

GNet::DatagramSocket GNet::StreamSocket

List of all members.

Public Types

typedef size_t size_type
typedef ssize_t ssize_type

Public Member Functions

virtual ~Socket ()
 Destructor.
bool valid () const
 Returns true if the socket handle is valid (open).
std::pair< bool, AddressgetLocalAddress () const
 Retrieves local address of the socket.
std::pair< bool, AddressgetPeerAddress () const
 Retrieves address of socket's peer.
bool hasPeer () const
 Returns true if the socket has a valid peer.
bool bind (const Address &address)
 Binds the socket with an INADDR_ANY network address and the port number taken from the given address.
bool canBindHint (const Address &address)
 Returns true if the socket can probably be bound with the given address.
bool connect (const Address &addr, bool *done=NULL)
 Initiates a connection to (or association with) the given address.
bool listen (int backlog=1)
 Starts the socket listening on the bound address for incoming connections or incoming datagrams.
virtual ssize_type write (const char *buf, size_type len)
 Sends data.
bool eWouldBlock ()
 Returns true if the previous socket operation failed with the EWOULDBLOCK or EGAIN error status.
bool eInProgress ()
 Returns true if the previous socket operation failed with the EINPROGRESS error status.
bool eMsgSize ()
 Returns true if the previous socket operation failed with the EMSGSIZE error status.
void addReadHandler (EventHandler &handler)
 Adds this socket to the event source list so that the given handler receives read events.
void dropReadHandler ()
 Reverses addReadHandler().
void addWriteHandler (EventHandler &handler)
 Adds this socket to the event source list so that the given handler receives write events when flow control is released.
void dropWriteHandler ()
 Reverses addWriteHandler().
void addExceptionHandler (EventHandler &handler)
 Adds this socket to the event source list so that the given handler receives exception events.
void dropExceptionHandler ()
 Reverses addExceptionHandler().
std::string asString () const
 Returns the socket handle as a string.
std::string reasonString () const
 Returns the failure reason as a string.
void shutdown (bool for_writing=true)
 Shuts the socket for writing (or reading).
int fd (Credentials) const
 Returns the socket descriptor as an integer.

Protected Member Functions

 Socket (int domain, int type, int protocol)
 Constructor used by derived classes.
 Socket (Descriptor s)
 Constructor which creates a socket object from an existing socket handle.
void prepare ()
void setFault ()
void setNoLinger ()
void setReuse ()
void setKeepAlive ()
std::pair< bool, AddressgetAddress (bool) const

Static Protected Member Functions

static bool valid (Descriptor s)
static int reason ()
static bool error (int rc)
static bool sizeError (ssize_type size)

Protected Attributes

int m_reason
Descriptor m_socket

Classes

class  Credentials
 A credentials class that allows SocketProtocol to call Socket::fd(). More...


Detailed Description

The Socket class encapsulates a non-blocking Unix socket file descriptor or a Windows 'SOCKET' handle.

The class hides all differences between BSD sockets and Winsock.

(Non-blocking network i/o is particularly appropriate for single- threaded server processes which manage multiple client connections. The main disagvantage is that flow control has to be managed explicitly: see Socket::write() and Socket::eWouldBlock().)

Exceptions are not used.

Definition at line 55 of file gsocket.h.


Member Typedef Documentation

typedef size_t GNet::Socket::size_type

Reimplemented in GNet::StreamSocket.

Definition at line 58 of file gsocket.h.

typedef ssize_t GNet::Socket::ssize_type

Reimplemented in GNet::StreamSocket.

Definition at line 59 of file gsocket.h.


Constructor & Destructor Documentation

GNet::Socket::~Socket (  )  [virtual]

Destructor.

Definition at line 63 of file gsocket.cpp.

References G_ASSERT, and valid().

GNet::Socket::Socket ( int  domain,
int  type,
int  protocol 
) [protected]

Constructor used by derived classes.

Opens the socket using socket().

Definition at line 29 of file gsocket.cpp.

References G_DEBUG, m_reason, m_socket, prepare(), reason(), and valid().

GNet::Socket::Socket ( Descriptor  s  )  [explicit, protected]

Constructor which creates a socket object from an existing socket handle.

Used only by StreamSocket::accept().

Definition at line 44 of file gsocket.cpp.

References prepare().


Member Function Documentation

bool GNet::Socket::valid (  )  const

Returns true if the socket handle is valid (open).

Definition at line 90 of file gsocket.cpp.

References m_socket.

Referenced by GNet::StreamSocket::accept(), addExceptionHandler(), addReadHandler(), addWriteHandler(), bind(), connect(), getAddress(), prepare(), GNet::StreamSocket::read(), Socket(), and ~Socket().

std::pair< bool, GNet::Address > GNet::Socket::getLocalAddress (  )  const

Retrieves local address of the socket.

Pair.first is false on error.

Definition at line 228 of file gsocket.cpp.

References getAddress().

Referenced by bind(), and GNet::SimpleClient::localAddress().

std::pair< bool, GNet::Address > GNet::Socket::getPeerAddress (  )  const

Retrieves address of socket's peer.

'Pair.first' is false on error.

Definition at line 233 of file gsocket.cpp.

References getAddress().

Referenced by hasPeer(), and GNet::SimpleClient::peerAddress().

bool GNet::Socket::hasPeer (  )  const

Returns true if the socket has a valid peer.

This can be used to see if a connect succeeded.

Definition at line 238 of file gsocket.cpp.

References getPeerAddress().

Referenced by GNet::SimpleClient::writeEvent().

bool GNet::Socket::bind ( const Address address  ) 

Binds the socket with an INADDR_ANY network address and the port number taken from the given address.

This is used for listening sockets.

Definition at line 95 of file gsocket.cpp.

References GNet::Address::address(), GNet::Address::displayString(), error(), G_DEBUG, G_WARNING, getLocalAddress(), GNet::Address::length(), m_reason, m_socket, reason(), setReuse(), and valid().

Referenced by canBindHint().

bool GNet::Socket::canBindHint ( const Address address  ) 

Returns true if the socket can probably be bound with the given address.

Some implementations will always return true. This method should be used on a temporary socket of the correct dynamic type since this socket may become unusable.

Definition at line 97 of file gsocket_unix.cpp.

References bind().

Referenced by GNet::Server::canBind().

bool GNet::Socket::connect ( const Address addr,
bool *  done = NULL 
)

Initiates a connection to (or association with) the given address.

Returns false on error.

If successful, a 'done' flag is returned by reference indicating whether the connect completed immediately. Normally a stream socket connection will take some time to complete so the 'done' flag will be false: the completion will be indicated by a write event some time later.

For datagram sockets this sets up an association between two addresses. The socket should first be bound with a local address.

Definition at line 128 of file gsocket.cpp.

References GNet::Address::address(), GNet::Address::displayString(), eInProgress(), error(), G_DEBUG, GNet::Address::length(), m_reason, m_socket, reason(), and valid().

Referenced by GNet::DatagramSocket::disconnect().

bool GNet::Socket::listen ( int  backlog = 1  ) 

Starts the socket listening on the bound address for incoming connections or incoming datagrams.

Definition at line 195 of file gsocket.cpp.

References error(), m_reason, m_socket, and reason().

GNet::Socket::ssize_type GNet::Socket::write ( const char *  buf,
size_type  len 
) [virtual]

Sends data.

For datagram sockets the datagram is sent to the address specified in the previous connect(). Returns the amount of data submitted.

If write() returns -1 then use eWouldBlock() to determine whether there was a flow control problem. If write() returns -1 and eWouldBlock() returns false then the connection is lost and the socket should be closed. If write() returns less than 'len' then assume that there was a partial flow control problem (do not use eWouldBlock()).

This method is virtual to allow overloading (sic) in derived classes.

Definition at line 153 of file gsocket.cpp.

References G_DEBUG, G_WARNING, m_reason, m_socket, reason(), and sizeError().

Referenced by GNet::DatagramSocket::write().

bool GNet::Socket::eWouldBlock (  ) 

Returns true if the previous socket operation failed with the EWOULDBLOCK or EGAIN error status.

When writing this indicates a flow control problem; when reading it indicates that there is nothing to read.

Definition at line 77 of file gsocket_unix.cpp.

References m_reason.

bool GNet::Socket::eInProgress (  ) 

Returns true if the previous socket operation failed with the EINPROGRESS error status.

When connecting this can be considered a non-error.

Definition at line 82 of file gsocket_unix.cpp.

References m_reason.

Referenced by connect().

bool GNet::Socket::eMsgSize (  ) 

Returns true if the previous socket operation failed with the EMSGSIZE error status.

When writing to a datagram socket this indicates that the message was too big to send atomically.

Definition at line 87 of file gsocket_unix.cpp.

References m_reason.

void GNet::Socket::addReadHandler ( EventHandler handler  ) 

Adds this socket to the event source list so that the given handler receives read events.

Definition at line 243 of file gsocket.cpp.

References GNet::EventLoop::addRead(), G_ASSERT, G_DEBUG, GNet::EventLoop::instance(), m_socket, and valid().

Referenced by GNet::SimpleClient::writeEvent().

void GNet::Socket::dropReadHandler (  ) 

Reverses addReadHandler().

Definition at line 250 of file gsocket.cpp.

References GNet::EventLoop::dropRead(), GNet::EventLoop::instance(), and m_socket.

void GNet::Socket::addWriteHandler ( EventHandler handler  ) 

Adds this socket to the event source list so that the given handler receives write events when flow control is released.

(Not used for datagram sockets.)

Definition at line 255 of file gsocket.cpp.

References GNet::EventLoop::addWrite(), G_ASSERT, G_DEBUG, GNet::EventLoop::instance(), m_socket, and valid().

void GNet::Socket::dropWriteHandler (  ) 

void GNet::Socket::addExceptionHandler ( EventHandler handler  ) 

Adds this socket to the event source list so that the given handler receives exception events.

An exception event should be treated as a disconnection event. (Not used for datagram sockets.)

Definition at line 262 of file gsocket.cpp.

References GNet::EventLoop::addException(), G_ASSERT, G_DEBUG, GNet::EventLoop::instance(), m_socket, and valid().

Referenced by GNet::SimpleClient::writeEvent().

void GNet::Socket::dropExceptionHandler (  ) 

std::string GNet::Socket::asString (  )  const

Returns the socket handle as a string.

Only used in debugging.

Definition at line 279 of file gsocket.cpp.

References m_socket.

std::string GNet::Socket::reasonString (  )  const

Returns the failure reason as a string.

Only used in debugging.

Definition at line 286 of file gsocket.cpp.

References m_reason.

void GNet::Socket::shutdown ( bool  for_writing = true  ) 

Shuts the socket for writing (or reading).

Definition at line 293 of file gsocket.cpp.

References m_socket.

int GNet::Socket::fd ( Credentials   )  const

Returns the socket descriptor as an integer.

Only callable from SocketProtocol.

Definition at line 298 of file gsocket.cpp.

References m_socket.

bool GNet::Socket::valid ( Descriptor  s  )  [static, protected]

Definition at line 32 of file gsocket_unix.cpp.

int GNet::Socket::reason (  )  [static, protected]

bool GNet::Socket::error ( int  rc  )  [static, protected]

Definition at line 67 of file gsocket_unix.cpp.

Referenced by bind(), connect(), GNet::DatagramSocket::disconnect(), getAddress(), and listen().

bool GNet::Socket::sizeError ( ssize_type  size  )  [static, protected]

Definition at line 72 of file gsocket_unix.cpp.

Referenced by GNet::DatagramSocket::read(), GNet::StreamSocket::read(), and write().

void GNet::Socket::prepare (  )  [protected]

Definition at line 51 of file gsocket.cpp.

References G_ASSERT, G_WARNING, G::Cleanup::init(), m_reason, reason(), and valid().

Referenced by Socket().

void GNet::Socket::setFault (  )  [protected]

Definition at line 92 of file gsocket_unix.cpp.

References m_reason.

void GNet::Socket::setNoLinger (  )  [protected]

Definition at line 173 of file gsocket.cpp.

References m_socket.

Referenced by GNet::StreamSocket::StreamSocket().

void GNet::Socket::setReuse (  )  [protected]

Definition at line 189 of file gsocket.cpp.

References m_socket.

Referenced by bind().

void GNet::Socket::setKeepAlive (  )  [protected]

Definition at line 182 of file gsocket.cpp.

References m_socket.

Referenced by GNet::StreamSocket::StreamSocket().

std::pair< bool, GNet::Address > GNet::Socket::getAddress ( bool  local  )  const [protected]


Member Data Documentation

int GNet::Socket::m_reason [protected]


The documentation for this class was generated from the following files:

Generated on Fri Apr 18 15:56:13 2008 for E-MailRelay by  doxygen 1.5.5