DOCSEARCHbyAlgolia
Submit Docs

Alibaba Cloud Object Storage Service (OSS) C++ SDK

repository·master·Indexed 42 days ago

https://github.com/aliyun/aliyun-oss-cpp-sdk

A modern C++ (C++11 or later) interface for interacting with Alibaba Cloud Object Storage Service (OSS). It enables programmatic file management, data uploads, downloads, and secure operations via the OssClient. The SDK supports multiple platforms including Linux, Windows, macOS, and Android, and provides features for client-side encryption through the CryptoModule.

Tokens
3.9K
Snippets
14
Records
19
Agent score
53%

What's inside Alibaba Cloud OSS C++ SDK

  1. Upgrade to OSS SDK for C++ V2

    master

    OSS SDK for C++ V2 (alibabacloud-oss-cpp-sdk-v2) is a major rewrite of the V1 (aliyun-oss-cpp-sdk) codebase. V2 simplifies authentication, automatic request retries, and error handling. It also introduces advanced features like native asynchronous APIs, request cancellation, paginators, transfer managers, and pre-signed URLs.

    To start using V2, refer to the V2 Developer Guide. For upgrading from V1 to V2, refer to the Migration Guide.

  2. Build the SDK on Mac

    master

    On macOS, you must explicitly specify the OpenSSL path during the CMake configuration step. For example, if OpenSSL is installed via Homebrew at /usr/local/Cellar/openssl/1.0.2p:

    cmake -DOPENSSL_ROOT_DIR=/usr/local/Cellar/openssl/1.0.2p \
      -DOPENSSL_LIBRARIES=/usr/local/Cellar/openssl/1.0.2p/lib \
      -DOPENSSL_INCLUDE_DIRS=/usr/local/Cellar/openssl/1.0.2p/include ..
make
    cmake -DOPENSSL_ROOT_DIR=/usr/local/Cellar/openssl/1.0.2p  \
      -DOPENSSL_LIBRARIES=/usr/local/Cellar/openssl/1.0.2p/lib  \
      -DOPENSSL_INCLUDE_DIRS=/usr/local/Cellar/openssl/1.0.2p/include ..
make

  3. Build the SDK on Windows

    master

    After running cmake .. in the build directory, you can:

    1. Open alibabacloud-oss-cpp-sdk.sln in Visual Studio to generate the solution.
    2. Or use the Visual Studio Developer Command Prompt to compile and install:
    msbuild ALL_BUILD.vcxproj
msbuild INSTALL.vcxproj

  4. Build and install the Alibaba Cloud OSS C++ SDK

    master

    To build the SDK from source, you must first clone the repository and use CMake 3.1 or later to generate build files. The build process varies depending on your operating system.

    General Steps

    1. Clone the repository:
    git clone https://github.com/aliyun/aliyun-oss-cpp-sdk.git
    1. Create a build directory and run CMake:
    cd <path/to/aliyun-oss-cpp-sdk>
mkdir build
cd build
cmake ..
    git clone https://github.com/aliyun/aliyun-oss-cpp-sdk.git
cd aliyun-oss-cpp-sdk
mkdir build
cd build
cmake ..

  5. Build the SDK on Linux

    master

    Linux builds require libcurl and libopenssl. Install them via your package manager first:

    Redhat / Fedora:

    sudo dnf install libcurl-devel openssl-devel

    Debian / Ubuntu:

    sudo apt-get install libcurl4-openssl-dev libssl-dev

    After installing dependencies, compile and install the SDK:

    make
sudo make install
    sudo dnf install libcurl-devel openssl-devel
sudo apt-get install libcurl4-openssl-dev libssl-dev
make
sudo make install

  6. Prerequisites for using the OSS C++ SDK

    master

    Before using the SDK, ensure you have:

    1. Alibaba Cloud Account Credentials: An AccessKey. It is recommended to use a RAM account with limited permissions for better security.
    2. C++11 Compatible Compiler:
      • Visual Studio 2013 or higher
      • GCC 4.8 or higher
      • Clang 3.3 or higher

  7. Build the SDK for Android

    master

    To build for Android using the android-ndk-r16 toolchain in a Linux environment, ensure libcurl and libopenssl are compiled and installed to $ANDROID_NDK/sysroot. Use the following CMake command:

    cmake -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake  \
      -DANDROID_NDK=$ANDROID_NDK    \
      -DANDROID_ABI=armeabi-v7a     \
      -DANDROID_TOOLCHAIN=clang     \
      -DANDROID_PLATFORM=android-21 \
      -DANDROID_STL=c++_shared ..
make

  9. Use the OSS C++ SDK to list buckets

    master

    The following example demonstrates how to initialize the SDK, configure an OssClient, and list the buckets owned by the user.

    Note: Replace your-region-id, your-access-key-id, and your-access-key-secret with your actual credentials.

    #include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(int argc, char** argv)
{
    // Initialize SDK
    InitializeSdk();

    // Configure instance
    ClientConfiguration conf;
    OssClient client("your-region-id", "your-access-key-id", "your-access-key-secret", conf);

    // Create API request
    ListBucketsRequest request;
    auto outcome = client.ListBuckets(request);
    if (!outcome.isSuccess()) {
        // Error handling
        std::cout << "ListBuckets fail"
            << ",code:" << outcome.error().Code() <<
            ",message:" << outcome.error().Message() <<
            ",requestId:" << outcome.error().RequestId() << std::endl;
        ShutdownSdk();
        return -1;
    }

    // Shutdown SDK
    ShutdownSdk();
    return 0;
}

  10. List buckets using the OSS C++ SDK

    master

    To use the SDK, you must initialize it, configure an OssClient with your credentials, and then execute requests. Always remember to call ShutdownSdk() to clean up resources.

    Workflow:

    1. Call InitializeSdk().
    2. Create a ClientConfiguration object.
    3. Instantiate OssClient with region, access_key_id, access_key_secret, and the configuration.
    4. Create a request object (e.g., ListBucketsRequest).
    5. Execute the request via the client and check outcome.isSuccess().
    6. Call ShutdownSdk().
    #include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(int argc, char** argv)
{
    // Initialize the SDK
    InitializeSdk();

    // Configure the instance
    ClientConfiguration conf;
    OssClient client("your-region-id", "your-access-key-id", "your-access-key-secret", conf);

    // Create an API request
    ListBucketsRequest request;
    auto outcome = client.ListBuckets(request);
    if (!outcome.isSuccess()) {
        // Handle exceptions
        std::cout << "ListBuckets fail"
            << ",code:" << outcome.error().Code() <<
            ",message:" << outcome.error().Message() <<
            ",requestId:" << outcome.error().RequestId() << std::endl;
        ShutdownSdk();
        return -1;
    }

    // Close the SDK
    ShutdownSdk();
    return 0;
}

  11. Configure SDK build with CMake options

    master

    You can customize the SDK build using the following CMake flags:

    OptionDefaultDescription
    BUILD_SHARED_LIBSOFFIf ON, builds both static and shared libraries. Static library name gets a -static suffix.
    BUILD_TESTSOFFIf ON, builds test and ptest projects.
    ENABLE_RTTIONIf OFF, builds without RTTI information.
    OSS_DISABLE_BUCKETOFFIf ON, builds without the bucket's API.
    OSS_DISABLE_LIVECHANNELOFFIf ON, builds without the livechannel's API.
    OSS_DISABLE_RESUAMABLEOFFIf ON, builds without the resumable operation feature.
    OSS_DISABLE_ENCRYPTIONOFFIf ON, builds without the client-side encryption feature.
    # Example: Build with shared libraries and no RTTI
cmake .. -DBUILD_SHARED_LIBS=ON -DENABLE_RTTI=OFF

  12. Configure CMake build options

    master

    Use the following CMake flags to customize the SDK build:

    OptionDefaultDescription
    BUILD_SHARED_LIBSOFFIf ON, builds both static and dynamic libraries. Static libraries will have a -static suffix.
    BUILD_TESTSOFFIf ON, builds test and ptest projects.
    ENABLE_RTTIONIf OFF, the library will not include Run-Time Type Information.
    OSS_DISABLE_BUCKETOFFIf ON, the library will not include Bucket-related interfaces.
    OSS_DISABLE_LIVECHANNELOFFIf ON, the library will not include LiveChannel-related interfaces.
    OSS_DISABLE_RESUAMABLEOFFIf ON, disables breakpoint resumable upload/download functionality.
    OSS_DISABLE_ENCRYPTIONOFFIf ON, disables client-side encryption features.
    # Example: Build with shared libraries and tests enabled
cmake .. -DBUILD_SHARED_LIBS=ON -DBUILD_TESTS=ON