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.
General filetransfer definitions and structures are described in the headers public_sdk_definitions.h
and server_commands.h
, which are required to include if you want to use the filetransfer feature.
In addition to the standard virtual server properties there are extented filetransfer properties available.
Filetransfer bandwidth statistics can be queried with special filetransfer connection properties.
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( | filebase, | |
ips, | ||
port, | ||
downloadBandwitdh, | ||
uploadBandwidth) ; |
const char* filebase
;const char** ips
;int port
;uint64 downloadBandwitdh
;uint64 uploadBandwidth
;filebase
The base folder where to save the files to. If this is initalized to "sdk_files", we would get the following directory structure:
All files for virtual server with id 1 will be in “sdk_files/virtualserver_1”.
Files in channel 1 in virtual server 1 will be in “sdk_files/virtualserver_1/channel_1”
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.
ips
Array of IPs (IPv4 and IPv6 are supported) to bind to. This can be NULL, in which case we bind to “0.0.0.0, ::”. Otherwise pass a NULL-terminated array of strings (IPs, not domainnames).
port
Specifies the TCP port used for filetransfer. Free to choose between 1 and 65536. TeamSpeak defaults to 30033.
downloadBandwidth
Download limit in bytes/s or BANDWIDTH_LIMIT_UNLIMITED
uploadBandwidth
Upload limit in bytes/s or BANDWIDTH_LIMIT_UNLIMITED
The serverlib notifies about ongoing filetransfers with an event, which is called everytime a file upload or download has finished:
void onFileTransferEvent( | data) ; |
const struct FileTransferCallbackExport* data
;data
Data structure containing values describing the finished filetransfer event:
clientID
ID of the client who triggerd the filetransfer
transferID
The local filetransfer ID
remoteTransferID
The remote filetransfer ID
status
Info on the state of the transfer, defined by the struct FileTransferState
:
enum FileTransferState { FILETRANSFER_INITIALISING = 0, FILETRANSFER_ACTIVE, FILETRANSFER_FINISHED, };
statusMessage
Info on the state in text form
remotefileSize
Size of the transfer file
bytes
Transferred bytes
isSender
True, if the server is sending the file, false if the server is receiving the file.
To change the filename or path of a file transfer, the following callback can be implemented. This is optional, when modifying path or name is not required, simply do not implement this callback. When this function is called, default path and name values are already filled in the passed structs.
unsigned int onTransformFilePath( | serverID, | |
invokerClientID, | ||
original, | ||
result) ; |
uint64 serverID
;anyID invokerClientID
;const struct TransformFilePathExport* original
;struct TransformFilePathExportReturns* result
;serverID
ID of the virtual server on which the event is called
invokerClientID
ID of the client which invoked the file transfer
original
Struct TransformFilePathExport, defining the original file transfer path and name:
struct TransformFilePathExport { uint64 channel; const char* filename; int action; int transformedFileNameMaxSize; int channelPathMaxSize; };
channel
ChannelID if appropriate (not for FT_INIT_SERVER
, where it defaults to 0)
filename
Original file name
action
Event was called for which action? (See below)
transformedFileNameMaxSize
Maximum size of transformedFileName (see result param)
channelPathMaxSize
Maximum size of channelPath (see result param)
result
Struct TransformFilePathExportReturns, target struct where the file transfer path or name can be changed:
struct TransformFilePathExportReturns { char* transformedFileName; char* channelPath; int logFileAction; };
transformedFileName
Pointer to string where the transformed filename is located. To change it, overwrite the content of where the pointer points, up to original->transformedFileNameMaxSize
bytes.
channelPath
Pointer to string where the channel path is located. To change it, overwrite the content of where the pointer points, up to original->channelPathMaxSize
bytes.
logFileAction
Set to 0 to not log to logfile, or 1 to log to file. VIRTUALSERVER_LOG_FILETRANSFER
must also be true for logging to happen (see struct VirtualServerPropertiesSDK in public_sdk_definitions.h
).
Return with ERROR_ok
if there are no errors, or return an other error value.
When implementing this callback, depending on the state in original->action
different fields in the result
struct can be modified.
Possible states for original->action
are:
FT_INIT_SERVER
When the virtual server is being is being created. The result->channelPath
can be changed to create a different folder for the virtual server.
FT_INIT_CHANNEL
When a channel is being is being created. The result->channelPath
can be changed to create a different folder for the channel.
FT_UPLOAD
When a file is being uploaded. Here result->channelPath
and/or result->transformedFileName
can be changed.
FT_DOWNLOAD
When a file is being downloaded. Here result->channelPath
and/or result->transformedFileName
can be changed.
FT_DELETE
When a file is being deleted. Here result->channelPath
and/or result->transformedFileName
can be changed.
FT_CREATEDIR
When a folder is being created. Here result->channelPath
and/or result->transformedFileName
can be changed
FT_RENAME
When a file/folder is being renamed. This callback will be called 2 times, first for old, then for new name. Here result->channelPath
and/or result->transformedFileName
can be changed.
FT_FILELIST
Called when a listing of a folder is requested. Here result->channelPath
and/or result->transformedFileName
can be changed.
FT_FILEINFO
Called when file info is requested. Here result->channelPath
and/or result->transformedFileName
can be changed.
The follow callbacks can be optionally implemented to control if various filetransfer actions are allowed or denied. If a callback is not implemented, actions are allowed by default.
If you want to use these functions, include server_commands.h
.
Control if a client is allowed to upload a file:
unsigned int permFileTransferInitUpload( | serverID, | |
client, | ||
params) ; |
uint64 serverID
;const struct ClientMiniExport* client
;const struct ts3sc_ftinitupload* params
;serverID
ID of the server where the file transfer is initiated.
client
Summary client info:
struct ClientMiniExport { anyID ID; uint64 channel; const char* ident; const char* nickname; };
params
Summary file info (fileName/fileSize/channelID):
struct ts3sc_ftinitupload { struct ts3sc_meta_ftinitupload m; /* message meta data */ struct ts3sc_data_ftinitupload d; /* message data */ }; struct ts3sc_data_ftinitupload { const char* fileName; /* The file name */ uint64 fileSize; /* The file size */ uint64 channelID; /* The channel ID where the file is to be uploaded */ int overwrite; /* Set to 1 to overwrite files, 0 to prevent overwrites */ int resume; /* Set to 1 to resume an existing upload, 0 to start new */ };
Return ERROR_OK
if allowed or ERROR_permissions_client_insufficient
/ERROR_permissions
.
Control if a client is allowed to download a file:
unsigned int permFileTransferInitDownload( | serverID, | |
client, | ||
params) ; |
uint64 serverID
;const struct ClientMiniExport* client
;const struct ts3sc_ftinitdownload* params
;serverID
ID of the server where the file transfer is initiated.
client
Summary client info
params
Summary file info (fileName/channelID):
struct ts3sc_ftinitdownload { struct ts3sc_meta_ftinitdownload m; /* message meta data */ struct ts3sc_data_ftinitdownload d; /* message data */ }; struct ts3sc_data_ftinitdownload { const char* fileName; /* The file name */ uint64 channelID; /* The channel ID where the file is to be downloaded from */ };
Return ERROR_OK
if allowed or ERROR_permissions_client_insufficient
/ERROR_permissions
.
Control if a client is allowed to request the file information:
unsigned int permFileTransferGetFileInfo( | serverID, | |
client, | ||
params) ; |
uint64 serverID
;const struct ClientMiniExport* client
;const struct ts3sc_ftgetfileinfo* params
;serverID
ID of the server where the file info request is initiated.
client
Summary client info
params
Summary file info (fileName/channelID):
struct ts3sc_ftgetfileinfo { struct ts3sc_meta_ftgetfileinfo m; /* message meta data */ struct ts3sc_data_ftgetfileinfo d; /* message data */ int r_size; /* items in r */ struct ts3sc_array_ftgetfileinfo* r; /* message repeat data */ }; struct ts3sc_data_ftgetfilelist { uint64 channelID; /* The channel ID */ const char* path; /* The path where to get the list for */ }; struct ts3sc_array_ftgetfileinfo { uint64 channelID; /* The channel ID where the file is located */ const char* fileName; /* The file name */ };
Return ERROR_OK
if allowed or ERROR_permissions_client_insufficient
/ERROR_permissions
.
Control if a client is allowed to request a directory listing:
unsigned int permFileTransferGetFileList( | serverID, | |
client, | ||
params) ; |
uint64 serverID
;const struct ClientMiniExport* client
;const struct ts3sc_ftgetfilelist* params
;serverID
ID of the server where the file list request is initiated.
client
Summary client info
params
Summary file info (path/channelID):
struct ts3sc_ftgetfilelist { struct ts3sc_meta_ftgetfilelist m; /* message meta data */ struct ts3sc_data_ftgetfilelist d; /* message data */ }; struct ts3sc_data_ftgetfilelist { uint64 channelID; /* The channel ID */ const char* path; /* The path where to get the list for */ };
Return ERROR_OK
if allowed or ERROR_permissions_client_insufficient
/ERROR_permissions
.
Control if a client is allowed to delete one or more files:
unsigned int permFileTransferDeleteFile( | serverID, | |
client, | ||
params) ; |
uint64 serverID
;const struct ClientMiniExport* client
;const struct ts3sc_ftdeletefile* params
;serverID
ID of the server where the file deletion is initiated.
client
Summary client info
params
Summary file info (channelID/array of filenames):
struct ts3sc_ftdeletefile { struct ts3sc_meta_ftdeletefile m; /* message meta data */ struct ts3sc_data_ftdeletefile d; /* message data */ int r_size; /* items in r */ struct ts3sc_array_ftdeletefile* r; /* message repeat data */ }; struct ts3sc_data_ftdeletefile { uint64 channelID; /* The channel ID where the file is to be deleted */ }; struct ts3sc_array_ftdeletefile { const char* fileName; /* The file name to be deleted */ };
Return ERROR_OK
if allowed or ERROR_permissions_client_insufficient
/ERROR_permissions
.
Control if a client is allowed to create a directory:
unsigned int permFileTransferCreateDirectory( | serverID, | |
client, | ||
params) ; |
uint64 serverID
;const struct ClientMiniExport* client
;const struct ts3sc_ftcreatedir* params
;serverID
ID of the server where the directory creation is initiated.
client
Summary client info
params
Summary file info (channelID/dirname):
struct ts3sc_ftcreatedir { struct ts3sc_meta_ftcreatedir m; /* message meta data */ struct ts3sc_data_ftcreatedir d; /* message data */ }; struct ts3sc_data_ftcreatedir { uint64 channelID; /* The channel ID where the file is to be uploaded */ const char* dirname; /* The directory name */ };
Return ERROR_OK
if allowed or ERROR_permissions_client_insufficient
/ERROR_permissions
.
Control if a client is allowed to rename a file:
unsigned int permFileTransferRenameFile( | serverID, | |
client, | ||
params) ; |
uint64 serverID
;const struct ClientMiniExport* client
;const struct ts3sc_ftrenamefile* params
;serverID
ID of the server where the file rename is initiated.
client
Summary client info
params
Summary file info (fromChannelID/toChannelID/oldFileName/newFileName). Use params->m.has_toChannelID
to check if toChannelID
is valid (else it is a rename in the same channel)
struct ts3sc_ftrenamefile { struct ts3sc_meta_ftrenamefile m; /* message meta data */ struct ts3sc_data_ftrenamefile d; /* message data */ }; struct ts3sc_data_ftrenamefile { uint64 fromChannelID; /* The channel ID where the file is located now */ uint64 toChannelID; /* The channel ID where the file is to be moved to */ const char* oldFileName; /* The current file name */ const char* newFileName; /* The new file name */ };
Return ERROR_OK
if allowed or ERROR_permissions_client_insufficient
/ERROR_permissions
.