Docs

Torch Object Storage

C++

Initializing the Client (C++ SDK)

TOSClient provides a set of interfaces for interacting with the TOS service, enabling the management of resources such as buckets and objects. You can initialize TOSClient using methods such as AccessKey/SecretKey, STS (Security Token Service), and other similar approaches. When initializing TOSClient, TOS also supports configuring optional parameters such as connection establishment timeout. You may refer to this document to configure these parameters according to your business requirements.

When initializing TosClient, you must provide the AccessKey, SecretKey, and Region.

Prerequisites

Installing the SDK

Obtaining AKSK Information

Configuring Long-Term Access Credentials

Before initializing the SDK, you must first configure long-term access credentials. This chapter outlines the procedures for configuring long-term access credentials across different operating systems.

macOS

Linux

Windows

Open the terminal and execute the following command to open the file.

Add AKSK information at the end of the document.

Save the file and exit.

Execute the following commands to make the configuration information take effect.

Execute the following command to verify the configuration information.

If the configuration is successful, the following example will be returned:

Creating TosClient

warning

The TosClient instance is thread-safe and supports concurrent access by multiple threads. You may create a single TosClient instance for multi-threaded invocation, or create multiple TosClient instances for separate use.

InitializeClient() and CloseClient() are global interfaces that should be invoked only once during the program's lifecycle.

Configure mandatory parameters

TosClient is used to manage TOS resources such as storage buckets (Bucket) and files (Object). The following sample code demonstrates how to initialize TosClient using only the required parameters: AccessKey, SecretKey, and Region.

tip

Endpoint is the access domain name for TOS external services. For information on the endpoints supported by TOS, please refer to Access Domain Name Endpoint.

AKSK information can be obtained from environment variables. For configuration instructions, please refer to Configuring Access Credentials.

Common Configuration Scenarios

ClientConfig is the configuration class for TOSClient, allowing the specification of parameters such as endpoint, timeout duration, and whether to perform CRC data validation. When initiating a request using the C++ SDK, you need to initialize a TosClient instance and modify the default configuration options in ClientConfig as needed.

Configuring STS

If you do not wish to disclose long-term key information, you can use the STS service to generate temporary access credentials. This allows users to access TOS resources within a specified time frame; once expired, the credentials become invalid, effectively safeguarding your resources.

tip

You can obtain temporary access credentials by calling the STS service's AssumeRole API. Temporary access credentials consist of temporary access keys (AccessKeyId and AccessKeySecret) and a security token (SecurityToken). You may subsequently use this information to access the TOS service. For specific steps on setting up the STS service, please refer to Using STS Temporary AK/SK+Token to Access Volcengine TOS.

The following code example demonstrates how to configure the initialization of the TOS C++ SDK using an STS Token.

Configure Timeout Mechanism

When initializing TosClient, you can configure the network request timeout by adding optional parameters. The TOS C++ SDK currently supports setting the connection timeout (connectionTimeout) and the read/write request timeout (socketTimeout). The following code example is used to configure a timeout mechanism:

Configuring Retry Strategies

The TOS C++ SDK configures the number of retry attempts after a request failure through the initialization parameter maxRetryCount, helping to address request failures caused by issues such as network jitter and reducing the probability of users encountering intermittent errors. In cases of request timeout, or when the server returns 5xx errors or 429 errors, retries are performed for scenarios with idempotent semantics using an exponential backoff strategy based on the number of retry attempts.

During TOS retries, exponential backoff is applied with a base interval of 100 ms until the maximum retry count is reached. For example, if the maximum retry count is three, the retry intervals are 100 ms, 200 ms, and 400 ms, respectively.

tip

To disable the retry mechanism, set maxRetryCount to a value less than or equal to zero.

The following code example is used to configure a retry strategy.

Configuration Data Validation

During object upload and download, the TOS server returns the object's Crc64 value. The SDK verifies whether the locally computed Crc64 matches the Crc64 returned by TOS, thereby ensuring the integrity of uploaded and downloaded data. To ensure data integrity during upload and download processes, the SDK enables Crc64 data verification by default. You may disable the Crc64 verification feature by specifying an optional parameter when initializing TosClient.

danger

It is strongly recommended that you do not disable the Crc64 data verification feature. If this feature is disabled, TOS does not guarantee data integrity during upload and download operations.

The following code example demonstrates how to configure CRC verification.

Configure DNS Cache

In public network environments, there may be scenarios where domain name resolution for TOS services is time-consuming or unavailable for a period of time. To address this, the TOS C++ SDK supports configuring the DNS cache validity period through the initialization parameter dnsCacheTime. The default value is 0, which indicates that the domain name caching feature is disabled. The following code example is used to set up the DNS cache.

Configure Proxy Server

The TOS C++ SDK supports accessing TOS services via a proxy server. You can configure the proxy server by adding an optional parameter when initializing TosClient.

tip

Currently, only HTTP protocol proxies are supported.

The following code is used to configure the proxy server.

Configure Connection Pool

The TOS C++ SDK supports connection pool configuration. When initializing the TosClient, you can specify optional parameters to configure the connection pool size.

The following code is used to configure the connection pool.

Configure Custom Domain Name

The TOS C++ SDK supports the configuration of custom domain names. When initializing TosClient, you can specify a custom domain name as the Host. After specifying a custom domain name, it is not necessary to provide the Bucket parameter when using the SDK interface.

tip

Before using a custom domain name, you must configure the custom domain name on the server. For detailed instructions, please refer to Setting Up a Custom Domain Name.

In the SDK, the isCustomDomain identifier can be used to indicate that the current domain name is a custom domain.

Initialization Parameter List

The following parameters are optional when initializing TOSClient.

Parameters	Parameter Type	Mandatory	Sample Value	Description
ak	string	Mandatory	AKTPYmI1Z****	Access Key ID, that is, Key ID.
sk	string	Mandatory	T1dJM01UU****	SecretAccess Key, that is, a private access key.
region	string	Mandatory	cn-beijing	TOS server region.
securityToken	string	Optional	STSkeyJBY2NvdW50SW************	The security token in the temporary access credential.
endPoint	string	Optional	tos-cn-beijing.volces.com	TOS server-side domain name. The default value is empty. If no protocol is specified, the HTTPS protocol is used by default, with the complete format being https://{host}:{port}.
enableVerifySSL	bool	Optional	true	Configure whether to enable SSL certificate verification; enabled by default.
autoRecognizeContentType	bool	Optional	true	Automatic MIME type recognition is enabled by default.
requestTimeout	int	Optional	120000	Set the timeout duration for a single HTTP request in milliseconds; the default value is 120,000 milliseconds.
connectionTimeout	int	Optional	10000	Set the connection establishment timeout period in milliseconds; the default value is 10,000 milliseconds.
enableCRC	bool	Optional	true	Whether to enable CRC data verification; enabled by default.
dnsCacheTime	int	Optional	3	Validity period of DNS cache (unit: minutes). A value less than or equal to 0 disables DNS cache. The default value is 0.
proxyHost	string	Optional	localhost	Host address of the proxy server; currently, only the HTTP protocol is supported.
proxyPort	int	Optional	8080	Port number of the proxy server.
proxyUsername	string	Optional	Alice	Username used for connecting to the proxy server.
proxyPassword	string	Optional	pwd123	The user password used when connecting to the proxy server.
maxRetryCount	int	Optional	3	Maximum number of retries allowed after a request failure. Default: three times.
maxConnections	int	Optional	25	Maximum number of connections in the connection pool. Default: 25.
socketTimeout	int	Optional	30000	Request timeout duration. If no data is received within the request timeout period, the connection will be closed. The default timeout is 30,000 milliseconds.
isCustomDomain	bool	Optional	false	Whether to prepend the bucket name to the Endpoint to access TOS using the virtual host domain name method; the value descriptions are as follows: true: Do not concatenate. false: Concatenation. The default value is false. tip When accessing TOS via a custom domain, you must set isCustomDomain to true.

Last updated: 2025.09.25 14:22:45