BLib.Socket - TCP/IP Socket Library Routines
               ============================================
                        File: Socket - Update: 0.11
                  Author: J.G.Harston - Date: 18-Dec-2010


  The Socket library provides functions to communicate over a TCP/IP
network, for example an Ethernet interface, such as the Sprow Master
Ethernet Interface[1].

Requirements and Dependancies
=============================
  The library requires a global control block large enough to hold the data
required for the calls accessible with X% holding the address of this
block, and Y% holding X% DIV 256. A control block size of 32 bytes is
sufficient for most calls. This can easily be set up with DIM ctrl% 31 near
the start of the program and X%=ctrl%:Y%=X%DIV256 at the begining of the
major program code and at the start of any main program loop.

  The resolver calls require name% to point to a block of at least 80
bytes, set up with DIM name% 80.

Definitions
===========
socket%   - a socket number to identify a connection
addr%     - address of data to transfer or socket structure
len%      - length of data or size of socket sctruture
domain%   - communications domain, usually 2 for PF_INIT
protocol% - communications protocol

Socket Function Calls
=====================
  Functions return a positive number (or zero) to indicate success, and a
negative number to indicate failure. This allows the following sort of code
to be used:

  A%=FNSocket_xxxx(parameters):IF A%<0 THEN REM Failed...

FNSocket_Open(domain%,type%,protocol%)
--------------------------------------
Opens a new socket for communication. Returns a socket number for future
communication, or a negative number if the call failed. domain% is usually
2 for PF_INET. type% can be 1=stream, 2=datagram, 3=raw.

FNSocket_Bind(socket%,addr%,len%)
---------------------------------
Binds a socket to the socket structure at the specified address.

FNSocket_Listen(socket%,count%)
-------------------------------
Listen for connections on a socket.

FNSocket_Accept(socket%,addr%,len%)
-----------------------------------
Waits for an incoming connection on a socket. Once an incoming connection
has been accepted, the socket structure at the specified address is updated
with the incoming connection details.

FNSocket_Connect(socket%,addr%,len%)
------------------------------------
Connects a socket to the remote connection at the specified address.

FNSocket_Recv(socket%,addr%,len%,opts%)
---------------------------------------
Attempts to read data from the specified socket. Returns a negative number
if the call failed, or the number of bytes transfered if successful.

FNSocket_Send(socket%,addr%,len%,opts%)
------------------------------------
Attempts to send data to the specified socket. Returns a negative number if
the call failed, or the number of bytes transfered if successful.

PROCSocket_Shutdown(socket%,type%)
----------------------------------
Partially shuts down a socket.

PROCSocket_Close(socket%)
----------------------
Closes an open socket.

Socket Structure
================
  The socket structure used by Bind, Accept and Connect has the following
layout:
     0     = Size of socket structure, usually 16
     1     = address type, usually 2 for AF_INET
     2..3  = port number
     4..7  = IPv4 internet address
     8..11 = 0
    12..15 = 0

Resolver Function Calls
=======================
  If a resolver call fails it returns zero, otherwise returns the address
of a hostent structure holding the following data:
     0..3  = pointer to name looked up
     4..7  = IP address type, 2 for AF_INET
     8..11 = length of address type, 4 for IPv4
    12..15 = pointer to a null-terminated list of pointers to IP addresses

FNDNS_GetHostByName(name$)
--------------------------
Searches for the specified hostname and waits until a match is found.

FNDNS_GetHost(name$)
--------------------
Searches for the specified host name, returns immediatedly returning 0 if
no match. Can be called repeatedly until a match is found.

References
==========
[1]Sprow Ethernet Interface, http://sprow.co.uk/bbc/masternet.htm

Version History
===============
0.10 12-Sep-2009 First version written, based on original RFC.
0.11 18-Dec-2010 Updated.