Managing server connections

Before connecting to a TeamSpeak 3 server, a server connection handler needs to be spawned. Each handler is identified by a unique ID (usually called serverConnectionHandlerID internally).

For each connection handler one connection can be established. Connection handlers can be re-used as needed as long as they exist. So for simply reconnecting to the same server or connecting to another server after disconnecting, no new handler needs to be spawned but existing ones can be reused.

However if you need multiple simultaneous connections, you need one server connection handler per simultaneous connection.

Creating a connection handler

A connection handler is created using

unsigned int ts3client_spawnNewServerConnectionHandler(int port, uint64 *result)

Creates a new server connection handler to connect to servers.

A connection handler is what handles and identifies server connections to the client library. There can be many of these at the same time and every single one of them can be connected to any server. The client library identifies them by the id placed in the result param. When you receive callbacks, or need to change things, on a specific server you will also specify which server you would like to use by providing the corresponding serverConnectionHandlerId to the client library function.

Parameters:

port – the local port to use. Specify 0 to use an ephemeral port.
result – Address of a variable to store the id of the connection handler in. Use this to reference the connection handler in future calls to client lib functions.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Caution

Do not specify a non-zero value for port unless you absolutely need a specific port. Passing zero is the better way in most use cases.

Note

When no longer needed a connection handler should be destroyed

Removing a connection handler

To destroy a server connection handler call

unsigned int ts3client_destroyServerConnectionHandler(uint64 serverConnectionHandlerID)

Destroys a connection handler.

After destruction the connection handler is invalid and cannot be used any longer. Must not be called from within a callback!

Parameters:

serverConnectionHandlerID – which connection handler to destroy

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Important

Destroying invalidates the handler ID, so it must not be used anymore afterwards.

Caution

Do not destroy a server connection handler from within a callback.

List connection handlers

A client can connect to multiple servers. To list all currently existing server connection handlers call:

unsigned int ts3client_getServerConnectionHandlerList(uint64 **result)

get a list of all connection handlers

Parameters:

result – address of a variable to receive a zero terminated array of connection handlers, like {1, 5, …, 0} Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Creating an identity

To connect to a server, a client application is required to request an identity from the Client Lib. This string should be requested only once and then locally stored in the applications configuration. The next time the application connects to a server, the identity should be read from the configuration and reused again.

unsigned int ts3client_createIdentity(char **result)

Create a new identity to use for connecting to a server.

Identities identify a client to the server. The identity should be stored and reused for sessions by the same user.

Parameters:

result – Address of a variable to store the identity in. Memory is allocated by the client lib and caller must free it using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Connecting to a server

Once a connection handler and identity are available, you can attempt to connect to a server using either of these two functions

unsigned int ts3client_startConnection(uint64 serverConnectionHandlerID, const char *identity, const char *ip, unsigned int port, const char *nickname, const char **defaultChannelArray, const char *defaultChannelPassword, const char *serverPassword)

initiates a connection to a TeamSpeak server.

When using a hostname instead of an IP address, this function will block until the client lib resolved the host name.

Example

Example code to request a connection to a TeamSpeak 3 server:

unsigned int error;
uint64 scHandlerID;
char* identity;

error = ts3client_spawnNewServerConnectionHandler(&scHandlerID);
if (error != ERROR_ok) {
    printf("Error spawning server conection handler: %d\n", error);
    return;
}

error = ts3client_createIdentity(&identity);  /* Application should store and reuse the identity */
if (error != ERROR_ok) {
    printf("Error creating identity: %d\n", error);
    return;
}

error = ts3client_startConnection(scHandlerID, identity, "my-teamspeak-server.com", 9987, "Gandalf",
                  NULL,      // Join servers default channel
                  "",        // Empty default channel password
                  "secret"); // Server password
if (error != ERROR_ok) {
    // Handle the error
}
ts3client_freeMemory(identity);  /* Don't need this anymore */

Connection change notification

After calling ts3client_startConnection(), the client will be informed of the connection status changes through the callback

struct ClientUIFunctions

Defines available callbacks that you can receive.

Set the members of this struct to a function to call when the specific event happens.

Public Members

void (*onConnectStatusChangeEvent)(uint64 serverConnectionHandlerID, int newStatus, unsigned int errorNumber)

called when the status of a connection changes

Param serverConnectionHandlerID:: specifies on which connection the status has changed
Param newStatus:: the current status of the connection. One of the values from the ConnectStatus enum
Param errorNumber:: if the state change was caused by an error this is set to one of the values from the Ts3ErrorType enum

This callback will be called every time the connection advances or changes state. Valid states are described in ConnectStatus

You may want to query certain server variables like VIRTUALSERVER_WELCOMEMESSAGE when the status is STATUS_CONNECTED for display purposes. You will also be informed about existing channels by means of the onNewChannelEvent() callback as well as visible clients by means of the onClientMoveEvent() callback.

If the server is shut down, in addition to the above, the following callback will be called

struct ClientUIFunctions

Defines available callbacks that you can receive.

Set the members of this struct to a function to call when the specific event happens.

Public Members

void (*onServerStopEvent)(uint64 serverConnectionHandlerID, const char *shutdownMessage)

called when the server was stopped

Param serverConnectionHandlerID:: specifies on which connection the callback was called
Param shutdownMessage:: utf8 encoded c string containing the provided reason for the shutdown

Disconnecting

To disconnect from a TeamSpeak 3 server call

unsigned int ts3client_stopConnection(uint64 serverConnectionHandlerID, const char *quitMessage)

Disconnect from a TeamSpeak server.

Parameters:

serverConnectionHandlerID – the connection handler to disconnect on
quitMessage – an optional utf8 encoded message to display to other clients. Pass empty string if unused.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason