Editing SimTX API v24/Packets/HandshakeResult

{{SimTX API v24 navigation}}
{{SimTX packet v24
| name = HandshakeResult
| id = 30
| hex = 0x1E
| direction = s2c
| session = [[SimTX API v24/Connection and handshake|All roles]]
| size = Variable, at least 24 bytes
| permission = None
| answers = [[SimTX API v24/Packets/Handshake|Handshake]]
| group = handshake
}}
'''HandshakeResult''' is the server's answer to a [[SimTX API v24/Packets/Handshake|Handshake]]. It either accepts the connection, in which case the session continues according to the role, or rejects it, in which case the server closes the connection after sending it. For authenticated connections it also describes the account.

== Layout ==
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>packetId</code> || <code>u8</code> || Always <code>30</code>.
|-
| <code>status</code> || <code>u8</code> || Result code. See [[#Status codes|Status codes]].
|-
| <code>message</code> || <code>UTF</code> || Human-readable explanation. Empty on success.
|-
| <code>hasAccount</code> || <code>bool</code> || True when the connection is authenticated.
|-
| <code>accountUuidMsb</code> || <code>i64</code> || Present only if <code>hasAccount</code>. Most significant 64 bits of the account UUID.
|-
| <code>accountUuidLsb</code> || <code>i64</code> || Present only if <code>hasAccount</code>. Least significant 64 bits of the account UUID.
|-
| <code>handle</code> || <code>UTF</code> || Account handle, or empty.
|-
| <code>displayName</code> || <code>UTF</code> || Account display name, or empty.
|-
| <code>permissionCount</code> || <code>u8</code> || Number of permissions that follow, at most 64.
|-
| <code>permissions</code> || <code>permissionCount × UTF</code> || Effective [[SimTX API v24/Permissions|permissions and capabilities]], sorted alphabetically.
|-
| <code>authorizationRevision</code> || <code>i64</code> || Revision of the account's authorisation data. Changes when permissions change. 0 for anonymous connections.
|-
| <code>leaseExpiresAtEpochMillis</code> || <code>i64</code> || Unix time in milliseconds at which the server will close an authenticated connection. 0 for anonymous connections.
|}

== Status codes ==
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>ACCEPTED</code> || The session may begin.
|-
| 1 || <code>VERSION_UNSUPPORTED</code> || The protocol version does not match. Typical message: ''This server requires protocol v24''.
|-
| 2 || <code>AUTHENTICATION_REQUIRED</code> || The role requires a ticket. Typical message: ''This role requires a SimTX account''.
|-
| 3 || <code>CREDENTIAL_INVALID</code> || The ticket is invalid, expired, already used, or bound to another server or role. Typical message: ''Game ticket is invalid or expired''.
|-
| 4 || <code>ACCOUNT_RESTRICTED</code> || The account is restricted.
|-
| 5 || <code>ROLE_FORBIDDEN</code> || The account lacks the permission for the role. Typical message: ''Account is not permitted to transmit''.
|-
| 6 || <code>SERVER_UNAVAILABLE</code> || The server cannot verify the ticket or accept the connection right now. Retry later.
|-
| 7 || <code>IP_BANNED</code> || The client address is banned. The message contains the reason.
|}

An unknown status value is a protocol error. A client should treat it like a rejection.

== Usage ==
* After status <code>0</code> on a receiver or transmitter connection, send the session request immediately.
* After status <code>0</code> on a control connection, expect [[SimTX API v24/Packets/ControlAck|ControlAck]] next.
* Show <code>message</code> to the user on rejection. It is written for people.
* Use the numeric capabilities in <code>permissions</code>, such as <code>tx.pa_limit.400</code>, to configure the user interface.
* Reconnect with a fresh ticket shortly before <code>leaseExpiresAtEpochMillis</code>. The lease is about 12 hours.

== See also ==
* [[SimTX API v24/Connection and handshake#Handshake results|Handshake results]]
* [[SimTX API v24/Permissions]]

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