diff --git a/doxygen/akashi.qch b/doxygen/akashi.qch index 4c5eed5..4582a17 100644 Binary files a/doxygen/akashi.qch and b/doxygen/akashi.qch differ diff --git a/include/advertiser.h b/include/advertiser.h index 071be89..bdd834c 100644 --- a/include/advertiser.h +++ b/include/advertiser.h @@ -96,10 +96,7 @@ class Advertiser : public QObject { QString ip; /** - * @copydoc ConfigManager::server_settings::port - * - * @bug Because of a typo in the code, this also replaces #local_port, thus clients will have to attempt - * to connect through the same port as the connection is established to the master server. + * @copydoc ConfigManager::server_settings::ms_port */ int port; @@ -109,7 +106,7 @@ class Advertiser : public QObject { int ws_port; /** - * @copydoc ConfigManager::server_settings::local_port + * @copydoc ConfigManager::server_settings::port * * @bug See #port. */ diff --git a/include/aoclient.h b/include/aoclient.h index a5442b9..effbfcf 100644 --- a/include/aoclient.h +++ b/include/aoclient.h @@ -70,6 +70,10 @@ class AOClient : public QObject { * @see #ipid */ QString getIpid(); + + /** + * @brief Calculates the client's IPID based on a hashed version of its IP. + */ void calculateIpid(); /** @@ -146,6 +150,9 @@ class AOClient : public QObject { */ bool global_enabled = true; + /** + * @brief If true, the client may not use in-character chat. + */ bool is_muted = false; /** @@ -189,8 +196,19 @@ class AOClient : public QObject { {"SUPER", ~0ULL }, }; + /** + * @brief If true, the client's in-character messages will have their word order randomised. + */ bool is_shaken; + + /** + * @brief If true, the client's in-character messages will have their vowels (English alphabet only) removed. + */ bool is_disemvoweled; + + /** + * @brief If true, the client's in-character messages will be overwritten by a randomly picked predetermined message. + */ bool is_gimped; public slots: @@ -602,7 +620,25 @@ class AOClient : public QObject { * @iscommand */ void cmdHelp(int argc, QStringList argv); + + /** + * @brief Gets or sets the server's Message Of The Day. + * + * @details If called without arguments, gets the MOTD. + * + * If it has any number of arguments, it is set as the **MOTD**. + * + * @iscommand + */ void cmdMOTD(int argc, QStringList argv); + + /** + * @brief Gives a very brief description of Akashi. + * + * @details No arguments. + * + * @iscommand + */ void cmdAbout(int argc, QStringList argv); /** @@ -649,6 +685,14 @@ class AOClient : public QObject { * @iscommand */ void cmdAddUser(int argc, QStringList argv); + + /** + * @brief Removes a user from the moderators in `"advanced"` authorisation type. + * + * @details Takes the **targer user's name** as the argument. + * + * @iscommand + */ void cmdRemoveUser(int argc, QStringList argv); /** @@ -887,8 +931,14 @@ class AOClient : public QObject { * @brief Bans a client from the server, forcibly severing its connection to the server, * and disallowing their return. * - * @details The first argument is the **target's IPID**, while the remaining arguments are the **reason** - * the client was banned. Both arguments are mandatory. + * @details The first argument is the **target's IPID**, the second is the **reason** why the client + * was banned, the third is the **duration**. + * + * Both the reason and the duration must be in quotation marks. + * + * The duration can be `"perma"`, meaning a forever ban, otherwise, it must be given in the format of `"YYyWWwDDdHHhMMmSSs"` to + * mean a YY years, WW weeks, DD days, HH hours, MM minutes and SS seconds long ban. Any of these may be left out, for example, + * `"1h30m"` for a 1.5 hour long ban. * * Besides banning, this command kicks all clients having the given IPID, * thus a multiclienting user will have all their clients be kicked from the server. @@ -899,6 +949,14 @@ class AOClient : public QObject { * @iscommand */ void cmdBan(int argc, QStringList argv); + + /** + * @brief Removes a ban from the database. + * + * @details Takes a single argument, the **ID** of the ban. + * + * @iscommand + */ void cmdUnBan(int argc, QStringList argv); /** @@ -913,11 +971,67 @@ class AOClient : public QObject { * @iscommand */ void cmdKick(int argc, QStringList argv); + + /** + * @brief Sends out a decorated global message, for announcements. + * + * @details The arguments are **the message** that the client wants to send. + * + * @iscommand + * + * @see AOClient::cmdG() + */ void cmdAnnounce(int argc, QStringList argv); + + /** + * @brief Sends a message in the server-wide, moderator only chat. + * + * @details The arguments are **the message** that the client wants to send. + * + * @iscommand + */ void cmdM(int argc, QStringList argv); + + /** + * @brief Sends out a global message that is marked with an `[M]` to mean it is coming from a moderator. + * + * @details The arguments are **the message** that the client wants to send. + * + * @iscommand + * + * @see AOClient::cmdG() + */ void cmdGM(int argc, QStringList argv); + + /** + * @brief Mutes a client. + * + * @details The only argument is the **target client's user ID**. + * + * @iscommand + * + * @see #is_muted + */ void cmdMute(int argc, QStringList argv); + + /** + * @brief Removes the muted status a client. + * + * @details The only argument is the **target client's user ID**. + * + * @iscommand + * + * @see #is_muted + */ void cmdUnmute(int argc, QStringList argv); + + /** + * @brief Lists the last five bans made on the server. + * + * @details No arguments. + * + * @iscommand + */ void cmdBans(int argc, QStringList argv); ///@} @@ -1031,6 +1145,14 @@ class AOClient : public QObject { * @see AreaData::EvidenceMod */ void cmdEvidenceMod(int argc, QStringList argv); + + /** + * @brief Changes the subtheme of the clients in the current area. + * + * @details The only argument is the **name of the subtheme**. Reloading is always forced. + * + * @iscommand + */ void cmdSubTheme(int argc, QStringList argv); ///@} @@ -1179,6 +1301,26 @@ class AOClient : public QObject { * @param Type The type of the dice-rolling being done. */ void diceThrower(int argc, QStringList argv, RollType Type); + + /** + * @brief Interprets an expression of time into amount of seconds. + * + * @param input A string in the format of `"XXyXXwXXdXXhXXmXXs"`, where every `XX` is some integer. + * There is no limit on the length of the integers, the `XX` text is just a placeholder, and is not intended to + * indicate a limit of two digits maximum. + * + * The string gets interpreted as follows: + * * `XXy` is parsed into `XX` amount of years, + * * `XXw` is parsed into `XX` amount of weeks, + * * `XXd` is parsed into `XX` amount of days, + * * `XXh` is parsed into `XX` amount of hours, + * * `XXm` is parsed into `XX` amount of minutes, and + * * `XXs` is parsed into `XX` amount of seconds. + * + * Any of these may be left out, but the order must be kept (i.e., `"10s5y"` is a malformed text). + * + * @return The parsed text, converted into their respective durations, summed up, then converted into seconds. + */ long long parseTime(QString input); ///@} diff --git a/include/area_data.h b/include/area_data.h index e40cb90..6ec803a 100644 --- a/include/area_data.h +++ b/include/area_data.h @@ -35,6 +35,13 @@ class Logger; class AreaData : public QObject { Q_OBJECT public: + /** + * @brief Constructor for the AreaData class. + * + * @param p_name The name of the area. This must be in the format of `"X:YYYYYY"`, where `X` is an integer, + * and `YYYYYY` is the actual name of the area. + * @param p_index The index of the area in the area list. + */ AreaData(QString p_name, int p_index); /** @@ -61,6 +68,9 @@ class AreaData : public QObject { */ int index; + /** + * @brief A list of the character IDs of all characters taken. + */ QList characters_taken; /** diff --git a/include/db_manager.h b/include/db_manager.h index 4ecbe2b..575df07 100644 --- a/include/db_manager.h +++ b/include/db_manager.h @@ -82,30 +82,73 @@ public: QString getBanReason(QHostAddress ip); /** - * @brief Overloaded function for getBanReason(QHostAddress). Returns based on HDID instead of IP. - * - * @param hdid The hardware ID whose ban reason needs to be returned. - * - * @return The ban reason if the hardware ID is actually banned, - * or `"Ban reason not found."` if the hardware ID is not actually banned. + * @overload */ QString getBanReason(QString hdid); - long long getBanDuration(QString hdid); + + /** + * @brief Returns the reason the given IP address was banned with. + * + * @param ip The IP address whose ban duration to get. + * + * @return The ban duration if the IP address is actually banned, + * or `-1` if the IP address is not actually banned. + */ long long getBanDuration(QHostAddress ip); - int getBanID(QString hdid); + + /** + * @overload + */ + long long getBanDuration(QString hdid); + + /** + * @brief Gets the ID number of a given ban. + * + * @param ip The IP address whose associated ban's ID we need. + * + * @return The ID of the ban if the IP address is actually banned, + * or `-1` if the IP address is not actually banned. + */ int getBanID(QHostAddress ip); + /** + * @overload + */ + int getBanID(QString hdid); + + /** + * @brief Details about a ban. + */ struct BanInfo { - QString ipid; - QHostAddress ip; - QString hdid; - unsigned long time; - QString reason; - long long duration; + QString ipid; //!< The banned user's IPID. + QHostAddress ip; //!< The banned user's IP. + QString hdid; //!< The banned user's hardware ID. + unsigned long time; //!< The time the ban was registered. + QString reason; //!< The reason given for the ban by the moderator who registered it. + long long duration; //!< The duration of the ban, in seconds. }; + + /** + * @brief Gets the last five bans made on the server. + * + * @return See brief description. + */ QList getRecentBans(); + /** + * @brief Registers a ban into the database. + * + * @param ban The details of the ban. + */ void addBan(BanInfo ban); + + /** + * @brief Sets the duration of a given ban to 0, effectively removing the ban the associated user. + * + * @param id The ID of the ban to invalidate. + * + * @return False if no such ban exists, true if the invalidation was successful. + */ bool invalidateBan(int id); /** @@ -122,6 +165,14 @@ public: * @see AOClient::ACLFlags for the potential special permissions a user may have. */ bool createUser(QString username, QString salt, QString password, unsigned long long acl); + + /** + * @brief Deletes an authorised user from the database. + * + * @param username The username whose associated user to delete. + * + * @return False if the user didn't even exist, true if the user was successfully deleted. + */ bool deleteUser(QString username); /** diff --git a/include/server.h b/include/server.h index 4212868..96cba1a 100644 --- a/include/server.h +++ b/include/server.h @@ -77,9 +77,18 @@ class Server : public QObject { * @param ipid The IPID to look for. * * @return A pointer to the client if found, a nullpointer if not. + * + * @see Server::getClientsByIpid() to get all clients ran by the same user. */ AOClient* getClient(QString ipid); + /** + * @brief Gets a list of pointers to all clients with the given IPID. + * + * @param ipid The IPID to look for. + * + * @return A list of clients whose IPID match. List may be empty. + */ QList getClientsByIpid(QString ipid); /** @@ -196,6 +205,10 @@ class Server : public QObject { * @note Unused. getServerName() serves its purpose instead. */ QString server_name; + + /** + * @brief The Message Of The Day of the server, shown upon entry to the server and on request. + */ QString MOTD; /**