deniskovalchuk / libftp

A cross-platform FTP/FTPS client library based on Boost.Asio

libftp

A cross-platform FTP client library based on Boost.Asio.

Table of contents

1. Overview
2. Features
3. Examples
4. Integration
5. Building
6. References

Overview

FTP (File Transfer Protocol) is a standard network protocol used to transfer files between a client and a server. FTP is built on a client-server model and uses separate connections for transferring commands and files.

Connections

• Control connection is a persistent connection used to transfer commands and replies between the client and the server.
• Data connection is a temporary connection used to transfer files. The connection is only open for the duration of the data transfer.

Transfer modes

The transfer mode determines how the data connection is established.

• In active mode, the client uses the control connection to send the server the IP address and port number on which the client accepts incoming data connections. The server then uses this information to open a data connection.
• In passive mode, the client uses the control connection to request from the server the IP address and port number on which the server accepts incoming data connections. The client then uses this information to open a data connection. This mode can be used in situations where the client cannot accept incoming connections (firewall, NAT).

Transfer types

The transfer type determines how data is transferred.

• ASCII type can be used to transfer ASCII files between systems with different newline representations. In this case, the sending side converts the newlines from system style to CRLF style, and the receiving side performs the reverse conversion.
• Binary type is used to transfer files byte by byte. This transfer type is used by default.

Features

• Windows, Linux and macOS are supported.
• Supports FTP and FTP over TLS/SSL (FTPS).
• Supports IPv4 and IPv6.
• Supports active and passive transfer modes.
• Supports ASCII and binary transfer types.

Examples

Download the README.TXT file from ftp.freebsd.org and output its contents to stdout:

#include <iostream>
#include <sstream>

#include <ftp/ftp.hpp>

int main(int argc, char *argv[])
{
    ftp::client client;

    client.connect("ftp.freebsd.org", 21, "anonymous");

    std::ostringstream oss;

    client.download_file(ftp::ostream_adapter(oss), "pub/FreeBSD/README.TXT");

    std::cout << oss.str();

    client.disconnect();

    return 0;
}

See more examples in the example folder.

Integration

This library can be integrated into a project via CMake's FetchContent, for example:

cmake_minimum_required(VERSION 3.14)
project(application)

include(FetchContent)
FetchContent_Declare(
        libftp
        GIT_REPOSITORY https://github.com/deniskovalchuk/libftp.git
        GIT_TAG        v0.5.0)
FetchContent_MakeAvailable(libftp)

add_executable(application main.cpp)
target_link_libraries(application ftp::ftp)

Building

Prerequisites

• A C++17-compliant compiler
• CMake 3.14 or newer
• Boost 1.67.0 or newer
• OpenSSL
• Python3 (only for tests)

Windows

Build and run tests:

tool/windows/build.ps1 [-BuildType Debug|Release] [-RunTest]

Clean the builds:

tool/windows/clean.ps1

Linux/macOS

Build and run tests:

tool/unix/build.sh [--debug | --release] [--test]

Clean the builds:

tool/unix/clean.sh

Custom environment

Build:

$ mkdir -p build
$ cd build
$ cmake ..
$ cmake --build .

To run tests, set the LIBFTP_TEST_SERVER_PATH environment variable to the path to the server.py file:

$ export LIBFTP_TEST_SERVER_PATH="/path/to/server.py"
$ cd test
$ ctest -V

References

• RFC 959 File Transfer Protocol (FTP). J. Postel, J. Reynolds. October 1985.
• RFC 2228 FTP Security Extensions. October 1997.
• RFC 2428 Extensions for IPv6, NAT, and Extended passive mode. September 1998.
• RFC 3659 Extensions to FTP. P. Hethmon. March 2007.
• RFC 4217 Securing FTP with TLS. October 2005.

libftp's Issues

Use success, thanks

A suggestion for creating multi-level directories.

bool client::mkdir(const string& directory_name) {
try {
if (!is_open()) {
throw ftp_exception("Connection is not open.");
}

std::filesystem::path path(directory_name);
auto ss = path.string();
if (ss == "")return false;
try {
  if (ls(ss)) return true;
} catch (...) {
}

std::vector<string> sub_dirs;
for (auto& sub : path) {
  sub_dirs.push_back(sub.string());
}

string to_dir;

if (sub_dirs.empty()) {
  throw ftp_exception("MKD empty sub_dirs.");
}
reply_t reply;
for (auto i = 0; i < sub_dirs.size(); i++) {
  auto s = sub_dirs[i];
  if (s == "") break;
  to_dir += s;
  to_dir += "/";

  reply = send_command("MKD " + to_dir);
}
if (reply.status_code == 550) return true;
return reply.is_positive();

} catch (const connection_exception& ex) {
reset_connection();
throw ftp_exception(ex);
}
}