S3 Client inteface. More...

#include <s3-api.h>

Data Structures
struct	ListObjectV2Config
	`ListObjectsV2` request See https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html More...

struct	ListObjectV2Result
	`ListObjectsV2` response. See https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html More...

struct	ObjectVersionInfo
	object version history More...

struct	ReadBuffer
	Memory buffer used in SendParams. More...

struct	SendParams
	Send request parameters. More...

struct	VersioningInfo
	versioning information More...

Public Types
enum	FileIOMode
	I/O mode used for reading and writing data from/to files.

Public Member Functions
	S3Api (const std::string &access, const std::string &secret, const std::string &endpoint, const std::string &signingEndpoint="")

	S3Api ()=delete
	No default constructor.

	S3Api (const S3Api &)=delete
	No copy constructor, `libcurl` handle cannot be copied or shared.

	S3Api (S3Api &&other)
	Move constructor, `libcurl` handle is moved into new instance.

bool	TestBucket (const std::string &bucket)
	Check if bucket exist.

bool	TestObject (const std::string &bucket, const std::string &key)
	Check if key exists.

void	Clear ()
	Clear data and reset read and write functions.

const WebClient &	Send (const SendParams &p)
	Send request.

WebClient &	Config (const SendParams &p)
	Configure instance.

void	Send (const SendParams &params, WebClient::ReadFunction sendFun, void sendUserData, WebClient::WriteFunction receiveFun, void receiveUserData)

void	GetFileObject (const std::string &outFileName, const std::string &bucket, const std::string &key, size_t writeOffset=0, size_t beginReadOffset=0, size_t endReadOffset=0, Headers headers={{}}, const std::string &versionId="")
	Download object into file.

ETag	PutFileObject (const std::string &infileName, const std::string &bucket, const std::string &key, size_t readOffset=0, size_t readSize=0, Headers headers={{}}, const std::string &payloadHash={})
	Upload file to object.

ETag	UploadFilePart (const std::string &inFileName, size_t readOffset, size_t readSize, const std::string &bucket, const std::string &key, const UploadId &uid, int partNum, FileIOMode iomode=BUFFERED, int maxRetries=1, Headers headers={{}}, const std::string &payloadHash={})
	Upload file part. Invoke after calling CreateMultipartUpload and before calling CompleteMultipartUpload.

ssize_t	GetObjectSize (const std::string &bucket, const std::string &key, const std::string &versionId="")
	Return object size.

void	AbortMultipartUpload (const std::string &bucket, const std::string &key, const UploadId &uploadId)
	Abort multipart upload.

ETag	CompleteMultipartUpload (const UploadId &uid, const std::string &bucket, const std::string &key, const std::vector< ETag > &etags)
	Complete multipart upload.

std::string	CreateBucket (const std::string &bucket, const Headers &headers={{}}, const std::string &locationConstraint=std::string())
	Create bucket.

UploadId	CreateMultipartUpload (const std::string &bucket, const std::string &key, size_t partSize=0, Headers headers={})
	Create multipart upload.

void	DeleteBucket (const std::string &bucket, const Headers &headers={{}})
	Delete bucket.

void	DeleteObject (const std::string &bucket, const std::string &key, const Headers &headers={}, const std::string &versionId="")
	Delete object.

void	DeleteBucketTagging (const std::string &bucket, const Headers &headers={})
	Remove all tags from bucket.

void	DeleteObjectTagging (const std::string &bucket, const std::string &key, const Headers &headers={})
	Remove all tags from object.

AccessControlPolicy	GetBucketAcl (const std::string &bucket)

TagMap	GetBucketTagging (const std::string &bucket)
	Return bucket tags.

VersioningInfo	GetBucketVersioning (const std::string &bucket)
	Retrieve versioning status.

const CharArray &	GetObject (const std::string &bucket, const std::string &key, size_t beginReadOffset=0, size_t endReadOffset=0, Headers={{}}, const std::string &versionId="")
	Download object data.

void	GetObject (const std::string &bucket, const std::string &key, CharArray &outBuffer, size_t writeOffset, size_t beginReadOffset=0, size_t endReadOffset=0, Headers headers={{}}, const std::string &versionId="")
	Download object data into `vector<char>`

void	GetObject (const std::string &bucket, const std::string &key, char *outBuffer, size_t writeOffset, size_t beginReadOffset=0, size_t endReadOffset=0, Headers headers={{}}, const std::string &versionId="")
	Download object data into `char` buffer.

AccessControlPolicy	GetObjectAcl (const std::string &bucket, const std::string &key)
	Return bucket's Access Control List.

TagMap	GetObjectTagging (const std::string &bucket, const std::string &key)
	Return object tags.

Headers	HeadBucket (const std::string &bucket, const Headers &headers={{}})

Headers	HeadObject (const std::string &bucket, const std::string &key, const Headers &={{}}, const std::string &versionId="")
	Send `HeadObject` request.

std::vector< BucketInfo >	ListBuckets (const Headers &headers={{}})
	List buckets.

ListObjectV2Result	ListObjectsV2 (const std::string &bucket, const ListObjectV2Config &config=ListObjectV2Config{}, const Headers &={{}})
	List objects by sending a `ListObjectsV2` request.

ObjectVersionInfo	ListObjectVersions (const std::string &bucket, const std::string &key)
	Return all versions and delete markers for object.

void	PutBucketAcl (const std::string &bucket, const AccessControlPolicy &acl)
	Set Access Control Policy for bucket.

void	PutBucketTagging (const std::string &bucket, const TagMap &tags, const Headers &headers={})
	Tag bucket.

void	PutBucketVersioning (const std::string &bucket, bool enabled)
	Enable bucket versioning.

ETag	PutObject (const std::string &bucket, const std::string &key, const CharArray &buffer, Headers headers={{}}, const std::string &payloadHash={})
	Upload data to object by sending a `PutObject` request.

ETag	PutObject (const std::string &bucket, const std::string &key, const char *buffer, size_t size, Headers headers={{}}, const std::string &payloadHash={})
	Upload data to object by sending a `PutObject` request.

void	PutObjectAcl (const std::string &bucket, const std::string &key, const AccessControlPolicy &acl)
	Set Access Control Policy.

void	PutObjectTagging (const std::string &bucket, const std::string &key, const TagMap &tags, const Headers &headers={})
	Set object tags.

ETag	UploadPart (const std::string &bucket, const std::string &key, const UploadId &uid, int partNum, const char *data, size_t size, int maxRetries=1, Headers headers={{}}, const std::string &payloadHash={})
	Upload part.

const std::string &	Access () const

const std::string &	Secret () const

const std::string &	Endpoint () const

const std::string &	SigningEndpoint () const

const std::vector< char > &	GetResponseBody () const

std::string	GetResponseText () const

Headers	GetResponseHeaders () const
	Get returned HTTP headers. Use this method to retrieve additional information e.g. `versionId` after sending a request.

Detailed Description

S3 Client inteface.

Implements some of the S3 actions documented here: https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations_Amazon_Simple_Storage_Service.html

Also includes higher level methods to simplify access to the API.

When sending requests, the fields specified as URL prameters are passed to methods as C++ structs and sent as part of the request, but in most cases the optional parameters sent as HTTP header fields are not sent along, it is therefore required to explicitly pass them in the headers parameter.

E.g. the ListObjectV2 request supports HTTP headers for specifying the payer for the request and owner of the listed objects.

 s3.ListObjectsV2(bucket, config, {
    {"x-amz-request-payer", "RequestPayer"},
    {"x-amz-expected-bucket-owner", "ExpectedBucketOwner"}
});

Error handling

Currently exceptions are being used to report errors, work is ongoing to move to result types similar to Rust's Result<ResultT,ErrorT>.

All methods that send requests throw:

std::runtime_error in case of errors sending the request
std::logic_error when the returned response code is >= 400

Example

From test cases printing results in CSV format.

Bucket

  string action = "CreateBucket";
  try {
    S3Api s3(cfg.access, cfg.secret, cfg.url);
    bucketName = prefix + ToLower(Timestamp());
    s3.CreateBucket(bucketName);
    TestOutput(action, true, TEST_PREFIX);
  } catch (const exception &e) {
    TestOutput(action, false, TEST_PREFIX, e.what());
  }

  action = "ListBuckets";
  try {
    S3Api s3(cfg.access, cfg.secret, cfg.url);
    auto buckets = s3.ListBuckets();
    if (buckets.empty()) {
      throw logic_error("Empty bucket list");
    }
    if (end(buckets) ==
        find_if(begin(buckets), end(buckets),
                [&](const auto &b) { return b.name == bucketName; })) {
      throw logic_error("Missing bucket");
    }
    TestOutput(action, true, TEST_PREFIX);
  } catch (const exception &e) {
    TestOutput(action, false, TEST_PREFIX, e.what());
  }

  action = "DeleteBucket";
  try {
    S3Api s3(cfg.access, cfg.secret, cfg.url);
    s3.DeleteBucket(bucketName);
    TestOutput(action, true, TEST_PREFIX);
  } catch (const exception &e) {
    TestOutput(action, false, TEST_PREFIX, e.what());
  }

Object

  action = "PutObject";
  try {
    S3Api s3(cfg.access, cfg.secret, cfg.url);
    const ETag etag = s3.PutObject(bucketName, objName, data);
    TestOutput(action, true, TEST_PREFIX);
  } catch (const exception &e) {
    TestOutput(action, false, TEST_PREFIX, e.what());
  }

  action = "GetObject";
  try {
    S3Api s3(cfg.access, cfg.secret, cfg.url);
    const auto &obj = s3.GetObject(bucketName, objName);
    if (obj != data) {
      throw logic_error("Data mismatch");
    }
    TestOutput(action, true, TEST_PREFIX);
  } catch (const exception &e) {
    TestOutput(action, false, TEST_PREFIX, e.what());
  }
 
  action = "Put/GetObjectTagging";
  try {
    S3Api s3(cfg.access, cfg.secret, cfg.url);
    TagMap tags = {{"tag1", "value1"}, {"tag2", "value2"}};
    s3.PutObjectTagging(bucketName, objName, tags);
    auto t = s3.GetObjectTagging(bucketName, objName);
    if (t != tags) {
      if (t.empty()) {
        throw logic_error("No tag set");
      }
      throw logic_error("Tags do not match");
    }
    TestOutput(action, true, TEST_PREFIX);
  } catch (const exception &e) {
    TestOutput(action, false, e.what());
  }
 

  action = "ListObjectsV2";
  try {
    S3Api s3(cfg.access, cfg.secret, cfg.url);
    auto objects = s3.ListObjectsV2(bucketName);
    if (objects.keys.empty()) {
      throw runtime_error("Empty object list");
    }
    bool found = false;
    for (const auto &k : objects.keys) {
      if (k.key == objName) {
        found = true;
        break;
      }
    }
    if (!found) {
      throw logic_error("Object not found");
    }
    TestOutput(action, true, TEST_PREFIX);
  } catch (const exception &e) {
    TestOutput(action, false, TEST_PREFIX, e.what());
  }

Constructor & Destructor Documentation

◆ S3Api()

sss::api::S3Api::S3Api	(	const std::string &	access,
		const std::string &	secret,
		const std::string &	endpoint,
		const std::string &	signingEndpoint = `""`
	)

inline

Constructor.

Parameters

[in]	access	access token
[in]	secret	token
[in]	endpoint	where reqests as sent
[in]	signingEndpoint	url used to sign request, required in case requests are not sent to S3 endpoint (e.g. SSH tunnel used).

Member Function Documentation

◆ AbortMultipartUpload()

void sss::api::S3Api::AbortMultipartUpload	(	const std::string &	bucket,
		const std::string &	key,
		const UploadId &	uploadId
	)

Abort multipart upload.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	uploadId	upload id returned by CreateMultipartUpload

References Send().

Here is the call graph for this function:

◆ Access()

const std::string & sss::api::S3Api::Access ( ) const

inline

Returns: access token

Here is the caller graph for this function:

◆ CompleteMultipartUpload()

ETag sss::api::S3Api::CompleteMultipartUpload	(	const UploadId &	uid,
		const std::string &	bucket,
		const std::string &	key,
		const std::vector< ETag > &	etags
	)

Complete multipart upload.

Parameters

[in]	uid	upload id returned by CreateMultipartUpload
[in]	bucket	bucket name
[in]	key	key name
[in]	etags	etags of uploaded parts

Returns: etag of multipart upload

Exceptions

std::runtime_error	in case of error sending request
std::logic_error	in case of returned error (status >= 400)

References Send(), and sss::XMLTag().

Here is the call graph for this function:

◆ Config()

WebClient & sss::api::S3Api::Config ( const SendParams & p )

Configure instance.

[WebClient::Config]

Parameters

[in] p configuration

See also: SendParams

References Access(), sss::api::S3Api::SendParams::bucket, Clear(), Endpoint(), sss::api::S3Api::SendParams::headers, sss::api::S3Api::SendParams::key, sss::api::S3Api::SendParams::method, sss::api::S3Api::SendParams::params, sss::api::S3Api::SendParams::payloadHash, Secret(), sss::WebClient::SetEndpoint(), sss::WebClient::SetHeaders(), sss::WebClient::SetMethod(), sss::WebClient::SetPath(), sss::WebClient::SetReqParameters(), and sss::SignHeaders().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CreateBucket()

string sss::api::S3Api::CreateBucket	(	const std::string &	bucket,
		const Headers &	headers = `{{}}`,
		const std::string &	locationConstraint = `std::string()`
	)

Create bucket.

Parameters

[in]	bucket	bucket name
[in]	headers	optional HTTP headers as {name, value} map
[in]	locationConstraint	bucket location e.g. `ap-east-1` or `EU` refer to the updated list on the AWS web site

Returns: bucket location

References sss::api::S3Api::SendParams::method, sss::ParseHeaders(), Send(), and sss::ToLower().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CreateMultipartUpload()

UploadId sss::api::S3Api::CreateMultipartUpload	(	const std::string &	bucket,
		const std::string &	key,
		size_t	partSize = `0`,
		Headers	headers = `{}`
	)

Create multipart upload.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	partSize	part size hint, optional
[in]	headers	optional HTTP headers as {name, value} map

References sss::WebClient::GetContentText(), Send(), and sss::XMLTag().

Here is the call graph for this function:

◆ DeleteBucket()

void sss::api::S3Api::DeleteBucket	(	const std::string &	bucket,
		const Headers &	headers = `{{}}`
	)

Delete bucket.

Parameters

[in]	bucket	bucket name
[in]	headers	headers sent along w
[in]	headers	optional HTTP headers as {name, value} map

References Send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ DeleteBucketTagging()

void sss::api::S3Api::DeleteBucketTagging	(	const std::string &	bucket,
		const Headers &	headers = `{}`
	)

Remove all tags from bucket.

Parameters

[in]	bucket	bucket name
[in]	headers	optional http headers as {name, value} map

References Send().

Here is the call graph for this function:

◆ DeleteObject()

void sss::api::S3Api::DeleteObject	(	const std::string &	bucket,
		const std::string &	key,
		const Headers &	headers = `{}`,
		const std::string &	versionId = `""`
	)

Delete object.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	headers	optional http headers as {name, value} map sent along with request
[in]	versionId	version id, leave blank for latest version or in case versioning is not enabled

References Send().

Here is the call graph for this function:

◆ DeleteObjectTagging()

void sss::api::S3Api::DeleteObjectTagging	(	const std::string &	bucket,
		const std::string &	key,
		const Headers &	headers = `{}`
	)

Remove all tags from object.

Parameters

[in]	bucket	bucket name
[in]	key	name
[in]	headers	optional http headers as {name, value} map

References Send().

Here is the call graph for this function:

◆ Endpoint()

const std::string & sss::api::S3Api::Endpoint ( ) const

inline

Returns: endpoint URL

Here is the caller graph for this function:

◆ GetBucketAcl()

AccessControlPolicy sss::api::S3Api::GetBucketAcl ( const std::string & bucket )

Return bucket's Access Control List

Parameters

bucket bucket name

Returns: Acess Control Policy

See also: AccessControlPolicy

References Send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetBucketTagging()

TagMap sss::api::S3Api::GetBucketTagging ( const std::string & bucket )

Return bucket tags.

Parameters

[in] bucket bucket name

Returns: tag name => tag value map

References Send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetBucketVersioning()

S3Api::VersioningInfo sss::api::S3Api::GetBucketVersioning ( const std::string & bucket )

Retrieve versioning status.

Parameters

[in] bucket bucket name

Returns: versioning info: if enabled and if MFA delete enabled

See also: VersioningInfo

References Send(), sss::ToLower(), and sss::XMLTag().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetFileObject()

void sss::api::S3Api::GetFileObject	(	const std::string &	outFileName,
		const std::string &	bucket,
		const std::string &	key,
		size_t	writeOffset = `0`,
		size_t	beginReadOffset = `0`,
		size_t	endReadOffset = `0`,
		Headers	headers = `{{}}`,
		const std::string &	versionId = `""`
	)

Download object into file.

Parameters

[in]	outFileName	output file name
[in]	bucket	bucket name
[in]	key	key name
[in]	writeOffset	write location in file
[in]	beginReadOffset	offset of first byte to read from object
[in]	endReadOffset	offset of last byte to read from object
[in]	headers	optional headers
[in]	versionId	version id

References sss::begin(), Config(), sss::end(), sss::HandleError(), sss::WebClient::Send(), and sss::WebClient::SetWriteFunction().

Here is the call graph for this function:

◆ GetObject() [1/3]

void sss::api::S3Api::GetObject	(	const std::string &	bucket,
		const std::string &	key,
		char *	outBuffer,
		size_t	writeOffset,
		size_t	beginReadOffset = `0`,
		size_t	endReadOffset = `0`,
		Headers	headers = `{{}}`,
		const std::string &	versionId = `""`
	)

Download object data into char buffer.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[out]	outBuffer	output buffer
[in]	writeOffset	offset in output buffer
[in]	beginReadOffset	offset of first byte read from object
[in]	endReadOffset	offset of last byte read from object
[in]	optional	http headers as {name, value} map sent along with request
[in]	versionId	version id, leave blank for latest version or in case versioning is not enabled

◆ GetObject() [2/3]

void sss::api::S3Api::GetObject	(	const std::string &	bucket,
		const std::string &	key,
		CharArray &	outBuffer,
		size_t	writeOffset,
		size_t	beginReadOffset = `0`,
		size_t	endReadOffset = `0`,
		Headers	headers = `{{}}`,
		const std::string &	versionId = `""`
	)

Download object data into vector<char>

Parameters

[in]	bucket	bucket name
[in]	key	key name
[out]	outBuffer	output buffer
[in]	writeOffset	offset in output buffer
[in]	beginReadOffset	offset of first byte read from object
[in]	endReadOffset	offset of last byte read from object
[in]	optional	http headers as {name, value} map sent along with request
[in]	versionId	version id, leave blank for latest version or in case versioning is not enabled

◆ GetObject() [3/3]

const CharArray & sss::api::S3Api::GetObject	(	const std::string &	bucket,
		const std::string &	key,
		size_t	beginReadOffset = `0`,
		size_t	endReadOffset = `0`,
		Headers	= `{{}}`,
		const std::string &	versionId = `""`
	)

Download object data.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	beginReadOffset	offset of first byte read from object
[in]	endReadOffset	offset of last byte read from object
[in]	optional	http headers as {name, value} map sent along with request
[in]	versionId	version id, leave blank for latest version or in case versioning is not enabled

Returns: char array; char is the type used by libcurl

◆ GetObjectAcl()

AccessControlPolicy sss::api::S3Api::GetObjectAcl	(	const std::string &	bucket,
		const std::string &	key
	)

Return bucket's Access Control List.

Parameters

bucket	bucket name
key	key name

Returns: Acess Control Policy

See also: AccessControlPolicy

References Send().

Here is the call graph for this function:

◆ GetObjectSize()

ssize_t sss::api::S3Api::GetObjectSize	(	const std::string &	bucket,
		const std::string &	key,
		const std::string &	versionId = `""`
	)

Return object size.

[WebClient::Config]

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	versionId	version id

Returns: object size

References sss::GetValue(), and HeadObject().

Here is the call graph for this function:

◆ GetObjectTagging()

TagMap sss::api::S3Api::GetObjectTagging	(	const std::string &	bucket,
		const std::string &	key
	)

Return object tags.

Parameters

[in]	bucket	bucket name
[in]	key	key name

Returns: tag name => tag value map

References Send().

Here is the call graph for this function:

◆ GetResponseBody()

const std::vector< char > & sss::api::S3Api::GetResponseBody ( ) const

inline

Returns: response body

References sss::WebClient::GetResponseBody().

Here is the call graph for this function:

◆ GetResponseHeaders()

Headers sss::api::S3Api::GetResponseHeaders ( ) const

inline

Get returned HTTP headers. Use this method to retrieve additional information e.g. versionId after sending a request.

Returns: {header name, header value} map

References sss::WebClient::GetHeaderText(), and sss::HTTPHeaders().

Here is the call graph for this function:

◆ GetResponseText()

std::string sss::api::S3Api::GetResponseText ( ) const

inline

Returns: response body as text

References sss::WebClient::GetContentText().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ HeadBucket()

Headers sss::api::S3Api::HeadBucket	(	const std::string &	bucket,
		const Headers &	headers = `{{}}`
	)

Send HeadBucket request

Parameters

[in]	bucket	bucket name
[in]	optional	http headers as {name, value} map sent along with request

Returns: HTTP headers as {http header name, value} map

References sss::HTTPHeaders(), and Send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ HeadObject()

Headers sss::api::S3Api::HeadObject	(	const std::string &	bucket,
		const std::string &	key,
		const Headers &	= `{{}}`,
		const std::string &	versionId = `""`
	)

Send HeadObject request.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	optional	http headers as {name, value} map sent along with request
[in]	versionId	version id, leave blank for latest version or in case versioning is not enabled

Returns: HTTP headers as {http header name, value} map

References sss::HTTPHeaders(), and Send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ListBuckets()

vector< BucketInfo > sss::api::S3Api::ListBuckets ( const Headers & headers = {{}} )

List buckets.

Parameters

[in] headers optional http headers as {name, value} map sent along with request

Returns: bucket list

See also: BucketInfo

References sss::WebClient::GetContentText(), and Send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ListObjectsV2()

S3Api::ListObjectV2Result sss::api::S3Api::ListObjectsV2	(	const std::string &	bucket,
		const ListObjectV2Config &	config = `ListObjectV2Config{}`,
		const Headers &	headers = `{{}}`
	)

List objects by sending a ListObjectsV2 request.

Parameters

[in]	bucket	bucket name
[in]	config	optional configuration parameters

See also: ListObjectV2Config

Parameters

[in] headers optional http headers as {name, value} map sent along with request

Returns: object list

See also: ListObjectV2Result

References sss::WebClient::GetContentText(), and Send().

Here is the call graph for this function:

◆ ListObjectVersions()

S3Api::ObjectVersionInfo sss::api::S3Api::ListObjectVersions	(	const std::string &	bucket,
		const std::string &	key
	)

Return all versions and delete markers for object.

Parameters

[in] bucket bucket name

\key[in] key name

Returns: list of versions and delete markers; delete markers are version ids that have been marked as deleted

See also: ObjectVersionInfo

References GetResponseText(), and Send().

Here is the call graph for this function:

◆ PutBucketAcl()

void sss::api::S3Api::PutBucketAcl	(	const std::string &	bucket,
		const AccessControlPolicy &	acl
	)

Set Access Control Policy for bucket.

Parameters

[in]	bucket	bucket name
[in]	acl	Acess Control Policy

See also: AccessControlPolicy

References Send().

Here is the call graph for this function:

◆ PutBucketTagging()

void sss::api::S3Api::PutBucketTagging	(	const std::string &	bucket,
		const TagMap &	tags,
		const Headers &	headers = `{}`
	)

Tag bucket.

Parameters

[in]	bucket	bucket name
[in]	tags	tag map: {tag name => tag value}
[in]	http	headers as {header name, header value} map

References Send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ PutBucketVersioning()

void sss::api::S3Api::PutBucketVersioning	(	const std::string &	bucket,
		bool	enabled
	)

Enable bucket versioning.

Parameters

[in]	bucket	bucket name
[in]	enables	`true` to enable, `false` to disable

References Send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ PutFileObject()

ETag sss::api::S3Api::PutFileObject	(	const std::string &	infileName,
		const std::string &	bucket,
		const std::string &	key,
		size_t	readOffset = `0`,
		size_t	readSize = `0`,
		Headers	headers = `{{}}`,
		const std::string &	payloadHash = `{}`
	)

Upload file to object.

Parameters

[in]	infileName	input file name
[in]	bucket	bucket name
[in]	key	key name
[in]	readOffset	offset of first byte to read from file
[in]	readSize	number of bytes to read from file starting at `readOffset`

Returns: ETag of uploaded object

References Config(), sss::WebClient::ErrorMsg(), sss::WebClient::GetHeaderText(), sss::HandleError(), sss::HTTPHeader(), and sss::WebClient::UploadFile().

Here is the call graph for this function:

◆ PutObject() [1/2]

ETag sss::api::S3Api::PutObject	(	const std::string &	bucket,
		const std::string &	key,
		const char *	buffer,
		size_t	size,
		Headers	headers = `{{}}`,
		const std::string &	payloadHash = `{}`
	)

Upload data to object by sending a PutObject request.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	buffer	input buffer
[in]	headers	optional HTTP headers as {header name, value} map
[in]	optional	payloadHash payload hash can be empty

Returns: etag

◆ PutObject() [2/2]

ETag sss::api::S3Api::PutObject	(	const std::string &	bucket,
		const std::string &	key,
		const CharArray &	buffer,
		Headers	headers = `{{}}`,
		const std::string &	payloadHash = `{}`
	)

Upload data to object by sending a PutObject request.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	buffer	input buffer
[in]	headers	optional http headers as {header name, value} map
[in]	optional	payloadHash payload hash can be empty

Returns: etag

◆ PutObjectAcl()

void sss::api::S3Api::PutObjectAcl	(	const std::string &	bucket,
		const std::string &	key,
		const AccessControlPolicy &	acl
	)

Set Access Control Policy.

Parameters

bucket[in]	bucket name
key[in]	key name
acl[in]	access control policy

See also: AccessControlPolicy

References Send().

Here is the call graph for this function:

◆ PutObjectTagging()

void sss::api::S3Api::PutObjectTagging	(	const std::string &	bucket,
		const std::string &	key,
		const TagMap &	tags,
		const Headers &	headers = `{}`
	)

Set object tags.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	tags	tag map
[in]	headers	http headers as {header name, header value} map

References Send().

Here is the call graph for this function:

◆ Secret()

const std::string & sss::api::S3Api::Secret ( ) const

inline

Returns: secret token

Here is the caller graph for this function:

◆ Send() [1/2]

const WebClient & sss::api::S3Api::Send ( const SendParams & p )

inline

Send request.

Parameters

[in] p send parameters

See also: SendParams

Returns: reference to this S3Api instance.

Exceptions

std::runtime_error	in case of error sending request
std::logic_error	in case of returned error (status >= 400)

References Config(), sss::HandleError(), sss::api::S3Api::SendParams::method, sss::ParseParams(), sss::WebClient::Send(), sss::WebClient::SetPostData(), sss::WebClient::SetUrlEncodedPostData(), sss::ToLower(), sss::api::S3Api::SendParams::uploadData, sss::WebClient::UploadDataFromBuffer(), and sss::api::S3Api::SendParams::urlEncodePostParams.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Send() [2/2]

void sss::api::S3Api::Send	(	const SendParams &	params,
		WebClient::ReadFunction	sendFun,
		void *	sendUserData,
		WebClient::WriteFunction	receiveFun,
		void *	receiveUserData
	)

inline

Send method with configurable send and receive functions.

Parameters

[in] params

See also: SendParams

Parameters

[in]	sendFun	pointer to function generating the data to send
[in]	sendUseData	pointer to user data passed to `sendFun` at each invocation
[in]	receiveFun	pointer to function receiving data
[in]	receiveUserData	pointer to user data passed to `receiveFun` at each invocation

References Send(), sss::WebClient::SetReadFunction(), and sss::WebClient::SetWriteFunction().

Here is the call graph for this function:

◆ SigningEndpoint()

const std::string & sss::api::S3Api::SigningEndpoint ( ) const

inline

Returns: signing endpoint URL

Here is the caller graph for this function:

◆ TestBucket()

bool sss::api::S3Api::TestBucket ( const std::string & bucket )

Check if bucket exist.

Parameters

[in] bucket bucket name

Returns: true if bucket exist, false otherwise

References Send(), and SigningEndpoint().

Here is the call graph for this function:

◆ TestObject()

bool sss::api::S3Api::TestObject	(	const std::string &	bucket,
		const std::string &	key
	)

Check if key exists.

Parameters

[in]	bucket	bucket name
[in]	key	key name

Returns: true if key exists, false otherwise

References HeadObject().

Here is the call graph for this function:

◆ UploadFilePart()

ETag sss::api::S3Api::UploadFilePart	(	const std::string &	inFileName,
		size_t	readOffset,
		size_t	readSize,
		const std::string &	bucket,
		const std::string &	key,
		const UploadId &	uid,
		int	partNum,
		FileIOMode	iomode = `BUFFERED`,
		int	maxRetries = `1`,
		Headers	headers = `{{}}`,
		const std::string &	payloadHash = `{}`
	)

Upload file part. Invoke after calling CreateMultipartUpload and before calling CompleteMultipartUpload.

Parameters

[in]	inFileName	input file name
[in]	readOffset	offset of first byte to read in file
[in]	readSize	number of bytes to read starting at `readOffset`
[in]	bucket	bucket name
[in]	key	key name
[in]	uid	upload id returned by CreateMultipartUpload method
[in]	partNum	zero-indexed part number
[in]	iomode	read mode

See also: FileIOMode

Parameters

[in]	maxRetries	number of retried before aborting upload
[in]	headers	optional HTTP headers as {name, value} map
[in]	payloadHash	payload hash, can be empty

Returns: ETag of uploaded object

◆ UploadPart()

ETag sss::api::S3Api::UploadPart	(	const std::string &	bucket,
		const std::string &	key,
		const UploadId &	uid,
		int	partNum,
		const char *	data,
		size_t	size,
		int	maxRetries = `1`,
		Headers	headers = `{{}}`,
		const std::string &	payloadHash = `{}`
	)

Upload part.

Parameters

[in]	bucket	bucket name
[in]	key	key name
[in]	uid	upload id returned by CreateMultipartUpload
[in]	partNum	zero-indexed part number
[in]	data	input buffer
[in]	size	data size
[in]	maxRetries	maximum number of retries before aborting upload
[in]	headers	optional HTTP headers as {header name, value} map
[in]	payloadHash	optional payload hash, can be empty

Returns: etag

The documentation for this class was generated from the following files:

/Users/ugo/projects/s3client/repo/lib/include/s3-api.h
/Users/ugo/projects/s3client/repo/lib/src/api/bucket.cpp
/Users/ugo/projects/s3client/repo/lib/src/api/multipart_upload.cpp
/Users/ugo/projects/s3client/repo/lib/src/api/object.cpp
/Users/ugo/projects/s3client/repo/lib/src/api/s3-api.cpp

Data Structures

Public Types

Public Member Functions

Detailed Description

Error handling

Example

Constructor & Destructor Documentation

◆ S3Api()

Member Function Documentation

◆ AbortMultipartUpload()

◆ Access()

◆ CompleteMultipartUpload()

◆ Config()

◆ CreateBucket()

◆ CreateMultipartUpload()

◆ DeleteBucket()

◆ DeleteBucketTagging()

◆ DeleteObject()

◆ DeleteObjectTagging()

◆ Endpoint()

◆ GetBucketAcl()

◆ GetBucketTagging()

◆ GetBucketVersioning()

◆ GetFileObject()

◆ GetObject() [1/3]

◆ GetObject() [2/3]

◆ GetObject() [3/3]

◆ GetObjectAcl()

◆ GetObjectSize()

◆ GetObjectTagging()

◆ GetResponseBody()

◆ GetResponseHeaders()

◆ GetResponseText()

◆ HeadBucket()

◆ HeadObject()

◆ ListBuckets()

◆ ListObjectsV2()

◆ ListObjectVersions()

◆ PutBucketAcl()

◆ PutBucketTagging()

◆ PutBucketVersioning()

◆ PutFileObject()

◆ PutObject() [1/2]

◆ PutObject() [2/2]

◆ PutObjectAcl()

◆ PutObjectTagging()

◆ Secret()

◆ Send() [1/2]

◆ Send() [2/2]

◆ SigningEndpoint()

◆ TestBucket()

◆ TestObject()

◆ UploadFilePart()

◆ UploadPart()