Files
@ r24060:e29844f8baad
Branch filter:
Location: cpp/openttd-patchpack/source/docs/admin_network.md - annotation
r24060:e29844f8baad
8.6 KiB
text/x-markdown
Update: Translations from eints
finnish: 8 changes by ln
italian: 25 changes by AlphaJack
finnish: 8 changes by ln
italian: 25 changes by AlphaJack
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 | r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b r23872:61253e664d3b | # OpenTTD's admin network
Last updated: 2011-01-20
## Table of contents
- 1.0) [Preface](#10-preface)
- 2.0) [Joining the network](#20-joining-the-network)
- 3.0) [Asking for updates](#30-asking-for-updates)
- 3.1) [Polling manually](#31-polling-manually)
- 4.0) [Sending rcon commands](#40-sending-rcon-commands)
- 5.0) [Sending chat](#50-sending-chat)
- 5.1) [Receiving chat](#51-receiving-chat)
- 6.0) [Disconnecting](#60-disconnecting)
- 7.0) [Certain packet information](#70-certain-packet-information)
## 1.0) Preface
The admin network provides a dedicated network protocol designed for other
applications to communicate with OpenTTD. Connected applications can execute
console commands remotely (rcon commands) with no further authentication.
Furthermore information about clients and companies can be provided.
Admin applications remain connected when starting a new game or loading a saved
game in contrast to normal OpenTTD clients that get disconnected.
This document describes the admin network and its protocol.
Please refer to the mentioned enums in `src/network/core/tcp_admin.h`
Please also note that further improvements to the admin protocol can mean that
more packet types will be sent by the server. For forward compatibility it is
therefore wise to ignore unknown packets. Future improvements might also add
additional data to packets. This data should be ignored. Data will never be
removed from packets in later versions, except the possibility that complete
packets are dropped in favour of a new packet.
This though will be reflected in the protocol version as announced in the
`ADMIN_PACKET_SERVER_PROTOCOL` in section 2.0).
A reference implementation in Java for a client connecting to the admin interface
can be found at: [http://dev.openttdcoop.org/projects/joan](http://dev.openttdcoop.org/projects/joan)
## 2.0) Joining the network
Create a TCP connection to the server on port 3977. The application is
expected to authenticate within 10 seconds.
To authenticate send a `ADMIN_PACKET_ADMIN_JOIN` packet.
The server will reply with `ADMIN_PACKET_SERVER_PROTOCOL` followed directly by
`ADMIN_PACKET_SERVER_WELCOME`.
`ADMIN_PACKET_SERVER_PROTOCOL` contains details about the protocol version.
It is the job of your application to check this number and decide whether
it will remain connected or not.
Furthermore, this packet holds details on every `AdminUpdateType` and the
supported `AdminFrequencyTypes` (bitwise representation).
`ADMIN_PACKET_SERVER_WELCOME` contains details on the server and the map,
e.g. if the server is dedicated, its NetworkLanguage, size of the Map, etc.
Once you have received `ADMIN_PACKET_SERVER_WELCOME` you are connected and
authorized to do your thing.
The server will not provide any game related updates unless you ask for them.
There are four packets the server will none the less send, if applicable:
- ADMIN_PACKET_SERVER_ERROR
- ADMIN_PACKET_SERVER_WELCOME
- ADMIN_PACKET_SERVER_NEWGAME
- ADMIN_PACKET_SERVER_SHUTDOWN
However, `ADMIN_PACKET_SERVER_WELCOME` only after a `ADMIN_PACKET_SERVER_NEWGAME`
## 3.0) Asking for updates
Asking for updates is done with `ADMIN_PACKET_ADMIN_UPDATE_FREQUENCY`.
With this packet you define which update you wish to receive at which
frequency.
Note: not every update type supports every frequency. If in doubt, you can
verify against the data received in `ADMIN_PACKET_SERVER_PROTOCOL`.
The server will not confirm your registered update. However, asking for an
invalid `AdminUpdateType` or a not supported `AdminUpdateFrequency` you will be
disconnected from the server with `NETWORK_ERROR_ILLEGAL_PACKET`.
Additional debug information can be found with a debug level of `net=3`.
`ADMIN_UPDATE_DATE` results in the server sending:
- ADMIN_PACKET_SERVER_DATE
`ADMIN_UPDATE_CLIENT_INFO` results in the server sending:
- ADMIN_PACKET_SERVER_CLIENT_JOIN
- ADMIN_PACKET_SERVER_CLIENT_INFO
- ADMIN_PACKET_SERVER_CLIENT_UPDATE
- ADMIN_PACKET_SERVER_CLIENT_QUIT
- ADMIN_PACKET_SERVER_CLIENT_ERROR
`ADMIN_UPDATE_COMPANY_INFO` results in the server sending:
- ADMIN_PACKET_SERVER_COMPANY_NEW
- ADMIN_PACKET_SERVER_COMPANY_INFO
- ADMIN_PACKET_SERVER_COMPANY_UPDATE
- ADMIN_PACKET_SERVER_COMPANY_REMOVE
`ADMIN_UPDATE_COMPANY_ECONOMY` results in the server sending:
- ADMIN_PACKET_SERVER_COMPANY_ECONOMY
`ADMIN_UPDATE_COMPANY_STATS` results in the server sending:
- ADMIN_PACKET_SERVER_COMPANY_STATS
`ADMIN_UPDATE_CHAT` results in the server sending:
- ADMIN_PACKET_SERVER_CHAT
`ADMIN_UPDATE_CONSOLE` results in the server sending:
- ADMIN_PACKET_SERVER_CONSOLE
`ADMIN_UPDATE_CMD_LOGGING` results in the server sending:
- ADMIN_PACKET_SERVER_CMD_LOGGING
## 3.1) Polling manually
Certain `AdminUpdateTypes` can also be polled:
- ADMIN_UPDATE_DATE
- ADMIN_UPDATE_CLIENT_INFO
- ADMIN_UPDATE_COMPANY_INFO
- ADMIN_UPDATE_COMPANY_ECONOMY
- ADMIN_UPDATE_COMPANY_STATS
- ADMIN_UPDATE_CMD_NAMES
`ADMIN_UPDATE_CLIENT_INFO` and `ADMIN_UPDATE_COMPANY_INFO` accept an additional
parameter. This parameter is used to specify a certain client or company.
Setting this parameter to `UINT32_MAX (0xFFFFFFFF)` will tell the server you
want to receive updates for all clients or companies.
Not supported `AdminUpdateType` in the poll will result in the server
disconnecting the application with `NETWORK_ERROR_ILLEGAL_PACKET`.
Additional debug information can be found with a debug level of `net=3`.
## 4.0) Sending rcon commands
Rcon runs separate from the `ADMIN_UPDATE_CONSOLE` `AdminUpdateType`. Requesting
the execution of a remote console command is done with the packet
`ADMIN_PACKET_ADMIN_RCON`.
Note: No additional authentication is required for rcon commands.
The server will reply with one or more `ADMIN_PACKET_SERVER_RCON` packets.
Finally an `ADMIN_PACKET_ADMIN_RCON_END` packet will be sent. Applications
will not receive the answer twice if they have asked for the `AdminUpdateType`
`ADMIN_UPDATE_CONSOLE`, as the result is not printed on the servers console
(just like clients rcon commands).
Furthermore, sending a `say` command (or any similar command) will not
be sent back into the admin network.
Chat from the server itself will only be sent to the admin network when it
was not sent from the admin network.
Note that when content is queried or updated via rcon, the processing
happens asynchronously. But the `ADMIN_PACKET_ADMIN_RCON_END` packet is sent
already right after the content is requested as there's no immediate output.
Thus other packages and the output of content rcon command may be sent at
an arbitrary later time, mixing into the output of other console activity,
e.g. also of possible subsequent other rcon commands sent.
## 5.0) Sending chat
Sending a `ADMIN_PACKET_ADMIN_CHAT` results in chat originating from the server.
Currently four types of chat are supported:
- NETWORK_ACTION_CHAT
- NETWORK_ACTION_CHAT_CLIENT
- NETWORK_ACTION_CHAT_COMPANY
- NETWORK_ACTION_SERVER_MESSAGE
`NETWORK_ACTION_SERVER_MESSAGE` can be sent to a single client or company
using the respective `DestType` and ID.
This is a message prefixed with the 3 stars, e.g. `*** foo has joined the game`
## 5.1) Receiving chat
Register `ADMIN_UPDATE_CHAT` at `ADMIN_FREQUENCY_AUTOMATIC` to receive chat.
The application will be able to receive all chat the server can see.
The configuration option `network.server_admin_chat` specifies whether
private chat for to the server is distributed into the admin network.
## 6.0) Disconnecting
It is a kind thing to say good bye before leaving. Do this by sending the
`ADMIN_PACKET_ADMIN_QUIT` packet.
## 7.0) Certain packet information
All `ADMIN_PACKET_SERVER_*` packets have an enum value greater 100.
`ADMIN_PACKET_SERVER_WELCOME`
Either directly follows `ADMIN_PACKET_SERVER_PROTOCOL` or is sent
after a new game has been started or a map loaded, i.e. also
after ADMIN_PACKET_SERVER_NEWGAME.
`ADMIN_PACKET_SERVER_CLIENT_JOIN` and `ADMIN_PACKET_SERVER_COMPANY_NEW`
These packets directly follow their respective INFO packets. If you receive
a CLIENT_JOIN / COMPANY_NEW packet without having received the INFO packet
it may be a good idea to POLL for the specific ID.
`ADMIN_PACKET_SERVER_CMD_NAMES` and `ADMIN_PACKET_SERVER_CMD_LOGGING`
Data provided with these packets is not stable and will not be
treated as such. Do not rely on IDs or names to be constant
across different versions / revisions of OpenTTD.
Data provided in this packet is for logging purposes only.
|