This project has moved. For the latest updates, please go here.

Connect to a server


To connect to a server, the instances of 2 classes are required:
Sample Code VB.net
Imports TS3QueryLib.Core
Imports TS3QueryLib.Core.Query
Imports TS3QueryLib.Core.Query.Responses
...

' the IP or Hostname of the teamspeak server to connect to
Dim targetHost As String = "127.0.0.1"
' the query port of the teamspeak server to connect to
Dim targetQueryPort As UShort = 10011
' the username used in Login-Method
Dim login As String = "serveradmin"
' the password for the login
Dim password As String = "ANicePassword"

' The QueryRunner is used to send queries. All Queries are implemented type save and return objects with properties
Using queryRunner As New QueryRunner(New SyncTcpDispatcher(targetHost, targetQueryPort))
	' host and port
	' connection to the TS3-Server is established with the first query command when using SyncTcpDispatcher

	' login using the provided username and password and show a dump-output of the response in a textbox
	Dim loginResponse As SimpleResponse = queryRunner.Login(login, password)

	If loginResponse.IsErroneous Then
		' login failed! Use loginResponse.ErrorMessage and loginResponse.ErrorId to get the reason
		Return
	End If

	Dim versionResponse As VersionResponse = queryRunner.GetVersion()

			' use versionResponse.Platform, versionResponse.Version and versionResponse.Build to show the version info of the server
	If Not versionResponse.IsErroneous Then
	End If
End Using
...
Sample Code C#
using TS3QueryLib.Core;
using TS3QueryLib.Core.Query;
using TS3QueryLib.Core.Query.Responses;
...

string targetHost = "127.0.0.1"; // the IP or Hostname of the teamspeak server to connect to
ushort targetQueryPort = 10011; // the query port of the teamspeak server to connect to
string login = "serveradmin"; // the username used in Login-Method
string password = "ANicePassword"; // the password for the login

// The QueryRunner is used to send queries. All Queries are implemented type save and return objects with properties
using (QueryRunner queryRunner = new QueryRunner(new SyncTcpDispatcher(targetHost, targetQueryPort))) // host and port
{
	// connection to the TS3-Server is established with the first query command when using SyncTcpDispatcher

	// login using the provided username and password and show a dump-output of the response in a textbox
	SimpleResponse loginResponse = queryRunner.Login(login, password); 

	if (loginResponse.IsErroneous)
	{
		// login failed! Use loginResponse.ErrorMessage and loginResponse.ErrorId to get the reason
		return;
	}

	VersionResponse versionResponse = queryRunner.GetVersion();

	if (!versionResponse.IsErroneous)
	{
		// use versionResponse.Platform, versionResponse.Version and versionResponse.Build to show the version info of the server
	}
}

...

The above sample shows how to connect to a teamspeak server using the QueryRunner and the SyncTcpDispatcher class. The QueryRunner is the class providing methods that can be called at the query port. The QueryRunner is creating the textual command under the hood and uses the passed Dispatcher (in this case the SyncTcpDispatcher) to send the created command to the query port and to get the response, which is then processed by the QueryRunner and transformed into typesafe classes.

Within the sample a connection to a local teamspeak server is made and using the Login-Method of the QueryRunner a login is tried. The code checks if the login is successful, if not the code returns. Then a version call is done to get the information about the teamspeak servers version including platform, version and build details. The result is checked for errors.

A call to a method of QueryRunner always returns a class derived from class ResponseBase<T>. This class contains important information about the response. You should always check if a response's IsErroneous property is "false" before proceeding with the code. There are multiple reasons why a response can be erroneous:
  • not enough rights to execute the command
  • you're banned from the server

Here are the Properties of the class ResponseBase<T> which every response derives from:
public uint ErrorId { get; protected set; }
public string ErrorMessage { get; protected set; }
public uint? FailedPermissionId { get; protected set; }
public bool IsErroneous { get { return (ErrorId != 0 && ErrorId != 1281) || IsBanned || ResponseText == null; } }
public bool IsBanned { get; protected set; }
public string BanExtraMessage { get; protected set; }
public string BodyText { get; protected set; }
public string StatusText { get; protected set; }
public string ResponseText { get; protected set; }

Most of the properties are self explaining. But I think the last 3 properties are not. Normally you dont need them, but I'll explain them to you. Let's say we connect to a teamspeak server on the queryport using a telnet client and type "version" and press ENTER. The result sent by the server would be:
version=3.0.0-rc1 build=14468 platform=Windows
error id=0 msg=ok

A response to a command contains at least the last line. This line is the StatusText-Property of the QueryRunner class. The first line (on some commands there are more than one line) containing the version info is the BodyText-Property of the QueryRunner class. The whole response text of the command is saved to the ResponseText-Property of the QueryRunner class. But as stated before, normally you dont need to use those properties, because all information within those properties is transfered typesafe to other properties and structures.

Last edited Jun 21, 2011 at 8:39 AM by JoshuaK456, version 6

Comments

No comments yet.