Interacting with the server

Interacting with the server means various actions, related to both channels and clients. Channels can be joined, created, edited, deleted and subscribed. Clients can use text chat with other clients, be kicked or poked and move between channels.

All strings passed to and from the Client Lib need to be encoded in UTF-8 format.

Joining a channel

When a client logs on to a TeamSpeak 3 server, he will automatically join the channel with the “Default” flag, unless he specified another channel in ts3client_startConnection. To have your own or another client switch to a certain channel, call

`unsigned int ts3client_requestClientMove(`	`serverConnectionHandlerID`,
	`clientID`,
	`newChannelID`,
	`password`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
anyID clientID;
uint64 newChannelID;
const char* password;
const char* returnCode;

serverConnectionHandlerID
ID of the server connection handler ID on which this action is requested.
clientID
ID of the client to move.
newChannelID
ID of the channel the client wants to join.
password
An optional password, required for password-protected channels. Pass an empty string if no password is given.
returnCode
See return code documentation. Pass NULL if you do not need this feature.

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

If the move was successful, one the following events will be called:

`void onClientMoveEvent(`	`serverConnectionHandlerID`,
	`clientID`,
	`oldChannelID`,
	`newChannelID`,
	`visibility`,
	`moveMessage)`;

uint64 serverConnectionHandlerID;
anyID clientID;
uint64 oldChannelID;
uint64 newChannelID;
int visibility;
const char* moveMessage;

serverConnectionHandlerID
ID of the server connection handler on which the action occured.
clientID
ID of the moved client.
oldChannelID
ID of the old channel left by the client.
newChannelID
ID of the new channel joined by the client.
visibility
Defined in the enum Visibility
```
enum Visibility {
    ENTER_VISIBILITY = 0,
    RETAIN_VISIBILITY,
    LEAVE_VISIBILITY
};
```
- ENTER_VISIBILITY
  Client moved and entered visibility. Cannot happen on own client.
- RETAIN_VISIBILITY
  Client moved between two known places. Can happen on own or other client.
- LEAVE_VISIBILITY
  Client moved out of our sight. Cannot happen on own client.
moveMessage
When a client disconnects from the server, this includes the optional message set by the disconnecting client in ts3client_stopConnection.

Example: Requesting to move the own client into channel ID 12 (not password-protected):

ts3client_requestClientMove(scHandlerID, ts3client_getClientID(scHandlerID), 12, "", NULL);

Now wait for the callback:

void my_onClientMoveEvent(uint64 scHandlerID, anyID clientID,
                          uint64 oldChannelID, uint64 newChannelID,
                          int visibility, const char* moveMessage) {
  // scHandlerID   ->  Server connection handler ID, same as above when requesting
  // clientID      ->  Own client ID, same as above when requesting
  // oldChannelID  ->  ID of the channel the client has left
  // newChannelID  ->  12, as requested above
  // visibility    ->  One of ENTER_VISIBILITY, RETAIN_VISIBILITY, LEAVE_VISIBILITY
  // moveMessage   ->  Optional message set by disconnecting clients
}

If the move was initiated by another client, instead of onClientMove the following event is called:

`void onClientMoveMovedEvent(`	`serverConnectionHandlerID`,
	`clientID`,
	`oldChannelID`,
	`newChannelID`,
	`visibility`,
	`moverID`,
	`moverName`,
	`moverUniqueIdentifier`,
	`moveMessage)`;

uint64 serverConnectionHandlerID;
anyID clientID;
uint64 oldChannelID;
uint64 newChannelID;
int visibility;
anyID moverID;
const char* moverName;
const char* moverUniqueIdentifier;
const char* moveMessage;

Like onClientMoveEvent but with additional information about the client, which has initiated the move: moverID defines the ID, moverName the nickname and moverUniqueIdentifier the unique ID of the client who initiated the move. moveMessage contains a string giving the reason for the move.

If oldChannelID is 0, the client has just connected to the server. If newChannelID is 0, the client disconnected. Both values cannot be 0 at the same time.