First commit.

2 files changed, 77 insertions, 0 deletions

diff --git a/doc/API.md b/doc/API.md
new file mode 100644
index 0000000..bee7c42
--- /dev/null
+++ b/doc/API.md
@@ -0,0 +1,32 @@
+
+## Extended Ban Mod API
+
+### ban_player
+
+`xban.ban_player(player_or_ip, source, expires, reason)`
+
+Ban a player and all of his/her alternative names and IPs.
+
+#### Arguments:
+
+* `player_or_ip` - Player to search for and ban. See note 1 below.
+* `source` - Source of the ban. See note 2 below.
+* `expires` - Time at which the ban expires. If nil, ban is permanent.
+* `reason` - Reason for ban.
+
+### unban_player
+
+`xban.unban_player(player_or_ip, source)`
+
+Unban a player and all of his/her alternative names and IPs.
+
+#### Arguments:
+
+* `player_or_ip` - Player to search for and unban.
+* `source` - Source of the ban. See note 2 below.
+
+### Notes
+
+* 1: If player is currently online, all his accounts are kicked.
+* 2: Mods using the xban API are advised to use the `"modname:source"`
+format for `source` (for example: `"anticheat:main"`).
diff --git a/doc/dbformat.txt b/doc/dbformat.txt
new file mode 100644
index 0000000..71b25a5
--- /dev/null
+++ b/doc/dbformat.txt
@@ -0,0 +1,45 @@
+
+Database is a regular Lua script that returns a table.
+
+Table has a single named field `timestamp' containing the time_t the
+DB was last saved. It's not used in the mod and is only meant for
+external use (I don't find filesystem timestamps too reliable).
+
+Next is a simple array (number indices) of entries.
+
+Each entry contains following fields:
+
+[1] = {
+	-- Names/IPs associated with this entry
+	names = {
+		["foo"] = true,
+		["bar"] = true,
+		["123.45.67.89"] = true,
+	},
+	banned = true,      -- Whether this user is banned
+	                    -- Other fields do not apply if false
+	time = 12341234,    -- Time of last ban (*1)
+	expires = 43214321  -- Time at which ban expires (*2)
+	                    -- If nil, permanent ban
+	reason = "asdf",    -- Reason for ban
+	source = "qwerty",  -- Source of ban (*2)
+	record = {
+		[1] = {
+			source = "asdf",
+			reason = "qwerty",
+			time = 12341234,
+			expires = 43214321,
+		},
+		[1] = {
+			source = "asdf",
+			reason = "Unbanned",  -- When unbanned
+			time = 12341234,
+		},
+	},
+}
+
+Notes:
+(*1)  All times are expressed in whatever unit `os.time()' uses
+      (`time_t' on most (all?) systems).
+(*2)  Mods using the xban API are advised to use the "modname:source"
+      format for `source' (for example: "anticheat:main").