Use to perform download/upload of ressources easily. More...

Public Types
enum	IdError { ERR_NO_ERROR = 0 , ERR_INTERNAL , ERR_INVALID_LOGIN , ERR_INVALID_REQUEST , ERR_INVALID_SSL , ERR_BUSY , ERR_USER_ABORT , ERR_MAX_TRIALS , ERR_MEMORY_FULL_HOST , ERR_MEMORY_FULL_REMOTE , ERR_HOST_NOT_FOUND , ERR_HOST_REFUSED , ERR_CONTENT_NOT_FOUND }
	List of errors identifiers. More...

enum	FlagOption : std::uint32_t { OPT_NONE = 0 , OPT_VERBOSE = 1 << 0 , OPT_FTP_CREATE_DIRS = 1 << 1 }
	List of available options. More...

using	CbStarted = std::function<void(Request::TypeTransfer typeTransfer)>
	Callback called when transfer has been started.

using	CbProgress = std::function<void(Request::TypeTransfer typeTransfer, size_t transferTotal, size_t transferNow)>
	Callback called during transfer.

using	CbCompleted = std::function<void(Request::TypeTransfer typeTransfer)>
	Callback called when transfer finished and succeed.

using	CbFailed = std::function<void(Request::TypeTransfer typeTransfer, IdError idErr)>
	Callback called when transfer finished due to an error.

Public Member Functions
IdError	startDownload (const Request::List &listReqs)
	Use to start downloading list of requests.

IdError	startUpload (const Request::List &listReqs)
	Use to start upload list of requests.

void	abortTransfer ()
	Use to abort current transfer.

bool	transferIsInProgress () const
	Verify is a tranfer is in progress or not.

const std::string &	getUserLogin () const
	Retrieve login information currently used.

const std::string &	getUserPasswd () const
	Retrieve password information currently used.

int	getNbMaxTrials () const
	Retrieve maximum number of trials currently set.

long	getTimeoutConnection () const
	Retrieve connection timeout.

long	getTimeoutTransfer () const
	Retrieve transfer timeout.

FlagOption	getOptions () const
	Retrieve transfer options.

void	setUserInfos (const std::string &username, const std::string &passwd)
	Use to set user informations.

void	setNbMaxTrials (int nbTrials)
	Use to set maximum number of trials.

void	setTimeoutConnection (long timeout)
	Use to set the maximum time in seconds that allow connection phase to take.

void	setTimeoutTransfer (long timeout)
	Use to set the maximum time in seconds to wait when no data is received before considering a timeout.

void	setOptions (FlagOption options)
	Use to set options of the transfer manager.

void	setCbStarted (CbStarted fct)
	Use to set started transfer callback.

void	setCbProgress (CbProgress fct)
	Use to set progress transfer callback.

void	setCbCompleted (CbCompleted fct)
	Use to set completed transfer callback.

void	setCbFailed (CbFailed fct)
	Use to set failed transfer callback.

Static Public Member Functions
static double	transferProgressToPercent (size_t transferTotal, size_t transferNow)
	Use to convert progress data to a percentage.

static std::string	flagOptionToStr (FlagOption options, char separator='\|')
	Use to convert flags option to a string.

static const std::string &	idErrorToStr (IdError idErr)

Detailed Description

Use to perform download/upload of ressources easily.

This class will allow to easily perform download/upload ressources from/to a remote.
A simple example used to download/upload a list of request:

#include <iostream>
#include <map>
#include <thread>
 
#include <transferease/transfermanager.h>
 
/*****************************/
/* Example details           */
/*****************************/
 
/*
 * Simple example to download/upload a list of requests.
 * Note that default callback behaviour are used 
 * here to reduce example size. 
 */
 
/*****************************/
/* Macro definitions         */
/*****************************/
 
#define CFG_HOST        "0.0.0.0"
#define CFG_USERNAME    "myusername"
#define CFG_PASSWD      "mypasswd"
#define CFG_MAX_TRIALS  1
 
#define RUN_DL_ENABLE   true    // Only here to simplify example : set to "false" for upload
 
/*****************************/
/* Class aliases             */
/*****************************/
 
using BytesArray = tease::BytesArray;
using Manager = tease::TransferManager;
using Request = tease::Request;
using Url = tease::Url;
 
/*****************************/
/* Functions helpers         */
/*****************************/
 
static void prepareRequestsDl(Request::List &listReqs)
{
    /* Create server ressources path */
    const std::vector<std::string> listPaths =
    {
        "mypath/res/entity1.zip",
        "mypath/res/entity2.zip",
        "mypath/res/entity3.zip"
    };
 
    /* Prepare requests */
    for(auto it = listPaths.cbegin(); it != listPaths.cend(); ++it){
        Url url;
        url.setIdScheme(Url::SCHEME_FTP);
        url.setHost(CFG_HOST);
        url.setPath(*it);
 
        Request::PtrShared req = std::make_shared<Request>();
        req->configureDownload(url);
 
        listReqs.push_back(req);
    }
}
 
static void prepareRequestsUp(Request::List &listReqs)
{
    /* Create ressources path */
    const std::map<std::string, std::string> mapRrcs =
    {
        {"entity1.zip", "path/server/entity1.zip"},
        {"entity2.zip", "path/server/entity2.zip"},
    };
 
    /* Prepare requests */
    for(auto it = mapRrcs.cbegin(); it != mapRrcs.cend(); ++it){
        // Load ressources to upload
        BytesArray data;
        data.setFromFile(it->first);
 
        // Set destination URL
        Url url;
        url.setIdScheme(Url::SCHEME_FTP);
        url.setHost(CFG_HOST);
        url.setPath(it->second);
 
        // Create associated request
        Request::PtrShared req = std::make_shared<Request>();
        req->configureUpload(url, std::move(data));
 
        listReqs.push_back(req);
    }
}
 
/*****************************/
/* Main method               */
/*****************************/
 
int main(int argc, char *argv[])
{
    Manager manager;
    Request::List listReqs;
 
    /* Configure transfer manager */
    manager.setUserInfos(CFG_USERNAME, CFG_PASSWD);
    manager.setNbMaxTrials(CFG_MAX_TRIALS);
 
    /* Create requests and start transfer */
#if RUN_DL_ENABLE
    prepareRequestsDl(listReqs);
    Manager::IdError idErr = manager.startDownload(listReqs);
#else
    prepareRequestsUp(listReqs);
    Manager::IdError idErr = manager.startUpload(listReqs);
#endif
 
    if(idErr != Manager::ERR_NO_ERROR){
        std::cerr << "Failed to start transfer [id-err: " << idErr << "]" << std::endl;
        return 1;
    }
 
    /*
     * Placeholder loop used to wait for the transfer to finish before exiting application.
     * In a real application, prefer to use callbacks methods !
     */
    while(manager.transferIsInProgress()) {
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
    }
 
    std::cout << "Done" << std::endl;
 
    return 0;
}

Note: For a more real-world example, we can refer to application using this library at:
https://github.com/legerch/TransferEaseApp

This class allow to register custom callbacks using std::function type. We have multiple ways to register a callback function:

/* Using lambda */
transferManager.setCbFailed([](tease::Request::TypeTransfer typeTransfer, tease::TransferManager::IdError idErr){
    std::cerr << "Failed to perform transfer [type: " << typeTransfer << ", id-err: " << idErr << "]" << std::endl;
});
 
/* Using class methods : static or member */
class CustomClass
{
public:
    CustomClass()
    {
        m_transferManager.setCbFailed(myMethodStaticForFailure); // Register static method
        m_transferManager.setCbFailed(std::bind(&CustomClass::myMethodMemberForFailure, this, std::placeholders::_1, std::placeholders::_2)); // Register member method
    }
 
private:
    void myMethodMemberForFailure(tease::Request::TypeTransfer typeTransfer, tease::TransferManager::IdError idErr){...}
 
private:
    static void myMethodStaticForFailure(tease::Request::TypeTransfer typeTransfer, tease::TransferManager::IdError idErr){...}
 
private:
    tease::TransferManager m_transferManager;
}

Note

Some developer useful docs:

See also: startDownload(); tease::Url

Member Typedef Documentation

◆ CbCompleted

using tease::TransferManager::CbCompleted = std::function<void(Request::TypeTransfer typeTransfer)>

Callback called when transfer finished and succeed.

Parameters

[in] typeTransfer Type of transfer which succeeded to complete.

See also: setCbCompleted(); startDownload()

◆ CbFailed

using tease::TransferManager::CbFailed = std::function<void(Request::TypeTransfer typeTransfer, IdError idErr)>

Callback called when transfer finished due to an error.

Parameters

[in] typeTransfer Type of transfer which failed to complete.

See also: setCbFailed(); startDownload()

◆ CbProgress

using tease::TransferManager::CbProgress = std::function<void(Request::TypeTransfer typeTransfer, size_t transferTotal, size_t transferNow)>

Callback called during transfer.

Parameters

[in]	typeTransfer	Type of transfer being started.
[in]	transferTotal	Total size of the transfer in bytes
[in]	transferNow	Current values of transfered data in bytes

See also: setCbProgress(); startDownload()

◆ CbStarted

using tease::TransferManager::CbStarted = std::function<void(Request::TypeTransfer typeTransfer)>

Callback called when transfer has been started.

Parameters

[in] typeTransfer Type of transfer being started.

See also: setCbStarted(); startDownload()

Member Enumeration Documentation

◆ FlagOption

enum tease::TransferManager::FlagOption : std::uint32_t

List of available options.

See also: setOptions(); flagOptionToStr()

Enumerator
OPT_NONE	0	No options defined, use this value to reset flags
OPT_VERBOSE	1 << 0	Enable to provide a lot of verbose informations, you hardly ever want this enabled in production use, you almost always want this used when you debug/report problems.
OPT_FTP_CREATE_DIRS	1 << 1	When uploading ressource via FTP protocol, missing directories will be automatically created. Note that this option will be ignored for any other protocol.

◆ IdError

enum tease::TransferManager::IdError

List of errors identifiers.

Enumerator
ERR_NO_ERROR	0	Success return code, no error detected
ERR_INTERNAL		Internal error mainly due to underlying library, please refer to logs if this error is triggered
ERR_INVALID_LOGIN		Login informations used were wrong
ERR_INVALID_REQUEST		Receive an invalid request : can be an unsupported protocol and a misformatted request
ERR_INVALID_SSL		Provided SSL informations are invalid
ERR_BUSY		Manager is already performing requests transfers
ERR_USER_ABORT		User abort current transfer
ERR_MAX_TRIALS		Maximum number of trials were reached
ERR_MEMORY_FULL_HOST		Trying to download a ressource to host which have his memory full
ERR_MEMORY_FULL_REMOTE		Trying to upload a ressource to remote which have his memory full
ERR_HOST_NOT_FOUND		Host server informations are either invalid or unreachable
ERR_HOST_REFUSED		Host server refused connection
ERR_CONTENT_NOT_FOUND		Ressource could not be found

Member Function Documentation

◆ abortTransfer()

void tease::TransferManager::abortTransfer ( )

Use to abort current transfer.

This method will return directly, that don't mean that transfer has been aborted yet.
Once transfer aborted, callback TransferManager::CbFailed will be called with error code TransferManager::ERR_USER_ABORT.
Nothing will be perform if no transfer is currently running

Note: This method is thread-safe; This method is asynchronous, so please use dedicated callbacks to manage transfer status.

See also: startDownload(), startUpload()

◆ flagOptionToStr()

std::string tease::TransferManager::flagOptionToStr	(	FlagOption	options,
		char	separator = '\|' )

static

Use to convert flags option to a string.

Parameters

[in]	options	Options to convert to string
[in]	separator	Character separator to use between each options

Returns: Returns string of options.
Example:
const FlagOption options = (TransferManager::OPT_FTP_CREATE_DIRS | TransferManager::OPT_VERBOSE)

std::cout << TransferManager::flagOptionToStr(options, '|'); // Will display: "OPT_FTP_CREATE_DIRS|OPT_VERBOSE"

tease::TransferManager::FlagOption
FlagOption
List of available options.
Definition transfermanager.h:52

tease::TransferManager::OPT_FTP_CREATE_DIRS
@ OPT_FTP_CREATE_DIRS
Definition transfermanager.h:56

tease::TransferManager::OPT_VERBOSE
@ OPT_VERBOSE
Definition transfermanager.h:55

tease::TransferManager::flagOptionToStr
static std::string flagOptionToStr(FlagOption options, char separator='|')
Use to convert flags option to a string.
Definition transfermanager.cpp:1176

◆ getNbMaxTrials()

int tease::TransferManager::getNbMaxTrials ( ) const

Retrieve maximum number of trials currently set.

Note: This method is thread-safe

Returns: Returns maximum number of trials currently set.

See also: setNbMaxTrials()

◆ getOptions()

TransferManager::FlagOption tease::TransferManager::getOptions ( ) const

Retrieve transfer options.

Note: This method is thread-safe

Returns: Returns transfer options.

See also: setOptions()

◆ getTimeoutConnection()

long tease::TransferManager::getTimeoutConnection ( ) const

Retrieve connection timeout.

Note: This method is thread-safe

Returns: Returns connection timeout in seconds currently set.

See also: setTimeoutConnection()

◆ getTimeoutTransfer()

long tease::TransferManager::getTimeoutTransfer ( ) const

Retrieve transfer timeout.

Note: This method is thread-safe

Returns: Returns transfer timeout in seconds currently set.

See also: setTimeoutTransfer()

◆ getUserLogin()

const std::string & tease::TransferManager::getUserLogin ( ) const

Retrieve login information currently used.

Note: This method is thread-safe

Returns: Returns user information login.

See also: setUserInfos()

◆ getUserPasswd()

const std::string & tease::TransferManager::getUserPasswd ( ) const

Retrieve password information currently used.

Note: This method is thread-safe

Returns: Returns user information password.

See also: setUserInfos()

◆ setCbCompleted()

void tease::TransferManager::setCbCompleted ( CbCompleted fct )

Use to set completed transfer callback.

Default callback will simply log a message.
See TransferManager documentation for more details on how to set the callback.

Parameters

[in] fct Callback function to use when transfer is completed

Note: This method is thread-safe

◆ setCbFailed()

void tease::TransferManager::setCbFailed ( CbFailed fct )

Use to set failed transfer callback.

Default callback will simply log a message.
See TransferManager documentation for more details on how to set the callback.

Parameters

[in] fct Callback function to use when transfer has failed

Note: This method is thread-safe

◆ setCbProgress()

void tease::TransferManager::setCbProgress ( CbProgress fct )

Use to set progress transfer callback.

Default callback will simply log a message.
See TransferManager documentation for more details on how to set the callback.

Parameters

[in] fct Callback function to use for transfer progress

Note: This method is thread-safe

◆ setCbStarted()

void tease::TransferManager::setCbStarted ( CbStarted fct )

Use to set started transfer callback.

Default callback will simply log a message.
See TransferManager documentation for more details on how to set the callback.

Parameters

[in] fct Callback function to use when transfer is started

Note: This method is thread-safe

◆ setNbMaxTrials()

void tease::TransferManager::setNbMaxTrials ( int nbTrials )

Use to set maximum number of trials.

If a request fail, it will be restarted until max number of trials is reached.
Default value is: 1

Parameters

[in] nbTrials Maximum number of trials allowed

Note: This method is thread-safe

See also: getNbMaxTrials()

◆ setOptions()

void tease::TransferManager::setOptions ( FlagOption options )

Use to set options of the transfer manager.

Parameters

[in] options Option flag(s) to use.
Default value is: TransferManager::OPT_NONE

Note: This method is thread-safe

See also: getOptions()

◆ setTimeoutConnection()

void tease::TransferManager::setTimeoutConnection ( long timeout )

Use to set the maximum time in seconds that allow connection phase to take.

This timeout only limits the connection phase, it has no impact once connection has been done.
The connection phase includes the name resolve (DNS) and all protocol handshakes and negotiations until there is an established connection with the remote side.

Parameters

[in] timeout Timeout in seconds.
To disable it, use value 0. Default value is: 10

Note: This method is thread-safe

See also: getTimeoutConnection()

◆ setTimeoutTransfer()

void tease::TransferManager::setTimeoutTransfer ( long timeout )

Use to set the maximum time in seconds to wait when no data is received before considering a timeout.

This timeout is used when connection to host has been made, it will check for average speed transfer.
If transfer speed is below 20 bytes/sec for timeout time, request is aborted (and retried if available).

Parameters

[in] timeout Timeout in seconds.
To disable it, use value 0. Default value is: 10

Note: This method is thread-safe

See also: getTimeoutTransfer()

◆ setUserInfos()

void tease::TransferManager::setUserInfos	(	const std::string &	username,
		const std::string &	passwd )

Use to set user informations.

Can be useful if server require authentication.

Parameters

[in]	username	Login username to use.
[in]	passwd	Login password to use.

Note: This method is thread-safe; If credentials are invalid, transfer will failed with error TransferManager::ERR_INVALID_LOGIN

See also: getUserLogin(), getUserPasswd()

◆ startDownload()

TransferManager::IdError tease::TransferManager::startDownload ( const Request::List & listReqs )

Use to start downloading list of requests.

Parameters

[in,out] listReqs List of requests to download.
This argument is a list of request pointers, those will be directly filled with downloaded datas, so pointers must remains valid.
Once transfer is finished, user can read request content directly

Note: This method is thread-safe; This method is asynchronous, so please use dedicated callbacks to manage transfer status.

Returns: Returns TransferManager::ERR_NO_ERROR if download succeed to be prepared.
This method will return TransferManager::ERR_BUSY error if a transfer is already running or if called from a callback.

See also: startUpload(); abortTransfer()

◆ startUpload()

TransferManager::IdError tease::TransferManager::startUpload ( const Request::List & listReqs )

Use to start upload list of requests.

Parameters

[in,out] listReqs List of requests to upload.
This argument is a list of request pointers, those will be directly read in order to upload datas, so pointers must remains valid.
Once transfer is finished, user can still use request content.

Note: This method is thread-safe; This method is asynchronous, so please use dedicated callbacks to manage transfer status.

Returns: Returns TransferManager::ERR_NO_ERROR if upload succeed to be prepared.
This method will return TransferManager::ERR_BUSY error if a transfer is already running or if called from a callback.

See also: startDownload(); abortTransfer()

◆ transferIsInProgress()

bool tease::TransferManager::transferIsInProgress ( ) const

Verify is a tranfer is in progress or not.

Note: This method is thread-safe

Returns: Returns true if a transfer is currently running

◆ transferProgressToPercent()

double tease::TransferManager::transferProgressToPercent	(	size_t	transferTotal,
		size_t	transferNow )

static

Use to convert progress data to a percentage.

Parameters

[in]	transferTotal	Total size of the transfer
[in]	transferNow	Current size of transferred datas

Returns: Return progress percentage.

The documentation for this class was generated from the following files:

include/transferease/transfermanager.h
src/transfermanager.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ CbCompleted

◆ CbFailed

◆ CbProgress

◆ CbStarted

Member Enumeration Documentation

◆ FlagOption

◆ IdError

Member Function Documentation

◆ abortTransfer()

◆ flagOptionToStr()

◆ getNbMaxTrials()

◆ getOptions()

◆ getTimeoutConnection()

◆ getTimeoutTransfer()

◆ getUserLogin()

◆ getUserPasswd()

◆ setCbCompleted()

◆ setCbFailed()

◆ setCbProgress()

◆ setCbStarted()

◆ setNbMaxTrials()

◆ setOptions()

◆ setTimeoutConnection()

◆ setTimeoutTransfer()

◆ setUserInfos()

◆ startDownload()

◆ startUpload()

◆ transferIsInProgress()

◆ transferProgressToPercent()