//
//------------------ DOK FILE --------------------------------------------------
+Header	networkLib
=pkg	bios
=title	Networking
=short	sockets, ip, tcp, udp
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- Tcp
+Proto	Tcp
=type	Tcp
=mode	structure
=pkg	bios
=impl	mcy
=link	
=desc	A TCP socket. Such a socket is symmetric: it is created as a client socket with [[tcpOpen]], or on server side when there is an incoming connection.
//
//
//------------------ PROTO ----------------------------------------------------- TcpSrv
+Proto	TcpSrv
=type	TcpSrv
=mode	structure
=pkg	bios
=impl	mcy
=link	
=desc	A TCP server.
//
//
//------------------ PROTO ----------------------------------------------------- Udp
+Proto	Udp
=type	Udp
=mode	structure
=pkg	bios
=impl	mcy
=link	
=desc	A UDP server.
//
//
//------------------ PROTO ----------------------------------------------------- tcpOnEvent
+Proto	tcpOnEvent
=type	fun Tcp (fun Str -> a1) (fun -> a2) -> Tcp
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function defines two lambda functions to control a tcp connection.
The fRead function will be called on the same thread when some incoming data is available.
The fWrite function will be called once at the beginning to inform that the socket is ready to send data. Then it will be called only after an uncomplete [[tcpWrite]], when the socket is ready for further sending.
//
+arg	tcp
=type	Tcp
=desc	A TCP socket
//
+arg	fRead
=type	fun Str -> a1
=desc	A lambda function with one string argument and any result
//
+arg	fWrite
=type	fun -> a2
=desc	A lambda function with no argument and any result
//
+arg	result
=type	Tcp
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- tcpClose
+Proto	tcpClose
=type	fun Tcp -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function closes the TCP connection.
//
+arg	tcp
=type	Tcp
=desc	A TCP socket
//
+arg	result
=type	Bool
=desc	Always true
//
//
//------------------ PROTO ----------------------------------------------------- tcpSrvCreate
+Proto	tcpSrvCreate
=type	fun Str Int -> TcpSrv
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function creates a TCP server attached to a specific IP address, or to any address when addr is nil.
This function should be followed by a call to [[tcpSrvOnAccept]] to define the behaviour on incoming connections.
//
+arg	addr
=type	Str
=desc	An IP address, such as "127.0.0.1", or nil
//
+arg	port
=type	Int
=desc	A port number
//
+arg	result
=type	TcpSrv
=desc	A TCP server
//
//
//------------------ PROTO ----------------------------------------------------- tcpSrvOnAccept
+Proto	tcpSrvOnAccept
=type	fun TcpSrv (fun Stream -> a1) -> TcpSrv
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
Each time there is an incoming connection on the TCP server, the system creates a TCP socket and calls the lambda function fAccept with this socket, in the same thread.
From there the program is expected to call [[tcpOnEvent]] to define how to receive data, or more likely to create a dedicated thread and call [[tcpOnEvent]] from this new thread, so that the TCP server and each TCP socket have their own thread and run independantly.
//
+arg	tcpSrv
=type	TcpSrv
=desc	A TCP server
//
+arg	fAccept
=type	fun Stream -> a1
=desc	A lambda function with one Stream argument and any result.
//
+arg	result
=type	TcpSrv
=desc	The TCP server
//
//
//------------------ PROTO ----------------------------------------------------- tcpNoDelay
+Proto	tcpNoDelay
=type	fun Tcp Bool -> Tcp
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function enables or disables the noDelay mecanism.
When noDelay is true, a call to [[tcpWrite]] will try sending data immediately with a dedicated IP frame.
Else the system waits for a very little amount of time, in order to keep a chance to group data from successive calls to [[tcpWrite]] in a single IP frame.
//
+arg	tcp
=type	Tcp
=desc	A TCP socket
//
+arg	noDelay
=type	Bool
=desc	A boolean
//
+arg	result
=type	Tcp
=desc	The same TCP socket
//
//
//------------------ PROTO ----------------------------------------------------- tcpOpen
+Proto	tcpOpen
=type	fun Str Int -> Tcp
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function initiates a TCP connection to a distant server. It returns a TCP socket. Then the program is expected to call [[tcpOnEvent]] to define how to receive data.
//
+arg	addr
=type	Str
=desc	An IP address, such as "213.186.33.19"
//
+arg	port
=type	Int
=desc	A port number
//
+arg	result
=type	Tcp
=desc	A TCP socket
//
//
//------------------ PROTO ----------------------------------------------------- tcpRemoteIp
+Proto	tcpRemoteIp
=type	fun Tcp -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the IP address of the peer
//
+arg	tcp
=type	Tcp
=desc	A TCP socket
//
+arg	result
=type	Str
=desc	An IP address
//
//
//------------------ PROTO ----------------------------------------------------- tcpRemotePort
+Proto	tcpRemotePort
=type	fun Tcp -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the port number of the socket on the peer.
//
+arg	tcp
=type	Tcp
=desc	A TCP socket
//
+arg	result
=type	Int
=desc	A port number
//
//
//------------------ PROTO ----------------------------------------------------- tcpSrvClose
+Proto	tcpSrvClose
=type	fun TcpSrv -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function closes a TCP server.
//
+arg	srv
=type	TcpSrv
=desc	A TCP server
//
+arg	result
=type	Bool
=desc	Always true
//
//
//------------------ PROTO ----------------------------------------------------- tcpWrite
+Proto	tcpWrite
=type	fun Tcp Str Int -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function tries to send data over a TCP socket. It tries to send all the data from the position start to the end of src.
TCP socket may accept or not accept the data, or may accept only a smaller set of data. The function returns the position of the next byte to sending.
When everything works fine, the returned value is the length of the string src. Else there will be a later call to the lambda function fWrite defined in function [[tcpOnEvent]], when the socket is ready to send at least one byte.
//
+arg	tcp
=type	Tcp
=desc	A TCP socket
//
+arg	src
=type	Str
=desc	A string
//
+arg	start
=type	Int
=desc	A position in the string
//
+arg	result
=type	Int
=desc	The new position in the string
//
//
//------------------ PROTO ----------------------------------------------------- hostName
+Proto	hostName
=type	fun -> Str
=mode	function
=pkg	bios
=impl	native
=link	
=desc	This function returns the name of the host. It is not supposed to be an IP address or a domain name, it is usually a kind of 'nickname'.
//
+arg	result
=type	Str
=desc	A string
//
//
//------------------ PROTO ----------------------------------------------------- ipByName
+Proto	ipByName
=type	fun Str -> list Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function returns the IP addresses of a named machine. Depending on the host, this function may request a DNS server or reads the /etc/hosts file.
It will return nil when the machine name cannot be resolved.
This function blocks the thread, but other threads are still running.
//
+arg	hostname
=type	Str
=desc	A machine name, usually a domain name.
//
+arg	result
=type	list Str
=desc	A list of IP addresses
//
//
//------------------ PROTO ----------------------------------------------------- nameByIp
+Proto	nameByIp
=type	fun Str -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc
This function is the opposite to [[ipByName]]. Depending on the host, this function may request a DNS server or reads the /etc/hosts file.
It will return nil when no machine name can be found for the IP address.
This function blocks the thread, but other threads are still running.
//
+arg	ip
=type	Str
=desc	An IP address
//
+arg	result
=type	Str
=desc	A machine name
//
//
//------------------ PROTO ----------------------------------------------------- udpClose
+Proto	udpClose
=type	fun Udp -> Bool
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function closes a UDP server.
//
+arg	udp
=type	Udp
=desc	A UDP server
//
+arg	result
=type	Bool
=desc	Always true
//
//
//------------------ PROTO ----------------------------------------------------- udpCreate
+Proto	udpCreate
=type	fun Str Int Str Int -> Udp
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function creates a UDP server, ready to receive data from outside.
When distantAddr and distantPort are not nil, this UDP server is linked to this distant machine: only messages from this source will be managed, and the [[udpSend]] function will send the message to this distant machine.
When distantAddr is nil, the [[udpSend]] function will not work. Instead, use the [[udpSendTo]] function.
This function should be followed by a call to [[udpOnEvent]] to define the behaviour on incoming message.
//
+arg	distantAddr
=type	Str
=desc	An IP address, such as "127.0.0.1", or nil
//
+arg	distantPort
=type	Int
=desc	A port number
//
+arg	localAddr
=type	Str
=desc	A local IP address, such as "127.0.0.1", or nil
//
+arg	localPort
=type	Int
=desc	A port number
//
+arg	result
=type	Udp
=desc	
//
//
//------------------ PROTO ----------------------------------------------------- udpOnEvent
+Proto	udpOnEvent
=type	fun Udp (fun Str -> a1) (fun -> a2) -> Udp
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function defines two lambda functions to control a udp connection.
The fRead function will be called on the same thread when some incoming data is available.
The fWrite function will be called once at the beginning to inform that the socket is ready to send data. Then it will be called only after a failed [[udpSend]] or [[udpSendTo]], when the socket is ready for further sending.
//
+arg	udp
=type	Udp
=desc	A UDP socket
//
+arg	fRead
=type	fun Str -> a1
=desc	A lambda function with one string argument and any result
//
+arg	fWrite
=type	fun -> a2
=desc	A lambda function with no argument and any result
//
+arg	result
=type	Udp
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- udpRemoteIp
+Proto	udpRemoteIp
=type	fun Udp -> Str
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the IP address of the sender. The same [[Udp]] may receive data from multiple sources, so it is imperative to call [[udpRemoteIP]] in the lambda function fRead defined with [[udpCreate]], before it is replaced with next message source.
//
+arg	udp
=type	Udp
=desc	A UDP server
//
+arg	result
=type	Str
=desc	An IP address, such as "213.186.33.19"
//
//
//------------------ PROTO ----------------------------------------------------- udpRemotePort
+Proto	udpRemotePort
=type	fun Udp -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function returns the port number of the sender. The same [[Udp]] may receive data from multiple sources, so it is imperative to call [[udpRemotePort]] in the lambda function fRead defined with [[udpCreate]], before it is replaced with next message source.
//
+arg	udp
=type	Udp
=desc	A UDP server
//
+arg	result
=type	Int
=desc	A port number
//
//
//------------------ PROTO ----------------------------------------------------- udpSendTo
+Proto	udpSendTo
=type	fun Udp Str Int Str -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function sends a UDP message using a UDP stream. It returns the number of bytes sent, or nil when the sending is unavailable. However UDP does not guarantee that the message will reach the server.
//
+arg	udp
=type	Udp
=desc	A UDP server
//
+arg	addr
=type	Str
=desc	An IP address, such as "213.186.33.19"
//
+arg	port
=type	Int
=desc	A port number
//
+arg	data
=type	Str
=desc	A string
//
+arg	result
=type	Int
=desc	An integer
//
//
//------------------ PROTO ----------------------------------------------------- udpSend
+Proto	udpSend
=type	fun Udp Str -> Int
=mode	function
=pkg	bios
=impl	mcy
=link	
=desc	This function sends a UDP message using a UDP link stream created with [[udpCreate]]. It returns the number of bytes sent, or nil when the sending is unavailable. However UDP does not guarantee that the message will reach the server.
//
+arg	udp
=type	Udp
=desc	A UDP server
//
+arg	data
=type	Str
=desc	A string
//
+arg	result
=type	Int
=desc	An integer