Files

T

2026-07-20 19:01:03 +08:00

40 KiB

Raw Blame History

Bridge 层 API 文档

本文档是 go/teamspeak/bridge.go + go/teamspeak/kotlin_api.go 的完整 API 参考。两个文件共同构成 gomobile 导出的 teamspeak 包，供 Kotlin 侧通过 TSBridge 调用。

gomobile 导出约定：

返回 string：空字符串 "" = 成功，非空 = 错误信息

返回 JSON string：查询结果以 JSON 编码，"[]" / "{}" 表示空或错误

不支持 []string、[]*T、error 等 Go 类型，复杂数据一律通过 JSON 传递

回调通过 EventCallback 接口定义，所有 JNI 回调在同一线程顺序执行

一、客户端构造

NewClient

名字	触发形式	用法	作用	详细描述
`NewClient`	本地调用	`NewClient() *TSClient`	创建客户端实例	创建一个空的 TSClient 实例。不建立网络连接，不生成 Identity。需要随后调用 `Connect` 或 `ConnectWithIdentity` 发起连接。

二、Identity 管理

GenerateIdentity

名字	触发形式	用法	作用	详细描述
`GenerateIdentity`	本地调用	`GenerateIdentity(securityLevel int) string`	生成加密身份	生成 TeamSpeak 加密身份（ECDSA P-256 密钥对），返回序列化字符串 `"base64PrivateKey:offset"`。`securityLevel` 推荐值 8（2048-bit RSA challenge），值越大生成越慢。Kotlin 侧应将返回值持久化到 SharedPreferences / DataStore，后续通过 `ConnectWithIdentity` 复用。返回空字符串表示生成失败。

ConnectWithIdentity

名字	触发形式	用法	作用	详细描述
`ConnectWithIdentity`	客户端请求	`(c *TSClient) ConnectWithIdentity(identityStr, host, nickname, password, defaultChannel, defaultChannelPassword string, cb EventCallback) string`	用已有身份连接	使用 `GenerateIdentity` 生成并持久化的 identity 字符串连接服务器。与 `Connect` 行为相同（注册事件 → 发起 UDP 连接 → 等待握手完成，30 秒超时），但复用已有身份而非每次生成新的。`password`、`defaultChannel`、`defaultChannelPassword` 为空时忽略。返回空字符串表示连接成功。

三、连接管理

Connect

名字	触发形式	用法	作用	详细描述
`Connect`	客户端请求	`(c *TSClient) Connect(host, nickname, password, defaultChannel, defaultChannelPassword string, cb EventCallback) string`	连接服务器	每次生成新 Identity，注册全部事件回调，发起 UDP 连接并等待握手完成（30 秒超时）。`host` 支持域名/IP/TSDNS，可带端口号（默认 9987）。`password` 为服务器密码（可选）。`defaultChannel` 为连接后自动加入的频道名（可选）。`defaultChannelPassword` 为默认频道密码（可选）。返回空字符串表示连接成功。

Disconnect

名字	触发形式	用法	作用	详细描述
`Disconnect`	客户端请求	`(c *TSClient) Disconnect()`	断开连接	停止事件消费协程，发送 disconnect 命令通知服务器，清理客户端状态。断开后触发 `OnDisconnected` 回调。可安全重复调用。

IsConnected

名字	触发形式	用法	作用	详细描述
`IsConnected`	本地调用	`(c *TSClient) IsConnected() bool`	查询连接状态	返回当前是否已连接且客户端实例有效。线程安全。

GetClientID

名字	触发形式	用法	作用	详细描述
`GetClientID`	本地调用	`(c *TSClient) GetClientID() int`	获取自身客户端 ID	返回服务器分配的当前客户端 ID（clid）。未连接时返回 0。ID 由 SDK 本地缓存，不产生网络请求。

GetChannelID

名字	触发形式	用法	作用	详细描述
`GetChannelID`	客户端请求	`(c *TSClient) GetChannelID() string`	获取自身所在频道 ID	通过 `clientinfo clid=self` 查询当前客户端所在频道 ID。返回频道 ID 字符串，未连接或查询失败返回 `"0"`。

四、频道查询

GetChannelsJSON

名字	触发形式	用法	作用	详细描述
`GetChannelsJSON`	客户端请求	`(c *TSClient) GetChannelsJSON() string`	获取基础频道列表	调用 `channellist` 协议命令，返回 JSON 数组。每个元素包含 `id`、`name`、`parentId`、`description` 四个字段。ID 和 ParentID 均为字符串格式的 uint64。未连接返回 `"[]"`。

返回示例：

[{"id":"1","name":"Lobby","parentId":"0","description":""}]

GetChannelsDetailedJSON

名字	触发形式	用法	作用	详细描述
`GetChannelsDetailedJSON`	客户端请求	`(c *TSClient) GetChannelsDetailedJSON() string`	获取详细频道列表	调用 `channellist -topic -flags -voice -limits -icon` 协议命令，返回 JSON 数组。比 `GetChannelsJSON` 多出 14 个字段：`topic`、`order`、`codec`、`codecQuality`、`neededTalkPower`、`maxClients`、`maxFamilyClients`、`isMaxClientsUnlimited`、`isMaxFamilyClientsUnlimited`、`isPermanent`、`isSemiPermanent`、`isDefault`、`isPassword`、`isOrdered`、`iconId`、`neededModifyPower`。用于频道列表页 UI 渲染（密码图标🔒、永久标记📌、人数限制👥等）。未连接返回 `"[]"`。

返回示例：

[{
  "id": "1", "name": "Lobby", "parentId": "0", "topic": "欢迎",
  "order": "0", "codec": 4, "codecQuality": 7, "neededTalkPower": 0,
  "maxClients": -1, "maxFamilyClients": -1,
  "isMaxClientsUnlimited": true, "isMaxFamilyClientsUnlimited": true,
  "isPermanent": true, "isSemiPermanent": false, "isDefault": true,
  "isPassword": false, "isOrdered": false, "iconId": "0", "neededModifyPower": 75
}]

ListChannelsSortedJSON

名字	触发形式	用法	作用	详细描述
`ListChannelsSortedJSON`	客户端请求	`(c *TSClient) ListChannelsSortedJSON() string`	获取去重+排序的详细频道列表	底层同样调用 `channellist -topic -flags -voice -limits -icon`，但额外处理：①按 ID 去重（保留最后出现的条目）；②按 `channel_order` 排序，先顶层频道再子频道（树形扁平化：顶层频道按 order 排序，每个频道的子频道紧跟其后并按 order 排序）。返回 JSON 数组，字段与 `GetChannelsDetailedJSON` 完全一致。适合频道列表页直接展示，无需客户端侧再做排序和去重。未连接返回 `"[]"`。

GetChannelDetailInfoJSON

名字	触发形式	用法	作用	详细描述
`GetChannelDetailInfoJSON`	客户端请求	`(c *TSClient) GetChannelDetailInfoJSON(channelIDStr string) string`	获取单频道详情	调用 `channelinfo cid=X` 协议命令，返回 JSON 对象。与 `GetChannelsDetailedJSON` 的区别：本方法返回单个频道的完整信息（含 `description` 完整描述和 `bannerGfxUrl`），适合频道详情面板展示。`channelIDStr` 为频道 ID 字符串。未连接或无效 ID 返回 `"{}"`。

返回示例：

{
  "id": "1", "parentId": "0", "name": "Lobby", "topic": "欢迎",
  "description": "这是频道的完整描述...", "codec": 4, "codecQuality": 7,
  "maxClients": -1, "maxFamilyClients": -1, "neededTalkPower": 0,
  "iconId": "0", "isPermanent": true, "isSemiPermanent": false,
  "isDefault": true, "isPassword": false, "order": "0", "bannerGfxUrl": ""
}

FindChannelsJSON

名字	触发形式	用法	作用	详细描述
`FindChannelsJSON`	客户端请求	`(c *TSClient) FindChannelsJSON(pattern string) string`	按名称搜索频道	调用 `channelfind pattern=X` 协议命令，返回 JSON 数组。每个元素包含 `id` 和 `name`。`pattern` 支持通配符。用于频道搜索/快速跳转功能。未连接或无匹配返回 `"[]"`。

返回示例：

[{"id":"5","name":"Gaming Room"},{"id":"12","name":"Gaming Lounge"}]

五、客户端查询

GetClientsJSON

名字	触发形式	用法	作用	详细描述
`GetClientsJSON`	客户端请求	`(c *TSClient) GetClientsJSON() string`	获取在线客户端列表	调用 `clientlist -uid -away -voice -groups` 协议命令，返回 JSON 数组。每个元素包含 `id`（clid）、`nickname`、`uid`、`channelId`、`serverGroups`（字符串数组）、`isSelf`（是否是当前用户）。自动比对 `ClientID()` 标记 `isSelf` 字段。未连接返回 `"[]"`。

返回示例：

[
  {"id":1,"nickname":"Admin","uid":"abc123","channelId":"1","serverGroups":["6","9"],"isSelf":true},
  {"id":2,"nickname":"User","uid":"def456","channelId":"2","serverGroups":[],"isSelf":false}
]

GetClientDetailInfoJSON

名字	触发形式	用法	作用	详细描述
`GetClientDetailInfoJSON`	客户端请求	`(c *TSClient) GetClientDetailInfoJSON(clid int) string`	获取单客户端详情	调用 `clientinfo clid=X` 协议命令，返回 JSON 对象。比 `GetClientsJSON` 的列表项多出 `away`、`awayMessage`、`inputMuted`、`outputMuted`、`platform`、`version`、`ip`、`created`、`lastConnected`、`totalConnections`、`description`、`iconId` 等字段。用于点击客户端后的详情弹窗。`clid` 为客户端 ID。未连接返回 `"{}"`。

返回示例：

{
  "id": "1", "nickname": "Admin", "uid": "abc123", "channelId": "1",
  "type": 0, "serverGroups": ["6","9"],
  "away": false, "awayMessage": "", "inputMuted": false, "outputMuted": false,
  "platform": "Windows", "version": "3.x.x", "ip": "192.168.1.1",
  "created": "1700000000", "lastConnected": "1710000000", "totalConnections": 42,
  "description": "", "iconId": "0"
}

FindClientByNameJSON

名字	触发形式	用法	作用	详细描述
`FindClientByNameJSON`	客户端请求	`(c *TSClient) FindClientByNameJSON(nickname string) string`	按昵称搜索数据库客户端	调用 `clientdbfind pattern=X -uid` 协议命令，返回 JSON 对象 `{"uid":"xxx","dbid":"123"}`。搜索服务器数据库中注册过的客户端（不要求在线）。未连接或无匹配返回 `"{}"`。

FindClientByDBIDJSON

名字	触发形式	用法	作用	详细描述
`FindClientByDBIDJSON`	客户端请求	`(c *TSClient) FindClientByDBIDJSON(dbidStr string) string`	按 DBID 查找客户端 UID	调用 `clientdbfind -uid cldbid=X` 协议命令，返回 JSON 对象 `{"uid":"xxx"}`。通过数据库 ID 反查唯一标识。`dbidStr` 为数据库 ID 字符串。未连接或无匹配返回 `"{}"`。

ListDBClientsJSON

名字	触发形式	用法	作用	详细描述
`ListDBClientsJSON`	客户端请求	`(c *TSClient) ListDBClientsJSON(start, duration int) string`	获取数据库客户端列表	调用 `clientdblist start=X duration=X` 协议命令，返回 JSON 数组。每个元素包含 `dbid`、`uid`、`nickname`、`created`、`lastConnected`、`totalConnections`、`description`。`start` 为起始位置，`duration` 为返回数量（0=全部）。用于管理功能中的用户数据库浏览。未连接返回 `"[]"`。

六、服务器信息

GetServerInfoJSON

名字	触发形式	用法	作用	详细描述
`GetServerInfoJSON`	客户端请求	`(c *TSClient) GetServerInfoJSON() string`	获取服务器信息	调用 `serverinfo` 协议命令，返回 JSON 对象。包含 `name`（服务器名）、`welcomeMessage`、`maxClients`、`clientsOnline`、`channelsOnline`、`uptime`（运行秒数）、`version`、`platform`、`created`（创建时间戳）、`iconId`、`defaultServerGroup`、`defaultChannelGroup`。用于服务器详情展示。未连接返回 `"{}"`。

返回示例：

{
  "name": "My TeamSpeak Server", "welcomeMessage": "Welcome!",
  "maxClients": 100, "clientsOnline": 5, "channelsOnline": 3,
  "uptime": "86400", "version": "3.13.7", "platform": "Linux",
  "created": "1700000000", "iconId": "0",
  "defaultServerGroup": 8, "defaultChannelGroup": 1
}

七、文本消息与 Poke

SendTextMessage

名字	触发形式	用法	作用	详细描述
`SendTextMessage`	客户端请求	`(c *TSClient) SendTextMessage(targetMode int, targetIDStr string, message string) string`	发送文字消息	发送文本消息到指定目标。`targetMode`: 1=私聊（target 为客户端 ID）、2=频道消息（target 为频道 ID）、3=服务器消息（target 忽略）。`targetIDStr` 为目标 ID 字符串。`message` 为消息内容。返回空字符串表示发送成功。

SendChannelMessage

名字	触发形式	用法	作用	详细描述
`SendChannelMessage`	客户端请求	`(c *TSClient) SendChannelMessage(channelIDStr, message string) string`	发送频道消息	`SendTextMessage(targetMode=2, ...)` 的快捷方式。`channelIDStr` 为频道 ID 字符串。返回空字符串表示发送成功。

Poke

名字	触发形式	用法	作用	详细描述
`Poke`	客户端请求	`(c *TSClient) Poke(clidStr string, message string) string`	发送 Poke	向指定客户端发送 Poke（戳一戳）消息。`clidStr` 为目标客户端 ID 字符串。`message` 为 Poke 文本。对方会收到弹窗通知。返回空字符串表示发送成功。

八、频道切换与客户端移动

MoveToChannel

名字	触发形式	用法	作用	详细描述
`MoveToChannel`	客户端请求	`(c *TSClient) MoveToChannel(channelIDStr, password string) string`	移动自己到目标频道	将当前客户端移动到指定频道。`channelIDStr` 为目标频道 ID 字符串。`password` 为频道密码（无密码传空字符串）。调用 `ClientMove(selfID, channelID, password)`。返回空字符串表示命令已发送，实际移动需等待 `OnClientMoved` 事件确认。

MoveClient

名字	触发形式	用法	作用	详细描述
`MoveClient`	客户端请求	`(c *TSClient) MoveClient(clientID int, channelIDStr, password string) string`	移动指定客户端到目标频道	将任意客户端移动到指定频道（需要权限）。`clientID` 为要移动的客户端 ID（clid）。`channelIDStr` 为目标频道 ID 字符串。`password` 为频道密码（可选）。返回空字符串表示命令已发送。

MoveChannel

名字	触发形式	用法	作用	详细描述
`MoveChannel`	客户端请求	`(c *TSClient) MoveChannel(channelIDStr, parentIDStr, orderStr string) string`	移动频道位置	移动频道到新的父频道下或调整排序。`channelIDStr` 为要移动的频道 ID。`parentIDStr` 为新的父频道 ID（`"0"` = 顶层）。`orderStr` 为排序位置（`"0"` = 最顶部）。返回空字符串表示成功。

九、频道管理

CreateChannelJSON

名字	触发形式	用法	作用	详细描述
`CreateChannelJSON`	客户端请求	`(c *TSClient) CreateChannelJSON(name, propertiesJSON string) string`	创建频道	调用 `channelcreate channel_name=X [params...]`。`name` 为频道名。`propertiesJSON` 为 JSON 对象，包含可选属性如 `{"channel_topic":"主题","channel_flag_permanent":"1","cpid":"父频道ID","channel_password":"密码","channel_maxclients":"10","channel_codec":"4"}`。返回新频道 ID 字符串，空字符串表示失败。

EditChannelJSON

名字	触发形式	用法	作用	详细描述
`EditChannelJSON`	客户端请求	`(c *TSClient) EditChannelJSON(channelIDStr, propertiesJSON string) string`	编辑频道属性	调用 `channeledit cid=X [params...]`。`channelIDStr` 为频道 ID 字符串。`propertiesJSON` 为 JSON 对象，包含要修改的属性。返回空字符串表示成功。

DeleteChannel

名字	触发形式	用法	作用	详细描述
`DeleteChannel`	客户端请求	`(c *TSClient) DeleteChannel(channelIDStr string, force bool) string`	删除频道	调用 `channeldelete cid=X force=X`。`channelIDStr` 为频道 ID 字符串。`force=true` 强制删除（含子频道），`false` 仅在频道为空时删除。返回空字符串表示成功。

十、客户端管理

UpdateSelfJSON

名字	触发形式	用法	作用	详细描述
`UpdateSelfJSON`	客户端请求	`(c *TSClient) UpdateSelfJSON(propertiesJSON string) string`	更新自身属性	调用 `clientupdate [params...]`。`propertiesJSON` 为 JSON 对象。常用参数：`client_nickname`（新昵称）、`client_away`（`"1"`/`"0"` 离开状态）、`client_away_message`（离开消息）、`client_input_muted`（`"1"`/`"0"` 输入静音）、`client_output_muted`（`"1"`/`"0"` 输出静音）、`client_phonetic_nickname`（语音昵称）。返回空字符串表示成功。

用法示例：

UpdateSelfJSON('{"client_nickname":"NewName","client_away":"1","client_away_message":"AFK"}')

KickClient

名字	触发形式	用法	作用	详细描述
`KickClient`	客户端请求	`(c *TSClient) KickClient(clid int, reasonID int, reasonMsg string) string`	踢出客户端	调用 `clientkick clid=X reasonid=X reasonmsg=X`。`clid` 为客户端 ID。`reasonID`: 4=从频道踢出，5=从服务器踢出。`reasonMsg` 为踢出原因文本。返回空字符串表示成功。

十一、语音

SendVoice

名字	触发形式	用法	作用	详细描述
`SendVoice`	客户端请求	`(c *TSClient) SendVoice(data []byte, codec int64) string`	发送语音帧	发送原始 Opus 编码的语音帧到当前频道。`data` 为 Opus 编码的音频数据（20ms 帧）。`codec`: 4=Opus Voice（语音通话，默认），5=Opus Music（高保真音频）。通过 UDP 传输。返回空字符串表示发送成功。

十二、Ban 管理

ListBansJSON

名字	触发形式	用法	作用	详细描述
`ListBansJSON`	客户端请求	`(c *TSClient) ListBansJSON() string`	获取封禁列表	调用 `banlist` 协议命令，返回 JSON 数组。每个元素包含 `banId`、`ip`、`name`、`uid`、`created`（时间戳）、`invokerName`（操作者）、`invokerUid`、`reason`、`enforcement`（是否立即执行）。未连接返回 `"[]"`。

AddBan

名字	触发形式	用法	作用	详细描述
`AddBan`	客户端请求	`(c *TSClient) AddBan(ip, name, uid string, timeSeconds int, reason string) string`	添加封禁	调用 `banadd ip=X name=X uid=X time=X banreason=X`。`ip`/`name`/`uid` 至少指定一个，可组合使用。`timeSeconds` 为封禁时长（秒），0=永久。`reason` 为封禁原因（可选）。返回空字符串表示成功。

DeleteBan

名字	触发形式	用法	作用	详细描述
`DeleteBan`	客户端请求	`(c *TSClient) DeleteBan(banIDStr string) string`	删除封禁	调用 `bandel banid=X`。`banIDStr` 为封禁 ID 字符串（从 `ListBansJSON` 获取）。返回空字符串表示成功。

DeleteAllBans

名字	触发形式	用法	作用	详细描述
`DeleteAllBans`	客户端请求	`(c *TSClient) DeleteAllBans() string`	清除所有封禁	调用 `bandelall` 协议命令，删除服务器上的全部封禁记录。返回空字符串表示成功。

十三、Token 管理

ListTokensJSON

名字	触发形式	用法	作用	详细描述
`ListTokensJSON`	客户端请求	`(c *TSClient) ListTokensJSON() string`	获取权限密钥列表	调用 `tokenlist` 协议命令，返回 JSON 数组。每个元素包含 `token`（密钥字符串）、`tokenType`（0=服务器组, 1=频道组）、`tokenId1`（组 ID）、`tokenId2`（频道 ID，仅 tokenType=1）、`created`（创建时间戳）、`description`。未连接返回 `"[]"`。

UseToken

名字	触发形式	用法	作用	详细描述
`UseToken`	客户端请求	`(c *TSClient) UseToken(token string) string`	激活权限密钥	调用 `tokenuse token=X`。`token` 为权限密钥字符串。激活后自动获得对应的服务器组或频道组权限。返回空字符串表示成功。

十四、投诉管理

ListComplaintsJSON

名字	触发形式	用法	作用	详细描述
`ListComplaintsJSON`	客户端请求	`(c *TSClient) ListComplaintsJSON(targetDBIDStr string) string`	获取投诉列表	调用 `complainlist [tcldbid=X]` 协议命令，返回 JSON 数组。每个元素包含 `fromDbid`（投诉者 DBID）、`toDbid`（被投诉者 DBID）、`message`（投诉内容）、`timestamp`（投诉时间戳）。`targetDBIDStr` 为 `"0"` 或空字符串时返回全部投诉。未连接返回 `"[]"`。

AddComplaint

名字	触发形式	用法	作用	详细描述
`AddComplaint`	客户端请求	`(c *TSClient) AddComplaint(targetDBIDStr, message string) string`	提交投诉	调用 `complainadd tcldbid=X message=X`。`targetDBIDStr` 为被投诉者的数据库 ID 字符串。`message` 为投诉内容。返回空字符串表示成功。

DeleteComplaint

名字	触发形式	用法	作用	详细描述
`DeleteComplaint`	客户端请求	`(c *TSClient) DeleteComplaint(targetDBIDStr, fromDBIDStr string) string`	删除投诉	调用 `complaindel tcldbid=X fcldbid=X`。`targetDBIDStr` 为被投诉者 DBID，`fromDBIDStr` 为投诉者 DBID。返回空字符串表示成功。

十五、文件传输

ListFilesJSON

名字	触发形式	用法	作用	详细描述
`ListFilesJSON`	客户端请求	`(c *TSClient) ListFilesJSON(channelIDStr, path string) string`	获取频道文件列表	调用 `ftgetfilelist cid=X path=X` 协议命令，返回 JSON 数组。每个元素包含 `name`（文件/目录名）、`size`（字节数，目录为 0）、`dateTime`（修改时间戳）、`isFile`（true=文件, false=目录）。`channelIDStr` 为频道 ID 字符串。`path` 为虚拟路径，根目录为 `"/"`。未连接返回 `"[]"`。

FileTransferInitUploadJSON

名字	触发形式	用法	作用	详细描述
`FileTransferInitUploadJSON`	客户端请求	`(c *TSClient) FileTransferInitUploadJSON(channelIDStr, path string, size int64, overwrite bool) string`	初始化文件上传	调用 `ftinitupload cid=X path=X size=X overwrite=X`，等待服务器返回传输参数。返回 JSON 对象：`port`（TCP 端口）、`key`（传输密钥）、`clientFileTransferID`、`serverFileTransferID`、`seekPosition`（断点续传位置）。`channelIDStr` 为频道 ID。`path` 为目标路径。`size` 为文件字节数。`overwrite` 为是否覆盖。TCP 连接 host 为当前服务器地址。未连接返回 `"{}"`。

FileTransferInitDownloadJSON

名字	触发形式	用法	作用	详细描述
`FileTransferInitDownloadJSON`	客户端请求	`(c *TSClient) FileTransferInitDownloadJSON(channelIDStr, path string) string`	初始化文件下载	调用 `ftinitdownload cid=X path=X`，等待服务器返回传输参数。返回 JSON 对象：`port`（TCP 端口）、`key`（传输密钥）、`size`（文件字节数）、`clientFileTransferID`、`serverFileTransferID`。`channelIDStr` 为频道 ID。`path` 为源路径。未连接返回 `"{}"`。

DeleteFile

名字	触发形式	用法	作用	详细描述
`DeleteFile`	客户端请求	`(c *TSClient) DeleteFile(channelIDStr, pathsJSON string) string`	删除频道文件	调用 `ftdeletefile cid=X path=X [path2=X ...]`。`channelIDStr` 为频道 ID 字符串。`pathsJSON` 为要删除的文件路径 JSON 数组，如 `["/file1.txt","/dir/file2.txt"]`。返回空字符串表示成功。

十六、批量查询

GetInitialSyncJSON

名字	触发形式	用法	作用	详细描述
`GetInitialSyncJSON`	客户端请求	`(c *TSClient) GetInitialSyncJSON() string`	首次同步批量查询	一次性返回连接后首次同步所需的全部数据，将 4 次 JNI 调用合并为 1 次。内部依次调用 `GetChannelsDetailedJSON`、`GetClientsJSON`、`GetClientID`、`GetChannelID`、`GetServerInfoJSON`，合并为单个 JSON 对象返回。任一子查询失败时对应字段为 null/空，不影响其他字段。未连接返回 `"{}"`。

返回格式：

{
  "channels": [
    {"id":"1","name":"Lobby","parentId":"0","topic":"","order":"0","codec":4,...}
  ],
  "clients": [
    {"id":1,"nickname":"Admin","uid":"abc","channelId":"1","serverGroups":[],"isSelf":true}
  ],
  "selfId": 1,
  "selfChannelId": "1",
  "server": {
    "name":"My Server","welcomeMessage":"","maxClients":100,"clientsOnline":5,...
  }
}

十七、事件回调接口

EventCallback

所有事件通过 EventCallback 接口回调。Kotlin 侧实现此接口并传入 Connect 或 ConnectWithIdentity。所有回调在同一个 goroutine 中顺序执行（通过内部事件队列保证），无需担心并发问题。

回调方法	触发时机	参数	描述
`OnConnected()`	连接握手完成	无	服务器握手成功，可以开始发送业务命令。此时应执行首次同步（调用 `GetInitialSyncJSON`）。
`OnDisconnected(message string)`	连接断开	`message`: 错误原因	网络中断或服务器主动断开。`message` 为空表示正常断开。此时应清理 UI 状态并提示用户。
`OnTextMessage(msg *TextMsg)`	收到文本消息	`msg.TargetMode`: 1=私聊/2=频道/3=服务器；`msg.TargetID`: 目标 ID；`msg.InvokerName`: 发送者昵称；`msg.InvokerUID`: 发送者 UID；`msg.Message`: 消息内容	收到其他客户端发送的文本消息。按 TargetMode + Target 归档到正确的会话。
`OnClientEnter(client *Client)`	用户进入视野	`client.ID`: 客户端 ID；`client.Nickname`: 昵称；`client.UID`: UID；`client.ChannelID`: 所在频道 ID	新客户端进入服务器。应添加到本地成员表。`client.ChannelID` 来自 `notifycliententerview`，可能不准确，需补偿同步。
`OnClientLeave(id int, reasonMsg string)`	用户离开	`id`: 客户端 ID；`reasonMsg`: 离开原因	客户端离开服务器。应从本地成员表移除。
`OnClientMoved(id int, targetChannelID string)`	用户移动频道	`id`: 客户端 ID；`targetChannelID`: 目标频道 ID	客户端在频道间移动。当 `id == GetClientID()` 时，表示自己被移动（含密码验证结果）。应更新成员所在频道。
`OnKicked(reason string)`	被踢出	`reason`: 踢出原因	自己被从频道或服务器踢出。应停止语音采集，清理会话状态，显示被踢原因并允许重连。
`OnVoiceData(clientID int, data []byte, codec int)`	收到语音	`clientID`: 发送者 ID；`data`: Opus 编码帧；`codec`: 4=Opus Voice/5=Opus Music	收到同频道其他客户端的语音数据。`data` 可直接送入 Opus 解码器。回调中不要做耗时操作，应推入 channel 由独立协程解码播放。
`OnPoked(event *PokeEvent)`	被 Poke	`event.InvokerID`: 发送者 ID；`event.InvokerName`: 发送者昵称；`event.InvokerUID`: 发送者 UID；`event.Message`: Poke 消息	收到其他用户的 Poke 消息。应显示 Toast 或弹窗通知。

Kotlin 侧事件处理流程

以下三个事件在 Android 端有完整的 UI 处理链路：

被管理员移动到指定频道（OnClientMoved）

Go SDK notifyclientmoved
  → EventCallback.OnClientMoved(id, targetChannelID)
  → TSBridge 转发
  → ChannelViewModel.handleClientMoved()
      → 判断 id == selfId → 标记为"被外部移动"
      → 更新 _currentChannelId
      → refreshClientList() 刷新当前频道成员
  → UI 自动更新频道列表和成员列表

日志标识: Client moved: {id} -> channel {channelID}、Self moved by external action to channel {channelID}

收到频道内文本消息（OnTextMessage, targetMode=2）

Go SDK notifytextmessage
  → EventCallback.OnTextMessage(msg)
  → TSBridge 转发
  → ServerViewModel.handleTextMessage()
      → 解析 senderId（通过 clientlist 匹配 invokerUID）
      → 转发给 ChatViewModel
  → ChatViewModel.handleTextMessage()
      → 判断 targetMode=2（频道消息）
      → 归档到对应会话（频道 ID 为 key）
      → 如果匹配当前打开的聊天，更新实时消息列表

日志标识: onTextMessage: targetMode=2, targetID={channelID}, invokerName={name}, message={content}

被 Poke 带文本消息（OnPoked）

Go SDK notifyclientpoke
  → EventCallback.OnPoked(event)
  → TSBridge 转发
  → ServerViewModel.handlePoked()
      → 更新 _pokeNotification 状态
      → triggerVibration() 震动反馈（需 VIBRATE 权限）
      → 5 秒后自动隐藏通知
  → UI 显示 Poke 弹窗（发送者昵称 + 消息内容）

日志标识: Poked by {name}: {message}

注意: Poke 震动需要 android.permission.VIBRATE 权限（AndroidManifest.xml 中声明即可，无需运行时请求）。

十八、导出数据类型

以下类型通过 gomobile 导出到 Kotlin 侧，可直接在回调参数中使用。

Channel

字段	类型	描述
`ID`	`string`	频道 ID
`Name`	`string`	频道名称
`ParentID`	`string`	父频道 ID
`Description`	`string`	频道描述

Client

字段	类型	描述
`ID`	`int`	客户端 ID（clid）
`Nickname`	`string`	昵称
`UID`	`string`	唯一标识
`ChannelID`	`string`	所在频道 ID
`IsSelf`	`bool`	是否是当前用户（仅 `GetClientsJSON` 中自动标记）

TextMsg

字段	类型	描述
`InvokerName`	`string`	发送者昵称
`InvokerUID`	`string`	发送者唯一标识
`Message`	`string`	消息内容
`TargetMode`	`int`	1=私聊, 2=频道, 3=服务器
`TargetID`	`string`	目标 ID

PokeEvent

字段	类型	描述
`InvokerID`	`int`	发送者客户端 ID
`InvokerName`	`string`	发送者昵称
`InvokerUID`	`string`	发送者唯一标识
`Message`	`string`	Poke 消息内容

十九、JSON 数据结构参考

以下 JSON 结构由查询方法返回，供 Kotlin 侧反序列化使用。

channelJSON（GetChannelsJSON / FindChannelsJSON）

字段	类型	描述
`id`	`string`	频道 ID
`name`	`string`	频道名称
`parentId`	`string`	父频道 ID（GetChannelsJSON 有，FindChannelsJSON 无）
`description`	`string`	频道描述（GetChannelsJSON 有，FindChannelsJSON 无）

channelDetailedJSON（GetChannelsDetailedJSON）

字段	类型	描述
`id`	`string`	频道 ID
`name`	`string`	频道名称
`parentId`	`string`	父频道 ID
`topic`	`string`	频道主题
`order`	`string`	排序顺序
`codec`	`int`	编解码器（4=Opus Voice, 5=Opus Music）
`codecQuality`	`int`	编解码质量（0-10）
`neededTalkPower`	`int`	发言所需权限等级
`maxClients`	`int`	最大客户端数（-1=无限）
`maxFamilyClients`	`int`	最大族客户端数（-1=无限）
`isMaxClientsUnlimited`	`bool`	是否无限人数
`isMaxFamilyClientsUnlimited`	`bool`	是否无限族人数
`isPermanent`	`bool`	永久频道
`isSemiPermanent`	`bool`	半永久频道
`isDefault`	`bool`	默认频道
`isPassword`	`bool`	有密码
`isOrdered`	`bool`	手动排序
`iconId`	`string`	频道图标 ID
`neededModifyPower`	`int`	修改频道所需权限

channelDetailedInfoJSON（GetChannelDetailInfoJSON）

字段	类型	描述
`id`	`string`	频道 ID
`parentId`	`string`	父频道 ID
`name`	`string`	频道名称
`topic`	`string`	频道主题
`description`	`string`	完整描述（可能很长）
`codec`	`int`	编解码器
`codecQuality`	`int`	编解码质量
`maxClients`	`int`	最大人数
`maxFamilyClients`	`int`	最大族人数
`neededTalkPower`	`int`	发言权限
`iconId`	`string`	图标 ID
`isPermanent`	`bool`	永久
`isSemiPermanent`	`bool`	半永久
`isDefault`	`bool`	默认
`isPassword`	`bool`	有密码
`order`	`string`	排序
`bannerGfxUrl`	`string`	Banner 图片 URL

clientJSON（GetClientsJSON）

字段	类型	描述
`id`	`int`	客户端 ID
`nickname`	`string`	昵称
`uid`	`string`	唯一标识
`channelId`	`string`	所在频道 ID
`serverGroups`	`[]string`	所在服务器组 ID 列表
`isSelf`	`bool`	是否是当前用户

clientDetailedInfoJSON（GetClientDetailInfoJSON）

字段	类型	描述
`id`	`string`	客户端 ID
`nickname`	`string`	昵称
`uid`	`string`	唯一标识
`channelId`	`string`	所在频道 ID
`type`	`int`	客户端类型
`serverGroups`	`[]string`	服务器组
`away`	`bool`	是否离开
`awayMessage`	`string`	离开消息
`inputMuted`	`bool`	输入静音
`outputMuted`	`bool`	输出静音
`platform`	`string`	平台
`version`	`string`	版本
`ip`	`string`	IP 地址
`created`	`string`	首次连接时间戳
`lastConnected`	`string`	最近连接时间戳
`totalConnections`	`int`	总连接次数
`description`	`string`	用户描述
`iconId`	`string`	图标 ID

serverInfoJSON（GetServerInfoJSON）

字段	类型	描述
`name`	`string`	服务器名称
`welcomeMessage`	`string`	欢迎消息
`maxClients`	`int`	最大客户端数
`clientsOnline`	`int`	在线客户端数
`channelsOnline`	`int`	在线频道数
`uptime`	`string`	运行时长（秒）
`version`	`string`	服务器版本
`platform`	`string`	服务器平台
`created`	`string`	创建时间戳
`iconId`	`string`	服务器图标 ID
`defaultServerGroup`	`int`	默认服务器组 ID
`defaultChannelGroup`	`int`	默认频道组 ID

dbClientJSON（ListDBClientsJSON）

字段	类型	描述
`dbid`	`string`	数据库 ID
`uid`	`string`	唯一标识
`nickname`	`string`	昵称
`created`	`string`	首次连接时间戳
`lastConnected`	`string`	最近连接时间戳
`totalConnections`	`int`	总连接次数
`description`	`string`	描述

banEntryJSON（ListBansJSON）

字段	类型	描述
`banId`	`string`	封禁 ID
`ip`	`string`	IP
`name`	`string`	名称
`uid`	`string`	唯一标识
`created`	`string`	封禁时间戳
`invokerName`	`string`	操作者昵称
`invokerUid`	`string`	操作者 UID
`reason`	`string`	封禁原因
`enforcement`	`bool`	是否立即执行

fileEntryJSON（ListFilesJSON）

字段	类型	描述
`name`	`string`	文件/目录名
`size`	`string`	字节数（目录为 "0"）
`dateTime`	`string`	修改时间戳
`isFile`	`bool`	true=文件, false=目录

tokenEntryJSON（ListTokensJSON）

字段	类型	描述
`token`	`string`	权限密钥字符串
`tokenType`	`int`	0=服务器组, 1=频道组
`tokenId1`	`string`	组 ID
`tokenId2`	`string`	频道 ID（仅 tokenType=1）
`created`	`string`	创建时间戳
`description`	`string`	描述

complaintEntryJSON（ListComplaintsJSON）

字段	类型	描述
`fromDbid`	`string`	投诉者 DBID
`toDbid`	`string`	被投诉者 DBID
`message`	`string`	投诉内容
`timestamp`	`string`	投诉时间戳

fileTransferInitJSON（FileTransferInitUploadJSON / FileTransferInitDownloadJSON）

字段	类型	描述
`port`	`int`	TCP 传输端口
`key`	`string`	传输密钥
`size`	`int`	文件字节数（仅下载）
`clientFileTransferID`	`int`	客户端传输 ID
`serverFileTransferID`	`int`	服务器传输 ID
`seekPosition`	`int`	断点续传位置（仅上传）

initialSyncJSON（GetInitialSyncJSON）

字段	类型	描述
`channels`	`[]channelDetailedJSON`	详细频道列表
`clients`	`[]clientJSON`	在线客户端列表
`selfId`	`int`	自身客户端 ID
`selfChannelId`	`string`	自身所在频道 ID
`server`	`serverInfoJSON`	服务器信息

二十、方法来源标记

标记每个方法的实现文件，便于定位代码。

方法	来源文件	说明
`NewClient`	bridge.go
`GenerateIdentity`	kotlin_api.go
`Connect`	bridge.go	每次生成新 Identity
`ConnectWithIdentity`	kotlin_api.go	复用已有 Identity
`Disconnect`	bridge.go
`IsConnected`	bridge.go
`GetClientID`	bridge.go
`GetChannelID`	bridge.go
`GetChannelsJSON`	bridge.go
`GetChannelsDetailedJSON`	bridge.go
`ListChannelsSortedJSON`	kotlin_api.go	去重+排序
`GetClientsJSON`	bridge.go
`GetServerInfoJSON`	bridge.go
`GetChannelDetailInfoJSON`	bridge.go
`GetClientDetailInfoJSON`	bridge.go
`ListDBClientsJSON`	bridge.go
`FindChannelsJSON`	kotlin_api.go
`FindClientByNameJSON`	kotlin_api.go
`FindClientByDBIDJSON`	kotlin_api.go
`SendTextMessage`	bridge.go
`SendChannelMessage`	bridge.go	快捷方式
`Poke`	bridge.go
`MoveToChannel`	bridge.go	移动自己
`MoveClient`	kotlin_api.go	移动指定客户端
`MoveChannel`	kotlin_api.go	移动频道位置
`CreateChannelJSON`	bridge.go
`EditChannelJSON`	bridge.go
`DeleteChannel`	bridge.go
`UpdateSelfJSON`	bridge.go
`KickClient`	bridge.go
`SendVoice`	bridge.go
`ListBansJSON`	bridge.go
`AddBan`	bridge.go
`DeleteBan`	bridge.go
`DeleteAllBans`	kotlin_api.go
`ListTokensJSON`	bridge.go
`UseToken`	bridge.go
`ListComplaintsJSON`	bridge.go
`AddComplaint`	bridge.go
`DeleteComplaint`	kotlin_api.go
`ListFilesJSON`	bridge.go
`FileTransferInitUploadJSON`	kotlin_api.go
`FileTransferInitDownloadJSON`	kotlin_api.go
`DeleteFile`	kotlin_api.go
`GetInitialSyncJSON`	kotlin_api.go

40 KiB Raw Blame History Unescape Escape

Bridge 层 API 文档

一、客户端构造

NewClient

二、Identity 管理

GenerateIdentity

ConnectWithIdentity

三、连接管理

Connect

Disconnect

IsConnected

GetClientID

GetChannelID

四、频道查询

GetChannelsJSON

GetChannelsDetailedJSON

ListChannelsSortedJSON

GetChannelDetailInfoJSON

FindChannelsJSON

五、客户端查询

GetClientsJSON

GetClientDetailInfoJSON

FindClientByNameJSON

FindClientByDBIDJSON

ListDBClientsJSON

六、服务器信息

GetServerInfoJSON

七、文本消息与 Poke

SendTextMessage

SendChannelMessage

Poke

八、频道切换与客户端移动

MoveToChannel

MoveClient

MoveChannel

九、频道管理

CreateChannelJSON

EditChannelJSON

DeleteChannel

十、客户端管理

UpdateSelfJSON

KickClient

十一、语音

SendVoice

十二、Ban 管理

ListBansJSON

AddBan

DeleteBan

DeleteAllBans

十三、Token 管理

ListTokensJSON

UseToken

十四、投诉管理

ListComplaintsJSON

AddComplaint

DeleteComplaint

十五、文件传输

ListFilesJSON

FileTransferInitUploadJSON

FileTransferInitDownloadJSON

DeleteFile

十六、批量查询

GetInitialSyncJSON

十七、事件回调接口

EventCallback

Kotlin 侧事件处理流程

被管理员移动到指定频道（OnClientMoved）

收到频道内文本消息（OnTextMessage, targetMode=2）

被 Poke 带文本消息（OnPoked）

十八、导出数据类型

Channel

Client

TextMsg

PokeEvent

十九、JSON 数据结构参考

channelJSON（GetChannelsJSON / FindChannelsJSON）

channelDetailedJSON（GetChannelsDetailedJSON）

channelDetailedInfoJSON（GetChannelDetailInfoJSON）

clientJSON（GetClientsJSON）

clientDetailedInfoJSON（GetClientDetailInfoJSON）

40 KiB

Raw Blame History