AWSS3TransferUtility Class Reference

Inherits from AWSService : NSObject
Declared in AWSS3TransferUtility.h
AWSS3TransferUtility.m

Overview

A high-level utility for managing background uploads and downloads. The transfers continue even when the app is suspended. You must call + application:handleEventsForBackgroundURLSession:completionHandler: in the - application:handleEventsForBackgroundURLSession:completionHandler: application delegate in order for the background transfer callback to work.

  configuration

The service configuration used to instantiate this service client.

@property (readonly) AWSServiceConfiguration *configuration

Discussion

Warning: Once the client is instantiated, do not modify the configuration object. It may cause unspecified behaviors.

Declared In

AWSS3TransferUtility.h

+ defaultS3TransferUtility

Returns the singleton service client. If the singleton object does not exist, the SDK instantiates the default service client with defaultServiceConfiguration from [AWSServiceManager defaultServiceManager]. The reference to this object is maintained by the SDK, and you do not need to retain it manually.

+ (instancetype)defaultS3TransferUtility

Return Value

The default service client.

Discussion

For example, set the default service configuration in - application:didFinishLaunchingWithOptions:

Swift

 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
     let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
     let configuration = AWSServiceConfiguration(region: .USEast1, credentialsProvider: credentialProvider)
     AWSServiceManager.default().defaultServiceConfiguration = configuration

     return true
 }

Objective-C

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
                                                                                                      identityPoolId:@"YourIdentityPoolId"];
      AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1
                                                                           credentialsProvider:credentialsProvider];
      [AWSServiceManager defaultServiceManager].defaultServiceConfiguration = configuration;

      return YES;
  }

Then call the following to get the default service client:

Swift

 let S3TransferUtility = AWSS3TransferUtility.default()

Objective-C

 AWSS3TransferUtility *S3TransferUtility = [AWSS3TransferUtility defaultS3TransferUtility];

Declared In

AWSS3TransferUtility.h

+ registerS3TransferUtilityWithConfiguration:forKey:

Creates a service client with the given service configuration and registers it for the key.

+ (void)registerS3TransferUtilityWithConfiguration:(AWSServiceConfiguration *)configuration forKey:(NSString *)key

Parameters

configuration

A service configuration object.

key

A string to identify the service client.

Discussion

For example, set the default service configuration in - application:didFinishLaunchingWithOptions:

Swift

 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
     let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
     let configuration = AWSServiceConfiguration(region: .USWest2, credentialsProvider: credentialProvider)
     AWSS3TransferUtility.register(with: configuration!, forKey: "USWest2S3TransferUtility")

     return true
 }

Objective-C

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
                                                                                                     identityPoolId:@"YourIdentityPoolId"];
     AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSWest2
                                                                          credentialsProvider:credentialsProvider];

     [AWSS3TransferUtility registerS3TransferUtilityWithConfiguration:configuration forKey:@"USWest2S3TransferUtility"];

     return YES;
 }

Then call the following to get the service client:

Swift

 let S3TransferUtility = AWSS3TransferUtility(forKey: "USWest2S3TransferUtility")

Objective-C

 AWSS3TransferUtility *S3TransferUtility = [AWSS3TransferUtility S3TransferUtilityForKey:@"USWest2S3TransferUtility"];

Warning: After calling this method, do not modify the configuration object. It may cause unspecified behaviors.

Declared In

AWSS3TransferUtility.h

+ registerS3TransferUtilityWithConfiguration:transferUtilityConfiguration:forKey:

Creates a service client with the given service configuration and registers it for the key.

+ (void)registerS3TransferUtilityWithConfiguration:(AWSServiceConfiguration *)configuration transferUtilityConfiguration:(nullable AWSS3TransferUtilityConfiguration *)transferUtilityConfiguration forKey:(NSString *)key

Parameters

configuration

A service configuration object.

transferUtilityConfiguration

An S3 transfer utility configuration object.

key

A string to identify the service client.

Discussion

For example, set the default service configuration in - application:didFinishLaunchingWithOptions:

Swift

 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
     let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
     let configuration = AWSServiceConfiguration(region: .USWest2, credentialsProvider: credentialProvider)
     AWSS3TransferUtility.register(with: configuration!, transferUtilityConfiguration: nil, forKey: "USWest2S3TransferUtility")

     return true
 }

Objective-C

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
                                                                                                     identityPoolId:@"YourIdentityPoolId"];
     AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSWest2
                                                                          credentialsProvider:credentialsProvider];

     [AWSS3TransferUtility registerS3TransferUtilityWithConfiguration:configuration transferUtilityConfiguration:nil forKey:@"USWest2S3TransferUtility"];

     return YES;
 }

Then call the following to get the service client:

Swift

 let S3TransferUtility = AWSS3TransferUtility(forKey: "USWest2S3TransferUtility")

Objective-C

 AWSS3TransferUtility *S3TransferUtility = [AWSS3TransferUtility S3TransferUtilityForKey:@"USWest2S3TransferUtility"];

Warning: After calling this method, do not modify the configuration object. It may cause unspecified behaviors.

Declared In

AWSS3TransferUtility.h

+ S3TransferUtilityForKey:

Retrieves the service client associated with the key. You need to call + registerS3TransferUtilityWithConfiguration:forKey: before invoking this method.

+ (instancetype)S3TransferUtilityForKey:(NSString *)key

Parameters

key

A string to identify the service client.

Return Value

An instance of the service client.

Discussion

For example, set the default service configuration in - application:didFinishLaunchingWithOptions:

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     AWSCognitoCredentialsProvider *credentialsProvider = [AWSCognitoCredentialsProvider credentialsWithRegionType:AWSRegionUSEast1 identityPoolId:@"YourIdentityPoolId"];
     AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSWest2 credentialsProvider:credentialsProvider];

     [AWSS3TransferUtility registerS3TransferUtilityWithConfiguration:configuration forKey:@"USWest2S3TransferUtility"];

     return YES;
 }

Then call the following to get the service client:

 AWSS3TransferUtility *S3TransferUtility = [AWSS3TransferUtility S3ForKey:@"USWest2S3TransferUtility"];

Declared In

AWSS3TransferUtility.h

+ removeS3TransferUtilityForKey:

Removes the service client associated with the key and release it.

+ (void)removeS3TransferUtilityForKey:(NSString *)key

Parameters

key

A string to identify the service client.

Discussion

The underlying NSURLSession is invalidated, and after the invalidation has completed the transfer is utility removed.

Observe the AWSS3TransferUtilityURLSessionDidBecomeInvalidNotification to be informed when this has occurred.

Warning: Before calling this method, make sure no method is running on this client.

Declared In

AWSS3TransferUtility.h

+ interceptApplication:handleEventsForBackgroundURLSession:completionHandler:

Tells AWSS3TransferUtility that events related to a URL session are waiting to be processed. This method needs to be called in the - application:handleEventsForBackgroundURLSession:completionHandler: applicatoin delegate for AWSS3TransferUtility to work.

+ (void)interceptApplication:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void ( ^ ) ( ))completionHandler

Parameters

application

The singleton app object.

identifier

The identifier of the URL session requiring attention.

completionHandler

The completion handler to call when you finish processing the events.

Declared In

AWSS3TransferUtility.h

– uploadData:key:contentType:expression:completionHandler:

Saves the NSData to a temporary directory and uploads it to the configured Amazon S3 bucket in AWSS3TransferUtilityConfiguration.

- (AWSTask<AWSS3TransferUtilityUploadTask*> *)uploadData:(NSData *)data key:(NSString *)key contentType:(NSString *)contentType expression:(nullable AWSS3TransferUtilityUploadExpression *)expression completionHandler:(nullable AWSS3TransferUtilityUploadCompletionHandlerBlock)completionHandler

Parameters

data

The data to upload.

key

The Amazon S3 object key name.

contentType

Content-Type of the data.

expression

The container object to configure the upload request.

completionHandler

The completion handler when the upload completes.

Return Value

Returns an instance of AWSTask. On successful initialization, task.result contains an instance of AWSS3TransferUtilityUploadTask.

Declared In

AWSS3TransferUtility.h

– uploadData:bucket:key:contentType:expression:completionHandler:

Saves the NSData to a temporary directory and uploads it to the specified Amazon S3 bucket.

- (AWSTask<AWSS3TransferUtilityUploadTask*> *)uploadData:(NSData *)data bucket:(NSString *)bucket key:(NSString *)key contentType:(NSString *)contentType expression:(nullable AWSS3TransferUtilityUploadExpression *)expression completionHandler:(nullable AWSS3TransferUtilityUploadCompletionHandlerBlock)completionHandler

Parameters

data

The data to upload.

bucket

The Amazon S3 bucket name.

key

The Amazon S3 object key name.

contentType

Content-Type of the data.

expression

The container object to configure the upload request.

completionHandler

The completion handler when the upload completes.

Return Value

Returns an instance of AWSTask. On successful initialization, task.result contains an instance of AWSS3TransferUtilityUploadTask.

Declared In

AWSS3TransferUtility.h

– uploadFile:key:contentType:expression:completionHandler:

Uploads the file to the configured Amazon S3 bucket in AWSS3TransferUtilityConfiguration.

- (AWSTask<AWSS3TransferUtilityUploadTask*> *)uploadFile:(NSURL *)fileURL key:(NSString *)key contentType:(NSString *)contentType expression:(nullable AWSS3TransferUtilityUploadExpression *)expression completionHandler:(nullable AWSS3TransferUtilityUploadCompletionHandlerBlock)completionHandler

Parameters

fileURL

The file URL of the file to upload.

key

The Amazon S3 object key name.

contentType

Content-Type of the file.

expression

The container object to configure the upload request.

completionHandler

The completion handler when the upload completes.

Return Value

Returns an instance of AWSTask. On successful initialization, task.result contains an instance of AWSS3TransferUtilityUploadTask.

Declared In

AWSS3TransferUtility.h

– uploadFile:bucket:key:contentType:expression:completionHandler:

Uploads the file to the specified Amazon S3 bucket.

- (AWSTask<AWSS3TransferUtilityUploadTask*> *)uploadFile:(NSURL *)fileURL bucket:(NSString *)bucket key:(NSString *)key contentType:(NSString *)contentType expression:(nullable AWSS3TransferUtilityUploadExpression *)expression completionHandler:(nullable AWSS3TransferUtilityUploadCompletionHandlerBlock)completionHandler

Parameters

fileURL

The file URL of the file to upload.

bucket

The Amazon S3 bucket name.

key

The Amazon S3 object key name.

contentType

Content-Type of the file.

expression

The container object to configure the upload request.

completionHandler

The completion handler when the upload completes.

Return Value

Returns an instance of AWSTask. On successful initialization, task.result contains an instance of AWSS3TransferUtilityUploadTask.

Declared In

AWSS3TransferUtility.h

– downloadDataForKey:expression:completionHandler:

Downloads the specified Amazon S3 object as NSData from the bucket configured in AWSS3TransferUtilityConfiguration.

- (AWSTask<AWSS3TransferUtilityDownloadTask*> *)downloadDataForKey:(NSString *)key expression:(nullable AWSS3TransferUtilityDownloadExpression *)expression completionHandler:(nullable AWSS3TransferUtilityDownloadCompletionHandlerBlock)completionHandler

Parameters

key

The Amazon S3 object key name.

expression

The container object to configure the download request.

completionHandler

The completion handler when the download completes.

Return Value

Returns an instance of AWSTask. On successful initialization, task.result contains an instance of AWSS3TransferUtilityDownloadTask.

Declared In

AWSS3TransferUtility.h

– downloadDataFromBucket:key:expression:completionHandler:

Downloads the specified Amazon S3 object as NSData.

- (AWSTask<AWSS3TransferUtilityDownloadTask*> *)downloadDataFromBucket:(NSString *)bucket key:(NSString *)key expression:(nullable AWSS3TransferUtilityDownloadExpression *)expression completionHandler:(nullable AWSS3TransferUtilityDownloadCompletionHandlerBlock)completionHandler

Parameters

bucket

The Amazon S3 bucket name.

key

The Amazon S3 object key name.

expression

The container object to configure the download request.

completionHandler

The completion handler when the download completes.

Return Value

Returns an instance of AWSTask. On successful initialization, task.result contains an instance of AWSS3TransferUtilityDownloadTask.

Declared In

AWSS3TransferUtility.h

– downloadToURL:key:expression:completionHandler:

Downloads the specified Amazon S3 object to a file URL from the bucket configured in AWSS3TransferUtilityConfiguration.

- (AWSTask<AWSS3TransferUtilityDownloadTask*> *)downloadToURL:(NSURL *)fileURL key:(NSString *)key expression:(nullable AWSS3TransferUtilityDownloadExpression *)expression completionHandler:(nullable AWSS3TransferUtilityDownloadCompletionHandlerBlock)completionHandler

Parameters

fileURL

The file URL to download the object to.

key

The Amazon S3 object key name.

expression

The container object to configure the download request.

completionHandler

The completion handler when the download completes.

Return Value

Returns an instance of AWSTask. On successful initialization, task.result contains an instance of AWSS3TransferUtilityDownloadTask.

Declared In

AWSS3TransferUtility.h

– downloadToURL:bucket:key:expression:completionHandler:

Downloads the specified Amazon S3 object to a file URL.

- (AWSTask<AWSS3TransferUtilityDownloadTask*> *)downloadToURL:(NSURL *)fileURL bucket:(NSString *)bucket key:(NSString *)key expression:(nullable AWSS3TransferUtilityDownloadExpression *)expression completionHandler:(nullable AWSS3TransferUtilityDownloadCompletionHandlerBlock)completionHandler

Parameters

fileURL

The file URL to download the object to.

bucket

The Amazon S3 bucket name.

key

The Amazon S3 object key name.

expression

The container object to configure the download request.

completionHandler

The completion handler when the download completes.

Return Value

Returns an instance of AWSTask. On successful initialization, task.result contains an instance of AWSS3TransferUtilityDownloadTask.

Declared In

AWSS3TransferUtility.h

– enumerateToAssignBlocksForUploadTask:downloadTask:

Assigns progress feedback and completion handler blocks. This method should be called when the app was suspended while the transfer is still happening.

- (void)enumerateToAssignBlocksForUploadTask:(nullable void ( ^ ) ( AWSS3TransferUtilityUploadTask *uploadTask , _Nullable AWSS3TransferUtilityProgressBlock *_Nullable uploadProgressBlockReference , _Nullable AWSS3TransferUtilityUploadCompletionHandlerBlock *_Nullable completionHandlerReference ))uploadBlocksAssigner downloadTask:(nullable void ( ^ ) ( AWSS3TransferUtilityDownloadTask *downloadTask , _Nullable AWSS3TransferUtilityProgressBlock *_Nullable downloadProgressBlockReference , _Nullable AWSS3TransferUtilityDownloadCompletionHandlerBlock *_Nullable completionHandlerReference ))downloadBlocksAssigner

Parameters

uploadBlocksAssigner

The block for assigning the upload pregree feedback and completion handler blocks.

downloadBlocksAssigner

The block for assigning the download pregree feedback and completion handler blocks.

Declared In

AWSS3TransferUtility.h

– getAllTasks

Retrieves all running tasks.

- (AWSTask<NSArray<__kindofAWSS3TransferUtilityTask*> *> *)getAllTasks

Return Value

An array of AWSS3TransferUtilityTask.

Declared In

AWSS3TransferUtility.h

– getUploadTasks

Retrieves all running upload tasks.

- (AWSTask<NSArray<AWSS3TransferUtilityUploadTask*> *> *)getUploadTasks

Return Value

An array of AWSS3TransferUtilityUploadTask.

Declared In

AWSS3TransferUtility.h

– getDownloadTasks

Retrieves all running download tasks.

- (AWSTask<NSArray<AWSS3TransferUtilityDownloadTask*> *> *)getDownloadTasks

Return Value

An array of AWSS3TransferUtilityDownloadTask.

Declared In

AWSS3TransferUtility.h