Connecting to a server

## 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`;

Parameters

- `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`)`; |

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

Parameters

- `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`.

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

    unsigned int error;
    anyID 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`)`; |

`anyID serverConnectionHandlerID`;
`int newStatus`;
`int errorNumber`;

Parameters

- `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`)`; |

`anyID serverConnectionHandlerID`;
`int* result`;

Parameters

- `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`)`; |

`anyID serverConnectionHandlerID`;
`anyID* result`;

Parameters

- `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`)`; |

`anyID serverConnectionHandlerID`;
`anyID channelID`;
`anyID channelParentID`;

Parameters

- `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