Connecting to a server

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( result);

char** result;

result
Address of a variable that receives the identity string, encoded in UTF-8.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h. If an error occured, the result string is uninitialized and must not be accessed.

	Caution
	The result string must be released using `ts3client_freeMemory`. If an error has occured, the result string is uninitialized and must not be released.

Once a server connection handler has been spawned and an identity is available, connect to a TeamSpeak 3 server with

`unsigned int ts3client_startConnection(`	`serverConnectionHandlerID`,
	`identity`,
	`ip`,
	`port`,
	`nickname`,
	`defaultChannelArray`,
	`defaultChannelPassword`,
	`serverPassword)`;

uint64 serverConnectionHandlerID;
const char* identity;
const char* ip;
unsigned int port;
const char* nickname;
const char** defaultChannelArray;
const char* defaultChannelPassword;
const char* serverPassword;

serverConnectionHandlerID
Unique identifier for this server connection. Created with ts3client_spawnNewServerConnectionHandler
identity
The clients identity. This string has to be created by calling ts3client_createIdentity. Please note an application should create the identity only once, store the string locally and reuse it for future connections.
ip
Hostname or IP of the TeamSpeak 3 server.
If you pass a hostname instead of an IP, the Client Lib will try to resolve it to an IP, but the function may block for an unusually long period of time while resolving is taking place. If you are relying on the function to return quickly, we recommend to resolve the hostname yourself (e.g. asynchronously) and then call ts3client_startConnection with the IP instead of the hostname.
port
UDP port of the TeamSpeak 3 server, by default 9987. TeamSpeak 3 uses UDP. Support for TCP might be added in the future.
nickname
On login, the client attempts to take this nickname on the connected server. Note this is not necessarily the actually assigned nickname, as the server can modifiy the nickname ("gandalf_1" instead the requested "gandalf") or refuse blocked names.
defaultChannelArray
String array defining the path to a channel on the TeamSpeak 3 server. If the channel exists and the user has sufficient rights and supplies the correct password if required, the channel will be joined on login.
To define the path to a subchannel of arbitrary level, create an array of channel names detailing the position of the default channel (e.g. "grandparent", "parent", "mydefault", ""). The array is terminated with a empty string.
Pass NULL to join the servers default channel.
defaultChannelPassword
Password for the default channel. Pass an empty string if no password is required or no default channel is specified.
serverPassword
Password for the server. Pass an empty string if the server does not require a password.

All strings need to be encoded in UTF-8 format.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h. When trying to connect with an invalid identity, the Client Lib will set the error ERROR_client_could_not_validate_identity.

There is an alternative convinience function to start the connection which takes a channelID as parameter for the default channel instead of a channel name string array.

`unsigned int ts3client_startConnectionWithChannelID(`	`serverConnectionHandlerID`,
	`identity`,
	`ip`,
	`port`,
	`nickname`,
	`defaultChannelId`,
	`defaultChannelPassword`,
	`serverPassword)`;

uint64 serverConnectionHandlerID;
const char* identity;
const char* ip;
unsigned int port;
const char* nickname;
uint64 defaultChannelId;
const char* defaultChannelPassword;
const char* serverPassword;

serverConnectionHandlerID
Unique identifier for this server connection. Created with ts3client_spawnNewServerConnectionHandler
identity
The clients identity. This string has to be created by calling ts3client_createIdentity. Please note an application should create the identity only once, store the string locally and reuse it for future connections.
ip
Hostname or IP of the TeamSpeak 3 server.
If you pass a hostname instead of an IP, the Client Lib will try to resolve it to an IP, but the function may block for an unusually long period of time while resolving is taking place. If you are relying on the function to return quickly, we recommend to resolve the hostname yourself (e.g. asynchronously) and then call ts3client_startConnection with the IP instead of the hostname.
port
UDP port of the TeamSpeak 3 server, by default 9987. TeamSpeak 3 uses UDP. Support for TCP might be added in the future.
nickname
On login, the client attempts to take this nickname on the connected server. Note this is not necessarily the actually assigned nickname, as the server can modifiy the nickname ("gandalf_1" instead the requested "gandalf") or refuse blocked names.
defaultChannelID
Specifies ID of the channel on the TeamSpeak server we want to connect to. This is an alternative way to define the channel by ID instead of channel path as in ts3client_startConnection. If the specified channel does no longer exist or if the channel password is incorrect, the user will be connected to the default channel of the TeamSpeak server.
defaultChannelPassword
Password for the default channel. Pass an empty string if no password is required or no default channel is specified.
serverPassword
Password for the server. Pass an empty string if the server does not require a password.

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) {
    (...)
}			  
ts3client_freeMemory(identity);  /* Don't need this anymore */

After calling ts3client_startConnection, the client will be informed of the connection status changes by the callback

`void onConnectStatusChangeEvent(`	`serverConnectionHandlerID`,
	`newStatus`,
	`errorNumber)`;

uint64 serverConnectionHandlerID;
int newStatus;
int errorNumber;

newStatus

The new connect state as defined by the enum ConnectStatus:

enum ConnectStatus {
    STATUS_DISCONNECTED = 0,       //There is no activity to the server, this is the default value
    STATUS_CONNECTING,             //We are trying to connect, we haven't got a clientID yet, we
                                   //haven't been accepted by the server
    STATUS_CONNECTED,              //The server has accepted us, we can talk and hear and we got a
                                   //clientID, but we don't have the channels and clients yet, we
                                   //can get server infos (welcome msg etc.)
    STATUS_CONNECTION_ESTABLISHING,//we are CONNECTED and we are visible
    STATUS_CONNECTION_ESTABLISHED, //we are CONNECTED and we have the client and channels available
};

errorNumber
Should be ERROR_ok (zero) when connecting

While connecting, the states will switch through the values STATUS_CONNECTING, STATUS_CONNECTED and STATUS_CONNECTION_ESTABLISHED. Once the state STATUS_CONNECTED has been reached, there the server welcome message is available, which can be queried by the client:

Welcome message

Query the server variable VIRTUALSERVER_WELCOMEMESSAGE for the message text using the function ts3client_getServerVariableAsString:

char* welcomeMsg;
if(ts3client_getServerVariableAsString(serverConnectionHandlerID, VIRTUALSERVER_WELCOMEMESSAGE, &welcomeMsg)
   != ERROR_ok) {
    printf("Error getting server welcome message: %d\n", error);
    return;
}
print("Welcome message: %s\n", welcomeMsg);  /* Display message */
ts3client_freeMemory(welcomeMsg);  /* Release memory */

To check if a connection to a given server connection handler is established, call:

`unsigned int ts3client_getConnectionStatus(`	`serverConnectionHandlerID`,
	`result)`;

uint64 serverConnectionHandlerID;
int* result;

serverConnectionHandlerID
ID of the server connection handler of which the connection state is checked.
result
Address of a variable that receives the result: 1 - Connected, 0 - Not connected.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.

After the state STATUS_CONNECTED has been reached, the client is assigned an ID which identifies the client on this server. This ID can be queried with

`unsigned int ts3client_getClientID(`	`serverConnectionHandlerID`,
	`result)`;

uint64 serverConnectionHandlerID;
anyID* result;

serverConnectionHandlerID
ID of the server connection handler on which we are querying the own client ID.
result
Address of a variable that receives the client ID. Client IDs start with the value 1.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.

After connection has been established, all current channels on the server are announced to the client. This happens with delays to avoid a flood of information after connecting. The client is informed about the existance of each channel with the following event:

`void onNewChannelEvent(`	`serverConnectionHandlerID`,
	`channelID`,
	`channelParentID)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
uint64 channelParentID;

serverConnectionHandlerID
The server connection handler ID.
channelID
The ID of the announced channel.
channelParentID
ID of the parent channel.

Channel IDs start with the value 1.

The order in which channels are announced by onNewChannelEvent is defined by the channel order as explained in the chapter Channel sorting.

All clients currently logged to the server are announced after connecting with the callback onClientMoveEvent.


Managing server connection handlers		Disconnecting from a server