SimTX API v24/Packets/HandshakeResult - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:15:18Z

Archive the v24 protocol reference: use the v24 templates, links and categories

← Older revision		Revision as of 16:15, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	{{SimTX packet		{{SimTX packet v24
	\| name = HandshakeResult		\| name = HandshakeResult
	\| id = 30		\| id = 30
	\| hex = 0x1E		\| hex = 0x1E
	\| direction = s2c		\| direction = s2c
	\| session = [[SimTX API/Connection and handshake\|All roles]]		\| session = [[SimTX API v24/Connection and handshake\|All roles]]
	\| size = Variable, at least 24 bytes		\| size = Variable, at least 24 bytes
	\| permission = None		\| permission = None
	\| answers = [[SimTX API/Packets/Handshake\|Handshake]]		\| answers = [[SimTX API v24/Packets/Handshake\|Handshake]]
	\| group = handshake		\| group = handshake
	}}		}}
	'''HandshakeResult''' is the server's answer to a [[SimTX API/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.		'''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 ==		== Layout ==
Line 35:		Line 35:
	\| <code>permissionCount</code> \|\| <code>u8</code> \|\| Number of permissions that follow, at most 64.		\| <code>permissionCount</code> \|\| <code>u8</code> \|\| Number of permissions that follow, at most 64.
	\|-		\|-
	\| <code>permissions</code> \|\| <code>permissionCount × UTF</code> \|\| Effective [[SimTX API/Permissions\|permissions and capabilities]], sorted alphabetically.		\| <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>authorizationRevision</code> \|\| <code>i64</code> \|\| Revision of the account's authorisation data. Changes when permissions change. 0 for anonymous connections.
Line 67:		Line 67:
	== Usage ==		== Usage ==
	* After status <code>0</code> on a receiver or transmitter connection, send the session request immediately.		* 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/Packets/ControlAck\|ControlAck]] next.		* 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.		* 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.		* Use the numeric capabilities in <code>permissions</code>, such as <code>tx.pa_limit.400</code>, to configure the user interface.
Line 73:		Line 73:

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

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

Clanker: Clanker moved page SimTX API/Packets/HandshakeResult to SimTX API v24/Packets/HandshakeResult: Archive the v24 protocol reference

2026-10-24T16:15:16Z

Clanker moved page SimTX API/Packets/HandshakeResult to SimTX API v24/Packets/HandshakeResult: Archive the v24 protocol reference

← Older revision	Revision as of 16:15, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:57:50Z

SimTX API documentation

New page

{{SimTX API navigation}}
{{SimTX packet
| name = HandshakeResult
| id = 30
| hex = 0x1E
| direction = s2c
| session = [[SimTX API/Connection and handshake|All roles]]
| size = Variable, at least 24 bytes
| permission = None
| answers = [[SimTX API/Packets/Handshake|Handshake]]
| group = handshake
}}
'''HandshakeResult''' is the server's answer to a [[SimTX API/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/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/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/Connection and handshake#Handshake results|Handshake results]]
* [[SimTX API/Permissions]]

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