Improve documentation for layers and protocol

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, 
+In this state, messages are serialized according to the
\ No newline at end of file
+[SignalProxy Messages](../serialization/signalproxy_messages.md) specification.
\ No newline at end of file

docs/protocol/layers/overview.md

+# 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

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 | --                                                                   |

docs/protocol/serialization/handshake.md → 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                         |

docs/protocol/serialization/signalproxy_messages.md

+# 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` |

docs/protocol/serialization/compound.md → docs/protocol/serialization/signalproxy_objects.md

-# 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

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: