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.
Enable file transfer
The availability of filetransfer in the TeamSpeak server can be
controlled by the following function, which should be called right after
ts3server_initServerLib() to initialize filetransfer.
-
unsigned int ts3server_enableFileManager(const char *filebase, const char **ips, int port, uint64 downloadBandwidth, uint64 uploadBandwidth)
Initialize the file transfer subsystem. Allows clients to store files on the machine the server is running on and download them.
If you want to support file transfer functionality, then call this function after calling ts3server_initServerLib If you don’t call this function file transfer features will not be available. The server library will create the directories necessary for storing files as needed, however directories will not be cleaned up by the server library. Instead it is the responsibility of the application to clean up these directories when they’re no longer needed (e.g. after a virtual server was deleted)
- Parameters:
filebase – path to where the server library will create necessary directories and store files uploaded by clients.
ips – zero terminated array of IP addresses to listen on for file transfer connections. IPv4 and IPv6 addresses are supported, do NOT pass host names. If set to 0, it will be treated as if you passed { “0.0.0.0”, “::”, 0 }
port – the TCP port to listen on for file transfer connections.
downloadBandwidth – limit in bytes per second which is available for downloading files from the server. Speed across all transfers will be limited to this number. Specify BANDWIDTH_LIMIT_UNLIMITED for no limit.
uploadBandwidth – limit in bytes per second which is available for uploading files to the server. Speed across all transfers will be limited to this number. Specify BANDWIDTH_LIMIT_UNLIMITED for no limit.
- Returns:
An Error code from the Ts3ErrorType enum indicating either success or the failure reason
The filebase directory will be created by the server lib. The individual files will be in a sub directory of the filebase called ‘virtualserver_x’ where x is the id of the virtual server. Individual channel files will be in a directory ‘channel_y’ within their respective server directory where y is the channel id of the channel.
Note
These directories will automatically be created by the server if they do not exist. It is the responsibility of the application (not serverlib) to delete these directories when they are no longer needed.
Callbacks
The server lib notifies about ongoing file transfers by optionally calling a defined callback, which is called everytime a file upload or download has finished.
-
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
-
void (*onFileTransferEvent)(const struct FileTransferCallbackExport *data)
called whenever a file transfer is done
- Param data:
pointer to a structure describing the file transfer that completed. See FileTransferCallbackExport for details.
-
void (*onFileTransferEvent)(const struct FileTransferCallbackExport *data)
-
struct FileTransferCallbackExport
Public Members
-
anyID clientID
the client who started the file transfer
-
anyID transferID
local identifier of the transfer that has completed
-
anyID remoteTransferID
remote identifier of the transfer that has completed
-
unsigned int status
status of the transfer. One of the values from the FileTransferState enum
-
const char *statusMessage
utf8 encoded c string containing a human readable description of the status
-
uint64 remotefileSize
size in bytes of the complete file to be transferred
-
uint64 bytes
number of bytes transferred. Same as remotefileSize when the transfer completed entirely.
-
int isSender
boolean. 1 if the server is sending the file. 0 if the server is receiving the file.
-
anyID clientID
Rewriting the path on the server
The SDK allows users to control where files are stored on the server as well as the file name the files have on the server side file system. The intended file name and path is already set in the parameters of this callback when it is called.
Note
This feature is optional. If you don’t need to rewrite file system paths or file names, simply do not implement this callback.
-
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 (*onTransformFilePath)(uint64 serverID, anyID invokerClientID, const struct TransformFilePathExport *original, struct TransformFilePathExportReturns *result)
Allows to rewrite the file path and name of the file to be transfered. Called when a transfer starts.
If you don’t need to control server side file name and path then don’t implement this callback. The parameters are already filled with the default values intended by the client starting the transfer. These can be changed as required. When the callback exits with ERROR_ok the transfer is started with the values present in the result struct.
See the SDK documentation for further details.
- Param serverID:
the server for which the callback was called
- Param invokerClientID:
the client which started the file transfer
- Param original:
the original file path and name desired by the client
- Param result:
the values from this struct will be used by the server when the callback exits. Already filled with a copy of original. Change the values in this struct as needed.
- Return:
a value from the Ts3ErrorType enum. Return ERROR_ok to start the transfer with the values in the result struct. When returning an error code the file transfer is not started.
-
unsigned int (*onTransformFilePath)(uint64 serverID, anyID invokerClientID, const struct TransformFilePathExport *original, struct TransformFilePathExportReturns *result)
Important
The length of the values present in the result TransformFilePathExportReturns
are limited and must not exceed the original length!
Permissions
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.
-
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
-
unsigned int (*permFileTransferInitUpload)(uint64 serverID, const struct ClientMiniExport *client, const struct ts3sc_ftinitupload *params)