src/network/core/tcp_admin.h

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