Add new [add|get|delete]ServerQueryLogin methods to TS3Api(Async)

These methods can be used to create server-local and global server
query logins, look up server query logins (optionally filtered by name),
and delete existing server query logins.

Author: rogermb

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

@@ -476,6 +476,34 @@ public void addServerGroupPermission(int groupId, String permName, int value, bo
 		asyncApi.addServerGroupPermission(groupId, permName, value, negated, skipped).getUninterruptibly();
 	}
 
+	/**
+	 * Creates a server query login with name {@code loginName} for the client specified by {@code clientDBId}
+	 * on the currently selected virtual server and returns the password of the created login.
+	 * If the client already had a server query login, the existing login will be deleted and replaced.
+	 * <p>
+	 * Moreover, this method can be used to create new <i>global</i> server query logins that are not tied to any
+	 * particular virtual server or client. To create such a server query login, make sure no virtual server is
+	 * selected (e.g. use {@code selectVirtualServerById(0)}) and call this method with {@code clientDBId = 0}.
+	 * </p>
+	 *
+	 * @param loginName
+	 * 		the name of the server query login to add
+	 * @param clientDBId
+	 * 		the database ID of the client for which a server query login should be created
+	 *
+	 * @return an object containing the password of the new server query login
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #deleteServerQueryLogin(int)
+	 * @see #getServerQueryLogins()
+	 * @see #updateServerQueryLogin(String)
+	 */
+	public CreatedQueryLogin addServerQueryLogin(String loginName, int clientDBId) {
+		return asyncApi.addServerQueryLogin(loginName, clientDBId).getUninterruptibly();
+	}
+
 	/**
 	 * Adds one or more {@link TS3Listener}s to the event manager of the query.
 	 * These listeners will be notified when the TS3 server fires an event.
@@ -1298,6 +1326,26 @@ public void deleteServerGroupPermission(int groupId, String permName) {
 		asyncApi.deleteServerGroupPermission(groupId, permName).getUninterruptibly();
 	}
 
+	/**
+	 * Deletes the server query login with the specified client database ID.
+	 * <p>
+	 * If you only know the name of the server query login, use {@link #getServerQueryLoginsByName(String)} first.
+	 * </p>
+	 *
+	 * @param clientDBId
+	 * 		the client database ID of the server query login (usually the ID of the associated client)
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #addServerQueryLogin(String, int)
+	 * @see #getServerQueryLogins()
+	 * @see #updateServerQueryLogin(String)
+	 */
+	public void deleteServerQueryLogin(int clientDBId) {
+		asyncApi.deleteServerQueryLogin(clientDBId).getUninterruptibly();
+	}
+
 	/**
 	 * Restores the selected virtual servers configuration using the data from a
 	 * previously created server snapshot.
@@ -2770,6 +2818,46 @@ public VirtualServerInfo getServerInfo() {
 		return asyncApi.getServerInfo().getUninterruptibly();
 	}
 
+	/**
+	 * Gets a list of all server query logins (containing login name, virtual server ID, and client database ID).
+	 * If a virtual server is selected, only the server query logins of the selected virtual server are returned.
+	 *
+	 * @return a list of {@code QueryLogin} objects describing existing server query logins
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #addServerQueryLogin(String, int)
+	 * @see #deleteServerQueryLogin(int)
+	 * @see #getServerQueryLoginsByName(String)
+	 * @see #updateServerQueryLogin(String)
+	 */
+	public List<QueryLogin> getServerQueryLogins() {
+		return asyncApi.getServerQueryLogins().getUninterruptibly();
+	}
+
+	/**
+	 * Gets a list of all server query logins (containing login name, virtual server ID, and client database ID)
+	 * whose login name matches the specified SQL-like pattern.
+	 * If a virtual server is selected, only the server query logins of the selected virtual server are returned.
+	 *
+	 * @param pattern
+	 * 		the SQL-like pattern to match the server query login name against
+	 *
+	 * @return a list of {@code QueryLogin} objects describing existing server query logins
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #addServerQueryLogin(String, int)
+	 * @see #deleteServerQueryLogin(int)
+	 * @see #getServerQueryLogins()
+	 * @see #updateServerQueryLogin(String)
+	 */
+	public List<QueryLogin> getServerQueryLoginsByName(String pattern) {
+		return asyncApi.getServerQueryLoginsByName(pattern).getUninterruptibly();
+	}
+
 	/**
 	 * Gets the version, build number and platform of the TeamSpeak3 server.
 	 *
@@ -4370,6 +4458,9 @@ public void updateClient(ClientProperty property, String value) {
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails
 	 * @querycommands 1
+	 * @see #addServerQueryLogin(String, int)
+	 * @see #deleteServerQueryLogin(int)
+	 * @see #getServerQueryLogins()
 	 */
 	public String updateServerQueryLogin(String loginName) {
 		return asyncApi.updateServerQueryLogin(loginName).getUninterruptibly();

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

@@ -525,6 +525,35 @@ public CommandFuture<Void> addServerGroupPermission(int groupId, String permName
 		return executeAndReturnError(cmd);
 	}
 
+	/**
+	 * Creates a server query login with name {@code loginName} for the client specified by {@code clientDBId}
+	 * on the currently selected virtual server and returns the password of the created login.
+	 * If the client already had a server query login, the existing login will be deleted and replaced.
+	 * <p>
+	 * Moreover, this method can be used to create new <i>global</i> server query logins that are not tied to any
+	 * particular virtual server or client. To create such a server query login, make sure no virtual server is
+	 * selected (e.g. use {@code selectVirtualServerById(0)}) and call this method with {@code clientDBId = 0}.
+	 * </p>
+	 *
+	 * @param loginName
+	 * 		the name of the server query login to add
+	 * @param clientDBId
+	 * 		the database ID of the client for which a server query login should be created
+	 *
+	 * @return an object containing the password of the new server query login
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #deleteServerQueryLogin(int)
+	 * @see #getServerQueryLogins()
+	 * @see #updateServerQueryLogin(String)
+	 */
+	public CommandFuture<CreatedQueryLogin> addServerQueryLogin(String loginName, int clientDBId) {
+		Command cmd = QueryLoginCommands.queryLoginAdd(loginName, clientDBId);
+		return executeAndTransformFirst(cmd, CreatedQueryLogin::new);
+	}
+
 	/**
 	 * Adds one or more {@link TS3Listener}s to the event manager of the query.
 	 * These listeners will be notified when the TS3 server fires an event.
@@ -1462,6 +1491,29 @@ public CommandFuture<Void> deleteServerGroupPermission(int groupId, String permN
 		return executeAndReturnError(cmd);
 	}
 
+	/**
+	 * Deletes the server query login with the specified client database ID.
+	 * <p>
+	 * If you only know the name of the server query login, use {@link #getServerQueryLoginsByName(String)} first.
+	 * </p>
+	 *
+	 * @param clientDBId
+	 * 		the client database ID of the server query login (usually the ID of the associated client)
+	 *
+	 * @return a future to track the progress of this command
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #addServerQueryLogin(String, int)
+	 * @see #getServerQueryLogins()
+	 * @see #updateServerQueryLogin(String)
+	 */
+	public CommandFuture<Void> deleteServerQueryLogin(int clientDBId) {
+		Command cmd = QueryLoginCommands.queryLoginDel(clientDBId);
+		return executeAndReturnError(cmd);
+	}
+
 	/**
 	 * Restores the selected virtual servers configuration using the data from a
 	 * previously created server snapshot.
@@ -3150,6 +3202,47 @@ public CommandFuture<VirtualServerInfo> getServerInfo() {
 		return executeAndTransformFirst(cmd, VirtualServerInfo::new);
 	}
 
+	/**
+	 * Gets a list of all server query logins (containing login name, virtual server ID, and client database ID).
+	 * If a virtual server is selected, only the server query logins of the selected virtual server are returned.
+	 *
+	 * @return a list of {@code QueryLogin} objects describing existing server query logins
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #addServerQueryLogin(String, int)
+	 * @see #deleteServerQueryLogin(int)
+	 * @see #getServerQueryLoginsByName(String)
+	 * @see #updateServerQueryLogin(String)
+	 */
+	public CommandFuture<List<QueryLogin>> getServerQueryLogins() {
+		return getServerQueryLoginsByName(null);
+	}
+
+	/**
+	 * Gets a list of all server query logins (containing login name, virtual server ID, and client database ID)
+	 * whose login name matches the specified SQL-like pattern.
+	 * If a virtual server is selected, only the server query logins of the selected virtual server are returned.
+	 *
+	 * @param pattern
+	 * 		the SQL-like pattern to match the server query login name against
+	 *
+	 * @return a list of {@code QueryLogin} objects describing existing server query logins
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #addServerQueryLogin(String, int)
+	 * @see #deleteServerQueryLogin(int)
+	 * @see #getServerQueryLogins()
+	 * @see #updateServerQueryLogin(String)
+	 */
+	public CommandFuture<List<QueryLogin>> getServerQueryLoginsByName(String pattern) {
+		Command cmd = QueryLoginCommands.queryLoginList(pattern);
+		return executeAndTransform(cmd, QueryLogin::new);
+	}
+
 	/**
 	 * Gets the version, build number and platform of the TeamSpeak3 server.
 	 *
@@ -5039,6 +5132,9 @@ public CommandFuture<Void> updateClient(ClientProperty property, String value) {
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails
 	 * @querycommands 1
+	 * @see #addServerQueryLogin(String, int)
+	 * @see #deleteServerQueryLogin(int)
+	 * @see #getServerQueryLogins()
 	 */
 	public CommandFuture<String> updateServerQueryLogin(String loginName) {
 		Command cmd = ClientCommands.clientSetServerQueryLogin(loginName);

src/main/java/com/github/theholywaffle/teamspeak3/api/wrapper/CreatedQueryLogin.java

@@ -0,0 +1,40 @@
+package com.github.theholywaffle.teamspeak3.api.wrapper;
+
+/*
+ * #%L
+ * TeamSpeak 3 Java API
+ * %%
+ * Copyright (C) 2021 Bert De Geyter, Roger Baumgartner
+ * %%
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ * #L%
+ */
+
+import java.util.Map;
+
+public class CreatedQueryLogin extends QueryLogin {
+
+	public CreatedQueryLogin(Map<String, String> map) {
+		super(map);
+	}
+
+	public String getQueryClientLoginPassword() {
+		return get("client_login_password");
+	}
+}

src/main/java/com/github/theholywaffle/teamspeak3/api/wrapper/QueryLogin.java

@@ -0,0 +1,48 @@
+package com.github.theholywaffle.teamspeak3.api.wrapper;
+
+/*
+ * #%L
+ * TeamSpeak 3 Java API
+ * %%
+ * Copyright (C) 2021 Bert De Geyter, Roger Baumgartner
+ * %%
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ * #L%
+ */
+
+import java.util.Map;
+
+public class QueryLogin extends Wrapper {
+
+	public QueryLogin(Map<String, String> map) {
+		super(map);
+	}
+
+	public int getClientDatabaseId() {
+		return getInt("cldbid");
+	}
+
+	public int getVirtualServerId() {
+		return getInt("sid");
+	}
+
+	public String getQueryClientLoginName() {
+		return get("client_login_name");
+	}
+}

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

@@ -0,0 +1,53 @@
+package com.github.theholywaffle.teamspeak3.commands;
+
+/*
+ * #%L
+ * TeamSpeak 3 Java API
+ * %%
+ * Copyright (C) 2021 Bert De Geyter, Roger Baumgartner
+ * %%
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ * #L%
+ */
+
+import com.github.theholywaffle.teamspeak3.commands.parameter.KeyValueParam;
+
+public final class QueryLoginCommands {
+
+	private QueryLoginCommands() {
+		throw new Error("No instances");
+	}
+
+	public static Command queryLoginAdd(String loginName, int clientDBId) {
+		CommandBuilder builder = new CommandBuilder("queryloginadd", 2);
+		builder.add(new KeyValueParam("client_login_name", loginName));
+		builder.addIf(clientDBId > 0, new KeyValueParam("cldbid", clientDBId));
+		return builder.build();
+	}
+
+	public static Command queryLoginDel(int clientDBId) {
+		return new CommandBuilder("querylogindel", 1).add(new KeyValueParam("cldbid", clientDBId)).build();
+	}
+
+	public static Command queryLoginList(String pattern) {
+		CommandBuilder builder = new CommandBuilder("queryloginlist", 1);
+		builder.addIf(pattern != null, new KeyValueParam("pattern", pattern));
+		return builder.build();
+	}
+}