From eedb2f7525a7d4d69851f8b7a7cad2231620546b Mon Sep 17 00:00:00 2001
From: Janne Mareike Koschinski <janne@kuschku.de>
Date: Mon, 23 Dec 2019 19:10:04 +0100
Subject: [PATCH] Improve documentation for layers and protocol

---
 docs/protocol/layers/message.md               |  7 +-
 docs/protocol/layers/overview.md              |  6 ++
 docs/protocol/serialization/features.md       |  3 +
 .../{handshake.md => handshake_messages.md}   |  2 +
 .../{primitive.md => primitive_objects.md}    |  0
 .../serialization/signalproxy_messages.md     | 70 +++++++++++++++++++
 .../{compound.md => signalproxy_objects.md}   | 12 +---
 mkdocs.yml                                    |  8 ++-
 8 files changed, 92 insertions(+), 16 deletions(-)
 create mode 100644 docs/protocol/layers/overview.md
 rename docs/protocol/serialization/{handshake.md => handshake_messages.md} (97%)
 rename docs/protocol/serialization/{primitive.md => primitive_objects.md} (100%)
 create mode 100644 docs/protocol/serialization/signalproxy_messages.md
 rename docs/protocol/serialization/{compound.md => signalproxy_objects.md} (95%)

diff --git a/docs/protocol/layers/message.md b/docs/protocol/layers/message.md
index e762340..127c453 100644
--- a/docs/protocol/layers/message.md
+++ b/docs/protocol/layers/message.md
@@ -7,8 +7,8 @@ It starts off in `HANDSHAKE` state.
 
 ## Handshake State
 
-In this state, messages are encoded/decoded according to the [Handshake](../serialization/handshake.md)
-specification.
+In this state, messages are encoded/decoded according to the
+[Handshake Messages](../serialization/handshake_messages.md) specification.
 
 [![Init Diagram](../../assets/images/message_init.png)](../../assets/images/message_init.png)
 
@@ -36,4 +36,5 @@ If the client receives a CoreSetupAck, the client will proceed normally in the i
 
 ## Connected State
 
-In this state, 
\ No newline at end of file
+In this state, messages are serialized according to the
+[SignalProxy Messages](../serialization/signalproxy_messages.md) specification.
\ No newline at end of file
diff --git a/docs/protocol/layers/overview.md b/docs/protocol/layers/overview.md
new file mode 100644
index 0000000..f5d9f49
--- /dev/null
+++ b/docs/protocol/layers/overview.md
@@ -0,0 +1,6 @@
+# Layers
+
+The lowest layer is the [Framing Layer](framing.md), on top of that rests the
+[Message Layer](message.md).
+
+How to interpret those messages is going to be described at a later time.
\ No newline at end of file
diff --git a/docs/protocol/serialization/features.md b/docs/protocol/serialization/features.md
index b6cb9c3..20ae33e 100644
--- a/docs/protocol/serialization/features.md
+++ b/docs/protocol/serialization/features.md
@@ -3,6 +3,9 @@
 Legacy features encode the flags of each supported feature, extended features
 encodes a QStringList of the names of all supported features.
 
+If no flag is given, this feature is not included when legacy features are
+encoded.
+
 | Flag       | Name                   | Description                                                          |
 |------------|------------------------|----------------------------------------------------------------------|
 |`0x00000001`| SynchronizedMarkerLine | --                                                                   |
diff --git a/docs/protocol/serialization/handshake.md b/docs/protocol/serialization/handshake_messages.md
similarity index 97%
rename from docs/protocol/serialization/handshake.md
rename to docs/protocol/serialization/handshake_messages.md
index 8719c10..a31e49d 100644
--- a/docs/protocol/serialization/handshake.md
+++ b/docs/protocol/serialization/handshake_messages.md
@@ -7,6 +7,8 @@ Handshake Types are (de-)serialized to and from QVariantMaps. An additional
 key/value pair "MsgType" is added, which contains the name of the
 complexStruct’s type – for example `ClientInitAck` – as QString.
 
+For en/decoding the specified fields see [Primitive Objects](primitive_objects.md).
+
 ## ClientInit
 
 | Field          | Type          | Description                         |
diff --git a/docs/protocol/serialization/primitive.md b/docs/protocol/serialization/primitive_objects.md
similarity index 100%
rename from docs/protocol/serialization/primitive.md
rename to docs/protocol/serialization/primitive_objects.md
diff --git a/docs/protocol/serialization/signalproxy_messages.md b/docs/protocol/serialization/signalproxy_messages.md
new file mode 100644
index 0000000..ce84e78
--- /dev/null
+++ b/docs/protocol/serialization/signalproxy_messages.md
@@ -0,0 +1,70 @@
+# Sync Types
+
+Sync messages are (de-)serialized to and from QVariantLists. They are encoded
+as the request type, followed by the parameters of that type.
+
+For en/decoding the specified fields see [Primitive Objects](primitive_objects.md).
+
+## Request Type Enum
+
+| Value        | Name           | Direction     |
+|--------------|----------------|---------------|
+| `0x00000001` | SyncMessage    | bidirectional |
+| `0x00000002` | RpcCall        | bidirectional |
+| `0x00000003` | InitRequest    | C->S          |
+| `0x00000004` | InitData       | S->C          |
+| `0x00000005` | HeartBeat      | bidirectional |
+| `0x00000006` | HeartBeatReply | bidirectional |
+
+## SyncMessage
+
+| Parameter  | Type           | Description                                                                     |
+|------------|----------------|---------------------------------------------------------------------------------|
+| ClassName  | `QByteArray`   | Encoded as UTF-8                                                                |
+| ObjectName | `QByteArray`   | Encoded as UTF-8                                                                |
+| SlotName   | `QByteArray`   | Encoded as UTF-8                                                                |
+| Params     | `QVariantList` | Not an actual parameter, just the remaining elements of the list (may be empty) |
+
+## RpcCall
+
+| Parameter | Type           | Description                                                                     |
+|-----------|----------------|---------------------------------------------------------------------------------|
+| SlotName  | `QByteArray`   | Encoded as UTF-8                                                                |
+| Params    | `QVariantList` | Not an actual parameter, just the remaining elements of the list (may be empty) |
+
+## InitRequest
+
+| Parameter  | Type         | Description      |
+|------------|--------------|------------------|
+| ClassName  | `QByteArray` | Encoded as UTF-8 |
+| ObjectName | `QByteArray` | Encoded as UTF-8 |
+
+## InitData
+
+| Parameter  | Type          | Description      |
+|------------|---------------|------------------|
+| ClassName  | `QByteArray`  | Encoded as UTF-8 |
+| ObjectName | `QByteArray`  | Encoded as UTF-8 |
+| InitData   | `QVariantMap` | See below        |
+
+The InitData field is not an actual parameter, just the remaining elements of
+the list (may be empty), grouped into pairs of 2, interpreted as key and value
+respectively.
+
+These are according to the [SignalProxy Objects](signalproxy_objects.md)
+specification.
+
+## HeartBeat
+
+| Parameter | Name        |
+|-----------|-------------|
+| Timestamp | `QDateTime` |
+
+In case this is received, the other side expects a corresponding HeartBeatReply
+with the same timestamp.
+
+## HeartBeatReply
+
+| Parameter | Name        |
+|-----------|-------------|
+| Timestamp | `QDateTime` |
diff --git a/docs/protocol/serialization/compound.md b/docs/protocol/serialization/signalproxy_objects.md
similarity index 95%
rename from docs/protocol/serialization/compound.md
rename to docs/protocol/serialization/signalproxy_objects.md
index b5480fc..cf4d756 100644
--- a/docs/protocol/serialization/compound.md
+++ b/docs/protocol/serialization/signalproxy_objects.md
@@ -1,6 +1,6 @@
-# Compound Types
+# SignalProxy Objects
 
-This document discusses how complex objects are translated to and from
+This document discusses how sync objects are translated to and from
 QVariantMaps.
 
 ## Network::Server
@@ -23,14 +23,6 @@ type:
 | ProxyUser  | `QString`  | --          |
 | ProxyPass  | `QString`  | --          |
 
-## SessionState
-
-| Field       | Type                       | Description |
-|-------------|----------------------------|-------------|
-| Identities  | `QVariantList<Identity>`   | --          |
-| BufferInfos | `QVariantList<BufferInfo>` | --          |
-| NetworkIds  | `QVariantList<NetworkId>`  | --          |
-
 ## Identity
 
 Warning: This type has, when serialized, QVariantType "Network::Server" (which
diff --git a/mkdocs.yml b/mkdocs.yml
index 503b910..62c5ec1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,13 +13,15 @@ nav:
     - "Upgrade Guide": usage/upgrade_guide.md
   - "Protocol":
     - "Layers":
+      - "Overview": protocol/layers/overview.md
       - "Framing": protocol/layers/framing.md
       - "Message": protocol/layers/message.md
     - "Serialization":
-      - "Primitive Types": protocol/serialization/primitive.md
-      - "Compound Types": protocol/serialization/compound.md
+      - "Handshake Messages": protocol/serialization/handshake_messages.md
       - "Features": protocol/serialization/features.md
-      - "Handshake": protocol/serialization/handshake.md
+      - "SignalProxy Messages": protocol/serialization/signalproxy_messages.md
+      - "SignalProxy Objects": protocol/serialization/signalproxy_objects.md
+      - "Primitive Objects": protocol/serialization/primitive_objects.md
 
 extra:
   social:
-- 
GitLab