SimTX API v24/Packets/HandshakeResult: Difference between revisions
SimTX API documentation |
Archive the v24 protocol reference: use the v24 templates, links and categories |
||
| (One intermediate revision by the same user not shown) | |||
| 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]] | ||
Latest revision as of 16:15, 24 October 2026
| Packet ID | 30(0x1E)
|
|---|---|
| Direction | Server → client |
| Session | All roles |
| Body size | Variable, at least 24 bytes |
| Permission | None |
| 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[edit | edit source]
| 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[edit | edit source]
| 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[edit | edit source]
- After status
0on a receiver or transmitter connection, send the session request immediately. - After status
0on a control connection, expect ControlAck next. - Show
messageto the user on rejection. It is written for people. - Use the numeric capabilities in
permissions, such astx.pa_limit.400, to configure the user interface. - Reconnect with a fresh ticket shortly before
leaseExpiresAtEpochMillis. The lease is about 12 hours.