HandshakeResult
| Frame
|
{{{frame}}}, field {{{field}}}
|
| Member
|
{{{member}}}
|
| Direction
|
Server → client
|
| Session
|
All roles
|
| Roles
|
|
| Permission
|
None
|
| Answered by
|
|
| Answers
|
Handshake
|
| Defined in
|
|
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
