Wavepacket Sockets API [Networking Libraries]

This is a quick and dirty sockets-like API to abstract the netlib implementation from operating-system-specific issues. More...

Collaboration diagram for Wavepacket Sockets API:

Classes
struct	netlib::ip_addr_t
	representation of IP address (abstracts IPv4 and IPv6) More...
struct	netlib::address_t
	holds the IP address and port of a remote host More...
Typedefs
typedef std::map< std::string, ip_addr_t >	netlib::map_ip_addr_t
	a map of IP addresses (typically interface name --> IP address)
typedef void *	netlib::ws_set_t
Enumerations
enum	netlib::eWSError {   netlib::eWS_Okay = 0,   netlib::eWS_Again = 1,   netlib::eWS_Denied = 2,   netlib::eWS_InUse = 3,   netlib::eWS_ConnectionRefused = 4,   netlib::eWS_Unknown = 0x100,   netlib::eWS_Invalid = 0x7ff }
	these are error codes. More...
Functions
	netlib::ip_addr_t::ip_addr_t (void) throw ()
void	netlib::ip_addr_t::clear (void) throw ()
eType	netlib::ip_addr_t::getType (void) const throw ()
bool	netlib::ip_addr_t::isValid (void) const throw ()
bool	netlib::ip_addr_t::operator!= (IN const ip_addr_t &rhs) const throw ()
bool	netlib::ip_addr_t::operator== (IN const ip_addr_t &rhs) const throw ()
void	netlib::ip_addr_t::dump (IN const char *title) const throw ()
bool	netlib::ip_addr_t::lookupHostname (IN const char *hostname)
	attempts to look up the IP of the remote host.
bool	netlib::ip_addr_t::isLoopback (void) const throw ()
	is this just a loopback IP address? (127.0.0.1 for IPv4)
void	netlib::ip_addr_t::setLoopback (void) throw ()
	sets to loopback (127.0.0.1 for IPv4)
bool	netlib::ip_addr_t::setBroadcast (void) throw ()
	sets to broadcast.
void	netlib::ip_addr_t::setIPv4 (IN const byte_t *ip) throw ()
void	netlib::ip_addr_t::setIPv6 (IN const byte_t *ip) throw ()
	netlib::address_t::address_t (void) throw ()
void	netlib::address_t::clear (void) throw ()
bool	netlib::address_t::isValid (void) const throw ()
bool	netlib::address_t::operator== (IN const address_t &rhs) const throw ()
bool	netlib::address_t::operator!= (IN const address_t &rhs) const throw ()
bool	netlib::address_t::set (IN const char *server, IN int remotePort)
	set the IP and port. Returns false if server name doesn't resolve
bool	netlib::address_t::setlocal (IN int remotePort)
	set to local host (picks first non-loopback address)
void	netlib::address_t::dump (IN const char *msg) const throw ()
bool	netlib::getLocalInterfaces (OUT map_ip_addr_t &interfaces)
	get set of local interfaces
bool	netlib::wsIsValidSocket (IN int s) throw ()
	is the given socket identifier valid?
eWSError	netlib::wsGetError (void) throw ()
	gets the current error (0 means no error).
void	netlib::wsGetErrorMessage (IN char *buffer, IN int bufferSize) throw ()
	returns the most recent error message
int	netlib::wsCreateTcpSocket (void) throw ()
	creates a socket that can be used for TCP
int	netlib::wsCreateUdpSocket (IN bool broadcast) throw ()
	creates a socket that can be used for UDP
int	netlib::wsBindToPort (IN int s, IN int port) throw ()
	binds the given socket to a specific local port for UDP or TCP returns 0 on success, -1 for error.
int	netlib::wsListen (IN int s, IN int maxBacklog) throw ()
	usually used for TCP listening sockets.
int	netlib::wsConnect (IN int s, IN const address_t &server) throw ()
	makes a connection to the specified server
int	netlib::wsReceive (IN int s, IN char *buffer, IN int bufferSize) throw ()
	receives data (typically from TCP).
int	netlib::wsReceiveFrom (IN int s, IN char *buffer, IN int bufferSize, OUT address_t &from) throw ()
	receives data (typically from UPD).
int	netlib::wsSend (IN int s, IN const char *buffer, IN int bufferSize) throw ()
	sends data (typically for TCP).
int	netlib::wsSendTo (IN int s, IN const char *buffer, IN int bufferSize, IN const address_t &to) throw ()
	sends data (typically for UDP).
int	netlib::wsAccept (IN int s, OUT address_t &address) throw ()
	accepts an incoming request.
ws_set_t	netlib::wsCreateSet (void)
	creates an object that you can clear, and then populate with sockets.
void	netlib::wsClearSet (IN ws_set_t set) throw ()
	clears the given set
void	netlib::wsAddSocketToSet (IN ws_set_t set, IN int s) throw ()
	adds the given socket to the given set
bool	netlib::wsIsSocketInSet (IN ws_set_t set, IN int s) throw ()
	is the given socket in the set?
void	netlib::wsDestroySet (IN ws_set_t set) throw ()
	destroys the given set
int	netlib::wsSelect (IN int maxSocket,IN ws_set_t readers, IN ws_set_t writers, IN long wait_microseconds) throw ()
	waits until a socket is ready for read/write.
void	netlib::wsCloseSocket (IN int s) throw ()
	closes a socket
Variables
byte_t	netlib::ip_addr_t::addr [6]
byte_t	netlib::ip_addr_t::flags
byte_t	netlib::ip_addr_t::unused
ip_addr_t	netlib::address_t::ip
int	netlib::address_t::port

---

Detailed Description

This is a quick and dirty sockets-like API to abstract the netlib implementation from operating-system-specific issues.

Basically this abstracts the BSD Sockets and Winsock APIs.

This is not completely general, it is tailored for netlib. For instance, it assumes (and enforces) nonblocking sockets. It quiets all signals.

This follows BSD socket-style error handling. If something goes wrong, call wsGetError() for the error code.

WARNING: the select() behavior is a bit funky. In particular, I took a shortcut and relied on global state for some of the fd sets. This means this library is NOT threadsafe. That's fine for now, but may be cleaned up someday.

---

Typedef Documentation

typedef std::map<std::string, ip_addr_t> netlib::map_ip_addr_t

a map of IP addresses (typically interface name --> IP address)

Definition at line 223 of file wavesock.h.

typedef void* netlib::ws_set_t

Definition at line 310 of file wavesock.h.

---

Enumeration Type Documentation

enum netlib::eWSError

these are error codes.

They also are abstracted! as a result, they don't cover the full spectrum of possible errors. They only cover what I've needed so far. Most errors will therefore be mapped to eWS_Unknown.

Enumerator:

eWS_Okay	no error
eWS_Again	read/write failed, just try again
eWS_Denied	permission denied (bad port#?)
eWS_InUse	address is already in use
eWS_ConnectionRefused	no one listening at other end
eWS_Unknown	unmapped error
eWS_Invalid

Definition at line 75 of file wavesock.h.

---

Function Documentation

netlib::ip_addr_t::ip_addr_t

(

void

)

throw () [inline, inherited]

Definition at line 100 of file wavesock.h.

void netlib::ip_addr_t::clear

(

void

)

throw () [inline, inherited]

Definition at line 101 of file wavesock.h.

eType netlib::ip_addr_t::getType

(

void

)

const throw () [inline, inherited]

Definition at line 107 of file wavesock.h.

bool netlib::ip_addr_t::isValid

(

void

)

const throw () [inline, inherited]

Definition at line 109 of file wavesock.h.

bool netlib::ip_addr_t::operator!=

(

IN const ip_addr_t &

rhs

)

const throw () [inline, inherited]

Definition at line 114 of file wavesock.h.

bool netlib::ip_addr_t::operator==

(

IN const ip_addr_t &

rhs

)

const throw () [inline, inherited]

Definition at line 118 of file wavesock.h.

void netlib::ip_addr_t::dump

(

IN const char *

title

)

const throw () [inline, inherited]

Definition at line 122 of file wavesock.h.

bool netlib::ip_addr_t::lookupHostname

(

IN const char *

hostname

)

[inherited]

attempts to look up the IP of the remote host.

Returns false on failure (and the value of the ip address object is unchanged).

Definition at line 338 of file wavesock.cpp.

bool netlib::ip_addr_t::isLoopback

(

void

)

const throw () [inherited]

is this just a loopback IP address? (127.0.0.1 for IPv4)

Definition at line 408 of file wavesock.cpp.

void netlib::ip_addr_t::setLoopback

(

void

)

throw () [inherited]

sets to loopback (127.0.0.1 for IPv4)

Definition at line 429 of file wavesock.cpp.

bool netlib::ip_addr_t::setBroadcast

(

void

)

throw () [inherited]

sets to broadcast.

WARNING: this isn't a very clever method. It just sets the last byte to 255. If you want more control over the broadcast mask, set it explicitly. Only works when applied to an already-valid IP address. Returns false on failure.

Definition at line 442 of file wavesock.cpp.

void netlib::ip_addr_t::setIPv4

(

IN const byte_t *

ip

)

throw () [inline, inherited]

Definition at line 152 of file wavesock.h.

void netlib::ip_addr_t::setIPv6

(

IN const byte_t *

ip

)

throw () [inline, inherited]

Definition at line 162 of file wavesock.h.

netlib::address_t::address_t

(

void

)

throw () [inline, inherited]

Definition at line 183 of file wavesock.h.

void netlib::address_t::clear

(

void

)

throw () [inline, inherited]

Definition at line 184 of file wavesock.h.

bool netlib::address_t::isValid

(

void

)

const throw () [inline, inherited]

Definition at line 189 of file wavesock.h.

bool netlib::address_t::operator==

(

IN const address_t &

rhs

)

const throw () [inline, inherited]

Definition at line 193 of file wavesock.h.

bool netlib::address_t::operator!=

(

IN const address_t &

rhs

)

const throw () [inline, inherited]

Definition at line 198 of file wavesock.h.

bool netlib::address_t::set	(	IN const char *	server,
		IN int	remotePort
	)			[inherited]

set the IP and port. Returns false if server name doesn't resolve

Definition at line 461 of file wavesock.cpp.

bool netlib::address_t::setlocal

(

IN int

remotePort

)

[inherited]

set to local host (picks first non-loopback address)

Definition at line 506 of file wavesock.cpp.

void netlib::address_t::dump

(

IN const char *

msg

)

const throw () [inline, inherited]

Definition at line 208 of file wavesock.h.

bool netlib::getLocalInterfaces

(

OUT map_ip_addr_t &

map

)

get set of local interfaces

bool netlib::wsIsValidSocket

(

IN int

s

)

throw ()

is the given socket identifier valid?

eWSError netlib::wsGetError

(

void

)

throw ()

gets the current error (0 means no error).

This is mapped to the known (small) set of wavesocket errors, and therefore is only useful in a few cases. See the eWSError enum. If you need richer information, call wsGetErrorMessage().

void netlib::wsGetErrorMessage	(	IN char *	buffer,
		IN int	bufferSize
	)			throw ()

returns the most recent error message

int netlib::wsCreateTcpSocket

(

void

)

throw ()

creates a socket that can be used for TCP

int netlib::wsCreateUdpSocket

(

IN bool

broadcast

)

throw ()

creates a socket that can be used for UDP

int netlib::wsBindToPort	(	IN int	s,
		IN int	port
	)			throw ()

binds the given socket to a specific local port for UDP or TCP returns 0 on success, -1 for error.

See BSD bind() for details.

int netlib::wsListen	(	IN int	s,
		IN int	maxBacklog
	)			throw ()

usually used for TCP listening sockets.

See BSD listen() for details. Returns 0 on success, -1 for error.

int netlib::wsConnect	(	IN int	s,
		IN const address_t &	address
	)			throw ()

makes a connection to the specified server

int netlib::wsReceive	(	IN int	s,
		IN char *	buffer,
		IN int	bufferSize
	)			throw ()

receives data (typically from TCP).

Look at BSD recv() for details. Returns the number of bytes read, -1 for error, 0 for disconnect

int netlib::wsReceiveFrom	(	IN int	s,
		IN char *	buffer,
		IN int	bufferSize,
		OUT address_t &	from
	)			throw ()

receives data (typically from UPD).

This also tells you where the data came from (where the sender is). Look at BSD recvfrom() for details. Returns the number of bytes read, -1 for error, 0 for disconnect

int netlib::wsSend	(	IN int	s,
		IN const char *	buffer,
		IN int	bufferSize
	)			throw ()

sends data (typically for TCP).

Look at BSD send() for details. Returns the number of bytes sent, -1 for error

int netlib::wsSendTo	(	IN int	s,
		IN const char *	buffer,
		IN int	bufferSize,
		IN const address_t &	to
	)			throw ()

sends data (typically for UDP).

Look at BSD sendto() for details. Returns the number of bytes sent, -1 for error

int netlib::wsAccept	(	IN int	s,
		OUT address_t &	address
	)			throw ()

accepts an incoming request.

See BSD accept() for details. Returns the socket for the accepted connection.

ws_set_t netlib::wsCreateSet

(

void

)

creates an object that you can clear, and then populate with sockets.

This involves memory allocation, so you should cache any sets you create.

void netlib::wsClearSet

(

IN ws_set_t

set

)

throw ()

clears the given set

void netlib::wsAddSocketToSet	(	IN ws_set_t	set,
		IN int	s
	)			throw ()

adds the given socket to the given set

bool netlib::wsIsSocketInSet	(	IN ws_set_t	set,
		IN int	s
	)			throw ()

is the given socket in the set?

void netlib::wsDestroySet

(

IN ws_set_t

set

)

throw ()

destroys the given set

int netlib::wsSelect	(	IN int	maxSocket,
		IN ws_set_t	readers,
		IN ws_set_t	writers,
		IN long	wait_microseconds
	)			throw ()

waits until a socket is ready for read/write.

See BSD select() for details. To call this, you must first clear and then populate the reader and writer sets. Returns -1 on error

Parameters:

maxSocket

needs to be max+1 of any socket in any set

void netlib::wsCloseSocket

(

IN int

s

)

throw ()

closes a socket

---

Variable Documentation

byte_t netlib::ip_addr_t::addr[6] [inherited]

Definition at line 169 of file wavesock.h.

byte_t netlib::ip_addr_t::flags [inherited]

Definition at line 170 of file wavesock.h.

byte_t netlib::ip_addr_t::unused [inherited]

Definition at line 171 of file wavesock.h.

ip_addr_t netlib::address_t::ip [inherited]

Definition at line 216 of file wavesock.h.

int netlib::address_t::port [inherited]

Definition at line 217 of file wavesock.h.