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, |
| clID, |
| newChannelID, |
| password, |
| returnCode`)`; |

`anyID serverConnectionHandlerID`;
`anyID clID`;
`anyID newChannelID`;
`const char* password`;
`const char* returnCode`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler ID on which this action is requested.

- `clID`

  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.

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

`anyID serverConnectionHandlerID`;
`anyID clientID`;
`anyID oldChannelID`;
`anyID 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`

  Displaying the optional message given in `ts3client_stopConnection`.

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

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

Now wait for the callback:

    void yourImplementationOf_onClientMoveEvent(anyID scHandlerID, anyID clientID,
                                                anyID oldChannelID, anyID newChannelID,
                                                int visibility) {
      // 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
    }

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

`anyID serverConnectionHandlerID`;
`anyID clientID`;
`anyID oldChannelID`;
`anyID newChannelID`;
`int visibility`;
`anyID moverID`;
`const char* moverName`;
`moveMessage moverUniqueIdentifier`;
`moveMessage 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 mover client. `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