README
¶
libts
libts is a pure go wrapper for the TeamSpeak Serverquery protocol. Its goal is to ease the pain of interfacing with a TeamSpeak Server from a program.
What it can do
libts is supposed to be a complete wrapper around the TeamSpeak Serverquery, so you don't have to actually deal with it. It implements most of the functionality of the Serverquery and is much easier to use as a developer than actually trying to deal with the Serverquery and its weird responses.
Connecting
There are currently three ways to connect to a TeamSpeak Serverquery:
- Telnet
- SSH
- HTTP/HTTPS
Which one you choose is pretty much irrelevent for the most part as the Queries are nearly feature-equal. However there are some differences and a clear recommendation from my side.
Telnet
Telnet is that ancient protocol noone really uses anymore as it has no security whatsoever. It is, afaik, the predessesor of SSH and provides a remote terminal to another machine.
| Pros | Cons |
|---|---|
| easy to use | insecure |
| supports the whole functionality of Serverquery | plain-text communication |
serverquery, err := NewServerQuery("my-cool-teamspeak.com", 10011, "serveradmin", "mySuperSecurePassword")
if err != nil {
panic(err)
}
SSH
SSH was later added to TeamSpeak Server as a secure alternative to Telnet. It supports all the functionality Telnet does.
| Pros | Cons |
|---|---|
| easy to use | |
| supports the whole functionality of Serverquery | |
| secure |
serverquery, err := NewSSHQuery("my-cool-teamspeak.com", 10022, "serveradmin", "mySuperSecurePassword")
if err != nil {
panic(err)
}
HTTP/HTTPS
As of late 2020 TeamSpeak Server provides a somewhat RESTful interface. That means you can query a TeamSpeak Server with pretty much everything, as long as it is connected to the Internet. Unfortunately since HTTP isn't a statful protocol, events are currently not supported. Also some other commands, which are obsolete when using HTTP/HTTPS, are also not supported such as use or login.
| Pros | Cons |
|---|---|
| easy to use | not feature complete |
| can be queried by nearly anything | not really RESTful |
| can be secured |
webClient := &http.Client{...}
serverquery := webquery.WebQuery{
Host: "my-cool-teamspeak.com",
Port: 10088,
Key: "myAPIKey",
TLS: false,
HTTPClient: webClient,
}
Querying
After connecting to the TeamSpeak server you can start querying information from the TeamSpeak server. You can either just send commands,
globalMessage := libts.Request{
Command: "gm",
Args: map[string]interface{}{
"msg": "Hello World",
},
}
response, err := serverquery.DoRaw(globalMessage)
if err != nil {
panic(err)
}
send them and process the response,
hostinfo := libts.Request{
Command: "hostinfo",
}
host := &struct {
Uptime int `mapstructure:"instance_uptime"`
}
err := serverquery.Do(hostinfo, host)
if err != nil {
panic(err)
}
fmt.Printf("Server is %ds up", host.Uptime)
or use the helper methods provided in the query package:
queryAgent := query.Agent{
Query: serverquery,
}
hostinfo, err := queryAgent.Host()
if err != nil {
panic(err)
}
fmt.Printf("There are %d clients in %d channel on %d virtual server",
hostinfo.ClientsOnlineTotal,
hostinfo.ChannelOnlineTotal,
hostinfo.VirtualServerRunningTotal)
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // QueryEncoder escapes special characters as needed QueryEncoder = strings.NewReplacer( `\`, `\\`, `/`, `\/`, ` `, `\s`, `|`, `\p`, "\a", `\a`, "\b", `\b`, "\f", `\f`, "\n", `\n`, "\r", `\r`, "\t", `\t`, "\v", `\v`, ) // QueryDecoder replaces escaped characters with thier string representation QueryDecoder = strings.NewReplacer( `\\`, "\\", `\/`, "/", `\s`, " ", `\p`, "|", `\a`, "\a", `\b`, "\b", `\f`, "\f", `\n`, "\n", `\r`, "\r", `\t`, "\t", `\v`, "\v", ) )
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event struct {
Template interface{}
C chan<- interface{}
}
Event describes the structure and the channel for a single event (cliententerview, clientleftview, etc.)
type Query ¶
type Query interface {
// Do executes a given request against teamspeak and tries to parse the answer in the given interface
// You can give it either one single PTR to a struct or a PTR to a slice if you expect to recieve more than one answer
Do(req Request, res interface{}) error
// DoRaw just returns the answer of teamspeak
DoRaw(req Request) ([]byte, error)
// Notifications provides a chan which includes only the notifications
Notification() <-chan []byte
// Connected returns true, if the query can still send and recieve on the connection
// The query sends the version command to do that
// Returns the recieved error if false
Connected() (bool, error)
}
Query is the interface for all implementation (webquery, serverquery, sshquery) Be aware, that different queries can do different things (e.g. serverquery can recieve notifications, webquery can't atm)
type Request ¶
Request contains all necessary infos for a query request towards teamspeak You need to know, what to expect as an answer
type Subscriber ¶
type Subscriber interface {
// Subscribe to s and attempt to parse the response
Subscribe(s Subscription) error
// Unsubscribe from notification n
Unsubscribe(n string)
// UnsubscribeAll form all subscriptions
UnsubscribeAll() error
}
Subscriber can subscribe to events
type Subscription ¶
Subscription describes an event a subscriber can subscribe to Name is the Name of the "Event" you are subscribing to (server, channel, etc.) Events are the events with the type that represents them you want to recieve. All other are discarded The subscriber will attempt to parse the event to the type of the channel ChannelID is ignored if Subscription is not libts.ChannelEvents
Source Files
Directories