Filetransfer

The TeamSpeak SDK includes the ability to support filetransfer, like the regular TeamSpeak server and client offer. The Server can function as a file storage, which can be accessed by Clients who can up- and download files. Files are stored on the server side filesystem.

In general, clients can initiate filetransfer actions like uploading or downloading a file, requesting file information (size, name, path etc.), list files in a directory and so on. The functions to call these actions are explained in detail below. In addition to the functions actively called, there are filetransfer related callbacks which are triggered when the server returned the requested information (e.g. list of files in a directory).

Each transfer is identified by a transferID, which is passed to most filetransfer functions. Transfer IDs are unique during the time of the transfer, but may be reused again some time after the previous transfer with the same ID has finished.

Files are organized on the server inside channels (identified by their channelID. The top-level directory in each channel is “/”. Subdirectories in each channel may exist and are defined with a path of the form “/dir1/dir2”. Subdirectories are optional and need to be created with ts3client_requestCreateDirectory(), the channel root directory always exists by default.

See File Transfer Definitions for various enums and structs used with file transfer.

Active transfer information

The following functions allow to query information about a file transfer identified by its transferID.

Query the file name of the specified transfer

unsigned int ts3client_getTransferFileName(anyID transferID, char **result)

get the local file name for a file transfer

Parameters:

transferID – identifies the file transfer to query
result – address of a variable to receive an utf8 encoded c string on success. Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

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

Query the file path of the specified transfer

unsigned int ts3client_getTransferFilePath(anyID transferID, char **result)

get the local path of a file transfer

Parameters:

transferID – identifies the file transfer to query
result – address of a variable to receive an utf8 encoded c string on success. Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

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

Query the remote path on the server for the specified transfer

unsigned int ts3client_getTransferFileRemotePath(anyID transferID, char **result)

get the server path of the file transfer

Parameters:

transferID – identifies which file transfer to query
result – address of a variable to receive an utf8 encoded c string on success. Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

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

Query the file size of the specified transfer

unsigned int ts3client_getTransferFileSize(anyID transferID, uint64 *result)

get the total size in bytes of a file transfer.

Parameters:

transferID – specifies which file transfer to query
result – address of a variable to receive the file size

Returns:

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

Query the currently transferred file size

unsigned int ts3client_getTransferFileSizeDone(anyID transferID, uint64 *result)

get the amount of bytes already transferred.

0 <= result <= ts3client_getTransferFileSize for the same transferID.

Parameters:

transferID – specifies the file transfer to query
result – address of a variable to receive the result on success

Returns:

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

Query if the specified transfer is an upload or download

unsigned int ts3client_isTransferSender(anyID transferID, int *result)

determine if the file transfer is an upload or download

Parameters:

transferID – specifies the file transfer to query
result – address of a variable to receive the result on success. 1 = upload, 0 = download

Returns:

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

Query the status of the specified transfer

unsigned int ts3client_getTransferStatus(anyID transferID, int *result)

determine the current status of the transfer in question

Parameters:

transferID – specifies the file transfer to query
result – address of a variable to receive the status on success. One of the values from the FileTransferState enum.

Returns:

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

Query the current speed of the specified transfer

unsigned int ts3client_getCurrentTransferSpeed(anyID transferID, float *result)

get the current approximate speed (in bytes/sec) of a file transfer

Parameters:

transferID – specifies the file transfer to query
result – address of a variable to receive the transfer speed in bytes per second, averaged across the past 5 seconds.

Returns:

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

Query the average speed of the specified transfer

unsigned int ts3client_getAverageTransferSpeed(anyID transferID, float *result)

get the average transfer speed (in bytes/sec) of a file transfer since it started

Parameters:

transferID – specifies the file transfer to query
result – address of a variable to receive the approximate speed in bytes per second, averaged across its lifetime.

Returns:

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

Query the time the specified transfer has been active

unsigned int ts3client_getTransferRunTime(anyID transferID, uint64 *result)

get the time (in seconds) a file transfer has been active

Parameters:

transferID – specifies the file transfer to query
result – address of a variable to receive the time in seconds the transfer was active.

Returns:

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

Initiate transfers

The following functions implement the core functionality of filetransfers. They initiate new up- and downloads, request file info, delete and rename files, create directories, list directories etc.

Upload a local file

unsigned int ts3client_sendFile(uint64 serverConnectionHandlerID, uint64 channelID, const char *channelPW, const char *file, int overwrite, int resume, const char *sourceDirectory, anyID *result, const char *returnCode)

Initiate a file upload to the server.

Parameters:

serverConnectionHandlerID – connection handler to which to upload a file
channelID – channel to which to upload the file
channelPW – password of the channel specified in channelID. Pass an empty string if the channel does not have a password.
file – the name of file to upload on the local file system.
overwrite – boolean flag, whether to overwrite the file on the server. If 0 the transfer will fail if the file already exists on the server.
resume – boolean flag, set to 1 to resume a previously aborted or halted transfer. If 1 will append to the file on the server.
sourceDirectory – the absolute path in which the file resides on the local file system.
result – address of a variable in which to store the transferID on success.
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

Download a file

unsigned int ts3client_requestFile(uint64 serverConnectionHandlerID, uint64 channelID, const char *channelPW, const char *file, int overwrite, int resume, const char *destinationDirectory, anyID *result, const char *returnCode)

Initiate a file download from the server.

Parameters:

serverConnectionHandlerID – connection handler from which to download the file
channelID – channel in which the file to download is located
channelPW – password of the channel specified in channelID. Pass an empty string if the channel does not have a password.
file – the name of the file on the server file system. See ts3client_getFileList to receive a list of files.
overwrite – boolean flag, whether to overwrite the local file if it already exists. If set to 0 transfer will fail if local file already exists unless resume is 1. Mutually exclusive to resume.
resume – boolean flag, whether to append to the local file. If set to 1 the contents of the download will be appended to the local file. Mutually exclusive with overwrite.
destinationDirectory – absolute path to the directory in which to store the file.
result – address of a variable to receive the transfer id, used to identity this request in callbacks and other calls regarding the status of this transfer
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

Cancel a transfer

unsigned int ts3client_haltTransfer(uint64 serverConnectionHandlerID, anyID transferID, int deleteUnfinishedFile, const char *returnCode)

Cancel a file transfer.

Parameters:

serverConnectionHandlerID – connection handler on which the file transfer is happening
transferID – specifies the file transfer to cancel
deleteUnfinishedFile – boolean flag, whether to delete the partially transmitted file from the file system.
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

Note

A cancelled transfer can later be resumed by calling ts3client_sendFile() with the same file and target and set resume = 1

Request file and directory information

unsigned int ts3client_requestFileList(uint64 serverConnectionHandlerID, uint64 channelID, const char *channelPW, const char *path, const char *returnCode)

retrieve a list of files in a directory.

This function is NOT recursive. Only directories and files in the directory specified by path will be listed. You will receive a onFileListEvent callback for every file or directory after this function was successful. Once all files and directories were sent you will receive a onFileListFinishedEvent callback.

Parameters:

serverConnectionHandlerID – the connection handler on which to request files
channelID – the channel from which to list the files
channelPW – the password of the specified channel. Pass an empty string if the channel has no password.
path – the path in the specified channel from which to list the files. Pass “/” to list the files in the root channel.
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

unsigned int ts3client_requestFileInfo(uint64 serverConnectionHandlerID, uint64 channelID, const char *channelPW, const char *file, const char *returnCode)

retrieve information about a specific file.

You will receive an onFileInfoEvent callback after this function was successful.

Parameters:

serverConnectionHandlerID – connection handler on which to request the file information.
channelID – the channel in which the file is located
channelPW – the password of the specified channel. Pass an empty string if the channel has no password.
file – absolute path to the file to query information of. Must begin with “/”.
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

unsigned int ts3client_requestDeleteFile(uint64 serverConnectionHandlerID, uint64 channelID, const char *channelPW, const char **file, const char *returnCode)

delete one or more files from a channel.

You will receive an onServerErrorEvent with the passed returnCode indicating whether or not the operation was successful.

Parameters:

serverConnectionHandlerID – connection handler on which to delete the file
channelID – the channel in which the file is located
channelPW – the password of the specified channel. Pass an empty string if the channel has no password.
file – a zero terminated array of absolute paths to the files to delete. Each path must begin with “/”. Like {“/file.txt”, “/dir/subdir/test.txt”, …, 0}
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

unsigned int ts3client_requestCreateDirectory(uint64 serverConnectionHandlerID, uint64 channelID, const char *channelPW, const char *directoryPath, const char *returnCode)

create a directory in a channel for file organization

Note: This will NOT recursively create directories. If you need recursive creation call this function again after the intended parent directory has been created. You will receive an onServerErrorEvent with the passed returnCode indicating whether or not the operation was successful.

Parameters:

serverConnectionHandlerID – connection handler on which the channel is located.
channelID – the channel in which the file is located
channelPW – the password of the specified channel. Pass an empty string if the channel has no password.
directoryPath – absolute path of the directory to create. Must start with “/” e.g. “/existing/newDirName”
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

Request renaming or moving a file. If the source and target channels and paths are the same, the file will simply be renamed

unsigned int ts3client_requestRenameFile(uint64 serverConnectionHandlerID, uint64 fromChannelID, const char *fromChannelPW, uint64 toChannelID, const char *toChannelPW, const char *oldFile, const char *newFile, const char *returnCode)

move or rename a file on the server.

You will receive an onServerErrorEvent with the passed returnCode indicating whether or not the operation was successful.

Parameters:

serverConnectionHandlerID – connection handler on which to move/rename the file
fromChannelID – channel the file is currently located in
fromChannelPW – password of the specified channel. Pass an empty string if the channel has no password.
toChannelID – channel id to which to move the file to. Pass the same value as fromChannelID to keep the file in the same channel.
toChannelPW – password of the target channel. Pass an empty string if the channel has no password.
oldFile – current absolute path of the file in the channel. Must start with “/”.
newFile – new absolute path of the file in the target channel. Must start with “/”. e.g. “/subdirectory/filename.txt”
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

Speed limits

The TeamSpeak SDK offers the possibility to control and finetune transfer speed limits. These limits can be applied to the complete server, specific virtual servers or for each individual transfer. By default the transfer speed is unlimited.

Caution

Every file transfer should at least have a minimum speed limit of 5kb/s.

Note

Neither the TeamSpeak client nor server will store any of those values. When used, they’ll have to be set at each client start to be considered permanent.

Set speed limits

To set the download speed limit for all virtual servers in bytes/s:

unsigned int ts3client_setInstanceSpeedLimitDown(uint64 newLimit)

set the instance wide download speed limit for file transfer.

All concurrent file transfers combined will not exceed min(instance limit, virtual server limit) bytes per second. The limit is temporary and valid only for the lifetime of the connection handler.

Parameters:

newLimit – maximum download speed in bytes per second. Must be >= 5120.

Returns:

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

To set the upload speed limit for all virtual servers in bytes/s:

unsigned int ts3client_setInstanceSpeedLimitUp(uint64 newLimit)

set the instance wide upload speed limit for file transfer.

All concurrent file transfers combined will not exceed min(instance limit, virtual server limit) bytes per second. The limit is temporary and valid only for the lifetime of the connection handler.

Parameters:

newLimit – maximum upload speed in bytes per second. Must be >= 5120.

Returns:

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

unsigned int ts3client_setServerConnectionHandlerSpeedLimitDown(uint64 serverConnectionHandlerID, uint64 newLimit)

set the virtual server download speed limit for file transfer.

All concurrent file transfers combined will not exceed min(instance limit, virtual server limit) bytes per second. The limit is temporary and valid only for the lifetime of the connection handler.

Parameters:

serverConnectionHandlerID – connection handler on which to set the limit.
newLimit – maximum download speed in bytes per second. Must be >= 5120.

Returns:

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

unsigned int ts3client_setServerConnectionHandlerSpeedLimitUp(uint64 serverConnectionHandlerID, uint64 newLimit)

set the virtual server upload speed limit for file transfer.

All concurrent file transfers combined will not exceed min(instance limit, virtual server limit) bytes per second. The limit is temporary and valid only for the lifetime of the connection handler.

Parameters:

serverConnectionHandlerID – connection handler on which to set the limit.
newLimit – maximum upload speed in bytes per second. Must be >= 5120.

Returns:

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

To set the up- or download speed limit for the specified file transfer, first determine whether it is an up or download using ts3client_isTransferSender() The speed limit for the transfer can be set using

unsigned int ts3client_setTransferSpeedLimit(anyID transferID, uint64 newLimit)

set the transfer limit for an individual file transfer.

The maximum transfer speed will be min(instance limit, virtual server limit, transfer limit). Whether the limit is upload or download depends on what kind of transfer the specified transfer is.

Parameters:

transferID – the transfer to set the limit for
newLimit – the new maximum speed in bytes per second. Must be >= 5120.

Returns:

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

Query speed limits

unsigned int ts3client_getInstanceSpeedLimitDown(uint64 *limit)

get the configured maximum download speed of the server instance.

The limit is temporary and valid only until ts3client_destroyClientLib is called.

Parameters:

limit – address of a variable to receive the limit in bytes per second.

Returns:

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

unsigned int ts3client_getInstanceSpeedLimitUp(uint64 *limit)

get the configured maximum upload speed of the server instance.

The limit is temporary and valid only until ts3client_destroyClientLib is called.

Parameters:

limit – address of a variable to receive the limit in bytes per second.

Returns:

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

unsigned int ts3client_getServerConnectionHandlerSpeedLimitDown(uint64 serverConnectionHandlerID, uint64 *limit)

get the configured maximum download speed for the virtual server.

Download speeds on this server will not exceed min(instance limit, virtual server limit) bytes per second. The limit is temporary and valid only for the lifetime of the connection handler.

Parameters:

serverConnectionHandlerID – connection handler to query the value on.
limit – address of a variable to receive the limit in bytes per second.

Returns:

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

unsigned int ts3client_getServerConnectionHandlerSpeedLimitUp(uint64 serverConnectionHandlerID, uint64 *limit)

get the configured maximum upload speed for the virtual server.

Upload speeds on this server will not exceed min(instance limit, virtual server limit) bytes per second. The limit is temporary and valid only for the lifetime of the connection handler.

Parameters:

serverConnectionHandlerID – connection handler to query the value on.
limit – address of a variable to receive the limit in bytes per second.

Returns:

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

unsigned int ts3client_getTransferSpeedLimit(anyID transferID, uint64 *limit)

get the speed limit for a specific file transfer.

Parameters:

transferID – specifies which transfer to query.
limit – address of a variable to receive the transfer limit in bytes per second.

Returns:

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

Callbacks

The following callbacks are called for file transfer actions

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 (*onFileTransferStatusEvent)(anyID transferID, unsigned int status, const char *statusMessage, uint64 remotefileSize, uint64 serverConnectionHandlerID)

called when file transfers finish or terminate with an error