From c4aa943aaa2718d046aa591555efb7538e77d780 Mon Sep 17 00:00:00 2001 From: rubidium Date: Thu, 5 May 2011 16:24:48 +0000 Subject: (svn r22424) -Document: some more bits --- src/network/network.cpp | 7 +- src/network/network_admin.cpp | 80 ++++++++++++++++++++++ src/network/network_admin.h | 11 +++ src/network/network_chat_gui.cpp | 63 ++++++++++++----- src/network/network_gui.cpp | 9 ++- src/network/network_internal.h | 2 +- src/network/network_server.cpp | 144 +++++++++++++++++++++++++++++++++------ src/network/network_server.h | 12 ++++ 8 files changed, 284 insertions(+), 44 deletions(-) (limited to 'src') diff --git a/src/network/network.cpp b/src/network/network.cpp index 741540661..d3f771c8e 100644 --- a/src/network/network.cpp +++ b/src/network/network.cpp @@ -126,7 +126,7 @@ NetworkClientInfo::~NetworkClientInfo() * @param client_id the ClientID to search for * @return return a pointer to the corresponding NetworkClientSocket struct or NULL when not found */ -/* static */ NetworkClientSocket *NetworkClientSocket::GetByClientID(ClientID client_id) +/* static */ ServerNetworkGameSocketHandler *ServerNetworkGameSocketHandler::GetByClientID(ClientID client_id) { NetworkClientSocket *cs; @@ -479,6 +479,11 @@ void ParseConnectionString(const char **company, const char **port, char *connec } } +/** + * Handle the acception of a connection to the server. + * @param s The socket of the new connection. + * @param address The address of the peer. + */ /* static */ void ServerNetworkGameSocketHandler::AcceptConnection(SOCKET s, const NetworkAddress &address) { /* Register the login */ diff --git a/src/network/network_admin.cpp b/src/network/network_admin.cpp index a29a35b8e..caded2cf9 100644 --- a/src/network/network_admin.cpp +++ b/src/network/network_admin.cpp @@ -107,6 +107,11 @@ ServerNetworkAdminSocketHandler::~ServerNetworkAdminSocketHandler() } } +/** + * Handle the acception of a connection. + * @param s The socket of the new connection. + * @param address The address of the peer. + */ /* static */ void ServerNetworkAdminSocketHandler::AcceptConnection(SOCKET s, const NetworkAddress &address) { ServerNetworkAdminSocketHandler *as = new ServerNetworkAdminSocketHandler(s); @@ -117,6 +122,10 @@ ServerNetworkAdminSocketHandler::~ServerNetworkAdminSocketHandler() * Sending functions for admin network ************/ +/** + * Send an error to the admin. + * @param error The error to send. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendError(NetworkErrorCode error) { Packet *p = new Packet(ADMIN_PACKET_SERVER_ERROR); @@ -133,6 +142,7 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendError(NetworkErrorCode er return this->CloseConnection(true); } +/** Send the protocol version to the admin. */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendProtocol() { Packet *p = new Packet(ADMIN_PACKET_SERVER_PROTOCOL); @@ -152,6 +162,7 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendProtocol() return this->SendWelcome(); } +/** Send a welcome message to the admin. */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendWelcome() { this->status = ADMIN_STATUS_ACTIVE; @@ -174,6 +185,7 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendWelcome() return NETWORK_RECV_STATUS_OKAY; } +/** Tell the admin we started a new game. */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendNewGame() { Packet *p = new Packet(ADMIN_PACKET_SERVER_NEWGAME); @@ -181,6 +193,7 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendNewGame() return NETWORK_RECV_STATUS_OKAY; } +/** Tell the admin we're shutting down. */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendShutdown() { Packet *p = new Packet(ADMIN_PACKET_SERVER_SHUTDOWN); @@ -188,6 +201,7 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendShutdown() return NETWORK_RECV_STATUS_OKAY; } +/** Tell the admin the date. */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendDate() { Packet *p = new Packet(ADMIN_PACKET_SERVER_DATE); @@ -198,6 +212,10 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendDate() return NETWORK_RECV_STATUS_OKAY; } +/** + * Tell the admin that a client joined. + * @param client_id The client that joined. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientJoin(ClientID client_id) { Packet *p = new Packet(ADMIN_PACKET_SERVER_CLIENT_JOIN); @@ -208,6 +226,10 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientJoin(ClientID clien return NETWORK_RECV_STATUS_OKAY; } +/** + * Send an initial set of data from some client's information. + * @param cs The information about a client. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientInfo(const NetworkClientSocket *cs) { /* Only send data when we're a proper client, not just someone trying to query the server. */ @@ -228,6 +250,11 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientInfo(const NetworkC return NETWORK_RECV_STATUS_OKAY; } + +/** + * Send an update for some client's information. + * @param ci The information about a client. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientUpdate(const NetworkClientInfo *ci) { Packet *p = new Packet(ADMIN_PACKET_SERVER_CLIENT_UPDATE); @@ -241,6 +268,10 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientUpdate(const Networ return NETWORK_RECV_STATUS_OKAY; } +/** + * Tell the admin that a client quit. + * @param client_id The client that quit. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientQuit(ClientID client_id) { Packet *p = new Packet(ADMIN_PACKET_SERVER_CLIENT_QUIT); @@ -251,6 +282,11 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientQuit(ClientID clien return NETWORK_RECV_STATUS_OKAY; } +/** + * Tell the admin that a client made an error. + * @param client_id The client that made the error. + * @param error The error that was made. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientError(ClientID client_id, NetworkErrorCode error) { Packet *p = new Packet(ADMIN_PACKET_SERVER_CLIENT_ERROR); @@ -262,6 +298,10 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendClientError(ClientID clie return NETWORK_RECV_STATUS_OKAY; } +/** + * Tell the admin that a new company was founded. + * @param company_id The company that was founded. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyNew(CompanyID company_id) { Packet *p = new Packet(ADMIN_PACKET_SERVER_COMPANY_NEW); @@ -272,6 +312,10 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyNew(CompanyID comp return NETWORK_RECV_STATUS_OKAY; } +/** + * Send the admin some information about a company. + * @param c The company to send the information about. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyInfo(const Company *c) { char company_name[NETWORK_COMPANY_NAME_LENGTH]; @@ -298,6 +342,11 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyInfo(const Company return NETWORK_RECV_STATUS_OKAY; } + +/** + * Send an update about a company. + * @param c The company to send the update of. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyUpdate(const Company *c) { char company_name[NETWORK_COMPANY_NAME_LENGTH]; @@ -327,6 +376,11 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyUpdate(const Compa return NETWORK_RECV_STATUS_OKAY; } +/** + * Tell the admin that a company got removed. + * @param company_id The company that got removed. + * @param acrr The reason for removal, e.g. bankruptcy or merger. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyRemove(CompanyID company_id, AdminCompanyRemoveReason acrr) { Packet *p = new Packet(ADMIN_PACKET_SERVER_COMPANY_REMOVE); @@ -339,6 +393,7 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyRemove(CompanyID c return NETWORK_RECV_STATUS_OKAY; } +/** Send economic information of all companies. */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyEconomy() { const Company *company; @@ -373,6 +428,7 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyEconomy() return NETWORK_RECV_STATUS_OKAY; } +/** Send statistics about the companies. */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyStats() { /* Fetch the latest version of the stats. */ @@ -402,6 +458,14 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCompanyStats() return NETWORK_RECV_STATUS_OKAY; } +/** + * Send a chat message. + * @param action The action associated with the message. + * @param desttype The destination type. + * @param client_id The origin of the chat message. + * @param msg The actual message. + * @param data Arbitrary extra data. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendChat(NetworkAction action, DestType desttype, ClientID client_id, const char *msg, int64 data) { Packet *p = new Packet(ADMIN_PACKET_SERVER_CHAT); @@ -416,6 +480,11 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendChat(NetworkAction action return NETWORK_RECV_STATUS_OKAY; } +/** + * Send the reply of an rcon command. + * @param colour The colour of the text. + * @param result The result of the command. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendRcon(uint16 colour, const char *result) { Packet *p = new Packet(ADMIN_PACKET_SERVER_RCON); @@ -443,6 +512,11 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::Receive_ADMIN_RCON(Packet *p) return NETWORK_RECV_STATUS_OKAY; } +/** + * Send console output of other clients. + * @param origin The origin of the string. + * @param string The string that's put on the console. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendConsole(const char *origin, const char *string) { /* If the length of both strings, plus the 2 '\0' terminations and 3 bytes of the packet @@ -460,6 +534,7 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendConsole(const char *origi return NETWORK_RECV_STATUS_OKAY; } +/** Send the names of the commands. */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCmdNames() { Packet *p = new Packet(ADMIN_PACKET_SERVER_CMD_NAMES); @@ -489,6 +564,11 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCmdNames() return NETWORK_RECV_STATUS_OKAY; } +/** + * Send a command for logging purposes. + * @param client_id The client executing the command. + * @param cp The command that would be executed. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendCmdLogging(ClientID client_id, const CommandPacket *cp) { Packet *p = new Packet(ADMIN_PACKET_SERVER_CMD_LOGGING); diff --git a/src/network/network_admin.h b/src/network/network_admin.h index e05637ea7..01e00e334 100644 --- a/src/network/network_admin.h +++ b/src/network/network_admin.h @@ -21,6 +21,7 @@ extern AdminIndex _redirect_console_to_admin; class ServerNetworkAdminSocketHandler; +/** Pool with all admin connections. */ typedef Pool NetworkAdminSocketPool; extern NetworkAdminSocketPool _networkadminsocket_pool; @@ -82,7 +83,17 @@ public: } }; +/** + * Iterate over all the sockets from a given starting point. + * @param var The variable to iterate with. + * @param start The start of the iteration. + */ #define FOR_ALL_ADMIN_SOCKETS_FROM(var, start) FOR_ALL_ITEMS_FROM(ServerNetworkAdminSocketHandler, adminsocket_index, var, start) + +/** + * Iterate over all the sockets. + * @param var The variable to iterate with. + */ #define FOR_ALL_ADMIN_SOCKETS(var) FOR_ALL_ADMIN_SOCKETS_FROM(var, 0) void NetworkAdminClientInfo(const NetworkClientSocket *cs, bool new_client = false); diff --git a/src/network/network_chat_gui.cpp b/src/network/network_chat_gui.cpp index 6a39ffef0..245d15ea5 100644 --- a/src/network/network_chat_gui.cpp +++ b/src/network/network_chat_gui.cpp @@ -30,30 +30,38 @@ #include "table/strings.h" -/* The draw buffer must be able to contain the chat message, client name and the "[All]" message, +/** The draw buffer must be able to contain the chat message, client name and the "[All]" message, * some spaces and possible translations of [All] to other languages. */ assert_compile((int)DRAW_STRING_BUFFER >= (int)NETWORK_CHAT_LENGTH + NETWORK_NAME_LENGTH + 40); +/** Spacing between chat lines. */ static const uint NETWORK_CHAT_LINE_SPACING = 3; +/** Container for a message. */ struct ChatMessage { - char message[DRAW_STRING_BUFFER]; - TextColour colour; - uint32 remove_time; + char message[DRAW_STRING_BUFFER]; ///< The action message. + TextColour colour; ///< The colour of the message. + uint32 remove_time; ///< The time to remove the message. }; /* used for chat window */ -static ChatMessage *_chatmsg_list = NULL; -static bool _chatmessage_dirty = false; -static bool _chatmessage_visible = false; -static bool _chat_tab_completion_active; -static uint MAX_CHAT_MESSAGES = 0; - -/* The chatbox grows from the bottom so the coordinates are pixels from - * the left and pixels from the bottom. The height is the maximum height */ +static ChatMessage *_chatmsg_list = NULL; ///< The actual chat message list. +static bool _chatmessage_dirty = false; ///< Does the chat message need repainting? +static bool _chatmessage_visible = false; ///< Is a chat message visible. +static bool _chat_tab_completion_active; ///< Whether tab completion is active. +static uint MAX_CHAT_MESSAGES = 0; ///< The limit of chat messages to show. + +/** + * The chatbox grows from the bottom so the coordinates are pixels from + * the left and pixels from the bottom. The height is the maximum height. + */ static PointDimension _chatmsg_box; -static uint8 *_chatmessage_backup = NULL; +static uint8 *_chatmessage_backup = NULL; ///< Backup in case text is moved. +/** + * Count the chat messages. + * @return The number of chat messages. + */ static inline uint GetChatMessageCount() { uint i = 0; @@ -119,6 +127,7 @@ void NetworkReInitChatBoxSize() _chatmessage_backup = ReallocT(_chatmessage_backup, _chatmsg_box.width * _chatmsg_box.height * BlitterFactoryBase::GetCurrentBlitter()->GetBytesPerPixel()); } +/** Initialize all buffers of the chat visualisation. */ void NetworkInitChatMessage() { MAX_CHAT_MESSAGES = _settings_client.gui.network_chat_box_height; @@ -258,7 +267,12 @@ void NetworkDrawChatMessage() _chatmessage_dirty = false; } - +/** + * Send an actual chat message. + * @param buf The message to send. + * @param type The type of destination. + * @param dest The actual destination index. + */ static void SendChat(const char *buf, DestType type, int dest) { if (StrEmpty(buf)) return; @@ -278,11 +292,18 @@ enum NetWorkChatWidgets { NWCW_SENDBUTTON, }; +/** Window to enter the chat message in. */ struct NetworkChatWindow : public QueryStringBaseWindow { - DestType dtype; - StringID dest_string; - int dest; + DestType dtype; ///< The type of destination. + StringID dest_string; ///< String representation of the destination. + int dest; ///< The identifier of the destination. + /** + * Create a chat input window. + * @param desc Description of the looks of the window. + * @param type The type of destination. + * @param dest The actual destination index. + */ NetworkChatWindow(const WindowDesc *desc, DestType type, int dest) : QueryStringBaseWindow(NETWORK_CHAT_LENGTH) { this->dtype = type; @@ -542,6 +563,7 @@ struct NetworkChatWindow : public QueryStringBaseWindow { } }; +/** The widgets of the chat window. */ static const NWidgetPart _nested_chat_window_widgets[] = { NWidget(NWID_HORIZONTAL), NWidget(WWT_CLOSEBOX, COLOUR_GREY, NWCW_CLOSE), @@ -556,6 +578,7 @@ static const NWidgetPart _nested_chat_window_widgets[] = { EndContainer(), }; +/** The description of the chat window. */ static const WindowDesc _chat_window_desc( WDP_MANUAL, 640, 14, // x, y, width, height WC_SEND_NETWORK_MSG, WC_NONE, @@ -563,6 +586,12 @@ static const WindowDesc _chat_window_desc( _nested_chat_window_widgets, lengthof(_nested_chat_window_widgets) ); + +/** + * Show the chat window. + * @param type The type of destination. + * @param dest The actual destination index. + */ void ShowNetworkChatQueryWindow(DestType type, int dest) { DeleteWindowByClass(WC_SEND_NETWORK_MSG); diff --git a/src/network/network_gui.cpp b/src/network/network_gui.cpp index a5ef1ac83..ac3e383de 100644 --- a/src/network/network_gui.cpp +++ b/src/network/network_gui.cpp @@ -2045,11 +2045,10 @@ void ShowClientList() AllocateWindowDescFront(&_client_list_desc, 0); } -/* Vars needed for the join-GUI */ -NetworkJoinStatus _network_join_status; -uint8 _network_join_waiting; -uint32 _network_join_bytes; -uint32 _network_join_bytes_total; +NetworkJoinStatus _network_join_status; ///< The status of joining. +uint8 _network_join_waiting; ///< The number of clients waiting in front of us. +uint32 _network_join_bytes; ///< The number of bytes we already downloaded. +uint32 _network_join_bytes_total; ///< The total number of bytes to download. /** Widgets used for the join status window. */ enum NetworkJoinStatusWidgets { diff --git a/src/network/network_internal.h b/src/network/network_internal.h index 818773256..ccbb23b74 100644 --- a/src/network/network_internal.h +++ b/src/network/network_internal.h @@ -52,7 +52,7 @@ extern bool _ddc_fastforward; typedef class ServerNetworkGameSocketHandler NetworkClientSocket; - +/** Status of the clients during joining. */ enum NetworkJoinStatus { NETWORK_JOIN_STATUS_CONNECTING, NETWORK_JOIN_STATUS_AUTHORIZING, diff --git a/src/network/network_server.cpp b/src/network/network_server.cpp index 53198f970..bd4b16056 100644 --- a/src/network/network_server.cpp +++ b/src/network/network_server.cpp @@ -43,8 +43,10 @@ static ClientID _network_client_id = CLIENT_ID_FIRST; /** Make very sure the preconditions given in network_type.h are actually followed */ assert_compile(MAX_CLIENT_SLOTS > MAX_CLIENTS); +/** Yes... */ assert_compile(NetworkClientSocketPool::MAX_SIZE == MAX_CLIENT_SLOTS); +/** The pool with clients. */ NetworkClientSocketPool _networkclientsocket_pool("NetworkClientSocket"); INSTANTIATE_POOL_METHODS(NetworkClientSocket) @@ -296,6 +298,10 @@ static void NetworkHandleCommandQueue(NetworkClientSocket *cs); * DEF_SERVER_SEND_COMMAND has parameter: NetworkClientSocket *cs ************/ +/** + * Send the client information about a client. + * @param ci The client to send information about. + */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendClientInfo(NetworkClientInfo *ci) { if (ci->client_id != INVALID_CLIENT_ID) { @@ -309,6 +315,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendClientInfo(NetworkClientIn return NETWORK_RECV_STATUS_OKAY; } +/** Send the client information about the companies. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendCompanyInfo() { /* Fetch the latest version of the stats */ @@ -371,6 +378,10 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendCompanyInfo() return NETWORK_RECV_STATUS_OKAY; } +/** + * Send an error to the client, and close its connection. + * @param error The error to disconnect for. + */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendError(NetworkErrorCode error) { char str[100]; @@ -413,6 +424,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendError(NetworkErrorCode err return this->CloseConnection(NETWORK_RECV_STATUS_SERVER_ERROR); } +/** Send the check for the NewGRFs. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendNewGRFCheck() { Packet *p = new Packet(PACKET_SERVER_CHECK_NEWGRFS); @@ -432,6 +444,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendNewGRFCheck() return NETWORK_RECV_STATUS_OKAY; } +/** Request the game password. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendNeedGamePassword() { /* Invalid packet when status is STATUS_AUTH_GAME or higher */ @@ -444,6 +457,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendNeedGamePassword() return NETWORK_RECV_STATUS_OKAY; } +/** Request the company password. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendNeedCompanyPassword() { /* Invalid packet when status is STATUS_AUTH_COMPANY or higher */ @@ -458,6 +472,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendNeedCompanyPassword() return NETWORK_RECV_STATUS_OKAY; } +/** Send the client a welcome message with some basic information. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendWelcome() { Packet *p; @@ -485,6 +500,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendWelcome() return this->SendClientInfo(NetworkClientInfo::GetByClientID(CLIENT_ID_SERVER)); } +/** Tell the client that its put in a waiting queue. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendWait() { int waiting = 0; @@ -503,7 +519,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendWait() return NETWORK_RECV_STATUS_OKAY; } -/* This sends the map to the client */ +/** This sends the map to the client */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendMap() { static uint sent_packets; // How many packets we did send succecfully last time @@ -609,6 +625,10 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendMap() return NETWORK_RECV_STATUS_OKAY; } +/** + * Tell that a client joined. + * @param client_id The client that joined. + */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendJoin(ClientID client_id) { Packet *p = new Packet(PACKET_SERVER_JOIN); @@ -619,7 +639,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendJoin(ClientID client_id) return NETWORK_RECV_STATUS_OKAY; } - +/** Tell the client that they may run to a particular frame. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendFrame() { Packet *p = new Packet(PACKET_SERVER_FRAME); @@ -642,6 +662,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendFrame() return NETWORK_RECV_STATUS_OKAY; } +/** Request the client to sync. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendSync() { Packet *p = new Packet(PACKET_SERVER_SYNC); @@ -655,6 +676,10 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendSync() return NETWORK_RECV_STATUS_OKAY; } +/** + * Send a command to the client to execute. + * @param cp The command to send. + */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendCommand(const CommandPacket *cp) { Packet *p = new Packet(PACKET_SERVER_COMMAND); @@ -667,6 +692,14 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendCommand(const CommandPacke return NETWORK_RECV_STATUS_OKAY; } +/** + * Send a chat message. + * @param action The action associated with the message. + * @param client_id The origin of the chat message. + * @param self_send Whether we did send the message. + * @param msg The actual message. + * @param data Arbitrary extra data. + */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendChat(NetworkAction action, ClientID client_id, bool self_send, const char *msg, int64 data) { Packet *p = new Packet(PACKET_SERVER_CHAT); @@ -681,6 +714,11 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendChat(NetworkAction action, return NETWORK_RECV_STATUS_OKAY; } +/** + * Tell the client another client quit with an error. + * @param client_id The client that quit. + * @param errorno The reason the client quit. + */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendErrorQuit(ClientID client_id, NetworkErrorCode errorno) { Packet *p = new Packet(PACKET_SERVER_ERROR_QUIT); @@ -692,6 +730,10 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendErrorQuit(ClientID client_ return NETWORK_RECV_STATUS_OKAY; } +/** + * Tell the client another client quit. + * @param client_id The client that quit. + */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendQuit(ClientID client_id) { Packet *p = new Packet(PACKET_SERVER_QUIT); @@ -702,6 +744,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendQuit(ClientID client_id) return NETWORK_RECV_STATUS_OKAY; } +/** Tell the client we're shutting down. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendShutdown() { Packet *p = new Packet(PACKET_SERVER_SHUTDOWN); @@ -709,6 +752,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendShutdown() return NETWORK_RECV_STATUS_OKAY; } +/** Tell the client we're starting a new game. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendNewGame() { Packet *p = new Packet(PACKET_SERVER_NEWGAME); @@ -716,6 +760,11 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendNewGame() return NETWORK_RECV_STATUS_OKAY; } +/** + * Send the result of a console action. + * @param colour The colour of the result. + * @param command The command that was executed. + */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendRConResult(uint16 colour, const char *command) { Packet *p = new Packet(PACKET_SERVER_RCON); @@ -726,6 +775,11 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendRConResult(uint16 colour, return NETWORK_RECV_STATUS_OKAY; } +/** + * Tell that a client moved to another company. + * @param client_id The client that moved. + * @param company_id The company the client moved to. + */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendMove(ClientID client_id, CompanyID company_id) { Packet *p = new Packet(PACKET_SERVER_MOVE); @@ -736,6 +790,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendMove(ClientID client_id, C return NETWORK_RECV_STATUS_OKAY; } +/** Send an update about the company password states. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendCompanyUpdate() { Packet *p = new Packet(PACKET_SERVER_COMPANY_UPDATE); @@ -745,6 +800,7 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendCompanyUpdate() return NETWORK_RECV_STATUS_OKAY; } +/** Send an update about the max company/spectator counts. */ NetworkRecvStatus ServerNetworkGameSocketHandler::SendConfigUpdate() { Packet *p = new Packet(PACKET_SERVER_CONFIG_UPDATE); @@ -1168,7 +1224,16 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::Receive_CLIENT_ACK(Packet *p) } - +/** + * Send an actual chat message. + * @param action The action that's performed. + * @param desttype The type of destination. + * @param dest The actual destination index. + * @param msg The actual message. + * @param from_id The origin of the message. + * @param data Arbitrary data. + * @param from_admin Whether the origin is an admin or not. + */ void NetworkServerSendChat(NetworkAction action, DestType desttype, int dest, const char *msg, ClientID from_id, int64 data, bool from_admin) { NetworkClientSocket *cs; @@ -1499,7 +1564,10 @@ void NetworkPopulateCompanyStats(NetworkCompanyStats *stats) } } -/* Send a packet to all clients with updated info about this client_id */ +/** + * Send updated client info of a particular client. + * @param client_id The client to send it for. + */ void NetworkUpdateClientInfo(ClientID client_id) { NetworkClientSocket *cs; @@ -1516,7 +1584,7 @@ void NetworkUpdateClientInfo(ClientID client_id) NetworkAdminClientUpdate(ci); } -/* Check if we want to restart the map */ +/** Check if we want to restart the map */ static void NetworkCheckRestartMap() { if (_settings_client.network.restart_game_year != 0 && _cur_year >= _settings_client.network.restart_game_year) { @@ -1526,11 +1594,12 @@ static void NetworkCheckRestartMap() } } -/* Check if the server has autoclean_companies activated - Two things happen: - 1) If a company is not protected, it is closed after 1 year (for example) - 2) If a company is protected, protection is disabled after 3 years (for example) - (and item 1. happens a year later) */ +/** Check if the server has autoclean_companies activated + * Two things happen: + * 1) If a company is not protected, it is closed after 1 year (for example) + * 2) If a company is protected, protection is disabled after 3 years (for example) + * (and item 1. happens a year later) + */ static void NetworkAutoCleanCompanies() { const NetworkClientInfo *ci; @@ -1600,8 +1669,11 @@ static void NetworkAutoCleanCompanies() } } -/* This function changes new_name to a name that is unique (by adding #1 ...) - * and it returns true if that succeeded. */ +/** + * Check whether a name is unique, and otherwise try to make it unique. + * @param new_name The name to check/modify. + * @return True if an unique name was achieved. + */ bool NetworkFindName(char new_name[NETWORK_CLIENT_NAME_LENGTH]) { bool found_name = false; @@ -1683,7 +1755,10 @@ void NetworkServerSetCompanyPassword(CompanyID company_id, const char *password, NetworkServerUpdateCompanyPassworded(company_id, !StrEmpty(_network_company_states[company_id].password)); } -/* Handle the local command-queue */ +/** + * Handle the command-queue of a socket. + * @param cs The socket to handle the queue for. + */ static void NetworkHandleCommandQueue(NetworkClientSocket *cs) { CommandPacket *cp; @@ -1693,7 +1768,10 @@ static void NetworkHandleCommandQueue(NetworkClientSocket *cs) } } -/* This is called every tick if this is a _network_server */ +/** + * This is called every tick if this is a _network_server + * @param send_frame Whether to send the frame to the clients. + */ void NetworkServer_Tick(bool send_frame) { NetworkClientSocket *cs; @@ -1817,6 +1895,7 @@ const char *ServerNetworkGameSocketHandler::GetClientIP() return this->client_address.GetHostname(); } +/** Show the status message of all clients on the console. */ void NetworkServerShowStatusToConsole() { static const char * const stat_str[] = { @@ -1860,6 +1939,11 @@ void NetworkServerSendConfigUpdate() } } +/** + * Tell that a particular company is (not) passworded. + * @param company_id The company that got/removed the password. + * @param passworded Whether the password was received or removed. + */ void NetworkServerUpdateCompanyPassworded(CompanyID company_id, bool passworded) { if (NetworkCompanyIsPassworded(company_id) == passworded) return; @@ -1909,27 +1993,42 @@ void NetworkServerDoMove(ClientID client_id, CompanyID company_id) NetworkServerSendChat(action, DESTTYPE_BROADCAST, 0, "", client_id, company_id + 1); } +/** + * Send an rcon reply to the client. + * @param client_id The identifier of the client. + * @param colour_code The colour of the text. + * @param string The actual reply. + */ void NetworkServerSendRcon(ClientID client_id, TextColour colour_code, const char *string) { NetworkClientSocket::GetByClientID(client_id)->SendRConResult(colour_code, string); } -static void NetworkServerSendError(ClientID client_id, NetworkErrorCode error) -{ - NetworkClientSocket::GetByClientID(client_id)->SendError(error); -} - +/** + * Kick a single client. + * @param client_id The client to kick. + */ void NetworkServerKickClient(ClientID client_id) { if (client_id == CLIENT_ID_SERVER) return; - NetworkServerSendError(client_id, NETWORK_ERROR_KICKED); + NetworkClientSocket::GetByClientID(client_id)->SendError(NETWORK_ERROR_KICKED); } +/** + * Ban, or kick, everyone joined from the given client's IP. + * @param client_id The client to check for. + * @param ban Whether to ban or kick. + */ uint NetworkServerKickOrBanIP(ClientID client_id, bool ban) { return NetworkServerKickOrBanIP(NetworkClientSocket::GetByClientID(client_id)->GetClientIP(), ban); } +/** + * Kick or ban someone based on an IP address. + * @param ip The IP address/range to ban/kick. + * @param ban Whether to ban or just kick. + */ uint NetworkServerKickOrBanIP(const char *ip, bool ban) { /* Add address to ban-list */ @@ -1950,6 +2049,11 @@ uint NetworkServerKickOrBanIP(const char *ip, bool ban) return n; } +/** + * Check whether a particular company has clients. + * @param company The company to check. + * @return True if at least one client is joined to the company. + */ bool NetworkCompanyHasClients(CompanyID company) { const NetworkClientInfo *ci; diff --git a/src/network/network_server.h b/src/network/network_server.h index 2aa0bef34..ad1b381a9 100644 --- a/src/network/network_server.h +++ b/src/network/network_server.h @@ -19,7 +19,9 @@ #include "../thread/thread.h" class ServerNetworkGameSocketHandler; +/** Make the code look slightliy nicer/simpler. */ typedef ServerNetworkGameSocketHandler NetworkClientSocket; +/** Pool with all client sockets. */ typedef Pool NetworkClientSocketPool; extern NetworkClientSocketPool _networkclientsocket_pool; @@ -125,7 +127,17 @@ public: void NetworkServer_Tick(bool send_frame); void NetworkServerSetCompanyPassword(CompanyID company_id, const char *password, bool already_hashed = true); +/** + * Iterate over all the sockets from a given starting point. + * @param var The variable to iterate with. + * @param start The start of the iteration. + */ #define FOR_ALL_CLIENT_SOCKETS_FROM(var, start) FOR_ALL_ITEMS_FROM(NetworkClientSocket, clientsocket_index, var, start) + +/** + * Iterate over all the sockets. + * @param var The variable to iterate with. + */ #define FOR_ALL_CLIENT_SOCKETS(var) FOR_ALL_CLIENT_SOCKETS_FROM(var, 0) #else /* ENABLE_NETWORK */ -- cgit v1.2.3-70-g09d2