SimTX API v24/Packets/HandshakeResult

HandshakeResult

Packet ID	30(0x1E)
Direction	Server → client
Session	All roles
Body size	Variable, at least 24 bytes
Permission	None
Answered by
Answers	Handshake

HandshakeResult is the server's answer to a 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

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

Status codes

Value	Name	Meaning
0	ACCEPTED	The session may begin.
1	VERSION_UNSUPPORTED	The protocol version does not match. Typical message: This server requires protocol v24.
2	AUTHENTICATION_REQUIRED	The role requires a ticket. Typical message: This role requires a SimTX account.
3	CREDENTIAL_INVALID	The ticket is invalid, expired, already used, or bound to another server or role. Typical message: Game ticket is invalid or expired.
4	ACCOUNT_RESTRICTED	The account is restricted.
5	ROLE_FORBIDDEN	The account lacks the permission for the role. Typical message: Account is not permitted to transmit.
6	SERVER_UNAVAILABLE	The server cannot verify the ticket or accept the connection right now. Retry later.
7	IP_BANNED	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 0 on a receiver or transmitter connection, send the session request immediately.
• After status 0 on a control connection, expect ControlAck next.
• Show message to the user on rejection. It is written for people.
• Use the numeric capabilities in permissions, such as tx.pa_limit.400, to configure the user interface.
• Reconnect with a fresh ticket shortly before leaseExpiresAtEpochMillis. The lease is about 12 hours.

See also

• Handshake results
• SimTX API v24/Permissions