Editing SimTX API/Framing (section)

== Frames ==
After the preface, each direction is a sequence of frames:

<syntaxhighlight lang="text">
varint      length       number of bytes that follow
bytes       message      one ClientFrame (client to server) or ServerFrame (server to client)
</syntaxhighlight>

This is protobuf's standard ''length-delimited'' encoding of a message, as written by <code>writeDelimitedTo</code> and read by <code>parseDelimitedFrom</code>, or the equivalent helpers of other protobuf libraries. The varint is the usual base-128 encoding, least significant group first.

<code>ClientFrame</code> and <code>ServerFrame</code> each consist of one <code>oneof msg</code>. Exactly one member is set in every frame. The member number says what the frame is, and the member's value is the message:

<syntaxhighlight lang="protobuf">
message ClientFrame {
  oneof msg {
    ClientHello hello = 1;
    Ping ping = 2;
    ...
    ReceiverStart receiver_start = 10;
    ...
  }
}
</syntaxhighlight>

So a frame body always starts with the tag of its member (field number × 8 + 2), then the member's length, then the member's message. The complete lists are on [[SimTX API/Packet list]].

=== Member numbers ===
Member numbers are allocated in blocks, the same in both directions:

{| class="wikitable"
! Numbers !! Area
|-
| 1 to 9 || Connection: hello, ping, errors, banners
|-
| 10 to 29 || Receiver and transmitter sessions
|-
| 30 to 59 || Control sessions
|-
| 60 to 79 || Moderation sessions
|-
| 80 to 99 || Reserved for the next area
|}

Numbers 1 to 15 encode the tag in one byte. <code>ServerFrame</code> numbers 15, 16 and 62 are reserved; do not use them.