Download and Installation
Download the COS XML C++ SDK source code below:
Linux/Windows/macOS: XML Linux C++ SDK Note:
If you encounter errors such as non-existent functions or methods when using the XML version of the SDK, update the SDK to the latest version and try again.
Precompilation (Recommended)
Download the XML C++ SDK source code. In the libs
directory, you can find the ready-to-use precompiled libraries. Choose the one that suits your system version. libs/linux/libcossdk.a
libs/linux/libcossdk-shared.so
libs/Win32/cossdk.lib
libs/x64/cossdk.lib
libs/macOS/libcossdk.a
libs/macOS/libcossdk-shared.dylib
Note:
Copy the libraries and SDK include
files for your OS to your project.
The following third-party dependent libraries can be found in the Third-party
directory:
third_party/lib/linux/poco/
third_party/lib/Win32/openssl/
third_party/lib/Win32/poco/
third_party/lib/x64/openssl/
third_party/lib/x64/poco/
third_party/lib/macOS/poco/
Note:
Copy the dependent libraries for your OS to your project.
Manual Compilation
Compilation options
You can configure the following compilation options by using the CMakeLists.txt
file in the root directory:
option(BUILD_UNITTEST "Build unittest" OFF)
option(BUILD_DEMO "Build demo" ON)
option(BUILD_SHARED_LIB "Build shared library" OFF)
Dependent libraries
Dynamic libraries: POCO, OpenSSL, and Crypto.
Compiling Linux SDK
1. Install the compiler and dependent libraries.
yum install -y gcc gcc-c++ make cmake openssl
2. Compile the SDK.
Download the XML C++ SDK source code to your development environment and run the following command: cd ${cos-cpp-sdk}
mkdir -p build
cd build
cmake ..
make
3. Install the POCO library.
cd ${cos-cpp-sdk}
sh install-libpoco.sh
Note:
This script installs the POCO dynamic library to the /usr/lib64
directory and creates a soft link. To use a COS SDK in the production environment, install the POCO library to the production environment as well.
4. Run the demo.
Note:
You can skip this step if you don't need to test the demo.
cd ${cos-cpp-sdk}
vim demo/cos_demo.cpp
vim CMakeLists.txt
cd build && make
ls bin/cos_demo
vim bin/config.json
cd bin && ./cos_demo
5. Use the SDK.
The compiled libraries can be found in the build/lib
directory. The static library name is libcossdk.a
, and the dynamic library name is libcossdk-shared.so
. During actual use, copy the include
directory to the include
path of your project.
Compiling Windows SDK
1. Install Visual Studio 2017.
Install the Visual Studio 2017 development environment.
2. Install CMake.
Download the CMake for Windows compiler from CMake official website, and then configure ${CMake installation path}\\bin
in the Path
environment variable. 3. Compile the SDK.
i. Download the XML Windows C++ SDK source code to your development environment.
ii. Open the Windows command-line tool, run cd
to the directory of the C++ SDK source code, and run the following command: mkdir build
cd build
cmake ..
cmake -G "Visual Studio 15 Win64" ..
iii. Use Visual Studio 2017 to open the Solution Explorer and perform compilation.
4. Run the demo.
Note:
You can skip this step if you don't need to test the demo.
Modify the demo code and compile it. The generated cos_demo.exe
file is in the bin
directory. You can modify bin/config.json
to run cos_demo.exe
.
5. Use the SDK.
The compiled libraries can be found in the build/Release
directory. The static library name is cossdk.lib
. During actual use, copy the include
directory to the include
path of your project.
Compiling macOS SDK
1. Install the compiler and dependent libraries.
brew install gcc make cmake openssl
2. Compile the SDK.
Download the XML C++ SDK source code to your development environment and run the following command: cd ${cos-cpp-sdk}
mkdir -p build
cd build
cmake ..
make
3. Install the POCO library.
The POCO library is in the third_party/lib/macOS/poco
directory. You can install it by yourself.
4. Run the demo.
Note:
You can skip this step if you don't need to test the demo.
Modify the demo code and compile it. The generated cos_demo
is in the bin
directory. Copy cos-cpp-sdk-v5/demo/config.json
to the bin
directory and modify bin/config.json
. Then, you can run cos_demo
.
5. Use the SDK.
The compiled libraries can be found in the build/lib
directory. The static library name is libcossdk.a
, and the dynamic library name is libcossdk-shared.dylib
. During actual use, copy the include
directory to the include
path of your project.
Common compilation errors
1. The following error information is displayed when the executable program is compiled:
PocoCrypto.so.64: undefined reference to `PEM_write_bio_PrivateKey@libcrypto.so.10'
libPocoNetSSL.so.64: undefined reference to `X509_check_host@libcrypto.so.10'
ibPocoCrypto.so.64: undefined reference to `ECDSA_sign@OPENSSL_1.0.1_EC'
libPocoCrypto.so.64: undefined reference to `CRYPTO_set_id_callback@libcrypto.so.10'
ibPocoCrypto.so.64: undefined reference to `EVP_PKEY_id@libcrypto.so.10'
libPocoNetSSL.so.64: undefined reference to `SSL_get1_session@libssl.so.10'
libPocoNetSSL.so.64: undefined reference to `SSL_get_shutdown@libssl.so.10'
libPocoCrypto.so.64: undefined reference to `EVP_PKEY_set1_RSA@libcrypto.so.10'
libPocoCrypto.so.64: undefined reference to `SSL_load_error_strings@libssl.so.10'
This is usually caused by the inconsistency between the project's built-in SSL version on which the POCO library compilation depends and the SSL version on your device. You need to compile the POCO library again and replace the POCO library in third_party
.
wget https://github.com/pocoproject/poco/archive/refs/tags/poco-1.9.4-release.zip
cd poco-poco-1.9.4-release/
./configure --omit=Data/ODBC,Data/MySQL
mkdir my_build
cd my_build
cmake ..
make -j5
2. The PocoNetSSL library failed to be compiled during POCO library compilation. This is usually because the openssl-devel
library is not installed.
yum install -y openssl-devel
3. The following error information is displayed when the executable program is compiled:
undefined reference to `qcloud_cos::CosConfig::CosConfig(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)
This is usually caused by the inconsistency between the project's built-in GCC version used by the libcossdk.a
compilation and the GCC version on your device. You need to compile the POCO library and libcossdk.a
again.
Getting Started
The section below describes how to use the COS C++ SDK to perform basic operations, such as initializing a client, creating a bucket, querying a bucket list, uploading an object, querying an object list, downloading an object, or deleting an object.
Note:
For the definitions of terms such as SecretId
, SecretKey
, and bucket, see Introduction. Initialization
Note:
We recommend you use a sub-account key and environment variables to call the SDK for security purposes. When authorizing a sub-account, follow the Notes on Principle of Least Privilege to avoid leaking resources besides your buckets and objects. Fields in the configuration file are as described below:
{
"SecretId":"********************************", // Replace the value with your `SecretId`, which can be viewed at https://console.tencentcloud.com/cam/capi.
"SecretKey":"*******************************", // Replace the value with your `SecretKey`, which can be viewed at https://console.tencentcloud.com/cam/capi.
"Region":"ap-guangzhou", // Bucket region. Replace it with your bucket region, which can be viewed on the overview page in the COS console at https://console.tencentcloud.com/cos5/bucket/. For more information on regions, visit https://www.tencentcloud.com/document/product/436/6224.
"SignExpiredTime":360, // Signature expiration time in seconds
"ConnectTimeoutInms":6000, // Connection timeout period in milliseconds
"ReceiveTimeoutInms":60000, // `Receive` timeout period in milliseconds
"UploadPartSize":10485760, // Size of the part to be uploaded, which can be 1 MB to 5 GB. Default value: 10 MB.
"UploadCopyPartSize":20971520, // Size of the copied part for upload, which can be 5 MB to 5 GB. Default value: 20 MB.
"UploadThreadPoolSize":5, // Size of the upload thread pool for a single multipart upload
"DownloadSliceSize":4194304, // Size of the part to be downloaded
"DownloadThreadPoolSize":5, // Size of the download thread pool for a single file
"AsynThreadPoolSize":2, // Size of the async thread pool for uploads/downloads
"LogoutType":1, // Log output type. Valid values: 0 (no output), 1 (output to screen), 2 (output to syslog).
"LogLevel":3, // Log level. Valid values: 1 (ERR), 2 (WARN), 3 (INFO), 4 (DBG).
"IsDomainSameToHost":false, // Whether to use a specific host
"DestDomain":"", // Specific host
"IsUseIntranet":false, // Whether to use a specific IP and port number
"IntranetAddr":"" // Specific IP and port number, such as `127.0.0.1:80`
}
Accessing COS with temporary key
To access COS with a temporary key, see the code below:
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
int main(int argc, char *argv[]) {
qcloud_cos::CosConfig config("./config.json");
config.SetTmpToken("xxx");
qcloud_cos::CosAPI cos(config);
}
Printing SDK internal logs to custom log file
To print SDK internal logs (especially for Windows) to a custom log file, see the code below:
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
void TestLogCallback(const std::string& log) {
std::ofstream ofs;
ofs.open("test.log", std::ios_base::app);
ofs << log;
ofs.close();
}
int main(int argc, char** argv) {
qcloud_cos::CosConfig config("./config.json");
config.SetLogCallback(&TestLogCallback);
qcloud_cos::CosAPI cos(config);
}
Creating bucket
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
int main(int argc, char *argv[]) {
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
qcloud_cos::PutBucketReq req(bucket_name);
qcloud_cos::PutBucketResp resp;
qcloud_cos::CosResult result = cos.PutBucket(req, &resp);
if (result.IsSucc()) {
} else {
std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
}
}
Querying bucket list
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
int main(int argc, char *argv[]) {
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
qcloud_cos::GetServiceReq req;
qcloud_cos::GetServiceResp resp;
qcloud_cos::CosResult result = cos.GetService(req, &resp);
const qcloud_cos::Owner& owner = resp.GetOwner();
const std::vector<qcloud_cos::Bucket>& buckets = resp.GetBuckets();
std::cout << "owner.m_id=" << owner.m_id << ", owner.display_name=" << owner.m_display_name << std::endl;
for (std::vector<qcloud_cos::Bucket>::const_iterator itr = buckets.begin(); itr != buckets.end(); ++itr) {
const qcloud_cos::Bucket& bucket = *itr;
std::cout << "Bucket name=" << bucket.m_name << ", location="
<< bucket.m_location << ", create_date=" << bucket.m_create_date << std::endl;
}
if (result.IsSucc()) {
} else {
std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
}
}
Uploading object
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
int main(int argc, char *argv[]) {
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "exampleobject";
qcloud_cos::PutObjectByFileReq req(bucket_name, object_name, "/path/to/local/file");
qcloud_cos::PutObjectByFileResp resp;
qcloud_cos::CosResult result = cos.PutObject(req, &resp);
if (result.IsSucc()) {
} else {
std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
}
}
Querying object list
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
int main(int argc, char *argv[]) {
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
qcloud_cos::GetBucketReq req(bucket_name);
qcloud_cos::GetBucketResp resp;
qcloud_cos::CosResult result = cos.GetBucket(req, &resp);
std::vector<qcloud_cos::Content> cotents = resp.GetContents();
for (std::vector<qcloud_cos::Content>::const_iterator itr = cotents.begin(); itr != cotents.end(); ++itr) {
const qcloud_cos::Content& content = *itr;
std::cout << "key name=" << content.m_key << ", lastmodified ="
<< content.m_last_modified << ", size=" << content.m_size << std::endl;
}
if (result.IsSucc()) {
} else {
std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
}
}
Downloading object
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
int main(int argc, char *argv[]) {
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "exampleobject";
std::string local_path = "/tmp/exampleobject";
qcloud_cos::GetObjectByFileReq req(bucket_name, object_name, local_path);
qcloud_cos::GetObjectByFileResp resp;
qcloud_cos::CosResult result = cos.GetObject(req, &resp);
if (result.IsSucc()) {
} else {
std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
}
}
Deleting object
#include "cos_api.h"
#include "cos_sys_config.h"
#include "cos_defines.h"
int main(int argc, char *argv[]) {
qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "exampleobject";
qcloud_cos::DeleteObjectReq req(bucket_name, object_name);
qcloud_cos::DeleteObjectResp resp;
qcloud_cos::CosResult result = cos.DeleteObject(req, &resp);
if (result.IsSucc()) {
} else {
std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
}
}
Was this page helpful?