diff --git a/TShockAPI/DB/UserManager.cs b/TShockAPI/DB/UserManager.cs index a899015e..56fcd056 100755 --- a/TShockAPI/DB/UserManager.cs +++ b/TShockAPI/DB/UserManager.cs @@ -29,28 +29,33 @@ using System.Security.Cryptography; namespace TShockAPI.DB { + /// UserManager - Methods for dealing with database users and other user functionality within TShock. public class UserManager { + /// database - The database object to use for connections. private IDbConnection database; + /// UserManager - Creates a UserManager object. During instantiation, this method will verify the table structure against the format below. + /// db - The database to connect to. + /// A UserManager object. public UserManager(IDbConnection db) { database = db; var table = new SqlTable("Users", - new SqlColumn("ID", MySqlDbType.Int32) {Primary = true, AutoIncrement = true}, - new SqlColumn("Username", MySqlDbType.VarChar, 32) {Unique = true}, - new SqlColumn("Password", MySqlDbType.VarChar, 128), - new SqlColumn("UUID", MySqlDbType.VarChar, 128), - new SqlColumn("Usergroup", MySqlDbType.Text), - new SqlColumn("Registered", MySqlDbType.Text), - new SqlColumn("LastAccessed", MySqlDbType.Text), - new SqlColumn("KnownIPs", MySqlDbType.Text) + new SqlColumn("ID", MySqlDbType.Int32) {Primary = true, AutoIncrement = true}, + new SqlColumn("Username", MySqlDbType.VarChar, 32) {Unique = true}, + new SqlColumn("Password", MySqlDbType.VarChar, 128), + new SqlColumn("UUID", MySqlDbType.VarChar, 128), + new SqlColumn("Usergroup", MySqlDbType.Text), + new SqlColumn("Registered", MySqlDbType.Text), + new SqlColumn("LastAccessed", MySqlDbType.Text), + new SqlColumn("KnownIPs", MySqlDbType.Text) ); var creator = new SqlTableCreator(db, - db.GetSqlType() == SqlType.Sqlite - ? (IQueryBuilder) new SqliteQueryCreator() - : new MysqlQueryCreator()); + db.GetSqlType() == SqlType.Sqlite + ? (IQueryBuilder) new SqliteQueryCreator() + : new MysqlQueryCreator()); creator.EnsureTableStructure(table); } @@ -67,7 +72,7 @@ namespace TShockAPI.DB try { ret = database.Query("INSERT INTO Users (Username, Password, UUID, UserGroup, Registered) VALUES (@0, @1, @2, @3, @4);", user.Name, - user.Password, user.UUID, user.Group, DateTime.UtcNow.ToString("s")); + user.Password, user.UUID, user.Group, DateTime.UtcNow.ToString("s")); } catch (Exception ex) { @@ -173,19 +178,24 @@ namespace TShockAPI.DB } } - public void UpdateLogin(User user) - { - try - { - if (database.Query("UPDATE Users SET LastAccessed = @0, KnownIps = @1 WHERE Username = @2;", DateTime.UtcNow.ToString("s"), user.KnownIps, user.Name) == 0) - throw new UserNotExistException(user.Name); - } - catch (Exception ex) - { - throw new UserManagerException("UpdateLogin SQL returned an error", ex); - } - } + /// UpdateLogin - Updates the last accessed time for a database user to the current time. + /// user - The user object to modify. + public void UpdateLogin(User user) + { + try + { + if (database.Query("UPDATE Users SET LastAccessed = @0, KnownIps = @1 WHERE Username = @2;", DateTime.UtcNow.ToString("s"), user.KnownIps, user.Name) == 0) + throw new UserNotExistException(user.Name); + } + catch (Exception ex) + { + throw new UserManagerException("UpdateLogin SQL returned an error", ex); + } + } + /// GetUserID - Gets the database ID of a given user object from the database. + /// username - The username of the user to query for. + /// int - The user's ID public int GetUserID(string username) { try @@ -205,6 +215,9 @@ namespace TShockAPI.DB return -1; } + /// GetUserByName - Gets a user object by name. + /// name - The user's name. + /// User - The user object returned from the search. public User GetUserByName(string name) { try @@ -217,6 +230,9 @@ namespace TShockAPI.DB } } + /// GetUserByID - Gets a user object by their user ID. + /// id - The user's ID. + /// User - The user object returned from the search. public User GetUserByID(int id) { try @@ -229,6 +245,9 @@ namespace TShockAPI.DB } } + /// GetUser - Gets a user object by a user object. + /// user - The user object to search by. + /// User - The user object that is returned from the search. public User GetUser(User user) { bool multiple = false; @@ -272,6 +291,8 @@ namespace TShockAPI.DB throw new UserNotExistException(user.Name); } + /// GetUsers - Gets all users from the database. + /// List - The users from the database. public List GetUsers() { try @@ -293,31 +314,60 @@ namespace TShockAPI.DB return null; } + /// LoadUserFromResult - Fills out the fields of a User object with the results from a QueryResult object. + /// user - The user to add data to. + /// result - The QueryResult object to add data from. + /// User - The 'filled out' user object. private User LoadUserFromResult(User user, QueryResult result) { user.ID = result.Get("ID"); user.Group = result.Get("Usergroup"); user.Password = result.Get("Password"); - user.UUID = result.Get("UUID"); + user.UUID = result.Get("UUID"); user.Name = result.Get("Username"); user.Registered = result.Get("Registered"); - user.LastAccessed = result.Get("LastAccessed"); - user.KnownIps = result.Get("KnownIps"); + user.LastAccessed = result.Get("LastAccessed"); + user.KnownIps = result.Get("KnownIps"); return user; } } + /// User - A database user. public class User { + /// ID - The database ID of the user. public int ID { get; set; } + + /// Name - The user's name. public string Name { get; set; } + + /// Password - The hashed password for the user. public string Password { get; internal set; } + + /// UUID - The user's saved Univerally Unique Identifier token. public string UUID { get; set; } + + /// Group - The group object that the user is a part of. public string Group { get; set; } + + /// Registered - The unix epoch corresponding to the registration date of the user. public string Registered { get; set; } + + /// LastAccessed - The unix epoch corresponding to the last access date of the user. public string LastAccessed { get; set; } + + /// KnownIps - A JSON serialized list of known IP addresses for a user. public string KnownIps { get; set; } + /// User - Constructor for the user object, assuming you define everything yourself. + /// name - The user's name. + /// pass - The user's password hash. + /// uuid - The user's UUID. + /// group - The user's group name. + /// registered - The unix epoch for the registration date. + /// last - The unix epoch for the last access date. + /// known - The known IPs for the user, serialized as a JSON object + /// A completed user object. public User(string name, string pass, string uuid, string group, string registered, string last, string known) { Name = name; @@ -329,6 +379,8 @@ namespace TShockAPI.DB KnownIps = known; } + /// User - Default constructor for a user object; holds no data. + /// A user object. public User() { Name = ""; @@ -517,41 +569,61 @@ namespace TShockAPI.DB } + /// UserManagerException - An exception generated by the user manager. [Serializable] public class UserManagerException : Exception { + /// UserManagerException - Creates a new UserManagerException object. + /// message - The message for the object. + /// public - a new UserManagerException object. public UserManagerException(string message) : base(message) { } + /// UserManagerException - Creates a new UserManagerObject with an internal exception. + /// message - The message for the object. + /// inner - The inner exception for the object. + /// public - a nwe UserManagerException with a defined inner exception. public UserManagerException(string message, Exception inner) : base(message, inner) { } } + /// UserExistsException - A UserExistsException object, used when a user already exists when attempting to create a new one. [Serializable] public class UserExistsException : UserManagerException { + /// UserExistsException - Creates a new UserExistsException object. + /// name - The name of the user that already exists. + /// public - a UserExistsException object with the user's name passed in the message. public UserExistsException(string name) : base("User '" + name + "' already exists") { } } + /// UserNotExistException - A UserNotExistException, used when a user does not exist and a query failed as a result of it. [Serializable] public class UserNotExistException : UserManagerException { + /// UserNotExistException - Creates a new UserNotExistException object, with the user's name in the message. + /// name - The user's name to be pasesd in the message. + /// public - a new UserNotExistException object with a message containing the user's name that does not exist. public UserNotExistException(string name) : base("User '" + name + "' does not exist") { } } + /// GroupNotExistsException - A GroupNotExistsException, used when a group does not exist. [Serializable] public class GroupNotExistsException : UserManagerException { + /// GroupNotExistsException - Creates a new GroupNotExistsException object with the group's name in the message. + /// group - The group name. + /// public - a new GroupNotExistsException with the group that does not exist's name in the message. public GroupNotExistsException(string group) : base("Group '" + group + "' does not exist") { diff --git a/TShockAPI/Utils.cs b/TShockAPI/Utils.cs index 8e4c7278..cad13756 100644 --- a/TShockAPI/Utils.cs +++ b/TShockAPI/Utils.cs @@ -46,13 +46,19 @@ namespace TShockAPI /// private const int LastItemPrefix = 83; - // Utils is a Singleton + /// instance - an instance of the utils class private static readonly Utils instance = new Utils(); + + /// Utils - Creates a utilities object. private Utils() {} + + /// Instance - An instance of the utils class. + /// value - the Utils instance public static Utils Instance { get { return instance; } } + /// Random - An instance of random for generating random data. + [Obsolete("Please create your own random objects; this will be removed in the next version of TShock.")] public Random Random = new Random(); - //private static List groups = new List(); /// /// Provides the real IP address from a RemoteEndPoint string that contains a port and an IP @@ -130,13 +136,18 @@ namespace TShockAPI } /// - /// Saves the map data + /// Saves the map data by calling the SaveManager and instructing it to save the world. /// public void SaveWorld() { SaveManager.Instance.SaveWorld(); } + /// Broadcast - Broadcasts a message to all players on the server, as well as the server console, and the logs. + /// msg - The message to send + /// red - The amount of red (0-255) in the color for supported destinations. + /// green - The amount of green (0-255) in the color for supported destinations. + /// blue - The amount of blue (0-255) in the color for the supported destinations. public void Broadcast(string msg, byte red, byte green, byte blue) { TSPlayer.All.SendMessage(msg, red, green, blue); @@ -144,19 +155,22 @@ namespace TShockAPI TShock.Log.Info(string.Format("Broadcast: {0}", msg)); } + /// >Broadcast - Broadcasts a message to all players on the server, as well as the server console, and the logs. + /// msg - The message to send + /// color - The color object for supported destinations. public void Broadcast(string msg, Color color) { Broadcast(msg, color.R, color.G, color.B); } /// - /// Broadcasts a message from a player, not TShock + /// Broadcasts a message from a Terraria playerplayer, not TShock /// - /// TSPlayer ply - the player that will send the packet - /// string msg - the message - /// r - /// g - /// b + /// ply - the Terraria player index that will send the packet + /// msg - The message to send + /// red - The amount of red (0-255) in the color for supported destinations. + /// green - The amount of green (0-255) in the color for supported destinations. + /// blue - The amount of blue (0-255) in the color for the supported destinations. public void Broadcast(int ply, string msg, byte red, byte green, byte blue) { TSPlayer.All.SendMessageFromPlayer(msg, red, green, blue, ply); @@ -183,9 +197,9 @@ namespace TShockAPI } /// - /// The number of active players on the server. + /// Gets the number of active players on the server. /// - /// int playerCount + /// The number of active players on the server. public int ActivePlayers() { return Main.player.Where(p => null != p && p.active).Count(); @@ -195,7 +209,7 @@ namespace TShockAPI /// Finds a TSPlayer based on name or ID /// /// Player name or ID - /// + /// A list of matching players public List FindPlayer(string plr) { var found = new List(); @@ -249,9 +263,9 @@ namespace TShockAPI tileY = startTileY; break; } - - tileX = startTileX + Random.Next(tileXRange*-1, tileXRange); - tileY = startTileY + Random.Next(tileYRange*-1, tileYRange); + Random r = new Random(); + tileX = startTileX + r.Next(tileXRange*-1, tileXRange); + tileY = startTileY + r.Next(tileYRange*-1, tileYRange); j++; } while (TilePlacementValid(tileX, tileY) && TileSolid(tileX, tileY)); } @@ -611,6 +625,10 @@ namespace TShockAPI return false; } + /// HasBanExpired - Returns whether or not a ban has expired or not. + /// ban - The ban object to check. + /// byName - Defines whether or not the ban should be checked by name. + /// bool - True if the ban has expired. public bool HasBanExpired(Ban ban, bool byName = false) { DateTime exp; @@ -903,6 +921,9 @@ namespace TShockAPI } } + /// EncodeColor - Encodes a color as an int. + /// color - The color to encode + /// int? - The encoded color public int? EncodeColor(Color? color) { if (color == null) @@ -911,6 +932,9 @@ namespace TShockAPI return BitConverter.ToInt32(new[] { color.Value.R, color.Value.G, color.Value.B, color.Value.A }, 0); } + /// DecodeColor - Decodes a color encoded by the EncodeColor function. + /// encodedColor - The encoded color + /// Color? - The decoded color public Color? DecodeColor(int? encodedColor) { if (encodedColor == null) @@ -920,6 +944,9 @@ namespace TShockAPI return new Color(data[0], data[1], data[2], data[3]); } + /// EncodeBitsByte - Encodes a BitsByte as a byte. + /// bitsByte - The BitsByte object + /// byte? - The converted byte public byte? EncodeBitsByte(BitsByte? bitsByte) { if (bitsByte == null) @@ -933,6 +960,9 @@ namespace TShockAPI return result; } + /// DecodeBitsByte - Decodes a bitsbyte from an int. + /// encodedBitsByte - The encoded bitsbyte object. + /// BitsByte? - The decoded bitsbyte object public BitsByte? DecodeBitsByte(int? encodedBitsByte) { if (encodedBitsByte == null) @@ -945,6 +975,9 @@ namespace TShockAPI return result; } + /// GetResponseNoException - Gets a web response without generating an exception. + /// req - The request to send. + /// HttpWebResponse - The response object. public HttpWebResponse GetResponseNoException(HttpWebRequest req) { try