diff --git a/docs/protocol/serialization/primitive_objects.md b/docs/protocol/serialization/primitive_objects.md index 8202bb06965973072b59a3fc013dd0e5634a5758..2800a74f7feab79de6dfca9da2e0797ef2ead9ed 100644 --- a/docs/protocol/serialization/primitive_objects.md +++ b/docs/protocol/serialization/primitive_objects.md @@ -7,6 +7,25 @@ Serialization of basic types is trivial and will not be discussed here. Primitive types are serialized by serializing each of their fields sequentially. +## Type Aliases + +Certain types have a representation which is identical to a pre-existing type +in this document. For this reason, we do not define them twice, but list the +type whose network representation they borrow here: + +|Type name | Network representation | +|-------------- | ---------------------- | +|BufferId | `Int` | +|IdentityId | `Int` | +|NetworkId | `Int` | +|MsgId | `Long` | +|PeerPtr | `Long` | +|IrcUser | `QVariantMap` | +|IrcChannel | `QVariantMap` | +|Identity | `QVariantMap` | +|NetworkInfo | `QVariantMap` | +|Network::Server| `QVariantMap` | + ## String Strings are serialized as a signed int of the length in bytes plus their content diff --git a/docs/protocol/serialization/signalproxy_objects.md b/docs/protocol/serialization/signalproxy_objects.md index cf4d756ac2b68e63342c79cc6c369ce56175cec9..37bdaf94e54740899396f92650bb8fb1dc44c734 100644 --- a/docs/protocol/serialization/signalproxy_objects.md +++ b/docs/protocol/serialization/signalproxy_objects.md @@ -1,188 +1,621 @@ # SignalProxy Objects -This document discusses how sync objects are translated to and from -QVariantMaps. - -## Network::Server - -Warning: This type has, when serialized, QVariantType "Network::Server" (which -is a usertype), but actually is just a QVariantMap for the following complex -type: - -| Field | Type | Description | -|------------|------------|-------------| -| UseSSL | `Bool` | -- | -| sslVersion | `Int` | -- | -| Host | `QString` | -- | -| Port | `Int` | -- | -| Password | `QString` | -- | -| UseProxy | `Bool` | -- | -| ProxyType | `Int` | -- | -| ProxyHost | `QString` | -- | -| ProxyPort | `Int` | -- | -| ProxyUser | `QString` | -- | -| ProxyPass | `QString` | -- | +SignalProxy objects are special, because these are actual classes you’ll use in +your representation of the client state, with actual behavior (described in +another document). -## Identity +All of these objects are translated into `QVariantMap` as network +representation, this document describes their fields at runtime, and how those +are translated into the maps used in `InitData` responses and arguments to +`Sync` and `RPC` messages. + +All types in this document are written in typescript typings notation. + +## AoS to SoA + +For most network objects, the runtime representation contains a +"Array of Structures" (AoS), while, for better compression, on the network a +"Structure of Arrays" (SoA) representation is used. + +As this protocol uses QVariantMap with QString keys in UTF-16BE, this saves +significant overhead. + +This means a runtime representation of +```json +[ + { "name": "intro", "expansion": "/welcome $1; /assist" }, + { "name": "welcome", "expansion": "/say Welcome to the support channel for the IRC client Quassel, $1"}, + { "name": "assist", "expansion": "/say How may I assist you today?" } +] +``` + +is translated into + +```json +{ + "names": [ "intro", "welcome", "assist" ], + "expansions": [ "/welcome $1; /assist", "/say Welcome to the support channel for the IRC client Quassel, $1", "/say How may I assist you today?" ] +} +``` -Warning: This type has, when serialized, QVariantType "Network::Server" (which -is a usertype), but actually is just a QVariantMap for the following complex -type: - -| Field | Type | Description | -|-------------------------|---------------|-------------| -| identityId | `IdentityId` | -- | -| identityName | `QString` | -- | -| realName | `QString` | -- | -| nicks | `QStringList` | -- | -| awayNick | `QString` | -- | -| awayNickEnabled | `Bool` | -- | -| awayReason | `QString` | -- | -| awayReasonEnabled | `Bool` | -- | -| autoAwayEnabled | `Bool` | -- | -| autoAwayTime | `Int` | -- | -| autoAwayReason | `QString` | -- | -| autoAwayReasonEnabled | `Bool` | -- | -| detachAwayEnabled | `Bool` | -- | -| detachAwayReason | `QString` | -- | -| detachAwayReasonEnabled | `Bool` | -- | -| ident | `QString` | -- | -| kickReason | `QString` | -- | -| partReason | `QString` | -- | -| quitReason | `QString` | -- | +## QVariantMap to QVariantList + +This translation is also common, it means that a QVariantMap is serialized as +QVariantList with keys and values interspersed. + +This means a runtime representation of + +```json +{ "name": "intro", "expansion": "/welcome $1; /assist" } +``` + +is translated into + +```json +[ "name", "intro", "expansion", "/welcome $1; /assist" ] +``` ## AliasManager -| Field | Type | Description | -|------------|---------------|-------------| -| names | `QStringList` | -- | -| expansions | `QStringList` | -- | +### Runtime + +```typescript +interface AliasManager { + aliases: [Alias] + + + // C->S calls + + /** + * Replaces all properties of the object with the content of the + * "properties" parameter. This parameter is in network representation. + */ + update(properties: QVariantMap) + + + // S->C calls + + addAlias(name: QString | null, expansion: QString | null) + /** + * Replaces all properties of the object with the content of the + * "properties" parameter. This parameter is in network representation. + */ + update(properties: QVariantMap) +} + +interface Alias { + name: QString, + expansion: QString +} +``` + +### Network + +Applied translations: + +- [AoS to SoA](#aos-to-soa) + +```typescript +interface AliasManager { + Aliases: QVariantMap{ + names: QStringList, + expansions: QStringList + } +} +``` + +## BacklogManager + +### Runtime + +```typescript +interface BacklogManager { + + + // C->S calls + + /** + * Loads backlog for `bufferId`, starting at message `first`, up to `last` + * (plus `additional` more messages after `last`) but at most `limit` + * messages total. + */ + requestBacklog(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, additional: Int) + /** + * Same as `requestBacklog`, but only messages of a certain message `type` + * with certain `flags` set. + */ + requestBacklogFiltered(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, additional: Int, type: Int, flags: Int) + /** + * Same as `requestBacklog`, but applied to all buffers. + */ + requestBacklogAll(first: MsgId, last: MsgId, limit: Int, additional: Int) + /** + * Same as `requestBacklogFiltered`, but applied to all buffers. + */ + requestBacklogAllFiltered(first: MsgId, last: MsgId, limit: Int, additional: Int, type: Int, flags: Int) + + + // S->C calls + + /** + * The response to `requestBacklog`, with the messages encoded as QVariants + * in the `messages` parameter. + */ + receiveBacklog(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, additional: Int, messages: QVariantList) + /** + * The response to `requestBacklogFiltered`, with the messages encoded as + * QVariants in the `messages` parameter. + */ + receiveBacklogFiltered(bufferId: BufferId, first: MsgId, last: MsgId, limit: Int, additional: Int, type: Int, flags: Int, messages: QVariantList) + /** + * The response to `requestBacklogAll`, with the messages encoded as + * QVariants in the `messages` parameter. + */ + receiveBacklogAll(first: MsgId, last: MsgId, limit: Int, additional: Int, messages: QVariantList) + /** + * The response to `requestBacklogAllFiltered`, with the messages encoded as + * QVariants in the `messages` parameter. + */ + receiveBacklogAllFiltered(first: MsgId, last: MsgId, limit: Int, additional: Int, type: Int, flags: Int, messages: QVariantList) +} +``` + +### Network + +Its network representation is an empty `QVariantMap`, as it has no syncable +fields. For the same reason it also does **not** support the otherwise standard +`update` call. ## BufferSyncer -| Field | Type | Description | -|-------------|-------------------------|-------------| -| LastSeenMsg | `QVariantList<Integer>` | -- | -| MarkerLines | `QVariantList<Integer>` | -- | +### Runtime + +```typescript +interface BufferSyncer { + /** + * A bitset of all message types of unread messages for each chat. + */ + activities: Map<BufferId, Message.Type>, + /** + * Number of unread messages with highlights per chat. + */ + highlightCounts: Map<BufferId, Int>, + /** + * The last "marked as read" message per chat + */ + lastSeenMsg: Map<BufferId, MsgId>, + /** + * The scrollposition at the bottom of the window of the last client that had + * each chat open + */ + markerLine: Map<BufferId, MsgId> + + + // C->S calls + + requestMarkBufferAsRead(buffer: BufferId) + requestMergeBuffersPermanently(buffer1: BufferId, buffer2: BufferId) + requestPurgeBufferIds() + requestRemoveBuffer(buffer: BufferId) + requestRenameBuffer(buffer: BufferId) + requestSetLastSeenMsg(buffer: BufferId, msgid: MsgId) + requestSetMarkerLine(buffer: BufferId, msgid: MsgId) + + // S->C calls + + markBufferAsRead(buffer: BufferId) + mergeBuffersPermanently(buffer1: BufferId, buffer2: BufferId) + removeBuffer(buffer: BufferId) + renameBuffer(buffer: BufferId, newName: QString | null) + setBufferActivity(buffer: BufferId, activity: Int) + setHighlightCount(buffer: BufferId, count: Int) + setLastSeenMsg(buffer: BufferId, msgId: MsgId) + setMarkerLine(buffer: BufferId, msgId: MsgId) +} +``` + +### Network + +Applied translations: + +- [QVariantMap to QVariantList](#qvariantmap-to-qvariantlist) + +```typescript +interface BufferSyncer { + Activities: QVariantList[BufferId | Int], + HiglightCounts: QVariantList[BufferId | Int], + LastSeenMsg: QVariantList[BufferId | MsgId], + MarkerLines: QVariantList[BufferId | MsgId] +} +``` ## BufferViewConfig -| Field | Type | Description | -|----------------------------|-------------------------|-------------| -| bufferViewName | `QString` | -- | -| TemporarilyRemovedBuffers | `List<Integer>` | -- | -| hideInactiveNetworks | `Bool` | -- | -| BufferList | `List<Integer>` | -- | -| allowedBufferTypes | `Int` | -- | -| sortAlphabetically | `Bool` | -- | -| disableDecoration | `Bool` | -- | -| addNewBuffersAutomatically | `Bool` | -- | -| networkId | `Int` | -- | -| minimumActivity | `Int` | -- | -| hideInactiveBuffers | `Bool` | -- | -| RemovedBuffers | `QVariantList<Integer>` | -- | +### Runtime + +```typescript +interface BufferViewConfig { + buffers: [BufferId], + removedBuffers: [BufferId], + temporarilyRemovedBuffers: [BufferId], + + bufferViewId: Int, + bufferViewName: QString, + networkId: NetworkId, + addNewBuffersAutomatically: Bool, + sortAlphabetically: Bool, + hideInactiveBuffers: Bool, + hideInactiveNetworks: Bool, + disableDecoration: Bool, + allowedBuffersTypes: Int, + minimumActivity: Int, + showSearch: Bool + + + // C->S calls + + requestAddBuffer(bufferId: BufferId, pos: Int) + requestMoveBuffer(bufferId: BufferId, pos: Int) + requestRemoveBuffer(bufferId: BufferId) + requestRemoveBufferPermanently(bufferId: BufferId) + requestSetBufferViewName(bufferViewName: QString | null) + /** + * Replaces all properties of the object with the content of the + * "properties" parameter. This parameter is in network representation. + */ + update(properties: QVariantMap) + + + // S->C calls + addBuffer(bufferId: BufferId, pos: Int) + moveBuffer(bufferId: BufferId, pos: Int) + removeBuffer(bufferId: BufferId) + removeBufferPermanently(bufferId: BufferId) + setAddNewBuffersAutomatically(addNewBuffersAutomatically: Bool) + setAllowedBufferTypes(bufferTypes: Int) + setBufferViewName(bufferViewName: QString | null) + setDisableDecoration(disableDecoration: Bool) + setHideInactiveBuffers(hideInactiveBuffers: Bool) + setHideInactiveNetworks(hideInactiveNetworks: Bool) + setMinimumActivity(activity: Int) + setNetworkId(networkId: NetworkId) + setShowSearch(showSearch: Bool) + setSortAlphabetically(sortAlphabetically: Bool) + /** + * Replaces all properties of the object with the content of the + * "properties" parameter. This parameter is in network representation. + */ + update(properties: QVariantMap) +} +``` + +### Network + +```typescript +interface BufferViewConfig { + BufferList: QVariantList[BufferId], + RemovedBuffers: QVariantList[BufferId], + TemporarilyRemovedBuffers: QVariantList[BufferId], + + bufferViewName: QString, + networkId: NetworkId, + addNewBuffersAutomatically: Bool, + sortAlphabetically: Bool, + hideInactiveBuffers: Bool, + hideInactiveNetworks: Bool, + disableDecoration: Bool, + allowedBuffersTypes: Int, + minimumActivity: Int, + showSearch: Bool +} +``` ## BufferViewManager -| Field | Type | Description | -|---------------|-------------------------|-------------| -| BufferViewIds | `QVariantList<Integer>` | -- | +### Runtime + +```typescript +interface BufferViewManager { + bufferViewConfigs: Map<Int, BufferViewConfig>, + + + // C->S calls + + requestCreateBufferView(properties: QVariantMap) + requestCreateBufferViews(properties: QVariantList) + requestDeleteBufferView(bufferViewId: Int) + requestDeleteBufferViews(bufferViews: QVariantList) + /** + * Replaces all properties of the object with the content of the + * "properties" parameter. This parameter is in network representation. + */ + update(properties: QVariantMap) + + + // S->C calls + + addBufferViewConfig(bufferViewConfigId: Int) + deleteBufferViewConfig(bufferViewConfigId: Int) + newBufferViewConfig(bufferViewConfigId: Int) + /** + * Replaces all properties of the object with the content of the + * "properties" parameter. This parameter is in network representation. + */ + update(properties: QVariantMap) +} +``` + +### Network + +```typescript +interface BufferViewManager { + BufferViewIds: QVariantList[Int] +} +``` + +## CertManager + +### Runtime + +```typescript +interface CertManager { + sslKey: QByteArray, + sslCert: QByteArray + + + // C->S calls + + /** + * Replaces all properties of the object with the content of the + * "properties" parameter. This parameter is in network representation. + */ + update(properties: QVariantMap) + + + // S->C calls + + setSslCert(encoded: QByteBuffer | null) + setSslKey(encoded: QByteBuffer | null) + /** + * Replaces all properties of the object with the content of the + * "properties" parameter. This parameter is in network representation. + */ + update(properties: QVariantMap) +} +``` + +### Network + +```typescript +interface CertManager { + sslKey: QByteArray, + sslCert: QByteArray +} +``` + +## CoreInfo + +### Runtime + +```typescript +interface CoreInfo { + coreData: CoreData + + // S->C calls + setCoreData(coreData: QVariantMap) + /** + * Replaces all properties of the object with the content of the + * "properties" parameter. This parameter is in network representation. + */ + update(properties: QVariantMap) +} + +interface CoreData { + quasselVersion: QString, + quasselBuildDate: QString, + startTime: QDateTime, + sessionConnectedClients: Int, + sessionConnectedClientData: [ConnectedClient] +} + +interface ConnectedClient { + id: Int, + remoteAddress: String, + location: String, + clientVersion: String, + clientVersionDate: String, + connectedSince: QDateTime, + secure: Bool, + features: Int, + featureList: QStringList +} +``` + +### Network + +```typescript +interface CoreInfo { + coreData: { + quasselVersion: QString, + quasselBuildDate: QString, + startTime: QDateTime, + sessionConnectedClients: Int, + sessionConnectedClientData: QVariantList[ + QVariantMap{ + id: Int, + remoteAddress: String, + location: String, + clientVersion: String, + clientVersionDate: String, + connectedSince: QDateTime, + secure: Bool, + features: Int, + featureList: QStringList + } + ] + } +} +``` + +## DccConfig + +### Runtime + +```typescript +interface DccConfig { + +} +``` + +### Network + +```typescript +interface DccConfig { + +} +``` + +## HighlightRuleManager + +### Runtime + +```typescript +interface HighlightRuleManager { + +} +``` + +### Network + +```typescript +interface HighlightRuleManager { + +} +``` + +## Identity + +### Runtime + +```typescript +interface Identity { + +} +``` + +### Network + +```typescript +interface Identity { + +} +``` ## IgnoreListManager -| Field | Type | Description | -|------------|-------------------------|-------------| -| scope | `QVariantList<Integer>` | -- | -| ignoreType | `QVariantList<Integer>` | -- | -| isActive | `QVariantList<Boolean>` | -- | -| scopeRule | `QStringList` | -- | -| isRegEx | `QVariantList<Boolean>` | -- | -| strictness | `QVariantList<Integer>` | -- | -| ignoreRule | `QStringList` | -- | +### Runtime + +```typescript +interface IgnoreListManager { + +} +``` + +### Network + +```typescript +interface IgnoreListManager { + +} +``` ## IrcChannel -| Field | Type | Description | -|-----------|---------------|-------------| -| name | `QString` | -- | -| topic | `QString` | -- | -| password | `QString` | -- | -| UserModes | `QVariantMap` | -- | -| ChanModes | `QVariantMap` | -- | -| encrypted | `Bool` | -- | +### Runtime + +```typescript +interface IrcChannel { + +} +``` + +### Network + +```typescript +interface IrcChannel { + +} +``` + +## IrcListHelper + +### Runtime + +```typescript +interface IrcListHelper { + +} +``` + +### Network + +```typescript +interface IrcListHelper { + +} +``` ## IrcUser -| Field | Type | Description | -|-------------------|---------------|-------------| -| server | `QString` | -- | -| ircOperator | `QString` | -- | -| away | `Bool` | -- | -| lastAwayMessage | `Int` | -- | -| idleTime | `DateTime` | -- | -| whoisServiceReply | `QString` | -- | -| suserHost | `QString` | -- | -| nick | `QString` | -- | -| realName | `QString` | -- | -| awayMessage | `QString` | -- | -| loginTime | `DateTime` | -- | -| encrypted | `Bool` | -- | -| channels | `QStringList` | -- | -| host | `QString` | -- | -| userModes | `QString` | -- | -| user | `QString` | -- | +### Runtime -## NetworkConfig +```typescript +interface IrcUser { + +} +``` -| Field | Type | Description | -|--------------------|---------|-------------| -| standardCtcp | `Bool` | -- | -| autoWhoEnabled | `Bool` | -- | -| autoWhoDelay | `Int` | -- | -| autoWhoNickLimit | `Int` | -- | -| autoWhoInterval | `Int` | -- | -| pingTimeoutEnabled | `Bool` | -- | -| pingInterval | `Int` | -- | -| maxPingCount | `Int` | -- | - -## NetworkInfo - -| Field | Type | Description | -|---------------------------|-------------------------------|-------------| -| networkName | `QString` | -- | -| identityId | `Int` | -- | -| codecForServer | `QString` | -- | -| codecForEncoding | `QString` | -- | -| codecForDecoding | `QString` | -- | -| ServerList | `QVariantList<NetworkServer>` | -- | -| useRandomServer | `Bool` | -- | -| perform | `QStringList` | -- | -| useAutoIdentify | `Bool` | -- | -| autoIdentifyService | `QString` | -- | -| autoIdentifyPassword | `QString` | -- | -| useSasl | `Bool` | -- | -| saslAccount | `QString` | -- | -| saslPassword | `QString` | -- | -| useAutoReconnect | `Bool` | -- | -| autoReconnectInterval | `Int` | -- | -| autoReconnectRetries | `short` | -- | -| unlimitedReconnectRetries | `Bool` | -- | -| rejoinChannels | `Bool` | -- | +### Network + +```typescript +interface IrcUser { + +} +``` ## Network -| Field | Type | Description | -|---------------------|-----------------------|-----------------------| -| IrcUsersAndChannels | `IrcUsersAndChannels` | -- | -| Supports | `QVariantMap` | -- | -| connectionState | `Int` | -- | -| currentServer | `QString` | -- | -| isConnected | `Bool` | -- | -| latency | `Int` | -- | -| myNick | `QString` | -- | -| -- | `NetworkInfo` | More about this below | - -The NetworkInfo data here isn’t an actual field – it’s serialized into the same -map as the network itself. Therefore we have to apply the NetworkInfoSerializer -to the same map to which we applied the NetworkSerializer before. \ No newline at end of file +### Runtime + +```typescript +interface Network { + +} +``` + +### Network + +```typescript +interface Network { + +} +``` + +## NetworkConfig + +### Runtime + +```typescript +interface NetworkConfig { + +} +``` + +### Network + +```typescript +interface NetworkConfig { + +} +```