SOCKET-Plugin V0.11a                                                 07.08.1998
===============================================================================
(C) 1998 StarSys - Jrgen Koneczny

	August-Gabler-Weg 2a
	D-89340 Leipheim
	Telefon: 08221/7523
	EMail: zulu@camelot.de
	http://www.camelot.de/~zulu


INSTALLATION
------------

Copy SOCKET.plg into the PLUGIN folder of MagiC Scripter.


PREREQUISITES
-------------

SOCKET.plg requires the MagiC Scripter, IConnect from V1.5 on and a 
multi-tasking operating system (N.AES or preferably MagiC from V4.5 on).


REMARKS
-------

As IConnect and with that also the SOCKET-Plugin - in contrast to other
TCP/IP stacks - is based on the socket interface, there is sufficient 
literature available about it. For German speakers I can recommend 
'Internet intern' by Data Becker.

With return, this documentation always means the result string, i.e. 
msg[5+6] for GS_ACK. This corresponds to the actual return of the 
commands in MagiC Scripter.

With 'errno' one specifies what the commands return in msg[7]. This value
can be inquired in MagiC Scripter via errno. If errno is non-zero (more 
exactly is 2), then an error has occurred in the Socket-Plugin in the 
execution of a command that does not return a result string interpretable 
as a number when executed correctly; this is then specified more exactly 
by the return value:

  "-1":    (=ERROR)
 "-39": insufficient memory (=ENSMEM)
"-100": not enough arguments
"-300": Socket operation on non-socket (=ENOTSOCK)
"-301": Destination address required (=EDESTADDRREQ)
"-302": Message too long (=EMSGSIZE)
"-303": Protocol wrong type for socket (=EPROTOTYPE)
"-304": Protocol not available (=ENOPROTOOPT)
"-305": Protocol not supported (=EPROTONOSUPPORT)
"-306": Socket type not supported (=ESOCKTNOSUPPORT)
"-307": Operation not supported (=EOPNOTSUPP)
"-308": Protocol family not supported (=EPFNOSUPPORT)
"-309": Address family not supported by protocol (=EAFNOSUPPORT)
"-310": Address already in use (=EADDRINUSE)
"-311": Cannot assign requested address (=EADDRNOTAVAIL)
"-312": Network is down (=ENETDOWN)
"-313": Network is unreachable (=ENETUNREACH)
"-314": Network dropped connection because of reset (=ENETRESET)
"-315": Software caused connection abort (=ECONNABORTED)
"-316": Connection reset by peer (=ECONNRESET)
"-317": Socket is already connected (=EISCONN)
"-318": Socket is not connected (=ENOTCONN)
"-319": Cannot send after shutdown (=ESHUTDOWN)
"-320": Connection timed out (=ETIMEDOUT)
"-321"; Connection refused (=ECONNREFUSED)
"-322": Host is down (=EHOSTDOWN)
"-323": No route to host (=EHOSTUNREACH)
"-324": Operation already in progress (=EALREADY)
"-325": Operation now in progress (=EINPROGRESS)
"-326": Operation would block (=EWOULDBLOCK)


COMMANDS
--------

accept <handle>

Accepts a connection on a socket and returns the handle.

handle: Handle of the socket.


bind <handle> <port>

Specifies the local address, i.e. the port, of the socket. If <port> <= 0 
then a port will be assigned.

handle: Handle of the socket
  port: Port


connect <handle> <addr> <port>

Sets up a connection to a host.

handle: Handle of the socket
  addr: IP-address of the host in dot-separated form
  port: Port


gethostbyname <name>

Establishes the IP-address of the host <name> as dot-separated numbers 
(a.b.c.d). The return is an error-code if errno equals 2.


getsockname_addr <handle>

Returns the IP-address as dot-separated numbers of the socket. If 'errno' 
is two, the return is an error-code.

handle: Handle of the socket


getsockname_port <handle>

Returns the port of the socket.
Return is an error-code if errno equals 2.

handle: Handle of the socket


listen <handle> <backlog>

Prepares the socket to accept the connections on the TCP-level.

 handle: Handle of the socket
backlog: The maximum number of connections to be accepted for this socket.


recv <handle> <flags>

Reads out the receive-buffer of the socket.
Return is an error-code if errno equals 2.

handle:	Handle of the socket
 flags: 0 (= no flag set), 1 (=MSG_PEEK)


sclose <handle>

Clears the socket.

handle: Handle of the socket


sendto <handle> <addr> <port> <flags> <msg>

Sends msg via the socket to addr, port.
handle:	Handle of the socket
  addr: IP-address of the host in dot-separated form
  port: Port
 flags: 0 (= no flag set), 1 (=MSG_OOB)
   msg: Message to be sent


socket <type> <protocol>

Creates a new socket and returns its handle.

    type: 1 (=SOCK_STREAM), 2 (=SOCK_DGRAM)
protocol: 0 (=IPPROTO_IP), 6 (=IPPROTO_TCP), 17 (=IPPROTO_UDP)


sread	<handle>

Reads out the receive-buffer of the socket.
Return is an error-code if errno equals 2.

handle:	Handle of the socket


swrite <handle> <msg>

Sends msg via the socket.

handle: Handle of the socket
   msg: Message to be sent


version

Returns the version of Socket.plg.