Interacting with the server

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

Parameters

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

Parameters

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

Server information |  | Creating a new channel