cpp_client/README.md
Official C++ client library for FastDFS - A high-performance distributed file system.
mkdir build
cd build
cmake ..
cmake --build .
BUILD_SHARED_LIBS: Build shared library (default: ON)BUILD_EXAMPLES: Build example programs (default: ON)BUILD_TESTS: Build test programs (default: OFF)cmake --install .
#include "fastdfs/client.hpp"
#include <iostream>
int main() {
// Create client configuration
fastdfs::ClientConfig config;
config.tracker_addrs = {"192.168.1.100:22122"};
config.max_conns = 10;
config.connect_timeout = std::chrono::milliseconds(5000);
config.network_timeout = std::chrono::milliseconds(30000);
// Initialize client
fastdfs::Client client(config);
// Upload a file
std::string file_id = client.upload_file("test.jpg", nullptr);
std::cout << "File uploaded: " << file_id << std::endl;
// Download the file
std::vector<uint8_t> data = client.download_file(file_id);
std::cout << "Downloaded " << data.size() << " bytes" << std::endl;
// Delete the file
client.delete_file(file_id);
// Close client
client.close();
return 0;
}
std::vector<uint8_t> data = {'H', 'e', 'l', 'l', 'o', ',', ' ', 'F', 'a', 's', 't', 'D', 'F', 'S', '!'};
std::string file_id = client.upload_buffer(data, "txt", nullptr);
fastdfs::Metadata metadata;
metadata["author"] = "John Doe";
metadata["date"] = "2025-01-01";
metadata["description"] = "Test file";
std::string file_id = client.upload_file("document.pdf", &metadata);
client.download_to_file(file_id, "/path/to/save/file.jpg");
// Download bytes from offset 100, length 1024
std::vector<uint8_t> data = client.download_file_range(file_id, 100, 1024);
// Upload appender file
std::string file_id = client.upload_appender_file("log.txt", nullptr);
// Append data
std::vector<uint8_t> new_data = {'N', 'e', 'w', ' ', 'l', 'o', 'g', ' ', 'e', 'n', 't', 'r', 'y', '\n'};
client.append_file(file_id, new_data);
// Modify file content
std::vector<uint8_t> modified_data = {'M', 'o', 'd', 'i', 'f', 'i', 'e', 'd'};
client.modify_file(file_id, 0, modified_data);
// Truncate file
client.truncate_file(file_id, 1024);
// Upload slave file with prefix
std::vector<uint8_t> slave_data =;
std::string slave_file_id = client.upload_slave_file(
master_file_id, "thumb", "jpg", slave_data, nullptr);
// Set metadata
fastdfs::Metadata metadata;
metadata["width"] = "1920";
metadata["height"] = "1080";
client.set_metadata(file_id, metadata, fastdfs::MetadataFlag::OVERWRITE);
// Get metadata
fastdfs::Metadata retrieved = client.get_metadata(file_id);
for (const auto& pair : retrieved) {
std::cout << pair.first << " = " << pair.second << std::endl;
}
fastdfs::FileInfo info = client.get_file_info(file_id);
std::cout << "Size: " << info.file_size << std::endl;
std::cout << "CreateTime: " << info.create_time << std::endl;
std::cout << "CRC32: " << info.crc32 << std::endl;
struct ClientConfig {
std::vector<std::string> tracker_addrs; // Required: Tracker server addresses
int max_conns = 10; // Maximum connections per tracker
std::chrono::milliseconds connect_timeout{5000}; // Connection timeout
std::chrono::milliseconds network_timeout{30000}; // Network I/O timeout
std::chrono::milliseconds idle_timeout{60000}; // Connection pool idle timeout
bool enable_pool = true; // Enable connection pooling
int retry_count = 3; // Retry count for failed operations
};
The client provides detailed exception types:
try {
std::string file_id = client.upload_file("test.jpg", nullptr);
} catch (const fastdfs::FileNotFoundException& e) {
// Handle file not found
} catch (const fastdfs::ConnectionException& e) {
// Handle connection error
} catch (const fastdfs::TimeoutException& e) {
// Handle timeout
} catch (const fastdfs::FastDFSException& e) {
// Handle other FastDFS errors
} catch (const std::exception& e) {
// Handle other errors
}
The client is thread-safe and can be used concurrently from multiple threads:
std::vector<std::thread> threads;
for (int i = 0; i < 10; ++i) {
threads.emplace_back([&client, i]() {
std::string file_id = client.upload_file("file" + std::to_string(i) + ".txt", nullptr);
// Handle result...
});
}
for (auto& t : threads) {
t.join();
}
See the examples directory for complete usage examples:
Contributions are welcome! Please see CONTRIBUTING.md for details.
GNU General Public License V3 - see LICENSE for details.