API Documentation

Last updated: 2019-06-21 15:35:17
The documentation is not available now.

    The API documentation contains a detailed API list and usage examples, which are written for those who completed initialization. It is recommended to use Command+F to find the API, check its description, and apply in your project.

    If you need more features, or do not understand what the returned parameters mean, you are advised to view the comments in the code using three finger drag, Force-touch, or hovering over the variable and pressing Control+Command+D.

    Best Practices of Common Operations

    This section describes the best practices of some common operations, which are available after you complete the initialization according to Getting Started.

    Upload a file

    See the Upload a file section in Getting Started.

    Resume upload from breakpoint

    Multipart upload is used to upload a file larger than 1 MB. That is, split the file into multiple parts with each holding a size of 1 MB, and then upload these parts (4 at most) in parallel. Resuming upload from breakpoint is implemented on the basis that the uploaded parts are stored in the backend server.

    During multipart upload, resumeData for resuming upload is generated after you initialize multipart upload or cancel the upload. This is used to generate another upload request for resuming upload. The following example shows how to get ResumeData:

    QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
    //···Set some parameters for upload
    put.initMultipleUploadFinishBlock = ^(QCloudInitiateMultipartUploadResult * multipleUploadInitResult, QCloudCOSXMLUploadObjectResumeData resumeData) {
        //Call back the block after you initialize multipart upload, in which you can obtain resumeData for generating a multipart upload request
        QCloudCOSXMLUploadObjectRequest* request = [QCloudCOSXMLUploadObjectRequest requestWithRequestData:resumeData];
    };
    
    [[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];
    
    //···When initialization is completed and upload is not completed
    NSError* error;
    //The following shows how resumeData is generated after the user cancels the upload
    resumeData = [put cancelByProductingResumeData:&error];
    if (resumeData) {
    QCloudCOSXMLUploadObjectRequest* request = [QCloudCOSXMLUploadObjectRequest requestWithRequestData:resumeData];
     }
     //The generated request for resuming upload can be directly uploaded
     [[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:request];
    

    Note: The multipart upload uses the serial mode where parts must be uploaded in sequence. Under the following circumstances, resuming upload from breakpoint cannot be used.

    • The file to be uploaded is smaller than 1 MB and multipart upload is not used.
    • A simple upload API rather than the QCloudCOSXMLUploadObjectRequest class is used to upload files.
    • Multipart upload initialization is not completed (the callback for completed upload initialization is yet to be called) when you cancel the generation of resumeData.

    Download a file

    See the Download a file section in Getting Started.

    Copy a file

    Notes

    Initialize a QCloudCOSXMLCopyObjectRequest object, and then call CopyObject of QCloudCOSTransferMangerService. Note that multipart copy is automatically used for large files, but users will not be aware of this process.

    For cross-origin replication, the region of transferManager must be the same as that of the bucket.

    Example

    QCloudCOSXMLCopyObjectRequest* request = [[QCloudCOSXMLCopyObjectRequest alloc] init];
    request.bucket = @"Destination bucket";
    request.object = @"Destination file name";
    request.sourceBucket = @"File source bucket. Public read or access to the current account is required";
    request.sourceObject = @"Source file name";
    request.sourceAPPID = @"Source APPID";
    request.sourceRegion= @"Source region";
    [request setFinishBlock:^(QCloudCopyObjectResult* result, NSError* error) {
        //Complete callback
        if (nil == error) {
          //Successful
        }
    }];
    //For cross-origin replication, the region of transferManager must be the same as that of the bucket.
    [[QCloudCOSTransferMangerService defaultCOSTransferManager] CopyObject:request];

    Service Operations

    List all buckets - Get Service

    This API (Get Service) is used to obtain all Bucket lists of the requester.

    Parameters of returned result QCloudListAllMyBucketsResult

    Parameter Name Description Type
    owner Bucket owner information QCloudOwner *
    buckets All bucket information NSArray<QCloudBucket*> *

    Example

    QCloudGetServiceRequest* request = [[QCloudGetServiceRequest alloc] init];
    [request setFinishBlock:^(QCloudListAllMyBucketsResult* result, NSError* error) {
    //Process after callback is completed
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetService:request];

    Generate and use pre-signed URLs

    You can generate a pre-signed URL from the SDK or server, and then upload, download or perform other operations as needed.

    Description

    1. Create a QCloudGetPresignedURLRequest instance.
    2. Enter required information such as Bucket, Object, and HTTPMethod.
    3. If additional HTTP headers or parameters are required for use, call the method in QCloudGetPresignedURLRequest to add them when generating pre-signed URLs.
    4. Call getPresignedURL in QCloudCOSXMLService to send requests, and obtain pre-signed URLs in results.

    QCloudGetPresignedURLRequest parameters

    Parameter Name Description Type Required
    bucket Bucket using a pre-signed request NSString* Yes
    object Object using a pre-signed request. ObjectKey is the unique identifier of an object in a bucket. For example, in the object's access domain name "bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg", the key is "doc1/pic1.jpg". For more information, see Object Description. NSString* Yes
    HTTPMethod HTTP method of the request using a pre-signed URL. Valid values (case-sensitive): @"GET", @"PUT", @"POST" and @"DELETE". NSString* Yes
    contentType This parameter is available when the request using a pre-signed URL has this header. NSString* No
    contentMD5 This parameter is available when the request using a pre-signed URL has this header. NSString* No

    Note: To set the header or URL parameter of the request using a pre-signed URL, do the following:

    /**
     Add the header of the request using a pre-signed request
    
     @param value HTTP header value
     @param requestHeader HTTP header key
     */
    - (void)setValue:(NSString * _Nullable)value forRequestHeader:(NSString * _Nullable)requestHeader;
    
    /**
     Add the URL parameter of the request using a pre-signed request
    
     @param value Parameter value
     @param requestParameter Parameter key
     */
    - (void)setValue:(NSString * _Nullable)value forRequestParameter:(NSString *_Nullable)requestParameter;

    Example on how to obtain a pre-signed URL

    QCloudGetPresignedURLRequest* getPresignedURLRequest = [[QCloudGetPresignedURLRequest alloc] init];
    getPresignedURLRequest.bucket = self.bucket;
    getPresignedURLRequest.HTTPMethod = @"GET";
    getPresignedURLRequest.object = @"testUploadWithPresignedURL";
    [getPresignedURLRequest setFinishBlock:^(QCloudGetPresignedURLResult * _Nonnull result, NSError * _Nonnull error) {
    if (nil == error) {
     NSString* presignedURL = result.presienedURL;
    }
    }
    [[QCloudCOSXMLService defaultCOSXML] getPresignedURL:getPresignedURLRequest];
    

    Example on how to use a pre-signed URL

    The following example shows how to download with a pre-signed URL.

    NSMutableURLRequest* request = [[NSMutableURLRequest alloc] initWithURL:[NSURL URLWithString:@"Pre-signed URL"]];
    request.HTTPMethod = @"GET";
    request.HTTPBody = [@"File content" dataUsingEncoding:NSUTF8StringEncoding];
    [[[NSURLSession sharedSession] downloadTaskWithRequest:request completionHandler:^(NSURL * _Nullable location, NSURLResponse * _Nullable response, NSError * _Nullable error) {
        NSInteger statusCode = [(NSHTTPURLResponse*)response statusCode];
    }] resume];

    Bucket Operations

    Create a bucket

    Method prototype

    Before using COS, you need to create a bucket under the specific account for use and management of objects, and define the region of the bucket. The creator of the bucket is the owner of the bucket by default. The bucket access permission is Private Read/Write by default if not otherwise specified upon creation. Specific steps are as follows:

    1. Instantiate QCloudPutBucketRequest and enter the required parameters.
    2. Call the PutBucket method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content from outputObject in finishBlock of callback.

    QCloudPutBucketRequest parameters

    Parameter Name Description Type Required
    bucket The name of the bucket to be created, which can be viewed in the COS V5 Console. Note that the bucket name can only consist of numbers and lowercase letters with a length limited to 40 characters; otherwise, the creation will fail. NSString * Yes
    accessControlList Defines the ACL attribute of a bucket. Valid values: private, public-read-write, public-read; Default: private NSString * No
    grantRead Grants read permission to the authorized user. Format: id=" ",id=" ". For authorization to a subaccount, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"; for authorization to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>", where OwnerUin refers to the ID of the root account and SubUin refers to the ID of the subaccount. NSString * No
    grantWrite Grants write permission to the authorized user. The format is the same as above. NSString * No
    grantFullControl Grants read and write permissions to the authorized user. The format is the same as above. NSString * No

    Example

    QCloudPutBucketRequest* request = [QCloudPutBucketRequest new];
    request.bucket = @"bucketname-appid"; //additional actions after finishing
    [request setFinishBlock:^(id outputObject, NSError* error) {
    
    }];
    [[QCloudCOSXMLService defaultCOSXML] PutBucket:request];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    List contents in a bucket

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudGetBucketRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudGetBucketRequest and enter the required parameters.
    2. Call the GetBucket method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content from QCloudListBucketResult in finishBlock of callback.

    QCloudGetBucketRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    prefix Prefix match, used to specify the prefix address of the returned file. NSString * No
    delimiter Delimiter is a sign. If Prefix exists, the same paths between Prefix and delimiter are grouped as the same type and defined as Common Prefix, and then all Common Prefixes are listed. If Prefix does not exist, the listing process starts from the beginning of the path. It can be considered as an ending symbol. For example, if you want a string to end with A, set delimiter to A. NSString * No
    encodingType Indicates the encoding method of the returned value. Available value: url NSString * No
    marker Entries are listed using UTF-8 binary order by default, starting from marker NSString * No
    maxKeys Maximum number of entries returned at a time. Default is 1000. int No

    Example

    QCloudGetBucketRequest* request = [QCloudGetBucketRequest new];
    request.bucket = @“testBucket-123456789”;
    request.maxKeys = 1000;
    [request setFinishBlock:^(QCloudListBucketResult * result, NSError*   error) {
    //additional actions after finishing
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetBucket:request];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Obtain bucket ACL (Access Control List)

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudGetBucketACLRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudGetBucketACLRequest and enter the bucket whose ACL is to be obtained.
    2. Call the GetBucketACL method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content from QCloudACLPolicy in finishBlock of callback.

    QCloudGetBucketACLRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes

    Parameters of returned result QCloudACLPolicy

    Parameter Name Description Type
    owner Bucket owner information QCloudACLOwner *
    accessControlList Information of the authorized user and permissions QCloudAccessControlList *

    Example

    QCloudGetBucketACLRequest* getBucketACl   = [QCloudGetBucketACLRequest new];
    getBucketACl.bucket = @"testbucket-123456789";
    [getBucketACl setFinishBlock:^(QCloudACLPolicy * _Nonnull result, NSError * _Nonnull error) {
       //QCloudACLPolicy contains Bucket ACL information.
    }];
    
    [[QCloudCOSXMLService defaultCOSXML] GetBucketACL:getBucketACl];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Set bucket ACL (Access Control List)

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudPutBucketACLRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudPutBucketACLRequest, enter the bucket to be set, and then enter corresponding parameters according to the permission type of the bucket.
    2. Call the PutBucketACL method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain the setting result (successful or failed) from finishBlock of callback, and perform some additional operations if the setting is successful.

    QCloudPutBucketACLRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID> , such as testBucket-1253653367 NSString * Yes
    accessControlList Defines the ACL attribute of an object. Valid values: private, public-read-write, public-read; Default: private NSString * No
    grantRead Grants read permission to the authorized user. Format: id=" ",id=" ".
    For authorization to a subaccount, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
    for authorization to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>",
    where OwnerUin refers to the ID of the root account and SubUin refers to the ID of the subaccount.
    NSString * No
    grantWrite Grants write permission to the authorized user. The format is the same as above. NSString * No
    grantFullControl Grants read and write permissions to the authorized user. The format is the same as above. NSString * No

    Example

    QCloudPutBucketACLRequest* putACL = [QCloudPutBucketACLRequest new];
    NSString* appID = @“Your APPID”;
    NSString *ownerIdentifier = [NSString stringWithFormat:@"qcs::cam::uin/%@:uin/%@", appID, appID];
    NSString *grantString = [NSString stringWithFormat:@"id=\"%@\"",ownerIdentifier];
    putACL.grantFullControl = grantString;
    putACL.bucket = @“testBucket-123456789”;
    [putACL setFinishBlock:^(id outputObject, NSError *error) {
    //error occucs if error != nil
    }];
    [[QCloudCOSXMLService defaultCOSXML] PutBucketACL:putACL];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Obtain bucket CORS configuration

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudGetBucketCORSRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudGetBucketCORSRequest and enter the bucket whose CORS is to be obtained.
    2. Call the GetBucketCORS method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain the result from finishBlock of callback. The result is encapsulated in the QCloudCORSConfiguration object whose "rules" attribute is an array containing a set of QCloudCORSRule. The specific CORS configurations are encapsulated in the QCloudCORSRule object.

    QCloudGetBucketACLRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes

    Parameters of returned result QCloudCORSConfiguration

    Parameter Name Description Type
    rules The array containing CORS. It is a QCloudCORSRule instance. NSArray<CloudCORSRule*> *

    QCloudCORSRule parameters

    Parameter Name Description Type
    identifier ID of the configuration rule NSString *
    allowedMethod Allowed HTTP operations. Enumerated values: GET, PUT, HEAD, POST, DELETE NSArray<NSString*>*
    allowedOrigin Allowed access source. The wildcard "*" is supported. Format: protocol://domain name[:port], for example, http://www.qq.com NSString *
    allowedHeader It is used to notify the server about which custom HTTP request headers are allowed for subsequent requests when an OPTIONS request is sent. The wildcard "*" is supported. NSArray<NSString*> *
    maxAgeSeconds Configures the valid period of the results obtained by OPTIONS request int
    exposeHeader Configures the custom header information that can be received by the browser from the server NSString *

    Example

    QCloudGetBucketCORSRequest* corsReqeust = [QCloudGetBucketCORSRequest new];
    corsReqeust.bucket = @"testBucket-123456789";
    [corsReqeust setFinishBlock:^(QCloudCORSConfiguration * _Nonnull result, NSError * _Nonnull error) {
       //CORS is encapsulated in result.
    }];
    
    [[QCloudCOSXMLService defaultCOSXML] GetBucketCORS:corsReqeust];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Configure bucket CORS

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudPutBucketCORSRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudPutBucketCORSRequest, configure the bucket, and put the required CORS into QCloudCORSRule. If there are multiple CORS configurations, you can place multiple QCloudCORSRule in an NSArray, put the array into QCloudCORSConfiguration's rules attribute, and then into the request.
    2. Call the PutBucketCORS method in the QCloudCOSXMLService object to initiate the request.
    3. Obtain the setting result (error is empty or not) from finishBlock of callback, and perform additional operations if the setting is successful.

    QCloudPutBucketCORSRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    corsConfiguration Specific parameter that encapsulates CORS QCloudCORSConfiguration * Yes

    QCloudCORSConfiguration parameters

    Parameter Name Description Type
    rules The array containing CORS. It is a QCloudCORSRule instance. NSArray<QCloudCORSRule* > *

    QCloudCORSRule parameters

    Parameter Name Description Type
    identifier ID of the configuration rule NSString *
    allowedMethod Allowed HTTP operations. Enumerated values: GET, PUT, HEAD, POST, DELETE NSArray <NSString*> *
    allowedOrigin Allowed access source. The wildcard "*" is supported. Format: protocol://domain name[:port], for example, http://www.qq.com NSString *
    allowedHeader It is used to notify the server about which custom HTTP request headers are allowed for subsequent requests when an OPTIONS request is sent. The wildcard "*" is supported. NSArray <NSString * > *
    maxAgeSeconds Configures the valid period of the results obtained by OPTIONS request int
    exposeHeader Configures the custom header information that can be received by the browser from the server NSString *

    Example

    QCloudPutBucketCORSRequest* putCORS = [QCloudPutBucketCORSRequest new];
    QCloudCORSConfiguration* cors = [QCloudCORSConfiguration new];
    
    QCloudCORSRule* rule = [QCloudCORSRule new];
    rule.identifier = @"sdk";
    rule.allowedHeader = @[@"origin",@"host",@"accept",@"content-type",@"authorization"];
    rule.exposeHeader = @"ETag";
    rule.allowedMethod = @[@"GET",@"PUT",@"POST", @"DELETE", @"HEAD"];
    rule.maxAgeSeconds = 3600;
    rule.allowedOrigin = @"*";
    cors.rules = @[rule];
    putCORS.corsConfiguration = cors;
    putCORS.bucket = @"testBucket-123456789";
    [putCORS setFinishBlock:^(id outputObject, NSError *error) {
        if (!error) {
          //success
      }
    }];
    [[QCloudCOSXMLService defaultCOSXML] PutBucketCORS:putCORS];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Get bucket location

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudGetBucketLocationRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudGetBucketLocationRequest and enter the Bucket name.
    2. Call the GetBucketLocation method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content in finishBlock of callback.

    QCloudGetBucketLocationRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes

    Parameters of returned result QCloudBucketLocationConstraint

    Parameter Name Description Type
    locationConstraint The region where the bucket resides NSString*

    Example

    QCloudGetBucketLocationRequest* locationReq = [QCloudGetBucketLocationRequest new];
    locationReq.bucket = @"testBucket-123456789";
     __block QCloudBucketLocationConstraint* location;
    [locationReq setFinishBlock:^(QCloudBucketLocationConstraint * _Nonnull result, NSError * _Nonnull error) {
           location = result;
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetBucketLocation:locationReq];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Delete bucket CORS configuration

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudDeleteBucketCORSRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudDeleteBucketCORSRequest and enter the required parameters.
    2. Call the method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content in finishBlock of callback.

    QCloudDeleteBucketCORSRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes

    Example

    QCloudDeleteBucketCORSRequest* deleteCORS = [QCloudDeleteBucketCORSRequest new];
    deleteCORS.bucket = @"testBucket-123456789";
    [deleteCORS setFinishBlock:^(id outputObject, NSError *error) {
       //success if error == nil
    }];
    [[QCloudCOSXMLService defaultCOSXML] DeleteBucketCORS:deleteCORS];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Query multipart upload in a bucket (List Bucket Multipart Uploads)

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudListBucketMultipartUploadsRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudListBucketMultipartUploadsRequest and enter the required parameters, such as the prefix and the encoding method of the returned result.
    2. Call the ListBucketMultipartUploads method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content in finishBlock of callback.

    QCloudListBucketMultipartUploadsRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    prefix The returned Object key must be prefixed with Prefix. Note that the returned key will still contain Prefix when querying with prefix. NSString * No
    delimiter Delimiter is a sign. If Prefix exists, the same paths between Prefix and delimiter are grouped as the same type and defined as Common Prefix, and then all Common Prefixes are listed. If Prefix does not exist, the listing process starts from the beginning of the path. It can be considered as an ending symbol. For example, if you want a string to end with A, set delimiter to A. NSString * No
    encodingType Indicates the encoding method of the returned value. Available value: url NSString * No
    keyMarker Entries will be listed starting from this key value NSString * No
    uploadIDMarker Entries will be listed starting from this UploadId value int No
    maxUploads Sets the maximum number of multipart returned. Valid values: 1-1000 int No

    Parameters of returned result QCloudListMultipartUploadsResult

    Parameter Name Description Type
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString *
    prefix The returned Object key must be prefixed with Prefix. Note that the returned key will still contain Prefix when querying with prefix. NSString *
    delimiter Delimiter is a sign. If Prefix exists, the same paths between Prefix and delimiter are grouped as the same type and defined as Common Prefix, and then all Common Prefixes are listed. If Prefix does not exist, the listing process starts from the beginning of the path NSString *
    encodingType Indicates the encoding method of the returned value. Available value: url NSString *
    keyMarker Entries will be listed starting from this key value NSString *
    maxUploads Sets the maximum number of multipart returned. Valid values: 1-1000 int
    uploads Information of all multipart upload operations NSArray*

    Example

    QCloudListBucketMultipartUploadsRequest* uploads = [QCloudListBucketMultipartUploadsRequest new];
    uploads.bucket = @"testBucket-123456789";
    uploads.maxUploads = 100;
    __block NSError* resulError;
    __block QCloudListMultipartUploadsResult* multiPartUploadsResult;
    [uploads setFinishBlock:^(QCloudListMultipartUploadsResult* result, NSError *error) {
        multiPartUploadsResult = result;
        localError = error;
    }];
    [[QCloudCOSXMLService defaultCOSXML] ListBucketMultipartUploads:uploads];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem. Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Query whether a bucket exists (Head Bucket)

    Head Bucket request is used to determine whether a bucket exists and whether you can access the bucket. Head and Read have the same permission. 200 is returned if the bucket exists; 403 is returned if you cannot access the bucket; and 404 is returned if the bucket does not exist.

    QCloudHeadBucketRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes

    Example

     QCloudHeadBucketRequest* request = [QCloudHeadBucketRequest new];
     request.bucket = @"testBucket-123456789";
     [request setFinishBlock:^(id outputObject, NSError* error) {
         //Set the completion callback. If no error, the bucket can be accessed normally. Otherwise, you can get the specific failure reason by viewing the error code and message.
     }];
     [[QCloudCOSXMLService defaultCOSXML] HeadBucket:request];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Put Bucket Lifecycle

    COS allows you to manage the lifecycle of an object in a bucket by configuring lifecycle. The lifecycle configuration contains one or more rule sets that will be applied to a group of object rules (each rule defines an operation for COS).
    These operations are divided into the following two types:

    • Transition: Specify the time when an object is transited to another storage class. For example, you can choose to transit an object to STANDARD_IA (applicable to infrequent access) storage class after 30 days of its creation.
    • Expiration: Specify the expiration time of an Object. COS will automatically delete the objects that have expired.

    Put Bucket Lifecycle is used to create a new lifecycle configuration for a Bucket. If the Bucket has been configured with a lifecycle, you can use this API to create a new configuration which will overwrite the existing one.

    Parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    lifeCycle Lifecycle configuration QCloudLifecycleConfiguration* Yes

    QCloudLifecycleConfiguration parameters

    Parameter Name Description Type Required
    rules An array describing a collection of rules NSArray<QCloudLifecycleRule*> * Yes

    QCloudLifecycleRule parameters

    Parameter Name Description Type Required
    identifier Uniquely identifies a rule. Its length cannot exceed 255 characters. NSString* Yes
    filter Describes the collection of Objects affected by rules QCloudLifecycleRuleFilter*
    status Indicates whether the rule is enabled. Enumerated values: Enabled, Disabled. QCloudLifecycleStatue Yes
    abortIncompleteMultipartUpload Sets the maximum length of time allowed for a continuous multipart upload QCloudLifecycleAbortIncompleteMultipartUpload No
    transition Rule transition attribute, which indicates when an object is transited to Standard_IA etc. QCloudLifecycleTransition* No
    expiration Rule expiration attribute QCloudLifecycleExpiration* No
    noncurrentVersionExpiration Indicates when objects of non-current version expire QCloudLifecycleExpiration* No
    noncurrentVersionTransition Indicates when objects of non-current version are transited to STANDARD_IA etc. QCloudNoncurrentVersionExpiration* No

    Example

    QCloudPutBucketLifecycleRequest* request = [QCloudPutBucketLifecycleRequest new];
    request.bucket = @"Enter bucket name";
    __block QCloudLifecycleConfiguration* configuration = [[QCloudLifecycleConfiguration alloc] init];
    QCloudLifecycleRule* rule = [[QCloudLifecycleRule alloc] init];
    rule.identifier = @"identifier";
    rule.status = QCloudLifecycleStatueEnabled;
    QCloudLifecycleRuleFilter* filter = [[QCloudLifecycleRuleFilter alloc] init];
    filter.prefix = @"0";
    rule.filter = filter;
    
    QCloudLifecycleTransition* transition = [[QCloudLifecycleTransition alloc] init];
    transition.days = 100;
    transition.storageClass = QCloudCOSStorageStandarIA;
    rule.transition = transition;
    request.lifeCycle = configuration;
    request.lifeCycle.rules = @[rule];
    [request setFinishBlock:^(id outputObject, NSError* error) {
       //Set the completion callback
    }];
    [[QCloudCOSXMLService defaultCOSXML] PutBucketLifecycle:request];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Get Bucket Lifecycle

    Parameters of returned result QCloudLifecycleConfiguration

    Same with QCloudLifecycleConfiguration in the API Put Bucket Lifecycle.

    Example

    QCloudGetBucketLifecycleRequest* request = [QCloudGetBucketLifecycleRequest new];
    request.bucket = @"testBucket-123456789";
    [request setFinishBlock:^(QCloudLifecycleConfiguration* result,NSError* error) {
        //Set the completion callback
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetBucketLifecycle:request];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Delete Bucket Lifecycle

    Parameters of returned result QCloudLifecycleConfiguration

    Same with QCloudLifecycleConfiguration in the API Put Bucket Lifecycle.

    Example

    QCloudDeleteBucketLifeCycleRequest* request = [[QCloudDeleteBucketLifeCycleRequest alloc ] init];
    request.bucket = @"testBucket-123456789";
     [request setFinishBlock:^(QCloudLifecycleConfiguration* result, NSError* error) {
     //Set the completion callback
    }];
     [[QCloudCOSXMLService defaultCOSXML] DeleteBucketLifeCycle:request];

    Put Bucket Versioning

    This API (Put Bucket Versioning) is used to enable or suspend the bucket version control feature. Note: this is an irreversible API, and cannot be disabled after being enabled.

    QCloudPutBucketVersioningRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    configuration Version control details QCloudBucketVersioningConfiguration* Yes

    QCloudBucketVersioningConfiguration parameters

    Parameter Name Description Type Required
    status Indicates whether version control is enabled. Enumerated values: Suspended\Enabled. QCloudCOSBucketVersioningStatus Yes

    Example

    QCloudPutBucketVersioningRequest* request = [[QCloudPutBucketVersioningRequest alloc] init];
    request.bucket = @"testBucket-123456789";
    QCloudBucketVersioningConfiguration* configuration = [[QCloudBucketVersioningConfiguration alloc] init];
    request.configuration = configuration;
    configuration.status = QCloudCOSBucketVersioningStatusEnabled;
    [request setFinishBlock:^(id outputObject, NSError* error) {
       //Set the completion callback
     }];
     [[QCloudCOSXMLService defaultCOSXML] PutBucketVersioning:request];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Get Bucket Versioning

    Parameters of returned result QCloudBucketVersioningConfiguration

    Parameter Name Description Type
    status Indicates whether version control is enabled. Enumerated values: Suspended\Enabled. QCloudCOSBucketVersioningStatus

    Example

    QCloudGetBucketVersioningRequest* request = [[QCloudGetBucketVersioningRequest alloc] init];
    request.bucket = @"testBucket-123456789";
    [request setFinishBlock:^(QCloudBucketVersioningConfiguration* result, NSError* error) {
       //Set the completion callback
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetBucketVersioning:request];

    Put Bucket Replication

    Put Bucket Replication request is used to add replication configuration to the bucket for which the version control is enabled. If the bucket already has a replication configuration, the request will replace the existing configuration.

    QCloudPutBucketReplicationRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    configuration Describes all the cross-origin configuration QCloudBucketReplicationConfiguration* Yes

    To use this API, version management must be enabled for the bucket. For more information on version management, see Put Bucket Versioning.

    Parameters of returned result

    Example

    QCloudPutBucketReplicationRequest* request = [[QCloudPutBucketReplicationRequest alloc] init];
    request.bucket = @"source-bucket";
    QCloudBucketReplicationConfiguation* configuration = [[QCloudBucketReplicationConfiguation alloc] init];
    configuration.role = [NSString identifierStringWithID:@"uin" :@"uin"];
    QCloudBucketReplicationRule* rule = [[QCloudBucketReplicationRule alloc] init];
    rule.identifier = @"identifier";
    rule.status = QCloudQCloudCOSXMLStatusEnabled;
    
    QCloudBucketReplicationDestination* destination = [[QCloudBucketReplicationDestination alloc] init];
    //qcs:id/0:cos:[region]:appid/[AppId]:[bucketname]
    NSString* destinationBucket = @"destinationBucket";
    NSString* region = @"destinationRegion"
    destination.bucket = [NSString stringWithFormat:@"qcs:id/0:cos:%@:appid/%@:%@",@"region",@"appid",@"destinationBucket"];
    rule.destination = destination;
    configuration.rule = @[rule];
    request.configuation = configuration;
    [request setFinishBlock:^(id outputObject, NSError* error) {
         //Set the completion callback
    }];
     [[QCloudCOSXMLService defaultCOSXML] PutBucketRelication:request];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Get Bucket Replication

    This API (Get Bucket Replication) is used to read the cross-origin replication configuration information in a bucket.

    Parameters of returned result QCloudBucketReplicationConfiguration

    Parameter Name Description Type
    role Initiator ID, in the format of qcs::cam::uin/:uin/ NSString*
    rule Specific configuration information. Up to 1000 rules are supported. All rules must be directed to one destination bucket. NSArray<QCloudBucketReplicationRule*> *

    QCloudBucketReplicationRule parameters

    Parameter Name Description Type
    status Indicates whether the Rule takes effect QCloudQCloudCOSXMLStatus
    identifier Indicates the name of a specific Rule NSString*
    prefix Prefix match policy (blank for root directory). Prefixes cannot overlap; otherwise, an error is returned. NSString*
    destination Destination bucket information QCloudBucketReplicationDestination*

    Example

    QCloudGetBucketReplicationRequest* request = [[QCloudGetBucketReplicationRequest alloc] init];
    request.bucket = @"testBucket-123456789";
    [request setFinishBlock:^(QCloudBucketReplicationConfiguation* result, NSError* error) {
        //Set the completion callback
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetBucketReplication:request];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Delete Bucket Replication

    This API (Delete Bucket Replication) is used to delete the cross-origin replication configuration in a bucket.

    Parameters

    Parameters of returned result

    Example

    QCloudDeleteBucketReplicationRequest* request = [[QCloudDeleteBucketReplicationRequest alloc] init];
    request.bucket = @"testBucket-123456789";
    [request setFinishBlock:^(id outputObject, NSError* error) {
       //Set the completion callback
    }];
    [[QCloudCOSXMLService defaultCOSXML] DeleteBucketReplication:request];

    In COS, each file is an Object. Operating on a file is actually operating on an Object.

    Simple upload (Put Object)

    Simple upload only applies to files less than 20 MB, and supports uploading files from memory.

    The number of access policies is up to 1000. Do not set object ACL control when you upload an object if it is not required. The object inherits the bucket permissions by default.

    QCloudPutObjectRequest parameters

    Parameter Name Description Type Required
    Object ObjectKey is the unique identifier of an object in a bucket. For example, in the object's access domain name "bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg", the ObjectKey is "doc1/pic1.jpg". For more information, see Object Description. NSString * Yes
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    body If a file is stored in the disk, it is the path of the file to be uploaded, and you can enter a variable of NSURL * type. If a file is stored in memory, you can enter a variable of NSData * type that contains the file binary data. BodyType Yes
    storageClass Storage class of an object QCloudCOSStorageClass Yes
    cacheControl Cache policy defined in RFC 2616 NSString * No
    contentDisposition File name defined in RFC 2616 NSString * No
    expect When expect=@"100-Continue" is used, the request content will not be sent until the receipt of response from server. NSString * No
    expires Expiration time defined in RFC 2616 NSString * No
    initMultipleUploadFinishBlock If the request generates a multipart upload request, after the initialization of multipart upload, a callback is performed via the block. The bucket, key, and uploadID after the completion of multipart upload, and ResumeData for resuming subsequent failed upload can be obtained from this callback block. block No
    accessControlList Defines the ACL attribute of an object. Valid values: private, public-read-write, public-read; Default: private NSString * No
    grantRead Grants read permission to the authorized user. Format: id=" ",id=" ". For authorization to a subaccount, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"; for authorization to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>", where OwnerUin refers to the ID of the root account and SubUin refers to the ID of the subaccount. NSString * No
    grantWrite Grants write permission to the authorized user. The format is the same as above. NSString * No
    grantFullControl Grants read and write permissions to the authorized user. The format is the same as above. NSString * No

    Example

    QCloudPutObjectRequest* put = [QCloudPutObjectRequest new];
    put.object = @"object-name";
    put.bucket = @"bucket-12345678";
    put.body =  [@"testFileContent" dataUsingEncoding:NSUTF8StringEncoding];
    [put setFinishBlock:^(id outputObject, NSError *error) {
       //Complete callback
      if (nil == error) {
       //Successful
       }
       }];
    [[QCloudCOSXMLService defaultCOSXML] PutObject:put];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Query object ACL (Access Control List)

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before file operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudGetObjectACLRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudGetObjectACLRequest, and enter the bucket name and the name of the object to be queried.
    2. Call the GetObjectACL method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain the specific ACL information encapsulated in the QCloudACLPolicy object obtained from finishBlock in callback.

    QCloudGetObjectACLRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    object ObjectKey is the unique identifier of an object in a bucket. For example, in the object's access domain name "bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg", the key is "doc1/pic1.jpg". For more information, see Object Description. NSString * Yes

    Example

    request.bucket = self.aclBucket;
    request.object = @"Object name";
    request.bucket = @"testBucket-123456789"
    __block QCloudACLPolicy* policy;
    [request setFinishBlock:^(QCloudACLPolicy * _Nonnull result, NSError * _Nonnull error) {
         policy = result;
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetObjectACL:request];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Set object ACL (Access Control List)

    The number of access policies is up to 1000. Do not set object ACL control if it is not required. The object inherits the bucket permissions by default.

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before object operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudPutObjectACLRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudPutObjectACLRequest, and enter the bucket name and additionally required parameters, such as authorization information.
    2. Call the method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain whether the configuration is completed from finishBlock in callback. If error is null, configuration is successful.

    QCloudPutObjectACLRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    object Object name NSString * Yes
    accessControlList Defines the ACL attribute of an object. Valid values: private, public-read-write, public-read; Default: private NSString * No
    grantRead Grants read permission to the authorized user. Format: id=" ",id=" ".
    For authorization to a subaccount, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
    for authorization to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>",
    where OwnerUin refers to the ID of the root account and SubUin refers to the ID of the subaccount
    NSString * No
    grantWrite Grants write permission to the authorized user. The format is the same as above. NSString * No
    grantFullControl Grants read and write permissions to the authorized user. The format is the same as above. NSString * No

    Example

    QCloudPutObjectACLRequest* request = [QCloudPutObjectACLRequest new];
    request.object = @"Name of the object whose ACL needs to be set";
    request.bucket = @"testBucket-123456789";
    NSString *ownerIdentifier = [NSString stringWithFormat:@"qcs::cam::uin/%@:uin/%@",self.appID, self.appID];
    NSString *grantString = [NSString stringWithFormat:@"id=\"%@\"",ownerIdentifier];
    request.grantFullControl = grantString;
    __block NSError* localError;
    [request setFinishBlock:^(id outputObject, NSError *error) {
         localError = error;
    }];
    [[QCloudCOSXMLService defaultCOSXML] PutObjectACL:request];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Download a file

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before file operations. Before that, you need to complete the initialization described in Getting Started by creating an instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Complete instantiation, and enter required parameters.
    2. Call the method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content in finishBlock of callback.

    Parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    object Object name NSString * Yes
    range The specified range of file download defined in RFC 2616 (in bytes) NSString * No
    ifModifiedSince The file content is only returned if the file is modified after the specified time. Otherwise, 412 (not modified) is returned. NSString * No
    responseContentType Sets the Content-Type parameter in the response header NSString * No
    responseContentLanguage Sets the Content-Language parameter in the response header NSString * No
    responseContentExpires Sets the Content-Expires parameter in the response header NSString * No
    responseCacheControl Sets the Cache-Control parameter in the response header NSString * No
    responseContentDisposition Sets the Content-Disposition parameter in the response header NSString * No
    responseContentEncoding Sets the Content-Encoding parameter in the response header NSString * No

    Example

    QCloudGetObjectRequest* request = [QCloudGetObjectRequest new];
    //Set the URL for download. If it has been set, the file is downloaded to the specified path. Otherwise, the file is downloaded to outputObject of finishBlock in memory.
    request.downloadingURL = [NSURL URLWithString:QCloudTempFilePathWithExtension(@"downding")];
    request.object = @“Your Object-Key”;
    request.bucket = @"testBucket-123456789";
    [request setFinishBlock:^(id outputObject, NSError *error) {
        //additional actions after finishing
    }];
    [request setDownProcessBlock:^(int64_t bytesDownload, int64_t totalBytesDownload, int64_t totalBytesExpectedToDownload) {
       //Progress of download
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetObject:request];

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Pre-request for CORS configuration of objects

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before file operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudOptionsObjectRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudOptionsObjectRequest, enter the object name, the bucket name, the HTTP method of the simulate CORS request and the access sources allowed for the simulate CORS.
    2. Call the method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content in finishBlock of callback.

    QCloudOptionsObjectRequest parameters

    Parameter Name Description Type Required
    object ObjectKey is the unique identifier of an object in a bucket. For example, in the object's access domain name "bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg", the key is "doc1/pic1.jpg". For more information, see Object Description. NSString * Yes
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    accessControlRequestMethod The HTTP method of the simulate CORS request NSArray<NSString*> * Yes
    origin The access sources allowed for the simulate CORS. The wildcard "*" is supported. Format: protocol://domain name[:port], for example, http://www.qq.com. NSString * Yes
    allowedHeader It is used to notify the server about which custom HTTP request headers are allowed for subsequent requests when an OPTIONS request is sent. The wildcard "*" is supported. NSArray<NSString * > * No

    Example

    QCloudOptionsObjectRequest* request = [[QCloudOptionsObjectRequest alloc] init];
    request.bucket =@"Bucket name";
    request.origin = @"*";
    request.accessControlRequestMethod = @"get";
    request.accessControlRequestHeaders = @"host";
    request.object = @"Object name";
    __block id resultError;
    [request setFinishBlock:^(id outputObject, NSError* error) {
         resultError = error;
     }];
    
    [[QCloudCOSXMLService defaultCOSXML] OptionsObject:request];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Delete a single object

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before file operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudDeleteObjectRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudDeleteObjectRequest and enter the required parameters.
    2. Call the method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content in finishBlock of callback.

    QCloudDeleteObjectRequest parameters

    Parameter Name Type Required Description
    object ObjectKey is the unique identifier of an object in a bucket. For example, in the object's access domain name "bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg", the key is "doc1/pic1.jpg". For more information, see Object Description. NSString * Yes
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes

    Example

    QCloudDeleteObjectRequest* deleteObjectRequest = [QCloudDeleteObjectRequest new];
    deleteObjectRequest.bucket = @"testBucket-123456789";
    deleteObjectRequest.object = @"Object name";
    __block NSError* resultError;
    [deleteObjectRequest setFinishBlock:^(id outputObject, NSError *error) {
        resultError = error;
    }];
    [[QCloudCOSXMLService defaultCOSXML] DeleteObject:deleteObjectRequest];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Delete multiple objects

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before file operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudDeleteMultipleObjectRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudDeleteMultipleObjectRequest and enter the required parameters.
    2. Call the method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content in finishBlock of callback.

    QCloudDeleteMultipleObjectRequest parameters

    Parameter Name Description Type Required
    object ObjectKey is the unique identifier of an object in a bucket. For example, in the object's access domain name "bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg", the key is "doc1/pic1.jpg". For more information, see Object Description. NSString * Yes
    deleteObjects Encapsulates information of multiple objects to be deleted in batches QCloudDeleteInfo * Yes

    QCloudDeleteInfo parameters

    Parameter Name Description Type Required
    objects An array containing information on the objects to be deleted NSArray<QCloudDeleteObjectInfo * > * Yes

    QCloudDeleteObjectInfo parameters

    Parameter Name Description Type Required
    key ObjectKey is the unique identifier of an object in a bucket. For example, in the object's access domain name "bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg", the key is "doc1/pic1.jpg". For more information, see Object Description. NSString * Yes

    Example

    QCloudDeleteMultipleObjectRequest* delteRequest = [QCloudDeleteMultipleObjectRequest new];
    delteRequest.bucket = @"testBucket-123456789";
    
    QCloudDeleteObjectInfo* deletedObject0 = [QCloudDeleteObjectInfo new];
    deletedObject0.key = @"Name of the first object";
    
    QCloudDeleteObjectInfo* deleteObject1 = [QCloudDeleteObjectInfo new];
    deleteObject1.key = @"Name of the second object";
    
    QCloudDeleteInfo* deleteInfo = [QCloudDeleteInfo new];
    deleteInfo.quiet = NO;
    deleteInfo.objects = @[ deletedObject0,deleteObject2];
    delteRequest.deleteObjects = deleteInfo;
    __block NSError* resultError;
    [delteRequest setFinishBlock:^(QCloudDeleteResult* outputObject, NSError *error) {
          localError = error;
          deleteResult = outputObject;
    }];
    [[QCloudCOSXMLService defaultCOSXML] DeleteMultipleObject:delteRequest];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Initialize multipart upload

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before file operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudInitiateMultipartUploadRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudInitiateMultipartUploadRequest and enter the required parameters.
    2. Call the InitiateMultipartUpload method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content in finishBlock of callback.

    Parameters

    Parameter Name Description Type Required
    Object The name of the file (object) to be uploaded, i.e. the key of the object. ObjectKey is the unique identifier of an object in a bucket. For example, in the object's access domain name "bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg", the key is "doc1/pic1.jpg". For more information, see Object Description. NSString * Yes
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    cacheControl Cache policy defined in RFC 2616 NSString * No
    contentDisposition File name defined in RFC 2616 NSString * No
    expect When expect=@"100-continue" is used, the request content will not be sent until the receipt of response from server. NSString * No
    expires Expiration time defined in RFC 2616 NSString * No
    storageClass Storage class of an object QCloudCOSStorageClass No
    accessControlList Defines the ACL attribute of an object. Valid values: private, public-read-write, public-read; Default: private NSString * No
    grantRead Grants read permission to the authorized user. Format: id=" ",id=" ".
    For authorization to a subaccount, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
    for authorization to the root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>",
    where OwnerUin refers to the ID of the root account and SubUin refers to the ID of the subaccount
    NSString * No
    grantWrite Grants write permission to the authorized user. The format is the same as above. NSString * No
    grantFullControl Grants read and write permissions to the authorized user. The format is the same as above. NSString * No

    Example

    QCloudInitiateMultipartUploadRequest* initrequest = [QCloudInitiateMultipartUploadRequest new];
    initrequest.bucket = @"testBucket-123456789";
    initrequest.object = @"Object name";
    __block QCloudInitiateMultipartUploadResult* initResult;
    [initrequest setFinishBlock:^(QCloudInitiateMultipartUploadResult* outputObject, NSError *error) {
        initResult = outputObject;
    }];
    [[QCloudCOSXMLService defaultCOSXML] InitiateMultipartUpload:initrequest];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Obtain object meta information

    Method prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before file operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudHeadObjectRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudHeadObjectRequest and enter the required parameters.
    2. Call the HeadObject method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content in finishBlock of callback.

    QCloudHeadObjectRequest parameters

    Parameter Name Description Type Required
    Object ObjectKey is the unique identifier of an object in a bucket. For example, in the object's access domain name "bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg", the key is "doc1/pic1.jpg". For more information, see Object Description. NSString * Yes
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    ifModifiedSince The file content is only returned if the file is modified after the specified time. Otherwise, 304 (not modified) is returned. NSString * Yes

    Example

    QCloudHeadObjectRequest* headerRequest = [QCloudHeadObjectRequest new];
    headerRequest.object = @“Object name”;
    headerRequest.bucket = @"testBucket-123456789";
    
       __block id resultError;
    [headerRequest setFinishBlock:^(NSDictionary* result, NSError *error) {
          resultError = error;
    }];
    [[QCloudCOSXMLService defaultCOSXML] HeadObject:headerRequest];
    

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    • Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    • Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    Adding Custom Headers

    You can add custom headers as needed. Classes allowing addition of custom headers are provided with the attribute customHeaders:

    @property (strong, nonatomic) NSMutableDictionary* customHeaders;

    Key-value pairs in this attribute will be added to the HTTP headers of creation requests accordingly.

    Server Encryption

    You can encrypt the uploaded objects in the following ways.

    Use server-side encryption with COS-hosted encryption keys (SSE-COS) to protect data

    COS can automatically encrypt data as it is written to the IDC and automatically decrypt it when you access it. COS master key is used to apply AES-256 encryption to data.

    You can achieve this by calling -(void)setCOSServerSideEncyption in the iOS SDK.

    [request setCOSServerSideEncyption];

    Use server-side encryption with customer-provided encryption keys (SSE-C) to protect data

    You can achieve this by calling -(void)setCOSServerSideEncyptionWithCustomerKey:(NSString *)customerKey in the iOS SDK.
    Note:

    1. To use server side encryption, HTTPS connection is required. See the Enable HTTPS Service section.
    2. customerKey: The key provided by the user, which shall be a 32-byte string consisting of numbers, letters and strings. Chinese characters are not supported.
    3. If the uploaded source file calls this method, it should also be called when downloading, querying, uploading and copying the source object using QCloudCOSXMLDownloadObjectRequest, QCloudHeadObjectRequest, QCloudCOSXMLUploadObjectRequest and QCloudCOSXMLUploadObjectRequest.
    NSString *customKey = @"123456qwertyuioplkjhgfdsazxcvbnm";
    [put setCOSServerSideEncyptionWithCustomerKey:customKey];

    Enable HTTPS Service

    The iOS SDK supports HTTPS requests. You only need to, when initializing the configuration object QCloudServiceConfiguration, set useHTTPS for its endpoint to YES.

    QCloudServiceConfiguration* configuration = [QCloudServiceConfiguration new];
    configuration.appID = kAppID;
    configuration.signatureProvider = self;
    QCloudCOSXMLEndPoint* endpoint = [[QCloudCOSXMLEndPoint alloc] init];
    endpoint.regionName = kRegion;
    endpoint.useHTTPS = YES;
    configuration.endpoint = endpoint;
    [QCloudCOSXMLService registerDefaultCOSXMLWithConfiguration:configuration];
    [QCloudCOSTransferMangerService registerDefaultCOSTransferMangerWithConfiguration:configuration];
    }

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help