Version 1
This document specifies the protocol by which a DAIDE client should communicate with a DAIDE server. It should be read in conjunction with the Parlance Message Syntax. The remainder of this document is structured as follows:
This document is aimed at people who wish to:
The following issues have been identified with this protocol and are under investigation.
This section defines the transport mechanism to be used.
Client-server communications will be carried out over a TCP connection.
The server will publish an address and TCP port on which the server can be contacted. The method of publishing the address is outside the scope of this document.
The server will open a listening connection on the published TCP port. It is recommended that a backlog of at least 10 connections be used where available to prevent unnecessary client connection failure.
Following a connection from a client, the server will continue to listen for further connections from clients on the original socket.
When a client connects to the server, the server will set the SO_KEEPALIVE socket option on the newly created socket. This causes dead connections to be cleared by the server.
The server will run a 30-second initial message timer. If the server hasn't received any data when the timer pops, the server will send an error message (see below) and terminate the connection.
If a client sends data over a connection with an invalid message structure (see chapter 3), the server will terminate the connection.
To communicate with a server, a client shall first establish a TCP connection to the address and port published by the server. The client may use any free local port.
The client will set the SO_KEEPALIVE socket option on the socket connected to the server.
Immediately following the establishment of a connection, the client shall send an Initial Message (see section 3.2).
Once a connection has been established, the two parties may transfer messages as described in this section. Both parties may send messages at any time except as limited below.
All message structures described in this section are shown in network byte order (big endian). Implementers of clients or servers for little endian machines (for example, Intel) should take care to swap the octets of multi-octet fields.
All messages sent between a client and a server will have the following message structure.
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Type | Pad | Remaining Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Optional Data | | . | | . | | . |
This is a fixed-length message.
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Type | Pad | Remaining Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Version | Magic Number | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This message is sent from the client to the server as soon as the connection has been opened. If the server discovers incompatible version numbers, it will send an error message and close the connection. Note that a single instance of a server may be able to talk several different protocol versions over different connections.
The message contains a magic number that is designed to quickly catch connections that have (inadvertently or deliberately) been made to the server by a program other than a DAIDE Client. Because the magic number's bit pattern is not the same forwards and backwards, it will also catch clients who have failed to send in network byte order. The message is only ever sent from the client to the server and it is only sent once.
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Type | Pad | Remaining Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Representation Message | | . | | . | | . |
This mandatory message is sent from the server to the client immediately on receipt of the IM. It is used to define additional power and province tokens that will be valid for the variant of the game that the server is set up to adjudicate for. It will also give a text representation of any such tokens. If there are no such tokens, the remaining length will be zero. If there are additional tokens, the remaining length will be a multiple of six. Each six-octet block will consist of the following:
If the RM has non-zero length then none of the powers or provinces defined in chapter 4 are valid. Instead, the powers and provinces defined in the RM are the only valid powers and provinces. Note that if a variant uses the standard powers on a variant board or variant powers on the standard board, both the provinces and the powers must be defined in the RM.
The same token must not appear in the RM more than once.
When defining provinces, the low-octet of the province tokens must be unique and form a sequence starting at 0 and incrementing by 1 up to the number of provinces less 1.
When defining powers, the low-octet of the power tokens must be unique and form a sequence starting at 0 and incrementing by 1 up to the number of powers less 1.
This message is only ever sent from the server to the client. It is sent immediately following the IM, and at other times under limited circumstances.*
This is a variable-length message.
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Type | Pad | Remaining Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Language Message | | . | | . | | . |
The optional data part contains a single “language message” as described in the Language Syntax. The language message is encoded as described in the chapter “Language Representation”. It can be sent by either party following the RM.
This is a fixed-length message.
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Type | Pad | Remaining Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This message is sent immediately before the either party closes the TCP connection. It is not sent if an error message has been sent. On receipt, the receiving party will immediately close the connection without sending a final message or error message.
This is a fixed-length message.
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Message Type | Pad | Remaining Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Error code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This message indicates that the sending party has detected a protocol error. An EM may be sent at any time. The party sending this message will terminate the connection immediately after sending it. The error codes are defined in the following table.
| Code | Meaning |
| 0x01 | IM timer popped |
| 0x02 | IM was not the first message sent by the client |
| 0x03 | IM indicated the wrong endian |
| 0x04 | IM had an incorrect magic number |
| 0x05 | Version incompatibility |
| 0x06 | More than one IM sent |
| 0x07 | IM sent by server |
| 0x08 | Unknown message received |
| 0x09 | Message shorter than expected |
| 0x0A | DM sent before RM |
| 0x0B | RM was not the first message sent by the server |
| 0x0C | Unexpected RM sent* |
| 0x0D | RM sent by client |
| 0x0E | Invalid token in DM |
Note that this message will not be sent due to a language error. Language errors are handled in the language itself (see Chapter 4).
On receipt of an error message, the receiving party will immediately close the connection without sending an error message or final message.
This section describes how a language message is encoded into the data part of a Diplomacy Message (see above).
Every language token will be represented by a 2-octet field.
The tokens are split into categories. Each category will have a 1-octet value associated with it. The tokens within each category will be numbered. The token value can be calculated by multiplying the category by 256 and adding the token number within the category.
This method means that the protocol is extensible and allows simple determination of a token category from the top octet. Tokens not listed here may be valid, and thus should not trigger Error Message 0x0E unless they can be determined invalid for other reasons; for example, tokens in the Reserved category are always invalid.*
The category space is divided as follows:
Of the 256 possible categories, 88 are assigned and the remaining 168 are reserved for future use. In those 168, a full 128-category block remains as well as a 32-category block. These blocks may be further subdivided in the future if appropriate.
The remainder of this chapter defines the categories, their value and the token numbers within the category.
The representable range of integers is -8192 to +8191. They are coded as a 14-bit two's-complement value. The top two bits of the category are always zero.
Note that the high three bits can be used to determine which phase the order is valid in. The top bit is valid the adjustments phase, the next is valid in the retreats phase and the last is valid in the movement phase.
The value is the ASCII code for a single letter. Strings are not delimited with quotation marks or anything else. There are no situations in the language where one string runs directly into another. Therefore, the end of a string can be identified when the first non-text token is received.
There are eight province categories as defined here.
On the standard map there are no sea SCs.
On the standard map there are no non-SC bicoastal provinces.
Note that the province values form a sequence starting at zero and leading up to 74 (giving 75 provinces in total). It will always be possible to use the bottom octet to index into a zero-based array. The low bit of the category determines whether the province is a supply centre or not. The next two bits can be used to determine province type.
These categories will never be assigned another use. Software writers are free to use these categories as they see fit. However, they must never be sent over the wire.
This chapter lists the differences between this document and revision 14 of The Diplomacy Centralisation Project Client-Server Protocol.
The official protocol only allows the Representation Message to be sent once; however, to support game selection, Parlance allows the server to send a new RM in response to specific Diplomacy Messages sent by the client. In conjunction with this, Error Message 0x0C has a slightly different description in this document.
The official document is less specific about when to send Error Message 0x0E; some implementations of this protocol have been known to send it upon receiving any unknown token, even in a DM that could be safely ignored. Now that clients are allowed to send HUH messages to the server, there is no longer any need for such behavior.
The SMR token has been added to this document, with its value as accepted by the DAIDE community. The CHO, BCC, and UNT were not originally in revision 14, but have been added to at least one version of the document claiming that number. In fact, the original revision 14 document assigns token number 0x4A22 to WRT, but no software ever used that number for it, and its use is now officially discouraged.
Punctuation, grammar, style, naming, and metadata have been changed in several places, but do not affect the meaning of the document.