GERTe External Protocol API

Official Global Empire Release

Forewords

This document only describes the official API release. Third party APIs, whilst potentially reliable and useful, may not follow this document.

Versioning is defined by the format of x.y.z where x is major, y is minor, and z is patch.

The API will always maintain backwards compatibility between major versions (I.E. methods will never be removed until an increment of the major number.) The API may add new methods between major and minor versions. The API may change background behavior between major, minor, and patch versions.

The API ought to keep the major and minor versions in step with the protocol version.

Requirements

The API is designed for the OpenComputers mod for Minecraft. Without this, emulation will be required.

This API depends on the OS, Component, Filesystem, and Internet libraries (specifically OpenOS versions.)

This API also depends on TCP functionality in the Internet library as well as the associated hardware. The card must be capable of reaching the general internet or a local peer with general internet access.

The API also depends on access to a Tier 3 Data Card.

The API depends on the resolution.geds file within the current working directory. This file is managed by the GEDS team and editing is highly ill-advised.

Connecting to a Peer

To connect, first create an address from GERTe.Address. Then create an identity using GERTe.Identity using the previous address and an ec-private key.
Note: The address must be associated with the private key passed into the identity or the peer will reject the connection.

Once the identity is ready, create the connection with GERTe.Connection passing in the IP of the peer, the port to connect to, and the identity.

Data Transmission

Data must be wrapped in a GERTe.Packet class to be sent. This class takes two GERTe.Address classes, the source and the destination. The destination must be a complete address, with internal or external. If the source has an external address, it will be overridden with the identity. The final argument is the data as a string.

Once the packet is ready, send it on the connection's write method.

Data Reception

Data can be received using the read method. The read takes in either an integer timeout in seconds or nil for infinite. The method will return either with a GERTe.Packet received or nil if timed out or errored.