YouQi/Pods/AliyunOSSiOS/AliyunOSSSDK/OSSClient.h

//
//  OSSClient.h
//  oss_ios_sdk
//
//  Created by zhouzhuo on 8/16/15.
//  Copyright (c) 2015 aliyun.com. All rights reserved.
//

#import <Foundation/Foundation.h>
@class OSSGetServiceRequest;
@class OSSCreateBucketRequest;
@class OSSDeleteBucketRequest;
@class OSSHeadObjectRequest;
@class OSSGetBucketRequest;
@class OSSGetBucketACLRequest;
@class OSSGetObjectRequest;
@class OSSGetObjectACLRequest;
@class OSSPutObjectRequest;
@class OSSPutObjectACLRequest;
@class OSSDeleteObjectRequest;
@class OSSDeleteMultipleObjectsRequest;
@class OSSCopyObjectRequest;
@class OSSInitMultipartUploadRequest;
@class OSSUploadPartRequest;
@class OSSCompleteMultipartUploadRequest;
@class OSSListPartsRequest;
@class OSSListMultipartUploadsRequest;
@class OSSAbortMultipartUploadRequest;
@class OSSAppendObjectRequest;
@class OSSResumableUploadRequest;
@class OSSMultipartUploadRequest;
@class OSSCallBackRequest;
@class OSSImagePersistRequest;
@class OSSGetBucketInfoRequest;
@class OSSPutSymlinkRequest;
@class OSSGetSymlinkRequest;
@class OSSRestoreObjectRequest;

@class OSSTask;
@class OSSExecutor;
@class OSSNetworking;
@class OSSClientConfiguration;
@protocol OSSCredentialProvider;

NS_ASSUME_NONNULL_BEGIN

/**
 OSSClient is the entry class to access OSS in an iOS client. It provides all the methods to communicate with OSS.
 Generally speaking, only one instance of OSSClient is needed in the whole app.
 */
@interface OSSClient : NSObject

/**
 OSS endpoint. It varies in different regions. Please check out OSS official website for the exact endpoints for your data.
 */
@property (nonatomic, strong) NSString * endpoint;

/**
 The networking instance for sending and receiving data
 */
@property (nonatomic, strong) OSSNetworking * networking;

/**
 The credential provider instance
 */
@property (nonatomic, strong) id<OSSCredentialProvider> credentialProvider;

/**
 Client configuration instance
 */
@property (nonatomic, strong) OSSClientConfiguration * clientConfiguration;

/**
 oss operation task queue
 */
@property (nonatomic, strong, readonly) OSSExecutor * ossOperationExecutor;

/**
 Initializes an OSSClient instance with the default client configuration.
 @endpoint it specifies domain of the bucket's region. Starting 2017, the domain must be prefixed with "https://" to follow Apple's ATS policy.
             For example: "https://oss-cn-hangzhou.aliyuncs.com"
 @credentialProvider The credential provider
 */
- (instancetype)initWithEndpoint:(NSString *)endpoint
              credentialProvider:(id<OSSCredentialProvider>) credentialProvider;

/**
 Initializes an OSSClient with the custom client configuration.
 @endpoint it specifies domain of the bucket's region. Starting 2017, the domain must be prefixed with "https://" to follow Apple's ATS policy.
             For example: "https://oss-cn-hangzhou.aliyuncs.com"
 @credentialProvider The credential provider
 @conf The custom client configuration such as retry time, timeout values, etc.
 */
- (instancetype)initWithEndpoint:(NSString *)endpoint
              credentialProvider:(id<OSSCredentialProvider>)credentialProvider
             clientConfiguration:(OSSClientConfiguration *)conf;

#pragma mark restful-api

/**
 The corresponding RESTFul API: GetService
 Gets all the buckets of the current user
 Notes：
 1. STS is not supported yet in this call.
 2. When all buckets are returned, the xml in response body does not have nodes of Prefix, Marker, MaxKeys, IsTruncated and NextMarker.
    If there're remaining buckets to return, the xml will have these nodes. The nextMarker is the value of marker in the next call.
 */
- (OSSTask *)getService:(OSSGetServiceRequest *)request;

@end


@interface OSSClient (Bucket)

/**
 The corresponding RESTFul API: PutBucket
 Creates a bucket--it does not support anonymous access. By default, the datacenter used is oss-cn-hangzhou.
 Callers could explicitly specify the datacenter for the bucket to optimize the performance and cost or meet the regulation requirement.
 Notes:
 1. STS is not supported yet.
 */
- (OSSTask *)createBucket:(OSSCreateBucketRequest *)request;

/**
 The corresponding RESTFul API: DeleteBucket
 Deletes a bucket.
 */
- (OSSTask *)deleteBucket:(OSSDeleteBucketRequest *)request;

/**
 The corresponding RESTFul API: GetBucket
 Lists all objects in a bucket. It could be specified with filters such as prefix, marker, delimeter and max-keys.
 */
- (OSSTask *)getBucket:(OSSGetBucketRequest *)request;

/**
 The corresponding RESTFul API: GetBucketInfo
 Gets the {@link Bucket}'s basic information as well as its ACL.
 */
- (OSSTask *)getBucketInfo:(OSSGetBucketInfoRequest *)request;

/**
 The corresponding RESTFul API: GetBucketACL
 Gets the bucket ACL.
 */
- (OSSTask *)getBucketACL:(OSSGetBucketACLRequest *)request;

@end


@interface OSSClient (Object)

/**
 The corresponding RESTFul API: HeadObject
 Gets the object's metadata information. The object's content is not returned.
 */
- (OSSTask *)headObject:(OSSHeadObjectRequest *)request;

/**
 The corresponding RESTFul API: GetObject
 Gets the whole object (includes content). It requires caller have read permission on the object.
 */
- (OSSTask *)getObject:(OSSGetObjectRequest *)request;

/**
 The corresponding RESTFul API: GetObjectACL
 get the acl of an object.
 */
- (OSSTask *)getObjectACL:(OSSGetObjectACLRequest *)request;

/**
 The corresponding RESTFul API: PutObject
 Uploads a file.
 */
- (OSSTask *)putObject:(OSSPutObjectRequest *)request;

/**
 Sets the object's ACL. Right now an object has three access permissions: private, public-ready, public-read-write.
 The operation specifies the x-oss-object-acl header in the put request. The caller must be the owner of the object.
 If succeeds, it returns HTTP status 200; otherwise it returns related error code and error messages.
 */
- (OSSTask *)putObjectACL:(OSSPutObjectACLRequest *)request;

/**
 The corresponding RESTFul API: AppendObject
 Appends data to an existing or non-existing object. The object created by this operation is appendable.
 As a comparison, the object created by Put Object is normal (non-appendable).
 */
- (OSSTask *)appendObject:(OSSAppendObjectRequest *)request;

/**
 *  @brief      Appends data to an existing or non-existing object on the OSS server.
 *              The object created by this operation is appendable.
 *  @request    request
 *  @crc64ecma  crc64ecma
 *             if object has been stored on OSS server, you need to invoke headObject
 *             api get object's crc64ecma,then use this api to append data to the
 *             object.
 */
- (OSSTask *)appendObject:(OSSAppendObjectRequest *)request withCrc64ecma:(nullable NSString *)crc64ecma;

/**
 The corresponding RESTFul API: copyObject
 Copies an existing object to another one.The operation sends a PUT request with x-oss-copy-source header to specify the source object.
 OSS server side will detect and copy the object. If it succeeds, the new object's metadata information will be returned.
 The operation applies for files less than 1GB. For big files, use UploadPartCopy RESTFul API.
 */
- (OSSTask *)copyObject:(OSSCopyObjectRequest *)request;

/**
 * Batch deletes the specified files under a specific bucket. If the files
 * are non-exist, the operation will still return successful.
 *
 * @param request
 *            A OSSDeleteMultipleObjectsRequest instance which specifies the
 *            bucket and file keys to delete.
 * @return A OSSTask with result of OSSDeleteMultipleObjectsResult instance which specifies each
 *         file's result in normal mode or only failed deletions in quite
 *         mode. By default it's quite mode.
 */
- (OSSTask *)deleteMultipleObjects:(OSSDeleteMultipleObjectsRequest *)request;

/**
 The corresponding RESTFul API: DeleteObject
 Deletes an object
 */
- (OSSTask *)deleteObject:(OSSDeleteObjectRequest *)request;

/**
 * Creates a symbol link to a target file under the bucket---this is not
 * supported for archive class bucket.
 *
 * @param request
 *            A OSSPutSymlinkRequest instance that specifies the
 *            bucket name, symlink name.
 * @return An instance of OSSTask. On successful execution, `task.result` will
 *         contain an instance of `OSSPutSymlinkResult`,otherwise will contain
 *         an instance of NSError.
 *
 * for more information,please refer to https://help.aliyun.com/document_detail/45126.html
 */
- (OSSTask *)putSymlink:(OSSPutSymlinkRequest *)request;

/**
 * Gets the symlink information for the given symlink name.
 *
 * @param request
 *            A OSSGetSymlinkRequest instance which specifies the bucket
 *            name and symlink name.
 * @return An instance of OSSTask. On successful execution, `task.result` will
 *         contain an instance of `OSSGetSymlinkResult`,otherwise will contain
 *         an instance of NSError.
 *
 * for more information,please refer to https://help.aliyun.com/document_detail/45146.html
 */
- (OSSTask *)getSymlink:(OSSGetSymlinkRequest *)request;

/**
 * Restores the object of archive storage. The function is not applicable to
 * Normal or IA storage. The restoreObject() needs to be called prior to
 * calling getObject() on an archive object.
 *
 * @param request
 *          A container for the necessary parameters to execute the RestoreObject
 *          service method.
 *
 * @return An instance of OSSTask. On successful execution, `task.result` will
 *         contain an instance of `OSSRestoreObjectResult`,otherwise will contain
 *         an instance of NSError.
 *
 * for more information,please refer to https://help.aliyun.com/document_detail/52930.html
 */
- (OSSTask *)restoreObject:(OSSRestoreObjectRequest *)request;

@end

@interface OSSClient (MultipartUpload)

/**
 The corresponding RESTFul API: InitiateMultipartUpload
 Initiates a multipart upload to get a upload Id. It's needed before starting uploading parts data.
 The upload Id is used for subsequential operations such as aborting the upload, querying the uploaded parts, etc.
 */
- (OSSTask *)multipartUploadInit:(OSSInitMultipartUploadRequest *)request;

/**
 The corresponding RESTFul API: UploadPart
 After the multipart upload is initiated, this API could be called to upload the data to the target file with the upload Id.
 Every uploaded part has a unique id called part number, which ranges from 1 to 10,000.
 For a given upload Id, the part number identifies the specific range of the data in the whole file.
 If the same part number is used for another upload, the existing data will be overwritten by the new upload.
 Except the last part, all other part's minimal size is 100KB.
 But no minimal size requirement on the last part.
 */
- (OSSTask *)uploadPart:(OSSUploadPartRequest *)request;

/**
 The corresponding RESTFul API: CompleteMultipartUpload
 This API is to complete the multipart upload after all parts data have been uploaded.
 It must be provided with a valid part list (each part has the part number and ETag).
 OSS will validate every part and then complete the multipart upload.
 If any part is invalid (e.g. the part is updated by another part upload), this API will fail.
 */
- (OSSTask *)completeMultipartUpload:(OSSCompleteMultipartUploadRequest *)request;

/**
 The corresponding RESTFul API: ListParts
 Lists all uploaded parts of the specified upload id.
 */
- (OSSTask *)listParts:(OSSListPartsRequest *)request;

/**
 The corresponding RESTFul API: ListMultipartUploads
 Lists all multipart uploads with the specified bucket.
 */
- (OSSTask *)listMultipartUploads:(OSSListMultipartUploadsRequest *)request;

/**
 The corresponding RESTFul API: AbortMultipartUpload
 Aborts the multipart upload by the specified upload Id.
 Once the multipart upload is aborted by this API, all parts data will be deleted and the upload Id is invalid anymore.
 */
- (OSSTask *)abortMultipartUpload:(OSSAbortMultipartUploadRequest *)request;

- (OSSTask *)abortResumableMultipartUpload:(OSSResumableUploadRequest *)request;

/**
 Multipart upload API
 */
- (OSSTask *)multipartUpload:(OSSMultipartUploadRequest *)request;
/**
 TODOTODO
 Resumable upload API
 This API wraps the multipart upload and also enables resuming upload by reading/writing  the checkpoint data.
 For a new file, multipartUploadInit() needs to be called first to get the upload Id. Then use this upload id to call this API to upload the data.
 If the upload fails, checks the error messages:
 If it's a recoverable error, then call this API again with the same upload Id to retry. The uploaded data will not be uploaded again.
 Otherwise then you may need to recreates a new upload Id and call this method again.
 Check out demo for the detail.
 */
- (OSSTask *)resumableUpload:(OSSResumableUploadRequest *)request;

/**
 * multipart upload sequentially in order,support resume upload
 */
- (OSSTask *)sequentialMultipartUpload:(OSSResumableUploadRequest *)request;

@end


@interface OSSClient (PresignURL)

/**
 Generates a signed URL for the object and anyone has this URL will get the GET permission on the object.
 @bucketName object's bucket name
 @objectKey Object name
 @interval Expiration time in seconds. The URL could be specified with the expiration time to limit the access window on the object.
 */
- (OSSTask *)presignConstrainURLWithBucketName:(NSString *)bucketName
                                 withObjectKey:(NSString *)objectKey
                        withExpirationInterval:(NSTimeInterval)interval;

/**
 Generates a signed URL for the object and anyone has this URL will get the specified permission on the object.
 @bucketName object's bucket name
 @objectKey Object name
 @interval Expiration time in seconds. The URL could be specified with the expiration time to limit the access window on the object.
 @parameter it could specify allowed HTTP methods
 */
- (OSSTask *)presignConstrainURLWithBucketName:(NSString *)bucketName
                                 withObjectKey:(NSString *)objectKey
                        withExpirationInterval:(NSTimeInterval)interval
                                withParameters:(NSDictionary *)parameters;

/**
 Generates a signed URL for the object and anyone has this URL will get the specified permission on the object. currently only support get and head method.
 @bucketName object's bucket name
 @objectKey Object name
 @httpMethod http method.currently only support get and head.
 @interval Expiration time in seconds. The URL could be specified with the expiration time to limit the access window on the object.
 @parameter it could specify allowed HTTP methods
 */
- (OSSTask *)presignConstrainURLWithBucketName:(NSString *)bucketName
                                 withObjectKey:(NSString *)objectKey
                                    httpMethod:(NSString *)method
                        withExpirationInterval:(NSTimeInterval)interval
                                withParameters:(NSDictionary *)parameters;

/**
 If the object's ACL is public read or public read-write, use this API to generate a signed url for sharing.
 @bucketName Object's bucket name
 @objectKey Object name
 */
- (OSSTask *)presignPublicURLWithBucketName:(NSString *)bucketName
                              withObjectKey:(NSString *)objectKey;

/** TODOTODO
 If the object's ACL is public read or public read-write, use this API to generate a signed url for sharing.
 @bucketName Object's bucket name
 @objectKey Object name
 @parameter the request parameters.
 */
- (OSSTask *)presignPublicURLWithBucketName:(NSString *)bucketName
                              withObjectKey:(NSString *)objectKey
                             withParameters:(NSDictionary *)parameters;

@end


@interface OSSClient (ImageService)

/*
 * image persist action
 * https://help.aliyun.com/document_detail/55811.html
 */
- (OSSTask *)imageActionPersist:(OSSImagePersistRequest *)request;

@end


@interface OSSClient (Utilities)

/**
 Checks if the object exists
 @bucketName Object's bucket name
 @objectKey Object name
 
 return YES                     Object exists
 return NO && *error = nil      Object does not exist
 return NO && *error != nil     Error occured.
 */
- (BOOL)doesObjectExistInBucket:(NSString *)bucketName
                      objectKey:(NSString *)objectKey
                          error:(const NSError **)error;

@end


@interface OSSClient (Callback)

- (OSSTask *)triggerCallBack:(OSSCallBackRequest *)request;

@end

NS_ASSUME_NONNULL_END