Transfer Ease

C++ cross-platform library TransferEase which provide methods to download/upload datas easily.

Remarks

Latest development/pull requests will be committed into main branch.
Each stable release have their dedicated branch:

• 1.0.x: branch dev/1.0
• 1.1.x: branch dev/1.1
• etc...

Table of contents :

• 1. Requirements
  • 1.1. C++ Standards
  • 1.2. Dependencies
• 2. Integration
  • 2.1. How to build
  • 2.2. CMake options
• 3. How to use
  • 3.1. Usage
  • 3.2. Logs management
  • 3.3. Library version
    • 3.3.1. Compilation time
    • 3.3.2. Runtime
• 4. Library details
  • 4.1. Implementation
  • 4.2. Known issues
    • 4.2.1. Large files
• 5. Documentation
• 6. License

1. Requirements

1.1. C++ Standards

This library requires at least C++ 17 standard

1.2. Dependencies

Below, list of required dependencies:

Dependencies	VCPKG package	Comments
libcurl	curl	/
Google Tests	gtest	Only needed to run unit-tests

‍Dependency manager VCPKG is not mandatory, this is only a note to be able to list needed packages

2. Integration

2.1. How to build

This library can be use as an embedded library in a subdirectory of your project (like a git submodule for example) :

1. In the root CMakeLists, add instructions :

   add_subdirectory(TransferEase) # Or if library is put in a folder "dependencies" : add_subdirectory(dependencies/TransferEase)

2. In the application/library CMakeLists, add instructions :

   # Link needed libraries
   target_link_libraries(${PROJECT_NAME} PRIVATE transferease)

2.2. CMake options

This library provide some CMake options:

• TEASE_BUILD_TESTS: Use to enable/disable unit-tests of the library. Default value: ON.

3. How to use

3.1. Usage

Please refer to tease::TransferManager class documentation for more details

3.2. Logs management

This library use a virtual logger (based on this implementation) in order to let users of the library use their own log management mechanism. By default, no logs will be printed. To enable library log usage, caller must provide a class inheriting from tease::ILogger interface.
More details on how to use this log interface can be found inside abstract logger repository

3.3. Library version

3.3.1. Compilation time

In order to easily check at compilation time library version (to manage compatibility between multiple versions for example), macro TEASE_VERSION_ENCODE (defined inside transferease_global.h file) can be used:

#if TEASE_VERSION >= TEASE_VERSION_ENCODE(1,0,0)
    // Do stuff for version 1.0.0 or higher
#else
    // Do stuff for version 0.0.x
#endif

3.3.2. Runtime

Since library header used during final application build could differ from the actual library version, it is recommended to use the static method:

#include "transferease/version/semver.h"
 
const Semver &teaseSemver = tease::Semver::getLibraryVersion();

4. Library details

4.1. Implementation

This library use the PImpl Idiom in order to preserve ABI compatibility (Qt wiki also have a great tutorial on the PImpl idiom).
So only major release (this project use the semantic versioning) should break the ABI.

4.2. Known issues

4.2.1. Large files

Currently, library store all downloaded/uploaded datas in heap memory, that provide us some advantages:

• For uploaded datas, we don't have to load data from a file (we still can) but those can also be runtime generated
• For downloaded datas, we can play with received datas directly instead of writing them on the disk and reloading those into memory

But this behaviour also have downsides : since all datas are stored into heap memory, this could lead to issues when managing large ressources.
Currently, only uploaded datas have a safeguard (when loading data from file) set to 1 Gigabytes (1024^3 bytes).

Warning

No safeguard currently set for downloaded datas !

This issue will be taken care in a future release (via streams/chunks management) but I can only recommend to not use this library for now if downloaded files can be large.

5. Documentation

All classes/methods has been documented with Doxygen utility and automatically generated at online website documentation.

Note

This repository contains two kinds of documentation:

• Public API: Available via online website documentation or locally via Doxyfile docs/fragments/Doxyfile-public-api.in
• Internal: Available locally only via docs/fragments/Doxyfile-internal.in

To generate documentation locally, we can use:

# Run documentation generation
doxygen ./Doxyfile-name
 
# Under Windows OS, maybe doxygen is not added to the $PATH
"C:\Program Files\doxygen\bin\doxygen.exe" ./Doxyfile-name

Remarks

You can also load the Doxyfile into Doxywizard (Doxygen GUI) and run generation.

6. License

This library is licensed under MIT license.