Aws::Crt::S3::S3MetaRequestOptions Class Reference

#include <S3.h>

Inheritance diagram for Aws::Crt::S3::S3MetaRequestOptions:

Classes
struct	Impl

Public Types
using	BodyCallback = std::function< bool(ByteCursor body, uint64_t rangeStart)>
using	BodyCallbackEx = std::function< bool(ByteCursor body, uint64_t rangeStart, S3BufferTicket &ticket)>
using	HeadersCallback = std::function< bool(const Vector< Http::HttpHeader > &headers, int responseStatus)>
using	ProgressCallback = std::function< void(uint64_t bytesTransferred, uint64_t contentLength)>
using	FinishCallback = std::function< void(const S3MetaRequestResult &result)>
using	ShutdownCallback = std::function< void()>

Public Member Functions
	S3MetaRequestOptions (const S3MetaRequestOptions &)=delete
	S3MetaRequestOptions (S3MetaRequestOptions &&)=delete
S3MetaRequestOptions &	operator= (const S3MetaRequestOptions &)=delete
S3MetaRequestOptions &	operator= (S3MetaRequestOptions &&)=delete
virtual	~S3MetaRequestOptions () noexcept
S3MetaRequestOptions &	SetSigningConfig (const Auth::AwsSigningConfig &config) noexcept
S3MetaRequestOptions &	SetSigningConfigFromEndpoint (const String &region, const String &signingRegion, const String &signingName, bool isS3Express, const std::shared_ptr< Auth::ICredentialsProvider > &provider) noexcept
S3MetaRequestOptions &	SetChecksumConfig (const S3ChecksumConfig &config) noexcept
S3MetaRequestOptions &	SetEndpoint (const Io::Uri &endpoint) noexcept
S3MetaRequestOptions &	SetHeadersCallback (HeadersCallback cb) noexcept
S3MetaRequestOptions &	SetProgressCallback (ProgressCallback cb) noexcept
S3MetaRequestOptions &	SetFinishCallback (FinishCallback cb) noexcept
S3MetaRequestOptions &	SetShutdownCallback (ShutdownCallback cb) noexcept
S3MetaRequestOptions &	SetRecvFileMode (S3RecvFileMode mode) noexcept
S3MetaRequestOptions &	SetRecvFilePosition (uint64_t position) noexcept
S3MetaRequestOptions &	SetRecvFileDeleteOnFailure (bool deleteOnFailure) noexcept
S3MetaRequestOptions &	SetObjectSizeHint (uint64_t bytes) noexcept
S3MetaRequestOptions &	SetPartSize (uint64_t bytes) noexcept
S3MetaRequestOptions &	SetMultipartUploadThreshold (uint64_t bytes) noexcept
const BodyCallback &	GetBodyCallback () const noexcept
const BodyCallbackEx &	GetBodyCallbackEx () const noexcept
const HeadersCallback &	GetHeadersCallback () const noexcept
const ProgressCallback &	GetProgressCallback () const noexcept
const FinishCallback &	GetFinishCallback () const noexcept
const ShutdownCallback &	GetShutdownCallback () const noexcept
int	GetLastError () const noexcept

Protected Member Functions
	S3MetaRequestOptions (S3MetaRequestType type, const std::shared_ptr< Http::HttpRequest > &request) noexcept

Protected Attributes
ScopedResource< Impl >	m_impl
std::shared_ptr< Http::HttpRequest >	m_httpRequest
String	m_operationName
String	m_sendFilepath
String	m_recvFilepath
aws_uri	m_endpoint
bool	m_endpointInit
Optional< uint64_t >	m_objectSizeHint
BodyCallback	m_bodyCb
BodyCallbackEx	m_bodyCbEx
HeadersCallback	m_headersCb
ProgressCallback	m_progressCb
FinishCallback	m_finishCb
ShutdownCallback	m_shutdownCb
int	m_lastError = AWS_ERROR_SUCCESS

Detailed Description

Abstract base for the four concrete options types. Users obtain a unique_ptr through the subclass's static Create factory (some subclasses overload Create so the body sink or source is chosen by argument type), then set cross-cutting fields on the base through the shared Set* setters before handing the object to S3Client::MakeMetaRequest.

Mutual exclusion of body-delivery paths (callback / callback_ex / recv_filepath) is enforced structurally by the factory shapes.

Member Typedef Documentation

using Aws::Crt::S3::S3MetaRequestOptions::BodyCallback = std::function<bool(ByteCursor body, uint64_t rangeStart)>

Invoked once per delivered body chunk during a download.

Parameters

body	the chunk of object bytes for this delivery.
rangeStart	byte offset within the object that this chunk starts at.

Returns

true to continue the meta request, false to abort it.

using Aws::Crt::S3::S3MetaRequestOptions::BodyCallbackEx = std::function<bool(ByteCursor body, uint64_t rangeStart, S3BufferTicket &ticket)>

Like BodyCallback, but the chunk is delivered with a borrowed S3BufferTicket. The receiver may call ticket.Acquire() to extend the buffer's lifetime past the callback return for zero-copy consumption.

Parameters

body	the chunk of object bytes for this delivery.
rangeStart	byte offset within the object that this chunk starts at.
ticket	borrowed handle to the CRT-owned buffer holding body.

Returns

true to continue the meta request, false to abort it.

using Aws::Crt::S3::S3MetaRequestOptions::FinishCallback = std::function<void(const S3MetaRequestResult &result)>

Invoked once when the meta request terminates (success or failure).

Parameters

result

final state of the meta request, including error code, HTTP status, and (on failure) the S3 error response headers and body. The error response body is a borrowed cursor into CRT-owned memory, valid only for the duration of this callback; copy it out if you need it.

using Aws::Crt::S3::S3MetaRequestOptions::HeadersCallback = std::function<bool(const Vector<Http::HttpHeader> &headers, int responseStatus)>

Invoked once when response headers are available.

Parameters

headers	materialized snapshot of the response headers.
responseStatus	HTTP status code from the response.

Returns

true to continue the meta request, false to abort it.

using Aws::Crt::S3::S3MetaRequestOptions::ProgressCallback = std::function<void(uint64_t bytesTransferred, uint64_t contentLength)>

Invoked periodically as bytes flow.

Parameters

bytesTransferred	number of bytes since the last invocation.
contentLength	total length of the transfer in bytes, if known.

using Aws::Crt::S3::S3MetaRequestOptions::ShutdownCallback = std::function<void()>

Invoked after the CRT has fully torn down the meta request and will not invoke any further callbacks. The right place to free any heap state that the callbacks depended on.

Constructor & Destructor Documentation

Aws::Crt::S3::S3MetaRequestOptions::S3MetaRequestOptions ( const S3MetaRequestOptions &  )

delete

Aws::Crt::S3::S3MetaRequestOptions::S3MetaRequestOptions ( S3MetaRequestOptions &&  )

delete

Aws::Crt::S3::S3MetaRequestOptions::~S3MetaRequestOptions ( )

virtualnoexcept

Aws::Crt::S3::S3MetaRequestOptions::S3MetaRequestOptions ( S3MetaRequestType  type, const std::shared_ptr< Http::HttpRequest > &  request  )

protectednoexcept

Protected ctor. Only invocable by subclasses. Allocates the C options struct, sets its type and message, and retains a shared reference to the HTTP request so the underlying aws_http_message stays alive for the meta request's lifetime.

Parameters

type	the operation the CRT should orchestrate.
request	the prepared HTTP request.

Member Function Documentation

const BodyCallback& Aws::Crt::S3::S3MetaRequestOptions::GetBodyCallback ( ) const

inlinenoexcept

Returns

the installed body callback, or an empty function if unset.

const BodyCallbackEx& Aws::Crt::S3::S3MetaRequestOptions::GetBodyCallbackEx ( ) const

inlinenoexcept

Returns

the installed zero-copy body callback, or an empty function if unset.

const FinishCallback& Aws::Crt::S3::S3MetaRequestOptions::GetFinishCallback ( ) const

inlinenoexcept

Returns

the installed finish callback, or an empty function if unset.

const HeadersCallback& Aws::Crt::S3::S3MetaRequestOptions::GetHeadersCallback ( ) const

inlinenoexcept

Returns

the installed response-headers callback, or an empty function if unset.

int Aws::Crt::S3::S3MetaRequestOptions::GetLastError ( ) const

inlinenoexcept

Returns

a validation error recorded by a Set* setter (ex. an invalid endpoint URI), or AWS_ERROR_SUCCESS if none. Checked by MakeMetaRequest before the request is issued.

const ProgressCallback& Aws::Crt::S3::S3MetaRequestOptions::GetProgressCallback ( ) const

inlinenoexcept

Returns

the installed progress callback, or an empty function if unset.

const ShutdownCallback& Aws::Crt::S3::S3MetaRequestOptions::GetShutdownCallback ( ) const

inlinenoexcept

Returns

the installed shutdown callback, or an empty function if unset.

S3MetaRequestOptions& Aws::Crt::S3::S3MetaRequestOptions::operator= ( const S3MetaRequestOptions &  )

delete

S3MetaRequestOptions& Aws::Crt::S3::S3MetaRequestOptions::operator= ( S3MetaRequestOptions &&  )

delete

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetChecksumConfig ( const S3ChecksumConfig &  config )

noexcept

Set the checksum configuration for this meta request.

Parameters

config

the checksum configuration.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetEndpoint ( const Io::Uri &  endpoint )

noexcept

Set a per-request endpoint override. Overrides the scheme and port the meta request would otherwise derive from the HTTP request. If the HTTP request already carries a Host header it must match this endpoint's authority, otherwise MakeMetaRequest fails. The options object owns a parsed copy of the URI for its lifetime. An invalid endpoint URI is recorded and causes MakeMetaRequest to fail with the parse error, rather than being silently ignored.

Parameters

endpoint

the endpoint URI to use for this meta request.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetFinishCallback ( FinishCallback  cb )

noexcept

Install the finish callback. Invoked once when the meta request terminates.

Parameters

cb	the callback to invoke on completion or failure.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetHeadersCallback ( HeadersCallback  cb )

noexcept

Install the response-headers callback.

Parameters

cb	the callback to invoke when response headers arrive.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetMultipartUploadThreshold ( uint64_t  bytes )

noexcept

Override the client-level multipart-upload threshold for just this meta request. Same semantics as S3ClientConfig::SetMultipartUploadThreshold. 0 means inherit from the client.

Parameters

bytes

threshold in bytes.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetObjectSizeHint ( uint64_t  bytes )

noexcept

Hint the size of the object being uploaded or downloaded. Used by the CRT to pick a strategy and validate part counts without an extra HeadObject roundtrip. Pass 0 to clear.

Parameters

bytes

known object size in bytes; 0 to clear.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetPartSize ( uint64_t  bytes )

noexcept

Override the client-level target part size for just this meta request. Same semantics as S3ClientConfig::SetPartSize. 0 means inherit from the client.

Parameters

bytes

target part size in bytes.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetProgressCallback ( ProgressCallback  cb )

noexcept

Install the progress callback.

Parameters

cb	the callback to invoke as bytes flow.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetRecvFileDeleteOnFailure ( bool  deleteOnFailure )

noexcept

Delete the receive file if the meta request fails. Off by default; the file is left as-is on failure. Useful when the caller wants the CRT to clean up its own temp file rather than doing the delete after the finish callback.

Parameters

deleteOnFailure

whether to delete the file on failure.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetRecvFileMode ( S3RecvFileMode  mode )

noexcept

Choose how the destination file supplied to a receive-to-file factory is opened. Defaults to CreateOrReplace. Ignored when the meta request has no receive filepath (i.e. a callback sink).

Parameters

mode	the file-open policy.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetRecvFilePosition ( uint64_t  position )

noexcept

Set the byte offset the CRT writes at when the recv file mode is WriteToPosition. Ignored otherwise.

Parameters

position

byte offset within the file.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetShutdownCallback ( ShutdownCallback  cb )

noexcept

Install the shutdown callback. Invoked after the CRT has fully torn down the meta request; the safe point to free callback state.

Parameters

cb	the callback to invoke after final teardown.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetSigningConfig ( const Auth::AwsSigningConfig &  config )

noexcept

Override the client-level signing config for this meta request.

Only the underlying handle is borrowed; no copy is taken (AwsSigningConfig is non-copyable). The supplied config must outlive the call that consumes it - S3Client::MakeMetaRequest, which deep-copies the signing config internally.

Parameters

config

the SigV4 signing config to use for this request.

Returns

this object, to allow chaining.

S3MetaRequestOptions & Aws::Crt::S3::S3MetaRequestOptions::SetSigningConfigFromEndpoint ( const String &  region, const String &  signingRegion, const String &  signingName, bool  isS3Express, const std::shared_ptr< Auth::ICredentialsProvider > &  provider  )

noexcept

Configure this meta request's signing from a resolved endpoint's auth scheme. The config is owned by this options object. Prefer this over SetSigningConfig for endpoint-resolved signing, since the S3Express algorithm is not expressible via the public SigningAlgorithm enum.

Parameters

region	the client region, used as the signing-config base.
signingRegion	signing region from the auth scheme, or empty to keep region.
signingName	signing service name from the auth scheme, or empty to keep "s3".
isS3Express	true for a directory bucket (use V4-S3Express); false for SigV4.
provider	the credentials provider used during signing. Required; a null provider is recorded as an error and fails MakeMetaRequest.

Returns

this object, to allow chaining.

Member Data Documentation

BodyCallback Aws::Crt::S3::S3MetaRequestOptions::m_bodyCb

protected

BodyCallbackEx Aws::Crt::S3::S3MetaRequestOptions::m_bodyCbEx

protected

aws_uri Aws::Crt::S3::S3MetaRequestOptions::m_endpoint

protected

bool Aws::Crt::S3::S3MetaRequestOptions::m_endpointInit

protected

FinishCallback Aws::Crt::S3::S3MetaRequestOptions::m_finishCb

protected

HeadersCallback Aws::Crt::S3::S3MetaRequestOptions::m_headersCb

protected

std::shared_ptr<Http::HttpRequest> Aws::Crt::S3::S3MetaRequestOptions::m_httpRequest

protected

ScopedResource<Impl> Aws::Crt::S3::S3MetaRequestOptions::m_impl

protected

int Aws::Crt::S3::S3MetaRequestOptions::m_lastError = AWS_ERROR_SUCCESS

protected

Optional<uint64_t> Aws::Crt::S3::S3MetaRequestOptions::m_objectSizeHint

protected

String Aws::Crt::S3::S3MetaRequestOptions::m_operationName

protected

ProgressCallback Aws::Crt::S3::S3MetaRequestOptions::m_progressCb

protected

String Aws::Crt::S3::S3MetaRequestOptions::m_recvFilepath

protected

String Aws::Crt::S3::S3MetaRequestOptions::m_sendFilepath

protected

ShutdownCallback Aws::Crt::S3::S3MetaRequestOptions::m_shutdownCb

protected

---

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

• include/aws/crt/s3/S3.h
• source/s3/S3.cpp