Permission checks

The TeamSpeak SDK offers an optional custom permission system, allowing SDK users to gain more control over allowed user actions on a TeamSpeak server. The custom permissions system is implemented in the Server Lib by adding callback functions which will be called, if implemented, when a certain user action occurs. In this callback the developer can allow or deny the action.

The callbacks should return ERROR_ok to allow the action or ERROR_permission to deny it.

Important

If a callback is not implemented, the action will be allowed by default.

Available callbacks

Standard Permission callbacks

struct ServerLibFunctions

Server callbacks. Zero initialize and set members to functions that are to be called when the event in question happens. Every callback you use should exit quickly to avoid stalling the server. If you need any expensive activity upon receiving callbacks, consider starting the activity in a new thread and allow the callback to exit quickly.

Public Members

unsigned int (*permClientCanConnect)(uint64 serverID, const struct ClientMiniExport *client)

called when a client is about to connect. Can be used to deny clients from connecting.

Return ERROR_ok to allow the client on the server, or ERROR_permissions to reject the client.

Param serverID:

the server the client wants to connect to

Param client:

pointer to a ClientMiniExport describing the client trying to connect

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permClientCanGetChannelDescription)(uint64 serverID, const struct ClientMiniExport *client)

called when a client requests channel description of a channel using ts3client_requestChannelDescription. Can be used to deny access to channel descriptions.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server on which the request was received

Param client:

pointer to a ClientMiniExport describing the client requesting the channel description

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permClientUpdate)(uint64 serverID, anyID clientID, const struct VariablesExport *variables)

called when a client wants to update a clients variables. Used to deny or allow updating certain client variables

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param clientID:

the client for which the variables are attempted to be changed.

Param variables:

pointer to a VariablesExport containing the variables, new and old values of the client.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permClientKickFromChannel)(uint64 serverID, const struct ClientMiniExport *client, int toKickCount, const struct ClientMiniExport *toKickClients, const char *reasonText)

called before a client is kicked from the channel. Allows you to control whether clients are allowed to kick another client

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

pointer to a ClientMiniExport describing the client attempting to kick another client.

Param toKickCount:

number of clients that are supposed to be kicked

Param toKickClients:

array of ClientMiniExport describing the clients to be kicked

Param reasonText:

utf8 encoded c string containing the reason for the kick provided.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permClientKickFromServer)(uint64 serverID, const struct ClientMiniExport *client, int toKickCount, const struct ClientMiniExport *toKickClients, const char *reasonText)

called before a client is kicked from the server. Allows you to control whether clients are allowed to kick another client

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

pointer to a ClientMiniExport describing the client attempting to kick another client.

Param toKickCount:

number of clients that are supposed to be kicked

Param toKickClients:

array of ClientMiniExport describing the clients to be kicked

Param reasonText:

utf8 encoded c string containing the provided reason for the kick.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permClientMove)(uint64 serverID, const struct ClientMiniExport *client, int toMoveCount, const struct ClientMiniExport *toMoveClients, uint64 newChannel, const char *reasonText)

called when a client requests to move one or more other clients. Allows you to control whether a client can move the clients.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server on which the move is attempted.

Param client:

pointer to a ClientMiniExport describing the client attempting to move the client(s).

Param toMoveCount:

number of clients that are being moved.

Param toMoveClients:

array of ClientMiniExport describing which clients are being moved.

Param newChannel:

id of the channel the clients are to be moved in to.

Param reasonText:

utf8 encoded c string containing the reason provided for the move.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permChannelMove)(uint64 serverID, const struct ClientMiniExport *client, uint64 channelID, uint64 newParentChannelID)

called when a client attempts to move a channel. Allows you to control whether the client is allowed to move the channel.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

a ClientMiniExport describing the client attempting to move the channel.

Param channelID:

the channel to be moved.

Param newParentChannelID:

the new parent channel of the channel

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permSendTextMessage)(uint64 serverID, const struct ClientMiniExport *client, anyID targetMode, uint64 targetClientOrChannel, const char *textMessage)

called when a client tries to send a message. Allows you to control whether the client is allowed to send the message.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

a ClientMiniExport describing the client attempting to send the message

Param targetMode:

describing the type of message attempting to be sent. One of the values from the TextMessageTargetMode enum

Param targetClientOrChannel:

id of the channel or client (depending of the targetMode) that the message is sent to.

Param textMessage:

utf8 encoded c string containing the message to be sent.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permServerRequestConnectionInfo)(uint64 serverID, const struct ClientMiniExport *client)

called when server connection information is requested using ts3client_requestServerConnectionInfo. Can be used to deny access.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

a ClientMiniExport describing the client requesting the action

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permSendConnectionInfo)(uint64 serverID, const struct ClientMiniExport *client, int *mayViewIpPort, const struct ClientMiniExport *targetClient)

called when a client attempts to request another clients connection variables using ts3client_requestConnectionInfo

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

describes the client requesting the other clients information

Param mayViewIpPort:

pointer to a variable that controls whether the IP and port of the target client may be seen by the client. Set to 1 to allow the requesting client to see the IP and port. Set to 0 to deny IP and port.

Param targetClient:

describes the client that the connection information is requested for.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permChannelCreate)(uint64 serverID, const struct ClientMiniExport *client, uint64 parentChannelID, const struct VariablesExport *variables)

called when a client attempts to create a channel. Allows you to control whether or not the client may create the desired channel.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server on which the client attempts to create the channel

Param client:

a ClientMiniExport describing the client trying to create a channel

Param parentChannelID:

the channel that is the parent channel of the channel to be created. 0 if the channel to be created will be a root channel.

Param variables:

a VariablesExport struct that describes the channel to be created.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permChannelEdit)(uint64 serverID, const struct ClientMiniExport *client, uint64 channelID, const struct VariablesExport *variables)

called when a channel is about to be edited by a client. Allows you to prevent channel edits.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

a ClientMiniExport describing the client trying to edit the channel

Param parentChannelID:

the channel that is to be edited.

Param variables:

a VariablesExport struct that describes the channel after the edit.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permChannelDelete)(uint64 serverID, const struct ClientMiniExport *client, uint64 channelID)

called before a channel is deleted by a client. Allows you to deny a client deleting channels.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server on which the channel is to be deleted

Param client:

a ClientMiniExport describing the client trying to delete the channel

Param channelID:

the channel that is to be deleted

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permChannelSubscribe)(uint64 serverID, const struct ClientMiniExport *client, uint64 channelID)

called when a client requests to subscribe a channel. Allows you to deny subscribing to a channel.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server on which the client attempts to subscribe to the channel.

Param client:

a ClientMiniExport describing the client trying to subscribe the channel

Param channelID:

the channel that is to be subscribed

Return:

ERROR_ok to allow, ERROR_permissions to deny

FileTransfer permission callbacks

struct ServerLibFunctions

Server callbacks. Zero initialize and set members to functions that are to be called when the event in question happens. Every callback you use should exit quickly to avoid stalling the server. If you need any expensive activity upon receiving callbacks, consider starting the activity in a new thread and allow the callback to exit quickly.

Public Members

unsigned int (*permFileTransferInitUpload)(uint64 serverID, const struct ClientMiniExport *client, const struct ts3sc_ftinitupload *params)

called when a file is to be uploaded. Allows you to deny a client from uploading files, files above a certain size, etc.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

describes the client that attempts to upload the file.

Param params:

describes the file to be uploaded.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permFileTransferInitDownload)(uint64 serverID, const struct ClientMiniExport *client, const struct ts3sc_ftinitdownload *params)

called when a file is to be downloaded. Allows you to deny a client from downloading files, files above a certain size, etc.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

describes the client that attempts to download the file

Param params:

describes the file to be downloaded.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permFileTransferGetFileInfo)(uint64 serverID, const struct ClientMiniExport *client, const struct ts3sc_ftgetfileinfo *params)

called when a client requests file information using ts3client_requestFileInfo. Allows to deny clients from getting file information.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

describes the client attempting to get information of the file.

Param params:

describes the file that information is requested for.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permFileTransferGetFileList)(uint64 serverID, const struct ClientMiniExport *client, const struct ts3sc_ftgetfilelist *params)

called when a client requests a directory listing using ts3client_requestFileList. Allows to deny listing files and directories in channels / directories.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permFileTransferDeleteFile)(uint64 serverID, const struct ClientMiniExport *client, const struct ts3sc_ftdeletefile *params)

called when a client attempts to delete one or more files using ts3client_requestDeleteFile. Allows denying clients deleting files.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

describes the client attempting to delete the file

Param params:

describes the file to be deleted

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permFileTransferCreateDirectory)(uint64 serverID, const struct ClientMiniExport *client, const struct ts3sc_ftcreatedir *params)

called when a directory is to be created using ts3client_requestCreateDirectory. Allows to deny creating certain directories.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

describes the client attempting to create the directory

Param params:

describes the directory to create.

Return:

ERROR_ok to allow, ERROR_permissions to deny

unsigned int (*permFileTransferRenameFile)(uint64 serverID, const struct ClientMiniExport *client, const struct ts3sc_ftrenamefile *params)

called when a file is to be renamed or moved using ts3client_requestRenameFile. Allows to deny moving files or even renaming files.

Return ERROR_ok to allow the action, or ERROR_permissions to reject it.

Param serverID:

the server for which the callback was called

Param client:

describes the client attempting to rename or move the file.

Param params:

describes the file to be renamed or moved, and where the file should be moved to if it’s being moved.

Return:

ERROR_ok to allow, ERROR_permissions to deny

Example

Example code to check if a client can connect to the server:

// Create the function pointer passed to ts3server_initServerLib
funcs.permClientCanConnect = onPermClientCanConnect;

// Custom callback
unsigned int onPermClientCanConnect(uint64 serverID, const struct ClientMiniExport* client) {
    // Forbid client with nickname "client" to connect
    if (strcmp(client->nickname, "client") == 0) {
        return ERROR_permissions;  // Deny
    }
    return ERROR_ok;  // Allow
}

Please see the server_permissions example for a demonstration of this mechanism.