Add the Complaints List and Make a Complaint

Tools > Complaints List (Ctrl+Shift+C) shows the server's complaints
grouped by target, with Remove, Reload and Ban Client, as TS3 does. The
client menu gains Make a Complaint below Poke. The complaint delete
permissions are missing from the needed-permissions subset, so they are
asked for alongside the move/kick/ban powers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-04 13:03:57 +00:00
co-authored by Claude Opus 5.5
parent ee1a83e981
commit fb1de8ac5b
13 changed files with 760 additions and 23 deletions
@@ -0,0 +1,35 @@
package com.ts3client.net;
import java.util.Map;
/**
* A complaint one client filed about another; the server keeps at most one per pair.
*
* @param targetDbId the database id of the client complained about
* @param fromDbId the database id of the client who complained
*/
public record Complaint(int targetDbId, String targetName, int fromDbId, String fromName,
String message, long timestampEpochSeconds) {
/** Reads a complaint off a {@code notifycomplainlist} event's fields. */
static Complaint from(Map<String, String> fields) {
return new Complaint((int) parseLong(fields.get("tcldbid")),
orEmpty(fields.get("tname")),
(int) parseLong(fields.get("fcldbid")),
orEmpty(fields.get("fname")),
orEmpty(fields.get("message")),
parseLong(fields.get("timestamp")));
}
private static String orEmpty(String s) {
return s == null || s.equals("null") ? "" : s;
}
private static long parseLong(String s) {
try {
return s == null ? 0 : Long.parseLong(s.trim());
} catch (NumberFormatException e) {
return 0;
}
}
}
@@ -0,0 +1,79 @@
package com.ts3client.net;
import com.github.manevolent.ts3j.command.CommandException;
import com.github.manevolent.ts3j.command.SingleCommand;
import com.github.manevolent.ts3j.command.parameter.CommandSingleParameter;
import com.github.manevolent.ts3j.event.UnknownTeamspeakEvent;
import com.github.manevolent.ts3j.protocol.ProtocolRole;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* The server's complaints: filing, listing and removing them.
*
* <p>Split out of {@link TeamspeakConnection} like {@link BanAdmin}, and answered the same
* way: {@code complainlist} replies with {@code notifycomplainlist} events ahead of the
* command's own completion. Every call here blocks and must run off the UI thread; the
* connection's public wrappers do that.
*/
final class ComplaintAdmin {
/** What {@code complainlist} answers when there are no complaints at all. */
private static final int ERROR_DATABASE_EMPTY_RESULT = 0x0501;
/** What {@code complainadd} answers when we already complained about that client. */
private static final int ERROR_DATABASE_DUPLICATE_ENTRY = 0x0502;
private final TeamspeakConnection conn;
/** The {@code complainlist} reply in progress; one request may be in flight at a time. */
private volatile List<Complaint> listing;
ComplaintAdmin(TeamspeakConnection conn) {
this.conn = conn;
}
List<Complaint> list() throws Exception {
List<Complaint> complaints = Collections.synchronizedList(new ArrayList<>());
listing = complaints;
try {
conn.socket().executeCommand(new SingleCommand("complainlist", ProtocolRole.CLIENT)).complete();
conn.awaitEventsProcessed();
} catch (CommandException e) {
if (e.getErrorId() != ERROR_DATABASE_EMPTY_RESULT) throw e;
} finally {
listing = null;
}
return new ArrayList<>(complaints);
}
void onListEntry(UnknownTeamspeakEvent e) {
List<Complaint> complaints = listing;
if (complaints != null) complaints.add(Complaint.from(e.getMap()));
}
/** Files a complaint about a client; the server takes one per client from each of us. */
void add(int targetDbId, String message) throws Exception {
try {
conn.socket().executeCommand(new SingleCommand("complainadd", ProtocolRole.CLIENT,
new CommandSingleParameter("tcldbid", Integer.toString(targetDbId)),
new CommandSingleParameter("message", message))).complete();
} catch (CommandException e) {
if (e.getErrorId() != ERROR_DATABASE_DUPLICATE_ENTRY) throw e;
throw new IllegalStateException("Cannot add multiple complaints about the same client.");
}
}
void delete(Complaint complaint) throws Exception {
conn.socket().executeCommand(new SingleCommand("complaindel", ProtocolRole.CLIENT,
new CommandSingleParameter("tcldbid", Integer.toString(complaint.targetDbId())),
new CommandSingleParameter("fcldbid", Integer.toString(complaint.fromDbId())))).complete();
}
/** Removes every complaint about one client. */
void deleteAll(int targetDbId) throws Exception {
conn.socket().executeCommand(new SingleCommand("complaindelall", ProtocolRole.CLIENT,
new CommandSingleParameter("tcldbid", Integer.toString(targetDbId)))).complete();
}
}
@@ -670,6 +670,7 @@ final class ConnectionEventHandler implements TS3Listener {
else if ("notifybanlist".equals(e.getCommand())) conn.bans.onListEntry(e);
else if ("notifytokenlist".equals(e.getCommand())) conn.privilegeKeys.onListEntry(e);
else if ("notifytokenadd".equals(e.getCommand())) conn.privilegeKeys.onAdded(e);
else if ("notifycomplainlist".equals(e.getCommand())) conn.complaints.onListEntry(e);
}
// ---- helpers ----
@@ -35,8 +35,8 @@ public final class ServerModel {
private int nextPermissionId = FIRST_PERMISSION_ID;
/** Permission id -> the local client's resolved value, from {@code notifyclientneededpermissions}. */
private final Map<Integer, Integer> selfPermissionValues = new LinkedHashMap<>();
/** The local client's {@link #SELF_POWERS}, which the needed permissions leave out; absent until known. */
private final Map<String, Integer> selfPowers = new HashMap<>();
/** The local client's {@link #UNREPORTED_PERMISSIONS}, which the needed permissions leave out; absent until known. */
private final Map<String, Integer> unreportedValues = new HashMap<>();
private String serverName = "TeamSpeak Server";
/** The {@code virtualserver_*} properties from {@code initserver}, kept up to date by server edits. */
private final Map<String, String> serverProperties = new HashMap<>();
@@ -52,7 +52,7 @@ public final class ServerModel {
permissionIds.clear();
nextPermissionId = FIRST_PERMISSION_ID;
selfPermissionValues.clear();
selfPowers.clear();
unreportedValues.clear();
serverProperties.clear();
defaultChannelGroupId = 0;
}
@@ -161,21 +161,22 @@ public final class ServerModel {
}
/**
* The powers {@code notifyclientneededpermissions} never carries, not even for an admin;
* The permissions {@code notifyclientneededpermissions} never carries, not even for an admin;
* they have to be asked for with {@code permget}.
*/
public static final List<String> SELF_POWERS = List.of("i_client_move_power",
"i_client_kick_from_channel_power", "i_client_kick_from_server_power", "i_client_ban_power");
public static final List<String> UNREPORTED_PERMISSIONS = List.of("i_client_move_power",
"i_client_kick_from_channel_power", "i_client_kick_from_server_power", "i_client_ban_power",
"b_client_complain_delete", "b_client_complain_delete_own");
/** Takes on the answer to asking for {@link #SELF_POWERS}; those it leaves out count as 0. */
public synchronized void setSelfPowers(Map<String, Integer> powers) {
selfPowers.clear();
selfPowers.putAll(powers);
/** Takes on the answer to asking for {@link #UNREPORTED_PERMISSIONS}; those it leaves out count as 0. */
public synchronized void setUnreportedPermissions(Map<String, Integer> values) {
unreportedValues.clear();
unreportedValues.putAll(values);
}
/** One of {@link #SELF_POWERS}; 0 until known, or when the server would not tell. */
/** One of {@link #UNREPORTED_PERMISSIONS}; 0 until known, or when the server would not tell. */
public synchronized int selfPower(String name) {
return selfPowers.getOrDefault(name, 0);
return unreportedValues.getOrDefault(name, 0);
}
// ---- what the local client may do ----
@@ -200,6 +201,16 @@ public final class ServerModel {
return bans.stream().allMatch(b -> b.createdBy(selfUid));
}
/**
* Whether we may remove all of {@code complaints}: any with {@code b_client_complain_delete},
* only those we filed with {@code b_client_complain_delete_own}.
*/
public synchronized boolean canDeleteComplaints(Collection<Complaint> complaints, int selfDbId) {
if (selfPower("b_client_complain_delete") > 0) return true;
if (selfPower("b_client_complain_delete_own") <= 0) return false;
return complaints.stream().allMatch(c -> c.fromDbId() == selfDbId);
}
/** Whether we may rewrite {@code ban}: that is deleting it and creating its replacement. */
public synchronized boolean canEditBan(BanEntry ban, String selfUid) {
return permits("b_client_ban_create") && canDeleteBans(List.of(ban), selfUid);
@@ -499,6 +510,15 @@ public final class ServerModel {
return null;
}
/** An online client by its database id, or {@code null} if none is visible. */
public synchronized ClientEntry findClientByDatabaseId(int databaseId) {
if (databaseId <= 0) return null;
for (ClientEntry c : clients.values()) {
if (c.databaseId == databaseId) return c;
}
return null;
}
public synchronized ClientEntry findClientByName(String name) {
for (ClientEntry c : clients.values()) {
if (c.nickname != null && c.nickname.equals(name)) return c;
@@ -60,6 +60,8 @@ public final class TeamspeakConnection implements TS3Listener {
/** The longest reason the protocol carries with a kick. */
public static final int KICK_REASON_LIMIT = 40;
/** The longest reason a complaint may carry. */
public static final int COMPLAINT_REASON_LIMIT = 200;
/** The protocol's reason ids for the two flavours of <b>clientkick</b>. */
private static final int REASON_KICK_CHANNEL = 4;
@@ -95,9 +97,10 @@ public final class TeamspeakConnection implements TS3Listener {
final ConnectionStatsCollector stats = new ConnectionStatsCollector(this);
/** Channel editing and the server's icon store; package-private for {@link ConnectionEventHandler}. */
final ChannelAdmin channels = new ChannelAdmin(this);
/** The server's ban list and privilege keys; also package-private for {@link ConnectionEventHandler}. */
/** The server's ban list, privilege keys and complaints; also package-private for {@link ConnectionEventHandler}. */
final BanAdmin bans = new BanAdmin(this);
final PrivilegeKeyAdmin privilegeKeys = new PrivilegeKeyAdmin(this);
final ComplaintAdmin complaints = new ComplaintAdmin(this);
private final AvatarAdmin avatarAdmin = new AvatarAdmin(this);
/*
@@ -735,13 +738,13 @@ public final class TeamspeakConnection implements TS3Listener {
}
/**
* Asks for our own {@link ServerModel#SELF_POWERS}, which {@code notifyclientneededpermissions}
* Asks for our own {@link ServerModel#UNREPORTED_PERMISSIONS}, which {@code notifyclientneededpermissions}
* never carries. Asking needs {@code b_client_permissionoverview_own}; refused, we take them
* as none, which is what the groups that lack the one usually have of the others.
*/
void requestSelfPowers() {
List<SingleCommand> rows = new ArrayList<>();
for (String name : ServerModel.SELF_POWERS) {
for (String name : ServerModel.UNREPORTED_PERMISSIONS) {
rows.add(new SingleCommand("permget", ProtocolRole.CLIENT, new CommandSingleParameter("permsid", name)));
}
submit(sock -> {
@@ -752,8 +755,8 @@ public final class TeamspeakConnection implements TS3Listener {
String value = fields.get("permvalue");
if (name != null && value != null) powers.put(name, Integer.parseInt(value));
}
model.setSelfPowers(powers);
}, e -> model.setSelfPowers(Map.of()));
model.setUnreportedPermissions(powers);
}, e -> model.setUnreportedPermissions(Map.of()));
}
/** Assigns or removes a server group for a client (by database id, as {@code servergroupaddclient} needs). */
@@ -1007,6 +1010,36 @@ public final class TeamspeakConnection implements TS3Listener {
});
}
// ---- complaints ----
/** Complains about an online client to the server's admins. */
public void complain(ClientEntry client, String reason) {
act("Failed to send complaint: ", sock -> {
complaints.add(client.databaseId, reason);
log("Complaint sent.");
});
}
/** Reads the server's complaints, delivering them (or a failure message) off the UI thread. */
public void requestComplaints(BiConsumer<List<Complaint>, String> callback) {
run(callback, complaints::list);
}
/**
* Removes every complaint about each of {@code targetDbIds}, then each of {@code single},
* stopping at the first the server refuses.
*
* @param callback given {@code null} on success, or the failure message
*/
public void deleteComplaints(Collection<Integer> targetDbIds, Collection<Complaint> single,
Consumer<String> callback) {
run((ignored, error) -> callback.accept(error), () -> {
for (int target : targetDbIds) complaints.deleteAll(target);
for (Complaint complaint : single) complaints.delete(complaint);
return null;
});
}
// ---- bans ----
/** Reads the server's ban list, delivering it (or a failure message) off the UI thread. */
@@ -432,6 +432,11 @@ public final class ServerSession {
return permits("b_client_ban_list");
}
/** Whether the server grants us {@code b_client_complain_list}; offered while unknown. */
public boolean canViewComplaints() {
return permits("b_client_complain_list");
}
/** Whether the server grants us {@code b_virtualserver_token_list}; offered while unknown. */
public boolean canListPrivilegeKeys() {
return permits("b_virtualserver_token_list");