Skip to content

Commit 8117dc9

Browse files
KaibaLopezKaibaLopez
authored
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+
[email protected] 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+
```

0 commit comments

Comments
 (0)