Volcengine TOS SDK for C++

The TOS C++ SDK enables C++ developers to easily work with TOS(Tinder Object Storage) service in the volcengine. This document will show developers some basic examples about TOS bucket and object operation. More details can be found in document

Install

Requirements

• C++ 11 or later
• CMake (version 3.1 or later)
• GCC 4.8 or later
• Clang 3.3 or later

Build through sources

1. Download the source code.

• You can simply download from release
• You can clone the source codes

git clone https://github.com/volcengine/ve-tos-cpp-sdk

2. Build with CMake 3.1 or later

cd ve-tos-cpp-sdk
mkdir build
cd build

The SDK depends on curl and openssl libraries. Before building the sdk library, please make sure that you have installed curl and openssl in your platform.

Linux

Install libcurl and openssl libraries through the following command.

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y libcurl4-openssl-dev libssl-dev

# Redhat/Fedora
sudo dnf install -y libcurl-devel openssl-devel

Run the following commands to build and install.

cmake ../ -DCMAKE_INSTALL_PREFIX="your path to install sdk"
make
make install

Macos

On macos platform, you should specify the openssl lib path. Take the following command as an example.

cmake .. -DOPENSSL_ROOT_DIR=/usr/local/Cellar/openssl@3/3.0.0 
         -DOPENSSL_LIBRARIES=/usr/local/Cellar/openssl@3/3.0.0/lib 
         -DOPENSSL_INCLUDE_DIRS=/usr/local/Cellar/openssl@3/3.0.0/include
         -DCMAKE_INSTALL_PREFIX="your path to install sdk"
make
make install

Windows

Please run the VS developer command prompt as an administrator and run the following command in the build directory file to compile and install.

cmake ../
msbuild ALL_BUILD.vcxproj
msbuild INSTALL.vcxproj

CMake Build Options

BUILD_SHARED_LIB

This option is default off and cmake only builds static library. If turn it on while building, CMake will both build static and shared libraries. The SDK will link to the shared lib.

cmake .. -DBUILD_SHARED_LIB=ON

BUILD_DEMO

This option is default off. If turn it on while building, CMake will build some examples about how to use SDK. Your can find more details in the example folder.

cmake .. -DBUILD_DEMO=ON

BUILD_UNITTEST

This option is default off. If turn it on while building, CMake will build the unittests. Your can find more details in the test folder.

cmake .. -DBUILD_UNITTEST=ON

Get Started

This section introduces how to create a bucket, upload/download/delete an object in TOS service through our SDK.

Init a TOSClient

You can interact with TOS service after initiating a TOSClient instance. The accesskey and secretkey of your account, endpoint and region are required as params.

#include "TosClientV2.h"
using namespace VolcengineTos;
std::string region("Your Region");

// Retrieve access credentials from environment variables. Before running the code, please make sure that the environment variables TOS_ACCESS_KEY and TOS_SECRET_KEY have been set.
std::string accessKey = std::getenv("TOS_ACCESS_KEY");
std::string secretKey = std::getenv("TOS_SECRET_KEY");

// init your client
InitializeClient();
// create a client handle for interacting
TosClientV2 client(region, accessKey, secretKey);
/*
do something with the client
*/
// close the client
CloseClient();

DNS IP balancing

When ClientConfig::enableDnsIpBalancing is true and ClientConfig::dnsCacheTime is greater than 0, the SDK enables SDK-managed IP balancing for endpoint hosts that resolve to multiple IP addresses. The transport rotates the selected IP for each request and evicts a failed IP after retryable connection failures. This keeps request signing and TLS/SNI bound to the original host while spreading connections across the resolved IP set.

The SDK-side host cache keeps up to ClientConfig::dnsCacheHostCapacity hosts and evicts the least recently used host when the capacity is exceeded. The default value is 1024.

When ClientConfig::enableDnsIpBalancing is false or ClientConfig::dnsCacheTime is 0, the SDK keeps the existing libcurl-based behavior and does not apply SDK-managed multi-IP balancing.

ClientConfig config;
config.dnsCacheTime = 5; // minutes, DNS cache TTL
config.enableDnsIpBalancing = true; // optional, enables SDK-managed IP balancing
config.dnsCacheHostCapacity = 1024; // optional, max cached hosts for SDK-side DNS/IP cache

InitializeClient();
TosClientV2 client(region, accessKey, secretKey, config);

Creat a bucket

The bucket is a kind of unique namespace in TOS, which is a container to store data. This example shows you how to create a bucket.

std::string bucketName("Your Bucket Name");
CreateBucketV2Input input(bucketName);
auto output = client.createBucket(input);
if (!output.isSuccess()){
  std::cout << output.error().String() << std::endl;
  return;
}
std::cout << output.result().getLocation() << std::endl;

PutObject

You can put your file as an object into your own bucket.

// data is what you want to upload, wrap it as a stringstream.
std::string bucketName("Your Bucket Name");
std::string data("1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./   :'1234567890abcdefghijklmnopqrstuvwxyz~!@#$%^&*()_+<>?,./   :'");
auto ss = std::make_shared<std::stringstream>(data);
std::string objectKey("Your Object Key");
PutObjectV2Input input(bucketName, objectKey, ss);
auto output = client.putObject(input);
if (!output.isSuccess()) {
  std::cout << "put object error: "
            << output.error().String()
            << std::endl;
  return;
}
std::cout << "put object success, object etag is: "
          << output.result().getEtag()
          << std::endl;

GetObject

You can download objects in the TOS bucket through our SDK.

std::string bucketName("Your Bucket Name");
std::string objectKey("Your Object Key");
GetObjectV2Input input(bucketName, objectKey);
auto output = client.getObject(input);
if (!output.isSuccess()){
  std::cout << output.error().String() << std::endl;
  return;
}
std::cout << output.result().getObjectMeta().getEtags() << std::endl;

DeleteObject

Your can delete your objects in the bucket.

std::string bucketName("Your Bucket Name");
std::string objectKey("Your Object Key");
DeleteObjectInput input(bucketName, objectKey);
auto output = client.deleteObject(input);
if (!output.isSuccess()){
  std::cout << output.error().String() << std::endl;
  return;
}
std::cout << output.result().getRequestInfo().getRequestId() << std::endl;

Security and privacy

This project takes security seriously. For vulnerability reporting and supported versions, see SECURITY.md

License

Apache License 2.0