Help Center/ Object Storage Service/ SDK Reference/ iOS/ Object Upload/ Setting a Callback for a Resumable Upload

Updated on 2025-09-22 GMT+08:00

View PDF

Setting a Callback for a Resumable Upload

Function

You can specify the callback parameters in a resumable upload (uploadFile) request. After the object is successfully uploaded, OBS calls back the upload result to a specific server and returns the callback result to you.

Method

    
         - (OBSBFTask*)uploadFile:(OBSUploadFileRequest *)request
         completionHandler:(void (^)(OBSUploadFileResponse  * response, NSError * error))completionHandler;

Request Parameters

**Table 1** OBSUploadFileRequest
Parameter	Type	Mandatory (Yes/No)	Description
bucketName	NSString *	Yes	Definition: Bucket name. Restrictions: A bucket name must be unique across all accounts and regions. A bucket name: Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed. Cannot be formatted as an IP address. Cannot start or end with a hyphen (-) or period (.). Cannot contain two consecutive periods (..), for example, my..bucket. Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket. If you repeatedly create buckets with the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request. Default value: None
objectKey	NSString *	Yes	Definition: Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path of the object that does not contain the bucket name. For example, if the access path is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt. Value range: The value can contain 1 to 1,024 characters. Default value: None
uploadFilePath	NSString *	Yes	Definition: File to be uploaded. Default value: None
enableCheckpoint	BOOL	Yes	Definition: Whether to enable the resumable mode. Value range: YES: The resumable mode is enabled. NO: The resumable mode is disabled. Default value: NO
checkpointFilePath	NSString *	No	Definition: Path of a file generated for recording the progress of a resumable download. The file contains the information about parts and the progress. Restrictions: This parameter is valid only when the resumable mode is enabled.
partSize	NSNumber *	Yes	Definition: Part size. Value range: The value ranges from 100 KB to 5 GB, in bytes. Default value: 5MB
callBack	OBSCallBack *	No	Definition: Upload callback parameters. Value range: For details, see Table 2. Default value: None

**Table 2** OBSCallBack
Parameter	Type	Mandatory (Yes/No)	Description
callbackUrl	NSString *	Yes	Definition: After an object is uploaded successfully, OBS sends a callback request to the URL using the POST method. Restrictions: You can specify a maximum of 10 URLs. Use semicolons (;) to separate URLs. URL-encoding is required. For example, http://www.example.com/Chinese?key=Chinese name should be encoded into http://www.example.com/%E4%B8%AD%E6%96%87?key=%E4%B8%AD%E6%96%87%E5%90%8D.
callbackHost	NSString *	No	Definition: Value of the Host header in the callback request. Restrictions: If callbackHost is not specified, the value of host parsed from the callbackUrl parameter is used.
callbackBody	NSString *	Yes	Definition: Body of the callback request. Restrictions: The body format must comply with the media type specified in the callbackBodyType field. Default value: The callback body supports system variables and custom variables. Custom variables are those starting with x:. For example, in key=$(key)&hash=$(etag)&fileid=$(x:fileid), variables key and etag are system variables, and x:fileid is a custom variable. If the object to be uploaded is an image, you can use imageInfo.width and imageInfo.height in the parameter to indicate the width and height of the image. Example: key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)
callbackBodyType	NSString *	No	Definition: Value of the Content-Type header in the callback request. Value range: application/x-www-form-urlencoded application/json Default value: If this parameter is not set, the default value application/json is used.

Responses

**Table 3** OBSUploadFileResponse
Parameter	Type	Description
statusCode	NSString *	Definition: HTTP status code. Value range: A status code is a group of digits indicating the status of a response. It ranges from 2xx (indicating successes) to 4xx or 5xx (indicating errors). For more information, see Status Code. Default value: None
headers	NSDictionary *	Definition: Response header list, composed of tuples. Default value: None
etag	NSString *	Definition: ETag of an object, which is a Base64-encoded 128-bit MD5 digest. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, the object content is changed. The ETag reflects changes only to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag. Restrictions: If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object. Value range: The value must contain 32 characters. Default value: None
responseRawData	NSMutableData *	Definition: Raw data of the response body. Default value: None

Code Examples

This example sets a callback for a resumable upload (uploadFile) request.

void testPutObjectWithCallback(){
//    NSString *endPoint = @"your-endpoint";
    // Hard-coded or plaintext AK and SK are risky. For security purposes, encrypt your AK and SK before storing them in the configuration file or environment variables. In this example, the AK and SK are stored in environment variables. Before running the code in this example, configure environment variables AccessKeyID and SecretAccessKey.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    NSString* endPoint = @"https://obs.ap-southeast-1.myhuaweicloud.com";
    char* ak_env = getenv("AccessKeyID");
    char* sk_env = getenv("SecretAccessKey");
    char* securityToken_env = getenv("SecurityToken");
    NSString *AK = [NSString stringWithUTF8String:ak_env];
    NSString *SK = [NSString stringWithUTF8String:sk_env];
    NSString* securityToken = [NSString stringWithUTF8String:securityToken_env];
    NSString* exampleBucketName = @"example-bucket-name";
    NSString* exampleObjectKey = @"objectname.pic";
    NSString* exampleFile = [[NSBundle mainBundle]pathForResource:@"pic" ofType:@"jpeg"];//@"";
    NSString* exampleCallbackUrl = @"www.example-url.com";
    NSString* exampleCallbackBody = @"exampleCallbackBody";
    NSString* exampleCallbackHost = @"www.example-host.com";
    NSString* exampleCallbackBodyType = @"example-content-type";
    // Initialize identity authentication.
    OBSStaticCredentialProvider *credentialProvider = [[OBSStaticCredentialProvider alloc] initWithAccessKey:AK secretKey:SK];
    // (Optional) If you use a temporary AK/SK pair and a security token to access OBS, you must specify a security token.
    // credentialProvider.securityToken = securityToken;
    // Initialize service configuration.
    OBSServiceConfiguration *conf = [[OBSServiceConfiguration alloc] initWithURLString:endPoint credentialProvider:credentialProvider];
    // Initialize the client.
    OBSClient *client = [[OBSClient alloc] initWithConfiguration:conf];
    // Initialize the object upload request putObjectRequest.
    OBSUploadFileRequest* uploadFileRequest = [[OBSUploadFileRequest alloc] initWithBucketName:exampleBucketName objectKey:exampleObjectKey uploadFilePath:exampleFile];
    uploadFileRequest.partSize = [NSNumber numberWithInteger: 100 * 1024];
    uploadFileRequest.callback = [[OBSCallback alloc] initWithUrl:exampleCallbackUrl withBody:exampleCallbackBody withBodyType:exampleCallbackBodyType withHost:exampleCallbackHost];
    // Initialize the asynchronous upload task.
    OBSBFTask* uploadFileTask = [client uploadFile:uploadFileRequest completionHandler:^(OBSUploadFileResponse *response, NSError *error) {
        if(error){
            // Upload failed.
            NSLog(@"UploadFile failed:%@", error);
        }
        if(response){
            NSLog(@"UploadFile response:%@", response);
            NSString* callbackResponseString = [[NSString alloc] initWithData:response.responseRawData
                                                                     encoding:NSUTF8StringEncoding];
            NSLog(@"UploadFile callbackResponseString:%@", callbackResponseString);
        }
    }];
    // Wait until the asynchronous upload task is complete.
    [uploadFileTask waitUntilFinished];
}