EGO network protocol
The EGO authoring system provides high-level and low-level network functions. The high-level functions let EGO transfer data between an EGO client and an HTTP or FTP server. With the high-level functions, EGO can therefore upload and download files from a remote server.
The low-level functions, which are the topic of this document, allow two EGO clients to exchange data in a peer-to-peer, group-wise mode. The low-level interface is designed such that application level protocols can be built on top of the low-level functions. For example, there is no inherent "receipt acknowledgement" handshake built into the low-level protocol, but the application can request for individual messages whether they have been well received.
The EGO low-level network functions
The EGO commands in this document will use the French names. If you have an English version of EGO, the commands are translated; for example ·ResInit() is called ·NetInit() in English. You can use the EGO help file to find the translations of EGO commands.
The EGO low-level interface is initialized with ·ResInit(). The first parameter of this command is the "socket number". This number is only used for the Novell IPX/SPX protocol. When EGO runs over TCP/IP, the socket number that it uses is always 51215 (hexadecimal: C80F).
The EGO communication is based on groups, where a group uses a "channel number". An EGO client that connects to a channel, sees all other hosts on that channel. An EGO client can furthermore only send a message to a host that is on the same channel. An EGO client uses command ·ResConnecte() to connect to a channel, and ·ResFerme() to close it. Incidentally, an EGO client can connect on multiple channels.
The messages that the EGO clients exchange are not the only messages that flow over the network: EGO also sends control messages to make group maintenance easier. For example, EGO polls the subscribers of a channel on various occasions, so that each EGO client can maintain a list of peers; see the command ·ResListeConnex() for an example.
The EGO network packet format
EGO sends data packets using the UDP protocol. All EGO packets start with the following 16-byte header:
| Packet header | ||
|---|---|---|
| Field | Size | Description |
| Protocol | 7 | A format identifier; this field always contains the string "EGOUDP" terminated with a zero-byte. |
| HeaderSize | 2 | Size of this header in bytes; this value should always be 16. |
| DataSize | 2 | Size of valid data in data block (the UDP protocol may pad the packet with extra bytes). |
| ReceiptRequest | 2 | This value is set to "1" if a the receiving host should send an acknowledgement message. For "user messages" (see below), this field is 1 if the number of retries in the command ·ResEnvoieMess() is greater than 0. For control messages, this field is usually zero. |
| PacketID | 2 | A number used in checking receipt acknowledgements. Control and data packets have different counters. |
| Command | 1 | A value that is set to 1 for a "control" packet. |
A user message has a "data" section following the header. The full packet is:
| User message | ||
|---|---|---|
| Field | Size | Description |
| Packet header | 16 | The packet header, see above. |
| DataString | 1025 | A buffer that contains the message that an EGO client sent. |
| FromName | 34 | The name of the sender, consisting of an alias and a channel number; see below for the syntax of this field. |
| ToName | 34 | The name of the intended recipient; again, see below for the syntax of this field. |
| UnitID | 2 | Currently unused (always zero). |
Names for a host have two parts: alias and channel number. An EGO client may use the same alias on different channels, and it may also connect to a channel twice, using two aliases.
| Name structure | ||
|---|---|---|
| Field | Size | Description |
| Alias | 32 | A zero-terminated string containing the name of the host. |
| Channel | 2 | The channel number. |
Command packets have the "Command" field in the packet header set to 1. The data part of the message contains a string that identifies the command and auxiliary data whose format and purpose depends on each respective command.
The next tables describe be full packets of the commands.
| Request connected names | ||
|---|---|---|
| Field | Size | Description |
| Packet header | 16 | The packet header, see above. |
| Command | 25 | The string "Get me all used names___" plus a zero-terminator. This command is typically sent as a broadcast message. |
| List local names | ||
|---|---|---|
| Field | Size | Description |
| Packet header | 16 | The packet header, see above. |
| Command | 25 | The string "Here are mine for you___" plus a zero-terminator. This command is sent in response to the "Request connected names" command. |
| Name | 34 | A structure with the newly added name (alias + channel). |
| [Name...] | 34 | The packet holds as many local names of the client that fit in a packet's maximum data size of 1025 bytes. If a client has more names than fit in 1025 bytes, the client will send multiple commands that list the local names. |
| Add local name | ||
|---|---|---|
| Field | Size | Description |
| Packet header | 16 | The packet header, see above. |
| Command | 25 | The string "I added a name__________" plus a zero-terminator. This command is typically sent as a broadcast message. |
| Name | 34 | A structure with the newly added name (alias + channel). |
| Remove local name | ||
|---|---|---|
| Field | Size | Description |
| Packet header | 16 | The packet header, see above. |
| Command | 25 | The string "I removed a name________" plus a zero-terminator. |
| Name | 34 | A structure with the local name just removed (alias + channel). |
| Receipt acknowledgement | ||
|---|---|---|
| Field | Size | Description |
| Packet header | 16 | The packet header, see above. |
| Command | 25 | The string "Confirmation for data___" plus a zero-terminator. |
| PacketID | 2 | The identifier of the packet that was received |
| Closing connection | ||
|---|---|---|
| Field | Size | Description |
| Packet header | 16 | The packet header, see above. |
| Command | 25 | The string "I closed the connection_" plus a zero-terminator. This command is typically sent as a broadcast message. All other clients remove all names that they have of the machine. |
Communicating with an EGO client
When you wish to make an application exchange messages with an EGO client, there are basically two hurdles to take. The first is that your application must adhere to the EGO protocol, as described above. This is typically an easy step, as the headers and data structures are relatively simple. The second hurdle is your application must make itself known on a channel before the EGO will be able to send messages to you or accept your messages.
In other words, the handling of control messages for the application is mandatory. At the very least, the application should send the "Add local name" and "Remove local name" control messages.