Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes

base::Socket Class Reference

A socket class for TCP/IP sockets. More...

#include <libppbase/base/Socket.h>

List of all members.

Public Types

typedef int socket_type
 socket type
typedef socklen_t socklen_type
 socket size type

Public Member Functions

 Socket (socket_type sd=invalid_socket, int tout_acc=60, int tout_conn=60, int tout_recv=60, int tout_send=60)
 Constructor.
 ~Socket ()
 Destructor.
Socketaccept ()
 Accept a new connection.
void close ()
 Closes the socket.
void connect (struct sockaddr *addr, socklen_type len)
 Connects to a remote service.
void connect (const String &host, int port=0)
 Connects to a remote service.
bool connected () const
 Checks if this socket is connected to a remote service.
void discard ()
 Discards data that is still to be sent over the socket (clears the write buffer).
bool eof () const
 Checks if an end-of-file occurred on this socket.
void flush ()
 Flushes unwritten data.
socket_type getSD () const
 Returns the file descriptor associated with this socket.
String getLocalAddr (bool full=false)
 Returns the local address.
String getLocalIP ()
 Returns the local IP address.
String getLocalIPPort ()
 Returns the local IP address and port number.
int getLocalPort ()
 Returns the local port number.
String getRemoteAddr (bool full=false)
 Returns the remote address.
String getRemoteIP ()
 Returns the remote IP address.
String getRemoteIPPort ()
 Returns the remote IP address and port number.
int getRemotePort ()
 Returns the remote port number.
void open (int type=SOCK_STREAM, int port=-1, int listenq=-1, const char *ip=NULL)
 Opens a socket.
void open (int type, const char *addr, int listenq=-1)
 Opens a socket.
size_t read (char *buf, size_t len)
 Reads data from the socket.
size_t read (String &buf, size_t len)
 Reads data from the socket.
void readEOF (String &ret)
 Reads data until end-of-file occurrs.
bool readln (String &line, bool strip=false)
 Reads a line from the socket.
void relay (socket_type sd, int timeout=0)
 Relays data between this socket and sd.
void relay (Socket &sock, int timeout=0)
 Relays data between this socket and sock.
void setBlocking (bool blocking)
 Sets or clears blocking flag.
void setSD (socket_type sd)
 Associates this socket with an open file descriptor.
void setReadBuffer (size_t len)
 Changes the size of the read buffer.
void setWriteBuffer (size_t len)
 Changes the size of the write buffer.
void setTimeout (int tout_acc, int tout_conn, int tout_recv, int tout_send)
 Sets new timeout values.
void write (const char *buf, size_t len)
 Writes to the socket.
void write (const String &s)
 Writes to the socket.
size_t writef (const char *fmt,...)
 Writes to the socket.
size_t writevf (const char *fmt, va_list ap)
 Writes to the socket.

Static Public Member Functions

static void finit ()
 Finishes the use of the socket library.
static void init ()
 Initializes the use of the socket library.
static socket_type openInet (int type=SOCK_STREAM, int port=-1, int listenq=-1, const char *ip=NULL)
 Opens an internet (IP) socket.
static socket_type openUnix (int type, int port=-1, int listenq=-1)
 Opens a UNIX domain socket.
static socket_type openUnix (int type=SOCK_STREAM, const char *path=NULL, int listenq=-1)
 Opens a UNIX domain socket.
static void readEOF (int fd, String &ret, int timeout=0)
 Reads data from the given file descriptor until end-of-file occurrs.
static size_t readto (socket_type sd, char *buf, size_t len, int timeout)
 Reads some data from the given file descriptor.
static void setBlocking (socket_type sd, bool blocking)
 Sets or clears blocking flag.
static size_t writeto (socket_type sd, const char *buf, size_t len, int timeout)
 Writes some data from the given socket.

Static Public Attributes

static const socket_type invalid_socket = -1
 invalid socket identifier

Detailed Description

A socket class for TCP/IP sockets.

Author:
Christoph Schwarz
Version:
$Id: Socket.h 21 2010-09-05 04:18:17Z cschwarz1 $

Constructor & Destructor Documentation

base::Socket::Socket ( socket_type  sd = invalid_socket,
int  tout_acc = 60,
int  tout_conn = 60,
int  tout_recv = 60,
int  tout_send = 60 
)

Constructor.

Parameters:
sd open file descriptor, invalid_socket for new socket
tout_acc accept timeout for new connections in seconds, 0 means infinite
tout_conn connect timeout to remote services in seconds, 0 means infinite
tout_recv receive timeout in seconds, 0 means infinite
tout_send send timeout in seconds, 0 means infinite

Member Function Documentation

Socket* base::Socket::accept (  ) 

Accept a new connection.

The socket must be a server socket, created with the open method

Returns:
a new connection
void base::Socket::connect ( const String host,
int  port = 0 
)

Connects to a remote service.

Parameters:
host host name or ip address, optional port number may be appended with a colon
port the port number of the remote service, can also be appended to host
void base::Socket::connect ( struct sockaddr *  addr,
socklen_type  len 
)

Connects to a remote service.

Parameters:
addr address of the remote service
len address length
bool base::Socket::connected (  )  const

Checks if this socket is connected to a remote service.

Returns:
true if connected
void base::Socket::discard (  ) 

Discards data that is still to be sent over the socket (clears the write buffer).

Use this method when you want to delete a socket after a socket error occurred, especially a send timeout. If you do not use this method, the object tries to flush the write buffer when closing the socket, probably causing an unwanted application delay because of a second send timeout.

bool base::Socket::eof (  )  const

Checks if an end-of-file occurred on this socket.

Returns:
true if eof occurred
static void base::Socket::finit (  )  [static]

Finishes the use of the socket library.

Calls WSACleanup() under windows, does nothing under linux

String base::Socket::getLocalAddr ( bool  full = false  ) 

Returns the local address.

Parameters:
full flag: get full address
Returns:
local address
String base::Socket::getLocalIP (  ) 

Returns the local IP address.

Returns:
local IP address in dot-number format
String base::Socket::getLocalIPPort (  ) 

Returns the local IP address and port number.

Returns:
local IP address in dot-number format, port number appended with a colon
int base::Socket::getLocalPort (  ) 

Returns the local port number.

Returns:
local port number
String base::Socket::getRemoteAddr ( bool  full = false  ) 

Returns the remote address.

Parameters:
full flag: get full address
Returns:
remote address
String base::Socket::getRemoteIP (  ) 

Returns the remote IP address.

Returns:
remote IP address in dot-number format
String base::Socket::getRemoteIPPort (  ) 

Returns the remote IP address and port number.

Returns:
remote IP address in dot-number format, port number appended with a colon
int base::Socket::getRemotePort (  ) 

Returns the remote port number.

Returns:
remote port number
socket_type base::Socket::getSD (  )  const

Returns the file descriptor associated with this socket.

Returns:
invalid_socket if there is none, e.g. because the socket is not connected or open
static void base::Socket::init (  )  [static]

Initializes the use of the socket library.

Calls WSAStartup() under windows, does nothing under linux

void base::Socket::open ( int  type = SOCK_STREAM,
int  port = -1,
int  listenq = -1,
const char *  ip = NULL 
)

Opens a socket.

The purpose of this method is to open a server socket

Parameters:
type socket type, SOCK_STREAM for TCP, or SOCK_DGRAM for UDP
port desired port number, 0 means the system picks one, -1 means not to bind to a port right now
listenq number of entries in the listen queue for server sockets, -1 means no server socket
ip local IP address to bind to, NULL means to bind to all IP addresses
void base::Socket::open ( int  type,
const char *  addr,
int  listenq = -1 
)

Opens a socket.

The purpose of this method is to open a server socket

Parameters:
type socket type, SOCK_STREAM for TCP, or SOCK_DGRAM for UDP
addr for IP sockets: [<addr>:]<port>, for UNIX sockets: [=|/]<port_or_path>
listenq number of entries in the listen queue for server sockets, -1 means no server socket
static socket_type base::Socket::openInet ( int  type = SOCK_STREAM,
int  port = -1,
int  listenq = -1,
const char *  ip = NULL 
) [static]

Opens an internet (IP) socket.

The purpose of this method is to open a server socket

Parameters:
type socket type, SOCK_STREAM for TCP, or SOCK_DGRAM for UDP
port desired port number, 0 means the system picks one, -1 means not to bind to a port right now
listenq number of entries in the listen queue for server sockets, -1 means no server socket
ip local IP address to bind to, NULL means to bind to all IP addresses
Returns:
file descriptor of open socket
static socket_type base::Socket::openUnix ( int  type,
int  port = -1,
int  listenq = -1 
) [static]

Opens a UNIX domain socket.

The purpose of this method is to open a server socket

Parameters:
type socket type, SOCK_STREAM for stream oriented, or SOCK_DGRAM for datagram
port desired port number, -1 mean not to allocate a port
listenq number of entries in the listen queue for server sockets, -1 means no server socket
Returns:
file descriptor of open socket
static socket_type base::Socket::openUnix ( int  type = SOCK_STREAM,
const char *  path = NULL,
int  listenq = -1 
) [static]

Opens a UNIX domain socket.

The purpose of this method is to open a server socket

Parameters:
type socket type, SOCK_STREAM for stream oriented, SOCK_DGRAM for datagram-oriented
path the path to bind the socket to
listenq number of entries in the listen queue for server sockets, -1 means no server socket
Returns:
file descriptor of open socket
size_t base::Socket::read ( char *  buf,
size_t  len 
)

Reads data from the socket.

Parameters:
buf buffer to read the data into
len maximum number of bytes to read
Returns:
number of bytes actually read, 0 means end-of-file (=the peer closed the connection)
size_t base::Socket::read ( String buf,
size_t  len 
)

Reads data from the socket.

Parameters:
buf buffer to read the data into
len maximum number of bytes to read
Returns:
number of bytes actually read, 0 means end-of-file (=the peer closed the connection)
static void base::Socket::readEOF ( int  fd,
String ret,
int  timeout = 0 
) [static]

Reads data from the given file descriptor until end-of-file occurrs.

Parameters:
fd the file descriptor to read from
ret the string that contains all read data
timeout timeout in seconds, 0 means infinite
void base::Socket::readEOF ( String ret  ) 

Reads data until end-of-file occurrs.

Parameters:
ret the string that contains all read data
bool base::Socket::readln ( String line,
bool  strip = false 
)

Reads a line from the socket.

Parameters:
line the line read from the socket
strip flag: strip cr/lf from end of line
Returns:
false means end-of-file (=the peer closed the connection)
static size_t base::Socket::readto ( socket_type  sd,
char *  buf,
size_t  len,
int  timeout 
) [static]

Reads some data from the given file descriptor.

Parameters:
sd the file descriptor to read from
buf buffer to read the data into
len maximum number of bytes to read
timeout timeout in seconds, 0 means infinite
Returns:
number of bytes actually read, 0 means end-of-file (=the peer closed the connection)
void base::Socket::relay ( Socket sock,
int  timeout = 0 
)

Relays data between this socket and sock.

Parameters:
sock the other socket
timeout timeout in seconds, 0 means infinite
void base::Socket::relay ( socket_type  sd,
int  timeout = 0 
)

Relays data between this socket and sd.

Parameters:
sd the other socket
timeout timeout in seconds, 0 means infinite
static void base::Socket::setBlocking ( socket_type  sd,
bool  blocking 
) [static]

Sets or clears blocking flag.

Parameters:
sd socket to set flag
blocking true=blocking, false=non-blocking
void base::Socket::setBlocking ( bool  blocking  ) 

Sets or clears blocking flag.

Parameters:
blocking true=blocking, false=non-blocking
void base::Socket::setReadBuffer ( size_t  len  ) 

Changes the size of the read buffer.

The initial read buffer is 4096 bytes.

Parameters:
len new size in bytes
void base::Socket::setSD ( socket_type  sd  ) 

Associates this socket with an open file descriptor.

Parameters:
sd the open file descriptor
void base::Socket::setTimeout ( int  tout_acc,
int  tout_conn,
int  tout_recv,
int  tout_send 
)

Sets new timeout values.

Parameters:
tout_acc accept timeout for new connections in seconds, 0 means infinite
tout_conn connect timeout to remote services in seconds, 0 means infinite
tout_recv receive timeout in seconds, 0 means infinite
tout_send send timeout in seconds, 0 means infinite
void base::Socket::setWriteBuffer ( size_t  len  ) 

Changes the size of the write buffer.

A write buffer improves performance when sending lots of data in small portions (e.g. byte by byte). Usually a write buffer of 1024 to 4096 bytes is sufficient. Initially there is no write buffer, this means all data written is immediately written to the socket.

Parameters:
len new size in bytes
void base::Socket::write ( const char *  buf,
size_t  len 
)

Writes to the socket.

Parameters:
buf data to write
len number of bytes to write
void base::Socket::write ( const String s  ) 

Writes to the socket.

Parameters:
s data to write
size_t base::Socket::writef ( const char *  fmt,
  ... 
)

Writes to the socket.

Parameters:
fmt printf-like format string
... parameters for the format string
Returns:
number of bytes written
static size_t base::Socket::writeto ( socket_type  sd,
const char *  buf,
size_t  len,
int  timeout 
) [static]

Writes some data from the given socket.

Parameters:
sd the socket to write to
buf buffer to write
len number of bytes to write
timeout timeout in seconds, 0 means infinite
Returns:
number of bytes actually written
size_t base::Socket::writevf ( const char *  fmt,
va_list  ap 
)

Writes to the socket.

Parameters:
fmt printf-like format string
ap parameters for the format string
Returns:
number of bytes written

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