External Agent Interface Specification

Document formatted by vherva at Fri Apr 24 11:23:39 1998 on the host schemestation. This document is produced by the SchemeStation project during the Tik-76.115 course.

1 Introduction
	Apart from the native ("internal") agents, that run in the SCHEMESTATION virtual machine, have heaps and are addressed by the addressing system, this simulation provides an interface for external agents to connect to the SCHEMESTATION domain. The external agents can be any entities that implement the SCHEMESTATION external agent interface protocol defined in this document. In particular, they do not have to be programmed in scheme, and do not run in the virtual machine. They are however addressed by the addressing system. The motive for this kind of external agent system is to isolate from the kernel some of the needed functions that can not be implemented in scheme. Such services might include file server on top of the unix file system, a TCP server, or any arbitratry interface to a unix resource. For this simulation, we have implemented the file server, TCP server, and, as an example, an interface to the Gnu Chess game. For more information on these example external agent, please refer to External agents. In order to make implementing a peer that complies eith the the SCHEMESTATION external agent interface protocol, we provide a C-library for communicating with the SCHEMESTATION domain.
2 The Nature of the Communication
	The communication provided by SCHEMESTATION is reliable in general. This also applies to the external agent interface. The communication is not reliable in terms of being able to survive a hardware failure or network fault by any means. Moreover no acknowledgement are sent at the arrival of a packet. In essence this means that in ordinary conditions (the underlying UNIX system is working properly) no packets will be lost. The external agent interface is implemented on top of TCP/IP. There is a extarnal agent server in the SCHEMESTATION end of the communication. It listens to a port same way the networking server does. When an external agent connects to the server, the peers execute a hand-shake defined below. After that the peers may begin communication in packet-oriented manner. The difference between the networking module and the external agent server is that neither the external agent server nor the agent it self need to be aware of agent specifiers. Instead, the kernel always request the server to send a packet to a specified connection, which naturally unambiguoysly defines the external agent. On the other hand, the external agent merely sends packets to the connection, relies on that there is a (native) interface agent in the SCHEMESTATION domain, that receives all the packets that the external agent has sent, and (presumably) delivers them further.
3 The hand-shake
	As a external agent (referred as to "client" below) connects to the SCHEMESTATION external agent interface server (referred as to "server" below), the server first accepts the TCP connection. The server then expects the client ot send the client magic cookie (0xef,0xfe,0xff,0xee) and after receiving that sends its own cookie (0xF0,0x00,0xF00,0x00). When this phase has been carried out, a SCHEMESTATION external agent interface connection is gareed to have been established, and the peers are free to send packet messages. Furthermore, apart from the hand-shake in the server's point of view, the SCHEMESTATION kernel agent expects to receive a identification string from he new client as the first packet. This way the kernel can spawn a new interface agent, depending on what kind of client has made the connection. The identification strings are just ascii strings, such as "tcpserver", "fileserver" or "chessserver". Unless the identification strings known by the kernel, the kernel instructs the server to drop the connection.
4 Packet format
	The packets consists of the data length field and the data. The Data length occupies the first four octets of the packet and indicates the length of the following data in octets. The data length is encoded in network byte order.
5 The ssextagent library
	In order to make it easier for the programmers to write external agent, we provide a library that complies with the extranal agent interface protocol. The interface to this library is defined below.
6 The functions of module ssextagent-library
	File ssextagent.h C-functions: ExtagStatus ssexact_blockingread(IN SsexConn* conn, OUT char** data, OUT int* len) Description: void ssexact_close(IN SsexConn* conn) Description: Closes the connection to the SchemeStation domain indentified by fd. int ssexact_fd(IN SsexConn* conn) Description: Returns the number of the fd for selecting etc. ExtagStatus ssexact_initialize(IN char *hostname, IN unsigned long ipaddr, IN unsigned short tcpport, OUT SsexConn** conn) Description: Initializes the ssextag interface instance and opens a connection to the SchemeStation domain specified by addr. Returns a fd for which the following semantics apply: * To ensure consistent operations, the fd should be read or written only using ssextag_send and ssextag_read functions. * The ssextag_read function call is non-blocking provided that it has been preceded by a call to select() returns ExtagStatus ssexact_read(IN SsexConn* conn, OUT char** data, OUT int* len) Description: Tries to read a message from the connection given by fd. The fd should be got from ssextag_initialize. The function unblocking sematics provided that the call is preceded by a successfull call to select that has returned ready to ready status for the fd. Unless this condition is met, blocking may take place. The data read is stored to dynamically allocated memory pointed the pointer data. The caller is responsible for deallocating the memory. The function returns EXTAG_OK and the length len on successful completition - that is when a complete message has been stored in the data struct. If the read discontinues in the middle of the packet, EXTAG_UNFINISHED is returned, the data is set to point to the read data, the len is set to the read message length. The ssextag_read maintains its internal state and automagically continues to read the unfinished message on next call. ExtagStatus ssexact_send(IN SsexConn* conn, IN int size, IN char* data) Description: Sends the size-long message (in bytes) data to the ActorAddress. Does not free any memory the arguments hold. The memory area that contains the packet data may be modified after this function returns; a copy of the packet is made internally if needed. Return EXTAG_OK if succeeded, EXTAG_FAILED if the packet cannot be delivered (SIZE <= 0 or tcp connection fails). A call to ssextact_send _may_ block. int ssextact_fd(IN SsexConn* conn) Description: Returns the fd from the SsexConn struct.