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. [](../../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