Server.php

Go to the documentation of this file.

<?php
 
namespace PlanetTeamSpeak\TeamSpeak3Framework\Node;
 
use PlanetTeamSpeak\TeamSpeak3Framework\Adapter\ServerQuery\Reply;
use PlanetTeamSpeak\TeamSpeak3Framework\Exception\AdapterException;
use PlanetTeamSpeak\TeamSpeak3Framework\Exception\HelperException;
use PlanetTeamSpeak\TeamSpeak3Framework\Exception\NodeException;
use PlanetTeamSpeak\TeamSpeak3Framework\Exception\ServerQueryException;
use PlanetTeamSpeak\TeamSpeak3Framework\Helper\Signal;
use PlanetTeamSpeak\TeamSpeak3Framework\Helper\StringHelper;
use PlanetTeamSpeak\TeamSpeak3Framework\TeamSpeak3;

class Server extends Node
{
    protected array|null $channelList = null;

    protected array|null $clientList = null;

    protected array|null $sgroupList = null;

    protected array|null $cgroupList = null;

    public function __construct(Host $host, array $info, string $index = "virtualserver_id")
    {
        $this->parent = $host;
        $this->nodeInfo = $info;
 
        if (!array_key_exists($index, $this->nodeInfo)) {
            throw new ServerQueryException("invalid serverID", 0x400);
        }
 
        $this->nodeId = $this->nodeInfo[$index];
    }

    public function request(string $cmd, bool $throw = true): Reply
    {
        if ($this->getId() != $this->getParent()->serverSelectedId()) {
            $this->getParent()->serverSelect($this->getId());
        }
 
        return $this->getParent()->request($cmd, $throw);
    }

    public function channelList(array $filter = []): array
    {
        if ($this->channelList === null) {
            $channels = $this->request("channellist -topic -flags -voice -limits -icon")->toAssocArray("cid");
 
            $this->channelList = [];
 
            foreach ($channels as $cid => $channel) {
                $this->channelList[$cid] = new Channel($this, $channel);
            }
 
            $this->resetNodeList();
        }
 
        return $this->filterList($this->channelList, $filter);
    }

    public function channelListReset(): void
    {
        $this->resetNodeList();
        $this->channelList = null;
    }

    public function channelGetDefault(): Channel
    {
        foreach ($this->channelList() as $channel) {
            if ($channel["channel_flag_default"]) {
                return $channel;
            }
        }
 
        throw new ServerQueryException("invalid channelID", 0x300);
    }

    public function channelCreate(array $properties): int
    {
        $cid = $this->execute("channelcreate", $properties)->toList();
        $this->channelListReset();
 
        if (!isset($properties["channel_flag_permanent"]) && !isset($properties["channel_flag_semi_permanent"])) {
            $this->getParent()->whoamiSet("client_channel_id", $cid["cid"]);
        }
 
        return $cid["cid"];
    }

    public function channelDelete(int|Node $cid, bool $force = false): void
    {
        $this->execute("channeldelete", ["cid" => $cid, "force" => $force]);
        $this->channelListReset();
 
        if (($cid instanceof Node ? $cid->getId() : $cid) == $this->whoamiGet("client_channel_id")) {
            $this->getParent()->whoamiReset();
        }
    }

    public function channelMove(int $cid, int $pid, int $order = null): void
    {
        $this->execute("channelmove", ["cid" => $cid, "cpid" => $pid, "order" => $order]);
        $this->channelListReset();
    }

    public function channelIsSpacer(Channel $channel): bool
    {
        return preg_match("/\[[^]]*spacer[^]]*]/", $channel) && $channel["channel_flag_permanent"] && !$channel["pid"];
    }

    public function channelSpacerCreate(
        string $ident,
        int    $type = TeamSpeak3::SPACER_SOLIDLINE,
        int    $align = TeamSpeak3::SPACER_ALIGN_REPEAT,
        int    $order = null,
        int    $maxclients = 0
    ): int {
        $properties = [
            "channel_name_phonetic" => "channel spacer",
            "channel_codec" => TeamSpeak3::CODEC_OPUS_VOICE,
            "channel_codec_quality" => 0x00,
            "channel_flag_permanent" => true,
            "channel_flag_maxclients_unlimited" => false,
            "channel_flag_maxfamilyclients_unlimited" => false,
            "channel_flag_maxfamilyclients_inherited" => false,
            "channel_maxclients" => $maxclients,
            "channel_order" => $order,
        ];
 
        $properties["channel_name"] = match ($align) {
            TeamSpeak3::SPACER_ALIGN_REPEAT => "[*spacer" . $ident . "]",
            TeamSpeak3::SPACER_ALIGN_LEFT => "[lspacer" . $ident . "]",
            TeamSpeak3::SPACER_ALIGN_RIGHT => "[rspacer" . $ident . "]",
            TeamSpeak3::SPACER_ALIGN_CENTER => "[cspacer" . $ident . "]",
            default => throw new ServerQueryException("missing required parameter", 0x606),
        };
 
        $properties["channel_name"] .= match ($type) {
            (string)TeamSpeak3::SPACER_SOLIDLINE => "___",
            (string)TeamSpeak3::SPACER_DASHLINE => "---",
            (string)TeamSpeak3::SPACER_DOTLINE => "...",
            (string)TeamSpeak3::SPACER_DASHDOTLINE => "-.-",
            (string)TeamSpeak3::SPACER_DASHDOTDOTLINE => "-..",
            default => strval($type),
        };
 
        return $this->channelCreate($properties);
    }

    public function channelSpacerGetType(int $cid): int
    {
        $channel = $this->channelGetById($cid);
 
        if (!$this->channelIsSpacer($channel)) {
            throw new ServerQueryException("invalid channel flags", 0x307);
        }
 
        return match ($channel["channel_name"]->section("]", 1)) {
            "___" => TeamSpeak3::SPACER_SOLIDLINE,
            "---" => TeamSpeak3::SPACER_DASHLINE,
            "..." => TeamSpeak3::SPACER_DOTLINE,
            "-.-" => TeamSpeak3::SPACER_DASHDOTLINE,
            "-.." => TeamSpeak3::SPACER_DASHDOTDOTLINE,
            default => TeamSpeak3::SPACER_CUSTOM,
        };
    }

    public function channelSpacerGetAlign(int $cid): int
    {
        $channel = $this->channelGetById($cid);
 
        if (!$this->channelIsSpacer($channel) || !preg_match("/\[(.*)spacer.*]/", $channel, $matches) || !isset($matches[1])) {
            throw new ServerQueryException("invalid channel flags", 0x307);
        }
 
        return match ($matches[1]) {
            "*" => TeamSpeak3::SPACER_ALIGN_REPEAT,
            "c" => TeamSpeak3::SPACER_ALIGN_CENTER,
            "r" => TeamSpeak3::SPACER_ALIGN_RIGHT,
            default => TeamSpeak3::SPACER_ALIGN_LEFT,
        };
    }

    public function channelPermList(int $cid, bool $permsid = false): array
    {
        return $this->execute("channelpermlist", ["cid" => $cid, $permsid ? "-permsid" : null])
            ->toAssocArray($permsid ? "permsid" : "permid");
    }

    public function channelPermAssign(int $cid, int|array $permid, int|array $permvalue): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("channeladdperm", ["cid" => $cid, $permident => $permid, "permvalue" => $permvalue]);
    }

    public function channelPermRemove(int $cid, int|array $permid): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("channeldelperm", ["cid" => $cid, $permident => $permid]);
    }

    public function channelClientPermList(int $cid, int $cldbid, bool $permsid = false): array
    {
        return $this->execute("channelclientpermlist", ["cid" => $cid, "cldbid" => $cldbid, $permsid ? "-permsid" : null])
            ->toAssocArray($permsid ? "permsid" : "permid");
    }

    public function channelClientPermAssign(int $cid, int $cldbid, int|array $permid, int|array $permvalue): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("channelclientaddperm", ["cid" => $cid, "cldbid" => $cldbid, $permident => $permid, "permvalue" => $permvalue]);
    }

    public function channelClientPermRemove(int $cid, int $cldbid, int|array $permid): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("channelclientdelperm", ["cid" => $cid, "cldbid" => $cldbid, $permident => $permid]);
    }

    public function channelFileList(int $cid, string $cpw = "", string $path = "/", bool $recursive = false): array
    {
        $files = $this->execute("ftgetfilelist", ["cid" => $cid, "cpw" => $cpw, "path" => $path])->toArray();
        $count = count($files);
 
        for ($i = 0; $i < $count; $i++) {
            $files[$i]["sid"] = $this->getId();
            $files[$i]["cid"] = $files[0]["cid"];
            $files[$i]["path"] = $files[0]["path"];
            $files[$i]["src"] = new StringHelper($cid ? $files[$i]["path"] : "/");
 
            if (!$files[$i]["src"]->endsWith("/")) {
                $files[$i]["src"]->append("/");
            }
 
            $files[$i]["src"]->append($files[$i]["name"]);
 
            if ($recursive && $files[$i]["type"] == TeamSpeak3::FILE_TYPE_DIRECTORY) {
                $files = array_merge($files, $this->channelFileList($cid, $cpw, $path . $files[$i]["name"], $recursive));
            }
        }
 
        uasort($files, [__CLASS__, "sortFileList"]);
 
        return $files;
    }

    public function channelFileInfo(int $cid, string $cpw = "", string $name = "/"): array
    {
        $info = $this->execute("ftgetfileinfo", ["cid" => $cid, "cpw" => $cpw, "name" => $name])->toArray();
 
        return array_pop($info);
    }

    public function channelFileRename(int $cid, string $cpw = "", string $oldname = "/", string $newname = "/", int $tcid = null, string $tcpw = null): void
    {
        $this->execute("ftrenamefile", ["cid" => $cid, "cpw" => $cpw, "oldname" => $oldname, "newname" => $newname, "tcid" => $tcid, "tcpw" => $tcpw]);
    }

    public function channelFileDelete(int $cid, string $cpw = "", string $name = "/"): void
    {
        $this->execute("ftdeletefile", ["cid" => $cid, "cpw" => $cpw, "name" => $name]);
    }

    public function channelDirCreate(int $cid, string $cpw = "", string $dirname = "/"): void
    {
        $this->execute("ftcreatedir", ["cid" => $cid, "cpw" => $cpw, "dirname" => $dirname]);
    }

    public function channelGetLevel(int $cid): int
    {
        $channel = $this->channelGetById($cid);
        $levelno = 0;
 
        if ($channel["pid"]) {
            $levelno = $this->channelGetLevel($channel["pid"]) + 1;
        }
 
        return $levelno;
    }

    public function channelGetPathway(int $cid): string
    {
        $channel = $this->channelGetById($cid);
        $pathway = $channel["channel_name"];
 
        if ($channel["pid"]) {
            $pathway = $this->channelGetPathway($channel["pid"]) . "/" . $channel["channel_name"];
        }
 
        return $pathway;
    }

    public function channelGetById(int $cid): Channel
    {
        if (!array_key_exists((string)$cid, $this->channelList())) {
            throw new ServerQueryException("invalid channelID", 0x300);
        }
 
        return $this->channelList[intval((string)$cid)];
    }

    public function channelGetByName(string $name): Channel
    {
        foreach ($this->channelList() as $channel) {
            if ($channel["channel_name"] == $name) {
                return $channel;
            }
        }
 
        throw new ServerQueryException("invalid channelID", 0x300);
    }

    public function clientList(array $filter = []): array
    {
        if ($this->clientList === null) {
            $clients = $this->request("clientlist -uid -away -badges -voice -info -times -groups -icon -country -ip")
                ->toAssocArray("clid");
 
            $this->clientList = [];
 
            foreach ($clients as $clid => $client) {
                if ($this->getParent()->getExcludeQueryClients() && $client["client_type"]) {
                    continue;
                }
 
                $this->clientList[$clid] = new Client($this, $client);
            }
 
            uasort($this->clientList, [__CLASS__, "sortClientList"]);
 
            $this->resetNodeList();
        }
 
        return $this->filterList($this->clientList, $filter);
    }

    public function clientListReset(): void
    {
        $this->resetNodeList();
        $this->clientList = null;
    }

    public function clientFind(string $pattern): array
    {
        return $this->execute("clientfind", ["pattern" => $pattern])->toAssocArray("clid");
    }

    public function clientListDb(int $offset = null, int $limit = null): array
    {
        return $this->execute("clientdblist -count", ["start" => $offset, "duration" => $limit])
            ->toAssocArray("cldbid");
    }

    public function clientCountDb(): int
    {
        return current($this->execute("clientdblist -count", ["duration" => 1])->toList("count"));
    }

    public function clientInfoDb(int $cldbid): array
    {
        return $this->execute("clientdbinfo", ["cldbid" => $cldbid])->toList();
    }

    public function clientFindDb(string $pattern, bool $uid = false): array
    {
        return array_keys($this->execute("clientdbfind", ["pattern" => $pattern, ($uid) ? "-uid" : null, "-details"])
            ->toAssocArray("cldbid"));
    }

    public function clientCount(): int
    {
        if ($this->isOffline()) {
            return 0;
        }
 
        return $this["virtualserver_clientsonline"] - $this["virtualserver_queryclientsonline"];
    }

    public function clientGetById(int $clid): Client
    {
        if (!array_key_exists((string)$clid, $this->clientList())) {
            throw new ServerQueryException("invalid clientID", 0x200);
        }
 
        return $this->clientList[intval((string)$clid)];
    }

    public function clientGetByName(string $name): Client
    {
        foreach ($this->clientList() as $client) {
            if ($client["client_nickname"] == $name) {
                return $client;
            }
        }
 
        throw new ServerQueryException("invalid clientID", 0x200);
    }

    public function clientGetByUid(string $uid): Client
    {
        foreach ($this->clientList() as $client) {
            if ($client["client_unique_identifier"] == $uid) {
                return $client;
            }
        }
 
        throw new ServerQueryException("invalid clientID", 0x200);
    }

    public function clientGetByDbid(int $dbid): Client
    {
        foreach ($this->clientList() as $client) {
            if ($client["client_database_id"] == $dbid) {
                return $client;
            }
        }
 
        throw new ServerQueryException("invalid clientID", 0x200);
    }

    public function clientGetNameByUid(string $cluid): array
    {
        return $this->execute("clientgetnamefromuid", ["cluid" => $cluid])->toList();
    }

    public function clientGetIdsByUid(string $cluid): array
    {
        return $this->execute("clientgetids", ["cluid" => $cluid])->toAssocArray("clid");
    }

    public function clientGetNameByDbid(string $cldbid): array
    {
        return $this->execute("clientgetnamefromdbid", ["cldbid" => $cldbid])->toList();
    }

    public function clientGetServerGroupsByDbid(string $cldbid): array
    {
        return $this->execute("servergroupsbyclientid", ["cldbid" => $cldbid])->toAssocArray("sgid");
    }

    public function clientMove(int|Node $clid, int|Node $cid, $cpw = null): void
    {
        $this->clientListReset();
 
        $this->execute("clientmove", ["clid" => $clid, "cid" => $cid, "cpw" => $cpw]);
 
        if ($clid instanceof Node) {
            $clid = $clid->getId();
        }
 
        if ($cid instanceof Node) {
            $cid = $cid->getId();
        }
 
        if (!is_array($clid) && $clid == $this->whoamiGet("client_id")) {
            $this->getParent()->whoamiSet("client_channel_id", $cid);
        }
    }

    public function clientKick(int $clid, int $reasonid = TeamSpeak3::KICK_CHANNEL, $reasonmsg = null): void
    {
        $this->clientListReset();
 
        $this->execute("clientkick", ["clid" => $clid, "reasonid" => $reasonid, "reasonmsg" => $reasonmsg]);
    }

    public function clientPoke(int $clid, string $msg): void
    {
        $this->execute("clientpoke", ["clid" => $clid, "msg" => $msg]);
    }

    public function clientBan(int $clid, int $timeseconds = null, string $reason = null): array
    {
        $this->clientListReset();
 
        $bans = $this->execute("banclient", ["clid" => $clid, "time" => $timeseconds, "banreason" => $reason])
            ->toAssocArray("banid");
 
        return array_keys($bans);
    }

    public function clientModifyDb(string $cldbid, array $properties): void
    {
        $properties["cldbid"] = $cldbid;
 
        $this->execute("clientdbedit", $properties);
    }

    public function clientDeleteDb(string $cldbid): void
    {
        $this->execute("clientdbdelete", ["cldbid" => $cldbid]);
    }

    public function clientSetChannelGroup(int $cldbid, int $cid, int $cgid): void
    {
        $this->execute("setclientchannelgroup", ["cldbid" => $cldbid, "cid" => $cid, "cgid" => $cgid]);
    }

    public function clientPermList(int $cldbid, bool $permsid = false): array
    {
        $this->clientListReset();
 
        return $this->execute("clientpermlist", ["cldbid" => $cldbid, $permsid ? "-permsid" : null])
            ->toAssocArray($permsid ? "permsid" : "permid");
    }

    public function clientPermAssign(int $cldbid, int|array $permid, int|array $permvalue, bool|array $permskip = false): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("clientaddperm -continueonerror", ["cldbid" => $cldbid, $permident => $permid, "permvalue" => $permvalue, "permskip" => $permskip]);
    }

    public function clientPermRemove(int $cldbid, int|array $permid): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("clientdelperm", ["cldbid" => $cldbid, $permident => $permid]);
    }

    public function serverGroupList(array $filter = []): array
    {
        if ($this->sgroupList === null) {
            $this->sgroupList = $this->request("servergrouplist")->toAssocArray("sgid");
 
            foreach ($this->sgroupList as $sgid => $group) {
                $this->sgroupList[$sgid] = new ServerGroup($this, $group);
            }
 
            uasort($this->sgroupList, [__CLASS__, "sortGroupList"]);
        }
 
        return $this->filterList($this->sgroupList, $filter);
    }

    public function serverGroupListReset(): void
    {
        $this->sgroupList = null;
    }

    public function serverGroupCreate(string $name, int $type = TeamSpeak3::GROUP_DBTYPE_REGULAR): int
    {
        $this->serverGroupListReset();
 
        $sgid = $this->execute("servergroupadd", ["name" => $name, "type" => $type])->toList();
 
        return $sgid["sgid"];
    }

    public function serverGroupCopy(int $ssgid, string $name = null, int $tsgid = 0, int $type = TeamSpeak3::GROUP_DBTYPE_REGULAR): int
    {
        $this->serverGroupListReset();
 
        $sgid = $this->execute("servergroupcopy", ["ssgid" => $ssgid, "tsgid" => $tsgid, "name" => $name, "type" => $type])
            ->toList();
 
        if ($tsgid && $name) {
            $this->serverGroupRename($tsgid, $name);
        }
 
        return count($sgid) ? $sgid["sgid"] : $tsgid;
    }

    public function serverGroupRename(int $sgid, string $name): void
    {
        $this->serverGroupListReset();
 
        $this->execute("servergrouprename", ["sgid" => $sgid, "name" => $name]);
    }

    public function serverGroupDelete(int $sgid, bool $force = false): void
    {
        $this->serverGroupListReset();
 
        $this->execute("servergroupdel", ["sgid" => $sgid, "force" => $force]);
    }

    public function serverGroupGetById(int $sgid): ServerGroup
    {
        if (!array_key_exists((string)$sgid, $this->serverGroupList())) {
            throw new ServerQueryException("invalid groupID", 0xA00);
        }
 
        return $this->sgroupList[intval((string)$sgid)];
    }

    public function serverGroupGetByName(string $name, int $type = TeamSpeak3::GROUP_DBTYPE_REGULAR): ServerGroup
    {
        foreach ($this->serverGroupList() as $group) {
            if ($group["name"] == $name && $group["type"] == $type) {
                return $group;
            }
        }
 
        throw new ServerQueryException("invalid groupID", 0xA00);
    }

    public function serverGroupPermList(int $sgid, bool $permsid = false): array
    {
        return $this->execute("servergrouppermlist", ["sgid" => $sgid, $permsid ? "-permsid" : null])
            ->toAssocArray($permsid ? "permsid" : "permid");
    }

    public function serverGroupPermAssign(int $sgid, int|array $permid, int|array $permvalue, int|array $permnegated = 0, bool|array $permskip = false): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("servergroupaddperm", ["sgid" => $sgid, $permident => $permid, "permvalue" => $permvalue, "permnegated" => $permnegated, "permskip" => $permskip]);
    }

    public function serverGroupPermRemove(int $sgid, int|array $permid): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("servergroupdelperm", ["sgid" => $sgid, $permident => $permid]);
    }

    public function serverGroupClientList(int $sgid): array
    {
        if ($this["virtualserver_default_server_group"] == $sgid) {
            return [];
        }
 
        return $this->execute("servergroupclientlist", ["sgid" => $sgid, "-names"])->toAssocArray("cldbid");
    }

    public function serverGroupClientAdd(int $sgid, int $cldbid): void
    {
        $this->clientListReset();
 
        $this->execute("servergroupaddclient", ["sgid" => $sgid, "cldbid" => $cldbid]);
    }

    public function serverGroupClientDel(int $sgid, int $cldbid): void
    {
        $this->execute("servergroupdelclient", ["sgid" => $sgid, "cldbid" => $cldbid]);
    }

    public function serverGroupGetProfiles(int $type = TeamSpeak3::GROUP_DBTYPE_REGULAR): array
    {
        $profiles = [];
 
        foreach ($this->serverGroupList() as $sgid => $sgroup) {
            if ($sgroup["type"] != $type) {
                continue;
            }
 
            $profiles[$sgid] = [
                "b_permission_modify_power_ignore" => 0,
                "i_group_member_add_power" => 0,
                "i_group_member_remove_power" => 0,
                "i_needed_modify_power_count" => 0,
                "i_needed_modify_power_total" => 0,
                "i_permission_modify_power" => 0,
                "i_group_modify_power" => 0,
                "i_client_modify_power" => 0,
                "b_virtualserver_servergroup_create" => 0,
                "b_virtualserver_servergroup_delete" => 0,
                "b_client_ignore_bans" => 0,
                "b_client_ignore_antiflood" => 0,
                "b_group_is_permanent" => 0,
                "i_client_needed_ban_power" => 0,
                "i_client_needed_kick_power" => 0,
                "i_client_needed_move_power" => 0,
                "i_client_talk_power" => 0,
                "__sgid" => $sgid,
                "__name" => $sgroup->toString(),
                "__node" => $sgroup,
            ];
 
            try {
                $perms = $this->serverGroupPermList($sgid, true);
                $grant = isset($perms["i_permission_modify_power"]) ? $perms["i_permission_modify_power"]["permvalue"] : null;
            } catch (ServerQueryException $e) {
                /* ERROR_database_empty_result */
                if ($e->getCode() != 0x501) {
                    throw $e;
                }
 
                $perms = [];
                $grant = null;
            }
 
            foreach ($perms as $permsid => $perm) {
                if (in_array($permsid, array_keys($profiles[$sgid]))) {
                    $profiles[$sgid][$permsid] = $perm["permvalue"];
                } elseif (StringHelper::factory($permsid)->startsWith("i_needed_modify_power_")) {
                    if (!$grant || $perm["permvalue"] > $grant) {
                        continue;
                    }
 
                    $profiles[$sgid]["i_needed_modify_power_total"] = $profiles[$sgid]["i_needed_modify_power_total"] + $perm["permvalue"];
                    $profiles[$sgid]["i_needed_modify_power_count"]++;
                }
            }
        }
 
        array_multisort($profiles, SORT_DESC);
 
        return $profiles;
    }

    public function serverGroupIdentify(
        int $mode = TeamSpeak3::GROUP_IDENTIFIY_STRONGEST,
        int $type = TeamSpeak3::GROUP_DBTYPE_REGULAR
    ): ServerGroup {
        $profiles = $this->serverGroupGetProfiles($type);
 
        $best_guess_profile = ($mode == TeamSpeak3::GROUP_IDENTIFIY_STRONGEST) ? array_shift($profiles) : array_pop($profiles);
 
        return $this->serverGroupGetById($best_guess_profile["__sgid"]);
    }

    public function channelGroupList(array $filter = []): array
    {
        if ($this->cgroupList === null) {
            $this->cgroupList = $this->request("channelgrouplist")->toAssocArray("cgid");
 
            foreach ($this->cgroupList as $cgid => $group) {
                $this->cgroupList[$cgid] = new ChannelGroup($this, $group);
            }
 
            uasort($this->cgroupList, [__CLASS__, "sortGroupList"]);
        }
 
        return $this->filterList($this->cgroupList, $filter);
    }

    public function channelGroupListReset(): void
    {
        $this->cgroupList = null;
    }

    public function channelGroupCreate(string $name, int $type = TeamSpeak3::GROUP_DBTYPE_REGULAR): int
    {
        $this->channelGroupListReset();
 
        $cgid = $this->execute("channelgroupadd", ["name" => $name, "type" => $type])->toList();
 
        return $cgid["cgid"];
    }

    public function channelGroupCopy(int $scgid, string $name = null, int $tcgid = 0, int $type = TeamSpeak3::GROUP_DBTYPE_REGULAR): int
    {
        $this->channelGroupListReset();
 
        $cgid = $this->execute("channelgroupcopy", ["scgid" => $scgid, "tcgid" => $tcgid, "name" => $name, "type" => $type])
            ->toList();
 
        if ($tcgid && $name) {
            $this->channelGroupRename($tcgid, $name);
        }
 
        return count($cgid) ? $cgid["cgid"] : $tcgid;
    }

    public function channelGroupRename(int $cgid, string $name): void
    {
        $this->channelGroupListReset();
 
        $this->execute("channelgrouprename", ["cgid" => $cgid, "name" => $name]);
    }

    public function channelGroupDelete(int $cgid, bool $force = false): void
    {
        $this->channelGroupListReset();
 
        $this->execute("channelgroupdel", ["cgid" => $cgid, "force" => $force]);
    }

    public function channelGroupGetById(int $cgid): ChannelGroup
    {
        if (!array_key_exists((string)$cgid, $this->channelGroupList())) {
            throw new ServerQueryException("invalid groupID", 0xA00);
        }
 
        return $this->cgroupList[intval((string)$cgid)];
    }

    public function channelGroupGetByName(string $name, int $type = TeamSpeak3::GROUP_DBTYPE_REGULAR): ChannelGroup
    {
        foreach ($this->channelGroupList() as $group) {
            if ($group["name"] == $name && $group["type"] == $type) {
                return $group;
            }
        }
 
        throw new ServerQueryException("invalid groupID", 0xA00);
    }

    public function channelGroupPermList(int $cgid, bool $permsid = false): array
    {
        return $this->execute("channelgrouppermlist", ["cgid" => $cgid, $permsid ? "-permsid" : null])
            ->toAssocArray($permsid ? "permsid" : "permid");
    }

    public function channelGroupPermAssign(int $cgid, int|array $permid, int|array $permvalue): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("channelgroupaddperm", ["cgid" => $cgid, $permident => $permid, "permvalue" => $permvalue]);
    }

    public function channelGroupPermRemove(int $cgid, int|array $permid): void
    {
        if (!is_array($permid)) {
            $permident = (is_numeric($permid)) ? "permid" : "permsid";
        } else {
            $permident = (is_numeric(current($permid))) ? "permid" : "permsid";
        }
 
        $this->execute("channelgroupdelperm", ["cgid" => $cgid, $permident => $permid]);
    }

    public function channelGroupClientList(int $cgid = null, int $cid = null, int $cldbid = null, bool $resolve = false): array
    {
        if ($this["virtualserver_default_channel_group"] == $cgid) {
            return [];
        }
 
        try {
            $result = $this->execute("channelgroupclientlist", ["cgid" => $cgid, "cid" => $cid, "cldbid" => $cldbid])
                ->toArray();
        } catch (ServerQueryException $e) {
            /* ERROR_database_empty_result */
            if ($e->getCode() != 0x501) {
                throw $e;
            }
 
            $result = [];
        }
 
        if ($resolve) {
            foreach ($result as $k => $v) {
                $result[$k] = array_merge($v, $this->clientInfoDb($v["cldbid"]));
            }
        }
 
        return $result;
    }

    public function permReset(): StringHelper
    {
        $token = $this->request("permreset")->toList();
 
        Signal::getInstance()->emit("notifyTokencreated", $this, $token["token"]);
 
        return $token["token"];
    }

    public function permRemoveAny(int $permid): int
    {
        $assignments = $this->permissionFind($permid);
 
        foreach ($assignments as $assignment) {
            switch ($assignment["t"]) {
                case TeamSpeak3::PERM_TYPE_SERVERGROUP:
                    $this->serverGroupPermRemove($assignment["id1"], $assignment["p"]);
                    break;
 
                case TeamSpeak3::PERM_TYPE_CLIENT:
                    $this->clientPermRemove($assignment["id1"], $assignment["p"]);
                    break;
 
                case TeamSpeak3::PERM_TYPE_CHANNEL:
                    $this->channelPermRemove($assignment["id1"], $assignment["p"]);
                    break;
 
                case TeamSpeak3::PERM_TYPE_CHANNELGROUP:
                    $this->channelGroupPermRemove($assignment["id2"], $assignment["p"]);
                    break;
 
                case TeamSpeak3::PERM_TYPE_CHANNELCLIENT:
                    $this->channelClientPermRemove($assignment["id1"], $assignment["id2"], $assignment["p"]);
                    break;
 
                default:
                    throw new ServerQueryException("convert error", 0x604);
            }
        }
 
        return count($assignments);
    }

    public function transferInitUpload(
        int    $clientftfid,
        int    $cid,
        string $name,
        int    $size,
        string $cpw = "",
        bool   $overwrite = false,
        bool   $resume = false
    ): array {
        $upload = $this->execute("ftinitupload", ["clientftfid" => $clientftfid, "cid" => $cid, "name" => $name, "cpw" => $cpw, "size" => $size, "overwrite" => $overwrite, "resume" => $resume])
            ->toList();
 
        if (array_key_exists("status", $upload) && $upload["status"] != 0x00) {
            throw new ServerQueryException($upload["msg"], $upload["status"]);
        }
 
        $upload["cid"] = $cid;
        $upload["file"] = $name;
 
        if (!array_key_exists("ip", $upload) || $upload["ip"]->startsWith("0.0.0.0")) {
            $upload["ip"] = $this->getParent()->getAdapterHost();
        } else {
            $upload["ip"] = $upload["ip"]->section(",");
        }
        $upload["host"] = $upload["ip"];
 
        Signal::getInstance()->emit("filetransferUploadInit", $upload["ftkey"], $upload);
 
        return $upload;
    }

    public function transferInitDownload(int $clientftfid, int $cid, string $name, string $cpw = "", int $seekpos = 0): array
    {
        $download = $this->execute("ftinitdownload", ["clientftfid" => $clientftfid, "cid" => $cid, "name" => $name, "cpw" => $cpw, "seekpos" => $seekpos])
            ->toList();
 
        if (array_key_exists("status", $download) && $download["status"] != 0x00) {
            throw new ServerQueryException($download["msg"], $download["status"]);
        }
 
        $download["cid"] = $cid;
        $download["file"] = $name;
 
        if (!array_key_exists("ip", $download) || $download["ip"]->startsWith("0.0.0.0")) {
            $download["ip"] = $this->getParent()->getAdapterHost();
        } else {
            $download["ip"] = $download["ip"]->section(",");
        }
        $download["host"] = $download["ip"];
 
        Signal::getInstance()->emit("filetransferDownloadInit", $download["ftkey"], $download);
 
        return $download;
    }

    public function transferList(): array
    {
        return $this->request("ftlist")->toAssocArray("serverftfid");
    }

    public function transferStop(int $serverftfid, bool $delete = false): void
    {
        $this->execute("ftstop", ["serverftfid" => $serverftfid, "delete" => $delete]);
    }

    public function iconDownload(string $iconname = null)
    {
        if ($iconname) {
            $name = new StringHelper("/" . $iconname);
        } else {
            $iconid = $this['virtualserver_icon_id'];
            if (!is_int($iconid)) {
                $iconid = $iconid->toInt();
            }
 
            if ($this->iconIsLocal("virtualserver_icon_id") || $iconid == 0) {
                return;
            }
            $name = $this->iconGetName("virtualserver_icon_id");
        }
 
        $download = $this->transferInitDownload(rand(0x0000, 0xFFFF), 0, $name);
        $transfer = TeamSpeak3::factory("filetransfer://" . (str_contains($download["host"], ":") ? "[" . $download["host"] . "]" : $download["host"]) . ":" . $download["port"]);
 
        return $transfer->download($download["ftkey"], $download["size"]);
    }

    public function iconUpload(string $data): int
    {
        $crc = crc32($data);
        $size = strlen($data);
 
        $upload = $this->transferInitUpload(rand(0x0000, 0xFFFF), 0, "/icon_" . $crc, $size);
        $transfer = TeamSpeak3::factory("filetransfer://" . (str_contains($upload["host"], ":") ? "[" . $upload["host"] . "]" : $upload["host"]) . ":" . $upload["port"]);
 
        $transfer->upload($upload["ftkey"], $upload["seekpos"], $data);
 
        return $crc;
    }

    public function modify(array $properties): void
    {
        $this->execute("serveredit", $properties);
        $this->resetNodeInfo();
    }

    public function message(string $msg): void
    {
        $this->execute("sendtextmessage", ["msg" => $msg, "target" => $this->getId(), "targetmode" => TeamSpeak3::TEXTMSG_SERVER]);
    }

    public function messageList(): array
    {
        return $this->request("messagelist")->toAssocArray("msgid");
    }

    public function messageCreate(string $cluid, string $subject, string $message): void
    {
        $this->execute("messageadd", ["cluid" => $cluid, "subject" => $subject, "message" => $message]);
    }

    public function messageDelete(int $msgid): void
    {
        $this->execute("messagedel", ["msgid" => $msgid]);
    }

    public function messageRead(int $msgid, bool $flag_read = true): array
    {
        $msg = $this->execute("messageget", ["msgid" => $msgid])->toList();
 
        if ($flag_read) {
            $this->execute("messageget", ["msgid" => $msgid, "flag" => $flag_read]);
        }
 
        return $msg;
    }

    public function snapshotCreate(int $mode = TeamSpeak3::SNAPSHOT_STRING): string
    {
        $snapshot = $this->request("serversnapshotcreate")->toString(false);
 
        return match ($mode) {
            TeamSpeak3::SNAPSHOT_BASE64 => $snapshot->toBase64(),
            TeamSpeak3::SNAPSHOT_HEXDEC => $snapshot->toHex(),
            default => (string)$snapshot,
        };
    }

    public function snapshotDeploy(string $data, int $mode = TeamSpeak3::SNAPSHOT_STRING): array
    {
        $data = match ($mode) {
            TeamSpeak3::SNAPSHOT_BASE64 => StringHelper::fromBase64($data),
            TeamSpeak3::SNAPSHOT_HEXDEC => StringHelper::fromHex($data),
            default => StringHelper::factory($data),
        };
 
        $detail = $this->request("serversnapshotdeploy -mapping " . $data)->toList();
 
        if (isset($detail[0]["sid"])) {
            Signal::getInstance()->emit("notifyServercreated", $this->getParent(), $detail[0]["sid"]);
 
            $server = array_shift($detail);
        } else {
            $server = [];
        }
 
        $server["mapping"] = $detail;
 
        return $server;
    }

    public function notifyRegister(string $event, int $id = 0): void
    {
        $this->execute("servernotifyregister", ["event" => $event, "id" => $id]);
    }

    public function notifyUnregister(): void
    {
        $this->request("servernotifyunregister");
    }

    public function tokenList(bool $translate = false): array
    {
        return $this->privilegeKeyList();
    }

    public function privilegeKeyList(bool $resolve = false): array
    {
        $tokens = $this->request("privilegekeylist")->toAssocArray("token");
 
        if ($resolve) {
            foreach ($tokens as $token => $array) {
                $func = $array["token_type"] ? "channelGroupGetById" : "serverGroupGetById";
 
                try {
                    $tokens[$token]["token_id1"] = $this->$func($array["token_id1"])->name;
                } catch (NodeException $e) {
                    /* ERROR_channel_invalid_id */
                    if ($e->getCode() != 0xA00) {
                        throw $e;
                    }
                }
 
                if ($array["token_type"]) {
                    $tokens[$token]["token_id2"] = $this->channelGetById($array["token_id2"])->getPathway();
                }
            }
        }
 
        return $tokens;
    }

    public function tokenCreate(
        int $id1,
        int $id2 = 0,
        int $type = TeamSpeak3::TOKEN_SERVERGROUP,
        string $description = null,
        array $customset = null
    ): StringHelper {
        return $this->privilegeKeyCreate($id1, $id2, $type, $description, $customset);
    }

    public function privilegeKeyCreate(
        int    $id1,
        int    $id2 = 0,
        int    $type = TeamSpeak3::TOKEN_SERVERGROUP,
        string $description = null,
        string $customset = null
    ): StringHelper {
        $token = $this->execute("privilegekeyadd", ["tokentype" => $type, "tokenid1" => $id1, "tokenid2" => $id2, "tokendescription" => $description, "tokencustomset" => $customset])
            ->toList();
 
        Signal::getInstance()->emit("notifyTokencreated", $this, $token["token"]);
 
        return $token["token"];
    }

    public function tokenDelete($token)
    {
        $this->privilegeKeyDelete($token);
    }

    public function privilegeKeyDelete(string $token): void
    {
        $this->execute("privilegekeydelete", ["token" => $token]);
    }

    public function tokenUse($token)
    {
        $this->privilegeKeyUse($token);
    }

    public function privilegeKeyUse(string $token): void
    {
        $this->execute("privilegekeyuse", ["token" => $token]);
    }

    public function customSearch(string $ident, string $pattern = "%"): array
    {
        return $this->execute("customsearch", ["ident" => $ident, "pattern" => $pattern])->toArray();
    }

    public function customInfo(int $cldbid): array
    {
        return $this->execute("custominfo", ["cldbid" => $cldbid])->toArray();
    }

    public function customSet(int $cldbid, string $ident, string $value): void
    {
        $this->execute("customset", ["cldbid" => $cldbid, "ident" => $ident, "value" => $value]);
    }

    public function customDelete(int $cldbid, string $ident): void
    {
        $this->execute("customdelete", ["cldbid" => $cldbid, "ident" => $ident]);
    }

    public function banList($offset = null, $limit = null): array
    {
        return $this->execute("banlist -count", ["start" => $offset, "duration" => $limit])->toAssocArray("banid");
    }

    public function banCount(): int
    {
        return current($this->execute("banlist -count", ["duration" => 1])->toList("count"));
    }

    public function banListClear(): void
    {
        $this->request("bandelall");
    }

    public function banCreate(array $rules, int $timeseconds = null, string $reason = null): int
    {
        $rules["time"] = $timeseconds;
        $rules["banreason"] = $reason;
 
        $banid = $this->execute("banadd", $rules)->toList();
 
        return $banid["banid"];
    }

    public function banDelete(int $banid): void
    {
        $this->execute("bandel", ["banid" => $banid]);
    }

    public function complaintList(int $tcldbid = null): array
    {
        return $this->execute("complainlist", ["tcldbid" => $tcldbid])->toArray();
    }

    public function complaintListClear(int $tcldbid): void
    {
        $this->execute("complaindelall", ["tcldbid" => $tcldbid]);
    }

    public function complaintCreate(int $tcldbid, string $message): void
    {
        $this->execute("complainadd", ["tcldbid" => $tcldbid, "message" => $message]);
    }

    public function complaintDelete(int $tcldbid, int $fcldbid): void
    {
        $this->execute("complaindel", ["tcldbid" => $tcldbid, "fcldbid" => $fcldbid]);
    }

    public function tempPasswordList(bool $resolve = false): array
    {
        $passwords = $this->request("servertemppasswordlist")->toAssocArray("pw_clear");
 
        if ($resolve) {
            foreach ($passwords as $password => $array) {
                $channel = $this->channelGetById($array["tcid"]);
 
                $passwords[$password]["tcname"] = $channel->toString();
                $passwords[$password]["tcpath"] = $channel->getPathway();
            }
        }
 
        return $passwords;
    }

    public function tempPasswordCreate(string $pw, int $duration, int $tcid = 0, string $tcpw = "", string $desc = ""): void
    {
        $this->execute("servertemppasswordadd", ["pw" => $pw, "duration" => $duration, "tcid" => $tcid, "tcpw" => $tcpw, "desc" => $desc]);
    }

    public function tempPasswordDelete(string $pw): void
    {
        $this->execute("servertemppassworddel", ["pw" => $pw]);
    }

    public function logView(int $lines = 30, int $begin_pos = null, bool $reverse = null, bool $instance = null): array
    {
        return $this->execute("logview", ["lines" => $lines, "begin_pos" => $begin_pos, "instance" => $instance, "reverse" => $reverse])
            ->toArray();
    }

    public function logAdd(string $logmsg, int $loglevel = TeamSpeak3::LOGLEVEL_INFO): void
    {
        $this->execute("logadd", ["logmsg" => $logmsg, "loglevel" => $loglevel]);
    }

    public function connectionInfo(): array
    {
        return $this->request("serverrequestconnectioninfo")->toList();
    }

    public function delete(): void
    {
        $this->getParent()->serverDelete($this->getId());
    }

    public function start(): void
    {
        $this->getParent()->serverStart($this->getId());
    }

    public function stop(string $msg = null): void
    {
        $this->getParent()->serverStop($this->getId(), $msg);
    }

    public function sendPluginCmd(string $plugin, string $data): void
    {
        $this->execute("plugincmd", ["name" => $plugin, "data" => $data, "targetmode" => TeamSpeak3::PLUGINCMD_SERVER]);
    }

    public function selfUpdate(array $properties): void
    {
        $this->execute("clientupdate", $properties);
 
        foreach ($properties as $ident => $value) {
            $this->whoamiSet($ident, $value);
        }
    }

    public function selfUpdateLogin(string $username): StringHelper
    {
        $password = $this->execute("clientsetserverquerylogin", ["client_login_name" => $username])->toList();
 
        return $password["client_login_password"];
    }

    public function selfPermOverview(): array
    {
        return $this->execute("permoverview", ["cldbid" => $this->whoamiGet("client_database_id"), "cid" => $this->whoamiGet("client_channel_id"), "permid" => 0])
            ->toArray();
    }

    protected function fetchNodeList()
    {
        $this->nodeList = [];
 
        foreach ($this->channelList() as $channel) {
            if ($channel["pid"] == 0) {
                $this->nodeList[] = $channel;
            }
        }
    }

    protected function fetchNodeInfo()
    {
        $this->nodeInfo = array_merge($this->nodeInfo, $this->request("serverinfo")->toList());
    }

    protected static function sortClientList(Client $a, Client $b): int
    {
        if (get_class($a) != get_class($b)) {
            return 0;
        }
 
        if ($a->getProperty("client_talk_power", 0) != $b->getProperty("client_talk_power", 0)) {
            return ($a->getProperty("client_talk_power", 0) > $b->getProperty("client_talk_power", 0)) ? -1 : 1;
        }
 
        if ($a->getProperty("client_is_talker", 0) != $b->getProperty("client_is_talker", 0)) {
            return ($a->getProperty("client_is_talker", 0) > $b->getProperty("client_is_talker", 0)) ? -1 : 1;
        }
 
        return strcmp(strtolower($a["client_nickname"]), strtolower($b["client_nickname"]));
    }

    protected static function sortGroupList(Node $a, Node $b): int
    {
        if (get_class($a) != get_class($b)) {
            return 0;
        }
 
        if (!$a instanceof ServerGroup && !$a instanceof ChannelGroup) {
            return 0;
        }
 
        if ($a->getProperty("sortid", 0) != $b->getProperty("sortid", 0) && $a->getProperty("sortid", 0) != 0 && $b->getProperty("sortid", 0) != 0) {
            return ($a->getProperty("sortid", 0) < $b->getProperty("sortid", 0)) ? -1 : 1;
        }
 
        return ($a->getId() < $b->getId()) ? -1 : 1;
    }

    protected static function sortFileList(array $a, array $b): int
    {
        if (!array_key_exists("src", $a) || !array_key_exists("src", $b) || !array_key_exists("type", $a) || !array_key_exists("type", $b)) {
            return 0;
        }
 
        if ($a["type"] != $b["type"]) {
            return ($a["type"] < $b["type"]) ? -1 : 1;
        }
 
        return strcmp(strtolower($a["src"]), strtolower($b["src"]));
    }

    public function isOnline(): bool
    {
        return $this["virtualserver_status"] == "online";
    }

    public function isOffline(): bool
    {
        return $this["virtualserver_status"] == "offline";
    }

    public function getUniqueId(): string
    {
        return $this->getParent()->getUniqueId() . "_s" . $this->getId();
    }

    public function getIcon(): string
    {
        if ($this["virtualserver_clientsonline"] - $this["virtualserver_queryclientsonline"] >= $this["virtualserver_maxclients"]) {
            return "server_full";
        } elseif ($this["virtualserver_flag_password"]) {
            return "server_pass";
        } else {
            return "server_open";
        }
    }

    public function getSymbol(): string
    {
        return "$";
    }

    public function __toString()
    {
        return (string)$this["virtualserver_name"];
    }
}