diff --git a/src/network/network.cpp b/src/network/network.cpp index 628845aa50..47ad8b10ce 100644 --- a/src/network/network.cpp +++ b/src/network/network.cpp @@ -61,7 +61,7 @@ bool _ddc_fastforward = true; static_assert(NetworkClientInfoPool::MAX_SIZE == NetworkClientSocketPool::MAX_SIZE); /** The pool with client information. */ -NetworkClientInfoPool _networkclientinfo_pool("NetworkClientInfo"); +NetworkClientInfoPool _networkclientinfo_pool{"NetworkClientInfo"}; INSTANTIATE_POOL_METHODS(NetworkClientInfo) bool _networking; ///< are we in networking mode? @@ -213,6 +213,10 @@ bool NetworkAuthorizedKeys::Remove(std::string_view key) } +/** + * Get the number of clients that are playing as a spectator. + * @return The number of spectator clients. + */ uint8_t NetworkSpectatorCount() { uint8_t count = 0; @@ -228,9 +232,15 @@ uint8_t NetworkSpectatorCount() } -/* This puts a text-message to the console, or in the future, the chat-box, - * (to keep it all a bit more general) - * If 'self_send' is true, this is the client who is sending the message */ +/** + * Writes a text-message to the console and the chat box. + * @param action The network action that lead to this message. + * @param colour The color for the message. + * @param self_send Whether the message came from ourselves, or the network. + * @param name The name of the client. + * @param str Arbitrary extra string, depending on the action. For example a complete message or company name. + * @param data Arbitrary extra data, depending on the action. For example a client's ID or an amount of money that was given. + */ void NetworkTextMessage(NetworkAction action, TextColour colour, bool self_send, std::string_view name, std::string_view str, StringParameter &&data) { std::string message; @@ -281,7 +291,11 @@ void NetworkTextMessage(NetworkAction action, TextColour colour, bool self_send, NetworkAddChatMessage(colour, _settings_client.gui.network_chat_timeout, message); } -/* Calculate the frame-lag of a client */ +/** + * Calculate the frame-lag of a client. + * @param cs The client's socket. + * @return The number of frames the client is lagging behind. + */ uint NetworkCalculateLag(const NetworkClientSocket *cs) { int lag = cs->last_frame_server - cs->last_frame; @@ -295,8 +309,10 @@ uint NetworkCalculateLag(const NetworkClientSocket *cs) } -/* There was a non-recoverable error, drop back to the main menu with a nice - * error */ +/** + * There was a non-recoverable error, drop back to the main menu with a nice error. + * @param error_string The error message to show. + */ void ShowNetworkError(StringID error_string) { _switch_mode = SM_MENU; @@ -621,7 +637,10 @@ void NetworkClose(bool close_admins) InitializeNetworkPools(close_admins); } -/* Initializes the network (cleans sockets and stuff) */ +/** + * Initializes the network (cleans sockets and stuff) + * @param close_admins Whether to disconnect all the admin connections. + */ static void NetworkInitialize(bool close_admins = true) { InitializeNetworkPools(close_admins); @@ -635,9 +654,13 @@ static void NetworkInitialize(bool close_admins = true) /** Non blocking connection to query servers for their game info. */ class TCPQueryConnecter : public TCPServerConnecter { private: - std::string connection_string; + std::string connection_string; ///< The address that this connecter is trying to query. public: + /** + * Create the connecter. + * @param connection_string The address to connect to. + */ TCPQueryConnecter(std::string_view connection_string) : TCPServerConnecter(connection_string, NETWORK_DEFAULT_PORT), connection_string(connection_string) {} void OnFailure() override @@ -739,9 +762,13 @@ void NetworkRebuildHostList() /** Non blocking connection create to actually connect to servers */ class TCPClientConnecter : public TCPServerConnecter { private: - std::string connection_string; + std::string connection_string; ///< The address that this connecter is trying to connect to. public: + /** + * Create the connecter. + * @param connection_string The address to connect to. + */ TCPClientConnecter(std::string_view connection_string) : TCPServerConnecter(connection_string, NETWORK_DEFAULT_PORT), connection_string(connection_string) {} void OnFailure() override @@ -825,12 +852,17 @@ void NetworkClientJoinGame() TCPConnecter::Create(_network_join.connection_string); } +/** Initialise/fill the server's game info. */ static void NetworkInitGameInfo() { FillStaticNetworkServerGameInfo(); /* The server is a client too */ _network_game_info.clients_on = _network_dedicated ? 0 : 1; +} +/** Initialise the server's client info. */ +static void NetworkInitServerClientInfo() +{ /* There should be always space for the server. */ assert(NetworkClientInfo::CanAllocateItem()); NetworkClientInfo *ci = NetworkClientInfo::Create(CLIENT_ID_SERVER); @@ -884,6 +916,10 @@ static void CheckClientAndServerName() } } +/** + * Run everything related to the network when starting a server. + * @return \c true iff everything required to start the server succeeded. + */ bool NetworkServerStart() { if (!_network_available) return false; @@ -922,6 +958,7 @@ bool NetworkServerStart() _network_clients_connected = 0; NetworkInitGameInfo(); + NetworkInitServerClientInfo(); if (_settings_client.network.server_game_type != ServerGameType::Local) { _network_coordinator_client.Register(); diff --git a/src/network/network_admin.cpp b/src/network/network_admin.cpp index 6e0a4196d7..0d153d1193 100644 --- a/src/network/network_admin.cpp +++ b/src/network/network_admin.cpp @@ -857,6 +857,10 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::Receive_ADMIN_JOIN_SECURE(Pac return this->SendAuthRequest(); } +/** + * Send the client a request to authenticate. + * @return The state the network should have. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendAuthRequest() { this->status = ADMIN_STATUS_AUTHENTICATE; @@ -871,6 +875,10 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendAuthRequest() return NETWORK_RECV_STATUS_OKAY; } +/** + * Send the client the message to enable encryption. + * @return The state the network should have. + */ NetworkRecvStatus ServerNetworkAdminSocketHandler::SendEnableEncryption() { if (this->status != ADMIN_STATUS_AUTHENTICATE) return this->SendError(NetworkErrorCode::NotExpected); diff --git a/src/network/network_admin.h b/src/network/network_admin.h index 7da444ac20..92bd58bc8d 100644 --- a/src/network/network_admin.h +++ b/src/network/network_admin.h @@ -17,8 +17,9 @@ extern AdminID _redirect_console_to_admin; class ServerNetworkAdminSocketHandler; -/** Pool with all admin connections. */ +/** Pool type for admin connections. */ using NetworkAdminSocketPool = Pool; +/** Pool with all admin connections. */ extern NetworkAdminSocketPool _networkadminsocket_pool; /** Class for handling the server side of the game connection. */ @@ -90,7 +91,13 @@ public: return "admin"; } + /** Filter for the #IterateActive iterator. */ struct ServerNetworkAdminSocketHandlerFilter { + /** + * Check whether the given admin is active. + * @param index The index of the admin. + * @return \c true iff the admin's status is #ADMIN_STATUS_ACTIVE. + */ bool operator() (size_t index) { return ServerNetworkAdminSocketHandler::Get(index)->GetAdminStatus() == ADMIN_STATUS_ACTIVE; } }; diff --git a/src/network/network_chat_gui.cpp b/src/network/network_chat_gui.cpp index 94d189722d..0338f31d72 100644 --- a/src/network/network_chat_gui.cpp +++ b/src/network/network_chat_gui.cpp @@ -269,6 +269,7 @@ static void SendChat(std::string_view buf, NetworkChatDestinationType type, int } } +/** Implementation of AutoCompletion for nicknames and town names in the chat. */ class NetworkChatAutoCompletion final : public AutoCompletion { public: using AutoCompletion::AutoCompletion; diff --git a/src/network/network_client.cpp b/src/network/network_client.cpp index 13783e2f10..73db1ef7e3 100644 --- a/src/network/network_client.cpp +++ b/src/network/network_client.cpp @@ -526,7 +526,8 @@ bool ClientNetworkGameSocketHandler::IsConnected() * Receiving functions ************/ -extern bool SafeLoad(const std::string &filename, SaveLoadOperation fop, DetailedFileType dft, GameMode newgm, Subdirectory subdir, std::shared_ptr lf); +struct LoadFilter; +extern bool SafeLoad(const std::string &filename, SaveLoadOperation fop, DetailedFileType dft, GameMode newgm, Subdirectory subdir, std::shared_ptr lf); NetworkRecvStatus ClientNetworkGameSocketHandler::Receive_SERVER_FULL(Packet &) { @@ -706,6 +707,7 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::Receive_SERVER_CHECK_NEWGRFS(P return ret; } +/** Handles requests by immediately returning the server password, or show the user to password window. */ class ClientGamePasswordRequestHandler : public NetworkAuthenticationPasswordRequestHandler { void SendResponse() override { MyClient::SendAuthResponse(); } void AskUserForPassword(std::shared_ptr request) override diff --git a/src/network/network_content.cpp b/src/network/network_content.cpp index 18cb5cda62..34413e8574 100644 --- a/src/network/network_content.cpp +++ b/src/network/network_content.cpp @@ -778,6 +778,7 @@ void ClientNetworkContentSocketHandler::SendReceive() /** Timeout after queueing content for it to try to be requested. */ static constexpr auto CONTENT_QUEUE_TIMEOUT = std::chrono::milliseconds(100); +/** Timer delay requesting content, so it can be batched more efficiently in asynchronous contexts. */ static TimeoutTimer _request_queue_timeout = {CONTENT_QUEUE_TIMEOUT, []() { _network_content_client.RequestQueuedContentInfo(); }}; diff --git a/src/network/network_content_gui.cpp b/src/network/network_content_gui.cpp index 02bf8c7671..899e296f3d 100644 --- a/src/network/network_content_gui.cpp +++ b/src/network/network_content_gui.cpp @@ -42,6 +42,12 @@ static bool _accepted_external_search = false; struct ContentTextfileWindow : public TextfileWindow { const ContentInfo *ci = nullptr; ///< View the textfile of this ContentInfo. + /** + * Create the window with one of the text files associated with content. + * @param parent Our parent window, i.e. if that window closes we close. + * @param file_type The type of file to load. + * @param ci The content info to load the file for. + */ ContentTextfileWindow(Window *parent, TextfileType file_type, const ContentInfo *ci) : TextfileWindow(parent, file_type), ci(ci) { this->ConstructWindow(); @@ -50,6 +56,10 @@ struct ContentTextfileWindow : public TextfileWindow { this->LoadTextfile(textfile.value(), GetContentInfoSubDir(this->ci->type)); } + /** + * Get the #StringID of the content type associated with this window. + * @return The string. + */ StringID GetTypeString() const { switch (this->ci->type) { @@ -77,6 +87,12 @@ struct ContentTextfileWindow : public TextfileWindow { } }; +/** + * Open the window with one of the text files associated with content. + * @param parent Our parent window, i.e. if that window closes we close. + * @param file_type The type of file to load. + * @param ci The content info to load the file for. + */ static void ShowContentTextfileWindow(Window *parent, TextfileType file_type, const ContentInfo *ci) { parent->CloseChildWindowById(WC_TEXTFILE, file_type); diff --git a/src/network/network_coordinator.cpp b/src/network/network_coordinator.cpp index 1a84a64046..ae988f96a0 100644 --- a/src/network/network_coordinator.cpp +++ b/src/network/network_coordinator.cpp @@ -416,6 +416,10 @@ bool ClientNetworkCoordinatorSocketHandler::Receive_GC_TURN_CONNECT(Packet &p) return true; } +/** + * Perform the TURN connection with the given token. + * @param token The token for the connection. + */ void ClientNetworkCoordinatorSocketHandler::StartTurnConnection(std::string_view token) { auto turn_it = this->turn_handlers.find(token); @@ -424,6 +428,7 @@ void ClientNetworkCoordinatorSocketHandler::StartTurnConnection(std::string_view turn_it->second->Connect(); } +/** Connect to the coordinator. */ void ClientNetworkCoordinatorSocketHandler::Connect() { /* We are either already connected or are trying to connect. */ diff --git a/src/network/network_crypto.cpp b/src/network/network_crypto.cpp index 88d56cb1d2..5e64160cb1 100644 --- a/src/network/network_crypto.cpp +++ b/src/network/network_crypto.cpp @@ -187,6 +187,7 @@ X25519AuthenticationHandler::X25519AuthenticationHandler(const X25519SecretKey & { } +/** @copydoc NetworkAuthenticationServerHandler::SendRequest */ /* virtual */ void X25519AuthenticationHandler::SendRequest(Packet &p) { p.Send_bytes(this->our_public_key); @@ -265,11 +266,13 @@ bool X25519AuthenticationHandler::ReceiveEnableEncryption(struct Packet &p) return p.Recv_bytes(this->encryption_nonce) == this->encryption_nonce.size(); } +/** @copydoc NetworkAuthenticationHandler::CreateClientToServerEncryptionHandler */ std::unique_ptr X25519AuthenticationHandler::CreateClientToServerEncryptionHandler() const { return std::make_unique(this->derived_keys.ClientToServer(), this->encryption_nonce); } +/** @copydoc NetworkAuthenticationHandler::CreateServerToClientEncryptionHandler */ std::unique_ptr X25519AuthenticationHandler::CreateServerToClientEncryptionHandler() const { return std::make_unique(this->derived_keys.ServerToClient(), this->encryption_nonce); diff --git a/src/network/network_crypto_internal.h b/src/network/network_crypto_internal.h index fbc4524bd4..50c254d645 100644 --- a/src/network/network_crypto_internal.h +++ b/src/network/network_crypto_internal.h @@ -184,7 +184,7 @@ public: */ class X25519PAKEClientHandler : protected X25519AuthenticationHandler, public NetworkAuthenticationClientHandler { private: - std::shared_ptr handler; + std::shared_ptr handler; ///< Callback to get the password from if needed. public: /** diff --git a/src/network/network_func.h b/src/network/network_func.h index a2dfa222d2..fa36ef57d3 100644 --- a/src/network/network_func.h +++ b/src/network/network_func.h @@ -45,7 +45,7 @@ void NetworkDisconnect(bool close_admins = true); void NetworkGameLoop(); void NetworkBackgroundLoop(); std::string_view ParseFullConnectionString(std::string_view connection_string, uint16_t &port, CompanyID *company_id = nullptr); -using NetworkCompanyStatsArray = TypedIndexContainer, CompanyID>; +using NetworkCompanyStatsArray = TypedIndexContainer, CompanyID>; ///< Container with statistics for all possible companies. NetworkCompanyStatsArray NetworkGetCompanyStats(); void NetworkUpdateClientInfo(ClientID client_id); diff --git a/src/network/network_gamelist.h b/src/network/network_gamelist.h index 55f2254c49..61d973b0ed 100644 --- a/src/network/network_gamelist.h +++ b/src/network/network_gamelist.h @@ -25,6 +25,10 @@ enum NetworkGameStatus : uint8_t { /** Structure with information shown in the game list (GUI) */ struct NetworkGame { + /** + * Create the game. + * @param connection_string The address of the server. + */ NetworkGame(std::string_view connection_string) : connection_string(connection_string) {} NetworkGameInfo info{}; ///< The game information of this server. diff --git a/src/network/network_gui.cpp b/src/network/network_gui.cpp index c0d58af14f..db7a7054bb 100644 --- a/src/network/network_gui.cpp +++ b/src/network/network_gui.cpp @@ -68,6 +68,10 @@ void UpdateNetworkGameWindow() InvalidateWindowData(WC_NETWORK_WINDOW, WN_NETWORK_WINDOW_GAME, 0); } +/** + * Create the dropdown with visibility options for the server. + * @return The created dropdown list. + */ static DropDownList BuildVisibilityDropDownList() { DropDownList list; @@ -79,14 +83,15 @@ static DropDownList BuildVisibilityDropDownList() return list; } -typedef GUIList GUIGameServerList; -typedef int ServerListPosition; -static const ServerListPosition SLP_INVALID = -1; +using GUIGameServerList = GUIList; ///< The list of servers with sorting/filtering. +using ServerListPosition = int; ///< A location within the server list +static const ServerListPosition SLP_INVALID = -1; ///< Sentinel for an invalid location in the server list. /** Full blown container to make it behave exactly as we want :) */ class NWidgetServerListHeader : public NWidgetContainer { static const uint MINIMUM_NAME_WIDTH_BEFORE_NEW_HEADER = 150; ///< Minimum width before adding a new header public: + /** Create the header. */ NWidgetServerListHeader() : NWidgetContainer(NWID_HORIZONTAL) { auto leaf = std::make_unique(WWT_PUSHTXTBTN, COLOUR_WHITE, WID_NG_NAME, WidgetData{.string = STR_NETWORK_SERVER_LIST_GAME_NAME}, STR_NETWORK_SERVER_LIST_GAME_NAME_TOOLTIP); @@ -173,6 +178,7 @@ public: } }; +/** Window with the list of game servers. */ class NetworkGameWindow : public Window { protected: /** Runtime saved values. */ @@ -435,6 +441,10 @@ protected: } public: + /** + * Create the window. + * @param desc The description of the window. + */ NetworkGameWindow(WindowDesc &desc) : Window(desc), name_editbox(NETWORK_CLIENT_NAME_LENGTH), filter_editbox(120) { this->CreateNestedTree(); @@ -600,6 +610,10 @@ public: this->DrawWidgets(); } + /** + * Get the string for the header of the 'selected server' subpanel. + * @return The StringID to show. + */ StringID GetHeaderString() const { if (this->server == nullptr) return STR_NETWORK_SERVER_LIST_GAME_INFO; @@ -613,6 +627,10 @@ public: } } + /** + * Draw the details about the selected server. + * @param r The bounding box to draw within. + */ void DrawDetails(const Rect &r) const { NetworkGame *sel = this->server; @@ -854,11 +872,7 @@ const std::initializer_list NetworkGa &NGameSearchFilter }; -static std::unique_ptr MakeResizableHeader() -{ - return std::make_unique(); -} - +/** Widgets and the structure of the NetworkGameWindow. */ static constexpr std::initializer_list _nested_network_game_widgets = { /* TOP */ NWidget(NWID_HORIZONTAL), @@ -878,7 +892,7 @@ static constexpr std::initializer_list _nested_network_game_widgets EndContainer(), NWidget(NWID_HORIZONTAL), NWidget(NWID_VERTICAL), - NWidgetFunction(MakeResizableHeader), + NWidgetFunction([]() -> std::unique_ptr { return std::make_unique(); }), NWidget(WWT_MATRIX, COLOUR_LIGHT_BLUE, WID_NG_MATRIX), SetResize(1, 1), SetFill(1, 0), SetMatrixDataTip(1, 0, STR_NETWORK_SERVER_LIST_CLICK_GAME_TO_SELECT), SetScrollbar(WID_NG_SCROLLBAR), EndContainer(), @@ -936,6 +950,7 @@ static constexpr std::initializer_list _nested_network_game_widgets EndContainer(), }; +/** Description of the NetworkGameWindow. */ static WindowDesc _network_game_window_desc( WDP_CENTER, "list_servers", 1000, 730, WC_NETWORK_WINDOW, WC_NONE, @@ -943,6 +958,7 @@ static WindowDesc _network_game_window_desc( _nested_network_game_widgets ); +/** Show the server list window. */ void ShowNetworkGameWindow() { static bool first = true; @@ -960,10 +976,15 @@ void ShowNetworkGameWindow() new NetworkGameWindow(_network_game_window_desc); } +/** Window to configure and start your server with. */ struct NetworkStartServerWindow : public Window { WidgetID widget_id{}; ///< The widget that has the pop-up input menu QueryString name_editbox; ///< Server name editbox. + /** + * Create the window. + * @param desc The description of the window. + */ NetworkStartServerWindow(WindowDesc &desc) : Window(desc), name_editbox(NETWORK_NAME_LENGTH) { this->InitNested(WN_NETWORK_WINDOW_START); @@ -1099,6 +1120,10 @@ struct NetworkStartServerWindow : public Window { this->SetDirty(); } + /** + * Check whether the currently entered server name is valid, and if so update the server_name setting. + * @return \c true iff the server name is valid. + */ bool CheckServerName() { std::string str{this->name_editbox.text.GetText()}; @@ -1134,6 +1159,7 @@ struct NetworkStartServerWindow : public Window { } }; +/** Widgets and the structure of the NetworkStartServerWindow. */ static constexpr std::initializer_list _nested_network_start_server_window_widgets = { NWidget(NWID_HORIZONTAL), NWidget(WWT_CLOSEBOX, COLOUR_LIGHT_BLUE), @@ -1201,6 +1227,7 @@ static constexpr std::initializer_list _nested_network_start_server EndContainer(), }; +/** Description of the NetworkStartServerWindow. */ static WindowDesc _network_start_server_window_desc( WDP_CENTER, {}, 0, 0, WC_NETWORK_WINDOW, WC_NONE, @@ -1208,6 +1235,7 @@ static WindowDesc _network_start_server_window_desc( _nested_network_start_server_window_widgets ); +/** Show the window to configure and start your server with. */ static void ShowNetworkStartServerWindow() { if (!NetworkValidateOurClientName()) return; @@ -1222,6 +1250,7 @@ static void ShowNetworkStartServerWindow() extern void DrawCompanyIcon(CompanyID cid, int x, int y); +/** Widgets and the structure of the NetworkClientListWindow. */ static constexpr std::initializer_list _nested_client_list_widgets = { NWidget(NWID_HORIZONTAL), NWidget(WWT_CLOSEBOX, COLOUR_GREY), @@ -1275,6 +1304,7 @@ static constexpr std::initializer_list _nested_client_list_widgets EndContainer(), }; +/** Description of the NetworkClientListWindow. */ static WindowDesc _client_list_desc( WDP_AUTO, "list_clients", 220, 300, WC_CLIENT_LIST, WC_NONE, @@ -1328,6 +1358,13 @@ public: uint height; ///< Calculated height of the button. uint width; ///< Calculated width of the button. + /** + * Create the button. + * @param sprite The sprite to draw on the button. + * @param tooltip The tooltip of the button. + * @param colour The colour of the button. + * @param disabled Whether the button is disabled or not. + */ ButtonCommon(SpriteID sprite, StringID tooltip, Colours colour, bool disabled = false) : sprite(sprite), tooltip(tooltip), @@ -1360,6 +1397,15 @@ private: ButtonCallback proc; ///< Callback proc to call when button is pressed. public: + /** + * Create the button. + * @param sprite The sprite to draw on the button. + * @param tooltip The tooltip of the button. + * @param colour The colour of the button. + * @param id The identifier of the object this button belongs to. + * @param proc The callback to call upon clicking. + * @param disabled Whether the button is disabled or not. + */ Button(SpriteID sprite, StringID tooltip, Colours colour, T id, ButtonCallback proc, bool disabled = false) : ButtonCommon(sprite, tooltip, colour, disabled), id(id), @@ -1376,8 +1422,8 @@ public: } }; -using CompanyButton = Button; -using ClientButton = Button; +using CompanyButton = Button; ///< Button linked to a company. +using ClientButton = Button; ///< Button linked to a client. /** * Base interface for a network client list line. @@ -1395,6 +1441,11 @@ public: */ virtual void Draw(Rect r) const = 0; + /** + * Construct a button and add it. + * @param ...args The arguments to construct the button. + * @return Reference to the created button. + */ template T &AddButton(TArgs &&... args) { @@ -1453,8 +1504,13 @@ protected: } }; +/** A line in the NetworkClientList with a company on it. */ class CompanyButtonLine : public ButtonLine { public: + /** + * Create the line. + * @param company_id The company to show on the line. + */ CompanyButtonLine(CompanyID company_id) : company_id(company_id) {} void Draw(Rect r) const override @@ -1477,11 +1533,16 @@ public: }; private: - CompanyID company_id; + CompanyID company_id; ///< The company to show on the line. }; +/** A line in the NetworkClientList with a client on it. */ class ClientButtonLine : public ButtonLine { public: + /** + * Create the line. + * @param client_pool_id The index into the client pool of client to show on this line. + */ ClientButtonLine(ClientPoolID client_pool_id) : client_pool_id(client_pool_id) {} void Draw(Rect r) const override @@ -1530,7 +1591,7 @@ public: } private: - ClientPoolID client_pool_id; + ClientPoolID client_pool_id; ///< The client to show on this line. }; /** @@ -1563,22 +1624,18 @@ private: /** * Chat button on a Company is clicked. - * @param w The instance of this window. - * @param pt The point where this button was clicked. * @param company_id The company this button was assigned to. */ - static void OnClickCompanyChat([[maybe_unused]] NetworkClientListWindow *w, [[maybe_unused]] Point pt, CompanyID company_id) + static void OnClickCompanyChat(NetworkClientListWindow *, Point, CompanyID company_id) { ShowNetworkChatQueryWindow(NetworkChatDestinationType::Team, company_id.base()); } /** * Join button on a Company is clicked. - * @param w The instance of this window. - * @param pt The point where this button was clicked. * @param company_id The company this button was assigned to. */ - static void OnClickCompanyJoin([[maybe_unused]] NetworkClientListWindow *w, [[maybe_unused]] Point pt, CompanyID company_id) + static void OnClickCompanyJoin(NetworkClientListWindow *, Point, CompanyID company_id) { if (_network_server) { NetworkServerDoMove(CLIENT_ID_SERVER, company_id); @@ -1590,10 +1647,8 @@ private: /** * Create new company button is clicked. - * @param w The instance of this window. - * @param pt The point where this button was clicked. */ - static void OnClickCompanyNew([[maybe_unused]] NetworkClientListWindow *w, [[maybe_unused]] Point pt, CompanyID) + static void OnClickCompanyNew(NetworkClientListWindow *, Point, CompanyID) { Command::Post(CompanyCtrlAction::New, CompanyID::Invalid(), CompanyRemoveReason::None, _network_own_client_id); } @@ -1604,7 +1659,7 @@ private: * @param pt The point where this button was clicked. * @param client_id The client this button was assigned to. */ - static void OnClickClientAdmin([[maybe_unused]] NetworkClientListWindow *w, [[maybe_unused]] Point pt, ClientID client_id) + static void OnClickClientAdmin(NetworkClientListWindow *w, Point pt, ClientID client_id) { DropDownList list; list.push_back(MakeDropDownListStringItem(STR_NETWORK_CLIENT_LIST_ADMIN_CLIENT_KICK, to_underlying(DropDownAction::AdminKickClient))); @@ -1626,7 +1681,7 @@ private: * @param pt The point where this button was clicked. * @param company_id The company this button was assigned to. */ - static void OnClickCompanyAdmin([[maybe_unused]] NetworkClientListWindow *w, [[maybe_unused]] Point pt, CompanyID company_id) + static void OnClickCompanyAdmin(NetworkClientListWindow *w, Point pt, CompanyID company_id) { DropDownList list; if (_network_server) list.push_back(MakeDropDownListStringItem(STR_NETWORK_CLIENT_LIST_ADMIN_COMPANY_RESET, to_underlying(DropDownAction::AdminResetCompany), NetworkCompanyHasClients(company_id))); @@ -1647,16 +1702,18 @@ private: /** * Chat button on a Client is clicked. - * @param w The instance of this window. - * @param pt The point where this button was clicked. * @param client_id The client this button was assigned to. */ - static void OnClickClientChat([[maybe_unused]] NetworkClientListWindow *w, [[maybe_unused]] Point pt, ClientID client_id) + static void OnClickClientChat(NetworkClientListWindow *, Point, ClientID client_id) { ShowNetworkChatQueryWindow(NetworkChatDestinationType::Client, client_id); } - static void OnClickClientAuthorize([[maybe_unused]] NetworkClientListWindow *w, [[maybe_unused]] Point pt, ClientID client_id) + /** + * Authorize button on a Client is clicked. + * @param client_id The client this button was assigned to. + */ + static void OnClickClientAuthorize(NetworkClientListWindow *, Point, ClientID client_id) { AutoRestoreBackup cur_company(_current_company, NetworkClientInfo::GetByClientID(_network_own_client_id)->client_playas); Command::Post(CompanyAllowListCtrlAction::AddKey, NetworkClientInfo::GetByClientID(client_id)->public_key); @@ -1726,6 +1783,11 @@ private: } public: + /** + * Create the window. + * @param desc The description of the window. + * @param window_number The window number for this window. + */ NetworkClientListWindow(WindowDesc &desc, WindowNumber window_number) : Window(desc) { this->CreateNestedTree(); @@ -2009,6 +2071,7 @@ public: } }; +/** Open the client list window. */ void ShowClientList() { AllocateWindowDescFront(_client_list_desc, 0); @@ -2019,9 +2082,14 @@ uint8_t _network_join_waiting; ///< The number of clients waiting in uint32_t _network_join_bytes; ///< The number of bytes we already downloaded. uint32_t _network_join_bytes_total; ///< The total number of bytes to download. +/** Window showing the progress during joining. */ struct NetworkJoinStatusWindow : Window { - std::shared_ptr request{}; + std::shared_ptr request{}; ///< Callback to send the password request result to. + /** + * Create the window. + * @param desc The description of the window. + */ NetworkJoinStatusWindow(WindowDesc &desc) : Window(desc) { this->parent = FindWindowById(WC_NETWORK_WINDOW, WN_NETWORK_WINDOW_GAME); @@ -2126,6 +2194,7 @@ struct NetworkJoinStatusWindow : Window { } }; +/** Widgets and the structure of the NetworkJoinStatusWindow. */ static constexpr std::initializer_list _nested_network_join_status_window_widgets = { NWidget(WWT_CAPTION, COLOUR_GREY), SetStringTip(STR_NETWORK_CONNECTING_CAPTION, STR_TOOLTIP_WINDOW_TITLE_DRAG_THIS), NWidget(WWT_PANEL, COLOUR_GREY), @@ -2137,6 +2206,7 @@ static constexpr std::initializer_list _nested_network_join_status_ EndContainer(), }; +/** Description of the NetworkJoinStatusWindow. */ static WindowDesc _network_join_status_window_desc( WDP_CENTER, {}, 0, 0, WC_NETWORK_STATUS_WINDOW, WC_NONE, @@ -2144,12 +2214,17 @@ static WindowDesc _network_join_status_window_desc( _nested_network_join_status_window_widgets ); +/** Open the window showing the status of joining the server. */ void ShowJoinStatusWindow() { CloseWindowById(WC_NETWORK_STATUS_WINDOW, WN_NETWORK_STATUS_WINDOW_JOIN); new NetworkJoinStatusWindow(_network_join_status_window_desc); } +/** + * Update the NetworkJoinStatusWindow to start requesting the server password. + * @param request The callback for the reply to the request. + */ void ShowNetworkNeedPassword(std::shared_ptr request) { NetworkJoinStatusWindow *w = dynamic_cast(FindWindowById(WC_NETWORK_STATUS_WINDOW, WN_NETWORK_STATUS_WINDOW_JOIN)); @@ -2167,6 +2242,14 @@ struct NetworkAskRelayWindow : public Window { std::string relay_connection_string{}; ///< The relay server we want to connect to. std::string token{}; ///< The token for this connection. + /** + * Create the window. + * @param desc The description of the window. + * @param parent The parent of this window. + * @param server_connection_string The game server we want to connect to. + * @param relay_connection_string The relay server we want to connect to. + * @param token The token for this relay attempt. + */ NetworkAskRelayWindow(WindowDesc &desc, Window *parent, std::string_view server_connection_string, std::string &&relay_connection_string, std::string &&token) : Window(desc), server_connection_string(server_connection_string), @@ -2227,6 +2310,7 @@ struct NetworkAskRelayWindow : public Window { } }; +/** Widgets and the structure of the NetworkAskRelayWindow. */ static constexpr std::initializer_list _nested_network_ask_relay_widgets = { NWidget(NWID_HORIZONTAL), NWidget(WWT_CLOSEBOX, COLOUR_RED), @@ -2244,6 +2328,7 @@ static constexpr std::initializer_list _nested_network_ask_relay_wi EndContainer(), }; +/** Description of the NetworkAskRelayWindow. */ static WindowDesc _network_ask_relay_desc( WDP_CENTER, {}, 0, 0, WC_NETWORK_ASK_RELAY, WC_NONE, @@ -2269,6 +2354,11 @@ void ShowNetworkAskRelay(std::string_view server_connection_string, std::string * Window used for asking if the user wants to participate in the automated survey. */ struct NetworkAskSurveyWindow : public Window { + /** + * Create the window. + * @param desc The description of the window. + * @param parent The parent of this window. + */ NetworkAskSurveyWindow(WindowDesc &desc, Window *parent) : Window(desc) { @@ -2322,6 +2412,7 @@ struct NetworkAskSurveyWindow : public Window { } }; +/** Widgets and the structure of the NetworkAskSurveyWindow. */ static constexpr std::initializer_list _nested_network_ask_survey_widgets = { NWidget(NWID_HORIZONTAL), NWidget(WWT_CLOSEBOX, COLOUR_GREY), @@ -2342,6 +2433,7 @@ static constexpr std::initializer_list _nested_network_ask_survey_w EndContainer(), }; +/** Description of the NetworkAskSurveyWindow. */ static WindowDesc _network_ask_survey_desc( WDP_CENTER, {}, 0, 0, WC_NETWORK_ASK_SURVEY, WC_NONE, @@ -2367,6 +2459,11 @@ void ShowNetworkAskSurvey() struct SurveyResultTextfileWindow : public TextfileWindow { const GRFConfig *grf_config; ///< View the textfile of this GRFConfig. + /** + * Create the window. + * @param parent The parent for this window. + * @param file_type The type of file to show. + */ SurveyResultTextfileWindow(Window *parent, TextfileType file_type) : TextfileWindow(parent, file_type) { this->ConstructWindow(); @@ -2377,6 +2474,10 @@ struct SurveyResultTextfileWindow : public TextfileWindow { } }; +/** + * Show the surver results as a text file. + * @param parent The parent of the text file window. + */ void ShowSurveyResultTextfileWindow(Window *parent) { parent->CloseChildWindowById(WC_TEXTFILE, TFT_SURVEY_RESULT); diff --git a/src/network/network_gui.h b/src/network/network_gui.h index 2f4fde3f06..3e014f667a 100644 --- a/src/network/network_gui.h +++ b/src/network/network_gui.h @@ -17,7 +17,8 @@ #include "network_type.h" #include "network_gamelist.h" -void ShowNetworkNeedPassword(std::shared_ptr request); +class NetworkAuthenticationPasswordRequest; +void ShowNetworkNeedPassword(std::shared_ptr request); void ShowNetworkChatQueryWindow(NetworkChatDestinationType type, int dest); void ShowJoinStatusWindow(); void ShowNetworkGameWindow(); @@ -38,6 +39,7 @@ struct NetworkCompanyInfo : NetworkCompanyStats { std::string clients; ///< The clients that control this company (Name1, name2, ..) }; +/** Reasons to close the window that opts you in for relaying the network game. */ enum NetworkRelayWindowCloseData : uint8_t { NRWCD_UNHANDLED = 0, ///< Relay request is unhandled. NRWCD_HANDLED = 1, ///< Relay request is handled, either by user or by timeout. diff --git a/src/network/network_internal.h b/src/network/network_internal.h index efab17e6ae..9572e8775a 100644 --- a/src/network/network_internal.h +++ b/src/network/network_internal.h @@ -38,7 +38,7 @@ #define NETWORK_SEND_DOUBLE_SEED #endif /* RANDOM_DEBUG */ -typedef class ServerNetworkGameSocketHandler NetworkClientSocket; +using NetworkClientSocket = class ServerNetworkGameSocketHandler; ///< @copydoc ServerNetworkGameSocketHandler /** Status of the clients during joining. */ enum class NetworkJoinStatus : uint8_t { diff --git a/src/network/network_server.cpp b/src/network/network_server.cpp index 94be9c2a7a..ea46cbc9f3 100644 --- a/src/network/network_server.cpp +++ b/src/network/network_server.cpp @@ -52,7 +52,7 @@ static ClientID _network_client_id = CLIENT_ID_FIRST; static_assert(NetworkClientSocketPool::MAX_SIZE > MAX_CLIENTS); /** The pool with clients. */ -NetworkClientSocketPool _networkclientsocket_pool("NetworkClientSocket"); +NetworkClientSocketPool _networkclientsocket_pool{"NetworkClientSocket"}; INSTANTIATE_POOL_METHODS(NetworkClientSocket) /** Instantiate the listen sockets. */ @@ -539,6 +539,10 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::SendWait() return NETWORK_RECV_STATUS_OKAY; } +/** + * Find the next candidate for joining, and start the joining process for that client. + * @param ignore_cs A client to ignore while searching. + */ void ServerNetworkGameSocketHandler::CheckNextClientToSendMap(NetworkClientSocket *ignore_cs) { Debug(net, 9, "client[{}] CheckNextClientToSendMap()", this->client_id); @@ -978,6 +982,11 @@ NetworkRecvStatus ServerNetworkGameSocketHandler::Receive_CLIENT_IDENTIFY(Packet return this->SendNewGRFCheck(); } +/** + * Determine the #NetworkErrorCode for a failure of a given authentication method. + * @param method The method for which authentication failed. + * @return The appropriate #NetworkErrorCode. + */ static NetworkErrorCode GetErrorForAuthenticationMethod(NetworkAuthenticationMethod method) { switch (method) { diff --git a/src/network/network_server.h b/src/network/network_server.h index 75f13d5d99..506168224d 100644 --- a/src/network/network_server.h +++ b/src/network/network_server.h @@ -116,6 +116,11 @@ public: } std::string_view GetClientIP(); + + /** + * Get the public key of our peer. + * @return The public key of our client. + */ std::string_view GetPeerPublicKey() const { return this->peer_public_key; } static ServerNetworkGameSocketHandler *GetByClientID(ClientID client_id); diff --git a/src/network/network_stun.cpp b/src/network/network_stun.cpp index d4c4248cfc..b148bac5a1 100644 --- a/src/network/network_stun.cpp +++ b/src/network/network_stun.cpp @@ -18,9 +18,9 @@ /** Connect to the STUN server. */ class NetworkStunConnecter : public TCPConnecter { private: - ClientNetworkStunSocketHandler *stun_handler; - std::string token; - uint8_t family; + ClientNetworkStunSocketHandler *stun_handler; ///< The STUN handler for callbacks. + std::string token; ///< The (server) token for this action. + uint8_t family; ///< The IP-family to connect with. public: /** diff --git a/src/network/network_survey.h b/src/network/network_survey.h index 9628bb196f..8b0a8919d1 100644 --- a/src/network/network_survey.h +++ b/src/network/network_survey.h @@ -35,6 +35,10 @@ public: void Transmit(Reason reason, bool blocking = false); std::string CreatePayload(Reason reason, bool for_preview = false); + /** + * Check whether a survey is possible. + * @return \c true. + */ constexpr static bool IsSurveyPossible() { return true; @@ -46,6 +50,7 @@ private: std::condition_variable transmitted_cv; ///< Condition variable to inform changes to transmitted. }; +/** The handler for sending surveys for statistics. */ extern NetworkSurveyHandler _survey; #endif /* NETWORK_SURVEY_H */ diff --git a/src/network/network_turn.cpp b/src/network/network_turn.cpp index bc57856fa9..4ea94a8d22 100644 --- a/src/network/network_turn.cpp +++ b/src/network/network_turn.cpp @@ -18,7 +18,7 @@ /** Connect to the TURN server. */ class NetworkTurnConnecter : public TCPConnecter { private: - ClientNetworkTurnSocketHandler *handler; + ClientNetworkTurnSocketHandler *handler; ///< The callback for this attempt. public: /** @@ -107,6 +107,7 @@ void ClientNetworkTurnSocketHandler::Connect() return turn_handler; } +/** Callback when we were unable to connect. */ void ClientNetworkTurnSocketHandler::ConnectFailure() { _network_coordinator_client.ConnectFailure(this->token, this->tracking_number); diff --git a/src/network/network_turn.h b/src/network/network_turn.h index 4b5c869fb6..88765af1cb 100644 --- a/src/network/network_turn.h +++ b/src/network/network_turn.h @@ -27,6 +27,12 @@ public: std::shared_ptr connecter{}; ///< Connecter instance. bool connect_started = false; ///< Whether we started the connection. + /** + * Create this handler. + * @param token The unique token of the connection. + * @param tracking_number Tracking number for the connection, from the TURN server. + * @param connection_string The address to connect to. + */ ClientNetworkTurnSocketHandler(std::string_view token, uint8_t tracking_number, std::string_view connection_string) : token(token), tracking_number(tracking_number), connection_string(connection_string) {} NetworkRecvStatus CloseConnection(bool error = true) override; diff --git a/src/network/network_udp.cpp b/src/network/network_udp.cpp index 858afbb9ad..66e6711406 100644 --- a/src/network/network_udp.cpp +++ b/src/network/network_udp.cpp @@ -30,14 +30,20 @@ struct UDPSocket { const std::string name; ///< The name of the socket. std::unique_ptr socket = nullptr; ///< The actual socket, which may be nullptr when not initialized yet. + /** + * Create this socket. + * @param name The name of the socket for logging purposes. + */ UDPSocket(const std::string &name) : name(name) {} + /** @copydoc NetworkUDPSocketHandler::CloseSocket */ void CloseSocket() { this->socket->CloseSocket(); this->socket = nullptr; } + /** @copydoc NetworkUDPSocketHandler::ReceivePackets */ void ReceivePackets() { this->socket->ReceivePackets();