src/network/core/tcp_admin.h

   1 /*
   2  * This file is part of OpenTTD.
   3  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   4  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   5  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   6  */
   7
   8 /**
   9  * @file tcp_admin.h Basic functions to receive and send TCP packets to and from the admin network.
  10  */
  11
  12 #ifndef NETWORK_CORE_TCP_ADMIN_H
  13 #define NETWORK_CORE_TCP_ADMIN_H
  14
  15 #include "os_abstraction.h"
  16 #include "tcp.h"
  17 #include "../network_type.h"
  18 #include "../../core/pool_type.hpp"
  19
  20 /**
  21  * Enum with types of TCP packets specific to the admin network.
  22  * This protocol may only be extended to ensure stability.
  23  */
  24 enum PacketAdminType {
  25         ADMIN_PACKET_ADMIN_JOIN,             ///< The admin announces and authenticates itself to the server.
  26         ADMIN_PACKET_ADMIN_QUIT,             ///< The admin tells the server that it is quitting.
  27         ADMIN_PACKET_ADMIN_UPDATE_FREQUENCY, ///< The admin tells the server the update frequency of a particular piece of information.
  28         ADMIN_PACKET_ADMIN_POLL,             ///< The admin explicitly polls for a piece of information.
  29         ADMIN_PACKET_ADMIN_CHAT,             ///< The admin sends a chat message to be distributed.
  30         ADMIN_PACKET_ADMIN_RCON,             ///< The admin sends a remote console command.
  31         ADMIN_PACKET_ADMIN_GAMESCRIPT,       ///< The admin sends a JSON string for the GameScript.
  32         ADMIN_PACKET_ADMIN_PING,             ///< The admin sends a ping to the server, expecting a ping-reply (PONG) packet.
  33
  34         ADMIN_PACKET_SERVER_FULL = 100,      ///< The server tells the admin it cannot accept the admin.
  35         ADMIN_PACKET_SERVER_BANNED,          ///< The server tells the admin it is banned.
  36         ADMIN_PACKET_SERVER_ERROR,           ///< The server tells the admin an error has occurred.
  37         ADMIN_PACKET_SERVER_PROTOCOL,        ///< The server tells the admin its protocol version.
  38         ADMIN_PACKET_SERVER_WELCOME,         ///< The server welcomes the admin to a game.
  39         ADMIN_PACKET_SERVER_NEWGAME,         ///< The server tells the admin its going to start a new game.
  40         ADMIN_PACKET_SERVER_SHUTDOWN,        ///< The server tells the admin its shutting down.
  41
  42         ADMIN_PACKET_SERVER_DATE,            ///< The server tells the admin what the current game date is.
  43         ADMIN_PACKET_SERVER_CLIENT_JOIN,     ///< The server tells the admin that a client has joined.
  44         ADMIN_PACKET_SERVER_CLIENT_INFO,     ///< The server gives the admin information about a client.
  45         ADMIN_PACKET_SERVER_CLIENT_UPDATE,   ///< The server gives the admin an information update on a client.
  46         ADMIN_PACKET_SERVER_CLIENT_QUIT,     ///< The server tells the admin that a client quit.
  47         ADMIN_PACKET_SERVER_CLIENT_ERROR,    ///< The server tells the admin that a client caused an error.
  48         ADMIN_PACKET_SERVER_COMPANY_NEW,     ///< The server tells the admin that a new company has started.
  49         ADMIN_PACKET_SERVER_COMPANY_INFO,    ///< The server gives the admin information about a company.
  50         ADMIN_PACKET_SERVER_COMPANY_UPDATE,  ///< The server gives the admin an information update on a company.
  51         ADMIN_PACKET_SERVER_COMPANY_REMOVE,  ///< The server tells the admin that a company was removed.
  52         ADMIN_PACKET_SERVER_COMPANY_ECONOMY, ///< The server gives the admin some economy related company information.
  53         ADMIN_PACKET_SERVER_COMPANY_STATS,   ///< The server gives the admin some statistics about a company.
  54         ADMIN_PACKET_SERVER_CHAT,            ///< The server received a chat message and relays it.
  55         ADMIN_PACKET_SERVER_RCON,            ///< The server's reply to a remove console command.
  56         ADMIN_PACKET_SERVER_CONSOLE,         ///< The server gives the admin the data that got printed to its console.
  57         ADMIN_PACKET_SERVER_CMD_NAMES,       ///< The server sends out the names of the DoCommands to the admins.
  58         ADMIN_PACKET_SERVER_CMD_LOGGING,     ///< The server gives the admin copies of incoming command packets.
  59         ADMIN_PACKET_SERVER_GAMESCRIPT,      ///< The server gives the admin information from the GameScript in JSON.
  60         ADMIN_PACKET_SERVER_RCON_END,        ///< The server indicates that the remote console command has completed.
  61         ADMIN_PACKET_SERVER_PONG,            ///< The server replies to a ping request from the admin.
  62
  63         INVALID_ADMIN_PACKET = 0xFF,         ///< An invalid marker for admin packets.
  64 };
  65
  66 /** Status of an admin. */
  67 enum AdminStatus {
  68         ADMIN_STATUS_INACTIVE,      ///< The admin is not connected nor active.
  69         ADMIN_STATUS_ACTIVE,        ///< The admin is active.
  70         ADMIN_STATUS_END,           ///< Must ALWAYS be on the end of this list!! (period)
  71 };
  72
  73 /** Update types an admin can register a frequency for */
  74 enum AdminUpdateType {
  75         ADMIN_UPDATE_DATE,            ///< Updates about the date of the game.
  76         ADMIN_UPDATE_CLIENT_INFO,     ///< Updates about the information of clients.
  77         ADMIN_UPDATE_COMPANY_INFO,    ///< Updates about the generic information of companies.
  78         ADMIN_UPDATE_COMPANY_ECONOMY, ///< Updates about the economy of companies.
  79         ADMIN_UPDATE_COMPANY_STATS,   ///< Updates about the statistics of companies.
  80         ADMIN_UPDATE_CHAT,            ///< The admin would like to have chat messages.
  81         ADMIN_UPDATE_CONSOLE,         ///< The admin would like to have console messages.
  82         ADMIN_UPDATE_CMD_NAMES,       ///< The admin would like a list of all DoCommand names.
  83         ADMIN_UPDATE_CMD_LOGGING,     ///< The admin would like to have DoCommand information.
  84         ADMIN_UPDATE_GAMESCRIPT,      ///< The admin would like to have gamescript messages.
  85         ADMIN_UPDATE_END,             ///< Must ALWAYS be on the end of this list!! (period)
  86 };
  87
  88 /** Update frequencies an admin can register. */
  89 enum AdminUpdateFrequency {
  90         ADMIN_FREQUENCY_POLL      = 0x01, ///< The admin can poll this.
  91         ADMIN_FREQUENCY_DAILY     = 0x02, ///< The admin gets information about this on a daily basis.
  92         ADMIN_FREQUENCY_WEEKLY    = 0x04, ///< The admin gets information about this on a weekly basis.
  93         ADMIN_FREQUENCY_MONTHLY   = 0x08, ///< The admin gets information about this on a monthly basis.
  94         ADMIN_FREQUENCY_QUARTERLY = 0x10, ///< The admin gets information about this on a quarterly basis.
  95         ADMIN_FREQUENCY_ANUALLY   = 0x20, ///< The admin gets information about this on a yearly basis.
  96         ADMIN_FREQUENCY_AUTOMATIC = 0x40, ///< The admin gets information about this when it changes.
  97 };
  98 DECLARE_ENUM_AS_BIT_SET(AdminUpdateFrequency)
  99
 100 /** Reasons for removing a company - communicated to admins. */
 101 enum AdminCompanyRemoveReason {
 102         ADMIN_CRR_MANUAL,    ///< The company is manually removed.
 103         ADMIN_CRR_AUTOCLEAN, ///< The company is removed due to autoclean.
 104         ADMIN_CRR_BANKRUPT,  ///< The company went belly-up.
 105
 106         ADMIN_CRR_END,       ///< Sentinel for end.
 107 };
 108
 109 /** Main socket handler for admin related connections. */
 110 class NetworkAdminSocketHandler : public NetworkTCPSocketHandler {
 111 protected:
 112         char admin_name[NETWORK_CLIENT_NAME_LENGTH];           ///< Name of the admin.
 113         char admin_version[NETWORK_REVISION_LENGTH];           ///< Version string of the admin.
 114         AdminStatus status;                                    ///< Status of this admin.
 115
 116         NetworkRecvStatus ReceiveInvalidPacket(PacketAdminType type);
 117
 118         /**
 119          * Join the admin network:
 120          * string  Password the server is expecting for this network.
 121          * string  Name of the application being used to connect.
 122          * string  Version string of the application being used to connect.
 123          * @param p The packet that was just received.
 124          * @return The state the network should have.
 125          */
 126         virtual NetworkRecvStatus Receive_ADMIN_JOIN(Packet *p);
 127
 128         /**
 129          * Notification to the server that this admin is quitting.
 130          * @param p The packet that was just received.
 131          * @return The state the network should have.
 132          */
 133         virtual NetworkRecvStatus Receive_ADMIN_QUIT(Packet *p);
 134
 135         /**
 136          * Register updates to be sent at certain frequencies (as announced in the PROTOCOL packet):
 137          * uint16  Update type (see #AdminUpdateType). Note integer type - see "Certain Packet Information" in docs/admin_network.md.
 138          * uint16  Update frequency (see #AdminUpdateFrequency), setting #ADMIN_FREQUENCY_POLL is always ignored.
 139          * @param p The packet that was just received.
 140          * @return The state the network should have.
 141          */
 142         virtual NetworkRecvStatus Receive_ADMIN_UPDATE_FREQUENCY(Packet *p);
 143
 144         /**
 145          * Poll the server for certain updates, an invalid poll (e.g. not existent id) gets silently dropped:
 146          * uint8   #AdminUpdateType the server should answer for, only if #AdminUpdateFrequency #ADMIN_FREQUENCY_POLL is advertised in the PROTOCOL packet. Note integer type - see "Certain Packet Information" in docs/admin_network.md.
 147          * uint32  ID relevant to the packet type, e.g.
 148          *          - the client ID for #ADMIN_UPDATE_CLIENT_INFO. Use UINT32_MAX to show all clients.
 149          *          - the company ID for #ADMIN_UPDATE_COMPANY_INFO. Use UINT32_MAX to show all companies.
 150          * @param p The packet that was just received.
 151          * @return The state the network should have.
 152          */
 153         virtual NetworkRecvStatus Receive_ADMIN_POLL(Packet *p);
 154
 155         /**
 156          * Send chat as the server:
 157          * uint8   Action such as NETWORK_ACTION_CHAT_CLIENT (see #NetworkAction).
 158          * uint8   Destination type such as DESTTYPE_BROADCAST (see #DestType).
 159          * uint32  ID of the destination such as company or client id.
 160          * string  Message.
 161          * @param p The packet that was just received.
 162          * @return The state the network should have.
 163          */
 164         virtual NetworkRecvStatus Receive_ADMIN_CHAT(Packet *p);
 165
 166         /**
 167          * Execute a command on the servers console:
 168          * string  Command to be executed.
 169          * @param p The packet that was just received.
 170          * @return The state the network should have.
 171          */
 172         virtual NetworkRecvStatus Receive_ADMIN_RCON(Packet *p);
 173
 174         /**
 175          * Send a JSON string to the current active GameScript.
 176          * json  JSON string for the GameScript.
 177          * @param p The packet that was just received.
 178          * @return The state the network should have.
 179          */
 180         virtual NetworkRecvStatus Receive_ADMIN_GAMESCRIPT(Packet *p);
 181
 182         /**
 183          * Ping the server, requiring the server to reply with a pong packet.
 184          * uint32 Integer value to pass to the server, which is quoted in the reply.
 185          * @param p The packet that was just received.
 186          * @return The state the network should have.
 187          */
 188         virtual NetworkRecvStatus Receive_ADMIN_PING(Packet *p);
 189
 190         /**
 191          * The server is full (connection gets closed).
 192          * @param p The packet that was just received.
 193          * @return The state the network should have.
 194          */
 195         virtual NetworkRecvStatus Receive_SERVER_FULL(Packet *p);
 196
 197         /**
 198          * The source IP address is banned (connection gets closed).
 199          * @param p The packet that was just received.
 200          * @return The state the network should have.
 201          */
 202         virtual NetworkRecvStatus Receive_SERVER_BANNED(Packet *p);
 203
 204         /**
 205          * An error was caused by this admin connection (connection gets closed).
 206          * uint8  NetworkErrorCode the error caused.
 207          * @param p The packet that was just received.
 208          * @return The state the network should have.
 209          */
 210         virtual NetworkRecvStatus Receive_SERVER_ERROR(Packet *p);
 211
 212         /**
 213          * Inform a just joined admin about the protocol specifics:
 214          * uint8   Protocol version.
 215          * bool    Further protocol data follows (repeats through all update packet types).
 216          * uint16  Update packet type.
 217          * uint16  Frequencies allowed for this update packet (bitwise).
 218          * @param p The packet that was just received.
 219          * @return The state the network should have.
 220          */
 221         virtual NetworkRecvStatus Receive_SERVER_PROTOCOL(Packet *p);
 222
 223         /**
 224          * Welcome a connected admin to the game:
 225          * string  Name of the Server (e.g. as advertised to master server).
 226          * string  OpenTTD version string.
 227          * bool    Server is dedicated.
 228          * string  Name of the Map.
 229          * uint32  Random seed of the Map.
 230          * uint8   Landscape of the Map.
 231          * uint32  Start date of the Map.
 232          * uint16  Map width.
 233          * uint16  Map height.
 234          * @param p The packet that was just received.
 235          * @return The state the network should have.
 236          */
 237         virtual NetworkRecvStatus Receive_SERVER_WELCOME(Packet *p);
 238
 239         /**
 240          * Notification about a newgame.
 241          * @param p The packet that was just received.
 242          * @return The state the network should have.
 243          */
 244         virtual NetworkRecvStatus Receive_SERVER_NEWGAME(Packet *p);
 245
 246         /**
 247          * Notification about the server shutting down.
 248          * @param p The packet that was just received.
 249          * @return The state the network should have.
 250          */
 251         virtual NetworkRecvStatus Receive_SERVER_SHUTDOWN(Packet *p);
 252
 253         /**
 254          * Send the current date of the game:
 255          * uint32  Current game date.
 256          * @param p The packet that was just received.
 257          * @return The state the network should have.
 258          */
 259         virtual NetworkRecvStatus Receive_SERVER_DATE(Packet *p);
 260
 261         /**
 262          * Notification of a new client:
 263          * uint32  ID of the new client.
 264          * @param p The packet that was just received.
 265          * @return The state the network should have.
 266          */
 267         virtual NetworkRecvStatus Receive_SERVER_CLIENT_JOIN(Packet *p);
 268
 269         /**
 270          * Client information of a specific client:
 271          * uint32  ID of the client.
 272          * string  Network address of the client.
 273          * string  Name of the client.
 274          * uint8   Language of the client.
 275          * uint32  Date the client joined the game.
 276          * uint8   ID of the company the client is playing as (255 for spectators).
 277          * @param p The packet that was just received.
 278          * @return The state the network should have.
 279          */
 280         virtual NetworkRecvStatus Receive_SERVER_CLIENT_INFO(Packet *p);
 281
 282         /**
 283          * Client update details on a specific client (e.g. after rename or move):
 284          * uint32  ID of the client.
 285          * string  Name of the client.
 286          * uint8   ID of the company the client is playing as (255 for spectators).
 287          * @param p The packet that was just received.
 288          * @return The state the network should have.
 289          */
 290         virtual NetworkRecvStatus Receive_SERVER_CLIENT_UPDATE(Packet *p);
 291
 292         /**
 293          * Notification about a client leaving the game.
 294          * uint32  ID of the client that just left.
 295          * @param p The packet that was just received.
 296          * @return The state the network should have.
 297          */
 298         virtual NetworkRecvStatus Receive_SERVER_CLIENT_QUIT(Packet *p);
 299
 300         /**
 301          * Notification about a client error (and thus the clients disconnection).
 302          * uint32  ID of the client that made the error.
 303          * uint8   Error the client made (see NetworkErrorCode).
 304          * @param p The packet that was just received.
 305          * @return The state the network should have.
 306          */
 307         virtual NetworkRecvStatus Receive_SERVER_CLIENT_ERROR(Packet *p);
 308
 309         /**
 310          * Notification of a new company:
 311          * uint8   ID of the new company.
 312          * @param p The packet that was just received.
 313          * @return The state the network should have.
 314          */
 315         virtual NetworkRecvStatus Receive_SERVER_COMPANY_NEW(Packet *p);
 316
 317         /**
 318          * Company information on a specific company:
 319          * uint8   ID of the company.
 320          * string  Name of the company.
 321          * string  Name of the companies manager.
 322          * uint8   Main company colour.
 323          * bool    Company is password protected.
 324          * uint32  Year the company was inaugurated.
 325          * bool    Company is an AI.
 326          * @param p The packet that was just received.
 327          * @return The state the network should have.
 328          */
 329         virtual NetworkRecvStatus Receive_SERVER_COMPANY_INFO(Packet *p);
 330
 331         /**
 332          * Company information of a specific company:
 333          * uint8   ID of the company.
 334          * string  Name of the company.
 335          * string  Name of the companies manager.
 336          * uint8   Main company colour.
 337          * bool    Company is password protected.
 338          * uint8   Quarters of bankruptcy.
 339          * uint8   Owner of share 1.
 340          * uint8   Owner of share 2.
 341          * uint8   Owner of share 3.
 342          * uint8   Owner of share 4.
 343          * @param p The packet that was just received.
 344          * @return The state the network should have.
 345          */
 346         virtual NetworkRecvStatus Receive_SERVER_COMPANY_UPDATE(Packet *p);
 347
 348         /**
 349          * Notification about a removed company (e.g. due to bankruptcy).
 350          * uint8   ID of the company.
 351          * uint8   Reason for being removed (see #AdminCompanyRemoveReason).
 352          * @param p The packet that was just received.
 353          * @return The state the network should have.
 354          */
 355         virtual NetworkRecvStatus Receive_SERVER_COMPANY_REMOVE(Packet *p);
 356
 357         /**
 358          * Economy update of a specific company:
 359          * uint8   ID of the company.
 360          * uint64  Money.
 361          * uint64  Loan.
 362          * int64   Income.
 363          * uint16  Delivered cargo (this quarter).
 364          * uint64  Company value (last quarter).
 365          * uint16  Performance (last quarter).
 366          * uint16  Delivered cargo (last quarter).
 367          * uint64  Company value (previous quarter).
 368          * uint16  Performance (previous quarter).
 369          * uint16  Delivered cargo (previous quarter).
 370          * @param p The packet that was just received.
 371          * @return The state the network should have.
 372          */
 373         virtual NetworkRecvStatus Receive_SERVER_COMPANY_ECONOMY(Packet *p);
 374
 375         /**
 376          * Company statistics on stations and vehicles:
 377          * uint8   ID of the company.
 378          * uint16  Number of trains.
 379          * uint16  Number of lorries.
 380          * uint16  Number of busses.
 381          * uint16  Number of planes.
 382          * uint16  Number of ships.
 383          * uint16  Number of train stations.
 384          * uint16  Number of lorry stations.
 385          * uint16  Number of bus stops.
 386          * uint16  Number of airports and heliports.
 387          * uint16  Number of harbours.
 388          * @param p The packet that was just received.
 389          * @return The state the network should have.
 390          */
 391         virtual NetworkRecvStatus Receive_SERVER_COMPANY_STATS(Packet *p);
 392
 393         /**
 394          * Send chat from the game into the admin network:
 395          * uint8   Action such as NETWORK_ACTION_CHAT_CLIENT (see #NetworkAction).
 396          * uint8   Destination type such as DESTTYPE_BROADCAST (see #DestType).
 397          * uint32  ID of the client who sent this message.
 398          * string  Message.
 399          * uint64  Money (only when it is a 'give money' action).
 400          * @param p The packet that was just received.
 401          * @return The state the network should have.
 402          */
 403         virtual NetworkRecvStatus Receive_SERVER_CHAT(Packet *p);
 404
 405         /**
 406          * Result of an rcon command:
 407          * uint16  Colour as it would be used on the server or a client.
 408          * string  Output of the executed command.
 409          * @param p The packet that was just received.
 410          * @return The state the network should have.
 411          */
 412         virtual NetworkRecvStatus Receive_SERVER_RCON(Packet *p);
 413
 414         /**
 415          * Send what would be printed on the server's console also into the admin network.
 416          * string  The origin of the text, e.g. "console" for console, or "net" for network related (debug) messages.
 417          * string  Text as found on the console of the server.
 418          * @param p The packet that was just received.
 419          * @return The state the network should have.
 420          */
 421         virtual NetworkRecvStatus Receive_SERVER_CONSOLE(Packet *p);
 422
 423         /**
 424          * Send DoCommand names to the bot upon request only.
 425          * Multiple of these packets can follow each other in order to provide
 426          * all known DoCommand names.
 427          *
 428          * NOTICE: Data provided with this packet is not stable and will not be
 429          *         treated as such. Do not rely on IDs or names to be constant
 430          *         across different versions / revisions of OpenTTD.
 431          *         Data provided in this packet is for logging purposes only.
 432          *
 433          * These three fields are repeated until the packet is full:
 434          * bool    Data to follow.
 435          * uint16  ID of the DoCommand.
 436          * string  Name of DoCommand.
 437          * @param p The packet that was just received.
 438          * @return The state the network should have.
 439          */
 440         virtual NetworkRecvStatus Receive_SERVER_CMD_NAMES(Packet *p);
 441
 442         /**
 443          * Send incoming command packets to the admin network.
 444          * This is for logging purposes only.
 445          *
 446          * NOTICE: Data provided with this packet is not stable and will not be
 447          *         treated as such. Do not rely on IDs or names to be constant
 448          *         across different versions / revisions of OpenTTD.
 449          *         Data provided in this packet is for logging purposes only.
 450          *
 451          * uint32  ID of the client sending the command.
 452          * uint8   ID of the company (0..MAX_COMPANIES-1).
 453          * uint16  ID of the command.
 454          * uint32  P1 (variable data passed to the command).
 455          * uint32  P2 (variable data passed to the command).
 456          * uint32  Tile where this is taking place.
 457          * string  Text passed to the command.
 458          * uint32  Frame of execution.
 459          * @param p The packet that was just received.
 460          * @return The state the network should have.
 461          */
 462         virtual NetworkRecvStatus Receive_SERVER_CMD_LOGGING(Packet *p);
 463
 464         /**
 465          * Send a ping-reply (pong) to the admin that sent us the ping packet.
 466          * uint32  Integer identifier - should be the same as read from the admins ping packet.
 467          * @param p The packet that was just received.
 468          * @return The state the network should have.
 469          */
 470         virtual NetworkRecvStatus Receive_SERVER_PONG(Packet *p);
 471
 472         /**
 473          * Notify the admin connection that the rcon command has finished.
 474          * string The command as requested by the admin connection.
 475          * @param p The packet that was just received.
 476          * @return The state the network should have.
 477          */
 478         virtual NetworkRecvStatus Receive_SERVER_RCON_END(Packet *p);
 479
 480         NetworkRecvStatus HandlePacket(Packet *p);
 481 public:
 482         NetworkRecvStatus CloseConnection(bool error = true) override;
 483
 484         NetworkAdminSocketHandler(SOCKET s);
 485         ~NetworkAdminSocketHandler();
 486
 487         NetworkRecvStatus ReceivePackets();
 488
 489         /**
 490          * Get the status of the admin.
 491          * @return The status of the admin.
 492          */
 493         AdminStatus GetAdminStatus() const
 494         {
 495                 return this->status;
 496         }
 497 };
 498
 499 #endif /* NETWORK_CORE_TCP_ADMIN_H */