The TCPNet.Mod module and TCPNet Device in Oberon Workstation provide client and server internet connectivity to Oberon programs. Each of the (max 32) connections works with 2 regular Oberon files. One file receives TCP data; the other supplies data to be transmitted.
Both files appear as normal files to the modules (programs) in the Oberon system, but have extended behaviour. If an Oberon module writes data to the ouput file of the connection, this data is sent out on the internet connection. Incoming data from the connection is appended to the input file. If you want to keep the in- and out- streams, you can normally register the file(s).
The TCPNet Device works concurrently with RISC5 execution. During regular Oberon command execution however, a program does not perceive any network activity. The program may freely append new output data to the connection output file, and/or it may read data from the input file. Interaction with the TCPNet Device occurs via a Service Request task in the TCPNet.Mod module. The task is periodically called to "synchronize" your in/out files with the TCPNet Device. The service request task performs 3 actions:
PROCEDURE Open* (conn: TCPConn; in, out: Files.File; address: ARRAY OF CHAR; port: INTEGER; handler: Handler; VAR res: INTEGER);
This procedure requests the establishment of a connection conform the given parameters. The action occurs asynchronously by macOS system calls to its sockets library. When the requested connection succeeds, streaming is potentially immediately started if either local or remote sides have data to send. The establishment of the connection (among other events) is reported via status calls to your handler procedure.
www.reactive-instruments.eu 188.8.131.52The address string is max. 63 chars (excluding trailing null)
Handler* = PROCEDURE (conn: TCPConn; stat:SET): INTEGER;
In case of a directly requested connection, if needed, you may use the TCPConn.raddr and TCPConn.lport fields of the connection record to inspect resolved remote address and the (automatically) assigned local port respectively.
In case of a served connection (see Listening connection), if needed, you may use the TCPConn.raddr field to inspect the remote client address, and TCPConn.rport to look up the remote port of the visitor.
PROCEDURE Close*(conn: TCPConn);
Closing a connection from the local site is useful when a protocol "cycle" has ended, and no new actions are planned, or an error occured. This saves resources on server and client sides. The Close procedure may be called from within the body of the handler or as part of a normal Oberon command. After closing, any references to the connection record and files in the TCPNet module and TCPNet Device are erased.
The connection record is subject to normal Oberon garbage collection. Since closing the connection has no impact on the in- and out files, these files have kept their content as it existed when closing the connection. The files may be re-used on new connections, or analyzed to study communication behaviour.
PROCEDURE Listen* (conn: TCPConn; in, out: Files.File; port: INTEGER; handler: Handler; VAR res: INTEGER);
This procedure reserves a serving connection slot where potentially a single remote client can connect to. If multiple of such listening slots are created with the same port number, effectively a "server" is created on that port with a fixed maximum number or simultaneous connections. These connections, once established, behave essentially the same as directly requested connections. Whereas directly requested connections specify a definite peer address and start contacting the peer immediately, these serving connection slots wait to be contacted by any remote computer.
The same type of handler procedure applies to a listening connection as to a directly created connection. A single handler for listening connections with a given port number would typically be implemented for that port number.
The TCPNet Device allows a maximum of 4 different serving ports to be in use, supporting 4 servers to be working at once.
This call is still being validated/tested: it may not yet work reliably.