Editing SimTX API/Packets/ClientHello

{{SimTX API navigation}}
{{SimTX packet
| name = ClientHello
| frame = ClientFrame
| field = 1
| member = hello
| direction = c2s
| session = [[SimTX API/Connection and handshake|All roles]]
| roles = All roles. Always the first frame.
| permission = Depends on the role
| reply = [[SimTX API/Packets/ServerHello|ServerHello]]
| group = connection
| file = frames.proto
}}
'''ClientHello''' opens every game connection. It names the role of the session, carries the game ticket of an authenticated connection, identifies the client software, and states which optional features and protocol revision the client implements. It is the first frame the client sends, immediately after the 8-byte [[SimTX API/Framing#Preface|preface]].

== Definition ==
<syntaxhighlight lang="protobuf">
message ClientHello {
  Role role = 1;
  AuthKind auth = 2;
  string credential = 3;        // stx_gt1_… game ticket; empty when anonymous
  string client_name = 4;       // e.g. "SimTX Transmitter"
  string client_version = 5;
  repeated string features = 6;  // client feature registry (see the top of this file)
  int32 protocol_revision = 7;    // highest protocol revision this client implements
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>role</code> || [[SimTX API/Data types#Role|Role]] || Session role. Required; <code>ROLE_UNSPECIFIED</code> or an unknown value is refused.
|-
| 2 || <code>auth</code> || [[SimTX API/Data types#AuthKind|AuthKind]] || <code>AUTH_KIND_ANONYMOUS</code> (0) or <code>AUTH_KIND_GAME_TICKET</code> (1).
|-
| 3 || <code>credential</code> || <code>string</code> || The <code>stx_gt1_</code> [[SimTX API/Game tickets|game ticket]] when <code>auth</code> is <code>GAME_TICKET</code>. Must be empty when anonymous: an anonymous hello with a credential is refused. At most 512 characters. Never an access or personal credential.
|-
| 4 || <code>client_name</code> || <code>string</code> || Name of the client software, for example <code>Example SDR Client</code>. Shown to operators.
|-
| 5 || <code>client_version</code> || <code>string</code> || Version of the client software.
|-
| 6 || <code>features</code> || <code>repeated string</code> || Optional behaviours the client understands, from the [[SimTX API/Compatibility and versioning#Feature registry|feature registry]]. Servers ignore names they do not know.
|-
| 7 || <code>protocol_revision</code> || <code>int32</code> || Highest [[SimTX API/Compatibility and versioning#Protocol revisions|protocol revision]] the client implements. Send 1. 0 (unset): the server leaves out the behaviours that need revision 1.
|}

== Rules ==
* Send it within 5 seconds of connecting, together with the preface.
* The hello frame may be at most 64 KiB. Before the hello the server skips at most 16 unknown or empty frames, and gives up 20 seconds after connecting.
* The role cannot change later on the same connection.
* <code>credential</code> carries the ticket when <code>auth</code> is <code>AUTH_KIND_GAME_TICKET</code>. An anonymous hello must leave it empty; one that carries a credential is refused. A ticket is valid for one connection, 60 seconds, one server and one role. See [[SimTX API/Game tickets|Game tickets]].
* Send <code>features: "stations.v1"</code> if the client handles station-bound sessions and [[SimTX API/Data types#BoundStation|BoundStation]], and <code>protocol_revision: 1</code> if it handles <code>SessionStatus UPDATED</code> with <code>update_reason</code> and station snapshots. See [[SimTX API/Compatibility and versioning|Compatibility and versioning]].

== Roles ==
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>ROLE_UNSPECIFIED</code> || Refused.
|-
| 1 || <code>ROLE_RECEIVER</code> || [[SimTX API/Receiver session|Receiver]]: an IQ stream. Anonymous for ad-hoc sites; a <code>receiver</code> ticket for station-bound ones.
|-
| 2 || <code>ROLE_TX_AUDIO</code> || [[SimTX API/Transmitter session|Transmitter]] whose samples the client streams. Ticket <code>tx-audio</code>, permission <code>game.transmit</code>.
|-
| 3 || <code>ROLE_TX_GENERATED</code> || Transmitter whose source the server generates. Ticket <code>tx-generated</code>, permission <code>game.transmit</code>.
|-
| 4 || <code>ROLE_CONTROL</code> || [[SimTX API/Control session|Control]]: station list, maps, health, catalog, ephemeris, passes, own-transmitter monitor. Anonymous, or ticket <code>control</code>.
|-
| 5 || <code>ROLE_MODERATION</code> || [[SimTX API/Moderation session|Moderation]]. Ticket <code>moderation</code>, permission <code>moderation.manage</code>.
|}

== Examples ==
Complete frames, including the varint length prefix.

'''<code>hello_anonymous_receiver</code>''' (client to server, 37 bytes):

<syntaxhighlight lang="text">
24                                           frame length 36
0A 22                                        hello (ClientHello), 34 bytes
  08 01                                      role = 1 (ROLE_RECEIVER)
  22 0C 53 69 6D 54 58 20 47 6F 6C 64 65 6E  client_name = "SimTX Golden"
  2A 06 32 35 2E 30 2E 30                    client_version = "25.0.0"
  32 08 70 6F 69 6E 74 69 6E 67              features = "pointing"
</syntaxhighlight>

'''<code>hello_ticket_tx_audio</code>''' (client to server, 50 bytes):

<syntaxhighlight lang="text">
31                                 frame length 49
0A 2F                              hello (ClientHello), 47 bytes
  08 02                            role = 2 (ROLE_TX_AUDIO)
  10 01                            auth = 1 (AUTH_KIND_GAME_TICKET)
  1A 0E 73 74 78 5F 67 74 31 5F …  credential = "stx_gt1_golden"
  22 11 53 69 6D 54 58 20 54 72 …  client_name = "SimTX Transmitter"
  2A 06 32 35 2E 30 2E 30          client_version = "25.0.0"
</syntaxhighlight>

'''<code>hello_revision_1_control</code>''' (client to server, 29 bytes):

<syntaxhighlight lang="text">
1C                                           frame length 28
0A 1A                                        hello (ClientHello), 26 bytes
  08 04                                      role = 4 (ROLE_CONTROL)
  22 0C 53 69 6D 54 58 20 47 6F 6C 64 65 6E  client_name = "SimTX Golden"
  2A 06 32 35 2E 31 2E 30                    client_version = "25.1.0"
  38 01                                      protocol_revision = 1
</syntaxhighlight>

== See also ==
* [[SimTX API/Connection and handshake]]
* [[SimTX API/Game tickets]]
* [[SimTX API/Compatibility and versioning]]

{{SimTX API navbox}}
[[Category:SimTX API]]