TCP & UDP sockets
=================

Scheme48 provides a simple facility for TCP & UDP sockets.  Both the structures sockets and udp-sockets export several general socket-related procedures:

 -- procedure: close-socket socket returns unspecified
 -- procedure: socket-port-number socket returns integer
 -- procedure: get-host-name returns string
     Close-socket closes SOCKET, which may be any type of socket.  Socket-port-number returns the port number through which SOCKET is communicating.  Get-host-name returns the network name of the current machine.

     Note: Programmers should be wary of storing the result of a call to get-host-name in a dumped heap image, because the actual machine's host name may vary from invocation to invocation of the Scheme48 VM on that image, since heap images may be resumed on multiple different machines.

TCP sockets
-----------

The sockets structure provides simple TCP socket facilities.

 -- procedure: open-socket [port-number] returns socket
 -- procedure: socket-accept socket returns [input-port output-port]
     The server interface.  Open-socket creates a socket that listens on PORT-NUMBER, which defaults to a random number above 1024. Socket-accept blocks until there is a client waiting to be accepted, at which point it returns two values: an input port & an output port to send & receive data to & from the client.

 -- procedure: socket-client host-name port-number returns [input-port output-port]
     Connects to the server at PORT-NUMBER denoted by the machine name HOST-NAME and returns an input port and an output port for sending & receiving data to & from the server.  Socket-client blocks the current thread until the server accepts the connection request.

UDP sockets
-----------

The udp-sockets structure defines a UDP socket facility.

 -- procedure: open-udp-socket [port-number] returns socket
     Opens a UDP socket on PORT-NUMBER, or a random port number if none was passed.  Open-udp-socket returns two values: an input UDP socket and an output UDP socket.

 -- procedure: udp-send socket address buffer count returns count-sent
 -- procedure: udp-receive socket buffer returns [count-received remote-address]
     Udp-send attempts to send COUNT elements from the string or byte vector BUFFER from the output UDP socket SOCKET to the UDP address ADDRESS, and returns the number of octets it successfully sent.  Udp-receive receives a UDP message from SOCKET, reading it into BUFFER destructively.  It returns two values: the number of octets read into BUFFER and the address whence the octets came.

 -- procedure: lookup-udp-address name port returns udp-address
 -- procedure: udp-address? object returns boolean
 -- procedure: udp-address-address address returns c-byte-vector
 -- procedure: udp-address-port address returns port-number
 -- procedure: udp-address-hostname address returns string-address
     Lookup-udp-address returns a UDP address for the machine name NAME at the port number PORT.  Udp-address? is the disjoint type predicate for UDP addresses.  Udp-address-address returns a byte vector that contains the C representation of ADDRESS, suitable for passing to C with Scheme48's C FFI. Udp-address-port returns the port number of ADDRESS. Udp-address-hostname returns a string representation of the IP address of ADDRESS.