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.
Socket *	accept ()
	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:

• libppbase/base/Socket.h