(svn r21005) -Document: the admin network protocol on a high(er) level (dihedral)
This commit is contained in:
rubidium
205
docs/admin_network.txt
Normal file
205
docs/admin_network.txt
Normal file
@@ -0,0 +1,205 @@
|
||||
Admin Network
|
||||
|
||||
Preface
|
||||
1. Joining the network
|
||||
2. Asking for updates
|
||||
3. Polling manually
|
||||
4. Sending rcon commands
|
||||
5. Sending chat
|
||||
6. Receiving chat
|
||||
7. Disconnecting
|
||||
8. Certain packet information
|
||||
|
||||
|
||||
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 1.
|
||||
|
||||
|
||||
1. 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 serve 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
|
||||
|
||||
|
||||
2. 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
|
||||
|
||||
|
||||
3. 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_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. 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 a ADMIN_PACIKET_SERVER_RCON packet. Applications
|
||||
will not receive the answer twice if they ave 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.
|
||||
|
||||
|
||||
5. 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
|
||||
|
||||
|
||||
6. 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.
|
||||
|
||||
|
||||
7. Disconnecting
|
||||
----------------
|
||||
|
||||
It is a kind thing to say good bye before leaving. Do this sending the
|
||||
ADMIN_PACKET_ADMIN_QUIT packet.
|
||||
|
||||
|
||||
8. 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 send
|
||||
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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user