Classes | Typedefs | Enumerations | Enumerator | Functions | Variables

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!= (const ip_addr_t &rhs) const throw ()
bool netlib::ip_addr_t::operator== (const ip_addr_t &rhs) const throw ()
void netlib::ip_addr_t::dump (const char *title) const throw ()
bool netlib::ip_addr_t::lookupHostname (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 (const byte_t *ip) throw ()
void netlib::ip_addr_t::setIPv6 (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== (const address_t &rhs) const throw ()
bool netlib::address_t::operator!= (const address_t &rhs) const throw ()
bool netlib::address_t::set (const char *server, int remotePort)
 set the IP and port. Returns false if server name doesn't resolve
bool netlib::address_t::setlocal (int remotePort)
 set to local host (picks first non-loopback address)
void netlib::address_t::dump (const char *msg) const throw ()
bool netlib::getLocalInterfaces (map_ip_addr_t &interfaces)
 get set of local interfaces
bool netlib::wsIsValidSocket (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 (char *buffer,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 (bool broadcast) throw ()
 creates a socket that can be used for UDP
int netlib::wsBindToPort (int s,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 (int s,int maxBacklog) throw ()
 usually used for TCP listening sockets.
int netlib::wsConnect (int s,const address_t &server) throw ()
 makes a connection to the specified server
int netlib::wsReceive (int s,char *buffer,int bufferSize) throw ()
 receives data (typically from TCP).
int netlib::wsReceiveFrom (int s,char *buffer,int bufferSize,address_t &from) throw ()
 receives data (typically from UPD).
int netlib::wsSend (int s,const char *buffer,int bufferSize) throw ()
 sends data (typically for TCP).
int netlib::wsSendTo (int s,const char *buffer,int bufferSize,const address_t &to) throw ()
 sends data (typically for UDP).
int netlib::wsAccept (int s,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 (ws_set_t set) throw ()
 clears the given set
void netlib::wsAddSocketToSet (ws_set_t set,int s) throw ()
 adds the given socket to the given set
bool netlib::wsIsSocketInSet (ws_set_t set,int s) throw ()
 is the given socket in the set?
void netlib::wsDestroySet (ws_set_t set) throw ()
 destroys the given set
int netlib::wsSelect (int maxSocket,ws_set_t readers,ws_set_t writers,long wait_microseconds) throw ()
 waits until a socket is ready for read/write.
void netlib::wsCloseSocket (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

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!= ( const ip_addr_t rhs  )  const throw () [inline, inherited]

Definition at line 114 of file wavesock.h.

bool netlib::ip_addr_t::operator== ( const ip_addr_t rhs  )  const throw () [inline, inherited]

Definition at line 118 of file wavesock.h.

void netlib::ip_addr_t::dump ( const char *  title  )  const throw () [inline, inherited]

Definition at line 122 of file wavesock.h.

bool netlib::ip_addr_t::lookupHostname ( 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 294 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 389 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 410 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 423 of file wavesock.cpp.

void netlib::ip_addr_t::setIPv4 ( const byte_t ip  )  throw () [inline, inherited]

Definition at line 152 of file wavesock.h.

void netlib::ip_addr_t::setIPv6 ( 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== ( const address_t rhs  )  const throw () [inline, inherited]

Definition at line 193 of file wavesock.h.

bool netlib::address_t::operator!= ( const address_t rhs  )  const throw () [inline, inherited]

Definition at line 198 of file wavesock.h.

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

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

Definition at line 442 of file wavesock.cpp.

bool netlib::address_t::setlocal ( int  remotePort  )  [inherited]

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

Definition at line 487 of file wavesock.cpp.

void netlib::address_t::dump ( const char *  msg  )  const throw () [inline, inherited]

Definition at line 208 of file wavesock.h.

bool netlib::getLocalInterfaces ( map_ip_addr_t &  map  ) 

get set of local interfaces

bool netlib::wsIsValidSocket ( 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 ( char *  buffer,
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 ( bool  broadcast  )  throw ()

creates a socket that can be used for UDP

int netlib::wsBindToPort ( int  s,
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 ( int  s,
int  maxBacklog 
) throw ()

usually used for TCP listening sockets.

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

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

makes a connection to the specified server

int netlib::wsReceive ( int  s,
char *  buffer,
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 ( int  s,
char *  buffer,
int  bufferSize,
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 ( int  s,
const char *  buffer,
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 ( int  s,
const char *  buffer,
int  bufferSize,
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 ( int  s,
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 ( ws_set_t  set  )  throw ()

clears the given set

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

adds the given socket to the given set

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

is the given socket in the set?

void netlib::wsDestroySet ( ws_set_t  set  )  throw ()

destroys the given set

int netlib::wsSelect ( int  maxSocket,
ws_set_t  readers,
ws_set_t  writers,
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 ( int  s  )  throw ()

closes a socket


Variable Documentation

Definition at line 169 of file wavesock.h.

Definition at line 170 of file wavesock.h.

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.