Download, Pause and Resume with the S3TransferManager for iOS

The S3TransferManager class in the AWS SDK for iOS 1.7.0 makes it easier for developers to transfer files to and from Amazon Simple Storage Service (S3). S3TransferManager has been updated to v2 and now supports new features, including:

• Pause and resume transfers
• Asynchronous and synchronous downloads
• Cancel transfers

This blog post provides an overview of the new features in S3TransferManager, discusses some limitations, and provides a link to a sample app.

Tip: If you aren’t familiar with setting up and configuring S3TransferManager, check out the Configuring S3TransferManager section of our previous blog post, which shows how to set up a delegate class to keep track of transfer progress.

Pause and Resume Transfers

S3TransferManager introduces a public facing operation class named S3TransferOperation, which is a subclass of NSOperation and conforms to the AmazonServiceRequestDelegate protocol. Asynchronous upload and download methods return S3TransferOperation objects, which can be used to pause or cancel a single operation.

Pause All Transfer Operations

The following example shows how to pause all transfer operations.

AmazonS3Client *s3 = [[AmazonS3Client alloc] initWithAccessKey:ACCESS_KEY withSecretKey:SECRET_KEY];
S3TransferManager *transferManager = [S3TransferManager new];
transferManager.s3 = s3;

// create upload and/or download requests
.
.
.
[transferManager pauseAllTransfers];

Pause a Single Operation

If you want to pause a single operation, then you will need a handle to the S3TransferOperation object. The following example shows how to pause an upload operation, assuming you stored the upload operation in a variable named uploadOperation.

[transferManager pause:uploadOperation];

Note: One thing to keep in mind is that any upload less than 5 MB will be restarted from the beginning when resumed.

Resume All Transfers

S3TransferManager provides the resumeAllTransfers method to resume paused transfers. This method takes a delegate object as an argument, which can be used to keep track of the transfer progress.

Resume a Single Operation

If you want to resume a single operation, then you will need a handle to the S3TransferOperation object. The following example shows how to resume an operation, assuming you stored the S3TransferOperation object in a variable named operation.

operation = [transferManager resume:operation requestDelegate:self];

Downloads

S3TransferManager provides support for asynchronous and synchronous downloads.

Asynchronous Download

The following example shows how to download a file asynchronously.

[transferManager downloadFile: FILEPATH_WHERE_DOWNLOADING_OBJECT bucket:BUCKET_NAME key:OBJECT_KEY];

Synchronous Download

The following example shows how to download a file synchronously.

[transferManager synchronouslyDownloadFile: FILEPATH_WHERE_DOWNLOADING_OBJECT bucket:BUCKET_NAME key:OBJECT_KEY];

Cancel Transfers

Transfers can be cancelled using the S3TransferOperation object or the request’s bucket and key. You can also simply cancel all transfers.

Cancel Using S3TransferOperation

If you store S3TransferOperation objects when asynchronous upload or download methods return, then you can simply call the cancel method on the S3TransferOperation object.

Cancel Using Bucket and Key

The following example shows how to cancel a download transfer based on the bucket name and object key.

[transferManager downloadFile: FILEPATH_WHERE_DOWNLOADING_OBJECT bucket:BUCKET_NAME key:OBJECT_KEY];
.
.
// cancel transfer for a specific bucket and key
for (S3TransferOperation *op in transferManager.operationQueue.operations) {
    // cancel get request
    if ([BUCKET_NAME isEqualToString:op.getRequest.bucket] && [OBJECT_KEY isEqualToString:op.getRequest.key]) {
        [op cancel];
    }
}

Cancel All Transfer Operations

To cancel all transfers, simply call cancelAllTransfers on the S3TransferManager object.

Limitations

There are some important limitations to keep in mind when using the new features of S3TransferManager:

• For uploads, pause and resume only work if you use the uploadFile method or specify the file name on the putObjectRequest. They will not work if you use the NSData or NSInputStream uploads. If all you have is NSData or NSInputStream, it is recommended to write the content to a temporary file first to take advantage of pause and resume.
• For downloads, you must specify the targetFilePath on the getObjectRequest or use the downloadFile method. Pause and resume will not work if you use an NSOutputStream.
• Resuming uploads will start from the beginning if the file you are uploading is less than 5 MB. Resuming uploads will start from the last successfully uploaded 5 MB part if the file is greater than 5 MB.
• Pause and resume stores a metadata file in the /tmp directory for your app. If iOS cleans up that file, you will not be able to resume. Usually this means you won’t be able to resume files if you pause for more than 3 days.
• Integrity checks are done when downloading files that weren’t uploaded using multipart uploads. By default, S3TransferManager uses multipart uploads for files >5MB.

Sample App

We’ve created a sample app that demonstrates the pause and resume features of S3TransferManager. It provides a good starting place to familiarize yourself with some of the functionality in S3TransferManager.

I hope this post helps you get started with these new features in S3TransferManager. If you have any questions regarding S3TransferManager, please leave a comment below!

If you like building mobile apps that use cloud services that our customers use on a daily basis, perhaps you would like to join the AWS Mobile SDK and Tools team. We are hiring Software Developers, Web Developers, and Product Managers.