Add support for banning clients by their myTeamSpeak ID

Author: rogermb

src/main/java/com/github/theholywaffle/teamspeak3/TS3Api.java

@@ -82,26 +82,27 @@ public TS3Api(TS3ApiAsync asyncApi) {
 	}
 
 	/**
-	 * Adds a new ban entry. At least one of the parameters {@code ip}, {@code name} or {@code uid} needs to be not null.
-	 * Returns the ID of the newly created ban.
+	 * Adds a new ban entry. At least one of the parameters {@code ip}, {@code name} or {@code uid} needs to be non-null.
+	 * Returns the ID of the newly created ban entry.
 	 *
 	 * @param ip
-	 * 		a RegEx pattern to match a client's IP against, can be null
+	 * 		a RegEx pattern to match a client's IP against, can be {@code null}
 	 * @param name
-	 * 		a RegEx pattern to match a client's name against, can be null
+	 * 		a RegEx pattern to match a client's name against, can be {@code null}
 	 * @param uid
-	 * 		the unique identifier of a client, can be null
+	 * 		the unique identifier of a client, can be {@code null}
 	 * @param timeInSeconds
 	 * 		the duration of the ban in seconds. 0 equals a permanent ban
 	 * @param reason
-	 * 		the reason for the ban, can be null
+	 * 		the reason for the ban, can be {@code null}
 	 *
 	 * @return the ID of the newly created ban entry
 	 *
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails
 	 * @querycommands 1
 	 * @see Pattern RegEx Pattern
+	 * @see #addBan(String, String, String, String, long, String)
 	 * @see Client#getId()
 	 * @see Client#getUniqueIdentifier()
 	 * @see ClientInfo#getIp()
@@ -110,6 +111,41 @@ public int addBan(String ip, String name, String uid, long timeInSeconds, String
 		return asyncApi.addBan(ip, name, uid, timeInSeconds, reason).getUninterruptibly();
 	}
 
+	/**
+	 * Adds a new ban entry. At least one of the parameters {@code ip}, {@code name}, {@code uid}, or
+	 * {@code myTSId} needs to be non-null. Returns the ID of the newly created ban entry.
+	 * <p>
+	 * Note that creating a ban entry for the {@code "empty"} "myTeamSpeak" ID will ban all clients who
+	 * don't have a linked "myTeamSpeak" account.
+	 * </p>
+	 *
+	 * @param ip
+	 * 		a RegEx pattern to match a client's IP against, can be {@code null}
+	 * @param name
+	 * 		a RegEx pattern to match a client's name against, can be {@code null}
+	 * @param uid
+	 * 		the unique identifier of a client, can be {@code null}
+	 * @param myTSId
+	 * 		the "myTeamSpeak" ID of a client, the string {@code "empty"}, or {@code null}
+	 * @param timeInSeconds
+	 * 		the duration of the ban in seconds. 0 equals a permanent ban
+	 * @param reason
+	 * 		the reason for the ban, can be {@code null}
+	 *
+	 * @return the ID of the newly created ban entry
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see Pattern RegEx Pattern
+	 * @see Client#getId()
+	 * @see Client#getUniqueIdentifier()
+	 * @see ClientInfo#getIp()
+	 */
+	public int addBan(String ip, String name, String uid, String myTSId, long timeInSeconds, String reason) {
+		return asyncApi.addBan(ip, name, uid, myTSId, timeInSeconds, reason).getUninterruptibly();
+	}
+
 	/**
 	 * Adds a specified permission to a client in a specific channel.
 	 *
@@ -463,8 +499,9 @@ public void addTS3Listeners(TS3Listener... listeners) {
 	/**
 	 * Bans a client with a given client ID for a given time.
 	 * <p>
-	 * Please note that this will create two separate ban rules,
-	 * one for the targeted client's IP address and their unique identifier.
+	 * Please note that this will create 2 or 3 separate ban rules,
+	 * one for the targeted client's IP address, one for their unique identifier,
+	 * and potentially one more for their "myTeamSpeak" ID.
 	 * </p><p>
 	 * <i>Exception:</i> If the banned client connects via a loopback address
 	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created
@@ -476,7 +513,7 @@ public void addTS3Listeners(TS3Listener... listeners) {
 	 * @param timeInSeconds
 	 * 		the duration of the ban in seconds. 0 equals a permanent ban
 	 *
-	 * @return an array containing the IDs of the first and the second ban entry
+	 * @return an array containing the IDs of the created ban entries
 	 *
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails

src/main/java/com/github/theholywaffle/teamspeak3/TS3ApiAsync.java

@@ -95,32 +95,68 @@ public TS3ApiAsync(TS3Query query) {
 	}
 
 	/**
-	 * Adds a new ban entry. At least one of the parameters {@code ip}, {@code name} or {@code uid} needs to be not null.
-	 * Returns the ID of the newly created ban.
+	 * Adds a new ban entry. At least one of the parameters {@code ip}, {@code name} or {@code uid} needs to be non-null.
+	 * Returns the ID of the newly created ban entry.
 	 *
 	 * @param ip
-	 * 		a RegEx pattern to match a client's IP against, can be null
+	 * 		a RegEx pattern to match a client's IP against, can be {@code null}
 	 * @param name
-	 * 		a RegEx pattern to match a client's name against, can be null
+	 * 		a RegEx pattern to match a client's name against, can be {@code null}
 	 * @param uid
-	 * 		the unique identifier of a client, can be null
+	 * 		the unique identifier of a client, can be {@code null}
 	 * @param timeInSeconds
 	 * 		the duration of the ban in seconds. 0 equals a permanent ban
 	 * @param reason
-	 * 		the reason for the ban, can be null
+	 * 		the reason for the ban, can be {@code null}
 	 *
 	 * @return the ID of the newly created ban entry
 	 *
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails
 	 * @querycommands 1
 	 * @see Pattern RegEx Pattern
+	 * @see #addBan(String, String, String, String, long, String)
 	 * @see Client#getId()
 	 * @see Client#getUniqueIdentifier()
 	 * @see ClientInfo#getIp()
 	 */
 	public CommandFuture<Integer> addBan(String ip, String name, String uid, long timeInSeconds, String reason) {
-		Command cmd = BanCommands.banAdd(ip, name, uid, timeInSeconds, reason);
+		return addBan(ip, name, uid, null, timeInSeconds, reason);
+	}
+
+	/**
+	 * Adds a new ban entry. At least one of the parameters {@code ip}, {@code name}, {@code uid}, or
+	 * {@code myTSId} needs to be non-null. Returns the ID of the newly created ban entry.
+	 * <p>
+	 * Note that creating a ban entry for the {@code "empty"} "myTeamSpeak" ID will ban all clients who
+	 * don't have a linked "myTeamSpeak" account.
+	 * </p>
+	 *
+	 * @param ip
+	 * 		a RegEx pattern to match a client's IP against, can be {@code null}
+	 * @param name
+	 * 		a RegEx pattern to match a client's name against, can be {@code null}
+	 * @param uid
+	 * 		the unique identifier of a client, can be {@code null}
+	 * @param myTSId
+	 * 		the "myTeamSpeak" ID of a client, the string {@code "empty"}, or {@code null}
+	 * @param timeInSeconds
+	 * 		the duration of the ban in seconds. 0 equals a permanent ban
+	 * @param reason
+	 * 		the reason for the ban, can be {@code null}
+	 *
+	 * @return the ID of the newly created ban entry
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see Pattern RegEx Pattern
+	 * @see Client#getId()
+	 * @see Client#getUniqueIdentifier()
+	 * @see ClientInfo#getIp()
+	 */
+	public CommandFuture<Integer> addBan(String ip, String name, String uid, String myTSId, long timeInSeconds, String reason) {
+		Command cmd = BanCommands.banAdd(ip, name, uid, myTSId, timeInSeconds, reason);
 		return executeAndReturnIntProperty(cmd, "banid");
 	}
 
@@ -504,8 +540,9 @@ public void addTS3Listeners(TS3Listener... listeners) {
 	/**
 	 * Bans a client with a given client ID for a given time.
 	 * <p>
-	 * Please note that this will create two separate ban rules,
-	 * one for the targeted client's IP address and their unique identifier.
+	 * Please note that this will create 2 or 3 separate ban rules,
+	 * one for the targeted client's IP address, one for their unique identifier,
+	 * and potentially one more for their "myTeamSpeak" ID.
 	 * </p><p>
 	 * <i>Exception:</i> If the banned client connects via a loopback address
 	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created
@@ -517,7 +554,7 @@ public void addTS3Listeners(TS3Listener... listeners) {
 	 * @param timeInSeconds
 	 * 		the duration of the ban in seconds. 0 equals a permanent ban
 	 *
-	 * @return an array containing the IDs of the first and the second ban entry
+	 * @return an array containing the IDs of the created ban entries
 	 *
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails

src/main/java/com/github/theholywaffle/teamspeak3/commands/BanCommands.java

@@ -34,15 +34,16 @@ private BanCommands() {
 		throw new Error("No instances");
 	}
 
-	public static Command banAdd(String ip, String name, String uid, long timeInSeconds, String reason) {
+	public static Command banAdd(String ip, String name, String uid, String myTSId, long timeInSeconds, String reason) {
 		if (ip == null && name == null && uid == null) {
 			throw new IllegalArgumentException("Either IP, name or UId must be non-null");
 		}
 
-		CommandBuilder builder = new CommandBuilder("banadd", 5);
+		CommandBuilder builder = new CommandBuilder("banadd", 6);
 		builder.addIf(ip != null, new KeyValueParam("ip", ip));
 		builder.addIf(name != null, new KeyValueParam("name", name));
 		builder.addIf(uid != null, new KeyValueParam("uid", uid));
+		builder.addIf(myTSId != null, new KeyValueParam("mytsid", myTSId));
 		builder.addIf(timeInSeconds > 0, new KeyValueParam("time", timeInSeconds));
 		builder.addIf(reason != null, new KeyValueParam("banreason", reason));
 		return builder.build();