So, for a revised specification I'll go with msgpack for now, since I don't want to port the rest of c-toxcore to CBOR and the availability of libraries is better.
| Length | Value | Description |
|---|---|---|
| 1 | 0x19 | PACKET_ID_ONLINE |
| Name | Length | Value | Description |
|---|---|---|---|
| ID | 1 | 0x19 | PACKET_ID_ONLINE |
| Flags | 2 | 0x0000 - 0xFFFF | Extension flags, see below |
| Size | 2 | 0x0000 - 0xFFFF | Size of the msgpack encoded rest in bytes |
| Capabilities | [0,] | msgpack encoded capabilities, structure to be specified |
| Flag Mask | Description |
|---|---|
| (1 << 0) | Reserved for eventually using CBOR (then this will be 1), must be 0 |
| (1 << 1) | Followup packet, if this flag is set this packet doesn't contain the Size field and data starts after the flags |
| (1 << 1) - (1 << 15) | Reserved for future use, must be sent as 0 |
The top level of the Capabilities structure is a fixarray with the following elements:
| Index | Name | msgpack type | Description |
|---|---|---|---|
| 0 | version | positive fixint | Version number of this protocol, increases with feature level |
| 1 | standard | array16 | fields that every client implementing a version must send |
| 2 | optional | map16 serialized to bstr |
field that are defined by the toktok spec, but optional |
| 3 | custom | map16 serialized to bstr |
for custom application specific extensions |
This field is only written by a toxcore implementation
This field is only written by a toxcore implementation
For version 0 of the protocol, standard should be empty.
For version 1 of the protocol, standard contains the following fields (not final yet):
| Index | Name | msgpack type | Description |
|---|---|---|---|
| 0 | basic-feature-flags | uint32 | See description below |
| Flag Mask | Name | Description |
|---|---|---|
| (1 << 0) | send-audio | 1 if the client can send audio, 0 else |
| (1 << 1) | recv-audio | 1 if the client can play audio, 0 else |
| (1 << 2) | send-video | 1 if the client can send video, 0 else |
| (1 << 3) | recv-video | 1 if the client can display video, 0 else |
| (1 << 4) | send-file | 1 if the client can send files, 0 else |
| (1 << 5) | recv-file | 1 if the client can accept file transfers, 0 else |
| (1 << 6) | group | 1 if the client supports group chats, 0 else |
| (1 << 7) | bot | 1 if the client wants to indicate it's a bot, 0 else |
| (1 << 8) | bot-info | 1 if the client can provide an answer to the !info command, 0 else (Note: most useful for bots) |
| (1 << 9) | bot-help | 1 if the client can provide an answer to the !help command, 0 else (Note: most useful for bots) |
| Rest | Must be sent as 0, for future use |
The key type for this field is fixstr and keys are to be encoded in UTF-8, with the preferred character set ofa-zA-Z0-9 as well as _ and-. There's no terminating NUL byte at the end of the string!.
The following keys and meanings are specified:
|key|msgpack type|Description|
|name|str| Name of the client|
|version|str| Version string of the client version, releases should use semver if applicable, for dev builds a git version hash or similar is preferred|
Each client/toxcore implementation should create their own namespace using a fixstr key with the name or shorthand name of the client, e.g. qTox, uTox, Antox, Trifa,...
The fields version and standard are only written by the toxcore implementation. version needs no API, because it's hardcoded and not changeable after a release of the implementation. All features supported by the implementation should have an API to enable/disable them in the application.
The implementation should provide a way to accept byte strings for the optional and custom fields. The implementation should provide a way to retrieve received byte strings for the optional and custom fields.
NOTE: Since this got way bigger than I initially though, maybe we should go the route of messageV2 and send this structure as a filetransfer, preferably by submitting a hash of it via the ONLINE packet, to allow caching on the client side.