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.

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;
 


Callbacks

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.


Permissions

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.