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