Joining a channel

When a client logs on to a TeamSpeak 3 server, it will automatically join the channel with the CHANNEL_FLAG_DEFAULT flag, unless it specified a different channel in the ts3client_startConnection() call.

To join a different channel, or move another client to a different channel, call

unsigned int ts3client_requestClientMove(uint64 serverConnectionHandlerID, const anyID *clientIDArray, uint64 newChannelID, const char *password, const char *returnCode)

Attempt to move one or more clients to a different channel.

The move is requested from the server. See the onServerErrorEvent callback to know whether the move was successful or not.

Parameters:

serverConnectionHandlerID – the connection handler of which the channel and client are located
clientIDArray – NULL terminated array of client ids to move
newChannelID – the target channel id to move the clients to
password – the password for the channel. Pass an empty string if the channel has no password.
returnCode – a c string to identify this request in callbacks. Pass an empty string if unused.

Returns:

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

If successful one of the following callbacks will be called depending whether you moved your own or a different client

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 (*onClientMoveEvent)(uint64 serverConnectionHandlerID, anyID clientID, uint64 oldChannelID, uint64 newChannelID, int visibility, const char *moveMessage)

called when a client moves to a different channel, disconnects, connects, gets kicked or banned.

Param serverConnectionHandlerID:: specifies on which connection the callback was called
Param clientID:: id of the client changing channels
Param oldChannelID:: id of the previous channel of the client.
Param newChannelID:: id of the current channel of the client. Can be 0, if the client disconnected / got kicked / banned.

void (*onClientMoveMovedEvent)(uint64 serverConnectionHandlerID, anyID clientID, uint64 oldChannelID, uint64 newChannelID, int visibility, anyID moverID, const char *moverName, const char *moverUniqueIdentifier, const char *moveMessage)

called when a client was moved by the server or another client

Param serverConnectionHandlerID:: specifies on which connection the callback was called
Param clientID:: the client that was moved
Param oldChannelID:: id of the previous channel the client used to be in
Param newChannelID:: id of the current channel the client was moved to
Param visibility:: whether we can see the client. One of the values from the Visibility enum.
Param moverID:: id of the client that moved the client
Param moverName:: utf8 encoded c string containing the display name of the client that caused the move
Param moverUniqueIdentifier:: utf8 encoded c string containing the identifier of the client that caused the move
Param moveMessage:: utf8 encoded c string containing the reason message

Examples

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
}

Note

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.