/TeamSpeak3QueryApi

.NET wrapper for the TeamSpeak 3 Query API

Primary LanguageC#GNU General Public License v3.0GPL-3.0

C# TeamSpeak3Query API Travis Build Status NuGet Downloads

An API wrapper for the TeamSpeak 3 Query API written in C#. Still work in progress.

Key features of this library:

  • Built entirely with the .NET TAP pattern for perfect async/await usage opportunities
  • Robust library architecture
  • Query responses are fully mapped to .NET objects, including the naming style
  • Usable via Middleware/Rich Client

Contents

  1. Documentation
  2. Compatibility
  3. NuGet
  4. Examples
  5. Connect and Login
  6. Notifications
  7. Requesting Client Information
  8. Exceptions
  9. Middleware
  10. Node.js

Documentation

The TeamSpeak 3 Query API is documented here. This library has an online documentation which was created using sharpDox. You can find the documentation on the GitHub Page of this repository.

Compatibility

This library requires .NET Standard 1.3. You can look at this table to see whether your platform is supported. If you find something that is missing (espacially in the TeamSpeakClient class), just submit a PR or an issue!

NuGet

Install-Package TeamSpeak3QueryApi
# or
dotnet add package TeamSpeak3QueryApi

Examples

Using the rich client, you can connect to a TeamSpeak Query server like this:

Connect and Login

var rc = new TeamSpeakClient(host, port); // Create rich client instance, optionally use the internal 'keep-alive' logic to keep the client from disconnecting by passing true here.
await rc.Connect(); // connect to the server
await rc.Login(user, password); // login to do some stuff that requires permission
await rc.UseServer(1); // Use the server with id '1'
var me = await rc.WhoAmI(); // Get information about yourself!

Notifications

You can receive notifications. The notification data is fully typed, so you can access the response via properties and not - like other wrappers - using a dictionary.

// assuming connected
await rc.RegisterServerNotification(); // register notifications to receive server notifications

// register channel notifications to receive notifications for channel with id '30'
await rc.RegisterChannelNotification(30);

//Subscribe a callback to a notification:
rc.Subscribe<ClientEnterView>(data => {
    foreach(var c in data)
    {
        Trace.WriteLine("Client " + c.NickName + " joined.");
    }
});

Requesting Client Information

Getting all clients and moving them to a specific channel is as simple as:

var currentClients = await rc.GetClients();
await rc.MoveClient(currentClients, 30); // Where 30 is the channel id

...and kick someone whose name is "Foobar".

var fooBar = currentClients.SingleOrDefault(c => c.NickName == "Foobar"); // Using linq to find our dude
if(fooBar != null) // Make sure we pass a valid reference
    await rc.KickClient(fooBar, 30);

Exceptions

There are three exceptions:

  • QueryProtocolException

    Only occurs when the server sends an invalid response, meaning the server violates the protocol specifications.

  • QueryException

    Occurs every time the server responds with an error code that is not 0. It holds the error information, for example the error code, error message and - if applicatable - the missing permission id for the operation.

  • FileTransferException

    Occurs when there was an error uploading or downloading a file.

Note that exceptions are also thrown when a network problem occurs. Just like a normal TcpClient.

Middleware

If you want to work more loose-typed, you can do this. This is possible using the QueryClient.

var qc = new QueryClient(host, port);
await qc.Connect();

await qc.Send("login", new Parameter("client_login_name", userName), new Parameter("client_login_password", password));

await qc.Send("use", new Parameter("sid", "1"));

var me = await qc.Send("whoami");

await qc.Send("servernotifyregister", new Parameter("event", "server"));
await qc.Send("servernotifyregister", new Parameter("event", "channel"), new Parameter("id", channelId));

// and so on.

Note that you have to look up the commands in the TeamSpeak documentation.

Node.js

Suddenly node.

Actually, this library is a port of my TypeScript port of a JS library.

Note that these ports only contain the (in this library called) middleware.