Aws::Transfer::TransferHandle Class Reference

#include <TransferHandle.h>

Public Member Functions

 TransferHandle (const Aws::String &bucketName, const Aws::String &keyName, uint64_t totalSize, const Aws::String &targetFilePath="")

 

 TransferHandle (const Aws::String &bucketName, const Aws::String &keyName, const Aws::String &targetFilePath="")

 

 TransferHandle (const Aws::String &bucketName, const Aws::String &keyName, CreateDownloadStreamCallback createDownloadStreamFn, const Aws::String &targetFilePath="")

 

 TransferHandle (const Aws::String &bucketName, const Aws::String &keyName, const uint64_t fileOffset, const uint64_t downloadBytes, CreateDownloadStreamCallback createDownloadStreamFn, const Aws::String &targetFilePath="")

 

 ~TransferHandle ()

 

bool IsMultipart () const

 

void SetIsMultipart (bool value)

 

const Aws::String GetMultiPartId () const

 

void SetMultipartId (const Aws::String &value)

 

PartStateMap GetCompletedParts () const

 

void ChangePartToCompleted (const PartPointer &partState, const Aws::String &eTag)

 

PartStateMap GetPendingParts () const

 

bool HasPendingParts () const

 

void AddPendingPart (const PartPointer &partState)

 

PartStateMap GetQueuedParts () const

 

bool HasQueuedParts () const

 

void AddQueuedPart (const PartPointer &partState)

 

PartStateMap GetFailedParts () const

 

bool HasFailedParts () const

 

void ChangePartToFailed (const PartPointer &partState)

 

void GetAllPartsTransactional (PartStateMap &queuedParts, PartStateMap &pendingParts, PartStateMap &failedParts, PartStateMap &completedParts)

 

bool HasParts () const

 

bool ShouldContinue () const

 

void Cancel ()

 

void Restart ()

 

uint64_t GetBytesTransferred () const

 

void UpdateBytesTransferred (uint64_t amount)

 

uint64_t GetBytesOffset () const

 

uint64_t GetBytesTotalSize () const

 

void SetBytesTotalSize (uint64_t value)

 

uint64_t GetBytesAvailableFromStart () const

 

const Aws::String & GetBucketName () const

 

const Aws::String & GetKey () const

 

const Aws::String & GetTargetFilePath () const

 

const Aws::String GetVersionId () const

 

void SetVersionId (const Aws::String &versionId)

 

const Aws::String GetEtag () const

 

void SetEtag (const Aws::String &etag)

 

TransferDirection GetTransferDirection () const

 

const Aws::String GetContentType () const

 

void SetContentType (const Aws::String &value)

 

const Aws::Map< Aws::String, Aws::String > GetMetadata () const

 

void SetMetadata (const Aws::Map< Aws::String, Aws::String > &value)

 

void AddMetadataEntry (const Aws::String &key, const Aws::String &value)

 

void SetContext (const std::shared_ptr< const Aws::Client::AsyncCallerContext > &context)

 

std::shared_ptr< const Aws::Client::AsyncCallerContext > GetContext () const

 

TransferStatus GetStatus () const

 

void UpdateStatus (TransferStatus value)

 

const Aws::Client::AWSError< Aws::S3::S3Errors > GetLastError () const

 

void SetError (const Aws::Client::AWSError< Aws::S3::S3Errors > &error)

 

void WaitUntilFinished () const

 

const CreateDownloadStreamCallback & GetCreateDownloadStreamFunction () const

 

Aws::String WritePartToDownloadStream (Aws::IOStream *partStream, uint64_t writeOffset)

 

void ApplyDownloadConfiguration (const DownloadConfiguration &downloadConfig)

 

bool LockForCompletion ()

 

Aws::String GetId () const

 

Aws::String GetChecksum () const

 

void SetChecksum (const Aws::String &checksum)

 

Detailed Description

This is the interface for interacting with an in-process transfer. All operations from TransferManager return an instance of this class. In addition to the status of the transfer and details about what operation is being performed, this class also has the Cancel() operation which is used to cancel a transfer, and WaitUntilCompleted() which will cause the calling thread to block until the transfer is finished.

In the context that by the time you are using this class, it is thread safe.

Definition at line 132 of file TransferHandle.h.

Constructor & Destructor Documentation

TransferHandle() [1/4]

Aws::Transfer::TransferHandle::TransferHandle ( const Aws::String &  bucketName,

const Aws::String &  keyName,

uint64_t  totalSize,

const Aws::String &  targetFilePath = "" 

)

Initialize with required information for an UPLOAD

TransferHandle() [2/4]

Aws::Transfer::TransferHandle::TransferHandle ( const Aws::String &  bucketName,

const Aws::String &  keyName,

const Aws::String &  targetFilePath = "" 

)

Initialize with required information for a DOWNLOAD

TransferHandle() [3/4]

Aws::Transfer::TransferHandle::TransferHandle ( const Aws::String &  bucketName,

const Aws::String &  keyName,

CreateDownloadStreamCallback  createDownloadStreamFn,

const Aws::String &  targetFilePath = "" 

)

Alternate DOWNLOAD constructor

TransferHandle() [4/4]

Aws::Transfer::TransferHandle::TransferHandle ( const Aws::String &  bucketName,

const Aws::String &  keyName,

const uint64_t  fileOffset,

const uint64_t  downloadBytes,

CreateDownloadStreamCallback  createDownloadStreamFn,

const Aws::String &  targetFilePath = "" 

)

Alternate DOWNLOAD constructor

~TransferHandle()

Aws::Transfer::TransferHandle::~TransferHandle ( )

Member Function Documentation

AddMetadataEntry()

void Aws::Transfer::TransferHandle::AddMetadataEntry ( const Aws::String &  key,

const Aws::String &  value 

)

inline

Add a new entry to or update an existed entry of m_metadata, useful when users want to get ETag directly from metadata.

Definition at line 332 of file TransferHandle.h.

AddPendingPart()

void Aws::Transfer::TransferHandle::AddPendingPart ( const PartPointer &  partState)

Set a part to pending. Used for all transfers.

AddQueuedPart()

void Aws::Transfer::TransferHandle::AddQueuedPart ( const PartPointer &  partState)

Set a part to queued. Used for all transfers.

ApplyDownloadConfiguration()

void Aws::Transfer::TransferHandle::ApplyDownloadConfiguration ( const DownloadConfiguration &  downloadConfig)

Cancel()

void Aws::Transfer::TransferHandle::Cancel ( )

Cancel the transfer. This will happen asynchronously, so if you need to wait for it to be canceled, either handle the callbacks, or call WaitUntilFinished.

ChangePartToCompleted()

void Aws::Transfer::TransferHandle::ChangePartToCompleted ( const PartPointer &  partState,

const Aws::String &  eTag 

)

Set a pending part to completed along with its etag. Used fore all transfers.

ChangePartToFailed()

void Aws::Transfer::TransferHandle::ChangePartToFailed ( const PartPointer &  partState)

Set a pending part to failed. Used for all transfers.

GetAllPartsTransactional()

void Aws::Transfer::TransferHandle::GetAllPartsTransactional ( PartStateMap &  queuedParts,

PartStateMap &  pendingParts,

PartStateMap &  failedParts,

PartStateMap &  completedParts 

)

Get all parts using transactions, mostly for internal purposes.

GetBucketName()

const Aws::String & Aws::Transfer::TransferHandle::GetBucketName ( ) const

inline

Bucket portion of the object location in Amazon S3.

Definition at line 283 of file TransferHandle.h.

GetBytesAvailableFromStart()

uint64_t Aws::Transfer::TransferHandle::GetBytesAvailableFromStart ( ) const

inline

Gets the total bytes that is already transferred and available to users starting from the beginning of the file. For multiple-part downloads, it's guaranteed that these bytes are committed to the underlying stream already. For single-part downloads, it's also true since we write() directly to the underlying stream. A potential use case is to poll and stream bytes to users as we are still doing multi-part downloading.

Definition at line 278 of file TransferHandle.h.

GetBytesOffset()

uint64_t Aws::Transfer::TransferHandle::GetBytesOffset ( ) const

inline

The offset from which to start downloading

Definition at line 262 of file TransferHandle.h.

GetBytesTotalSize()

uint64_t Aws::Transfer::TransferHandle::GetBytesTotalSize ( ) const

inline

The calculated total size of the object being transferred.

Definition at line 266 of file TransferHandle.h.

GetBytesTransferred()

uint64_t Aws::Transfer::TransferHandle::GetBytesTransferred ( ) const

inline

Total bytes transferred successfully on this transfer operation. We implement transfer progress with two invariants: (1) Never lock; given a callback that can happen hundreds of times a second or more on a solid connection, it isn't acceptable to lock each time (2) Never go backwards, in spite of part upload/download failures. Negative progress (canceling a highly concurrent transfer can lead to an enormous step backwards if many parts are aborted at once) is a confusing and undesirable user experience. In this sense, progress represents a high-water mark, and in the presence of heavy failures or cancellation, it may appear to pause until the necessary retries exceed the previous high-water mark. The amount of bytes transferred is the amount of bytes sent by the http client. If the user input stream is adapted as it is with aws-chunked, there will be a larger amount of bytes transferred than the original object.

Definition at line 253 of file TransferHandle.h.

GetChecksum()

Aws::String Aws::Transfer::TransferHandle::GetChecksum ( ) const

inline

Definition at line 389 of file TransferHandle.h.

GetCompletedParts()

PartStateMap Aws::Transfer::TransferHandle::GetCompletedParts ( ) const

Returns a copy of the completed parts, in the structure of <partId, ETag>. Used for all transfers.

GetContentType()

const Aws::String Aws::Transfer::TransferHandle::GetContentType ( ) const

inline

Content type of the object being transferred

Definition at line 313 of file TransferHandle.h.

GetContext()

std::shared_ptr< const Aws::Client::AsyncCallerContext > Aws::Transfer::TransferHandle::GetContext ( ) const

inline

Returns arbitrary user context or nullptr if it's not set.

Definition at line 342 of file TransferHandle.h.

GetCreateDownloadStreamFunction()

const CreateDownloadStreamCallback & Aws::Transfer::TransferHandle::GetCreateDownloadStreamFunction ( ) const

inline

Definition at line 368 of file TransferHandle.h.

GetEtag()

const Aws::String Aws::Transfer::TransferHandle::GetEtag ( ) const

inline

(Download only) ETAG of the object to retrieve.

Definition at line 303 of file TransferHandle.h.

GetFailedParts()

PartStateMap Aws::Transfer::TransferHandle::GetFailedParts ( ) const

Returns a copy of the failed parts. Used for all transfers.

GetId()

Aws::String Aws::Transfer::TransferHandle::GetId ( ) const

GetKey()

const Aws::String & Aws::Transfer::TransferHandle::GetKey ( ) const

inline

Key of the object location in Amazon S3.

Definition at line 287 of file TransferHandle.h.

GetLastError()

const Aws::Client::AWSError< Aws::S3::S3Errors > Aws::Transfer::TransferHandle::GetLastError ( ) const

inline

The last error that was encountered by the transfer. You can handle each error individually via the errorCallback callback function in the TransferConfiguration.

Definition at line 357 of file TransferHandle.h.

GetMetadata()

const Aws::Map< Aws::String, Aws::String > Aws::Transfer::TransferHandle::GetMetadata ( ) const

inline

In case of an upload, this is the metadata that was placed on the object when it was uploaded. In the case of a download, this is the object metadata from the GetObject operation.

Definition at line 322 of file TransferHandle.h.

GetMultiPartId()

const Aws::String Aws::Transfer::TransferHandle::GetMultiPartId ( ) const

inline

If this is a multi-part transfer, this is the ID of it. e.g. UploadId for UploadPart

Definition at line 171 of file TransferHandle.h.

GetPendingParts()

PartStateMap Aws::Transfer::TransferHandle::GetPendingParts ( ) const

Returns a copy of the pending parts. Used for all transfers.

GetQueuedParts()

PartStateMap Aws::Transfer::TransferHandle::GetQueuedParts ( ) const

Returns a copy of the queued parts. Used for all transfers.

GetStatus()

TransferStatus Aws::Transfer::TransferHandle::GetStatus ( ) const

The current status of the operation

GetTargetFilePath()

const Aws::String & Aws::Transfer::TransferHandle::GetTargetFilePath ( ) const

inline

If known, this is the location of the local file being uploaded from, or downloaded to. If you use the stream api however, this will always be blank.

Definition at line 292 of file TransferHandle.h.

GetTransferDirection()

TransferDirection Aws::Transfer::TransferHandle::GetTransferDirection ( ) const

inline

Upload or Download?

Definition at line 309 of file TransferHandle.h.

GetVersionId()

const Aws::String Aws::Transfer::TransferHandle::GetVersionId ( ) const

inline

(Download only) version id of the object to retrieve; if not specified in constructor, then latest is used

Definition at line 297 of file TransferHandle.h.

HasFailedParts()

bool Aws::Transfer::TransferHandle::HasFailedParts ( ) const

Returns true or false if there are currently any failed parts.

HasParts()

bool Aws::Transfer::TransferHandle::HasParts ( ) const

Returns true or false if any parts have been created for this transfer

HasPendingParts()

bool Aws::Transfer::TransferHandle::HasPendingParts ( ) const

Returns true or false if there are currently any pending parts.

HasQueuedParts()

bool Aws::Transfer::TransferHandle::HasQueuedParts ( ) const

Returns true or false if there are currently any queued parts.

IsMultipart()

bool Aws::Transfer::TransferHandle::IsMultipart ( ) const

inline

Whether or not this transfer is being performed using parallel parts via a multi-part s3 api.

Definition at line 163 of file TransferHandle.h.

LockForCompletion()

bool Aws::Transfer::TransferHandle::LockForCompletion ( )

inline

Definition at line 378 of file TransferHandle.h.

Restart()

void Aws::Transfer::TransferHandle::Restart ( )

Reset the cancellation status for a retry. This will be done automatically by Transfer Manager.

SetBytesTotalSize()

void Aws::Transfer::TransferHandle::SetBytesTotalSize ( uint64_t  value)

inline

Sets the total size of the object being transferred.

Definition at line 270 of file TransferHandle.h.

SetChecksum()

void Aws::Transfer::TransferHandle::SetChecksum ( const Aws::String &  checksum)

inline

Definition at line 390 of file TransferHandle.h.

SetContentType()

void Aws::Transfer::TransferHandle::SetContentType ( const Aws::String &  value)

inline

Content type of the object being transferred

Definition at line 317 of file TransferHandle.h.

SetContext()

void Aws::Transfer::TransferHandle::SetContext ( const std::shared_ptr< const Aws::Client::AsyncCallerContext > &  context)

inline

Arbitrary user context that can be accessed from the callbacks

Definition at line 337 of file TransferHandle.h.

SetError()

void Aws::Transfer::TransferHandle::SetError ( const Aws::Client::AWSError< Aws::S3::S3Errors > &  error)

inline

The last error that was encountered by the transfer. You can handle each error individually via the errorCallback callback function in the TransferConfiguration.

Definition at line 362 of file TransferHandle.h.

SetEtag()

void Aws::Transfer::TransferHandle::SetEtag ( const Aws::String &  etag)

inline

Definition at line 304 of file TransferHandle.h.

SetIsMultipart()

void Aws::Transfer::TransferHandle::SetIsMultipart ( bool  value)

inline

Whether or not this transfer is being performed using parallel parts via a multi-part s3 api.

Definition at line 167 of file TransferHandle.h.

SetMetadata()

void Aws::Transfer::TransferHandle::SetMetadata ( const Aws::Map< Aws::String, Aws::String > &  value)

inline

In case of an upload, this is the metadata that was placed on the object when it was uploaded. In the case of a download, this is the object metadata from the GetObject operation.

Definition at line 327 of file TransferHandle.h.

SetMultipartId()

void Aws::Transfer::TransferHandle::SetMultipartId ( const Aws::String &  value)

inline

If this is a multi-part transfer, this is the ID of it. e.g. UploadId for UploadPart

Definition at line 175 of file TransferHandle.h.

SetVersionId()

void Aws::Transfer::TransferHandle::SetVersionId ( const Aws::String &  versionId)

inline

Definition at line 298 of file TransferHandle.h.

ShouldContinue()

bool Aws::Transfer::TransferHandle::ShouldContinue ( ) const

Returns false if Cancel has been called. Largely for internal use.

UpdateBytesTransferred()

void Aws::Transfer::TransferHandle::UpdateBytesTransferred ( uint64_t  amount)

inline

Total bytes transferred successfully on this transfer operation.

Definition at line 257 of file TransferHandle.h.

UpdateStatus()

void Aws::Transfer::TransferHandle::UpdateStatus ( TransferStatus  value)

The current status of the operation

WaitUntilFinished()

void Aws::Transfer::TransferHandle::WaitUntilFinished ( ) const

Blocks the calling thread until the operation has finished. This function does not busy wait. It is safe for your CPU.

WritePartToDownloadStream()

Aws::String Aws::Transfer::TransferHandle::WritePartToDownloadStream ( Aws::IOStream *  partStream,

uint64_t  writeOffset 

)

Write @partStream to the configured output (f)stream. Return empty string on success, string with error message on error.

---

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

• src/aws-cpp-sdk-transfer/include/aws/transfer/TransferHandle.h