Project Fairdice
[Home] [Docs] [Users] [Gaming] [Crypto] [Devel] [Download] [Help]

Fairdice Protocol v0.3 : Link Facilities

Letter Name Description
D Describe Describe in a user readable way an app
K Keepalive Keep the link alive with pings and time synchs
L Link Link opening and closing (like TCP/IP ack and fin)
U Understand I do not understand the message you just sent me
[Definition]
LINK_MESSAGE = ("D " DESCRIBE_STR) | ("K " KEEPALIVE_STR) | ("L " LINK_STR) | ("U " UNDERSTAND_STR)
; these are defined in this file

Describe

[Definition]
DESCRIBE_STR = DESCRIBE_REQUEST | DESCRIBE_RESPONSE | DESCRIBE_NULL
DESCRIBE_REQUEST = "request"
DESCRIBE_RESPONSE = "is " DESCRIPTION
DESCRIBE_NULL = "null"
DESCRIPTION = 1*250<ALLOWED_CHAR>

[Sequence]
A describe sequence may only be sent once per direction per connection.

A describe sequence should be sent after the version sequence and before any game sequences.

Valid sequences are:

  1. DESCRIBE_RESPONSE
or
  1. DESCRIBE_REQUEST
  2. DESCRIBE_RESPONSE
or
  1. DESCRIBE_REQUEST
  2. DESCRIBE_NULL

[Example]
DESCRIBE_RESPONSE = "is Douglas Reay <douglasreay@sourceforge.net>"
; sent user to client
; or
DESCRIBE_REQUEST = "request"
; sent server to host
DESCRIBE_RESPONSE = "is http://www.harry.com:22300/"
; sent host to server

Keepalive

[Definition]
KEEPALIVE_STR = KEEPALIVE_PING_REQUEST | KEEPALIVE_PING_RESPONSE | KEEPALIVE_TIME_REQUEST | KEEPALIVE_TIME_RESPONSE | KEEPALIVE_NULL
KEEPALIVE_PING_REQUEST = "ping request " PING_SEQUENCE_NUMBER
PING_SEQUENCE_NUMBER = <any decimal integer between 1000 and 9999 (inclusive)>
KEEPALIVE_PING_RESPONSE = "ping respond " PING_SEQUENCE_NUMBER
KEEPALIVE_TIME_REQUEST = "time request"
KEEPALIVE_TIME_RESPONSE = "time respond " TIMESTAMP
; TIMESTAMP is the ISO 8601 one defined by BNF
KEEPALIVE_NULL = "null"

[Sequence]
A keepalive sequence may be sent any number of times.

Keepalive sequences may be sent any time after the version sequence and before the link close sequence

Valid sequences are:

  1. KEEPALIVE_NULL
or
  1. KEEPALIVE_PING_REQUEST
  2. KEEPALIVE_PING_RESPONSE
or
  1. KEEPALIVE_TIME_REQUEST
  2. KEEPALIVE_TIME_RESPONSE

[Example]
KEEPALIVE_TIME_REQUEST = "time request"
; sent client to server
KEEPALIVE_TIME_RESPONSE = "time respond 2004-08-17T14:06:42TZ"
; sent server to client
; or
KEEPALIVE_PING_REQUEST = "ping request 8872"
; sent user to client
KEEPALIVE_PING_RESPONSE = "ping respond 8872"
; sent client to user

Link

[Definition]
LINK_STR = LINK_OPENING | LINK_OPENED | LINK_CLOSING | LINK_CLOSED
LINK_OPENING = "opening"
LINK_OPENED = "opened"
LINK_CLOSING = "closing"
LINK_CLOSED = "closed"

[Sequence]
There are two valid link sequences.

the link opening sequence:

  1. LINK_OPENING
  2. LINK_OPENED

the link closing sequence

  1. LINK_CLOSING
  2. LINK_CLOSED

The link opening sequence may only be sent once per connection. It must be sent before any other sequences.

The link closing sequence may only be sent once per connection. It must be sent after any other sequences.

Understand

[Definition]
UNDERSTAND_STR = UNDERSTAND_RESPONSE | UNDERSTAND_NULL
UNDERSTAND_RESPONSE = MESSAGE
; specifically, the message that was not understood in which this has been sent in response to
UNDERSTAND_NULL = "null"
; sent when the app has no text to send to explain what it is puzzeled about, but still wishes to indicate puzzelment.

[Example]
MESSAGE = "K ping request 1234"
; sent client to server
MESSAGE = "K ping respond 123"
; sent server to client
MESSAGE = "U K ping respond 123"
; sent client to server
; sent on the ground the client doesn't recognise that PING_SEQUENCE_NUMBER

(TOP)(UP)