Basic Use - AWS SDK for C++
Initializing and Shutting Down the SDKSetting SDK OptionsCredential provider chainDefault AWS Region

Basic Use

Initializing and Shutting Down the SDK

Applications that use the AWS SDK for C++ must initialize it. Similarly, before the application terminates, the SDK must be shut down. Both operations accept configuration options that affect the initialization and shutdown processes and subsequent calls to the SDK.

All applications that use the AWS SDK for C++ must include the file aws/core/Aws.h.

The AWS SDK for C++ must be initialized by calling Aws::InitAPI. Before the application terminates, the SDK must be shut down by calling Aws::ShutdownAPI. Each method accepts an argument of Aws::SDKOptions. All other calls to the SDK can be performed between these two method calls.

All AWS SDK for C++ calls performed between Aws::InitAPI and Aws::ShutdownAPI should either to be contained within a pair of curly braces or should be invoked by functions called between the two methods.

A basic skeleton application is shown below.

#include <aws/core/Aws.h>
int main(int argc, char** argv)
{
   Aws::SDKOptions options;
   Aws::InitAPI(options);
   {
      // make your SDK calls here.
   }
   Aws::ShutdownAPI(options);
   return 0;
}

The SDK for C++ and its dependencies use C++ static objects, and the order of static object destruction is not determined by the C++ standard. To avoid memory issues caused by the nondeterministic order of static variable destruction, do not wrap the calls to Aws::InitAPI and Aws::ShutdownAPI into another static object.

Setting SDK Options

The Aws::SDKOptions struct contains SDK configuration options.

An instance of Aws::SDKOptions is passed to the Aws::InitAPI and Aws::ShutdownAPI methods. The same instance should be sent to both methods.

The following samples demonstrate some of the available options.

  • Turn logging on using the default logger

    Aws::SDKOptions options;
options.loggingOptions.logLevel = Aws::Utils::Logging::LogLevel::Info;
Aws::InitAPI(options);
{
    // make your SDK calls here.
}
Aws::ShutdownAPI(options);

  • Override the default HTTP client factory

    Aws::SDKOptions options;
options.httpOptions.httpClientFactory_create_fn = [](){
        return Aws::MakeShared<MyCustomHttpClientFactory>(
            "ALLOC_TAG", arg1);
    };
Aws::InitAPI(options);
{
    // make your SDK calls here.
}
Aws::ShutdownAPI(options);
    Note

    httpOptions takes a closure (also called an anonymous function or lambda expression) rather than a std::shared_ptr. Each of the SDK factory functions operates in this manner because at the time at which the factory memory allocation occurs, the memory manager has not yet been installed. By passing a closure to the method, the memory manager will be called to perform the memory allocation when it is safe to do so. A simple technique to accomplish this procedure is by using a Lambda expression.

  • Use a global SIGPIPE handler

    If you build the SDK for C++ with curl and OpenSSL, you must specify a signal handler. If you don’t use your own custom signal handler, set installSigPipeHandler to true.

    Aws::SDKOptions options;
options.httpOptions.installSigPipeHandler = true; 
Aws::InitAPI(options);
{
    // make your SDK calls here.
}
Aws::ShutdownAPI(options);

    When installSigPipeHandler is true, the SDK for C++ uses a handler that ignores SIGPIPE signals. For more information on SIGPIPE, see Operation Error Signals on the GNU Operating System website. For more information on the curl handler, see CURLOPT_NOSIGNAL explained on the curl website.

    The underlying libraries of curl and OpenSSL can send a SIGPIPE signal to notify when the remote side closes a connection. These signals must be handled by the application. For more information this curl functionality, see libcurl thread safety on the curl website. This behavior is not automatically built-in to the SDK because signal handlers are global for each application and the library is a dependency for the SDK.

Credential provider chain

The AWS SDKs and CLIs use provider chains to look for AWS credentials in several different places, including system/user environment variables and local AWS configuration files. For details on the order of precedence, see Credentials Providers in the aws-sdk-cpp repository in GitHub. For configuration details about other AWS SDK for C++ credential providers, see Standardized credential providers in the AWS SDKs and Tools Reference Guide.

Default AWS Region

You must set a default AWS Region for the AWS SDK for C++ to use for AWS requests. This Region is used for SDK service requests that aren't specified with a Region. The AWS SDKs and Tools Reference Guide has additional information on the following: