Skip to content

Commit 8117dc9

Browse files
KaibaLopezKaibaLopez
authoredJul 15, 2020
divided the Readme into different docs (aws#633)
* Divided the Readme into different docs to reduce its size and make it more readable for new comers. Also, updated information on credentials providers and Changelogs.
1 parent 3bac022 commit 8117dc9

14 files changed

+783
-642
lines changed
 

‎.github/ISSUE_TEMPLATE/---bug-report.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
name: "\U0001F41B Bug report"
33
about: Create a report to help us improve
44
title: ''
5-
labels: bug report, needs-triage
5+
labels: bug§, needs-triage
66
assignees: ''
77

88
---

‎CHANGELOG.md

+13-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,18 @@
11
# Breaking changes in AWS SDK for C++
22

3+
## [1.8.0](https://github.com/aws/aws-sdk-cpp/tree/1.8.0) (2020-06-30)
4+
Check our [Wiki](https://github.com/aws/aws-sdk-cpp/wiki/What%E2%80%99s-New-in-AWS-SDK-for-C---Version-1.8) for a comprehensive list of the featuers introduced on this version.
5+
6+
## [1.7.0](https://github.com/aws/aws-sdk-cpp/tree/1.7.0) (2018-11-15)
7+
8+
### aws-cpp-sdk-core
9+
Add new dependencies: [aws-c-common](https://github.com/awslabs/aws-c-common), [aws-checksums](https://github.com/awslabs/aws-checksums) and [aws-c-event-stream](https://github.com/awslabs/aws-c-event-stream) to support S3 select streaming API. The API is implemented in C99 via libraries that are developed by AWS as well.
10+
11+
These libraries are downloaded and built as part of the CMake configure step. That can be disabled via the new switch `-DBUILD_DEPS=OFF`. The switch is set to ON by default.
12+
13+
### aws-cpp-sdk-s3
14+
Add support for S3 `SelectContentObject` API.
15+
316
## [1.6.0](https://github.com/aws/aws-sdk-cpp/tree/1.6.0) (2018-08-28)
417

518
### aws-cpp-sdk-core
@@ -34,8 +47,6 @@ From the service release notes:
3447
> AWS Config updated the ConfigurationItemStatus enum values. The values prior to this update did not represent appropriate values returned by GetResourceConfigHistory. You must update your code to enumerate the new enum values so this is a breaking change. To map old properties to new properties, use the following descriptions: New discovered resource - Old property: Discovered, New property: ResourceDiscovered. Updated resource - Old property: Ok, New property: OK. Deleted resource - Old property: Deleted, New property: ResourceDeleted or ResourceDeletedNotRecorded. Not-recorded resource - Old property: N/A, New property: ResourceNotRecorded or ResourceDeletedNotRecorded.
3548
3649

37-
38-
3950
## [1.3.0](https://github.com/aws/aws-sdk-cpp/tree/1.3.0) (2017-11-09)
4051

4152
### aws-cpp-sdk-s3

‎CODE_OF_CONDUCT.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
## Code of Conduct
2+
This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
3+
For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
4+
opensource-codeofconduct@amazon.com with any additional questions or comments.

‎CONTRIBUTING.md

+100
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
## Contributing Back
2+
**Please Do!**
3+
4+
__Jump To:__
5+
* [Bug Reports](#bug-reports)
6+
* [Feature Requests](#feature-requests)
7+
* [Code Contributions](#code-contributions)
8+
* [Contribution Guidelines](#Contribution-Guidelines)
9+
10+
## Bug Reports
11+
Bug reports are accepted through the [Issues][issues] page.
12+
13+
### Before Submitting a Bug Report
14+
15+
Before submitting a bug report, please do the following:
16+
17+
1. Do a search through the existing issues to make sure it has not already been reported. If there's an existing one, be sure give a +1 reaction which will help us prioritize which issues to address first.
18+
19+
2. If possible, upgrade to the latest release of the SDK. The SDK has a near daily release cadence so it's possible the bug has already been fixed in the latest version.
20+
21+
If, after doing the above steps, you determine that you need to submit a bug report, refer to the next section.
22+
23+
### Submitting a Bug Report
24+
So that we are able to assist you as effectively as possible with the issue, please ensure that your bug report has the following:
25+
26+
* A short, descriptive title. Ideally, other community members should be able to get a good idea of the issue just from reading the title.
27+
* A succint, detailed description of the problem you're experiencing. This should include:
28+
* Expected behavior of the SDK and the actual behavior exhibited.
29+
* Any details of your application environment that may be relevant. At minimum, this should include the __SDK version__ and __Operating System__ you're using.
30+
* If applicable, the exception stacktrace.
31+
* If you are able to create one, include a [Minimal Working Example][mwe] that reproduces the issue.
32+
* [Markdown][markdown] formatting as appropriate to make the report easier to read; for example use code blocks when pasting a code snippet and exception stacktraces.
33+
34+
## Feature Requests
35+
Like bug reports, feature requests are submitted through the [Issues][issues] page.
36+
37+
As with Bug Reports, please do a search of the open requests first before submitting a new one to avoid duplicates. If you find an existing one, give it a +1.
38+
39+
__NOTE:__ If this is a feature you intend to implement, please submit the feature request *before* working on any code changes. This will allow members on the SDK team to have a discussion with you to ensure that it's the right design and that it makes sense to include in the SDK. Keep in mind that other concerns like source and binary compatibility will also play a deciding factor.
40+
41+
### Submitting a Feature Request
42+
Open an [issue][issues] with the following:
43+
44+
* A short, descriptive title. s should be able to get a good idea of the feature just from reading the title.Ideally, other community member
45+
* A detailed description of the the proposed feature. Include justification for why it should be added to the SDK, and possibly example code to illustrate how it should work.
46+
* [Markdown][markdown] formatting as appropriate to make the request easier to read.
47+
* If you intend to implement this feature, indicate that you'd like to the issue to be assigned to you
48+
49+
50+
## Code Contributions
51+
Code contributions to the SDK are done through [Pull Requests][pull-requests]. Please keep the following in mind when considering a code contribution:
52+
53+
* The SDK is released under the [Apache 2.0 License][license].
54+
55+
Any code you submit will be released under this license. If you are contributing a large/substantial feature, you may be asked to sign a Contributor License Agreement (CLA).
56+
* For anything but very small or quick changes, you should always start by checking the [Issues][issues] page to see if the work is already being done by another person.
57+
58+
If you're working on a bug fix, check to see if the bug has already been reported. If it has but no one is assigned to it, ask one of the maintainers to assign it to you before beginning work. If you're confident the bug hasn't been reported yet, create a new [Bug Report](#bug-reports) then ask to be assigned to it.
59+
60+
If you are thinking about adding entirely new functionality, open a [Feature Request](#feature-requests) first before beginning work; again this is to make sure that no one else is already working on it, and also that it makes sense to be included in the SDK.
61+
* All code contributions must be accompanied with new or modified tests that verify that the code works as expected; i.e. that the issue has been fixed or that the functionality works as intended.
62+
63+
## Your First Code Change
64+
Before submitting your pull request, refer to the pull request readiness
65+
checklist below:
66+
67+
* [ ] Includes tests to exercise the new behavior
68+
* [ ] Code is documented, especially public and user-facing constructs
69+
* [ ] Git commit message is detailed and includes context behind the change
70+
* [ ] If the change is related to an existing Bug Report or Feature Request, the issue number is referenced
71+
72+
__Note__: Some changes have additional requirements. Refer to the section below
73+
to see if your change will require additional work to be accepted.
74+
75+
All Pull Requests must be approved by at least one member of the SDK team before it can be merged in. The members only have limited bandwitdth to review Pull Requests so it's not unusual for a Pull Request to go unreviewed for a few days, especially if it's a large or complex one. If, after a week, your Pull Request has not had any engagement from the SDK team, feel free to comment and tag a member to ask for a review.
76+
77+
If your branch has more than one commit when it's approved, you will also be asked to squash them into a single commit before it is merged in.
78+
79+
## Contribution Guidelines
80+
* Don't make changes to generated clients directly, make your changes in the generator. Changes to Core, Scripts, and High-Level interfaces are fine directly in the code.
81+
* Do not use non-trivial statics anywhere. This will cause custom memory managers to crash in random places.
82+
* Use 4 spaces for indents and never use tabs.
83+
* No exceptions.... no exceptions. Use the Outcome pattern for returning data if you need to also return an optional error code.
84+
* Always think about platform independence. If this is impossible, put a nice abstraction on top of it and use an abstract factory.
85+
* Use RAII, Aws::New and Aws::Delete should only appear in constructors and destructors.
86+
* Be sure to follow the rule of 5.
87+
* Use the C++ 11 standard where possible.
88+
* Use UpperCamelCase for custom type names and function names. Use m_* for member variables. Don't use statics. If you must, use UpperCammelCase for static variables
89+
* Always be const correct, and be mindful of when you need to support r-values. We don't trust compilers to optimize this uniformly accross builds so please be explicit.
90+
* Namespace names should be UpperCammelCase. Never put a using namespace statement in a header file unless it is scoped by a class. It is fine to use a using namespace statement in a cpp file.
91+
* Use enum class, not enum
92+
* Prefer `#pragma once` for include guards.
93+
* Forward declare whenever possible.
94+
* Use nullptr instead of NULL.
95+
96+
[license]: ./LICENSE.txt
97+
[mwe]: https://en.wikipedia.org/wiki/Minimal_Working_Example
98+
[markdown]: https://guides.github.com/features/mastering-markdown/
99+
[issues]: https://github.com/aws/aws-sdk-cpp/issues
100+
[pull-requests]: https://github.com/aws/aws-sdk-cpp/pulls

‎Docs/Advanced_topics.md

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Advance Topics and tips
2+
3+
__This section includes the following topics:__
4+
* [Uninstalling (auto build only)](#Uninstalling)
5+
* [Overriding Your HTTP Client](#Overriding-your-Http-Client)
6+
* [Error Handling](#Error-Handling)
7+
* [Provided Utilities](#provided-utilities)
8+
* [Controlling IOStreams used by the HttpClient and the AWSClient](#Controlling-IOStreams-used-by-the-HttpClient-and-the-AWSClient)
9+
10+
11+
12+
### Uninstalling:
13+
To uninstall these libraries:
14+
```sh
15+
sudo make uninstall
16+
```
17+
You may define a custom uninstall target when you are using SDK as a sub-project, but make sure it comes before the default definition in `CMakeLists.txt`, and you can uninstall SDK related libraries by:
18+
```sh
19+
sudo make uninstall-awssdk
20+
```
21+
22+
### Overriding your Http Client
23+
The default HTTP client for Windows is WinHTTP. The default HTTP client for all other platforms is Curl. If needed, you can create a custom HttpClientFactory, add it to the SDKOptions object which you pass to Aws::InitAPI().
24+
25+
### Error Handling
26+
We do not use exceptions; however, you can use exceptions in your code. Every service client returns an outcome object that includes the result and an error code.
27+
28+
Example of handling error conditions:
29+
30+
```cpp
31+
bool CreateTableAndWaitForItToBeActive()
32+
{
33+
CreateTableRequest createTableRequest;
34+
AttributeDefinition hashKey;
35+
hashKey.SetAttributeName(HASH_KEY_NAME);
36+
hashKey.SetAttributeType(ScalarAttributeType::S);
37+
createTableRequest.AddAttributeDefinitions(hashKey);
38+
KeySchemaElement hashKeySchemaElement;
39+
hashKeySchemaElement.WithAttributeName(HASH_KEY_NAME).WithKeyType(KeyType::HASH);
40+
createTableRequest.AddKeySchema(hashKeySchemaElement);
41+
ProvisionedThroughput provisionedThroughput;
42+
provisionedThroughput.SetReadCapacityUnits(readCap);
43+
provisionedThroughput.SetWriteCapacityUnits(writeCap);
44+
createTableRequest.WithProvisionedThroughput(provisionedThroughput);
45+
createTableRequest.WithTableName(tableName);
46+
47+
CreateTableOutcome createTableOutcome = dynamoDbClient->CreateTable(createTableRequest);
48+
if (createTableOutcome.IsSuccess())
49+
{
50+
DescribeTableRequest describeTableRequest;
51+
describeTableRequest.SetTableName(tableName);
52+
bool shouldContinue = true;
53+
DescribeTableOutcome outcome = dynamoDbClient->DescribeTable(describeTableRequest);
54+
55+
while (shouldContinue)
56+
{
57+
if (outcome.GetResult().GetTable().GetTableStatus() == TableStatus::ACTIVE)
58+
{
59+
break;
60+
}
61+
else
62+
{
63+
std::this_thread::sleep_for(std::chrono::seconds(1));
64+
}
65+
}
66+
return true
67+
}
68+
else if(createTableOutcome.GetError().GetErrorType() == DynamoDBErrors::RESOURCE_IN_USE)
69+
{
70+
return true;
71+
}
72+
73+
return false;
74+
}
75+
```
76+
77+
### Provided Utilities
78+
The provided utilities include HTTP stack, string utils, hashing utils, JSON parser, and XML parser.
79+
80+
##### HTTP Stack
81+
/aws/core/http/
82+
83+
The HTTP client provides connection pooling, is thread safe, and can be reused for your purposes. See the Client Configuration section above.
84+
85+
##### String Utils
86+
/aws/core/utils/StringUtils.h
87+
88+
This header file provides core string functions, such as trim, lowercase, and numeric conversions.
89+
90+
##### Hashing Utils
91+
/aws/core/utils/HashingUtils.h
92+
93+
This header file provides hashing functions, such as SHA256, MD5, Base64, and SHA256_HMAC.
94+
95+
##### Cryptography
96+
/aws/core/utils/crypto/Cipher.h
97+
/aws/core/utils/crypto/Factories.h
98+
99+
This header file provides access to secure random number generators, AES symmetric ciphers in CBC, CTR, and GCM modes, and the underlying Hash implementations that are used in HashingUtils.
100+
101+
##### JSON Parser
102+
/aws/core/utils/json/JsonSerializer.h
103+
104+
This header file provides a fully functioning yet lightweight JSON parser (thin wrapper around JsonCpp).
105+
106+
##### XML Parser
107+
/aws/core/utils/xml/XmlSerializer.h
108+
109+
This header file provides a lightweight XML parser (thin wrapper around tinyxml2). RAII pattern has been added to the interface.
110+
111+
### Controlling IOStreams used by the HttpClient and the AWSClient
112+
By default all responses use an input stream backed by a stringbuf. If needed, you can override the default behavior. For example, if you are using Amazon S3 GetObject and do not want to load the entire file into memory, you can use IOStreamFactory in AmazonWebServiceRequest to pass a lambda to create a file stream.
113+
114+
Example file stream request:
115+
116+
```cpp
117+
GetObjectRequest getObjectRequest;
118+
getObjectRequest.SetBucket(fullBucketName);
119+
getObjectRequest.SetKey(keyName);
120+
getObjectRequest.SetResponseStreamFactory([](){ return Aws::New<Aws::FStream>( ALLOCATION_TAG, DOWNLOADED_FILENAME, std::ios_base::out ); });
121+
122+
auto getObjectOutcome = s3Client->GetObject(getObjectRequest);
123+
```

‎Docs/CMake_Parameters.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# CMake Parameters
2+
3+
## General CMake Variables/Options
4+
CMake options are variables that can either be ON or OFF, with a controllable default. You can set an option either with CMake Gui tools or the command line via -D.
5+
6+
### BUILD_ONLY
7+
Allows you to only build the clients you want to use. This will resolve low level client dependencies if you set this to a high-level sdk such as aws-cpp-sdk-transfer. This will also build integration and unit tests related to the projects you select if they exist. aws-cpp-sdk-core always builds regardless of the value of this argument. This is a list argument.
8+
Example:
9+
```sh
10+
-DBUILD_ONLY="s3;dynamodb;cognito-identity"
11+
```
12+
13+
### ADD_CUSTOM_CLIENTS
14+
Allows you to build any arbitrary clients based on the api definition. Simply place your definition in the code-generation/api-definitions folder. Then pass this arg to cmake. The cmake configure step will generate your client and include it as a subdirectory in your build. This is particularly useful if you want to generate a C++ client for using one of your API Gateway services. To use this feature you need to have python 2.7, java, jdk1.8, and maven installed and in your executable path. Example:
15+
```sh
16+
-DADD_CUSTOM_CLIENTS="serviceName=myCustomService, version=2015-12-21;serviceName=someOtherService, version=2015-08-15"
17+
```
18+
19+
### REGENERATE_CLIENTS
20+
This argument will wipe out all generated code and generate the client directories from the code-generation/api-definitions folder. To use this argument, you need to have python 2.7, java, jdk1.8, and maven installed in your executable path. Example:
21+
```sh
22+
-DREGENERATE_CLIENTS=1
23+
```
24+
25+
### CUSTOM_MEMORY_MANAGEMENT
26+
To use a custom memory manager, set the value to ON. You can install a custom allocator, and all STL types will use the custom allocation interface. If the value is set to OFF, you still might want to use the STL template types to help with DLL safety on Windows.
27+
28+
If static linking is enabled, custom memory management defaults to off. If dynamic linking is enabled, custom memory management defaults to on and avoids cross-DLL allocation and deallocation.
29+
30+
Note: To prevent linker mismatch errors, you must use the same value (ON or OFF) throughout your build system.
31+
32+
### TARGET_ARCH
33+
To cross compile or build for a mobile platform, you must specify the target platform. By default the build detects the host operating system and builds for that operating system.
34+
Options: `WINDOWS | LINUX | APPLE | ANDROID`
35+
36+
### G
37+
Use this variable to generate build artifacts, such as Visual Studio solutions and Xcode projects.
38+
39+
Windows example:
40+
```sh
41+
-G "Visual Studio 12 Win64"
42+
```
43+
44+
For more information, see the CMake documentation for your platform.
45+
46+
### ENABLE_UNITY_BUILD
47+
(Defaults to OFF) If enabled, most SDK libraries will be built as a single, generated .cpp file. This can significantly reduce static library size as well as speed up compilation time.
48+
49+
### MINIMIZE_SIZE
50+
(Defaults to OFF) A superset of ENABLE_UNITY_BUILD, if enabled this option turns on ENABLE_UNITY_BUILD as well as some additional binary size reduction settings. This is a work-in-progress and may change in the future (symbol stripping in particular).
51+
52+
### BUILD_SHARED_LIBS
53+
(Defaults to ON) A built-in CMake option, reexposed here for visibility. If enabled, shared libraries will be built, otherwise static libraries will be built.
54+
55+
### FORCE_SHARED_CRT
56+
(Defaults to ON) If enabled, the SDK will link to the C runtime dynamically, otherwise it will use the BUILD_SHARED_LIBS setting (weird but necessary for backwards compatibility with older versions of the SDK)
57+
58+
### SIMPLE_INSTALL
59+
(Defaults to ON) If enabled, the install process will not insert platform-specific intermediate directories underneath bin/ and lib/. Turn OFF if you need to make multi-platform releases under a single install directory.
60+
61+
### NO_HTTP_CLIENT
62+
(Defaults to OFF) If enabled, prevents the default platform-specific http client from being built into the library. Turn this ON if you wish to inject your own http client implementation.
63+
64+
### NO_ENCRYPTION
65+
(Defaults to OFF) If enabled, prevents the default platform-specific cryptography implementation from being built into the library. Turn this ON if you wish to inject your own cryptography implementation.
66+
67+
### ENABLE_RTTI
68+
(Defaults to ON) Controls whether or not the SDK is built with RTTI information
69+
70+
### CPP_STANDARD
71+
(Defaults to 11) Allows you to specify a custom c++ standard for use with C++ 14 and 17 code-bases
72+
73+
### ENABLE_TESTING
74+
(Defaults to ON) Controls whether or not the unit and integration test projects are built
75+
76+
### ENABLE_VIRTUAL_OPERATIONS
77+
(Defaults to ON) This option usually works with REGENERATE_CLIENTS.
78+
If enabled when doing code generation (REGENERATE_CLIENTS=ON), operation related functions in service clients will be marked as `virtual`.
79+
80+
If disabled when doing code generation (REGENERATE_CLIENTS=ON), `virtual` will not be added to operation functions and service client classes will be marked as final.
81+
82+
If disabled, SDK will also add compiler flags `-ffunction-sections -fdata-sections` for gcc and clang when compiling.
83+
84+
You can utilize this feature to work with your linker to reduce binary size of your application on Unix platforms when doing static linking in Release mode.
85+
86+
For example, if your system uses `ld` as linker, then you can turn this option OFF when building SDK, and specify linker flag `--gc-sections` (or `-dead_strip` on Mac) in your own build scripts.
87+
88+
You can also tell gcc or clang to pass these linker flags by specifying `-Wl,--gc-sections`, or `-Wl,-dead_strip`. Or via `-DCMAKE_CXX_FLAGS="-Wl,[flag]"` if you use CMake.
89+
90+
## Android CMake Variables/Options
91+
92+
### NDK_DIR
93+
An override path for where the build system should find the Android NDK. By default, the build system will check environment variables (ANDROID_NDK) if this CMake variable is not set.
94+
95+
### ANDROID_STL
96+
(Defaults to libc++\_shared) Controls what flavor of the C++ standard library the SDK will use. Valid values are one of {libc++\_shared, libc++\_static, gnustl_shared, gnustl_static}. There are severe performance problems within the SDK if gnustl is used and gnustl was deprecated starting from Android NDK 18, so we recommend libc++.
97+
98+
### ANDROID_ABI
99+
(Defaults to armeabi-v7a) Controls what abi to output code for. Not all valid Android ABI values are currently supported, but we intend to provide full coverage in the future. We welcome patches to our Openssl build wrapper that speed this process up. Valid values are one of {arm64, armeabi-v7a, x86_64, x86, mips64, mips}.
100+
101+
### ANDROID_TOOLCHAIN
102+
(Defaults to clang) Controls which compiler is used to build the SDK. With GCC being deprecated by Android NDK, we recommend using the default (clang).
103+
104+
### ANDROID_NATIVE_API_LEVEL
105+
(Default varies by STL choice) Controls what API level the SDK will be built against. If you use gnustl, you have complete freedom with the choice of API level. If you use libc++, you must use an API level of at least 21.

‎Docs/CODING_STANDARDS.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# CODING STANDARDS
2+
* Don't make changes to generated clients directly. Make your changes in the generator. Changes to Core, Scripts, and High-Level interfaces are fine directly in the code.
3+
* Do not use non-trivial statics anywhere. This will cause custom memory managers to crash in random places.
4+
* Use 4 spaces for indents and never use tabs.
5+
* No exceptions.... no exceptions. Use the Outcome pattern for returning data if you need to also return an optional error code.
6+
* Always think about platform independence. If this is impossible, put a nice abstraction on top of it and use an abstract factory.
7+
* Use RAII, Aws::New and Aws::Delete should only appear in constructors and destructors.
8+
* Be sure to follow the rule of 5.
9+
* Use the C++ 11 standard where possible.
10+
* Use UpperCamelCase for custom type names and function names. Use m_* for member variables. Don't use statics. If you must, use UpperCammelCase for static variables
11+
* Always be const correct, and be mindful of when you need to support r-values. We don't trust compilers to optimize this uniformly accross builds so please be explicit.
12+
* Namespace names should be UpperCammelCase. Never put a using namespace statement in a header file unless it is scoped by a class. It is fine to use a using namespace statement in a cpp file.
13+
* Use enum class, not enum
14+
* Prefer #pragma once for include guards.
15+
* Forward declare whenever possible.
16+
* Use nullptr instead of NULL.

‎Docs/ClientConfiguration_Parameters.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Client Configuration
2+
You can use the client configuration to control most functionality in the AWS SDK for C++.
3+
4+
ClientConfiguration declaration:
5+
6+
```cpp
7+
struct AWS_CORE_API ClientConfiguration
8+
{
9+
ClientConfiguration();
10+
11+
Aws::String userAgent;
12+
Aws::Http::Scheme scheme;
13+
Aws::Region region;
14+
bool useDualStack;
15+
unsigned maxConnections;
16+
long requestTimeoutMs;
17+
long connectTimeoutMs;
18+
std::shared_ptr<RetryStrategy> retryStrategy;
19+
Aws::String endpointOverride;
20+
Aws::Http::Scheme proxyScheme;
21+
Aws::String proxyHost;
22+
unsigned proxyPort;
23+
Aws::String proxyUserName;
24+
Aws::String proxyPassword;
25+
std::shared_ptr<Aws::Utils::Threading::Executor> executor;
26+
bool verifySSL;
27+
Aws::String caPath;
28+
std::shared_ptr<Aws::Utils::RateLimits::RateLimiterInterface> writeRateLimiter;
29+
std::shared_ptr<Aws::Utils::RateLimits::RateLimiterInterface> readRateLimiter;
30+
};
31+
```
32+
33+
### User Agent
34+
The user agent is built in the constructor and pulls information from your operating system. Do not alter the user agent.
35+
36+
### Scheme
37+
The default value for scheme is HTTPS. You can set this value to HTTP if the information you are passing is not sensitive and the service to which you want to connect supports an HTTP endpoint. AWS Auth protects you from tampering.
38+
39+
### Region
40+
The region specifies where you want the client to communicate. Examples include us-east-1 or us-west-1. You must ensure the service you want to use has an endpoint in the region you configure.
41+
42+
### UseDualStack
43+
Sets the endpoint calculation to go to a dual stack (ipv6 enabled) endpoint. It is your responsibility to check that the service actually supports ipv6 in the region you specify.
44+
45+
### Max Connections
46+
The default value for the maximum number of allowed connections to a single server for your HTTP communications is 25. You can set this value as high as you can support the bandwidth. We recommend a value around 25.
47+
48+
### Request Timeout and Connection Timeout
49+
This value determines the length of time, in milliseconds, to wait before timing out a request. You can increase this value if you need to transfer large files, such as in Amazon S3 or CloudFront.
50+
51+
### Retry Strategy
52+
The retry strategy defaults to exponential backoff. You can override this default by implementing a subclass of RetryStrategy and passing an instance.
53+
54+
### Endpoint Override
55+
Do not alter the endpoint.
56+
57+
### Proxy Scheme, Host, Port, User Name, and Password
58+
These settings allow you to configure a proxy for all communication with AWS. Examples of when this functionality might be useful include debugging in conjunction with the Burp suite, or using a proxy to connect to the internet.
59+
60+
### Executor
61+
The default behavior for the executor is to create and detach a thread for each async call. You can change this behavior by implementing a subclass of Executor and passing an instance. We now provide a thread pooled executor as an option. For more information see this blog post: https://aws.amazon.com/blogs/developer/using-a-thread-pool-with-the-aws-sdk-for-c/
62+
63+
### Verify SSL
64+
If necessary, you can disable SSL certificate verification by setting the verify SSL value to false.
65+
66+
### CA Path
67+
You can tell the http client where to find your certificate trust store ( e.g. a directory prepared with OpenSSL c_rehash utility). This should not be necessary unless you are doing some weird symlink farm stuff for your environment. This has no effect on Windows or OSX.
68+
69+
### Write Rate Limiter and Read Rate Limiter
70+
The write and read rate limiters are used to throttle the bandwidth used by the transport layer. The default for these limiters is open. You can use the default implementation with your desired rates, or you can create your own instance by implementing a subclass of RateLimiterInterface.

‎Docs/Credentials_Providers.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Credentials Providers
2+
You can use the AWSCredentialProvider interface to provide login credentials to AWS Auth. Implement this interface to provide your own method of credentials deployment. We also provide default credential providers.
3+
4+
## Default Credential Provider Chain
5+
The default credential provider chain does the following:
6+
1. Checks your environment variables for AWS Credentials
7+
2. Checks your $HOME/.aws/credentials file for a profile and credentials
8+
3. Contacts and logs in to a trusted identity provider (Cognito, Login with Amazon, Facebook, Google). The sdk looks for the login information to these providers either on the enviroment variables: AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE, AWS_ROLE_SESSION_NAME. Or on a profile in your $HOME/.aws/credentials.
9+
4. Checks for an external method set as part of a profile on $HOME/.aws/config to generate or look up credentials that isn't directly supported by AWS.
10+
5. Contacts the ECS TaskRoleCredentialsProvider service to request credentials if Environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI has been set.
11+
6. Contacts the EC2MetadataInstanceProfileCredentialsProvider service to request credentials if AWS_EC2_METADATA_DISABLED is NOT set to ON.
12+
13+
The simplest way to communicate with AWS is to ensure we can find your credentials in one of these locations.
14+
15+
## Other Methods
16+
We also support two other methods for providing credentials:
17+
* Provide your credentials in your client’s constructor.
18+
* Use Amazon Cognito Identity, which is an identity management solution. You can use the CognitoCaching*CredentialsProviders classes in the identity-management project. For more information, see the *Amazon Cognito Developer Guide*.

‎Docs/Memory_Management.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Memory Management
2+
The AWS SDK for C++ provides a way to control memory allocation and deallocation in a library.
3+
4+
Custom memory management is available only if you use a version of the library built using the compile-time constant AWS_CUSTOM_MEMORY_MANAGEMENT defined.
5+
6+
If you use a version of the library built without the compile-time constant, the global memory system functions such as InitializeAWSMemorySystem will not work and the global new and delete functions will be used instead.
7+
8+
For more information about the compile-time constant, see the STL and AWS Strings and Vectors section in this Readme.
9+
10+
To allocate or deallocate memory:
11+
1. Implement the MemorySystemInterface subclass:
12+
aws/core/utils/memory/MemorySystemInterface.h
13+
14+
In the following example, the type signature for AllocateMemory can be changed as needed:
15+
16+
```cpp
17+
class MyMemoryManager : public Aws::Utils::Memory::MemorySystemInterface
18+
{
19+
public:
20+
21+
// ...
22+
23+
virtual void* AllocateMemory(std::size_t blockSize, std::size_t alignment, const char *allocationTag = nullptr) override;
24+
virtual void FreeMemory(void* memoryPtr) override;
25+
26+
};
27+
```
28+
29+
In Main:
30+
31+
```cpp
32+
int main(void)
33+
{
34+
MyMemoryManager sdkMemoryManager;
35+
SDKOptions options;
36+
options.memoryManagementOptions.memoryManager = &sdkMemoryManager;
37+
Aws::InitAPI(options);
38+
39+
// ... do stuff
40+
41+
Aws::ShutdownAPI(options);
42+
43+
return 0;
44+
}
45+
```
46+
## STL and AWS Strings and Vectors
47+
When initialized with a memory manager, the AWS SDK for C++ defers all allocation and deallocation to the memory manager. If a memory manager does not exist, the SDK uses global new and delete.
48+
49+
If you use custom STL allocators, you must alter the type signatures for all STL objects to match the allocation policy. Because STL is used prominently in the SDK implementation and interface, a single approach in the SDK would inhibit direct passing of default STL objects into the SDK or control of STL allocation. Alternately, a hybrid approach – using custom allocators internally and allowing standard and custom STL objects on the interface – could potentially cause more difficulty when investigating memory issues.
50+
51+
The solution is to use the memory system’s compile-time constant AWS_CUSTOM_MEMORY_MANAGEMENT to control which STL types the SDK will use.
52+
53+
If the compile-time constant is enabled (on), the types resolve to STL types with a custom allocator connected to the AWS memory system.
54+
55+
If the compile-time constant is disabled (off), all Aws::* types resolve to the corresponding default std::* type.
56+
57+
Example code from the AWSAllocator.h file in the SDK:
58+
59+
```cpp
60+
#ifdef AWS_CUSTOM_MEMORY_MANAGEMENT
61+
62+
template< typename T >
63+
class AwsAllocator : public std::allocator< T >
64+
{
65+
... definition of allocator that uses AWS memory system
66+
};
67+
68+
#else
69+
70+
template< typename T > using Allocator = std::allocator<T>;
71+
72+
#endif
73+
```
74+
75+
In the example code, the AwsAllocator can be either a custom allocator or a default allocator, depending on the compile-time constant.
76+
77+
Example code from the AWSVector.h file in the SDK:
78+
`template< typename T > using Vector = std::vector< T, Aws::Allocator< T > >;`
79+
80+
In the example code, we define the Aws::* types.
81+
82+
If the compile-time constant is enabled (on), the type maps to a vector using custom memory allocation and the AWS memory system.
83+
84+
If the compile-time constant is disabled (off), the type maps to a regular std::vector with default type parameters.
85+
86+
Type aliasing is used for all std:: types in the SDK that perform memory allocation, such as containers, string stream, and string buf. The AWS SDK for C++ uses these types.
87+
88+
## Native SDK Developers and Memory Controls
89+
Follow these rules in the SDK code:
90+
* Do not use new and delete; use Aws::New<> and Aws::Delete<>.
91+
* Do not use new[] and delete []; use Aws::NewArray<> and Aws::DeleteArray<>.
92+
* Do not use std::make_shared; use Aws::MakeShared.
93+
* Use Aws::UniquePtr for unique pointers to a single object. Use the Aws::MakeUnique function to create the unique pointer.
94+
* Use Aws::UniqueArray for unique pointers to an array of objects. Use the Aws::MakeUniqueArray function to create the unique pointer.
95+
* Do not directly use STL containers; use one of the Aws::typedefs or add a typedef for the desired container. Example: `Aws::Map<Aws::String, Aws::String> m_kvPairs;`
96+
* Use shared_ptr for any external pointer passed into and managed by the SDK. You must initialize the shared pointer with a destruction policy that matches how the object was allocated. You can use a raw pointer if the SDK is not expected to clean up the pointer.
97+
98+
## Remaining Issues
99+
You can control memory allocation in the SDK; however, STL types still dominate the public interface through string parameters to the model object initialize and set methods. If you choose not to use STL and use strings and containers instead, you must create a lot of temporaries whenever you want to make a service call.
100+
101+
To remove most of the temporaries and allocation when service calls are made using non-STL, we have implemented the following:
102+
* Every Init/Set function that takes a string has an overload that takes the const char*.
103+
* Every Init/Set function that takes a container (map/vector) has an add variant that takes a single entry.
104+
* Every Init/Set function that takes binary data has an overload that takes a pointer to the data and a length value.
105+
* (Optional) Every Init/Set function that takes a string has an overload that takes a non-zero terminated constr char* and a length value.

‎Docs/README.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# AWS SDK for C++ Documentation
2+
3+
Here you can find some helpful information on usage of the SDK.
4+
5+
* [Using the SDK](./SDK_usage_guide.md)
6+
* [CMake Parameters](./CMake_Parameters.md)
7+
* [Credentials Providers](./Credentials_Providers.md)
8+
* [Client Configuration Parameters](./ClientConfiguration_Parameters.md)
9+
* [Service Client](./Service_Client.md)
10+
* [Memory Management](./Memory_Management.md)
11+
* [Advanced Topics](./Advanced_topics.md)
12+
* [Coding Standards](./CODING_STANDARDS.md)

‎Docs/SDK_usage_guide.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Using the SDK
2+
After they are constructed, individual service clients are very similar to other SDKs, such as Java and .NET. This section explains how core works, how to use each feature, and how to construct an individual client.
3+
4+
The aws-cpp-sdk-core is the heart of the system and does the heavy lifting. You can write a client to connect to any AWS service using just the core, and the individual service clients are available to help make the process a little easier.
5+
6+
## Running integration tests:
7+
Several directories are appended with \*integration-tests. After building your project, you can run these executables to ensure everything works properly.
8+
9+
## Build Defines
10+
If you dynamically link to the SDK you will need to define the USE_IMPORT_EXPORT symbol for all build targets using the SDK.
11+
If you wish to install your own memory manager to handle allocations made by the SDK, you will need to pass the CUSTOM_MEMORY_MANAGEMENT cmake parameter (-DCUSTOM_MEMORY_MANAGEMENT) as well as define AWS_CUSTOM_MEMORY_MANAGEMENT in all build targets dependent on the SDK.
12+
13+
Note, if you use our export file, this will be handled automatically for you. We recommend you use our export file to handle this for you:
14+
https://aws.amazon.com/blogs/developer/using-cmake-exports-with-the-aws-sdk-for-c/
15+
16+
## Initialization and Shutdown
17+
We avoid global and static state where ever possible. However, on some platforms, dependencies need to be globally initialized. Also, we have a few global options such as
18+
logging, memory management, http factories, and crypto factories. As a result, before using the SDK you MUST call our global initialization function. When you are finished using the SDK you should call our cleanup function.
19+
20+
All code using the AWS SDK and C++ should have at least the following:
21+
22+
```cpp
23+
#include <aws/core/Aws.h>
24+
...
25+
26+
Aws::SDKOptions options;
27+
Aws::InitAPI(options);
28+
29+
//use the sdk
30+
31+
Aws::ShutdownAPI(options);
32+
```
33+
34+
Due to the way memory managers work, many of the configuration options take closures instead of pointers directly in order to ensure that the memory manager
35+
is installed prior to any memory allocations occuring.
36+
37+
Here are a few recipes:
38+
39+
* Just use defaults:
40+
```cpp
41+
Aws::SDKOptions options;
42+
Aws::InitAPI(options);
43+
.....
44+
Aws::ShutdownAPI(options);
45+
```
46+
47+
* Install custom memory manager:
48+
```cpp
49+
MyMemoryManager memoryManager;
50+
51+
Aws::SDKOptions options;
52+
options.memoryManagementOptions.memoryManager = &memoryManager;
53+
Aws::InitAPI(options);
54+
.....
55+
Aws::ShutdownAPI(options);
56+
```
57+
58+
* Override default http client factory:
59+
```cpp
60+
Aws::SDKOptions options;
61+
options.httpOptions.httpClientFactory_create_fn = [](){ return Aws::MakeShared<MyCustomHttpClientFactory>("ALLOC_TAG", arg1); };
62+
Aws::InitAPI(options);
63+
.....
64+
Aws::ShutdownAPI(options);
65+
```
66+
## Logging
67+
The AWS SDK for C++ includes logging support that you can configure. When initializing the logging system, you can control the filter level and the logging target (file with a name that has a configurable prefix or a stream). The log file generated by the prefix option rolls over once per hour to allow for archiving or deleting log files.
68+
69+
You can provide your own logger. However, it is incredibly simple to use the default logger we've already provided:
70+
71+
In your main function:
72+
73+
```cpp
74+
SDKOptions options;
75+
options.loggingOptions.logLevel = Aws::Utils::Logging::LogLevel::Info;
76+
Aws::InitAPI(options);
77+
//do SDK stuff;
78+
Aws::ShutdownAPI(options);
79+
```

‎Docs/Service_Client.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Service Clients
2+
You can use the default constructor, or you can use the system interfaces to construct a service client.
3+
4+
As an example, the following code creates an Amazon DynamoDB client using a specialized client configuration, default credentials provider chain, and default HTTP client factory:
5+
6+
```cpp
7+
auto limiter = Aws::MakeShared<Aws::Utils::RateLimits::DefaultRateLimiter<>>(ALLOCATION_TAG, 200000);
8+
9+
// Create a client
10+
ClientConfiguration config;
11+
config.scheme = Scheme::HTTPS;
12+
config.connectTimeoutMs = 30000;
13+
config.requestTimeoutMs = 30000;
14+
config.readRateLimiter = m_limiter;
15+
config.writeRateLimiter = m_limiter;
16+
17+
auto client = Aws::MakeShared<DynamoDBClient>(ALLOCATION_TAG, config);
18+
```
19+
20+
You can also do the following to manually pass credentials:
21+
`auto client = Aws::MakeShared<DynamoDBClient>(ALLOCATION_TAG, AWSCredentials("access_key_id", "secret_key"), config);`
22+
23+
Or you can do the following to use a custom credentials provider:
24+
`auto client = Aws::MakeShared<DynamoDBClient>(ALLOCATION_TAG, Aws::MakeShared<CognitoCachingAnonymousCredentialsProvider>(ALLOCATION_TAG, "identityPoolId", "accountId"), config);`
25+
26+
Now you can use your Amazon DynamoDB client.
27+

‎README.md

+110-639
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)
Please sign in to comment.