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 filesystem where the server is running.

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.

Query 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(`	`transferID`,
	`result)`;

anyID transferID;
char** result;

transferID
ID of the filetransfer we want to query.
result
Points to a C string containing the file name. Remember to call ts3client_freeMemory to release the string, which is dynamically allocated in the clientlib.

Query the file path of the specified transfer:

`unsigned int ts3client_getTransferFilePath(`	`transferID`,
	`result)`;

anyID transferID;
char** result;

transferID
ID of the filetransfer we want to query.
result
Points to a C string containing the file path. Remember to call ts3client_freeMemory to release the string, which is dynamically allocated in the clientlib.

Query the remote path on the server of the specified transfer:

`unsigned int ts3client_getTransferFileRemotePath(`	`transferID`,
	`result)`;

anyID transferID;
char** result;

transferID
ID of the filetransfer we want to query.
result
Points to a C string containing the remote path on the server. Remember to call ts3client_freeMemory to release the string, which is dynamically allocated in the clientlib.

Query the file size of the specified transfer:

`unsigned int ts3client_getTransferFileSize(`	`transferID`,
	`result)`;

anyID transferID;
uint64* result;

transferID
ID of the filetransfer we want to query.
result
File size of the transfer.

Query the currently transferred file size of the queried transfer:

`unsigned int ts3client_getTransferFileSizeDone(`	`transferID`,
	`result)`;

anyID transferID;
uint64* result;

transferID
ID of the filetransfer we want to query.
result
Already transferred size of the transfer.

Query if the specified transfer is an upload or download:

`unsigned int ts3client_isTransferSender(`	`transferID`,
	`result)`;

anyID transferID;
int* result;

transferID
ID of the filetransfer we want to query.
result
1 == upload, 0 == download

Query the status of the specified transfer:

`unsigned int ts3client_getTransferStatus(`	`transferID`,
	`result)`;

anyID transferID;
int* result;

transferID
ID of the filetransfer we want to query.

result

Current status of the file transfer, specified by the struct FileTransferState:

enum FileTransferState {
    FILETRANSFER_INITIALISING = 0,
    FILETRANSFER_ACTIVE,
    FILETRANSFER_FINISHED,
};

Query the current speed of the specified transfer:

`unsigned int ts3client_getCurrentTransferSpeed(`	`transferID`,
	`result)`;

anyID transferID;
float* result;

transferID
ID of the filetransfer we want to query.
result
Currently measured speed of the file transfer.

Query the average speed of the specified transfer:

`unsigned int ts3client_getAverageTransferSpeed(`	`transferID`,
	`result)`;

anyID transferID;
float* result;

transferID
ID of the filetransfer we want to query.
result
Average speed of the file transfer.

Query the time the specified transfer has used:

`unsigned int ts3client_getTransferRunTime(`	`transferID`,
	`result)`;

anyID transferID;
uint64* result;

transferID
ID of the filetransfer we want to query.
result
Time the transfer has used.

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.

Request uploading a local file to the server:

`unsigned int ts3client_sendFile(`	`serverConnectionHandlerID`,
	`channelID`,
	`channelPW`,
	`file`,
	`overwrite`,
	`resume`,
	`sourceDirectory`,
	`result`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
const char* channelPW;
const char* file;
int overwrite;
int resume;
const char* sourceDirectory;
anyID* result;
const char* returnCode;

serverConnectionHandlerID
ID of the virtual server the file transfer operation will be requested.
channelID
Target channel ID in which the file should be uploaded.
channelPW
Optional channel password. Pass empty string if unused.
file
Filename of the local file, which is to be uploaded.
overwrite
1 == overwrite remote file if it exists, 0 = do not overwrite (operation will abort if remote file exists)
resume
If we have a previously halted transfer: 1 = resume, 0 = restart transfer
sourceDirectory
Local directory where the file to upload is located.
result
Pointer to memory where the transferID will be stored, if the transfer has been started successfully (when this function returns ERROR_ok).
returnCode
String containing the return code if it has been set by the Client Lib function call which caused this error event.
See return code documentation.

Request downloading a file from the server:

`unsigned int ts3client_requestFile(`	`serverConnectionHandlerID`,
	`channelID`,
	`channelPW`,
	`file`,
	`overwrite`,
	`resume`,
	`destinationDirectory`,
	`result`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
const char* channelPW;
const char* file;
int overwrite;
int resume;
const char* destinationDirectory;
anyID* result;
const char* returnCode;

serverConnectionHandlerID
ID of the virtual server the file transfer operation will be requested.
channelID
Remote channel ID from which the file should be downloaded.
channelPW
Optional channel password. Pass empty string if unused.
file
Filename of the remote file, which is to be downloaded.
overwrite
1 == overwrite local file if it exists, 0 = do not overwrite (operation will abort if local file exists)
resume
If we have a previously halted transfer: 1 = resume, 0 = restart transfer
destinationDirectory
Local target directory name where the download file should be saved.
result
Pointer to memory where the transferID will be stored, if the transfer has been started successfully (when this function returns ERROR_ok).
returnCode
String containing the return code if it has been set by the Client Lib function call which caused this error event.
See return code documentation.

Pause a transfer, specified by its transferID:

`unsigned int ts3client_haltTransfer(`	`serverConnectionHandlerID`,
	`transferID`,
	`deleteUnfinishedFile`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
anyID transferID;
int deleteUnfinishedFile;
const char* returnCode;

serverConnectionHandlerID
ID of the virtual server the file transfer operation will be requested.
transferID
ID of the transfer that should be halted.
deleteUnfinishedFile
1 = delete the halted file, 0 = do not deleted halted file
returnCode
String containing the return code if it has been set by the Client Lib function call which caused this error event.
See return code documentation.

Query list of files in a directory. The answer from the server will trigger the onFileListEvent and onFileListFinishedEvent callbacks with the requested information.

`unsigned int ts3client_requestFileList(`	`serverConnectionHandlerID`,
	`channelID`,
	`channelPW`,
	`path`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
const char* channelPW;
const char* path;
const char* returnCode;

serverConnectionHandlerID
ID of the virtual server the file transfer operation will be requested.
channelID
Remote channel ID, from which we want to query the file list.
channelPW
Optional channel password. Pass empty string if unused.
path
Path inside the channel, defining the subdirectory. Top level path is “/”
returnCode
String containing the return code if it has been set by the Client Lib function call which caused this error event.
See return code documentation.

Query information of a specified file. The answer from the server will trigger the onFileInfoEvent callback with the requested information.

`unsigned int ts3client_requestFileInfo(`	`serverConnectionHandlerID`,
	`channelID`,
	`channelPW`,
	`file`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
const char* channelPW;
const char* file;
const char* returnCode;

serverConnectionHandlerID
ID of the virtual server the file transfer operation will be requested.
channelID
Remote channel ID, from which we want to query the file info.
channelPW
Optional channel password. Pass empty string if unused.
file
File name we want to request info from, needs to include the full path within the channel, e.g. “/file” for a top-level file or “/dir1/dir2/file” for a file located in a subdirectory.
returnCode
String containing the return code if it has been set by the Client Lib function call which caused this error event.
See return code documentation.

Request deleting one or more remote files on the server:

`unsigned int ts3client_requestDeleteFile(`	`serverConnectionHandlerID`,
	`channelID`,
	`channelPW`,
	`file`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
const char* channelPW;
const char** file;
const char* returnCode;

serverConnectionHandlerID
ID of the virtual server the file transfer operation will be requested.
channelID
Remote channel ID, in which we want to delete the files.
channelPW
Optional channel password. Pass empty string if unused.
file
List of files we request to delete. Array must be NULL-terminated. The file names need to include the full path within the channel, e.g. “/file” for a top-level file or “/dir1/dir2/file” for a file located in a subdirectory.
returnCode
String containing the return code if it has been set by the Client Lib function call which caused this error event.
See return code documentation.

Request creating a directory:

`unsigned int ts3client_requestCreateDirectory(`	`serverConnectionHandlerID`,
	`channelID`,
	`channelPW`,
	`directoryPath`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
const char* channelPW;
const char* directoryPath;
const char* returnCode;

serverConnectionHandlerID
ID of the virtual server the file transfer operation will be requested.
channelID
Remote channel ID, in which we want to create the directory.
channelPW
Optional channel password. Pass empty string if unused.
file
Name of the directory to create. The directory name needs to include the full path within the channel, e.g. “/file” for a top-level file or “/dir1/dir2/file” for a file located in a subdirectory.
returnCode
String containing the return code if it has been set by the Client Lib function call which caused this error event.
See return code documentation.

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(`	`serverConnectionHandlerID`,
	`fromChannelID`,
	`fromChannelPW`,
	`toChannelID`,
	`toChannelPW`,
	`oldFile`,
	`newFile`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
uint64 fromChannelID;
const char* fromChannelPW;
uint64 toChannelID;
const char* toChannelPW;
const char* oldFile;
const char* newFile;
const char* returnCode;

serverConnectionHandlerID
ID of the virtual server the file transfer operation will be requested.
fromChannelID
Source channel ID, in which we want to rename the file.
fromChannelPW
Optional source channel password. Pass empty string if unused.
toChannelID
Target channel ID, to which we want to move the file. If the file should not be moved to another channel, this parameter should be equal to fromChannelID.
toChannelPW
Optional target channel password. Pass empty string if unused.
oldFile
Old name of the file. The file name needs to include the full path within the channel, e.g. “/file” for a top-level file or “/dir1/dir2/file” for a file located in a subdirectory.
newFile
Target name of the directory to create. The directory name need to include the full path within the channel, e.g. “/file” for a top-level file or “/dir1/dir2/file” for a file located in a subdirectory.
To move files to another subdirectory in the same channel without renaming the file, fromChannelID has to be equal to toChannelID, keep the file name itself but just change the path.
returnCode
String containing the return code if it has been set by the Client Lib function call which caused this error event.
See return code documentation.

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. Every file transfer should at least have a minimum speed limit of 5kb/s.

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.

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

unsigned int ts3client_setInstanceSpeedLimitUp( newLimit);

uint64 newLimit;

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

unsigned int ts3client_setInstanceSpeedLimitDown( newLimit);

uint64 newLimit;

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

unsigned int ts3client_getInstanceSpeedLimitUp( limit);

uint64* limit;

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

unsigned int ts3client_getInstanceSpeedLimitDown( limit);

uint64* limit;

To set the upload speed limit for the specified virtual server in bytes/s:

`unsigned int ts3client_setServerConnectionHandlerSpeedLimitUp(`	`serverConnectionHandlerID`,
	`newLimit)`;

uint64 serverConnectionHandlerID;
uint64 newLimit;

To set the download speed limit for the specified virtual server in bytes/s:

`unsigned int ts3client_setServerConnectionHandlerSpeedLimitDown(`	`serverConnectionHandlerID`,
	`newLimit)`;

uint64 serverConnectionHandlerID;
uint64 newLimit;

To get the upload speed limit for the specified virtual server in bytes/s:

`unsigned int ts3client_getServerConnectionHandlerSpeedLimitUp(`	`serverConnectionHandlerID`,
	`limit)`;

uint64 serverConnectionHandlerID;
uint64* limit;

To get the download speed limit for the specified virtual server in bytes/s:

`unsigned int ts3client_getServerConnectionHandlerSpeedLimitDown(`	`serverConnectionHandlerID`,
	`limit)`;

uint64 serverConnectionHandlerID;
uint64* limit;

To set the up- or download speed limit for the specified file transfer in bytes/s. Use ts3client_isTransferSender to query if the transfer is an up- or download.

`unsigned int ts3client_setTransferSpeedLimit(`	`transferID`,
	`newLimit)`;

anyID transferID;
uint64 newLimit;

To get the speed limit for the specified file transfer in bytes/s:

`unsigned int ts3client_getTransferSpeedLimit(`	`transferID`,
	`limit)`;

anyID transferID;
uint64* limit;

Callbacks

This event is called when a file transfer, triggered by ts3client_sendFile or ts3client_requestFile has finished or aborted with an error.

`void onFileTransferStatusEvent(`	`transferID`,
	`status`,
	`statusMessage`,
	`remotefileSize`,
	`serverConnectionHandlerID)`;

anyID transferID;
unsigned int status;
const char* statusMessage;
uint64 remotefileSize;
uint64 serverConnectionHandlerID;

transferID
ID of the transfer. This ID was returned by the call to ts3client_sendFile or ts3client_requestFile which triggered this event.
status
Indicates how and why the transfer has finished:
- ERROR_file_transfer_complete
  Transfer completed successfully.
- ERROR_file_transfer_canceled
  Transfer was halted by a call to ts3client_haltTransfer.
- ERROR_file_transfer_interrupted
  An error occured, transfer was stopped for various reasons (network error etc.)
- ERROR_file_transfer_reset
  Transfer was reset. This can happen if the remote file has changed (another user uploaded another file under the same channel ID, path and file name).
statusMessage
Status text message for a verbose display of the status parameter.
remotefileSize
Remote size of the file on the server.
serverConnectionHandlerID
ID of the virtual server on which the file list was requested.

Callback containing the reply by the server on ts3client_requestFileList. There event is called for every file in the specified path. After the last file, onFileListFinished will indicate the end of the list.

`void onFileListEvent(`	`serverConnectionHandlerID`,
	`channelID`,
	`path`,
	`name`,
	`size`,
	`datetime`,
	`type`,
	`incompletesize`,
	`returnCode)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
const char* path;
const char* name;
uint64 size;
uint64 datetime;
int type;
uint64 incompletesize;
const char* returnCode;

serverConnectionHandlerID
ID of the virtual server on which the file list was requested.
channelID
ID of the channel which file list was requested.
path
Subdirectory inside the channel for which the file list was requested. “/” indicates the root directory is listed.
name
File name.
size
File size
datetime
File date (Unix time in seconds)
type
Indicates if this entry is a directory or a file. Type is specified as:
```
enum {
    FileListType_Directory = 0,
    FileListType_File,
};
```
incompletesize
If the file is currently still being transferred, this indicates the currently transferred file size.
returnCode
String containing the return code if it has been set by ts3client_requestFileList which triggered this event.

Callback indicating the end of an incoming file list, see onFileList.

`void onFileListFinishedEvent(`	`serverConnectionHandlerID`,
	`channelID`,
	`path)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
const char* path;

serverConnectionHandlerID
ID of the virtual server on which the file list was requested.
channelID
If of the channel which files have been listed.
path
Path within the channel which files have been listed.

Callback containing the reply by the server for ts3client_requestFileInfo:

`void onFileInfoEvent(`	`serverConnectionHandlerID`,
	`channelID`,
	`name`,
	`size`,
	`datetime)`;

uint64 serverConnectionHandlerID;
uint64 channelID;
const char* name;
uint64 size;
uint64 datetime;

serverConnectionHandlerID
ID of the virtual server on which the file info was requested.
channelID
If of the channel in which the file is located.
name
File name including the path within the channel in which the file is located.
size
File size
datetime
File date (Unix time in seconds)


Miscellaneous functions		FAQ