SWSSOCK CLIENT APPLICATION PROGRAMMING INTERFACE
================================================

Author: Lawrence Rust (lvr@softsystem.co.uk)
Last Modified: 02-Feb-10

The C header file sws_sock.h contains C language declarations for all client
visible data types and functions.  To prevent naming clashes all SwsSock names
begin with a SWS_ prefix.

NB if the preprocessor symbol SWS_SOCK_COMPAT is defined before #include
"sws_sock.h" then standard BSD sockets and Winsock2 names are mapped to SwsSock
ones with a series of macro definitions.  This enables programs written for
Winsock2 or other POSIX systems to be built with SwsSock.

To facilitate portability the file sws_net.h includes the correct
networking header files for the platform.  If the preprocessor symbol
SWS_USE_SOCKLIB is set to a non-zero value beforehand then the SwsSock headers
are included, otherwise if WIN32 or WIN16 are defined then the Winsock headers
are included, if not the POSIX headers are included.


LIBRARY INITIALISATION
======================

Library clients MUST call SWS_SockStartup() before using any library function.

int SWS_SockStartup(
  SWS_FGef* pfn,
  void* pv
);

The parameter 'pfn' enables the client to install a global event filter.  This
callback is made during important internal events and enables the client to
monitor or change internal operations, for instance packet reception and
transmission.  The parameter 'pv' is passed to the callback as context.  See
SWS_GefInstall.

This function returns 0 on success, otherwise an SWS_Exxx error code.

When a client no longer require network access, resources allocated by the
library may be released by calling:

void SWS_SockCleanup( void);


UTILITIES
=========

void SWS_SockSleep( u_long)
  Sleep for a number of milliseconds.  This or any other SwsSock library
  function must be called on a regular basis on co-operatively scheduled
  threaded system.

u_long SWS_SockTicks( void)
  A monotonic clock.  The constant SWS_TIMER_TICKS defines the time resolution
  and is nominally 1000 ticks per second.

SWS_TimerLE & SWS_TimerLT
  Macros that compare clock values.  Allow for timer wraparound.

int SWS_stricmp( const char*, const char*)
  Case insensitive string compare.


STANDARD FUNCTIONS
==================

Given that the preprocessor symbol SWS_SOCK_COMPAT is defined then the
following POSIX/Winsock compatible functions are available.  NB this document
only details differences between the SwsSock implementation and the equivalent
Winsock or POSIX version.

SOCKET socket( int _family, int _type, int _protocol)
  Create a socket of the specified type.
  NB the return value is an opaque pointer type, not an int.

int bind( SOCKET, const struct sockaddr* _name, int _namelen)
  Bind a socket to a local adapter and port.

int listen( SOCKET, int _backlog)
  Start a socket listening.

int connect( SOCKET, const struct sockaddr* _name, int _namelen)
  Connect a socket to a remote host

SOCKET accept( SOCKET, struct sockaddr* _addr, int* _addrlen)
  Accept an incoming connection.

int recv( SOCKET, void* _buf, unsigned _len, unsigned _flags)
  Receive data.

int recvfrom( SOCKET, void* _buf, unsigned _len, unsigned _flags,
  struct sockaddr* _from, int* _fromlen)
  Receive data.

int send( SOCKET, const void* _buf, unsigned _len, unsigned _flags)
  Send data.

int sendto( SOCKET, const void* _buf, unsigned _len, unsigned _flags,
  const struct sockaddr* _to, int _tolen)
  Send data to a given host.

int getsockname( SOCKET, struct sockaddr*, int* _namelen )
  Get the local binding.

int getpeername( SOCKET, struct sockaddr*, int* _namelen )
  Get the remote binding

int getsockopt( SOCKET, unsigned _level, unsigned _opt, void* _val, int* _len)
  Get option data

int setsockopt( SOCKET, unsigned _level, unsigned _opt, const void* _val, int _len)
  Set option data

int shutdown( SOCKET, int _how)
  Shutdown a connection.

int closesocket( SOCKET)
  Destroy a socket.

int ioctlsocket( SOCKET, u_long _cmd, u_long* _args )
  Ioctl.

int select( int, fd_set*, fd_set*, fd_set*, const struct timeval* )
  Test socket readiness

int FdIsSet( SOCKET, fd_set* )
  Test if socket is in set.

void FdClr( SOCKET, fd_set* )
  Remove socket from set.

void FdSet( SOCKET, fd_set* )
  Add socket to set.

void FdZero( fd_set*)
  Initialise a set.

int GetLastError( void)
  Return the last error.  This should be used instead of reading errno.

struct hostent* gethostbyaddr( const char*, int _len, int _family)
  Get host given an address.

struct hostent* gethostbyname( const char* )
  Get host give a name.

struct protoent* getprotobyname( const char* )
  Get protocol given name.

struct protoent* getprotobynumber( int )
  Get protocol given number.

struct servent* getservbyname( const char*, const char* )
  Get service given name.

struct servent* getservbyport( int /* Network order */, const char* )
  Get service given port and name.

int gethostname( char*, int _namelen)
  Get host name.

in_addr_t inet_addr( const char* )
  Convert string to IP address

const char* inet_ntoa( struct in_addr);
  Convert IP address to string

u_long htonl( u_long)
u_short htons( u_short)
u_long ntohl( u_long)
u_short ntohs( u_short)
  Host <=> network byte order data conversions.


BUFFERS
=======

TIMERS
======

MESSAGE QUEUES
=============

GLOBAL EVENT FILTER
===================

IP
==

ICMP
====

IGMP
====

TCP
===

POINT TO POINT
==============

PPP
===

DHCP
====

DNS
===

THREADS
=======

SETTINGS FILE MANAGEMENT
========================

PACKET DUMPER
=============


WRITING TRANSPORTS
sws_tprt

WRITING DATALINKS
sws_dlnk

WRITING ETHERNET DRIVERS
sws_enet

WRITING SERIAL DRIVERS
sws_p2p
p2p