External Agent Interface Specification

External Agent Interface Specification
SchemeStation documentation

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.2.7 The functions of module ssextagent-library


File ssextagent.h

C-functions: